On Tue, 8 Oct 1996, Alexei Kosut wrote:
> I've begun to write documentation for Apache 1.2. I made an index page
> at http://www.apache.org/docs/1.2/, and put in most of the new
> features in 1.2. This is based on a list that Paul gave us a few weeks
> ago, and some of the newer stuff isn't there (like deny user-agent,
> and other stuff). At some point, most of those entries should be
> linked to pages. I'll be writing some of them (mostly for the stuff I
> wrote), but if other people wanted to, that'd be dandy.
A while ago (when I wrote the original message) I made a start of
documenting some of the bits. There didn't seem to be much interest in
documentation though, so I didn't submit them. But they might be useful.
So here are my documents for: <IfModule>, ScriptLogXXX, multiple log
file/CustomLog and usertrack module/CookieXXX.
Paul
=================================================================
<html><head>
<title>Apache Conditional Directives</title>
</head><body>
<img src="../images/apache_sub.gif" alt="">
<h1>Apache Conditional Directives</h1>
When Apache reads the configuration files, any unknown directives
cause an immediate error message and termination. However there
are times when it is preferable to ignore unknown directives. Since
directives are defined by modules, Apache provides a means of ignoring
directives based on whether particular modules have been compiled in.
<hr>
<h3>IfModule</h3>
<b>Syntax:</b> <IfModule [!]<i>module-name</i>> <i>...</i>
</IfModule><br>
<b>Default:</b> None<br>
<b>Context:</b> all<br>
<b>Status:</b> Core
<p>
The <IfModule <i>test</i>>...</IfModule>
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 <IfModule> section directive
can be one of two forms:
<ul>
<li><i>module name</i>
<li>! <i>module name</i>
</ul>
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 first
argument to the <b>Module</b> command in the Configuration file. Care
should be taken to spell the module name exactly as given in the
Configuration file.<p>
<IfModule> sections are nestable, which can be used to implement
simple multiple-module tests.
<hr>
<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
<A HREF="../"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
</BODY>
</HTML>
=======================================================================
<html><head>
<title>Apache CGI Debugging</title>
</head><body>
<img src="../images/apache_sub.gif" alt="">
<h1>CGI Debugging</h1>
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 new directives allow much 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 severl 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).
<h2>Directives</h2>
<h3>ScriptLog</h3>
<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.
<h3>ScriptLogLength</h3>
<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.
<h3>ScriptLogBuffer</h3>
<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, uup to 1024 bytes are logged,
but this can be changed with this directive.
<hr>
<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
<A HREF="../"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
</BODY>
</HTML>
=======================================================================
<html><head>
<title>Apache Multiple Log Files</title>
</head><body>
<img src="../images/apache_sub.gif" alt="">
<h1>Multiple Log Files</h1>
It is now possible to specify multiple log files, each with a fully
customisable format. This is fully compatible with existing configurations.
<hr>
<h2>Using Multiple Log Files</h2>
Multiple log files be created with either the <tt>TransferLog</tt>
or <tt>CustomLog</tt> directive. These directives can be
repeated, to create more than one log file (in previous releases,
only one logfile could be given per server configuration).
The <tt>TransferLog</tt> directive creates a log file
in the standard "common log format", although this can be customised
with <tt>LogFormat</tt>. The syntax of these two
directives is the same as for the config log module in previous
Apache releases.
<p>
The real power of multiple log files come from the ability to
create log files in different formats. For example, as well
as a CLF transfer log, the server could log the user agent of
each client, or the referer information, or any other aspect of
the request, such as the language preferences of the user.
<p>
The <tt>CustomLog</tt> directive takes both a filename to log
to, and a log file format.
<hr>
<strong>Sytnax:</strong> CustomLog <em>filename "format"</em><br>
<strong>Context:</strong> server config<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.
<p>
<h3>Use with Virtual Hosts</h3>
If a <VirtualHost> section does not contain any
<tt>TransferLog</tt> or <tt>CustomLog</tt> directives, the
logs defined for the main server will be used. If it does
contain one or more of these directives, requests serviced by
this virtual host will only be logged in the log files defined
within its definition, not in any of the main server's log files.
See the examples below.
<p>
<hr>
<h3>Examples</h3>
To create a normal (CLF) format log file in logs/access_log, and a
log of user agents:
<pre>
TransferLog logs/access_log
CustomLog logs/agents "%{user-agent}i"
</pre>
To define a CLF transfer log and a referer log which log
all accesses to both the main server and a virtual host:
<pre>
TransferLog logs/access_log
CustomLog logs/referer "%{referer}i"
<VirtualHost>
DocumentRoot /whatever
ServerName my.virtual.host
</VirtualHost>
</pre>
Since no TransferLog or CustomLog directives appear inside the
<VirtualHost> section, any requests for this virtual host
will be logged in the main server's log files. If however the
directive
<pre>
TransferLog logs/vhost_access_log
</pre>
was added inside the virtual host definition, then accesses to this
virtual host will be logged in vhost_acces_log file (in common
log format), and <i>not</i> in logs/access_log or logs/referer.
<hr>
<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
<A HREF="../"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
</BODY>
</HTML>
=======================================================================
<html><head>
<title>Apache </title>
</head><body>
<img src="../images/apache_sub.gif" alt="">
<h1>User Track Module Changes</h1>
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, this module has
been renamed the "user tracking" module, mod_usertrack. This module has been
simplified and new directives added.
<hr>
<h2>Logging</h2>
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>
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.
<hr>
<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
<A HREF="../"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>
</BODY>
</HTML>
=======================================================================
