Using Zope with an existing web server
--------------------------------------

  While Zope comes with a web server, you may wish to use it with an
  existing web server. Use Persistent CGI (PCGI) to allow your existing
  web server to work with Zope on Unix and Windows.

  The installation process should create a 'Zope.cgi' PCGI file. Copy the
  'Zope.cgi' file to your web server's cgi-bin directory.
  
  On Unix you can also create a symbolic link to 'Zope.cgi' from your cgi-bin
  directory. For example::

    ln -s /home/amos/Zope/Zope.cgi /usr/local/apache/cgi-bin/Zope

  At this point you should perform any other steps you web server
  requires to install and configure a CGI script.

  Note: For more information on PCGI check out Jeff Bauer's PCGI pages:
 
  http://starship.skyport.net/crew/jbauer/persistcgi/

  When your Zope.cgi file is correctly configured as a CGI script with
  your web server, you are ready to access Zope through the web. You should
  point your browser at:

    'http://youmachine.example.com:8998/cgi-bin/Zope.cgi/manage'

  (Your URL maybe be different depending on how your web server is configured.)

  You should be prompted to enter a username and password. Enter the Zope
  "super manager" name and password.

Zope authentication with existing web servers.

  Zope normally performs both authentication and authorization of users.
  Some web servers don't pass authentication information to CGI scripts.
  If you keep getting rejected when you try to access Zope through the
  web with the "super manager" user name and password, there is a good chance
  that your web server is not passing authentication information to Zope.

  Tricking Apache to pass authentication headers

    If you are using Apache you will need to trick Apache into passing
    authentication headers to Zope. The easiest way to do this with 
    Apache 1.3 and above is to use mod_rewrite. Here is an example of
    configuration information which you would place in an Apache conf file::

      # Zope configuration maps /Zope/ to the Zope.cgi CGI script
      RewriteEngine on
      RewriteCond %{HTTP:Authorization}  ^(.*)
      RewriteRule ^/Zope/(.*) /usr/local/apache/cgi-bin/Zope.cgi/$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]

    Note that the RewriteRule should be one long line, and that the last
    character is the letter l, not the number 1.

  Allowing your server to handle authentication itself
 
    Sometimes you may prefer to handle authentication outside Zope, for
    example if your web server already does complex authorization, or
    if it seems too difficult to convince it to pass authentication
    information to Zope.

    As of 1.0.9, Zope began supporting a mode that allowed the web
    server to handle authentication.  The 'REMOTE_USER' environment
    variable is then matched to the identity of a user object in
    Zope.

    The following provide step-by-step instructions for setting this up in
    Apache, allowing both the Zope "super manager" defined in the Zope
    'access' file and users defined in Zope User Folders to be authenticated
    via the web server.

      Get Apache to authenticate /cgi-bin/Zope

        Add a directive in your Apache configuration file such as::

         <Location /cgi-bin/Zope/>
         AuthType Basic
         AuthName Zope-realm
         AuthUserFile /usr/local/etc/httpd/conf/ru_users
         require valid-user
         </Location>

        Then send Apache a '-1' signal to tell it to re-read its
        configuration files.  *Note*: the above presumes that
        '/cgi-bin/Zope' has been made executable by some other Apache
        directive in the configuration file.

      Ensure Apache Has 'superuser'

        Using Apache's tools for managing a user database, make 
        sure that the 'AuthUserFile' defined above has a valid user 
        called 'superuser'.

      Get Zope to use Apache's authentication

        Change Zope's access file to contain just the superuser
        id followed by a colon, as in::

          superuser:

        Note that this can be any value, including spaces.  The only
        restriction is that the value must match a user defined in
        Apache's user database.

        Shut down Zope by doing::

          kill `cat var/Main.pid`

        from the Zope directory.

      Configure Zope

        At this point you are able to log in using the "superuser"
        identity.  If you want other people defined in the Apache user
        database to have identities in Zope, you need to add them to
        a User Folder (the object whose ID is acl_users). Either click on
        the pre-defined acl_users in the top folder or add a User Folder
        object to a subfolder.

Specific web servers

  Apache
  
    * As mentioned above, Apache does not pass authorization information
    to CGI scripts by default. See above for information on how to deal
    with this situation.

  Netscape Servers

    * Like Apache, Netscape does not pass HTTP Authorization information to
    CGI scripts.  We have a plugin at our website that addresses this.
    http://www.digicool.com

    * Alternatively, you can allow the web server to perform the
    authentication step. See above for more information.
    
  IIS

    * You must turn off Windows NT Challenge/Response authentication.
    To do this, go to IIS Manager, right-click on the server, select
    Service Properties, and deselect *both* 'Windows NT
    Challenge/Response' and, strangely, Basic Authentication from the
    Password Authentication area of the Service tabbed worksheet.

    * IIS kindly throws out PATH_INFO when writing to its logs, so if
    you want to log which Zope objects are actually being
    accessed, you will need to investigate an ISAPI filter

