mirror of
https://github.com/apache/httpd.git
synced 2025-05-30 01:07:09 +03:00
ef5c47b59e
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@558718 13f79535-47bb-0310-9956-ffa450edef68
238 lines
9.4 KiB
XML
238 lines
9.4 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_cgi.xml.meta">
|
|
|
|
<name>mod_cgi</name>
|
|
<description>Execution of CGI scripts</description>
|
|
<status>Base</status>
|
|
<sourcefile>mod_cgi.c</sourcefile>
|
|
<identifier>cgi_module</identifier>
|
|
|
|
<summary>
|
|
<!-- XXX: Should mention Options ExecCGI
|
|
is the link to howto/cgi not sufficient? -nd
|
|
-->
|
|
|
|
<p>Any file that has the handler
|
|
<code>cgi-script</code> will be treated
|
|
as a CGI script, and run by the server, with its output being
|
|
returned to the client. Files acquire this handler either by
|
|
having a name containing an extension defined by the
|
|
<directive module="mod_mime">AddHandler</directive> directive, or by being
|
|
in a <directive module="mod_alias">ScriptAlias</directive>
|
|
directory.</p>
|
|
|
|
<p>For an introduction 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
|
|
<module>mod_cgid</module> should be used in place of
|
|
this module. At the user level, the two modules are essentially
|
|
identical.</p>
|
|
|
|
<p>For backward-compatibility, the cgi-script handler will also be activated
|
|
for any file with the mime-type <code>application/x-httpd-cgi</code>. The
|
|
use of the magic mime-type is deprecated.</p>
|
|
</summary>
|
|
|
|
<seealso><directive module="core">AcceptPathInfo</directive></seealso>
|
|
<seealso><directive module="core">Options</directive></seealso>
|
|
<seealso><directive module="mod_alias">ScriptAlias</directive></seealso>
|
|
<seealso><directive module="mod_mime">AddHandler</directive></seealso>
|
|
<seealso><a href="../suexec.html">Running CGI programs under different
|
|
user IDs</a></seealso>
|
|
<seealso><a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI Specification</a></seealso>
|
|
|
|
<section id="env"><title>CGI Environment variables</title>
|
|
<p>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:</p>
|
|
|
|
<dl>
|
|
<dt>PATH_INFO</dt>
|
|
|
|
<dd>This will not be available if the <directive module="core"
|
|
>AcceptPathInfo</directive> directive is explicitly set to
|
|
<code>off</code>. The default behavior, if <directive
|
|
>AcceptPathInfo</directive> is not given, is that <module
|
|
>mod_cgi</module> will accept path info (trailing <code>
|
|
/more/path/info</code> following the script filename in the URI),
|
|
while the core server will return a 404 NOT FOUND error for requests
|
|
with additional path info. Omitting the <directive
|
|
>AcceptPathInfo</directive> directive has the same effect as setting
|
|
it <code>On</code> for <module>mod_cgi</module> requests.</dd>
|
|
|
|
<dt>REMOTE_HOST</dt>
|
|
|
|
<dd>This will only be set if <directive module="core"
|
|
>HostnameLookups</directive> 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.</dd>
|
|
|
|
<dt>REMOTE_IDENT</dt>
|
|
|
|
<dd>This will only be set if <directive module="core"
|
|
>IdentityCheck</directive> 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.</dd>
|
|
|
|
<dt>REMOTE_USER</dt>
|
|
|
|
<dd>This will only be set if the CGI script is subject to
|
|
authentication.</dd>
|
|
</dl>
|
|
</section>
|
|
|
|
<section id="cgi-debug"><title>CGI Debugging</title>
|
|
<p>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.</p>
|
|
|
|
<section><title>CGI Logfile Format</title>
|
|
<p>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:</p>
|
|
|
|
<example>
|
|
%% [<var>time</var>] <var>request-line</var><br />
|
|
%% <var>HTTP-status</var> <var>CGI-script-filename</var>
|
|
</example>
|
|
|
|
<p>If the error is that CGI script cannot be run, the log file
|
|
will contain an extra two lines:</p>
|
|
|
|
<example>
|
|
%%error<br />
|
|
<var>error-message</var>
|
|
</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 />
|
|
<var>All HTTP request headers received</var><br />
|
|
<var>POST or PUT entity (if any)</var><br />
|
|
%response<br />
|
|
<var>All headers output by the CGI script</var><br />
|
|
%stdout<br />
|
|
<var>CGI standard output</var><br />
|
|
%stderr<br />
|
|
<var>CGI standard error</var><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 <var>file-path</var></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</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 <directive>ScriptLog</directive> 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 <directive module="core">ServerRoot</directive>.
|
|
</p>
|
|
|
|
<example><title>Example</title>
|
|
ScriptLog logs/cgi_log
|
|
</example>
|
|
|
|
<p>This log will be opened as the user the child processes run
|
|
as, <em>i.e.</em> 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 <var>bytes</var></syntax>
|
|
<default>ScriptLogLength 10385760</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</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 <var>bytes</var></syntax>
|
|
<default>ScriptLogBuffer 1024</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</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>
|