mod_log_config.html revision 3d76f0e292da6a107829fbe83f98b8c0985c6ddb
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<!--%hypertext -->
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<HTML>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<HEAD>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<TITLE>Apache module mod_log_config</TITLE>
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner</HEAD>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<BODY>
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chin<IMG SRC="/images/apache_sub.gif" ALT="">
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<!--/%hypertext -->
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<H1>Module mod_log_config</h1>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis module is contained in the <code>mod_log_config.c</code> file, and is not
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincompiled in by default. It provides for logging of the requests made to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe server, using a user-specified format.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<h2>Summary</h2>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis is an EXPERIMENTAL module, which implements the TransferLog directive
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(same as the common log module), and an additional directive, LogFormat.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinBugs would not surprise me.<P>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe argument to the <A HREF="#logformat">LogFormat</A> is a string, which can
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininclude literal characters copied into the log files, and `%' directives as
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfollows:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<PRE>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...h: Remote host
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...l: Remote logname (from identd, if supplied)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...u: Remote user (from auth; may be bogus if return
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin status (%s) is 401)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...t: Time, in common log format time format
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...r: First line of request
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...s: Status. For requests that got internally redirected,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin this is status of the <b>original</b> request --- %...>s
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin for the last.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...b: Bytes sent.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...{Foobar}i: The contents of Foobar: header line(s) in the request
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin sent to the client.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin</PRE>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinindicate conditions for inclusion of the item (which will cause it
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto be replaced with `-' if the condition is not met). Note that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthere is no escaping performed on the strings from %r, %...i and
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin%...o; some with long memories may remember that I thought this was
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china bad idea, once upon a time, and I'm still not comfortable with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinit, but it is difficult to see how to `do the right thing' with all
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinof `%..i', unless we URL-escape everything and break with CLF.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<P>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe forms of condition are a list of HTTP status codes, which may
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinor may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinUser-agent: on 400 errors and 501 errors (Bad Request, Not
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinImplemented) only; `%!200,304,302{Referer}i' logs Referer: on all
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinrequests which did <b>not</b> return some sort of normal status.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<P>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe default LogFormat reproduces CLF; see below.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin<P>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe 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 -->