mirror of
https://github.com/apache/httpd.git
synced 2025-10-30 08:05:39 +03:00
62884a215d
- add docs for mod_cgid - link up the CGI tutorial brought forward from 1.3 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89035 13f79535-47bb-0310-9956-ffa450edef68
251 lines
7.6 KiB
HTML
251 lines
7.6 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_cgi</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
|
|
<H1 ALIGN="CENTER">Module mod_cgi</H1>
|
|
|
|
<p>This module provides for execution of CGI scripts.</p>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_cgi.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> cgi_module
|
|
</P>
|
|
|
|
|
|
<H2>Summary</H2>
|
|
<!-- XXX: Should have references to CGI definition/RFC -->
|
|
<!-- XXX: Should mention Options ExecCGI -->
|
|
|
|
<p>Any file that has the mime type <CODE>application/x-httpd-cgi</CODE>
|
|
or handler <CODE>cgi-script</CODE> (Apache 1.1 or later)
|
|
will be treated as a CGI script, and run by the server, with its output
|
|
being returned to the client. Files acquire this type either by
|
|
having a name containing an extension defined by the
|
|
<A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in
|
|
a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory.</P>
|
|
|
|
<p>When the server invokes a CGI script, it will add a variable called
|
|
<CODE>DOCUMENT_ROOT</CODE> to the environment. This variable will contain the
|
|
value of the <A HREF="core.html#documentroot">DocumentRoot</A>
|
|
configuration variable.</p>
|
|
|
|
<p>For an intruction to using CGI scripts with Apache, see our
|
|
tutorial on <a href="../howto/cgi.html">Dynamic Content With CGI</a>.</p>
|
|
|
|
<p>When using a multi-threaded MPM under unix, the module <a
|
|
href="mod_cgid.html">mod_cgid</a> should be used in place of this
|
|
module. At the user level, the two modules are essentially
|
|
identical.</p>
|
|
|
|
<h2>Directives</h2>
|
|
|
|
<ul>
|
|
<li><a href="#scriptlog">ScriptLog</a></li>
|
|
<li><a href="#scriptloglength">ScriptLogLength</a></li>
|
|
<li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li>
|
|
</ul>
|
|
|
|
<p>See also: <a href="core.html#options">Options</a>, <a
|
|
href="mod_alias.html#scriptalias">ScriptAlias</a>, <a
|
|
href="mod_mime.html#addtype">AddType</a> and <a
|
|
href="mod_mime.html#addhandler">AddHandler</a>.
|
|
|
|
<H2>CGI Environment variables</H2>
|
|
The server will set the CGI environment variables as described in the
|
|
<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI specification</A>, with the
|
|
following provisions:
|
|
<DL>
|
|
<DT>REMOTE_HOST
|
|
<DD>This will only be set if <A HREF="core.html#hostnamelookups"><CODE>HostnameLookups</CODE></A>
|
|
is set to <CODE>on</CODE> (it is off by default), and if a reverse DNS
|
|
lookup of the accessing host's address indeed finds a host name.
|
|
<DT>REMOTE_IDENT
|
|
<DD>This will only be set if
|
|
<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <CODE>on</CODE>
|
|
and the accessing host supports the ident protocol. Note that the contents
|
|
of this variable cannot be relied upon because it can easily be faked, and if
|
|
there is a proxy between the client and the server, it is usually
|
|
totally useless.
|
|
<DT>REMOTE_USER
|
|
<DD>This will only be set if the CGI script is subject to authentication.
|
|
</DL>
|
|
<P>
|
|
|
|
<H2><A NAME="cgi_debug">CGI Debugging</A></H2>
|
|
|
|
Debugging CGI scripts has traditionally been difficult, mainly because
|
|
it has
|
|
not
|
|
been possible to study the output (standard output and error) for
|
|
scripts
|
|
which are failing to run properly. These directives, included in
|
|
Apache 1.2 and later, provide
|
|
more detailed logging of errors when they occur.
|
|
|
|
<H2>CGI Logfile Format</H2>
|
|
|
|
When configured, the CGI error log logs any CGI which does not execute
|
|
properly. Each CGI script which fails to operate causes several lines
|
|
of information to be logged. The first two lines are always of the
|
|
format:
|
|
|
|
<PRE>
|
|
%% [<EM>time</EM>] <EM>request-line</EM>
|
|
%% <EM>HTTP-status</EM> <EM>CGI-script-filename</EM>
|
|
</PRE>
|
|
|
|
If the error is that CGI script cannot be run, the log file will
|
|
contain
|
|
an extra two lines:
|
|
|
|
<PRE>
|
|
%%error
|
|
<EM>error-message</EM>
|
|
</PRE>
|
|
|
|
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:
|
|
|
|
<PRE>
|
|
%request
|
|
<EM>All HTTP request headers received</EM>
|
|
<EM>POST or PUT entity (if any)</EM>
|
|
%response
|
|
<EM>All headers output by the CGI script</EM>
|
|
%stdout
|
|
<EM>CGI standard output</EM>
|
|
%stderr
|
|
<EM>CGI standard error</EM>
|
|
</PRE>
|
|
|
|
(The %stdout and %stderr parts may be missing if the script did not
|
|
output
|
|
anything on standard output or standard error).
|
|
|
|
<HR>
|
|
|
|
<H3><A NAME="scriptlog">ScriptLog</A> directive</H3>
|
|
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ScriptLog <EM>filename</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> none<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> mod_cgi
|
|
<P>
|
|
|
|
The <TT>ScriptLog</TT> 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>This log will be opened as the user the child processes run as,
|
|
ie. the user specified in the main <A HREF="core.html#User">User</A>
|
|
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>
|
|
|
|
<hr>
|
|
|
|
<H3><A NAME="scriptloglength">ScriptLogLength</A> directive</H3>
|
|
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ScriptLogLength <EM>bytes</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> 10385760<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> mod_cgi
|
|
<P>
|
|
|
|
<TT>ScriptLogLength</TT> 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.
|
|
|
|
<hr>
|
|
|
|
<H3><A NAME="scriptlogbuffer">ScriptLogBuffer</A></H3>
|
|
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ScriptLogBuffer <EM>bytes</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> 1024<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> mod_cgi
|
|
<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.
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|
|
|