mod_cgi.html revision 529582a553eeee60daa9cab7c3940331e984032c
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos BGCOLOR="#FFFFFF"
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo Hordos TEXT="#000000"
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos LINK="#0000FF"
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos VLINK="#000080"
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos ALINK="#FF0000"
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo Hordos<!--#include virtual="header.html" -->
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosThis module is contained in the <code>mod_cgi.c</code> file, and
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosis compiled in by default. It provides for execution of CGI scripts.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosAny file with mime type <code>application/x-httpd-cgi</code> will be
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosprocessed by this module.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<!--%plaintext <?INDEX {\tt application/x-httpd-cgi} mime type> -->
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo Hordos<!--%plaintext <?INDEX CGI scripts> -->
88f2d7061bb42999901dcff81c37089b000d32e0Paul BryanAny file that has the mime type <code>application/x-httpd-cgi</code>
88f2d7061bb42999901dcff81c37089b000d32e0Paul Bryanor handler <code>cgi-script</code> (Apache 1.1 or later)
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoswill be treated as a CGI script, and run by the server, with its output
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosbeing returned to the client. Files acquire this type either by
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoshaving a name ending in an extension defined by the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosa <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <p>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosWhen the server invokes a CGI script, it will add a variable called
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<code>DOCUMENT_ROOT</code> to the environment. This variable will contain the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosvalue of the <A HREF="core.html#documentroot">DocumentRoot</A>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosconfiguration variable.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosThe server will set the CGI environment variables as described in the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI specification</A>, with the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosfollowing provisions:
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<dt>REMOTE_HOST
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<dd>This will only be set if the server has not been compiled with
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<dt>REMOTE_IDENT
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<dd>This will only be set if
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <code>on</code>.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<dt>REMOTE_USER
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<dd>This will only be set if the CGI script is subject to authentication.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosDebugging CGI scripts has traditionally been difficult, mainly because
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo Hordosbeen possible to study the output (standard output and error) for
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo Hordoswhich are failing to run properly. These directives, included in
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo HordosApache 1.2 and later, provide
d0840514601c4eea1672996b07b27ca61bd4197dLaszlo Hordosmore detailed logging of errors when they occur.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosWhen configured, the CGI error log logs any CGI which does not execute
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosproperly. Each CGI script which fails to operate causes several lines
699a2bb8c272ad1594ca4e9b26ff876dcdf4f392Laszlo Hordosof information to be logged. The first two lines are always of the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos %% <i>HTTP-status</i> <i>CGI-script-filename</i>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosIf the error is that CGI script cannot be run, the log file will
c73d3f75658bdf9e249758bdff3c53d59d60d0b9Laszlo Hordosan extra two lines:
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosAlternatively, if the error is the result of the script returning
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosincorrect header information (often due to a bug in the script), the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosfollowing information is logged:
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos(The %stdout and %stderr parts may be missing if the script did not
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosanything on standard output or standard error).
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosThe <tt>ScriptLog</tt> directive sets the CGI script error logfile.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosIf no ScriptLog is given, no error log is created. If given, any
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosCGI errors are logged into the filename given as argument. If this
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosis a relative file or path it is taken relative to the server root.
d90caa300251d7fd09e3f286018ce04356a71e62Laszlo Hordos<P>This log will be opened as the user the child processes run as,
b8dc46d8fabaf0050ef4847d103e66ea9395a032Laszlo Hordosie. the user specified in the main <A HREF="core.html#User">User</A>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosdirective. This means that either the directory the script log is
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosin needs to be writable by that user or the file needs to be manually
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoscreated and set to be writable by that user. If you place the
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosscript log in your main logs directory, do <STRONG>NOT</STRONG>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoschange the directory permissions to make it writable by the user
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosthe child processes run as.</P>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<p>Note that script logging is meant to be a debugging feature when
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoswriting CGI scripts, and is not meant to be activated continuously on
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosrunning servers. It is not optimized for speed or efficiency, and may
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoshave security problems if used in a manner other than that for which
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosit was designed.</p>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<h3><a name="scriptloglength">ScriptLogLength</a></h3>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<tt>ScriptLogLength</tt> can be used to limit the size of the CGI
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosscript logfile. Since the logfile logs a lot of information per CGI
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordoserror (all request headers, all script output) it can grow to be a big
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosfile. To prevent problems due to unbounded growth, this directive can
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosbe used to set an maximum file-size for the CGI logfile. If the file
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosexceeds this size, no more information will be written to it.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<h3><a name="scriptlogbuffer">ScriptLogBuffer</a></h3>
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo HordosThe size of any PUT or POST entity body that is logged to the file is
9541e63de5a0e8de81d8f741de795a458ce0cbdeLaszlo Hordoslimited, to prevent the log file growing too big too quickly if large
9541e63de5a0e8de81d8f741de795a458ce0cbdeLaszlo Hordosbodies are being received. By default, up to 1024 bytes are logged,
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordosbut this can be changed with this directive.
0fdda69ce3627d501e4bb3103765f676bb1ab061Laszlo Hordos<!--#include virtual="footer.html" -->