<!--%hypertext -->
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<HTML>
<HEAD>
<TITLE>Apache module mod_log_config</TITLE>
</HEAD>

<BODY>
<IMG SRC="../images/apache_sub.gif" ALT="">
<!--/%hypertext -->
<H1>Module mod_log_config</h1>

This module is contained in the <code>mod_log_config.c</code> file, and is not
compiled in by default. It provides for logging of the requests made to
the server, using a user-specified format.

<h2>Summary</h2>
This is an EXPERIMENTAL module, which implements the TransferLog directive
(same as the common log module), and an additional directive, LogFormat.
Bugs would not surprise me.<P>

The argument to the <A HREF="#logformat">LogFormat</A> is a string, which can
include literal characters copied into the log files, and `%' directives as
follows:

<PRE>
%...h:          Remote host
%...l:          Remote logname (from identd, if supplied)
%...u:          Remote user (from auth; may be bogus if return 
                status (%s) is 401)
%...t:          Time, in common log format time format
%...r:          First line of request
%...s:          Status.  For requests that got internally redirected, 
                this is status of the <b>original</b> request --- %...>s 
                for the last.
%...b:          Bytes sent.
%...{Foobar}i:  The contents of Foobar: header line(s) in the request
                sent to the client.
%...{Foobar}o:  The contents of Foobar: header line(s) in the reply.
</PRE>

The `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can
indicate conditions for inclusion of the item (which will cause it
to be replaced with `-' if the condition is not met).  Note that
there is no escaping performed on the strings from %r, %...i and
%...o; some with long memories may remember that I thought this was
a bad idea, once upon a time, and I'm still not comfortable with
it, but it is difficult to see how to `do the right thing' with all
of `%..i', unless we URL-escape everything and break with CLF.

<P>

The forms of condition are a list of HTTP status codes, which may
or may not be preceded by `!'.  Thus, `%400,501{User-agent}i' logs
User-agent: on 400 errors and 501 errors (Bad Request, Not
Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all
requests which did <b>not</b> return some sort of normal status.

<P>

The default LogFormat reproduces CLF; see below.

<P>

The way this is supposed to work with virtual hosts is as follows:
a virtual host can have its own LogFormat, or its own TransferLog.
If it doesn't have its own LogFormat, it inherits from the main
server.  If it doesn't have its own TransferLog, it writes to the
same descriptor (meaning the same process for `| ...').

<P>

That means that you can do things like:

<blockquote><code>
&lt;VirtualHost hosta.com&gt;<br>
LogFormat "hosta ..."<br>
...<br>
&lt;/VirtualHost&gt;<br>
<br>
&lt;VirtualHost hosta.com&gt;<br>
LogFormat "hostb ..."<br>
...<br>
&lt;/VirtualHost&gt;</code></blockquote>

... to have different virtual servers write into the same log file,
but have some indication which host they came from, though a %v
directive may well be a better way to handle this.  Look for more
changes to come to this format.<p>


<!--%hypertext -->

<h2>Directives</h2>

<ul>
<li><A HREF="#logformat">LogFormat</A>
<li><A HREF="#transferlog">TransferLog</A>
</ul>
<hr>
<!--/%hypertext -->

<A name="logformat"><h2>LogFormat</h2></A>
<!--%plaintext &lt;?INDEX {\tt LogFormat} directive&gt; -->
<strong>Syntax:</strong> LogFormat <em>string</em><br>
<strong>Default:</strong> <code>LogFormat &quot;%h %l %u %t \&quot;%r\&quot;
%s %b&quot;</code><br>
<Strong>Context:</strong> server config, virtual host<br>
<strong>Status:</strong> Experimental<br>
<strong>Module:</strong> mod_log_config<p>

This sets the format of the logfile.<p><hr>


<A name="transferlog"><h2>TransferLog</h2></A>
<!--%plaintext &lt;?INDEX {\tt TransferLog} directive&gt; -->
<strong>Syntax:</strong> TransferLog <em>file-pipe</em><br>
<strong>Default:</strong> <code>TransferLog logs/transfer_log</code><br>
<Strong>Context:</strong> server config, virtual host<br>
<strong>Status:</strong> Experimental<br>
<strong>Module:</strong> mod_log_config<p>

The TransferLog directive sets the name of the file to which the server will
log the incoming requests. <em>File-pipe</em> is one
of
<dl><dt>A filename
<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>.
<dt> `|' followed by a command
<dd>A program to receive the agent log information on its standard input.
Note the a new program will not be started for a VirtualHost if it inherits
the TransferLog from the main server.
</dl>
<strong>Security:</strong> if a program is used, then it will be
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>

<!--%hypertext -->
<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>
<!--/%hypertext -->