You are not logged in Log in Join
You are here: Home » Zope Documentation » Misc » Webserver notes » View Document
Log in
Name

Password

 
Link icon Forgot your password?
Print

Webserver notes

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.

Roughly, PCGI is a protocol for translating CGI requests from a web server into Zope requests. CGI requests are traditionally one shot events; the web server handles a request for a CGI script by spawning a new process to handle the requests, returning the results of the request when the process dies.

Zope is a long running process, which means that it does not start up and die on each request like traditional CGI programs. If it did, each request would take far too long due to the time to start and stop an application server like Zope. Thus, PCGI is one of the options for gatewaying from the separate CGI processes to the Zope long running process.

Using Zope in multi-threaded mode with ZServer

ZServer is a general purpose TCP server for publishing Zope objects over various transport protocols. For Zope to run multi-threaded, you must run ZServer.

ZServer is based on Sam Rushing's Medusa software. The benefit of using Medusa as the ZServer core is that it is not protocol specific (Medusa provides libraries to program for any protocol) and it is easily extensible. Because Medusa is written in Python, is extremely high performance by design, and comes with an HTTP and FTP server, we chose it for the Zope core.

It is not necessary, however, for ZServer to actually listen for incoming HTTP requests. If you want Apache to do the actual listening and serving, then you can use ZServer's PCGI component to communicate with Apache.

To run ZServer with PCGI, you must specify the -p option to the z2.py startup script. From the top level Zope directory, you can: 

    bash% python1.5.2 z2.py -p

Note, you must have gone through the directions in INSTALL.txt for this to work.

This command will start ZServer up with PCGI (by default, it will also start up an HTTP and FTP server). For PCGI to work, the webserver and Zope must agree on a PCGI resource file. If this file is not named Zope.cgi and is not in the same directory as z2.py, then you can specify the file name after the -p, like: 

    bash% python.1.5.2 z2.py -p /path/to/PCGI/resource/file

Now the Zope long running process is started up, and the PCGI component is loaded and ready to receive CGI requests from your webserver.

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.

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.

Note: Apache requires some tricky configuration to get it to pass the HTTP authentication header information to Zope. See the section Zope authentication with existing web servers.

Using Zope in single-threaded mode with pcgi_publisher ------------------------------------------------------

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.

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.

Getting Apache to pass authentication headers

Before attempting to use your own Apache with Zope, it is highly recommended that you look at Zap. Zap is a preconfigured and precompiled version of Apache for Linux that drops right into Zope with no hassles. Even if you want to use your own Apache, or if you use it on a different platform than Linux, it is very helpful to have Zap's httpd.conf file to guide you through configuring Apache.

Zap can be found on the Zope website at:

http://www.zope.org/Download/Releases/Zap-1.1.0

If you are using Apache you will need to convince Apache to pass 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.

For Apache servers version 1.3b4 and above, there is an alternate way to get the server to pass through authorization headers, but you must have the ability to recompile your Apache server binary. If you pass the flag -DSECURITY_HOLE_PASS_AUTHORIZATION when compiling the server, the resulting Apache binary will allow authorization headers to pass through to CGI programs and you can avoid using the Rewrite rules described above.

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.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.
  • An Apache module to support PCGI (mod_pcgi) is under development.

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
  • An ISAPI module to support PCGI is under development.
  • IIS 4.0 throws away Zope's error messages by default. This behavior can create quite a few problems, including authentication problems.

Microsoft prides itself on the clear error messages that IIS 4.0 presents, when the user makes a mistake. These error messages are implemented in the form of Custom Error handlers, that return a file, or URL to a user when a certain error occurs.

This means, that when you forget to fill in an Id when you want to create, say, a new SQL Method, Zope's clear error message is replaced by IIS's totally irrelevant error message. Also, it completely breaks authentication when the user uses IE5.0 when trying to log into a secure area of the server. These Custom Error handlers are enabled by default.

Luckily, the handlers can quite easily be switched off:

Open the IIS website in the Management Console, and navigate to the folder you put the PCGI executable in. If you named your Zope installation Zope, it will be called Zope.exe. Double-click on that file. A property page will appear. Select the Custom Errors tab. Now, select every HTTP Error code in the listbox that doesn't have type Default, and click on the Set to Default button for each one. This will disable IIS overriding the error message returned by Zope.

Click OK, and voila, Zope is allowed to tell the world what it thinks went wrong.
Copyright (c) 2011 Zope Foundation. All rights reserved. Legal | Contact
If you can read this text, it means you are not experiencing the Plone design at its best. Plone makes heavy use of CSS, which means it is accessible to any internet browser, but the design needs a standards-compliant browser to look like we intended it. Just so you know ;)