Hack 92 Turning on CGI


CGI scripts allow you to serve up dynamic content on your web site using a Unix-based scripting language like Perl.

It's now time to fiddle with the most commonly used way of generating dynamic content and serving it up on your web server. We're talking about Common Gateway Interface (CGI). Without getting overly esoteric, CGI allows us to install thousands of different scripts that can be accessed through a normal web browser. CGI scripts are most often written in a Unix scripting language like Perl, Python, or Ruby. They can allow users to access databases, use interactive forms, chat in bulletin boards, and so on.

Apache comes with two simple scripts that can verify CGI is configured correctly. Before we test them, however, we've got to poke around our httpd.conf file a bit. As mentioned earlier [Hack #89], the easiest way to find out more about a feature is simply to search for the term in question. These are all the relevant matches we'll find in our httpd.conf for CGI:

LoadModule cgi_module libexec/httpd/mod_cgi.so
AddModule mod_cgi.c

ScriptAlias /cgi-bin/ "/Library/WebServer/CGI-Executables/"

<Directory "/Library/WebServer/CGI-Executables">
  AllowOverride None Options None
  Order allow,deny
  Allow from all

# AddHandler cgi-script .cgi

We've already described the first two lines [Hack #89], but the ScriptAlias directive allows us to map a URL to a location on our hard drive. In this case, Apache is mapping to the /Library/WebServer/CGI-Executables/ directory. If you browse there now, you'll see the two CGI scripts I offhandedly mentioned earlier: printenv and test-cgi ? we'll run those shortly.

Moving on, <Directory> isn't that important right now, so we'll jaunt off to our final search result, AddHandler. This is your first major decision concerning your Apache installation. When a certain directory has been ScriptAliased (as our CGI-Executables directory has), the files within that directory are always executed as CGI scripts. If the files were moved out of that directory, they'd be served as normal text files.

By uncommenting the AddHandler, you're telling Apache to execute any file that ends in .cgi. This can happen from any directory and from any user and is often considered a security hazard.

In a default installation of Apache on Mac OS X, CGI scripts are allowed only within /Library/Webserver/CGI-Executables/. Uncommenting [Hack #89] the preceding line (removing the # character) allows CGI scripts to be executed from any user directory, such as /Users/morbus/Sites. It's really your choice, but if you're new to the world of web serving, your best bet is to leave this alone.

If CGI access is turned on already, we should be able to reach and see a happy result, right? If you went to that URL, however, you were probably greeted by a not so joyous response: "FORBIDDEN." Apache screams, "You don't have permission to access /cgi-bin/test-cgi."

Huh? Why didn't this work? Now is a perfect time to prove how useful the Apache web-server logs can be. Apache's access file is located in /var/log/httpd/access_log, so let's look at the very last lines of that file, easily reached with this command:

% tail /var/log/httpd/access_log

You'll see that the last line looks something like this:

... - - [19/Nov/2002:21:59:46-0500] "GET /cgi-bin/test-cgi HTTP/1.1" 403 292

This line shows where the access request came from (, the time the file was requested, the protocol used (HTTP/1.1), the response code (403), and the size of the response (292 bytes). This is all fine and dandy, but it doesn't tell us what went wrong. For this, we'll dip into our error log:

% tail /var/log/httpd/error_log

And we see:

[Mon Nov 19 21:59:46 2002] [error] [client]
file permissions deny server execution:

Bingo! This tells us exactly what went awry: the file permissions were incorrect. For Apache to run a CGI script, the script in question needs to have execute permissions [Hack #55]. To give the test-cgi file the correct permissions, type the following on the command line [Hack #48]:

% cd /Library/WebServer/CGI-Executables
% chmod 755 test-cgi

After doing this, load the URL again, and you should be happily greeted with gobs of environment information. (To learn more about permissions and the chmod utility, see [Hack #49].)

With the basics of CGI out of the way, you can now install CGI-based applications to complement your intranet. Need a content management system for the developers to keep everyone up-to-date on their coding progress and discussions? Try the Movable Type (http://www.movabletype.org) weblog application.

92.1 See Also

  • Apache Web-Serving with Mac OS X: Part 2 (http://www.macdevcenter.com/lpt/a//mac/2001/12/14/apache_two.html)