- publishing free software manuals
The Apache HTTP Server Reference Manual
by Apache Software Foundation
Paperback (6"x9"), 862 pages
ISBN 9781906966034
RRP £19.95 ($29.95)

Get a printed copy>>>

9.2  Configuring Apache to permit CGI

In order to get your CGI programs to work properly, you’ll need to have Apache configured to permit CGI execution. There are several ways to do this.

9.2.1  ScriptAlias

The ScriptAlias

directive tells Apache that a particular directory is set aside for CGI programs. Apache will assume that every file in this directory is a CGI program, and will attempt to execute it, when that particular resource is requested by a client.

The ScriptAlias directive looks like:

ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

The example shown is from your default httpd.conf configuration file, if you installed Apache in the default location. The ScriptAlias directive is much like the Alias directive, which defines a URL prefix that is to mapped to a particular directory. Alias and ScriptAlias are usually used for directories that are outside of the DocumentRoot directory. The difference between Alias and ScriptAlias is that ScriptAlias has the added meaning that everything under that URL prefix will be considered a CGI program. So, the example above tells Apache that any request for a resource beginning with /cgi-bin/ should be served from the directory /usr/local/apache2/cgi-bin/, and should be treated as a CGI program.

For example, if the URL http://www.example.com/cgi-bin/test.pl is requested, Apache will attempt to execute the file /usr/local/apache2/cgi-bin/test.pl and return the output. Of course, the file will have to exist, and be executable, and return output in a particular way, or Apache will return an error message.

9.2.2  CGI outside of ScriptAlias directories

CGI programs are often restricted to ScriptAlias’ed directories for security reasons. In this way, administrators can tightly control who is allowed to use CGI programs. However, if the proper security precautions are taken, there is no reason why CGI programs cannot be run from arbitrary directories. For example, you may wish to let users have web content in their home directories with the UserDir directive. If they want to have their own CGI programs, but don’t have access to the main cgi-bin directory, they will need to be able to run CGI programs elsewhere.

There are two steps to allowing CGI execution in an arbitrary directory. First, the cgi-script handler must be activated using the AddHandler or SetHandler directive. Second, ExecCGI must be specified in the Options directive.

9.2.3  Explicitly using Options to permit CGI execution

You could explicitly use the Options directive, inside your main server configuration file, to specify that CGI execution was permitted in a particular directory:

<Directory /usr/local/apache2/htdocs/somedir>

Options +ExecCGI


The above directive tells Apache to permit the execution of CGI files. You will also need to tell the server what files are CGI files. The following AddHandler directive tells the server to treat all files with the cgi or pl extension as CGI programs:

AddHandler cgi-script .cgi .pl

9.2.4  .htaccess files

The .htaccess tutorial (p. 1365) shows how to activate CGI programs if you do not have access to httpd.conf.

9.2.5  User Directories

To allow CGI program execution for any file ending in .cgi in users’ directories, you can use the following configuration.

<Directory /home/*/public_html>

Options +ExecCGI
AddHandler cgi-script .cgi


If you wish designate a cgi-bin subdirectory of a user’s directory where everything will be treated as a CGI program, you can use the following.

<Directory /home/*/public_html/cgi-bin>

Options ExecCGI
SetHandler cgi-script


ISBN 9781906966034The Apache HTTP Server Reference ManualSee the print edition