manual/mod/mod_log_config.html

	mod_log_config.html revision a902ab8fc247cc32dda1479e9c069f59aa22a6e1
03831d35f7499c87d51205817c93e9a8d42c4baestevel<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
03831d35f7499c87d51205817c93e9a8d42c4baestevel<HTML>
03831d35f7499c87d51205817c93e9a8d42c4baestevel<HEAD>
03831d35f7499c87d51205817c93e9a8d42c4baestevel<TITLE>Apache module mod_log_config</TITLE>
03831d35f7499c87d51205817c93e9a8d42c4baestevel</HEAD>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<BODY>
03831d35f7499c87d51205817c93e9a8d42c4baestevel<!--#include virtual="header.html" -->
03831d35f7499c87d51205817c93e9a8d42c4baestevel<H1>Module mod_log_config</h1>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevelThis module is contained in the <code>mod_log_config.c</code> file,
03831d35f7499c87d51205817c93e9a8d42c4baesteveland is compiled in by default in Apache 1.2. mod_log_config replaces
03831d35f7499c87d51205817c93e9a8d42c4baestevelmod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
03831d35f7499c87d51205817c93e9a8d42c4baestevelan optional module. It provides for logging of the requests made to
03831d35f7499c87d51205817c93e9a8d42c4baestevelthe server, using the Common Log Format or a user-specified format.
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<h2>Summary</h2>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevelThree directives are provided by this module: <code>TransferLog</code>
03831d35f7499c87d51205817c93e9a8d42c4baestevelto create a log file, <code>LogFormat</code> to set a custom format,
03831d35f7499c87d51205817c93e9a8d42c4baesteveland <code>CustomLog</code> to define a log file and format in one go.
03831d35f7499c87d51205817c93e9a8d42c4baestevelThe <code>TransferLog</code> and <code>CustomLog</code> directives can
24fe0b3bf671e123467ce1df0b67cadd3614c8e4jmcpbe use multiple times in each server to cause each request to be
03831d35f7499c87d51205817c93e9a8d42c4baestevellogged to multiple files.
03831d35f7499c87d51205817c93e9a8d42c4baestevel<P>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<h3>Compatibility notes</h3>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<ul>
03831d35f7499c87d51205817c93e9a8d42c4baestevel<li>This module is based on mod_log_config distributed with
03831d35f7499c87d51205817c93e9a8d42c4baestevelprevious Apache releases, now updated to handle multiple logs.
03831d35f7499c87d51205817c93e9a8d42c4baestevelThere is now no need to re-configure Apache to get use
03831d35f7499c87d51205817c93e9a8d42c4baestevelconfiguration log formats.
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<li>The module also implements the <code>CookieLog</code> directive,
03831d35f7499c87d51205817c93e9a8d42c4baestevelused to log user-tracking information created by <a
03831d35f7499c87d51205817c93e9a8d42c4baestevelhref="mod_usertrack.html">mod_usertrack</a>. The use of
03831d35f7499c87d51205817c93e9a8d42c4baestevel<code>CookieLog</code> is deprecated, and a <code>CustomLog</code>
03831d35f7499c87d51205817c93e9a8d42c4baestevelshould be defined to log user-tracking information instead.
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel</ul>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<h2>Log File Formats</h2>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevelUnless told otherwise with <tt>LogFormat</tt> the log files created by
03831d35f7499c87d51205817c93e9a8d42c4baestevel<tt>TransferLog</tt> will be in standard "Common Log Format"
03831d35f7499c87d51205817c93e9a8d42c4baestevel(CLF). The contents of each line in a CLF file are explained
03831d35f7499c87d51205817c93e9a8d42c4baestevelbelow. Alternatively, the log file can be customised (and if multiple
03831d35f7499c87d51205817c93e9a8d42c4baestevellog files are used, each can have a different format). Custom formats
03831d35f7499c87d51205817c93e9a8d42c4baestevelare set with <code>LogFormat</code> and <code>CustomLog</code>.
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<h3>Common Log Format</h3>
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevelThe Common Log Format (CLF) file contains a separate line for each
03831d35f7499c87d51205817c93e9a8d42c4baestevelrequest. A line is composed of several tokens separated by spaces:
03831d35f7499c87d51205817c93e9a8d42c4baestevel
03831d35f7499c87d51205817c93e9a8d42c4baestevel<blockquote>
03831d35f7499c87d51205817c93e9a8d42c4baestevelhost ident authuser date request status bytes
03831d35f7499c87d51205817c93e9a8d42c4baestevel</blockquote>
03831d35f7499c87d51205817c93e9a8d42c4baestevelIf a token does not have a value then it is represented by a hyphen (-).
03831d35f7499c87d51205817c93e9a8d42c4baestevelThe meanings and values of these tokens are as follows:
03831d35f7499c87d51205817c93e9a8d42c4baestevel<dl>
03831d35f7499c87d51205817c93e9a8d42c4baestevel<dt>host
48bc00d6814e04ff3edb32cafe7d1bc580baff68jmcp<dd>The fully-qualified domain name of the client, or its IP number if the
03831d35f7499c87d51205817c93e9a8d42c4baestevelname is not available.
03831d35f7499c87d51205817c93e9a8d42c4baestevel<dt>ident
03831d35f7499c87d51205817c93e9a8d42c4baestevel<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
03831d35f7499c87d51205817c93e9a8d42c4baestevelclient machine runs identd, then this is the identity information reported
by the client.
<dt>authuser
<dd>If the request was for an password protected document, then this is
the userid used in the request.
<dt>date
<dd>The date and time of the request, in the following format:
<dl><dd><blockquote><code> date = [day/month/year:hour:minute:second zone] <br>
day = 2*digit<br>
month = 3*letter<br>
year = 4*digit<br>
hour = 2*digit<br>
minute = 2*digit<br>
second = 2*digit<br>
zone = (`+' | `-') 4*digit</code></blockquote></dl>
<dt>request
<dd>The request line from the client, enclosed in double quotes
(<code>&quot;</code>).
<dt>status
<dd>The three digit status code returned to the client.
<dt>bytes
<dd>The number of bytes in the object returned to the client, not including
any headers.
</dl>

<h3>Custom Log Formats</h3>

The format argument to the <code>LogFormat</code> and
<code>CustomLog</code> is a string. This string is logged to the log
file for each request. It can contain literal characters copied into
the log files, and `%' directives which are replaced in the log file
by the values as follows:

<PRE>
%...b:          Bytes sent.
%...f:          Filename
%...h:          Remote host
%...l:          Remote logname (from identd, if supplied)
%...p:          The port request was received on
%...P:          The process ID of the child that serviced the request
%...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.
%...t:          Time, in common log format time format
%...T:          The time taken to serve the request, in seconds
%...u:          Remote user (from auth; may be bogus if return
                status (%s) is 401)
%...U:          The URL path requested
%...v:          The name of the server (i.e. which virtual host)
%...{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.
%...{Foobar}n:  The contents of note "Foobar" from another module
</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>

Note that the common log format is defined by the string <code>"%h %l
%u %t \"%r\" %s %b"</code>, which can be used as the basis for
extending for format if desired (e.g. to add extra fields at the end).

<h2>Using Multiple Log Files</h3>

The <code>TransferLog</code> and <code>CustomLog</code> directives can
be given more than once to log requests to multiple log files. Each
request will be logged to all the log files defined by either of these
directives.

<h3>Use with Virtual Hosts</h3>

If a &lt;VirtualHost&gt; 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>

<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>
</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>
<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> Base<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> Base<br>
<strong>Module:</strong> mod_log_config<p>

The TransferLog directive adds a log file in Common Log Format.
<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>


<!--#include virtual="footer.html" -->
</BODY>
</HTML>