Installing and Starting Zope

By the end of this chapter you should be able to install and start Zope. It's fairly easy to install Zope on most platforms, and it should typically take you no longer than ten minutes.

Downloading Zope

Zope Corporation makes "binaries" which are available on Zope.org for the Windows, Linux and Solaris operating systems. These binaries are "ready-to-run" releases of the Zope application server that do not require compilation.

There are typically two types of Zope releases: a "stable" release and a "development" release. The "stable" Zope release is always available as a binary distribution for supported platforms. The "development" Zope release may or may not be distributed as a binary for any given platform. If you are new to Zope, you almost certainly want to use the "stable" Zope release.

You may download Zope from the Zope.org web site. The most recent stable and development versions are always available from the Download area of the Zope.org website.

For platforms for which there is no binary release, you must download the Zope source and compile it. Zope may be compiled on almost any Unix-like operating system. Zope has reportedly been successfully compiled on Linux, FreeBSD, NetBSD, OpenBSD, Mac OS X, HPUX, IRIX, DEC OFS/1, and even Cygwin (the UNIX emulation platform for Windows). As a general rule of thumb, if Python is available for your operating system, and you have a C compiler and associated development utilities, then you can probably compile Zope. A notable exception is Mac OS 7/8/9. Zope does not run at all on these platforms.

Installing Zope

Zope requires different installation steps depending on your operating system platform. The sections below detail installing the binary version of Zope on Windows on Intel platforms, Solaris on SPARC platforms, and Linux on Intel platforms. We also detail a installation from source for platforms for which Zope Corporation does not provide a binary distribution.

Various binary Zope packages exist that are not distributed by Zope Corporation, but instead are distributed by third parties. Provided here is a list of URLs to these below for convenience's sake. These packages are not directly supported by Zope Corporation, although Zope Corporation encourages alternate binary distributions for unsupported platforms by third parties.

Zope installers for MacOSX

Zope RPM build for RedHat 6.X

FreeBSD Zope port

Debian Linux Zope package

 

Zope is also available from many Linux distributors as a "native" package. For example, RedHat often ships Zope on its "PowerTools" CD as an RPM. Check with your Linux operating system vendor to see if there are native Zope packages available for your platform.

Installing Zope for Windows With Binaries from Zope.org

The "Win32" version of Zope works under Windows 95, Windows 98, and Windows ME, Windows NT, Windows 2000, and Windows XP. Zope for Windows comes as a self-installing .exe file. To install Zope, first, download the Win32 executable installer from the Download area on Zope.org. It is typically named something like "Zope-2.X.X-win32-x86.exe" where the "X"s refer to the current Zope version number.

Important note: Do not try to use the file named "Zope-2.X.X-to-2.X.X-win32.x86.tgz" to install Zope for the first time. This is an upgrade package which upgrades an older version of Zope to a newer one instead of an installable Zope distribution.

Current stable Windows Zope Release

Figure 2-1 Current stable Windows Zope Release

 

Download the current stable release installer for Windows from Zope.org using your web browser. Place the file in a temporary directory on your hard disk or on your Desktop. Once the installer file has been downloaded, navigate to the folder in which you downloaded the file to, and double-click on the file's icon. The installer then begins to walk you through the installation process.

Beginning the installer

Figure 2-2 Beginning the installer

 

Click Next. You are asked to accept the Zope Public License before installing the product. After you read and accept the license, click Next again. Since you can install more than one Zope instance on any given machine, you are asked to pick a unique "site name" for your Zope instance. The default name is "WebSite". It's recommended that you change this value. "Zope" is a reasonable name, although you are of course free to pick any name you choose.

Click Next after choosing your site's name. You are then asked to choose a directory in which to install Zope. A reasonable choice for a destination directory is "c:\Program Files\Zope". After filling in the directory name, click Next. You will be prompted to create a new Zope user account. This is not an operating system account. It is a user account that is only meaningful to Zope. The account that you specify is called the initial user (or "superuser") and is used to log into Zope for the first time. It is also given Zope administrative privileges. You can change this user name and password later if you wish. A reasonable choice for the initial user name is "admin".

Selecting a Site Name

Figure 2-3 Selecting a Site Name

 

Selecting a Destination Directory

Figure 2-4 Selecting a Destination Directory

 

Provide an initial username and password

Figure 2-5 Provide an initial username and password

 

Click Next after choosing the initial user name and password. The installer presents a dialog indicating that it is ready to install files. Click Next again to begin installing the files.

Installing files

Figure 2-6 Installing files

 

Once the file copy is finished, if you are using Windows NT, Windows 2000, or Windows XP, you will see a dialog that indicates that you may choose to run Zope as a service. If you are just running Zope for personal use, don't bother running it as a service. If you are running Windows 95, Windows 98, or Windows ME, you cannot run Zope as a service (it is not offered as an option). It is recommended that if you are installing Zope for the first time that you don't choose to run the server manually.

Server Options

Figure 2-7 Server Options

 

After you click "Next", the installer informs you that the installation was successful. Click "Finish". If you decide to uninstall Zope later you can use the Unwise.exe program that resides in the directory in which you chose to install Zope.

Note that the Zope installer does not add a program folder entry to your "Start" menu. You will see how to start Zope in an upcoming section.

Installing Zope on Linux and Solaris With Binaries from Zope.org

The binary installations of Zope on Linux and Solaris are very similar. The binary distribution of Zope for Linux and Solaris comes as a .tgz file which must be uncompressed before you are able to begin the installation.

Important note: Do not try to use the file named "Zope-2.X.X-to-2.X.X-platform.tgz" to install Zope for the first time. This is an upgrade package which upgrades an older version of Zope to a newer one instead of an installable Zope distribution.

This paragraph has material that only applies to Solaris users. Before attempting to install Zope on Solaris for the first time, you need to install "GNUtar" and "gunzip". Both packages are available from the Solaris Package Archive. GNUtar is a "tape archive" program which, unlike the standard Solaris "tar" program is able to handle long file paths. Although Solaris comes with its own "tar" program, it is unable to handle unpacking Zope because it has a lame filepath-length limit that is exceeded by the length of some of the paths in the install package. "gunzip" is the GNU Lempel-Ziv encoding "unzip" program. Most, if not all, Linux versions come with GNUtar as the default "tar" program and already have gunzip installed, so if you run Linux, don't worry about this.

To begin a Zope installation, download the required installation archive from the Download area on Zope.org. It is typically named something like "Zope-2.X.X-solaris-sparc.tgz" (for Solaris) or "Zope-2.X.X-linux2-x86.tgz" (for Linux) where the "X"s refer to the current Zope version number.

After you download the installation archive for your platform, but before you install Zope, it is important that you decide where you'd like to install Zope and which user will be used to run it. It is suggested that Zope be unpacked and run as a "normal" user (any user except the root user). Though you may of course create a "dedicated" Zope user account, we're going to assume you want to install it in a subdirectory of your own personal "home" directory for the purpose of these instructions.

Download the most recent stable binary installation archive for your platform into your user's "home" directory. Below we show a user using "wget" for this purpose, but you may download it via any web browser:

        chrism@saints:~$ wget http://old.zope.org/Products/Zope/2.5.1/Zope-2.5.1-linux2-x86.tgz        --20:27:56--  http://old.zope.org:80/Products/Zope/2.5.1/Zope-2.5.1-linux2-x86.tgz                   => `Zope-2.5.1-linux2-x86.tgz.1'        Connecting to old.zope.org:80... connected!        HTTP request sent, awaiting response... 200 OK        Length: 5,979,458 [application/x-gzip]            0K -> .......... .......... .......... .......... .......... [  0%]           50K -> .......... .......... .......... .......... .......... [  1%]        (..and so on..)

 

Note that unlike most other UNIX programs, the Zope installer does not distinguish between a "build" directory and a "install" directory. The "build" directory is the "install" directory and vice versa. This means that the place where you unpack Zope and in which you run the installer should be the place where you want it to ultimately live. In our example case below, we're choosing to both unpack and install Zope into /home/chrism/Zope-2.5.1-linux2-x86.

"cd" to your home directory and, using gunzip and GNUtar, extract the files from the .tgz archive you downloaded in the last step:

        chrism@saints:~$ gunzip -c Zope-2.5.1-linux2-x86.tgz | tar xvf -        Zope-2.5.1-linux2-x86/        Zope-2.5.1-linux2-x86/Extensions/        Zope-2.5.1-linux2-x86/Extensions/README.txt        Zope-2.5.1-linux2-x86/LICENSE.txt        Zope-2.5.1-linux2-x86/README.txt        (.. and so on..)

 

This will unpack Zope into a new directory named "Zope-2.X.X-osname-platformname" where the X's represent the current Zope version numbers, "osname" represents your OS name, and "platformname" represents your hardware platform name. "cd" to this Zope directory and run the Zope installer script. The command and output are shown below:

        chrism@saints:~$ cd Zope-2.5.1-linux2-x86        chrism@saints:~/Zope-2.5.1-linux2-x86$ ./install        ------------------------------------------------------------------        Compiling python modules        ------------------------------------------------------------------        ------------------------------------------------------------------        creating default inituser file        Note:                The initial user name and password are 'admin'                and 'tnLQ6imA'.                You can change the name and password through the web                interface or using the 'zpasswd.py' script.        chmod 0600 /home/chrism/Zope-2.5.1-linux2-x86/inituser        chmod 0711 /home/chrism/Zope-2.5.1-linux2-x86/var        ------------------------------------------------------------------        setting dir permissions        ------------------------------------------------------------------        creating default database        chmod 0600 /home/chrism/Zope-2.5.1-linux2-x86/var/Data.fs        ------------------------------------------------------------------        Writing the pcgi resource file (ie cgi script), /home/chrism/Zope-2.5.1-linux2-x86/Zope.cgi        chmod 0755 /home/chrism/Zope-2.5.1-linux2-x86/Zope.cgi        ------------------------------------------------------------------        Creating start script, start        chmod 0711 /home/chrism/Zope-2.5.1-linux2-x86/start        ------------------------------------------------------------------        Creating stop script, stop         chmod 0711 /home/chrism/Zope-2.5.1-linux2-x86/stop        ------------------------------------------------------------------        Done!        chrism@saints:~/Zope-2.5.1-linux2-x86$ 

 

Note that the installer, among other things, will create an "initial" Zope user account with an autogenerated password. Write this username and password down temporarily. You will use this information to log in to Zope for the first time. You can change the initial user name and password later with the zpasswd.py script (see the chapter entitled Users and Security).

You have now successfully installed the Zope binary distribution. For more information on installing the binary distribution of Zope in alternate configurations on UNIX, see the installation instructions in the INSTALL.txt file inside the doc directory of the binary release package. You may additionally find out more about the installer script by running it with the -h (help) switch:

        $ ./install -h

 

Compiling and Installing Zope from Source Code

If binaries aren't available for your platform, chances are good that you will be able to compile Zope from its source code. To do this, however, you first must:

  • ensure you have a "C" compiler on your system (GNU gcc is preferred)
  • ensure you have a recent "make" on your system (GNU make is preferred)
  • install the Python language on your system from source.

 

Zope is written primarily in the Python language, and Zope requires Python to be able to run at all. Though binary versions of Zope ship with a recent Python, the source Zope distribution does not. Although we try to use the most recent Python for Zope, often the latest Python version is more recent than the version we "officially" support for Zope. For the most recent information on which version of Python you need to compile Zope with, see the release notes on the Web page for each version. Zope versions 2.5 and 2.6 require a Python 2.1 version equal to or greater than 2.1.3. Zope 2.3 and earlier versions require Python 1.5.2. No version of Zope is yet officially compatible with any version of Python 2.2.

You can obtain instructions for downloading, compiling and installing Python from source at the Python.org web site. Some Linux distributions ship with a preinstalled Python 2.1, but you need to be careful when attempting to use a vendor-installed Python to compile Zope. Some of these vendor-supplied Python distributions do not ship the necessary Python development files needed to compile Zope from source. Sometimes these development files are included in a separate "python-devel" package that you may install and use, but sometimes they are not. We recommend, to avoid headaches like this, that you compile and install Python from source if you wish to compile and install Zope from source.

After downloading, compiling, and installing Python from source, download the current Zope source distribution. See the Zope.org Downloads area for the latest Zope source release. Below we use "wget" for the purpose of downloading the source release, although you may of course use any browser or file retrieval utility:

         chrism@saints:~$ wget http://www.zope.org/Products/Zope/2.5.1/Zope-2.5.1-src.tgz         --20:49:34--  http://www.zope.org:80/Products/Zope/2.5.1/Zope-2.5.1-src.tgz               => `Zope-2.5.1-src.tgz'         Connecting to www.zope.org:80... connected!         HTTP request sent, awaiting response... 200 OK         Length: 2,165,141 [application/x-gzip]            0K -> .......... .......... .......... .......... .......... [  2%]           50K -> .......... .......... .......... .......... .......... [  4%]          100K -> .......... .......... .......... .......... .......... [  7%]         (..and so on..)

 

Then extract the resulting .tgz archive into the place where you want Zope to be installed. Zope has no "build" directory, the "install" directory is the build directory. In the below example, we extract the .tgz directly into our home directory. This is recommended for purposes of this example:

        chrism@saints:~$ gunzip -c Zope-2.5.1-src.tgz | tar xvf - 

 

After extracting the .tgz file, "cd" to the resulting directory and, using the Python binary you compiled beforehand, invoke the Python script which compiles Zope. This script is cryptically named "wo_pcgi.py". "wo_pcgi" stands for "without PCGI", an artifact of Zope's web server integration roots, the meaning of which is largely unimportant today.:

        chrism@saints:~$ cd Zope-2.5.1-src                                   chrism@saints:~/Zope-2.5.1-src$ python2.1 wo_pcgi.py        --------------------------------------------------------------------        Deleting '.pyc' and '.pyo' files recursively under /home/chrism/Zope-2.5.1-src...        Done.        --------------------------------------------------------------------        Compiling python modules        --------------------------------------------------------------------        Building extension modules        cp ./lib/python/Setup20 ./lib/python/Setup        ------------------------------------------------        Compiling extensions in lib/python        cp /home/chrism/lib/python2.1/config/Makefile.pre.in .        make -f Makefile.pre.in boot PYTHON=        rm -f *.o *~        rm -f *.a tags TAGS config.c Makefile.pre python sedscript        rm -f *.so *.sl so_locations        VERSION=` -c "import sys; print sys.version[:3]"`; \        (..and so on until...)        --------------------------------------------------------------------        creating default inituser file        Note:                The initial user name and password are 'admin'                and 'w!YzlsDT'.                You can change the name and password through the web                interface or using the 'zpasswd.py' script.        chmod 0600 /home/chrism/Zope-2.5.1-src/inituser        --------------------------------------------------------------------        Done!

 

You've now successfully installed Zope from source code. Note that the compile script, among other things, has created an "initial" Zope user account with an autogenerated password. Write this username and password down. You will use this information to log in to Zope for the first time. You can change the initial user name and password later with the zpasswd.py script (see the chapter entitled Users and Security). The initial user has "administrator" privileges within this Zope instance.

Starting Zope

Zope is managed via a web browser, and Zope contains its own web server (named "ZServer"). A successful Zope startup implies that its web server starts, allowing you to access the Zope management interface via your web browser. You can access Zope's management interface from the same machine on which Zope runs, or you can access it from a remote machine that is connected to the same network as your Zope server.

Zope's ZServer will "listen" for HTTP (web browser, or Hypertext Transfer Protocol) requests on TCP port 8080. If your Zope instance fails to start, make sure you don't have another application running which is already using TCP port 8080.

Zope also has the capability to listen on other TCP ports. Zope supports separate TCP ports for FTP (File Transfer Protocol), "monitor" (internal debugging), WebDAV (Web Distributed Authoring and Versioning), and ICP (Internet Cache Protocol) access. If you see messages which indicate that Zope is listening on ports other than the default 8080 HTTP, don't panic, it's likely normal.

Using Zope With An Existing Webserver

If you wish, you can configure your existing web server to serve Zope content. Zope interfaces with Microsoft IIS, Apache, and other popular webservers.

The Virtual Hosting Services chapter of this book provides rudimentary setup information for configuring Zope behind Apache. However, configuring Zope for use behind an existing webserver can be a complicated task, and there is more than one way to get it done. In the interest of completeness, here are some additional resources which should get you started:

  • Apache: see the excellent DevShed article entitled Using Zope With Apache_Side/Zope/ZopeWithApache .
  • IIS: see Connecting IIS to Zope on using IIS with Zope. Also of interest may be the WEBSERVER.txt file in your Zope installation's doc directory, and andym's Zope Behind IIS HowTo.

 

If you are just "getting started" with Zope, note that it is not necessary to configure Apache or IIS (or any other webserver) to serve your Zope pages, as Zope comes with its own webserver. You typically only need to configure your existing webserver if you want to use it to serve Zope pages in a production environment.

Starting Zope On Windows

If you installed Zope to "run manually" (as opposed to installing Zope as a "service"), use Windows Explorer to navigate to the directory into which you installed the Zope instance (typically c:\Program Files\Zope or 'c:\Program Files\WebSite'). Within this directory, find a file called start.bat. Double-click the start.bat icon. A console window will be opened. It will display process startup information.

If you chose to run Zope as a "service" on Windows NT/2000/XP, you can start Zope via the standard Windows "Services" control panel application. A Zope started as a service writes events to the standard Windows Event Log; you can keep track of when your service starts and stops by reviewing your system's Event Log. A Zope instance which has been installed as a "service" can also be run manually by invoking the start.bat file in the Zope installation directory as described above.

Starting Zope on UNIX

Important note: If you installed Zope from an RPM or a another "vendor distribution" instead of installing a Zope Corporation-distributed binary or source release, the instructions below may be not be applicable. Under these circumstances, please read the documentation supplied by the vendor to determine how to start your Zope instance instead of relying on the instructions below.

To start Zope, "cd" into to the directory in which you installed Zope and invoke the shell script named "start". Here is an example of this invocation and its typical output:

      chrism@saints:~$ cd Zope-2.5.1-linux2-x86      chrism@saints:~/Zope-2.5.1-linux2-x86$ ./start      ------      2002-06-28T03:17:02 INFO(0) ZODB Opening database for mounting: '142168464_1025234222.179125'      ------      2002-06-28T03:17:02 INFO(0) ZODB Mounted database '142168464_1025234222.179125' at /temp_folder      ------      2002-06-28T03:17:17 INFO(0) Zope New disk product detected, determining if we need to fix up any ZClasses.      ------      2002-06-28T03:17:17 INFO(0) ZServer HTTP server started at Thu Jun 27 23:17:17 2002              Hostname: saints              Port: 8080      ------      2002-06-28T03:17:17 INFO(0) ZServer FTP server started at Thu Jun 27 23:17:17 2002              Hostname: saints              Port: 8021      ------      2002-06-28T03:17:17 INFO(0) ZServer PCGI Server started at Thu Jun 27 23:17:17 2002              Unix socket: /home/chrism/Zope-2.5.1-linux2-x86/var/pcgi.soc

 

Starting Zope As The Root User

ZServer (Zope's server) supports setuid() on POSIX systems in order to be able to listen on low ports such as 21 (FTP) and 80 (HTTP) but drop root privileges when running; on most POSIX systems only the root user can do this. Versions of Zope prior to 2.6 had less robust versions of this support. Several problems were corrected for the 2.6 release.

The most important thing to remember about this support is that you don't have to start ZServer as root unless you want to listen for requests on "low" ports. In fact, if you don't have this need, you are much better off just starting ZServer as a user account dedicated to running Zope. nobody is not a good idea for this user account; see below.

If you do need to have ZServer listening on low ports, you will need to start z2.py as the root user, and also specify what user ZServer should setuid() to. Do this by specifying the -u option followed by a username or UID, either in the start script or on the z2.py command line. The default used to be nobody; however if any other daemon on a system that ran as nobody was compromised, this would have opened up your Zope object data to compromise.

You must also make sure the "var" directory is owned by root, and that it has the sticky bit set. This is done by the command 'chmod o+t var' on most systems. When the sticky bit is set on a directory, anyone can write files, but nobody can delete others' files in order to rewrite them. This is necessary to keep others from overwriting the PID file, tricking root into killing processes when stop is run.

Your Zope Installation

To use and manage Zope, you'll need a web browser. Zope's management interface is written entirely in HTML, therefore any browser that understands modern HTML allows you to manage a Zope installation. Mozilla, and any 3.0+ version of Microsoft Internet Explorer or Netscape Navigator will do. Other browsers that are known to work with Zope include Opera, Galeon, Konqueror, OmniWeb, Lynx, and W3M.

Start a web browser on the same machine on which you installed Zope and visit the URL http://localhost:8080/. If your Zope is properly installed and you're visiting the correct URL, you will be presented with the Zope "QuickStart" screen.

Zope QuickStart

Figure 2-8 Zope QuickStart

 

 

If you see this screen, congratulations! You've installed Zope successfully. If you don't, see the Troubleshooting section below.

Logging In

To do anything remotely interesting with Zope, you need to use its "management interface". Zope is completely web-manageable. To log into the Zope management interface, use your web browser to navigate to Zope's management URL. Assuming you have Zope installed on the same machine from which you are running your web browser, the Zope management URL will be http://localhost:8080/manage.

Successful contact with Zope using this URL will result in an authentication dialog. In this dialog enter the "initial" username and password you chose when you installed Zope. You will be presented with the Zope Management Interface (ZMI).

The Zope management interface.

Figure 2-9 The Zope management interface.

 

If you do not see an authentication dialog and the Zope Management interface, refer to the Troubleshooting section of this chapter.

Controlling the Zope Process With the Control Panel

When you are using the ZMI, you can use the Zope Control Panel to control the Zope process. Find and click the **Control_Panel** object in ZMI.

The Control Panel

Figure 2-17 The Control Panel

 

The Control Panel displays information about your Zope, such as the Zope version you're running, the Python version that Zope is using, the system platform, the "SOFTWARE_HOME" (your Zope directory), the "INSTANCE_HOME" (typically the same as your zope home), your "CLIENT_HOME" directory (the "var" directory of your Zope), Zope's process id, and how long Zope has been running for. Several buttons and links will also be shown.

If you are running Zope on UNIX or as a service on Windows, you will see a button in the Control Panel named Restart. If you click the Restart button, Zope will shut down and then immediately start up again. It may take Zope a few seconds to come back up and start handling requests. You needn't shut your web browser down and restart it to resume using Zope after pressing Restart, just wait for the Control Panel display to reappear.

To shut Zope down from the ZMI, click the Shutdown button. Shutting Zope down will cause the server to stop handling requests and exit. You will have to manually start Zope to resume using it. Shut Zope down only if you are finished using it and you have the ability to access the server on which Zope is running, so that you can manually restart it later. If you see a "strange" message appear in your web browser when you shut Zope down, don't panic. This is normal. A normal shutdown presents the user with a web page that states:

      An error was encountered while publishing this resource      exceptions.SystemExit      Zope has exited normally      ( .. more output ..)

 

Controlling the Zope Process From the Command Line

To stop a manually-run Zope on Windows press "Ctrl-C" while the console window under which Zope is running is selected. To stop a Zope on Windows that was run as a service, find the service with the name you assigned to your Zope installed in the Services Control Panel application and stop the service.

To stop Zope on UNIX, press "Ctrl-C" in the terminal window from which you started Zope or use the UNIX "kill" command against the lowest-numbered Zope process id. Zope processes under UNIX will be listed in "ps" output as "python z2.py [ options ]". This process id can also be found in the "var/Z2.pid" file inside of your Zope directory.

Troubleshooting

If your browser fails to connect with anything on TCP port 8080, your Zope may be running on a nonstandard TCP port (for example, some versions of Debian Linux ship with Zope's TCP port as 9673). To find out exactly which URL to use, look at the logging information Zope prints as it starts up. For example:

      ------      2000-08-07T23:00:53 INFO(0) ZServer Medusa (V1.18) started at Mon Aug  7 16:00:53 2000              Hostname: peanut              Port:9673      ------      2000-08-07T23:00:53 INFO(0) ZServer FTP server started at Mon Aug  7 16:00:53 2000              Authorizer:None              Hostname: peanut              Port: 8021      ------      2000-08-07T23:00:53 INFO(0) ZServer Monitor Server (V1.9) started on port 8099  

 

The first log entry indicates that Zope's web server is listening on port 9673. This means that the management URL is http://peanut:9673/manage.

Certain versions of Microsoft Internet Explorer 5.0.1 and 5.5 have issues with the Zope management interface which manifest themselves as an inability to properly log in. If you have troubles logging in with IE 5.0.1 or IE 5.5, try a different browser or upgrade to IE 6.

If you forget or lose the initial user name and password, shut Zope down and change the initial user password with the zpasswd.py script and restart Zope. See the chapter entitled Users and Security for more information about configuring the initial user account.

Options To The Zope start or start.bat Script

The Zope startup script named start (or start.bat on Windows) has many command-line switch options. They are the same for UNIX and Windows (although some only work on one or the other). These command-line switches are detailed below:

        -h          Output help text.        -z path          The location of the Zope installation.          The default is the location of the "z2.py" script.        -Z path          Unix only! This option is ignored on windows.          If this option is specified, a separate management process will          be created that restarts Zope after a shutdown (or crash).          The path must point to a pid file that the process will record its          process id in. The path may be relative, in which case it will be          relative to the Zope location.          To prevent use of a separate management process, provide an          empty string: -Z=''        -t n          The number of threads to use.  The default is 4.        -i n          Set the interpreter check interval. This integer value          determines how often the interpreter checks for periodic things          such as thread switches and signal handlers. The Zope default          is 500, but you may want to experiment with other values that          may increase performance in your particular environment.        -D          Run in Zope debug mode.  This causes the Zope process not to          detach from the controlling terminal, and is equivalent to          supplying the environment variable setting Z_DEBUG_MODE=1        -a ipaddress          The IP address to listen on.  If this is an empty string          (e.g. -a ''), then all addresses on the machine are used.        -d ipaddress          IP address of your DNS server. If this is an empty string          (e.g. -d ''), then IP addresses will not be logged. If you have          DNS service on your local machine then you can set this to          127.0.0.1.        -u username or uid number          The username to run Zope as.  You may want to run Zope as          a dedicated user.  This only works under Unix.  If Zope          is started as root, it is a required parameter.        -P [ipaddress:]number          Set the web, ftp and monitor port numbers simultaneously          as offsets from the number.  The web port number will be number+80.          The FTP port number will be number+21.  The monitor port number will          be number+99.          The number can be preceded by an ip address followed by a colon          to specify an address to listen on. This allows different servers          to listen on different addresses.          Multiple -P options can be provided to run multiple sets of servers.        -w port          The Web server (HTTP) port.  This defaults to 8080. If this          is a dash (e.g. -w -), then HTTP is disabled.          The number can be preceded by an ip address followed by a colon          to specify an address to listen on. This allows different servers          to listen on different addresses.          Multiple -w options can be provided to run multiple servers.        -W port          The "WebDAV source" port.  If this is a dash (e.g. -w -), then          "WebDAV source" is disabled.  The default is disabled.  Note that          this feature is a workaround for the lack of "source-link" support          in standard WebDAV clients.          The port can be preceded by an ip address followed by a colon          to specify an address to listen on. This allows different servers          to listen on different addresses.          Multiple -W options can be provided to run multiple servers.        -C        --force-http-connection-close          If present, this option causes Zope to close all HTTP connections,          regardless of the 'Connection:' header (or lack of one) sent by          the client.        -f port          The FTP port.  If this is a dash (e.g. -f -), then FTP          is disabled.  The standard port for FTP services is 21.  The          default is 8021.          The port can be preceded by an ip address followed by a colon          to specify an address to listen on. This allows different servers          to listen on different addresses.          Multiple -f options can be provided to run multiple servers.        -p path          Path to the PCGI resource file.  The default value is          var/pcgi.soc, relative to the Zope location.  If this is a dash          (-p -) or the file does not exist, then PCGI is disabled.        -F path_or_port          Either a port number (for inet sockets) or a path name (for unix          domain sockets) for the FastCGI Server.  If the flag and value are          not specified then the FastCGI Server is disabled.        -m port          The secure monitor server port. If this is a dash          (-m -), then the monitor server is disabled. The monitor server          allows interactive Python style access to a running ZServer. To          access the server see medusa/monitor_client.py or          medusa/monitor_client_win32.py. The monitor server password is the          same as the Zope emergency user password set in the 'access'          file. The default is to not start up a monitor server.          The port can be preceded by an ip address followed by a colon          to specify an address to listen on. This allows different servers          to listen on different addresses.          Multiple -m options can be provided to run multiple servers.        --icp port          The ICP port. ICP can be used to distribute load between back-end          zope servers, if you are using an ICP-aware front-end proxy such          as Squid.          The port can be preceded by an ip address followed by a colon          to specify an address to listen on. This allows different servers          to listen on different addresses.          Multiple --icp options can be provided to run multiple servers.        -l path          Path to the ZServer log file. If this is a relative path then the          log file will be written to the 'var' directory. The default is          'var/Z2.log'.         -r          Run ZServer is read-only mode. ZServer won't write anything to disk.          No log files, no pid files, nothing. This means that you can't do a          lot of stuff like use PCGI, and zdaemon. ZServer will log hits to          STDOUT and zLOG will log to STDERR.        -L          Enable locale (internationalization) support. The value passed for          this option should be the name of the locale to be used (see your          operating system documentation for locale information specific to          your system). If an empty string is passed for this option (-L ''),          Zope will set the locale to the user's default setting (typically          specified in the $LANG environment variable). If your Python          installation does not support the locale module, the requested          locale is not supported by your system or an empty string was          passed but no default locale can be found, an error will be raised          and Zope will not start.        -X          Disable servers. This might be used to effectively disable all          default server settings or previous server settings in the option          list before providing new settings. For example to provide just a          web server:            ./start -X -w80        -M file          Save detailed logging information to the given file.          This log includes separate entries for:            - The start of a request,            - The start of processing the request in an application thread,            - The start of response output, and            - The end of the request.

 

Environment Variables that Affect Zope at Runtime

Zope behavior is also effected by the presence and value of operating system environment variables that are available in the shell from which Zope is started.

To set an OS environment variable under UNIX in the bash shell, use the "export" command e.g. 'export EVENT_LOG_FILE=/home/chrism/Zope/var/event.log'. To set an OS environment variable under Windows NT/2000, use the Control Panel -> System applet or use the DOS-mode "set" command e.g. 'set EVENT_LOG_FILE=c:\chrism\Zope\var\event.log'. The "set" command can also be used in Windows 98/ME. Below are the environment variables that effect Zope runtime behavior, including descriptions of each:

      Zope library paths          PYTHONPATH              Effects the library load path used by Python.  See "The              Python Tutorial Modules              Chapter":http://www.python.org/doc/current/tut/node8.html              for more information about PYTHONPATH.          INSTANCE_HOME              If an INSTANCE_HOME is defined and has a 'lib/python' sub              directory, it will be added to the front of the PYTHONPATH.              INSTANCE_HOME is usually used to separate the Zope core              installation from application code and third-party              modules/products.              See also: SOFTWARE_HOME          SOFTWARE_HOME               The SOFTWARE_HOME usually keeps the directory name of the               Zope core installation.              See also: INSTANCE_HOME          ZOPE_HOME              ZOPE_HOME is the root of the Zope software, where the              ZServer package, z2.py, and the default import directory              may be found.      Profiling          PROFILE_PUBLISHER              If set, Zope is forced profile every request of the              ZPublisher.  The profiling information is written to the              value of the PROFILE_PUBLISHER.      Access Rules and Site Roots          SUPPRESS_ACCESSRULE              If set, all SiteRoot behaviors are suppressed.          SUPPRESS_SITEROOT              If set, all access rules behaviors are suppressed.      ZEO-related          CLIENT_HOME              CLIENT_HOME allows ZEO clients to easily keep distinct              pid and log files. This is currently an *experimental*              feature.          ZEO_CLIENT              If you want a persistent client cache which retains              cache contents across ClientStorage restarts, you need              to define the environment variable, ZEO_CLIENT, to a              unique name for the client.  This is needed so that              unique cache name files can be computed.  Otherwise, the              client cache is stored in temporary files which are              removed when the ClientStorage shuts down.      Debugging and Logging          EVENT_LOG_FORMAT or STUPID_LOG_FORMAT              Set this variable if you like to customize the output              format of Zope event logger.  EVENT_LOG_FORMAT is the              preferred envvar but STUPID_LOG_FORMAT also works.          EVENT_LOG_FILE="path" or STUPID_LOG_FILE="path"              The event file logger writes Zope logging information to a file.              It is not very smart about it - it just dumps it to a file and the              format is not very configurable - hence the name STUPID_LOG_FILE.              EVENT_LOG_FILE is the preferred envvar but STUPID_LOG_FILE              also works.              See also: LOGGING.txt in top-level Zope "doc" directory.           EVENT_LOG_SEVERITY <number> or STUPID_LOG_SEVERITY <number>              If set, Zope logs only messages whose severity is level is              higher than the specified one.  EVENT_LOG_SEVERITY is the              preferred envvar but STUPID_LOG_SEVERITY also works.          ZSYSLOG="/dev/log"              Setting this environment variable will cause Zope to try              and write the event log to the named UNIX domain socket              (usually '/dev/log').  This will only work on UNIX.              See also: LOGGING.txt          ZSYSLOG_FACILITY="facilityname"              Setting this environment variable will cause Zope to use              the syslog logger with the given facility. This              environment variable is optional and overrides the              default facility "user". This will only work on UNIX.              See also: LOGGING.txt in top-level Zope "doc" directory.           ZSYSLOG_SERVER="machine.name:port"              Setting this environment variable tells Zope to connect              a UDP socket to machine.name (which can be a name or IP              address) and 'port' which must be an integer.  The              default syslogd port is '514' but Zope does not pick a              sane default, you must specify a port.  This may change,              so check back here in future Zope releases.              See also: LOGGING.txt in top-level Zope "doc" directory.           ZSYSLOG_ACCESS="/dev/log"          ZSYSLOG_ACCESS_FACILITY="facilityname"          ZSYSLOG_ACCESS_SERVER="machine.name:port"              Like ZSYSLOG, ZSYSLOG_FACILITY, and ZSYSLOG_SERVER, but              controlling the sending of access information to syslog              (rather than controlling the sending of the event log)          Z_DEBUG_MODE      "yes" or "no"          BOBO_DEBUG_MODE   "yes" or "no"  (obsolete)              Run Zope in "debug mode" if set. Same as -D option              to 'z2.py' or 'start'.      Misc.          Z_REALM       "your realm"          BOBO_REALM    "your realm" (obsolete)              Realm to be used when send HTTP authentication requests              to a web client. The real string is displayed when the              web browser pops up the username/password requester      Security related           ZOPE_SECURITY_POLICY              If this variable is set to "PYTHON", Zope will use the              traditional Python based AccessControl              implementation. By default and for performance reasons              Zope will use the cAccessControl module.          ZSP_OWNEROUS_SKIP              If set, will cause the Zope Security Policy to skip              checks relating to ownership, for servers on which              ownership is not important.          ZSP_AUTHENTICATED_SKIP              If set, will cause the Zope Security Policy to skip              checks relating to authentication, for servers which              serve only anonymous content.          ZOPE_DTML_REQUEST_AUTOQUOTE              Set this variable to one of 'no', '0' or 'disabled' to              disable autoquoting of implicitly retrieved REQUEST data              that contain a '<' when used in a dtml-var              construction. When *not* set to one of these values, all              data implicitly taken from the REQUEST (as opposed to              addressing REQUEST.varname directly), that contain a              '<', will be HTML quoted when interpolated with a              <dtml-var> or &dtml-; construct.      ZODB related          ZOPE_DATABASE_QUOTA              If this variable is set, it should be set to an integer              number of bytes.  Additions to the database are not              allowed if the database size exceeds the quota.          ZOPE_READ_ONLY              If this variable is set, then the database is opened in              read only mode.  If this variable is set to a string              parsable by DateTime.DateTime, then the database is              opened read-only as of the time given.  Note that              changes made by another process after the database has              been opened are not visible.      Session related          ZSESSION_ADD_NOTIFY              An optional full Zope path name of a callable object to              be set as the "script to call on object addition" of the              session_data transient object container created in              temp_folder at startup.          ZSESSION_DEL_NOTIFY              An optional full Zope path name of a callable object to              be set as the "script to call on object deletion" of the              session_data transient object container created in              temp_folder at startup.          ZSESSION_TIMEOUT_MINS              The number of minutes to be used as the "data object              timeout" of the "/temp_folder/session_data" transient              object container.          ZSESSION_OBJECT_LIMIT              The number of items to use as a "maximum number of              subobjects" value of the "/temp_folder" session data              transient object container.      WebDAV          WEBDAV_SOURCE_PORT_CLIENTS               Setting this variable enables the retrieval of the              document source through the standard HTTP port instead              of the WebDAV port. The value of this variable is a              regular expression that is matched against the              user-agent string of the client.              Example::                  WEBDAV_SOURCE_PORT_CLIENTS="cadaver.*"   enables retrieval                  of the document source for the Cadaver WebDAV client                      Structured Text          STX_DEFAULT_LEVEL             Set this variable to change the default level for <Hx>             elements.  The default level is 3.      Esoteric           Z_MAX_STACK_SIZE              This variable allows you to customize the size of the              Zope stack used by the SecurityManager (default 100).

 

When All Else Fails

If there's a problem with your installation that you just can't seem to solve, don't despair. You have many places to turn for help, including the Zope maillists and the #zope IRC channel.

If you are new to open source software, please realize that, for the most part, participants in the various "free" Zope support forums are volunteers. Though they are typically friendly and helpful, they are not obligated to answer your questions. Therefore, it's in your own self-interest to exercise your best manners in these forums in order to get your problem resolved quickly.

The most reliable way to get installation help is to send a message to the general Zope maillist detailing your installation problem. Typically someone on the "zope@zope.org" list will be willing to help you solve the problem.

For even more immediate help, you may choose to visit the #zope channel on the OpenProjects IRC (Internet Relay Chat) network. See the OpenProjects website for more information on how to connect to the OpenProjects IRC network.

If you are truly desperate and under a time constraint that prohibits you from utilizing "free" support channels, Zope Corporation provides for-fee service contracts which you can use for Zope installation help.