zopectl (1.0.0b1)

zopectl is a python utility designed to simplify the management of one or more zope instances. It is a configurable front end to z2.

zopectl [-n] [-f path] {start|stop|reload|restart|status} [sitelist]

-n

Do not execute the command, just display what would be done, including the values of any environment variables that would be set. In theory you could cut and paste the output into a bourn-shell type shell and it would have the same effect as running zopectl without the -n.

-f path

Specify the path to an alternate configuration file.

If -f is not specified, zopectl looks for the following files:

                /usr/local/etc/zopectl.conf

                /usr/local/zope/zopectl.conf

start

Bring up the zope site(s) (call z2), as controlled by the parameters set in the conf file(s).

stop

Shut down the zope site(s). Uses kill, like the distributed stop script.

restart

stop, wait for one second, and start.

reload

same as restart (for compatability with other xxxctl scripts)

status

not currently implemented.

sitelist

zero or more site names or sitelist names (see Configuration File, below). If no sitelist is given, the default sitelist, if any, is used. If there is no sitelist_default, and no siteconf parameter, then it is assumed that the configuration file deals with only one, default site, and that site is manipulated.

Configuration File

The configuration file conists of a series of lines of the form:

    parameter = value

A parameter consists of letters, numbers, and underscores and is case sensitive.

A value may contain any text. Leading and trailing whitespace is stripped. Substitution points may be specified using the syntax:

    %(parametername)

Substitution is done late, so parameter values may refer to each other in any order. (Bug: a circular reference will cause zopectl to crash.) Substitution parameter names may refer to environment variables. Boolean parameters may be set to true using any of: on, true,t, or 1, in any case. They may be set to false using any of: off, false, f, or 0.

The master (and possibly only) configuration file can be specified with the -f option, or will default to the paths shown above. The SITECONF parameter (see Parameters, below) causes zopectl to look for a sub-configuration file for each site. The definitions from the subfile will override the definitions in the master file, but can refer to parameters which it does not override. Environment variables not overridden by the either file may also be referenced.

Alternatively, if the SITECONF parameter is not set, zopectl will look for parameter overrides by prefixing the parameter name with the site name in upper case followed by an underscore. Thus a parameter named INSTANCE_HOME can, in the absence of a SITECONF, be overridden for site mysite inside the master configuration file by setting the parameter MYSITE_INSTANCE_HOME.

Parameters

SITECONF

Provides the full path name to the sub-configuration file containing overrides for the specific site.

Examples:

%(PYTHONPATH)/%(SITE).conf

%(INSTANCE_HOME)/zopectl.conf

If not specified, overrides are looked for in the master configuration file by prefixing the parameter name by the site name in upper case followed by an _.

PYTHONBIN

Name or full path of the python binary to be used to run Z2. Defaults to python.

PYTHONHOME

Path to the Zope executable tree (the directory containing z2.py). Required.

INSTANCE_HOME

Path to the directory containing the site specific files (var, import, Extensions, Products directories). If not specified, these directories are expected to be in PYTHONHOME (Products being in PYTHONHOME/lib/python/Products). Think of it as INSTANCE_HOME defaulting to PYTHONHOME, though that is not 100% accurate.

PRODUCTS_PATH

Path Zope should look for Products under. This path may inclide substitution variables named PRODUCTS_PATH, SOFTWARE_PRODUCTS, and INSTANCE_PRODUCTS, which are evaluated AT RUNTIME. That is, the substitutions are made by Zope and not by zopectl. The first is the complete products path determined by zope, the second the Products directory found in SOFTWARE_HOME, and the third the Products directory found in INSTANCE_HOME. So, for example, to add the directory /usr/local/zope/Products to the end of the default computed products path, under unix you would set this variable to

%%(PRODUCTS_PATH)s:/usr/local/zope/Products

Note the doubled %, this escapes the % so that zopectl doesn't try to do the substitution, leaving it for Zope to do at runtime.

XXX: This example appears to not work. However, you can still use the zopectl substitution to get the same effect. PRODUCTS_HOME without using the zope built in % substitution seems to work.

LOG_FILE

Path to the Z2.log file. Defaults to %(INSTANCEHOME)/var/z2.log.

STUPID_LOG_FILE

Path to the "stupid log file" log file. This log file logs information generated by various zope Zope internal processes (the zLOG facility). If not specified the information is not logged.

DETAIL_LOG_FILE

Path to the detail log flie. This will record extra information about Zope transactions, such as the start of the request, processing start, start of response, and end of request. If not specified this information is not logged.

IP_ADDRESS

The IP address on which the servers should listen. If not specified, Zope will listen on all addresses.

BASE_PORT

The starting offset for the standard port selection. The default web server will listen on BASE_PORT+80, the default FTP server on BASE_PORT+21, and the default monitor on BASE_PORT+99. A BASE_PORT of 0 causes Zope to listen on the well-known ports for the web and FTP services. On Unix, root privileges are required to use these ports. If you use both BASE_PORT and service_PORT for ftp, web, or monitor service, post 2.2.x Zope will attempt to bind the port twice, and fail. See Known Bugs. So use only one or the other.

SERVICE_LIST

The list of servers to run. Choices are: web, ftp, monitor, pcgi, fastcgi, and webdav. These may be specified in any case. Note that if any of web, ftp, or montior is omitted, the corresponding z2 parameter will be specified with a null argument so as to disable that server.

xxx_PORT

xxx can be one of WEB, FTP, MONITOR, PCGI, or FASTCGI, and specifies the absolute port number (or file system path, for pcgi and fastcgi) on which the corresponding service should listen. This overrides the default established by BASE_PORT in pre 2.2.x zope, but conflicts with BASE_PORT in post 2.2.x zope (see BASE_PORT above). For web, ftp, monitor, and (I believe) fastcgi, this can be in the form ipaddress:port, in which case the specific service indicated runs on the specific IP address indicated.

PCGI_PATH

Synonym for PCGI_PORT.

FASTCGI_PATH

Synonym for FASTCGI_PORT.

DEBUG

Boolean flag. If true, z2 is run in debug mode. Normally this means it does not detach from the terminal and logging output (see stupid_log_file above) appears there, but zopectl always runs zope in the background, so using this with zopectl is limited to the other effects of of the -D z2 flag, such as showing tracebacks on error pages. (Note: I haven't tested this, and it may not work.) This is off by default.

WATCHDOG

Boolean flag. Only available on Unix; this causes a second process to be started to monitor the main Zope process and restart it if it dies. This is on by default. (It is ignored under Windows).

READONLY

Boolean flag. Starts ZServer in readonly mode, where it will not write to disk.

THREADS

The number of threads to run. Defaults to 4.

INTERPRETER_CHECK_INTERVAL

"...determines how often the interpreter checks for periodic things such as thread switches and signal handlers. The Zope default is 120, but you may want to experiement with other values that may increase performance in your particular environment."

DNS_SERVER

IP addresss of a DNS server which ZServer will use to resolve IP addresses into names in the log files. If not specified, IP addresses are logged without lookup. This is the default.

RUN_USER

The user Zope should run as (after startup) if started initially as root. Defaults to nobody.

LOCALE

Turns on locale support. If a blank value is specified the operating system default is used.

SITELIST_default

A list of site names that will be manipulated if no sites are specified on the command line.

SITELIST_xxx

for any string xxx, if xxx is specified on the command line as a site, the list of sites specified for this parameter will be substituted.

ENV_VARS

A list of parameter names. The substituted values of these variables will be set in the environment before z2 is called during a START operation.

Installation

zopectl consists of a python script that uses three external modules. I suggest you copy the zopectl script to some appropriate location such as /usr/local/sbin, and the three modules (argparse.py, ParmFile.py, and xfile.py) to the site-packages subdirectory of your python library directory. Alternatively, it should be possible to concatenate the files with zopectl at the end, delete the import statements for the above modules, and end up with a working program in one file. I haven't tried this.

Included with the distrabution are fairly complete unit tests for xfile and ParmFile, and the start of a unit test framework for zopectl itself. You need PyUnit to run them. I have only thoroughly tested those parts of zopectl that I use myself, so bugs probably remain. The zopectl.conf.sample file shows the configuration I use, and thus the one that's been tested.

I welcome bug reports, patches, and especially unit tests demonstrating bugs. My contact address is [email protected].

Known Bugs

SERVICE_LIST allows the creation of only one server per service type. This should be augmented with a different mechanism allowing multiple servers to be specified, since z2 now supports that.

Specifying a PYTHONBIN different from the one that is used to run zopectl probably doesn't actually work. Yeah, I know, this is a serious bug, and it is the main reason this is a Beta release. I need to switch to using SOFT_HOME when possible.

Non-Copyright

Writen by R. David Murray ([email protected]).

This text is placed in the public domain.

$Id: zopectl.stx,v 1.9 2002/01/21 04:07:51 rdmurray Exp $