manual/mod/mod_log_config.html

	mod_log_config.html revision 4626d6d7ea118ca9df307c4a41a3c655a203a318
6a67d144095c31bbafed93cec1619590157335eajvergara<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
6a67d144095c31bbafed93cec1619590157335eajvergara<HTML>
6a67d144095c31bbafed93cec1619590157335eajvergara<HEAD>
6a67d144095c31bbafed93cec1619590157335eajvergara<TITLE>Apache module mod_log_config</TITLE>
6a67d144095c31bbafed93cec1619590157335eajvergara</HEAD>
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<BODY>
6a67d144095c31bbafed93cec1619590157335eajvergara<!--#include virtual="header.html" -->
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac<H1>Module mod_log_config</h1>
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac
6a67d144095c31bbafed93cec1619590157335eajvergaraThis module is contained in the <code>mod_log_config.c</code> file,
6a67d144095c31bbafed93cec1619590157335eajvergaraand is compiled in by default in Apache 1.2. mod_log_config replaces
6a67d144095c31bbafed93cec1619590157335eajvergaramod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
6a67d144095c31bbafed93cec1619590157335eajvergaraan optional module. It provides for logging of the requests made to
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignacthe server, using the Common Log Format or a user-specified format.
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac<h2>Summary</h2>
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac
6a67d144095c31bbafed93cec1619590157335eajvergaraThree directives are provided by this module: <code>TransferLog</code>
6a67d144095c31bbafed93cec1619590157335eajvergarato create a log file, <code>LogFormat</code> to set a custom format,
6a67d144095c31bbafed93cec1619590157335eajvergaraand <code>CustomLog</code> to define a log file and format in one go.
6a67d144095c31bbafed93cec1619590157335eajvergaraThe <code>TransferLog</code> and <code>CustomLog</code> directives can
6a67d144095c31bbafed93cec1619590157335eajvergarabe used multiple times in each server to cause each request to be
65e99be301d5a19db33f25841f671756e8dbb9b5ludovicplogged to multiple files.
6a67d144095c31bbafed93cec1619590157335eajvergara<P>
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<h3>Compatibility notes</h3>
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<ul>
6a67d144095c31bbafed93cec1619590157335eajvergara<li>This module is based on mod_log_config distributed with
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergaraprevious Apache releases, now updated to handle multiple logs.
6a67d144095c31bbafed93cec1619590157335eajvergaraThere is now no need to re-configure Apache to use configuration log
6a67d144095c31bbafed93cec1619590157335eajvergaraformats.
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<li>The module also implements the <code>CookieLog</code> directive,
6a67d144095c31bbafed93cec1619590157335eajvergaraused to log user-tracking information created by <a
6a67d144095c31bbafed93cec1619590157335eajvergarahref="mod_usertrack.html">mod_usertrack</a>. The use of
6a67d144095c31bbafed93cec1619590157335eajvergara<code>CookieLog</code> is deprecated, and a <code>CustomLog</code>
6a67d144095c31bbafed93cec1619590157335eajvergarashould be defined to log user-tracking information instead.
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara</ul>
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<h2>Log File Formats</h2>
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergaraUnless told otherwise with <tt>LogFormat</tt> the log files created by
6a67d144095c31bbafed93cec1619590157335eajvergara<tt>TransferLog</tt> will be in standard "Common Log Format"
2401d3c2af505789c7c3b860a43e973f27731243jvergara(CLF). The contents of each line in a CLF file are explained
2401d3c2af505789c7c3b860a43e973f27731243jvergarabelow. Alternatively, the log file can be customized (and if multiple
2401d3c2af505789c7c3b860a43e973f27731243jvergaralog files are used, each can have a different format). Custom formats
2401d3c2af505789c7c3b860a43e973f27731243jvergaraare set with <code>LogFormat</code> and <code>CustomLog</code>.
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<h3>Common Log Format</h3>
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergaraThe Common Log Format (CLF) file contains a separate line for each
6a67d144095c31bbafed93cec1619590157335eajvergararequest. A line is composed of several tokens separated by spaces:
6a67d144095c31bbafed93cec1619590157335eajvergara
6a67d144095c31bbafed93cec1619590157335eajvergara<blockquote>
c9d984b0d2c0fda320e79eb3868dd6fbeb1ffa34jvergarahost ident authuser date request status bytes
2401d3c2af505789c7c3b860a43e973f27731243jvergara</blockquote>
2401d3c2af505789c7c3b860a43e973f27731243jvergaraIf a token does not have a value then it is represented by a hyphen (-).
2401d3c2af505789c7c3b860a43e973f27731243jvergaraThe meanings and values of these tokens are as follows:
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergara<dl>
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergara<dt>host
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergara<dd>The fully-qualified domain name of the client, or its IP number if the
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergaraname is not available.
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergara<dt>ident
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergara<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
68c6568488f064ce97a76169ef43a8f5f7b1c2f6jvergaraclient machine runs identd, then this is the identity information reported
6a67d144095c31bbafed93cec1619590157335eajvergaraby 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, excluding HTTP headers.
%...f:          Filename
%...h:          Remote host
%...{Foobar}i:  The contents of Foobar: header line(s) in the request
                sent to the client.
%...l:          Remote logname (from identd, if supplied)
%...{Foobar}n:  The contents of note "Foobar" from another module.
%...{Foobar}o:  The contents of Foobar: header line(s) in the reply.
%...p:          The port the request was served to
%...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 *original* request --- %...>s for the last.
%...t:          Time, in common log format time format
%...{format}t:  The time, in the form given by format, which should
                be in strftime(3) 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?)
</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>Security Considerations</h2>

See the <A HREF="/misc/security_tips.html">security tips</A> document
for details on why your security could be compromised if the directory
where logfiles are stored is writable by anyone other than the user
that starts the server.
<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 deprecated.
<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>