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