1 Overview
The purpose of this document is to show how to configure CGIWrap to allow
users on shared hosting to run CGI and PHP scripts using their own user identity
and permissions. The code in this HOWTO is used to provide CGI and PHP capability for over 8,000
users of a Red Hat Enterprise Linux host. In this HOWTO you will learn how to install CGIWrap
so that users will be able to run CGI and PHP scripts in a directory named public_html.
2 What is CGIWrap?
CGIWrap is a gateway program that allows general users to use CGI scripts and HTML forms without compromising the security of the http server. Scripts are run with the permissions of the user who owns the script. In addition, several security checks are performed on the script, which will not be executed if any checks fail.
CGIWrap is used via a URL in an HTML document. As distributed, cgiwrap is configured to run user scripts which are located in the
~/public_html/cgi-bin/directory.
3 Get the CGIWrap Source Code
CGIWrap Source: http://sourceforge.net/projects/cgiwrap/
4 Configuring CGIWrap
CGIWrap will be reconfigured to allow URLs to mirror a script's path on the file system. Because cgiwrap needs a special configuration to process PHP scripts, it's necessary to create a CGIWrap binary for CGI scripts and a binary specifically configured for PHP scripts.
4.1 Debugging with CGIWrap
Each CGIWrap binary can serve in a debugging role when called as cgiwrapd or phpwrapd.
4.2 The Binaries
The CGIWrap binary files installed on the server will be:
/var/cgi-bin/cgiwrap/var/cgi-bin/cgiwrapd/var/cgi-bin/phpwrap/var/cgi-bin/phpwrapd
When installing multiple versions of CGIWrap, care must be taken not to
use the make install command. In this tutorial we will install the binaries
manually as the root user. The permissions on the cgiwrap and phpwrap binaries must be set by the root user to 4755.
5 Apache Configuration
The Apache web server must redirect requests for CGI and PHP scripts to the CGIWrap binaries,
where they will be executed using the identity and permissions of the local user. This redirection
is accomplished using an Apache rewrite rule that detects the .cgi and .php extensions
and rewrite the URLs for the appropriate version of CGIWrap.
This example shows a typical rewriting of CGI and PHP URLs so that they will
be handled by cgiwrap and phpwrap respectively.
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^/~(.*)/(.*)\.php$ /cgi-bin/phpwrap/$1/$2.php [PT]
RewriteRule ^/~(.*)/(.*)\.cgi$ /cgi-bin/cgiwrap/$1/$2.cgi [PT]
RewriteRule ^/~(.*)/(.*)\.pl$ /cgi-bin/cgiwrap/$1/$2.pl [PT]
RewriteRule ^/~(.*)/(.*)\.py$ /cgi-bin/cgiwrap/$1/$2.py [PT]
</IfModule>
6 PHP Configuration
In order to work with CGIWrap, PHP must be used with the FORCE_REDIRECT option turned off. Prior to PHP 5.3.0 we had to compile PHP with the --enable-discard-path and --enable-force-cgi-redirect
options. In newer versions of PHP, this is no longer necessary. However, we do have
to edit the PHP configuration file php.ini to set cgi.force_redirect = off.
Add these lines to php.ini.
cgi.force_redirect = 0
7 Compile and Configuration Options for CGIWrap
To get started, download the CGIWrap source to the /opt/cgiwrap directory. You will need to have
two copies of the source code, one in cgiwrap-4.1 and one in cgiwrap-4.1-php.
7.1 CGWRap for PHP Scripts
The PHP version of cgiwrap requires several configuration options that make it necessary to
create a custom cgiwrap binary for PHP only. PHP scripts to not need a shebang line.
The easiest way to deal with these options is to save them into a file. For example, the
configuration script below is named php-configuration.sh.
This example comes from a RHEL server with php-cgi located at /usr/local/bin/php. You
would change this option depending on where you've installed php-cgi.
# File: php-configuration.sh # Desc: Run this script as follows as root or using sudo # # sh ./php-configuration.sh # # Install the files manually. DO NOT RUN make install # As root, set permissions to setuid: 4755 ./configure --prefix=/opt/cgiwrap \ --without-nph \ --with-install-dir=/var/www/cgi-bin \ --with-perl=/usr/local/bin/perl \ --with-php=/usr/local/bin/php \ --with-httpd-user=apache \ --with-php-cgiwrapd \ --with-php-interpreter \ --with-php-cgiwrap \ --with-cgi-dir=public_html \ --with-logging-file=/var/www/logs/phpwrap.log \ --with-deny-file=/opt/cgiwrap/phpwrap.deny \ --without-check-group \ --with-check-shell
- Untar the
cgiwrap-4.1.tar.gzfile and rename thecgiwrap-4.1directory tocgiwrap-4.1-php.mv cgiwrap-4.1 cgiwrap-4.1-php
- Enter the
cgiwrap-4.1-phpdirectory.cd cgiwrap-4.1-php
- Run
./configure; makeusing the configuration options for PHP scripts shown in the example above. If you've created a configuration file containing the options you want to use, run that script.makewill create thecgiwrapbinary that you will copy in the next step. NOTE Do not runmake install. The default installation script will delete allcgiwrapfiles in the/var/cgi-bin/. - Run
maketo create the custom PHP version ofcgiwrap. - Copy the new
cgiwrapbinary to/var/www/cgi-bin/phpwrap.sudo cp cgiwrap /var/www/cgi-bin/phpwrap
- Create the debugging version named
phpwrapd. Copycgiwrapto/var/www/cgi-bin/phpwrapd.sudo cp cgiwrap /var/www/cgi-bin/phpwrapd
- Set the permissions correctly as the root user:
chmod 4755 /var/www/cgi-bin/phpwrap chmod 4755 /var/www/cgi-bin/phpwrapd
8 CGIWrap for CGI Scipts
This version of cgiwrap will handle regular CGI scripts that use Perl, Python, Ruby, or
another language. These scripts must have a valid shebang line, such as
#!/usr/local/bin/perl print "Content-type: text/html\n\n"; print "Hello, world!";
8.1 A configuration script for CGI scripts
# File: cgi-configuration.sh # Desc: Run this script as follows as root or using sudo # # sh ./cgi-configuration.sh # # Install the files manually. DO NOT RUN make install # As root, set permissions to setuid: 4755 ./configure --prefix=/opt/cgiwrap \ --without-nph \ --with-cgi-dir=public_html \ --with-perl=/usr/local/bin/perl \ --with-install-dir=/var/www/cgi-bin \ --with-httpd-user=apache \ --with-logging-file=/var/www/logs/cgiwrap.log \ --with-deny-file=/opt/cgiwrap/cgiwrap.deny \ --without-check-group \ --with-check-shell
8.2 Compiling cgiwrap for CGI Scripts
- Untar the CGIWrap source code to create
cgiwrap-4.1. - Enter the
cgiwrap-4.1directory. - Run
./configure; makeusing the configuration options for regular CGI scripts. If you've created a configuration file, run that script (see above). NOTE Do not runmake install— The default installation script will delete allcgiwrapfiles in the/var/cgi-bin/. - Copy the
cgiwrapbinary to/var/www/cgi-bin/cgiwrap.cp cgiwrap /var/www/cgi-bin/cgiwrap
- Create the debugging version name
cgiwrapd. Copycgiwrapto/var/www/cgi-bin/cgiwrapd.cp cgiwrap /var/www/cgi-bin/cgiwrapd
- Set the permissions correctly as the root user:
chmod 4755 /var/www/cgi-bin/cgiwrap chmod 4755 /var/www/cgi-bin/cgiwrapd
And you're done.
If you find any errors, please let me know in the comments.
