mod_cgi.xml revision 81c37886d057e583a58568f455a55d82c70bb946
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<!-- $LastChangedRevision$ -->
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz Licensed to the Apache Software Foundation (ASF) under one or more
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz contributor license agreements. See the NOTICE file distributed with
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz this work for additional information regarding copyright ownership.
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz The ASF licenses this file to You under the Apache License, Version 2.0
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz (the "License"); you may not use this file except in compliance with
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz the License. You may obtain a copy of the License at
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz Unless required by applicable law or agreed to in writing, software
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz distributed under the License is distributed on an "AS IS" BASIS,
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz See the License for the specific language governing permissions and
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz limitations under the License.
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<description>Execution of CGI scripts</description>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <!-- XXX: Should mention Options ExecCGI
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz is the link to howto/cgi not sufficient? -nd
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>Any file that has the handler
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz as a CGI script, and run by the server, with its output being
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz returned to the client. Files acquire this handler either by
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz having a name containing an extension defined by the
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <directive module="mod_mime">AddHandler</directive> directive, or by being
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz in a <directive module="mod_alias">ScriptAlias</directive>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz directory.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>For an introduction to using CGI scripts with Apache, see
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz our tutorial on <a href="/howto/cgi.html">Dynamic Content
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>When using a multi-threaded MPM under unix, the module
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <module>mod_cgid</module> should be used in place of
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz this module. At the user level, the two modules are essentially
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz identical.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>For backward-compatibility, the cgi-script handler will also be activated
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz for any file with the mime-type <code>application/x-httpd-cgi</code>. The
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz use of the magic mime-type is deprecated.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<seealso><directive module="core">AcceptPathInfo</directive></seealso>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<seealso><directive module="core">Options</directive></seealso>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<seealso><directive module="mod_alias">ScriptAlias</directive></seealso>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<seealso><directive module="mod_mime">AddHandler</directive></seealso>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<seealso><a href="/suexec.html">Running CGI programs under different
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<seealso><a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI Specification</a></seealso>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<section id="env"><title>CGI Environment variables</title>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>The server will set the CGI environment variables as described
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz specification</a>, with the following provisions:</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <dd>This will not be available if the <directive module="core"
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz >AcceptPathInfo</directive> directive is explicitly set to
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <code>off</code>. The default behavior, if <directive
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz >AcceptPathInfo</directive> is not given, is that <module
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz >mod_cgi</module> will accept path info (trailing <code>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz /more/path/info</code> following the script filename in the URI),
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz while the core server will return a 404 NOT FOUND error for requests
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz with additional path info. Omitting the <directive
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz >AcceptPathInfo</directive> directive has the same effect as setting
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz it <code>On</code> for <module>mod_cgi</module> requests.</dd>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <dd>This will only be set if <directive module="core"
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz >HostnameLookups</directive> is set to <code>on</code> (it
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz is off by default), and if a reverse DNS lookup of the accessing
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz host's address indeed finds a host name.</dd>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <dd>This will only be set if <directive module="core"
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz >IdentityCheck</directive> is set to
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <code>on</code> and the accessing host supports the ident
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz protocol. Note that the contents of this variable cannot be
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz relied upon because it can easily be faked, and if there is a
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz proxy between the client and the server, it is usually
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz totally useless.</dd>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <dd>This will only be set if the CGI script is subject to
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz authentication.</dd>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<section id="cgi-debug"><title>CGI Debugging</title>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>Debugging CGI scripts has traditionally been difficult, mainly
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz because it has not been possible to study the output (standard
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz output and error) for scripts which are failing to run
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz properly. These directives, included in Apache 1.2 and later,
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz provide more detailed logging of errors when they occur.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>When configured, the CGI error log logs any CGI which does not
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz execute properly. Each CGI script which fails to operate causes
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz several lines of information to be logged. The first two lines
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz are always of the format:</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %% [<var>time</var>] <var>request-line</var><br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %% <var>HTTP-status</var> <var>CGI-script-filename</var>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>If the error is that CGI script cannot be run, the log file
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz will contain an extra two lines:</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %%error<br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>Alternatively, if the error is the result of the script
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz returning incorrect header information (often due to a bug in
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz the script), the following information is logged:</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %request<br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <var>All HTTP request headers received</var><br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %response<br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <var>All headers output by the CGI script</var><br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %stdout<br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz %stderr<br />
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>(The %stdout and %stderr parts may be missing if the script did
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz not output anything on standard output or standard error).</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<directivesynopsis>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<description>Location of the CGI script error logfile</description>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<modulelist><module>mod_cgi</module><module>mod_cgid</module>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</modulelist>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>The <directive>ScriptLog</directive> directive sets the CGI
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz script error logfile. If no <directive>ScriptLog</directive> is given,
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz no error log is created. If given, any CGI errors are logged into the
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz filename given as argument. If this is a relative file or path it is
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz taken relative to the <directive module="core">ServerRoot</directive>.
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>This log will be opened as the user the child processes run
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz as, <em>i.e.</em> the user specified in the main <directive
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz module="mpm_common">User</directive> directive. This means that
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz either the directory the script log is in needs to be writable
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz by that user or the file needs to be manually created and set
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz to be writable by that user. If you place the script log in
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz your main logs directory, do <strong>NOT</strong> change the
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz directory permissions to make it writable by the user the child
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz processes run as.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>Note that script logging is meant to be a debugging feature
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz when writing CGI scripts, and is not meant to be activated
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz continuously on running servers. It is not optimized for speed
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz or efficiency, and may have security problems if used in a
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz manner other than that for which it was designed.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</directivesynopsis>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<directivesynopsis>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<description>Size limit of the CGI script logfile</description>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<syntax>ScriptLogLength <var>bytes</var></syntax>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<modulelist><module>mod_cgi</module><module>mod_cgid</module>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</modulelist>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p><directive>ScriptLogLength</directive> can be used to limit the
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz size of the CGI script logfile. Since the logfile logs a lot of
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz information per CGI error (all request headers, all script output)
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz it can grow to be a big file. To prevent problems due to unbounded
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz growth, this directive can be used to set an maximum file-size for
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz the CGI logfile. If the file exceeds this size, no more
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz information will be written to it.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</directivesynopsis>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<directivesynopsis>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<description>Maximum amount of PUT or POST requests that will be recorded
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantzin the scriptlog</description>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<syntax>ScriptLogBuffer <var>bytes</var></syntax>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz<modulelist><module>mod_cgi</module><module>mod_cgid</module>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</modulelist>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <p>The size of any PUT or POST entity body that is logged to
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz the file is limited, to prevent the log file growing too big
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz too quickly if large bodies are being received. By default, up
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz to 1024 bytes are logged, but this can be changed with this
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz directive.</p>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</directivesynopsis>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz</modulesynopsis>