mod_pcgi2 - PersistentCGI module for Apache.

Author: Oleg Broytmann <phd@phd.pp.ru>

It is called mod_pcgi2 because there was mod_pcgi written by AMK.

For copyright and licensing terms see files mod_pcgi2.c and COPYING.


INSTALLATION for Apache 1.3.
   Untar the archive to apache/src/modules.

   On some systems you need to edit libpcgi2.module and remove
-DHAVE_UNION_SEMUN before running configure. The symptom for this is when
you get an error like "storage size of `arg' isn't known".

   Add the following parameter to configure:
      --activate-module=src/modules/pcgi2/libpcgi2.a

   make && make install

   Compiling this module as DSO require some tweaking, but it is the
problem with Apache's configure, not the module (or at least it is my
understanding of Apache's configure :)

   John Morton <jwm@plain.co.nz> suggested the following:
   On system without the apache source code, but including some sort of
apache development package there's usually a tool called 'apxs' that can be
used to build the DSO module. Here's what he used on a Redhat 6.0 system:

/usr/sbin/apxs -Wc,-DMOD_PCGI2 -Wc,-DUNIX -Wc,-DHAVE_UNION_SEMUN -I./ \
   -o libpcgi2.so -c parseinfo.c pcgi-wrapper.c mod_pcgi2.c 


INSTALLATION for Apache 2.0.
   Untar the archive to httpd-$VERSION/modules.

   On some systems you need to edit Makefile.in and remove
-DHAVE_UNION_SEMUN before running configure. The symptom for this is when
you get an error like "storage size of `arg' isn't known".

   Patch Apache's configure using configure.patch.

   Add the following parameter to configure:
      --with-module=pcgi2:pcgi2/mod_pcgi2.c

   Change dir to modules/pcgi2, edit modules/pcgi2/modules.mk and remove
first two lines. Run make. Go back to top of the source tree and run make.

   All this wierd steps (blame Apache for their strangeness) are now
incorporated into build-apache script. Look at it, edit it to your taste,
run and watch the fun. You can pass additional parameters for configure:

   ./build-apache --prefix=/usr/local/apache2

   Then make install.

   Wes Kurdziolek <wkurdzio@cs.vt.edu> suggested the following:
   On system without the apache source code, but including some sort of
apache development package there's usually a tool called 'apxs' that can be
used to build the DSO module. Here's what he used on a Debian 3.0 system:

/usr/sbin/apxs  -i -a -n pcgi2 -DUNIX -DAPACHE2 -DMOD_PCGI2 \
   -c pcgi-wrapper.c parseinfo.c mod_pcgi2.c


CONFIGURATION

<IfModule mod_pcgi2.c>
PCGI_NAME Zope
PCGI_MODULE_PATH /usr/local/Zope/lib/python/Zope
PCGI_PUBLISHER /usr/local/Zope/pcgi/pcgi_publisher.py
PCGI_EXE /usr/local/bin/python
PCGI_SOCKET_FILE /usr/local/Zope/var/pcgi.soc
PCGI_PID_FILE /usr/local/Zope/var/pcgi.pid
PCGI_ERROR_LOG /usr/local/Zope/var/pcgi.log
PCGI_DISPLAY_ERRORS 1

<Location /pcgi>
SetHandler pcgi-handler
PCGI_ROOT /mysite
PCGI_SetEnv SiteRootPATH /
</Location>
</IfModule>

   Note - SiteRootPATH environment variable is only an example. If you
really want to use this variable to force Zope to do virtual hosting - you
may need to install SiteAccess and learn to use it.

   If you want to provide more than one <Location> sections for one
(virtual) server - sort them physically from shorter path to longer: first
goes <Location /> (if you set the module to handle root of the site), then
longer locations.


DIRECTIVES

PCGI_NAME Zope
   This sets PCGI module name; required.
   Alias: PCGI_SOFTWARE_NAME

PCGI_SOFTWARE_HOME /usr/local/Zope
   Root directory of your PCGI installation (where var directory exists)

PCGI_MODULE_PATH /usr/local/Zope/lib/python/Zope
   Full path to the module to publish; required

PCGI_PUBLISHER /usr/local/Zope/pcgi/pcgi_publisher.py
   Full path to the publisher; required

PCGI_EXE /usr/local/bin/python
   Full path to the python interpreter; required
   Alias: PCGI_SOFTWARE_EXE

PCGI_SOCKET_FILE /usr/local/Zope/var/pcgi.soc
   Full path to the PCGI (Unix) socket file; required;
if omitted, defaults to '%s/var/%s.soc' % (sw_home, sw_name)

PCGI_PID_FILE /usr/local/Zope/var/pcgi.pid
   Full path to the PCGI PID file; required;
if omitted, defaults to '%s/var/%s.pid' % (sw_home, sw_name)

PCGI_ERROR_LOG /usr/local/Zope/var/pcgi.log
   Full path to the PCGI errorlog file

PCGI_DISPLAY_ERRORS 1
   This controls how to show PCGI error;
   PCGI_DISPLAY_ERRORS 0 - show short message and include traceback in HTML
comment
   PCGI_DISPLAY_ERRORS 1 - show full message along with traceback

PCGI_PYTHONPATH /some/path:/another/path
   Set additional python search path (sys.path)

PCGI_INSERT_PATH /some/path:/another/path
   Additional path to search for publisher
   Alias: PCGI_WORKING_DIR

PCGI_ROOT /mysite
   Zope folder (or other object) that acts as the root for this location

PCGI_SetEnv SiteRootPATH /
   Set environment variable for this location


   Every directive is location specific - you can define global
configuration (for main server or virtual servers) and override some parts
with more specific directives. Example:

<IfModule mod_pcgi2.c>
PCGI_NAME Zope
PCGI_MODULE_PATH /usr/local/Zope/lib/python/Zope
PCGI_PUBLISHER /usr/local/Zope/pcgi/pcgi_publisher.py
PCGI_EXE /usr/local/bin/python
PCGI_SOCKET_FILE /usr/local/Zope/var/pcgi.soc
PCGI_PID_FILE /usr/local/Zope/var/pcgi.pid
PCGI_ERROR_LOG /usr/local/Zope/var/pcgi.log
PCGI_DISPLAY_ERRORS 0

<Location /pcgi>
SetHandler pcgi-handler
PCGI_ROOT /mysite
PCGI_SetEnv SiteRootPATH /
</Location>

<Location /pcgi/debug>
PCGI_DISPLAY_ERRORS 1
</Location>
</IfModule>


ADVICE: always use PCGI_ROOT in your config files.


CREDITS

   Many thanks to:

Jeff Bauer <jbauer@rubic.com>
A.M. Kuchling (http://www.amk.ca/)
John Morton <jwm@plain.co.nz>
Wes Kurdziolek <wkurdzio@cs.vt.edu>
Jan Mattila <jan.mattila@helsinki.fi>
Patrick Schoenenberg <patrick.schoenenberg@web.de>
