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.
- 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.
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
At an absolute minimum, you will probably want to specify the
'--with-install-dir' and '--with-httpd-user' options.
- path to perl executable to use
- Specify the name of the local contact
- Specify the local contact's email address
- Specify the local contact's phone number
- Specify a URL for the local contact
- Specify a URL for this site
- Specify a URL for a local copy of the cgiwrap docs
- Add the '-Wall' option for compilation with gcc, this is intended
primarily for development debugging.
- group to install cgiwrap as
- path to installation directory - this should be the path to your
server's cgi-bin directory
- path relative to home dir for cgi scripts
- 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.
- define what userid the web server is running as - this is required
- don't check to make sure cgiwrap is being run by server userid -
this is not recommended
- disable check for matching owner
- disable check for matching group
- disable check for setuid script
- disable check for setgid script
- disable check for group writable script
- disable check for world writable script
- disable check for symlinked script
- enable check for a valid user shell
- require that REDIRECT_URL be set in calling environment
- chroots script to PATH prior to script execution, requires
specific environment to be set up. See chroot docs
for more details.
set the minimum uid of user that can use cgiwrap, defaults to 100
set the minimum gid or aux gid of user that can use cgiwrap - not enabled by default
- enable logging script execution to syslog
- enable logging script execution to file
- prevent users from storing scripts in subdirs
- don't redirect stderr to stdout in scripts
- disable use of initgroups() to clear non-userid auxilliary groups
- disable use of setgroups() to add userid's auxilliary groups
- use a file to rewrite user directories
- set PATH environment variable to STRING
- set TZ environment variable to STRING
- limit cpu time with setrlimit
- limit total virtual memory with setrlimit
- limit total available memory with setrlimit
- limit writable file size with setrlimit
- limit data segment size with setrlimit
- limit stack segment size with setrlimit
- limit core file size with setrlimit
- limit resident set size with setrlimit
- limit number of processes with setrlimit
- limit number of open files with setrlimit
- limit lockable memory with setrlimit
- limit cgiwrap usage
- limit cgiwrap usage
- limit cgiwrap usage specific to each vhost, to restrict UnixTools.ORG, you would create the access file 'DIR/unixtools.org'.
- limit cgiwrap usage specific to each vhost
- allow specifying hosts in allow/deny files
- 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.
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.
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/ directory
(--with-cgi-dir=WWW cgiwrap configuration option), you may choose another method.
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:
- /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 value
- firstname.lastname@example.org 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 \
--email@example.com --with-php=/usr/local/bin/php \
# wait ...
# wait more until configure checks everything
3. run 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-cgiwrap
ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/nph-cgiwrapd
# ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/php-cgiwrap
# ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/php-cgiwrapd
Then you see you have cgiwrap in the /usr/local/apache/WWW/cgi-bin/
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:
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):
DocumentRoot /home/[... home directory/WWW here ...]/makler/WWW
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
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