Configuring CGIWrap for large shared hosting systems

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.

CGIWrap Documentation

3 Get the CGIWrap Source Code

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/$ [PT]
    RewriteRule ^/~(.*)/(.*)\.py$ /cgi-bin/cgiwrap/$1/$ [PT]

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

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:
# Desc: Run this script as follows as root or using sudo
#       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 \
  • Untar the cgiwrap-4.1.tar.gz file and rename the cgiwrap-4.1 directory to cgiwrap-4.1-php.
    mv cgiwrap-4.1 cgiwrap-4.1-php
  • Enter the cgiwrap-4.1-php directory.
    cd cgiwrap-4.1-php
  • Run ./configure; make using 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. make will create the cgiwrap binary that you will copy in the next step. NOTE Do not run make install. The default installation script will delete all cgiwrap files in the /var/cgi-bin/.
  • Run make to create the custom PHP version of cgiwrap.
  • Copy the new cgiwrap binary to /var/www/cgi-bin/phpwrap.
    sudo cp cgiwrap /var/www/cgi-bin/phpwrap
  • Create the debugging version named phpwrapd. Copy cgiwrap to /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

print "Content-type: text/html\n\n";
print "Hello, world!";

8.1 A configuration script for CGI scripts

# File:
# Desc: Run this script as follows as root or using sudo
#       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 \

8.2 Compiling cgiwrap for CGI Scripts

  • Untar the CGIWrap source code to create cgiwrap-4.1.
  • Enter the cgiwrap-4.1 directory.
  • Run ./configure; make using the configuration options for regular CGI scripts. If you've created a configuration file, run that script (see above). NOTE Do not run make install — The default installation script will delete all cgiwrap files in the /var/cgi-bin/.
  • Copy the cgiwrap binary to /var/www/cgi-bin/cgiwrap.
    cp cgiwrap /var/www/cgi-bin/cgiwrap
  • Create the debugging version name cgiwrapd. Copy cgiwrap to /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.

Reprint: My Collection of Vintage Smalltalk Books

This is a reprint of a 2010 item that got lost when I moved from WordPress to SquareSpace. I see in the logs that some really astute folks came looking for some Smalltalk news but got the 403 Missing Page instead. Sorry about that. Let's hope that Google sends its little robot around to re-index this real soon. :)

Every time I’m swept up in an new project I gird my loins by gathering a phalanx of books around me. I start by downloading all of the free PDF’s I can find. Stephane Ducasse, author the entertaining Squeak Robots book, has an exhaustive list of free out-of-print Smalltalk books. So I got them all. I don’t know how many of these books I’ll ever read, but I feel good having them there, just in case.

I like real books, so I scoured the used book list on Amazon and was able to find paper copies of many of my free PDF’s.

Most of these books were first published in the 80's and 90's, with a few of the Squeak books arriving after 2000.

Most of these books were first published in the 80's and 90's, with a few of the Squeak books arriving after 2000.

Of all of these books, my favorite is SMALLTALK-80 by Adele Goldberg and David Robson (1989). Though the book’s cover gives it a quaintly old-fashioned look, the content is contemporary and the writing admirably clear — perfect for a student like me.

I like this book so much that I carry it with me on my walks around San Francisco and read it while I sit in Starbucks eating pastries and drinking espressos. Now and then some generic dude will see my antique book and comment, “Damn. Is that language still around? Why would you want to learn that when you could learn Java?” 

I also have a soft spot in my heart for Squeak: Learn Programming with Robots by Stephane Ducasse, which I’ve mentioned previously. This book is good-spirited and all about having fun with programming. It’s an absolutely painless, fun introduction to Smalltalk. A kid can handle this book easily—even an adult kid.

My buddy Bill G. observed me collecting these dusty, out of print tomes. Back in the 80’s he did some Smalltalk programming in The Valley. He said, “There used to be an all-Smalltalk books store in Palo Alto on University Avenue, right down the road from Xerox. That’s how hot Smalltalk was in those days.” He paused. “I think that place is a Starbucks now.”

That’s cool with me. I need a clean, well-lighted place to hang out and read my books and get hassled by Java programmers.

Happy hacking…


A Linux Workstation for Eric S Raymond

One of my favorite tech-talk Youtube channels is TekSyndicate. Their combination of jerkiness, humor, and relevant information entertains me.  When I was putting together my workstation I watched a bunch of their DIY build videos, but ended up getting hooked on their news videos.

But, they recently they topped themselves --- they built Eric S. Raymond's new workstation. If you don't know who Eric S Raymond is, it's not big deal, but you're probably running his GPS daemon software on your phone. If you're into Linux, check it out --- it's fun to watch a bunch of geeks build a dream machine.