
                    CGIWrap - Installation Instructions
     _________________________________________________________________

   There are two sets of installation instructions here. The basic ones I
   use, and a real-world example config contributed by Piotr Klaban
   below.

  Quick Installation

   Look at the notes to see if there are any hints for your platform.

   Issue "./configure --help" to find out the various configuration
          options. You will need to specify some of them. At the very
          least, you will want to specify "--with-httpd-user=USERID".

   Type "./configure <options>" with whatever options you need..

   Type "make"

   If you specified the installation directory in the options, you can
          type "make install" to do all the following steps.

   Copy cgiwrap executable to your servers cgi-bin directory

   Make cgiwrap owned by root, executable by all, and setuid. (Note: This
          step must be performed while logged in as "root")

          chown root cgiwrap
          chmod 4755 cgiwrap

   Hardlink or symlink nph-cgiwrap, nph-cgiwrapd, cgiwrapd to cgiwrap in
          the cgi-bin directory.

          ln [-s] cgiwrap cgiwrapd
          ln [-s] cgiwrap nph-cgiwrap
          ln [-s] cgiwrap nph-cgiwrapd

   You can, if you wish, install it with less permissive permissions.
          (Eg. 4750) But if you do this, make sure that the group of
          cgiwrap is the same as the group that the server runs as.

   *VERY IMPORTANT* - Do NOT allow any non-trusted user to run scripts
          directly out of the main cgi-bin directory, as this will allow
          them to use cgiwrap to run any of the other users scripts. The
          reason for this is that if they can run scripts as the same
          userid as the web server, they can subvert some of cgiwrap's
          security checks to allow them to run other users scripts. I
          recommend not running ANY scripts on the web server directly,
          once you have cgiwrap installed.

  Configuration Options

   The following are options available with the 'configure' command.
   Items in boldface are highly recommended. Defaults can be seen by
   issuing './configure --help' or by looking at the 'config.h' file
   after you have run 'configure'.

   At an absolute minimum, you will probably want to specify the
   '--with-install-dir' and '--with-httpd-user' options.

   --with-perl=PATH
          path to perl executable to use

   --with-local-contact-name=NAME
          Specify the name of the local contact

   --with-local-contact-email
          Specify the local contact's email address

   --with-local-contact-phone
          Specify the local contact's phone number

   --with-local-contact-url
          Specify a URL for the local contact

   --with-local-site-url
          Specify a URL for this site

   --with-local-doc-url
          Specify a URL for a local copy of the cgiwrap docs

   --with-wall
          Add the '-Wall' option for compilation with gcc, this is
          intended primarily for development debugging.

   --with-install-group=GROUP
          group to install cgiwrap as

   --with-install-dir=PATH
          path to installation directory - this should be the path to
          your server's cgi-bin directory

   --with-cgi-dir=PATH
          path relative to home dir for cgi scripts

   --with-multiuser-cgi-dir=PATH
          define a central cgi script directory that is searched if the
          script is not found in a user directory. This can be used to
          make a single script available that will run as any user,
          however, this can be very dangerous if you're not extremely
          careful designing your script. Do not enable this unless you
          know what you're doing. It is not needed for normal usage.

   --with-httpd-user=USER
          define what userid the web server is running as - this is
          required

   --without-check-httpd-user
          don't check to make sure cgiwrap is being run by server userid
          - this is not recommended

   --without-check-owner
          disable check for matching owner

   --without-check-group
          disable check for matching group

   --without-check-setuid
          disable check for setuid script

   --without-check-setgid
          disable check for setgid script

   --without-check-group-writable
          disable check for group writable script

   --without-check-world-writable
          disable check for world writable script

   --without-check-symlink
          disable check for symlinked script

   --with-check-shell
          enable check for a valid user shell

   --with-require-redirect-url
          require that REDIRECT_URL be set in calling environment

   --with-chroot=PATH
          chroots script to PATH prior to script execution, requires
          specific environment to be set up. See chroot docs for more
          details.

   --with-minimum-uid=UID set the minimum uid of user that can use
          cgiwrap, defaults to 100

   --with-minimum-gid=GID set the minimum gid or aux gid of user that can
          use cgiwrap - not enabled by default

   --with-logging-syslog=LABEL
          enable logging script execution to syslog

   --with-logging-file=FILE
          enable logging script execution to file

   --without-script-subdirs
          prevent users from storing scripts in subdirs

   --without-redirect-stderr
          don't redirect stderr to stdout in scripts

   --without-initgroups
          disable use of initgroups() to clear non-userid auxilliary
          groups

   --without-setgroups
          disable use of setgroups() to add userid's auxilliary groups

   --with-rewrite=FILE
          use a file to rewrite user directories

   --with-setenv-path=STRING
          set PATH environment variable to STRING

   --with-setenv-tz=STRING
          set TZ environment variable to STRING

   --with-rlimit-cpu=SECONDS
          limit cpu time with setrlimit

   --with-rlimit-vmem=BYTES
          limit total virtual memory with setrlimit

   --with-rlimit-as=BYTES
          limit total available memory with setrlimit

   --with-rlimit-fsize=BYTES
          limit writable file size with setrlimit

   --with-rlimit-data=BYTES
          limit data segment size with setrlimit

   --with-rlimit-stack=BYTES
          limit stack segment size with setrlimit

   --with-rlimit-core=BYTES
          limit core file size with setrlimit

   --with-rlimit-rss=BYTES
          limit resident set size with setrlimit

   --with-rlimit-nproc=COUNT
          limit number of processes with setrlimit

   --with-rlimit-nofile=COUNT
          limit number of open files with setrlimit

   --with-rlimit-memlock=BYTES
          limit lockable memory with setrlimit

   --with-allow-file=FILE
          limit cgiwrap usage

   --with-deny-file=FILE
          limit cgiwrap usage

   --with-vhost-allow-dir=DIR
          limit cgiwrap usage specific to each vhost, to restrict
          UnixTools.ORG, you would create the access file
          'DIR/unixtools.org'.

   --with-vhost-deny-dir=DIR
          limit cgiwrap usage specific to each vhost

   --with-host-checking
          allow specifying hosts in allow/deny files

   --with-afs=DIR
          enable afs setpag() support
     _________________________________________________________________

  Password Protected Installation

   The following are pecial additional instructions for installing a copy
   of cgiwrap that allows users to create access controlled scripts. For
   this to work, you will need to have a single common password file that
   will be used by all authenticated scripts.

   Re run configure, specify "public_html/auth-cgi-bin" instead of
          "public_html/cgi-bin" for the cgi directory.

   Type make.

   Create a new server cgi-bin directory called "auth-cgi-bin", and
          install this new copy of cgiwrap into that directory the same
          way you installed it into the cgi-bin directory. (4 copies, and
          set permissions). You will now be able to use the url:
          http://server/auth-cgi-bin/cgiwrap...

   To enable access control, place a .htaccess or equivalent file in the
          auth-cgi-bin directory where cgiwrap is located, that requires
          authentication to get at any file in that directory, but will
          allow any valid user to get through.

   Now, your users can simply check: 1. That their script was executed by
          them (eg. check the real uid of the script to make sure someone
          else wasn't running it by hand) 2. That the REMOTE_USER
          environment variable contains a user name that they want to
          allow to access the script.
     _________________________________________________________________

  Supplementary Configuration

   If you enabled the access file checking, you need to make sure and
   create the necessary files.

   If you enabled the user directory rewriting feature, you need to
   create the configuration file that you specified in the configure run.
     _________________________________________________________________

Here is the real-world example, for those who have problems
with cgiwrap installing.

Assumptions:

A. I use cgi-bin/ for global cgi scripts, you may choose /cgi-sys/ instead.
B. I have installed apache in /usr/local/apache/ directory, you may have
   it in different location (/etc/httpd/ etc.)
C. I use WWW as a user web directory ('UserDir WWW' Apache directive),
   you may choose public_html if you wish.
D. I allow users place .cgi and .php scripts everywhere under the WWW/ director
y
   (--with-cgi-dir=WWW cgiwrap configuration option), you may choose another me
thod.
E. I have system-wide html pages in /usr/local/apache/WWW/HTML
   ('DocumentRoot /usr/local/apache/WWW/HTML' apache directive)
   and system-wide cgi-bin/ directory in /usr/local/apache/WWW/cgi-bin/
   ('ScriptAlias' apache directive)

Make sure you have installed php, that you can run it from the command line,
and you see the '--enable-discard-path' configuration option in the output
of the following command:
  % php -i | grep configure
If not, then before/after installing cgiwrap, install php as a normal program
with the configuration option: --enable-discard-path

cgiwrap install procedure:

1. download and unpack cgiwrap archive

  % wget http://telia.dl.sourceforge.net/sourceforge/cgiwrap/cgiwrap-3.8.tar.gz
  % gtar zxvf cgiwrap-3.8.tar.gz
  % cd cgiwrap-3.8

2. configure it:

Replace:
- /usr/local/bin/php with /usr/bin/php or other location of your php program
- WWW (in --with-cgi-dir=WWW) with public_html i.e. your users web directory
- /usr/local/apache/WWW/cgi-bin with /home/httpd/cgi-sys if you use such a valu
e
  for ScriptAlias
- admin@man.torun.pl with YOUR contact address
- www (in --with-httpd-user=www) with apache if you run web server as 'apache'
user

./configure --with-check-shell --with-rlimit-core=0 --with-rlimit-cpu=60 \
--without-redirect-stderr --without-logging-file --with-perl=/usr/bin/perl \
--with-httpd-user=www --with-cgi-dir=WWW \
--with-install-dir=/usr/local/apache/WWW/cgi-bin --with-wall \
--with-local-contact-email=admin@man.torun.pl --with-php=/usr/local/bin/php \
--with-php-interpreter

  # wait ...
  # wait more until configure checks everything

3. run make

  %  make

That should output:

gcc -c -Wall -g -O2  -I. -I. debug.c
gcc -c -Wall -g -O2  -I. -I. util.c
util.c: In function `CheckUser':
util.c:370: warning: suggest parentheses around assignment used as truth value
util.c: In function `UserInFile':
util.c:1088: warning: subscript has type `char'
util.c:1096: warning: subscript has type `char'
gcc -c -Wall -g -O2  -I. -I. fetch.c
gcc -c -Wall -g -O2  -I. -I. stdutil.c
gcc -c -Wall -g -O2  -I. -I. msgs.c
gcc -o cgiwrap cgiwrap.o debug.o util.o fetch.o stdutil.o msgs.o

4. install with 'make install':

  % make install

That would be executed (make install -n):

rm -f /usr/local/apache/WWW/cgi-bin/cgiwrap
rm -f /usr/local/apache/WWW/cgi-bin/cgiwrapd
rm -f /usr/local/apache/WWW/cgi-bin/nph-cgiwrap
rm -f /usr/local/apache/WWW/cgi-bin/nph-cgiwrapd
# rm -f /usr/local/apache/WWW/cgi-bin/php-cgiwrap
# rm -f /usr/local/apache/WWW/cgi-bin/php-cgiwrapd
cp cgiwrap /usr/local/apache/WWW/cgi-bin/cgiwrap
chown root /usr/local/apache/WWW/cgi-bin/cgiwrap
chgrp root /usr/local/apache/WWW/cgi-bin/cgiwrap
chmod 4755 /usr/local/apache/WWW/cgi-bin/cgiwrap
ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/cgiwrapd
ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/nph-cgiw
rap
ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/nph-cgiw
rapd
# ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/php-cg
iwrap
# ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/php-cg
iwrapd

Then you see you have cgiwrap in the /usr/local/apache/WWW/cgi-bin/
directory.

5. Now configure Apache:

  % cd /usr/local/apache/conf     (on linux: % cd /etc/httpd/conf/)
  % vim httpd.conf                (or % pico httpd.conf)

5a) add these lines to global directives:

# change /usr/local/apache/WWW/cgi-bin/ to YOUR /cgi-bin/ real path
ScriptAlias /cgi-bin/ "/usr/local/apache/WWW/cgi-bin/"

AddHandler cgi-wrapper .php
AddHandler cgi-wrapper .cgi
Action cgi-wrapper /cgi-bin/cgiwrap

5b) do not run cgiwrap on .cgi scripts in the global /cgi-bin/ directory:


AllowOverride None
Options None
AddHandler cgi-script .cgi


5c) I have a phpMyAdmin installed in /user/local/apache/WWW/HTML/phpMyAdmin/,
and I want it to be run as a 'www' user from the /WWW/HTML/ directory


Action cgi-wrapper /cgi-bin/cgiwrap/www/HTML


5d) I have some Virtual Domains defined. Every user can have its own
    virtual domain. I want .cgi and .php scripts to be run as a specified user
    ('makler' in this situation):


ServerAdmin info@klaban.torun.pl
DocumentRoot /home/[... home directory/WWW here ...]/makler/WWW
ServerName www.klaban.torun.pl
ErrorLog logs/klaban_error_log
CustomLog logs/klaban_access_log combined
Action cgi-wrapper /cgi-bin/cgiwrap/makler

# [... other configuration stuff discarded ...]



6. Test your configuration before Apache reload (you may use /etc/init.d/httpd
   instead of ~www/bin/apachectl):

  % ~www/bin/apachectl configtest
Syntax OK

7. Reload apache web server:

  % ~www/bin/apachectl stop    # (or: ~www/bin/apachectl restart)
  % ~www/bin/apachectl start

8. Test if the simple php script is executed OK:

8a) create php script - your php scripts should be owned by the user, not root:

  % su makler
  % echo '\n"; ?> HTML too' > ~makler/WWW/test-php.php

8b) point your web browser to: http://www.klaban.torun.pl/test-php.php

  Now you should see:
php is OK
HTML too

--
Piotr Klaban
