Some cleanup (the directives go in ALPHABETICAL ORDER, please), plus

adding of some docs that Paul Sutton sent to the list on October
10th.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@77082 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 103 insertions, 33 deletions

diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html
index 44d0d3e90a..425b7e7c6a 100644
--- a/docs/manual/mod/mod_cgi.html
+++ b/docs/manual/mod/mod_cgi.html
@@ -19,6 +19,7 @@ processed by this module.
 
 <h2>Summary</h2>
 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 ending in an extension defined by the
@@ -45,41 +46,110 @@ specification, with the following provisos:
 </dl>
 <P>
 
+<hr>
+
+<a name="cgi_debug"><h2>CGI Debugging</h2></a>
+
+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.
+
+<hr>
+
+<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>
+  %% [<i>time</i>] <i>request-line</i>
+  %% <i>HTTP-status</i> <i>CGI-script-filename</i>
+</pre>
+
+If the error is the that CGI script cannot be run, the log file will
+contain
+an extra two lines:
+
+<pre>
+  %%error
+  <i>error-message</i>
+</pre>
+
+Alternatively, if the error is the result of the script returning the
+incorrect header information (often due to a bug in the script), the
+following information is logged:
+
+<pre>
+  %request
+  <i>All HTTP request headers received</i>
+  <i>POST or PUT entity (if any)</i>
+  %response
+  <i>All headers output by the CGI script</i>
+  %stdout
+  <i>CGI standard output</i>
+  %stderr
+  <i>CGI standard error</i>
+</pre>
+
+(The %stdout and %stderr parts may  be missing if the script did not
+output
+anything on standard output or standard error).
+
+<hr>
+
 <h2>Directives</h2>
-<ul>
-<li><A HREF="#scriptlog">ScriptLog</A>
-<li><A HREF="#scriptloglength">ScriptLogLength</A>
-<li><A HREF="#scriptlogbuff">ScriptLogBuffer</A>
-</ul>
-
-<A NAME="scriptlog"><H2>ScriptLog</H2></A>
-
-<STRONG>Syntax:</STRONG> ScriptLog <EM>filename</EM><BR>
-<STRONG>Context:</STRONG> server config, virtualhost<BR>
-<STRONG>Status:</STRONG> Base<BR>
-<STRONG>Module:</STRONG> mod_cgi<BR>
-<STRONG>Compatibility:</STRONG> ScriptLog is only available in 1.2 and
-later.<P>
-
-<A NAME="scriptloglength"><H2>ScriptLogLength</H2></A>
-
-<STRONG>Syntax:</STRONG> ScriptLogLength <EM>size-bytes</EM><BR>
-<STRONG>Context:</STRONG> server config, virtualhost<BR>
-<STRONG>Status:</STRONG> Base<BR>
-<STRONG>Module:</STRONG> mod_cgi<BR>
-<STRONG>Default:</STRONG> ScriptLogLength 10385760<BR>
-<STRONG>Compatibility:</STRONG> ScriptLogLength is only available in 1.2 and
-later.<P>
-
-<A NAME="scriptlogbuff"><H2>ScriptLogBuffer</H2></A>
-<STRONG>Syntax:</STRONG> ScriptLogBuffer <EM>size-bytes</EM><BR>
-<STRONG>Context:</STRONG> server config, virtualhost<BR>
-<STRONG>Status:</STRONG> Base<BR>
-<STRONG>Module:</STRONG> mod_cgi<BR>
-<STRONG>Default:</STRONG> ScriptLogBuffer 1024<BR>
-<STRONG>Compatibility:</STRONG> ScriptLogBuffer is only available in 1.2 and
-later.<P>
 
+<a name="scriptlog"><h3>ScriptLog</h3></a>
+
+<b>Syntax:</b> ScriptLog <i>filename</i><br>
+<b>Default:</b> none<br>
+<b>Context:</b> resource config<br>
+<b>Status:</b> 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.
+
+<a name="scriptloglength"><h3>ScriptLogLength</h3></a>
+
+<b>Syntax:</b> ScriptLogLength <i>size</i><br>
+<b>Default:</b> 10385760<br>
+<b>Context:</b> resource config<br>
+<b>Status:</b> 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 filesize for the CGI logfile. If the file
+exceeds this size, no more information will be written to it.
+
+<a name="scriptlogbuffer"><h3>ScriptLogBuffer</h3></a>
+
+<b>Syntax:</b> ScriptLogBuffer <i>size</i><br>
+<b>Default:</b> 1024<br>
+<b>Context:</b> resource config<br>
+<b>Status:</b> mod_cgi
+<p>
+
+The size of any PUR 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>