Allow CGI scripts within the document root of an Apache webserver
|Debian (Etch, Lenny, Squeeze)|
|Ubuntu (Lucid, Maverick, Natty)|
To allow CGI scripts to execute from within the document root of an Apache webserver
By default Apache requires that all CGI scripts be placed in the directory
/usr/lib/cgi-bin/, away from the static content of the website. This can be inconvenient if it prevents closely related files from being located near to each other:
- It may increase the need to use absolute as opposed to relative URLs and pathnames.
- It may make it necessary for some parts of the configuration to be stated twice.
These instructions describe an alternative method whereby CGI scripts are identified by means of a particular file extension. Scripts can then be placed alongside related static content.
Suppose that you are developing a gaming website for the domain
wopr.norad.mil. The document root is
/var/www/. Each game has a subdirectory beneath the root, for example
You wish to locate all of the files for each game (including any CGI scripts) alongside each other in the relevant subdirectory. The CGI scripts may be distinguished from files to be served statically by the fact that they end with the extension
The existing configuration for the document root is as follows:
DocumentRoot /var/www <Directory /var/www> Options None AllowOverride None Order allow,deny Allow from all </Directory>
Three steps are required:
- Associate the
cgi-scriptcontent handler with the required file extension.
- Ensure that the
ExecCGIoption is set for all relevant directories.
- Ensure that the CGI scripts are executable.
The configuration will need to be reloaded afterwards. See Cause a system service to reload its configuration for instructions.
AddHandler directive to associate files that end with the extension
.cgi with the
cgi-script content handler:
AddHandler cgi-script .cgi
A suitable location for this directive would be within the
<Directory> container corresponding to the document root (
/var/www in this case), but it can be used in any configuration context if required.
Apache will not execute a CGI script unless it is located in a directory for which the
ExecCGI option is enabled. This can be done using an
A suitable location would be alongside the
AddHandler directive discussed above. The required form of the directive will depend on whether the directory in question had any pre-existing options specified:
- If there is no existing
Optionsdirective then add one with the argument
+ExecCGIas above (with plus sign).
- If the options are set to
Nonethen replace them with
ExecCGI(no plus sign).
- If there is a list of options prefixed with plus and/or minus signs then append
+ExecCGIto the end of it (with plus sign).
- If there is a list of options without plus or minus signs then append
ExecCGIto the end of it (no plus sign).
Apache will not execute a CGI script unless its file mode indicates that it is executable. Depending on what the script does it may be acceptable for it to be executable by any user:
chmod +x *.cgi
or you may prefer to make it usable only by the owner of the web server process. On Debian-based systems this is typically
chown www-data:www-data *.cgi chmod 700 *.cgi
whereas on Red Hat-based systems it would typically be the
chown apache:apache *.cgi chmod 700 *.cgi
The resulting configuration for the document root would be as follows:
DocumentRoot /var/www <Directory /var/www/> Options ExecCGI AllowOverride None Order allow,deny Allow from all AddHandler cgi-script .cgi </Directory>
Execution of CGI scripts can be disabled within a directory by turning off the
ExecCGI option. For example, to do this within the directory
<Directory /var/www/upload> Options -ExecCGI </Directory>
It can be argued that allowing CGI scripts to execute from within the document root is more risky than requiring them to be placed in a separate
location such as
/usr/lib/cgi-bin. The main points of concern are that:
- Files within the document root are served statically by default, increasing the risk of accidental disclosure.
- The document root may also be readable and/or writable through other services such as FTP.
- Users who need write access to the static content do not necessarily need the ability to install CGI scripts.
None of these prevent the web server from being run securely, however they could make the task more difficult or prone to error. The advice given in the Apache documentation is that:
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.
- Apache Tutorial: Dynamic Content with CGI