From c1a02e3595cb183a10d6dfbf5d159c0f10775958 Mon Sep 17 00:00:00 2001
From: Alexei Kosut <akosut@apache.org>
Date: Thu, 28 Nov 1996 07:42:17 +0000
Subject: [PATCH] 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
---
 docs/manual/mod/core.html           |  58 +++++++++---
 docs/manual/mod/directives.html     |  10 +-
 docs/manual/mod/mod_cgi.html        | 136 +++++++++++++++++++++-------
 docs/manual/mod/mod_log_config.html |  50 ++++++----
 docs/manual/mod/mod_usertrack.html  |  74 ++++++++++++---
 5 files changed, 248 insertions(+), 80 deletions(-)

diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html
index 9c530b7d3d..6d8af1fea2 100644
--- a/docs/manual/mod/core.html
+++ b/docs/manual/mod/core.html
@@ -14,28 +14,26 @@ always available.
 
 
 <ul>
-<LI> <A HREF="#sendbuffersize>SendBufferSize</A>
-<LI> <A HREF="#files">&lt;Files&gt;</A>
-<LI> <A HREF="#ifmodule">&lt;IfModule%gt;</A>
-<LI> Satisfy
-<LI> RLimitCPU
-<LI> RLimitMEM
-<LI> RLimitNPROC
-<LI> AddModule
-<LI> ClearModuleList
+<li>RLimitCPU
+<li>RLimitMEM
+<li>RLimitNPROC
 <li><A HREF="#accessconfig">AccessConfig</A>
 <li><A HREF="#accessfilename">AccessFileName</A>
+<li>AddModule
 <li><A HREF="#allowoverride">AllowOverride</A>
 <li><A HREF="#authname">AuthName</A>
 <li><A HREF="#authtype">AuthType</A>
 <li><A HREF="#bindaddress">BindAdress</A>
+<li>ClearModuleList
 <li><A HREF="#defaulttype">DefaultType</A>
 <li><A HREF="#directory">&lt;Directory&gt;</A>
 <li><A HREF="#documentroot">DocumentRoot</A>
 <li><A HREF="#errordocument">ErrorDocument</A>
 <li><A HREF="#errorlog">ErrorLog</A>
+<li><A HREF="#files">&lt;Files&gt;</A>
 <li><A HREF="#group">Group</A>
 <li><A HREF="#identitycheck">IdentityCheck</A>
+<li><A HREF="#ifmodule">&lt;IfModule%gt;</A>
 <li><A HREF="#keepalive">KeepAlive</A>
 <li><A HREF="#keepalivetimeout">KeepAliveTimeout</A>
 <li><A HREF="#limit">&lt;Limit&gt;</A>
@@ -50,6 +48,8 @@ always available.
 <li><A HREF="#port">Port</A>
 <li><A HREF="#require">require</A>
 <li><A HREF="#resourceconfig">ResourceConfig</A>
+<li>Satisfy
+<li><A HREF="#sendbuffersize>SendBufferSize</A>
 <li><A HREF="#serveradmin">ServerAdmin</A>
 <li><A HREF="#serveralias">ServerAlias</A>
 <li><A HREF="#servername">ServerName</A>
@@ -87,12 +87,42 @@ which match the regexp.
 <p> <hr>
 
 <A NAME="ifmodule"><H2>&lt;IfModule&gt;</H2></A>
-<STRONG>Syntax:</STRONG> &lt;IfModule <em>modulename</em>&gt;<BR>
-<STRONG>Context:</STRONG> server config, virtual host, directory<BR>
-<STRONG>Status:</STRONG> core<p>
+<b>Syntax:</b> &lt;IfModule [!]<i>module-name</i>&gt; <i>...</i>
+&lt;/IfModule&gt;<br>
+<b>Default:</b> None<br>
+<b>Context:</b> all<br>
+<b>Status:</b> Core
+<strong>Compatibility:</strong> ScriptLog is only available in 1.2 and
+later.<P>
 
-Directives within the &lt;IfModule&gt; container are activated
-if the specified module is configured into the server.
+<p>
+
+The &lt;IfModule <i>test</i>&gt;...&lt;/IfModule&gt;
+section is used to mark directives that are conditional. The
+directives within an IfModule section are only
+processed if the <i>test</i> is true. If <i>test</i>
+is false, everything between the start and end markers
+is ignored.<p>
+
+The <i>test</i> in the &lt;IfModule&gt; section directive
+can be one of two forms:
+
+<ul>
+<li><i>module name</i>
+<li>!<i>module name</i>
+</ul>
+
+<p>In the former case, the directives between the start and end markers
+are only processed if the module named <i>module name</i> is compiled
+in to Apache. The second format reverses the test, and only processes
+the directives if <i>module name</i> is <b>not</b> compiled in.
+
+<p>The <i>module name</i> argument is a module name as given as the file
+name of the module, at the time it was compiled. For example,
+<code>mod_rewrite.c</code>.
+
+<p>&lt;IfModule&gt; sections are nestable, which can be used to implement
+simple multiple-module tests.
 
 <P> <hr>
 
diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html
index 6a14a901f3..01e2eaa966 100644
--- a/docs/manual/mod/directives.html
+++ b/docs/manual/mod/directives.html
@@ -46,7 +46,10 @@
 <li><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A>
 <li><A HREF="mod_proxy.html#cacheroot">CacheRoot</A>
 <li><A HREF="mod_proxy.html#cachesize">CacheSize</A>
-<li><A HREF="mod_cookies.html#cookielog">CookieLog</A>
+<li><A HREF="mod_cookies.html#cookielog">CookieLog</A> (mod_cookies)
+<li><A HREF="mod_log_config.html#cookielog">CookieLog</A> (mod_log_config)
+<li><A HREF="mod_usertrack.html#cookieenable">CookieEnable</A>
+<li><A HREF="mod_usertrack.html#cookieexpires">CookieExpires</A>
 <li><A HREF="mod_dir.html#defaulticon">DefaultIcon</A>
 <li><A HREF="core.html#defaulttype">DefaultType</A>
 <li><A HREF="mod_access.html#deny">deny</A>
@@ -56,11 +59,13 @@
 <li><A HREF="core.html#errordocument">ErrorDocument</A>
 <li><A HREF="core.html#errorlog">ErrorLog</A>
 <li><A HREF="mod_dir.html#fancyindexing">FancyIndexing</A>
+<li><A HREF="core.html#files">&lt;Files&gt;</A>
 <li><A HREF="mod_mime.html#forcetype">ForceType</A>
 <li><A HREF="core.html#group">Group</A>
 <li><A HREF="mod_headers.html#header">Header</A>
 <li><A HREF="mod_dir.html#headername">HeaderName</A>
 <li><A HREF="core.html#identitycheck">IdentityCheck</A>
+<li><A HREF="core.html#ifmodule">IfModule</A>
 <li><A HREF="mod_imap.html#imapbase">ImapBase</A>
 <li><A HREF="mod_imap.html#imapdefault">ImapDefault</A>
 <li><A HREF="mod_imap.html#imapmenu">ImapMenu</A>
@@ -98,6 +103,9 @@
 <li><A HREF="core.html#resourceconfig">ResourceConfig</A>
 <li><A HREF="mod_actions.html#script">Script</A>
 <li><A HREF="mod_alias.html#scriptalias">ScriptAlias</A>
+<li><A HREF="mod_cgi.html#scriptlog">ScriptLog</A>
+<li><A HREF="mod_cgi.html#scriptloglength">ScriptLogLength</A>
+<li><A HREF="mod_cgi.html#scriptlogbuffer">ScriptLogBufffer</A>
 <li><A HREF="core.html#serveradmin">ServerAdmin</A>
 <li><A HREF="core.html#serveralias">ServerAlias</A>
 <li><A HREF="core.html#servername">ServerName</A>
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>
diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html
index 19c47bc1f3..f381bf2867 100644
--- a/docs/manual/mod/mod_log_config.html
+++ b/docs/manual/mod/mod_log_config.html
@@ -165,13 +165,45 @@ See the examples below.
 <h2>Directives</h2>
 
 <ul>
+<li><A HREF="#cookielog">CookieLog</A>
+<LI><A HREF="#customlog">CustomLog</A>
 <li><A HREF="#logformat">LogFormat</A>
 <li><A HREF="#transferlog">TransferLog</A>
-<LI><A HREF="#customlog">CustomLog</A>
 </ul>
 <hr>
 
 
+<A name="cookielog"><h2>CookieLog</h2></A>
+<!--%plaintext &lt;?INDEX {\tt CookieLog} directive&gt; -->
+<strong>Syntax:</strong> CookieLog <em>filename</em><br>
+<Strong>Context:</strong> server config, virtual host<br>
+<strong>Module:</strong> mod_cookies<br>
+<strong>Compatibility:</strong> Only available in Apache 1.2 and above<p>
+
+The CookieLog directive sets the filename for logging of cookies.
+The filename is relative to the <A
+HREF="core.html#serverroot">ServerRoot</A>. This directive is included
+only for compatibility with <a
+href="mod_cookies.html">mod_cookies</a>, and is depreciated.
+<p>
+
+<A NAME="customlog"><H2>CustomLog</H2></A>
+<STRONG>Syntax:</STRONG> CustomLog <em>file-pipe</em> <em>format</em><BR>
+<STRONG>Context:</STRONG> server config, virtual host<BR>
+<STRONG>Status:</STRONG> Base<BR>
+<STRONG>Module:</STRONG> mod_log_config<P>
+
+The first argument is the filename to log to. This is used
+exactly like the argument to <tt>TransferLog</tt>, that is,
+it is either a full path, or relative to the current
+server root. <p>
+
+The format argument specifies a format for each line of the log file.
+The options available for the format are exactly the same as for
+the argument of the <tt>LogFormat</tt> directive. If the format
+includes any spaces (which it will do in almost all cases) it
+should be enclosed in double quotes.
+
 <A name="logformat"><h2>LogFormat</h2></A>
 <!--%plaintext &lt;?INDEX {\tt LogFormat} directive&gt; -->
 <strong>Syntax:</strong> LogFormat <em>string</em><br>
@@ -206,22 +238,6 @@ the TransferLog from the main server.
 run under the user who started httpd. This will be root if the server
 was started by root; be sure that the program is secure.<p>
 
-<A NAME="customlog"><H2>CustomLog</H2></A>
-<STRONG>Syntax:</STRONG> CustomLog <em>file-pipe</em> <em>format</em><BR>
-<STRONG>Context:</STRONG> server config, virtual host<BR>
-<STRONG>Status:</STRONG> Base<BR>
-<STRONG>Module:</STRONG> mod_log_config<P>
-
-The first argument is the filename to log to. This is used
-exactly like the argument to <tt>TransferLog</tt>, that is,
-it is either a full path, or relative to the current
-server root. <p>
-
-The format argument specifies a format for each line of the log file.
-The options available for the format are exactly the same as for
-the argument of the <tt>LogFormat</tt> directive. If the format
-includes any spaces (which it will do in almost all cases) it
-should be enclosed in double quotes.
 
 <!--#include virtual="footer.html" -->
 </BODY>
diff --git a/docs/manual/mod/mod_usertrack.html b/docs/manual/mod/mod_usertrack.html
index 1d3de03057..4c563f9d25 100644
--- a/docs/manual/mod/mod_usertrack.html
+++ b/docs/manual/mod/mod_usertrack.html
@@ -8,26 +8,70 @@
 <!--#include virtual="header.html" -->
 <H1>Module mod_usertrack</h1>
 
-This module is contained in the <code>mod_usertrack.c</code> file, and
-is not compiled in by default. It provides for user tracking using cookies.
-There is no documentation available for this module.  Mark is writing this.
+Previous releases of Apache have included a module which generates a
+'clickstream' log of user activity on a site, using cookies. This was
+called the "cookies" module, mod_cookies. In Apache 1.2 and later, this module
+has
+been renamed the "user tracking" module, mod_usertrack. This module
+has been
+simplified and new directives added.
 
-<menu>
-<li><A HREF="#cookielog">CookieLog</A>
-</menu>
 <hr>
 
+<h2>Logging</h2>
 
-<A name="cookielog"><h2>CookieLog</h2></A>
-<!--%plaintext &lt;?INDEX {\tt CookieLog} directive&gt; -->
-<strong>Syntax:</strong> CookieLog <em>filename</em><br>
-<Strong>Context:</strong> server config, virtual host<br>
-<strong>Status:</strong> Experimental<br>
-<strong>Module:</strong> mod_cookies<p>
+Previously, the cookies module (now the user tracking module) did its
+own logging, using the <tt>CookieLog</tt> directive. In this release,
+this module does no logging at all. Instead, a configurable log
+format file should be used to log user clickstreams. This is possible
+because the logging module now allows <a
+href="multilogs.html">multiple log files</a>. The cookie itself is
+logged by using the text <tt>%{cookie}n </tt>
+
+in the log file format. For example:
+<pre>
+CustomLog logs/clickstream "%{cookie}i %r %t"
+</pre>
+
+For backward compatibility the configurable log module implements the
+old <tt>CookieLog</tt> directive, but this should be upgrade to the
+above <tt>CustomLog</tt> directive.
+
+<h2>Directives</h2>
+
+<ul>
+<li><a href="#cookieenable">CookieEnable</a>
+<li><a href="#cookieexpires">CookieExpires</a>
+</ul>
+
+<hr>
+
+<a name="cookieexpires"><h2>CookieEnable</h2></A>
+<strong>Sytnax:</strong> CookieEnable <em>on | off</em><br>
+<strong>Context:</strong> server config, virtual host, directory,
+.htaccess<br>
+<strong>Override:</strong> FileInfo<br>
+<strong>Status:</strong> optional<br>
+<strong>Module:</strong> mod_usertrack<p>
+
+When the user track module is compiled in, Apache will start
+sending a user-tracking cookie for all new requests. This directive
+can be used to turn this behavior on or off on a per-server or
+per-directory basis.
+
+<a name="cookieexpires"><h2>CookieExpires</h2></A>
+<strong>Sytnax:</strong> CookieExpires <em>expiry-period</em><br>
+<strong>Context:</strong> server config, virtual host<br>
+<strong>Status:</strong> optional<br>
+<strong>Module:</strong> mod_usertrack<p>
+
+When used,
+this directive sets an expiry time on the cookie generated by the
+usertrack module. The <i>expiry-period</i> can be given either as a
+number of seconds, or in the format such as "2 weeks 3 days 7 hours".
+Valid denominations are: years, months, weeks, hours, minues and
+seconds.
 
-The CookieLog directive sets the filename for logging of cookies.
-The filename is relative to the <A HREF="core.html#serverroot">ServerRoot</A>.
-<p>
 
 <!--#include virtual="footer.html" -->
 </BODY>
-- 
2.50.1