mod_cgi.html revision f1b61a479eb469248c50c5d62a884e255e5982f0
842ae4bd224140319ae7feec1872b93dfd491143fielding<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
842ae4bd224140319ae7feec1872b93dfd491143fieldingXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
842ae4bd224140319ae7feec1872b93dfd491143fielding This file is generated from xml source: DO NOT EDIT
842ae4bd224140319ae7feec1872b93dfd491143fieldingXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
842ae4bd224140319ae7feec1872b93dfd491143fielding--><title>mod_cgi - Apache HTTP Server</title><link rel="stylesheet" type="text/css" href="/style/manual.css"/></head><body><blockquote><div align="center"><img src="/images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_cgi</h1><table bgcolor="#cccccc" cellpadding="0" cellspacing="1"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td>Execution of CGI scripts</td></tr><tr><td><a class="help" href="module-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="module-dict.html#ModuleIdentifier">Module Identifier:</a></td><td>cgi_module</td></tr></table></td></tr></table><h2>Summary</h2>
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd <p>Any file that has the mime type
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd <code>cgi-script</code> (Apache 1.1 or later) will be treated
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd as a CGI script, and run by the server, with its output being
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd returned to the client. Files acquire this type either by
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding having a name containing an extension defined by the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <a class="directive" href="mod_mime.html#addtype"><code class="directive">AddType</code></a> directive, or by being
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding in a <a class="directive" href="mod_alias.html#scriptalias"><code class="directive">ScriptAlias</code></a>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding directory.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>When the server invokes a CGI script, it will add a variable
e8f95a682820a599fe41b22977010636be5c2717jim called <code>DOCUMENT_ROOT</code> to the environment. This
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding variable will contain the value of the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <a class="directive" href="core.html#documentroot"><code class="directive">DocumentRoot</code></a> configuration
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding variable.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>For an introduction to using CGI scripts with Apache, see
e8f95a682820a599fe41b22977010636be5c2717jim our tutorial on <a href="/howto/cgi.html">Dynamic Content
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>When using a multi-threaded MPM under unix, the module
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <code><a href="mod_cgid.html">mod_cgid</a></code> should be used in place of
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding this module. At the user level, the two modules are essentially
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding identical.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<h2>Directives</h2><ul><li><a href="#scriptlog">ScriptLog</a></li><li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li><li><a href="#scriptloglength">ScriptLogLength</a></li></ul><p><strong>See also </strong></p><ul><li><a class="directive" href="core.html#options"><code class="directive">Options</code></a></li><li><a class="directive" href="mod_alias.html#scriptalias"><code class="directive">ScriptAlias</code></a></li><li><a class="directive" href="mod_mime.html#addhandler"><code class="directive">AddHandler</code></a></li></ul><h2>CGI Environment variables</h2>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>The server will set the CGI environment variables as described
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding specification</a>, with the following provisions:</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <dd>This will not be available if the <a class="directive" href="core.html#acceptpathinfo"><code class="directive">AcceptPathInfo</code></a> directive is explicitly set to
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <code>off</code>. The default behavior, if AcceptPathInfo is
e8f95a682820a599fe41b22977010636be5c2717jim not given, is that mod_cgi will accept path info (trailing
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding /more/path/info following the script filename in the URI), while
e8f95a682820a599fe41b22977010636be5c2717jim the core server will return a 404 NOT FOUND error for requests
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding with additional path info. Omitting the AcceptPathInfo
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding directive has the same effect as setting it <code>on</code> for
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding mod_cgi requests.</dd>
e8f95a682820a599fe41b22977010636be5c2717jim <dd>This will only be set if <a class="directive" href="core.html#hostnamelookups"><code class="directive">HostnameLookups</code></a> is set to <code>on</code> (it
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding is off by default), and if a reverse DNS lookup of the accessing
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding host's address indeed finds a host name.</dd>
e8f95a682820a599fe41b22977010636be5c2717jim <dd>This will only be set if <a class="directive" href="core.html#identitycheck"><code class="directive">IdentityCheck</code></a> is set to
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <code>on</code> and the accessing host supports the ident
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding protocol. Note that the contents of this variable cannot be
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding relied upon because it can easily be faked, and if there is a
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding proxy between the client and the server, it is usually
e8f95a682820a599fe41b22977010636be5c2717jim totally useless.</dd>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <dd>This will only be set if the CGI script is subject to
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding authentication.</dd>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>Debugging CGI scripts has traditionally been difficult, mainly
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding because it has not been possible to study the output (standard
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding output and error) for scripts which are failing to run
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding properly. These directives, included in Apache 1.2 and later,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding provide more detailed logging of errors when they occur. </p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>When configured, the CGI error log logs any CGI which does not
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding execute properly. Each CGI script which fails to operate causes
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding several lines of information to be logged. The first two lines
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding are always of the format:</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding %% <em>HTTP-status</em> <em>CGI-script-filename</em>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>If the error is that CGI script cannot be run, the log file
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding will contain an extra two lines:</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
e8f95a682820a599fe41b22977010636be5c2717jim %%error<br/>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>Alternatively, if the error is the result of the script
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding returning incorrect header information (often due to a bug in
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding the script), the following information is logged: </p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding %request<br/>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding %response<br/>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding %stdout<br/>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding %stderr<br/>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>(The %stdout and %stderr parts may be missing if the script did
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding not output anything on standard output or standard error). </p>
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein<hr/><h2><a name="ScriptLog">ScriptLog</a> <a name="scriptlog">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Location of the CGI script error logfile</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>ScriptLog <em>file-path</em></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td><code><a href="mod_cgi.html">mod_cgi</a></code>, <code><a href="mod_cgid.html">mod_cgid</a></code></td></tr></table></td></tr></table>
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein <p>The <code class="directive">ScriptLog</code> directive sets the CGI
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein script error logfile. If no ScriptLog is given, no error log is
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein created. If given, any CGI errors are logged into the filename
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein given as argument. If this is a relative file or path it is taken
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein relative to the server root.</p>
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein <p>This log will be opened as the user the child processes run
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein as, ie. the user specified in the main <a class="directive" href="mpm_common.html#user"><code class="directive">User</code></a> directive. This means that
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein either the directory the script log is in needs to be writable
9625528fcf4fa27288f3be080a1979c8ef60d7dfrbb by that user or the file needs to be manually created and set
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding to be writable by that user. If you place the script log in
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding your main logs directory, do <strong>NOT</strong> change the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding directory permissions to make it writable by the user the child
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding processes run as.</p>
e9dacb49354baa7346837faad335f27caa7fe1eestoddard <p>Note that script logging is meant to be a debugging feature
ff250fa78a491f4dcf3e673f122f2d9942a7411awrowe when writing CGI scripts, and is not meant to be activated
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding continuously on running servers. It is not optimized for speed
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding or efficiency, and may have security problems if used in a
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding manner other than that for which it was designed.</p>
66724147170b966b8ce54b0b5f9d9bcc67641b90nd<hr/><h2><a name="ScriptLogBuffer">ScriptLogBuffer</a> <a name="scriptlogbuffer">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Maximum amount of PUT or POST requests that will be recorded
66724147170b966b8ce54b0b5f9d9bcc67641b90ndin the scriptlog</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>ScriptLogBuffer <em>bytes</em></td></tr><tr><td><a class="help" href="directive-dict.html#Default">Default:</a></td><td><code>ScriptLogBuffer 1024</code></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td><code><a href="mod_cgi.html">mod_cgi</a></code>, <code><a href="mod_cgid.html">mod_cgid</a></code></td></tr></table></td></tr></table>
66724147170b966b8ce54b0b5f9d9bcc67641b90nd <p>The size of any PUT or POST entity body that is logged to
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding the file is limited, to prevent the log file growing too big
3d96ee83babeec32482c9082c9426340cee8c44dwrowe too quickly if large bodies are being received. By default, up
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding to 1024 bytes are logged, but this can be changed with this
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding directive.</p>
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick<hr/><h2><a name="ScriptLogLength">ScriptLogLength</a> <a name="scriptloglength">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Size limit of the CGI script logfile</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>ScriptLogLength <em>bytes</em></td></tr><tr><td><a class="help" href="directive-dict.html#Default">Default:</a></td><td><code>ScriptLogLength 10385760</code></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td><code><a href="mod_cgi.html">mod_cgi</a></code>, <code><a href="mod_cgid.html">mod_cgid</a></code></td></tr></table></td></tr></table>
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick <p><code class="directive">ScriptLogLength</code> can be used to limit the
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick size of the CGI script logfile. Since the logfile logs a lot of
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding information per CGI error (all request headers, all script output)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding it can grow to be a big file. To prevent problems due to unbounded
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm growth, this directive can be used to set an maximum file-size for
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding the CGI logfile. If the file exceeds this size, no more
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding information will be written to it.</p>
