d9ef684564c53b70e20e0d8a98aa721687cf2605kess<?xml version="1.0"?>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<!DOCTYPE xml:manual [ <!ENTITY nbsp "&#160;"> ]>

eca1144dc479593f288406c5135a8b71d02c36c5kess<?xml-stylesheet type="text/xsl" href="/style/manual.xsl"?>

6e14faf37935e36804b8bad802bc9dd58f3cf65dsf<modulesynopsis>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

a3d2b657dd7ca66251b562b6a82c2335135b9172nd<name>mod_cgi</name>

031b91a62d25106ae69d4693475c79618dd5e884fielding<description>Execution of CGI scripts</description>

031b91a62d25106ae69d4693475c79618dd5e884fielding<status>Base</status>

031b91a62d25106ae69d4693475c79618dd5e884fielding<sourcefile>mod_cgi.c</sourcefile>

031b91a62d25106ae69d4693475c79618dd5e884fielding<identifier>cgi_module</identifier>

031b91a62d25106ae69d4693475c79618dd5e884fielding

031b91a62d25106ae69d4693475c79618dd5e884fielding<summary>

a3d2b657dd7ca66251b562b6a82c2335135b9172nd <!-- XXX: Should have references to CGI definition/RFC -->

a3d2b657dd7ca66251b562b6a82c2335135b9172nd <!-- XXX: Should mention Options ExecCGI -->

a3d2b657dd7ca66251b562b6a82c2335135b9172nd <!-- XXX: Should mention AcceptPathInfo -->

a3d2b657dd7ca66251b562b6a82c2335135b9172nd

a3d2b657dd7ca66251b562b6a82c2335135b9172nd <p>Any file that has the mime type

a3d2b657dd7ca66251b562b6a82c2335135b9172nd <code>application/x-httpd-cgi</code> or handler

a3d2b657dd7ca66251b562b6a82c2335135b9172nd <code>cgi-script</code> (Apache 1.1 or later) will be treated

a3d2b657dd7ca66251b562b6a82c2335135b9172nd as a CGI script, and run by the server, with its output being

a3d2b657dd7ca66251b562b6a82c2335135b9172nd returned to the client. Files acquire this type either by

a3d2b657dd7ca66251b562b6a82c2335135b9172nd having a name containing an extension defined by the

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <directive module="mod_mime">AddType</directive> directive, or by being

d9ef684564c53b70e20e0d8a98aa721687cf2605kess in a <directive module="mod_alias">ScriptAlias</directive>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess directory.</p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>When the server invokes a CGI script, it will add a variable

d9ef684564c53b70e20e0d8a98aa721687cf2605kess called <code>DOCUMENT_ROOT</code> to the environment. This

d9ef684564c53b70e20e0d8a98aa721687cf2605kess variable will contain the value of the

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <directive module="core.html">DocumentRoot</directive> configuration

d9ef684564c53b70e20e0d8a98aa721687cf2605kess variable.</p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>For an introduction to using CGI scripts with Apache, see

d9ef684564c53b70e20e0d8a98aa721687cf2605kess our tutorial on <a href="/howto/cgi.html">Dynamic Content

d9ef684564c53b70e20e0d8a98aa721687cf2605kess With CGI</a>.</p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>When using a multi-threaded MPM under unix, the module

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <module>mod_cgid</module> should be used in place of

d9ef684564c53b70e20e0d8a98aa721687cf2605kess this module. At the user level, the two modules are essentially

d9ef684564c53b70e20e0d8a98aa721687cf2605kess identical.</p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess</summary>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<seealso><directive module="core">Options</directive></seealso>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<seealso><directive module="mod_alias">ScriptAlias</directive></seealso>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<seealso><directive module="mod_mime">AddHandler</directive></seealso>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<section><title>CGI Environment variables</title>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>The server will set the CGI environment variables as described

d9ef684564c53b70e20e0d8a98aa721687cf2605kess in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI

d9ef684564c53b70e20e0d8a98aa721687cf2605kess specification</a>, with the following provisions:</p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dl>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dt>PATH_INFO</dt>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dd>This will not be available if the <directive module="core"

d9ef684564c53b70e20e0d8a98aa721687cf2605kess >AcceptPathInfo</directive> directive is explicitly set to

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <code>off</code>. The default behavior, if AcceptPathInfo is

d9ef684564c53b70e20e0d8a98aa721687cf2605kess not given, is that mod_cgi will accept path info (trailing

d9ef684564c53b70e20e0d8a98aa721687cf2605kess /more/path/info following the script filename in the URI), while

d9ef684564c53b70e20e0d8a98aa721687cf2605kess the core server will return a 404 NOT FOUND error for requests

d9ef684564c53b70e20e0d8a98aa721687cf2605kess with additional path info. Omitting the AcceptPathInfo

d9ef684564c53b70e20e0d8a98aa721687cf2605kess directive has the same effect as setting it <code>on</code> for

d9ef684564c53b70e20e0d8a98aa721687cf2605kess mod_cgi requests.</dd>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dt>REMOTE_HOST</dt>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dd>This will only be set if <directive module="core"

d9ef684564c53b70e20e0d8a98aa721687cf2605kess >HostnameLookups</directive> is set to <code>on</code> (it

d9ef684564c53b70e20e0d8a98aa721687cf2605kess is off by default), and if a reverse DNS lookup of the accessing

d9ef684564c53b70e20e0d8a98aa721687cf2605kess host's address indeed finds a host name.</dd>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dt>REMOTE_IDENT</dt>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dd>This will only be set if <directive module="core"

d9ef684564c53b70e20e0d8a98aa721687cf2605kess >IdentityCheck</directive> is set to

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <code>on</code> and the accessing host supports the ident

d9ef684564c53b70e20e0d8a98aa721687cf2605kess protocol. Note that the contents of this variable cannot be

d9ef684564c53b70e20e0d8a98aa721687cf2605kess relied upon because it can easily be faked, and if there is a

d9ef684564c53b70e20e0d8a98aa721687cf2605kess proxy between the client and the server, it is usually

d9ef684564c53b70e20e0d8a98aa721687cf2605kess totally useless.</dd>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dt>REMOTE_USER</dt>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <dd>This will only be set if the CGI script is subject to

d9ef684564c53b70e20e0d8a98aa721687cf2605kess authentication.</dd>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess </dl>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess</section>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<section id="cgi_debug"><title>CGI Debugging</title>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>Debugging CGI scripts has traditionally been difficult, mainly

d9ef684564c53b70e20e0d8a98aa721687cf2605kess because it has not been possible to study the output (standard

d9ef684564c53b70e20e0d8a98aa721687cf2605kess output and error) for scripts which are failing to run

d9ef684564c53b70e20e0d8a98aa721687cf2605kess properly. These directives, included in Apache 1.2 and later,

d9ef684564c53b70e20e0d8a98aa721687cf2605kess provide more detailed logging of errors when they occur. </p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<section><title>CGI Logfile Format</title>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>When configured, the CGI error log logs any CGI which does not

d9ef684564c53b70e20e0d8a98aa721687cf2605kess execute properly. Each CGI script which fails to operate causes

d9ef684564c53b70e20e0d8a98aa721687cf2605kess several lines of information to be logged. The first two lines

d9ef684564c53b70e20e0d8a98aa721687cf2605kess are always of the format:</p>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess<example>

d282b5abebd9c783b5db6b95b7d0a2707dd3317cnd %% [<em>time</em>] <em>request-line</em><br />

d282b5abebd9c783b5db6b95b7d0a2707dd3317cnd %% <em>HTTP-status</em> <em>CGI-script-filename</em>

d282b5abebd9c783b5db6b95b7d0a2707dd3317cnd</example>

d9ef684564c53b70e20e0d8a98aa721687cf2605kess <p>If the error is that CGI script cannot be run, the log file

d9ef684564c53b70e20e0d8a98aa721687cf2605kess will contain an extra two lines:</p>

<example>

%%error<br />

<em>error-message</em>

</example>

<p>Alternatively, if the error is the result of the script

returning incorrect header information (often due to a bug in

the script), the following information is logged: </p>

<example>

%request<br />

<em>All HTTP request headers received</em><br />

<em>POST or PUT entity (if any)</em><br />

%response<br />

<em>All headers output by the CGI script</em><br />

%stdout<br />

<em>CGI standard output</em><br />

%stderr<br />

<em>CGI standard error</em><br />

</example>

<p>(The %stdout and %stderr parts may be missing if the script did

not output anything on standard output or standard error). </p>

</section>

</section>

<directivesynopsis>

<name>ScriptLog</name>

<description>Location of the CGI script error logfile</description>

<syntax>ScriptLog <em>file-path</em></syntax>

<contextlist><context>server config</context></contextlist>

<modulelist><module>mod_cgi</module><module>mod_cgid</module>

</modulelist>

<usage>

<p>The <directive>ScriptLog</directive> directive sets the CGI

script error logfile. If no ScriptLog is given, no error log is

created. If given, any CGI errors are logged into the filename

given as argument. If this is a relative file or path it is taken

relative to the server root.</p>

<p>This log will be opened as the user the child processes run

as, ie. the user specified in the main <directive module="mpm_common"

>User</directive> directive. This means that

either the directory the script log is in needs to be writable

by that user or the file needs to be manually created and set

to be writable by that user. If you place the script log in

your main logs directory, do <strong>NOT</strong> change the

directory permissions to make it writable by the user the child

processes run as.</p>

<p>Note that script logging is meant to be a debugging feature

when writing CGI scripts, and is not meant to be activated

continuously on running servers. It is not optimized for speed

or efficiency, and may have security problems if used in a

manner other than that for which it was designed.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ScriptLogLength</name>

<description>Size limit of the CGI script logfile</description>

<syntax>ScriptLogLength <em>bytes</em></syntax>

<default>ScriptLogLength 10385760</default>

<contextlist><context>server config</context></contextlist>

<modulelist><module>mod_cgi</module><module>mod_cgid</module>

</modulelist>

<usage>

<p><directive>ScriptLogLength</directive> can be used to limit the

size of the CGI script logfile. Since the logfile logs a lot of

information per CGI error (all request headers, all script output)

it can grow to be a big file. To prevent problems due to unbounded

growth, this directive can be used to set an maximum file-size for

the CGI logfile. If the file exceeds this size, no more

information will be written to it.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ScriptLogBuffer</name>

<description>Maximum amount of PUT or POST requests that will be recorded

in the scriptlog</description>

<syntax>ScriptLogBuffer <em>bytes</em></syntax>

<default>ScriptLogBuffer 1024</default>

<contextlist><context>server config</context></contextlist>

<modulelist><module>mod_cgi</module><module>mod_cgid</module>

</modulelist>

<usage>

<p>The size of any PUT or POST entity body that is logged to

the file is limited, to prevent the log file growing too big

too quickly if large bodies are being received. By default, up

to 1024 bytes are logged, but this can be changed with this

directive.</p>

</usage>

</directivesynopsis>

</modulesynopsis>