mod_cgi.xml revision 08cb74ca432a8c24e39f17dedce527e6a47b8001
640b2adac05bb7f5e9fba064434c91852c3a72e6nd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
640b2adac05bb7f5e9fba064434c91852c3a72e6nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
640b2adac05bb7f5e9fba064434c91852c3a72e6nd<!-- $LastChangedRevision$ -->
640b2adac05bb7f5e9fba064434c91852c3a72e6nd Copyright 2002-2005 The Apache Software Foundation or its licensors, as
640b2adac05bb7f5e9fba064434c91852c3a72e6nd applicable.
640b2adac05bb7f5e9fba064434c91852c3a72e6nd Licensed under the Apache License, Version 2.0 (the "License");
640b2adac05bb7f5e9fba064434c91852c3a72e6nd you may not use this file except in compliance with the License.
640b2adac05bb7f5e9fba064434c91852c3a72e6nd You may obtain a copy of the License at
640b2adac05bb7f5e9fba064434c91852c3a72e6nd Unless required by applicable law or agreed to in writing, software
640b2adac05bb7f5e9fba064434c91852c3a72e6nd distributed under the License is distributed on an "AS IS" BASIS,
640b2adac05bb7f5e9fba064434c91852c3a72e6nd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
640b2adac05bb7f5e9fba064434c91852c3a72e6nd See the License for the specific language governing permissions and
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive limitations under the License.
b44815871de48215476ad1d4cc46d3f99da532a5erikabele <!-- XXX: Should mention Options ExecCGI
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive is the link to howto/cgi not sufficient? -nd
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive <p>Any file that has the mime type
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive <code>cgi-script</code> (Apache 1.1 or later) will be treated
d2a771c01de1a39b6f6770d9edd8b271d8e4f10eerikabele as a CGI script, and run by the server, with its output being
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive returned to the client. Files acquire this type either by
ef685e00a47967e27d89709461728a229d762172nd having a name containing an extension defined by the
ef685e00a47967e27d89709461728a229d762172nd <directive module="mod_mime">AddType</directive> directive, or by being
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive in a <directive module="mod_alias">ScriptAlias</directive>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive directory.</p>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive <p>When the server invokes a CGI script, it will add a variable
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive called <code>DOCUMENT_ROOT</code> to the environment. This
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive variable will contain the value of the
b44815871de48215476ad1d4cc46d3f99da532a5erikabele <directive module="core">DocumentRoot</directive> configuration
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive variable.</p>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive <p>For an introduction to using CGI scripts with Apache, see
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive our tutorial on <a href="/howto/cgi.html">Dynamic Content
d2a771c01de1a39b6f6770d9edd8b271d8e4f10eerikabele <p>When using a multi-threaded MPM under unix, the module
ef685e00a47967e27d89709461728a229d762172nd this module. At the user level, the two modules are essentially
2a7c98db85d4969dcbe7711a5ec3264ee4fc6222yoshiki identical.</p>
2a7c98db85d4969dcbe7711a5ec3264ee4fc6222yoshiki<seealso><directive module="core">AcceptPathInfo</directive></seealso>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive<seealso><directive module="core">Options</directive></seealso>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive<seealso><directive module="mod_alias">ScriptAlias</directive></seealso>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive<seealso><directive module="mod_mime">AddHandler</directive></seealso>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive<seealso><a href="/suexec.html">Running CGI programs under different
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive<seealso><a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI Specification</a></seealso>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive<section id="env"><title>CGI Environment variables</title>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive <p>The server will set the CGI environment variables as described
ef685e00a47967e27d89709461728a229d762172nd <dd>This will not be available if the <directive module="core"
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive >AcceptPathInfo</directive> directive is explicitly set to
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive >AcceptPathInfo</directive> is not given, is that <module
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive >mod_cgi</module> will accept path info (trailing <code>
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive /more/path/info</code> following the script filename in the URI),
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive while the core server will return a 404 NOT FOUND error for requests
b44815871de48215476ad1d4cc46d3f99da532a5erikabele with additional path info. Omitting the <directive
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive >AcceptPathInfo</directive> directive has the same effect as setting
a27e9e05958bc51ea09edb8d8d862fe8b125313bslive it <code>On</code> for <module>mod_cgi</module> requests.</dd>
d2a771c01de1a39b6f6770d9edd8b271d8e4f10eerikabele >HostnameLookups</directive> is set to <code>on</code> (it
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx is off by default), and if a reverse DNS lookup of the accessing
ef685e00a47967e27d89709461728a229d762172nd host's address indeed finds a host name.</dd>
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx >IdentityCheck</directive> is set to
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx <code>on</code> and the accessing host supports the ident
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx protocol. Note that the contents of this variable cannot be
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx relied upon because it can easily be faked, and if there is a
b44815871de48215476ad1d4cc46d3f99da532a5erikabele proxy between the client and the server, it is usually
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx totally useless.</dd>
cd51960ffc0f49d7a9e702162ed49b3eb0909276dirkx <dd>This will only be set if the CGI script is subject to
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick authentication.</dd>
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick <p>Debugging CGI scripts has traditionally been difficult, mainly
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick because it has not been possible to study the output (standard
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick output and error) for scripts which are failing to run
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick properly. These directives, included in Apache 1.2 and later,
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick provide more detailed logging of errors when they occur.</p>
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick <p>When configured, the CGI error log logs any CGI which does not
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick execute properly. Each CGI script which fails to operate causes
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick several lines of information to be logged. The first two lines
b5468eddc0cb1691af19ddc70a6e205daf00a94ctrawick are always of the format:</p>
d2a771c01de1a39b6f6770d9edd8b271d8e4f10eerikabele %% [<var>time</var>] <var>request-line</var><br />
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive %% <var>HTTP-status</var> <var>CGI-script-filename</var>
ef685e00a47967e27d89709461728a229d762172nd </example>
ef685e00a47967e27d89709461728a229d762172nd <p>If the error is that CGI script cannot be run, the log file
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive will contain an extra two lines:</p>
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive %%error<br />
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive <p>Alternatively, if the error is the result of the script
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive returning incorrect header information (often due to a bug in
222f0f03c2f9ee6343c18f80f0cb6e9aad21bc58slive the script), the following information is logged:</p>
1f2a7403f1389cbf2da0a53a2b2fb425dea75506erikabele %request<br />
d2a771c01de1a39b6f6770d9edd8b271d8e4f10eerikabele <var>All HTTP request headers received</var><br />
ef685e00a47967e27d89709461728a229d762172nd %response<br />
ef685e00a47967e27d89709461728a229d762172nd %stdout<br />
1f2a7403f1389cbf2da0a53a2b2fb425dea75506erikabele %stderr<br />
1f2a7403f1389cbf2da0a53a2b2fb425dea75506erikabele <p>(The %stdout and %stderr parts may be missing if the script did
b44815871de48215476ad1d4cc46d3f99da532a5erikabele not output anything on standard output or standard error).</p>
1f2a7403f1389cbf2da0a53a2b2fb425dea75506erikabele<directivesynopsis>
81622596373177e079337e956f7a5800895443b3erikabele<description>Location of the CGI script error logfile</description>
ef685e00a47967e27d89709461728a229d762172nd<modulelist><module>mod_cgi</module><module>mod_cgid</module>
ef685e00a47967e27d89709461728a229d762172nd</modulelist>
81622596373177e079337e956f7a5800895443b3erikabele <p>The <directive>ScriptLog</directive> directive sets the CGI
81622596373177e079337e956f7a5800895443b3erikabele script error logfile. If no <directive>ScriptLog</directive> is given,
81622596373177e079337e956f7a5800895443b3erikabele no error log is created. If given, any CGI errors are logged into the
81622596373177e079337e956f7a5800895443b3erikabele filename given as argument. If this is a relative file or path it is
81622596373177e079337e956f7a5800895443b3erikabele taken relative to the <directive module="core">ServerRoot</directive>.
ef685e00a47967e27d89709461728a229d762172nd </example>
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele <p>This log will be opened as the user the child processes run
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele as, <em>i.e.</em> the user specified in the main <directive
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele module="mpm_common">User</directive> directive. This means that
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele either the directory the script log is in needs to be writable
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele by that user or the file needs to be manually created and set
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele to be writable by that user. If you place the script log in
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele your main logs directory, do <strong>NOT</strong> change the
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele directory permissions to make it writable by the user the child
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele processes run as.</p>
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele <p>Note that script logging is meant to be a debugging feature
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele when writing CGI scripts, and is not meant to be activated
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele continuously on running servers. It is not optimized for speed
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele or efficiency, and may have security problems if used in a
f0eae6f6191f5730fa8db049f7391e93b4ff41b9erikabele manner other than that for which it was designed.</p>