mod_log_config.xml revision 481c1206b6065a8f37ab75ca1fc26c947cb37852
c3fcea07965f59723831e23da647a77518285b8eslive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
6c822625991844de5475569ff656a69965aa6affrbowen<modulesynopsis>
c3fcea07965f59723831e23da647a77518285b8eslive<description>Logging of the requests made to the server</description>
6c822625991844de5475569ff656a69965aa6affrbowen <p>This module provides for flexible logging of client
6c822625991844de5475569ff656a69965aa6affrbowen requests. Logs are written in a customizable format, and may be
6c822625991844de5475569ff656a69965aa6affrbowen written directly to a file, or to an external program.
6c822625991844de5475569ff656a69965aa6affrbowen Conditional logging is provided so that individual requests may
6c822625991844de5475569ff656a69965aa6affrbowen be included or excluded from the logs based on characteristics
6c822625991844de5475569ff656a69965aa6affrbowen of the request.</p>
6c822625991844de5475569ff656a69965aa6affrbowen <p>Three directives are provided by this module:
6c822625991844de5475569ff656a69965aa6affrbowen <code>CustomLog</code> to define a log file and format in one
6c822625991844de5475569ff656a69965aa6affrbowen step. The <code>TransferLog</code> and <code>CustomLog</code>
6c822625991844de5475569ff656a69965aa6affrbowen directives can be used multiple times in each server to cause
6c822625991844de5475569ff656a69965aa6affrbowen each request to be logged to multiple files.</p>
c3fcea07965f59723831e23da647a77518285b8eslive<seealso><a href="/logs.html">Apache Log Files</a></seealso>
6c822625991844de5475569ff656a69965aa6affrbowen <p>The format argument to the <code>LogFormat</code> and
6c822625991844de5475569ff656a69965aa6affrbowen <code>CustomLog</code> directives is a string. This string is
6c822625991844de5475569ff656a69965aa6affrbowen logged to the log file for each request. It can contain literal
6c822625991844de5475569ff656a69965aa6affrbowen characters copied into the log files and the c-type control
6c822625991844de5475569ff656a69965aa6affrbowen characters "\n" and "\t" to represent new-lines and tabs.
6c822625991844de5475569ff656a69965aa6affrbowen Literal quotes and back-slashes should be escaped with
6c822625991844de5475569ff656a69965aa6affrbowen back-slashes.</p>
6c822625991844de5475569ff656a69965aa6affrbowen <p>The characteristics of the request itself are logged by
6c822625991844de5475569ff656a69965aa6affrbowen placing "%" directives in the format string, which are replaced
6c822625991844de5475569ff656a69965aa6affrbowen in the log file by the values as follows:</p>
6c822625991844de5475569ff656a69965aa6affrbowen<td>Bytes sent, excluding HTTP headers. In CLF format
6c822625991844de5475569ff656a69965aa6affrboweni.e. a '-' rather than a 0 when no bytes are sent.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The contents of cookie "Foobar" in the request sent to the server.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The time taken to serve the request, in microseconds.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The contents of the environment variable FOOBAR</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The contents of Foobar: header line(s) in the request
6c822625991844de5475569ff656a69965aa6affrbowen<td>Remote logname (from identd, if supplied)</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The contents of note "Foobar" from another module.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The contents of Foobar: header line(s) in the reply.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The canonical Port of the server serving the request</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The process ID of the child that serviced the request.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The query string (prepended with a ? if a query string exists,
6c822625991844de5475569ff656a69965aa6affrbowen<td>Status. For requests that got internally redirected, this is
6c822625991844de5475569ff656a69965aa6affrbowenthe status of the *original* request --- %...>s for the last.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>Time, in common log format time format (standard english format)</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The time, in the form given by format, which should
6c822625991844de5475569ff656a69965aa6affrbowenbe in strftime(3) format. (potentially localized)</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The time taken to serve the request, in seconds.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>Remote user (from auth; may be bogus if return status (%s) is 401)</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The URL path requested, not including any query string.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The canonical ServerName of the server serving the request.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>The server name according to the UseCanonicalName setting.</td></tr>
6c822625991844de5475569ff656a69965aa6affrbowen<td>Connection status when response is completed.
6c822625991844de5475569ff656a69965aa6affrbowen'X' = connection aborted before the response completed.<br />
6c822625991844de5475569ff656a69965aa6affrbowen'+' = connection may be kept alive after the response is sent.<br />
6c822625991844de5475569ff656a69965aa6affrbowen'-' = connection will be closed after the response is sent.
90748b0dbcd510ae1099f96540c1bef60f8b76c0rbowen<note>(This directive was %...c in late versions of Apache 1.3, but
90748b0dbcd510ae1099f96540c1bef60f8b76c0rbowenthis conflicted with the historical ssl %...{var}c syntax.)</note>
481c1206b6065a8f37ab75ca1fc26c947cb37852ianh<td>Bytes received, including request and headers, cannot be zero. You need to
481c1206b6065a8f37ab75ca1fc26c947cb37852ianhenable <module>mod_logio</module> to use this.</td></tr>
481c1206b6065a8f37ab75ca1fc26c947cb37852ianh<td>Bytes sent, including headers, cannot be zero. You need to enable
6c822625991844de5475569ff656a69965aa6affrbowen <p>The "..." can be nothing at all (<em>e.g.</em>, <code>"%h %u
6c822625991844de5475569ff656a69965aa6affrbowen %r %s %b"</code>), or it can indicate conditions for inclusion
6c822625991844de5475569ff656a69965aa6affrbowen of the item (which will cause it to be replaced with "-" if the
6c822625991844de5475569ff656a69965aa6affrbowen condition is not met). The forms of condition are a list of
6c822625991844de5475569ff656a69965aa6affrbowen HTTP status codes, which may or may not be preceded by "!".
6c822625991844de5475569ff656a69965aa6affrbowen Thus, "%400,501{User-agent}i" logs User-agent: on 400 errors
6c822625991844de5475569ff656a69965aa6affrbowen and 501 errors (Bad Request, Not Implemented) only;
6c822625991844de5475569ff656a69965aa6affrbowen "%!200,304,302{Referer}i" logs Referer: on all requests which
6c822625991844de5475569ff656a69965aa6affrbowen did <strong>not</strong> return some sort of normal status.</p>
6c822625991844de5475569ff656a69965aa6affrbowen <p>Note that there is no escaping performed on the strings from
6c822625991844de5475569ff656a69965aa6affrbowen %...r, %...i and %...o. This is mainly to comply with the
6c822625991844de5475569ff656a69965aa6affrbowen requirements of the Common Log Format. This implies that
6c822625991844de5475569ff656a69965aa6affrbowen clients can insert control characters into the log, so care
6c822625991844de5475569ff656a69965aa6affrbowen should be taken when dealing with raw log files.</p>
6c822625991844de5475569ff656a69965aa6affrbowen <dd><code>"%v %h %l %u %t \"%r\" %>s %b"</code></dd>
6c822625991844de5475569ff656a69965aa6affrbowen <dd><code>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
6c822625991844de5475569ff656a69965aa6affrbowen href="mpm_common.html#listen">Listen</a> of the server serving the
6c822625991844de5475569ff656a69965aa6affrbowen request are used for <code>%v</code> and <code>%p</code>
6c822625991844de5475569ff656a69965aa6affrbowen respectively. This happens regardless of the <a
6c822625991844de5475569ff656a69965aa6affrbowen href="core.html#usecanonicalname">UseCanonicalName</a> setting
6c822625991844de5475569ff656a69965aa6affrbowen because otherwise log analysis programs would have to duplicate
6c822625991844de5475569ff656a69965aa6affrbowen the entire vhost matching algorithm in order to decide what
6c822625991844de5475569ff656a69965aa6affrbowen host really served the request.</p>
6c822625991844de5475569ff656a69965aa6affrbowen href="/misc/security_tips.html#serverroot">security tips</a>
6c822625991844de5475569ff656a69965aa6affrbowen document for details on why your security could be compromised
6c822625991844de5475569ff656a69965aa6affrbowen if the directory where logfiles are stored is writable by
6c822625991844de5475569ff656a69965aa6affrbowen anyone other than the user that starts the server.</p>
6c822625991844de5475569ff656a69965aa6affrbowen<directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<description>Sets filename for the logging of cookies</description>
6c822625991844de5475569ff656a69965aa6affrbowen<contextlist><context>server config</context><context>virtual
6c822625991844de5475569ff656a69965aa6affrbowen<compatibility>Only available in Apache 1.2 and above</compatibility>
6c822625991844de5475569ff656a69965aa6affrbowen <p>The <directive>CookieLog</directive> directive sets the
6c822625991844de5475569ff656a69965aa6affrbowen filename for logging of cookies. The filename is relative to the
6c822625991844de5475569ff656a69965aa6affrbowen <directive module="core">serverroot</directive>. This directive is
6c822625991844de5475569ff656a69965aa6affrbowen included only for compatibility with <module>mod_cookies</module>,
6c822625991844de5475569ff656a69965aa6affrbowen and is deprecated.</p>
6c822625991844de5475569ff656a69965aa6affrbowen</directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<description>Sets filename and format of log file</description>
6c822625991844de5475569ff656a69965aa6affrbowen<syntax>CustomLog
6c822625991844de5475569ff656a69965aa6affrbowen <em>file</em>|<em>pipe</em> <em>format</em>|<em>nickname</em>
6c822625991844de5475569ff656a69965aa6affrbowen<contextlist><context>server config</context><context>virtual
6c822625991844de5475569ff656a69965aa6affrbowen<compatibility>Nickname only available in Apache 1.3 or later.
6c822625991844de5475569ff656a69965aa6affrbowenConditional logging available in 1.3.5 or later.</compatibility>
6c822625991844de5475569ff656a69965aa6affrbowen <p>The <directive>CustomLog</directive> directive is used to
6c822625991844de5475569ff656a69965aa6affrbowen log requests to the server. A log format is specified, and the
6c822625991844de5475569ff656a69965aa6affrbowen logging can optionally be made conditional on request
6c822625991844de5475569ff656a69965aa6affrbowen characteristics using environment variables.</p>
6c822625991844de5475569ff656a69965aa6affrbowen <p>The first argument, which specifies the location to which
6c822625991844de5475569ff656a69965aa6affrbowen the logs will be written, can take on one of the following two
6c822625991844de5475569ff656a69965aa6affrbowen types of values:</p>
6c822625991844de5475569ff656a69965aa6affrbowen <dd>The pipe character "<code>|</code>", followed by the path
6c822625991844de5475569ff656a69965aa6affrbowen to a program to receive the log information on its standard
6c822625991844de5475569ff656a69965aa6affrbowen input. <strong>Security:</strong> if a program is used, then
6c822625991844de5475569ff656a69965aa6affrbowen it will be run under the user who started httpd. This will be
6c822625991844de5475569ff656a69965aa6affrbowen root if the server was started by root; be sure that the
6c822625991844de5475569ff656a69965aa6affrbowen program is secure.</dd>
6c822625991844de5475569ff656a69965aa6affrbowen <p>The second argument specifies what will be written to the
6c822625991844de5475569ff656a69965aa6affrbowen log file. It can specify either a <em>nickname</em> defined by
6c822625991844de5475569ff656a69965aa6affrbowen a previous <a href="#logformat">LogFormat</a> directive, or it
6c822625991844de5475569ff656a69965aa6affrbowen can be an explicit <em>format</em> string as described in the
6c822625991844de5475569ff656a69965aa6affrbowen <p>For example, the following two sets of directives have
6c822625991844de5475569ff656a69965aa6affrbowen exactly the same effect:</p>
6c822625991844de5475569ff656a69965aa6affrbowen # CustomLog with format nickname<br />
6c822625991844de5475569ff656a69965aa6affrbowen LogFormat "%h %l %u %t \"%r\" %>s %b" common<br />
6c822625991844de5475569ff656a69965aa6affrbowen # CustomLog with explicit format string<br />
6c822625991844de5475569ff656a69965aa6affrbowen CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"<br />
6c822625991844de5475569ff656a69965aa6affrbowen <p>The third argument is optional and allows the decision on
6c822625991844de5475569ff656a69965aa6affrbowen whether or not to log a particular request to be based on the
6c822625991844de5475569ff656a69965aa6affrbowen presence or absence of a particular variable in the server
6c822625991844de5475569ff656a69965aa6affrbowen environment. If the specified <a href="/env.html">environment
6c822625991844de5475569ff656a69965aa6affrbowen variable</a> is set for the request (or is not set, in the case
6c822625991844de5475569ff656a69965aa6affrbowen of a '<code>env=!<em>name</em></code>' clause), then the
6c822625991844de5475569ff656a69965aa6affrbowen request will be logged.</p>
6c822625991844de5475569ff656a69965aa6affrbowen <p>Environment variables can be set on a <em>per</em>-request
01814afd8daa1fb017fcb956ac01d173763f896eyoshiki example, if you want to record requests for all GIF
01814afd8daa1fb017fcb956ac01d173763f896eyoshiki images on your server in a separate logfile but not in your main
6c822625991844de5475569ff656a69965aa6affrbowen log, you can use:</p>
6c822625991844de5475569ff656a69965aa6affrbowen SetEnvIf Request_URI \.gif$ gif-image<br />
6c822625991844de5475569ff656a69965aa6affrbowen CustomLog gif-requests.log common env=gif-image<br />
6c822625991844de5475569ff656a69965aa6affrbowen CustomLog nongif-requests.log common env=!gif-image
6c822625991844de5475569ff656a69965aa6affrbowen</directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<description>Describes a format for use in a log file</description>
6c822625991844de5475569ff656a69965aa6affrbowen<syntax>LogFormat
6c822625991844de5475569ff656a69965aa6affrbowen <em>format</em>|<em>nickname</em> [<em>nickname</em>]</syntax>
7cb7b06acc8700479d4d4080b8c7bc5278f20028slive<default>LogFormat "%h %l %u %t \"%r\" %>s %b"</default>
6c822625991844de5475569ff656a69965aa6affrbowen<contextlist><context>server config</context><context>virtual
6c822625991844de5475569ff656a69965aa6affrbowen<compatibility>Nickname only available in Apache 1.3 or later.
6c822625991844de5475569ff656a69965aa6affrbowen</compatibility>
6c822625991844de5475569ff656a69965aa6affrbowen <p>This directive specifies the format of the access log
6c822625991844de5475569ff656a69965aa6affrbowen <p>The <directive>LogFormat</directive> directive can take one of two
6c822625991844de5475569ff656a69965aa6affrbowen forms. In the first form, where only one argument is specified,
6c822625991844de5475569ff656a69965aa6affrbowen this directive sets the log format which will be used by logs
6c822625991844de5475569ff656a69965aa6affrbowen specified in subsequent <directive>TransferLog</directive>
6c822625991844de5475569ff656a69965aa6affrbowen directives. The single argument can specify an explicit
6c822625991844de5475569ff656a69965aa6affrbowen <em>format</em> as discussed in <a href="#formats">custom log
6c822625991844de5475569ff656a69965aa6affrbowen formats</a> section above. Alternatively, it can use a
6c822625991844de5475569ff656a69965aa6affrbowen <em>nickname</em> to refer to a log format defined in a
6c822625991844de5475569ff656a69965aa6affrbowen previous <directive>LogFormat</directive> directive as described
6c822625991844de5475569ff656a69965aa6affrbowen <p>The second form of the <directive>LogFormat</directive>
6c822625991844de5475569ff656a69965aa6affrbowen directive associates an explicit <em>format</em> with a
6c822625991844de5475569ff656a69965aa6affrbowen <em>nickname</em>. This <em>nickname</em> can then be used in
6c822625991844de5475569ff656a69965aa6affrbowen <directive>CustomLog</directive> directives rather than
6c822625991844de5475569ff656a69965aa6affrbowen repeating the entire format string. A
7cb7b06acc8700479d4d4080b8c7bc5278f20028slive directive that defines a nickname <strong>does nothing
6c822625991844de5475569ff656a69965aa6affrbowen else</strong> -- that is, it <em>only</em> defines the
6c822625991844de5475569ff656a69965aa6affrbowen nickname, it doesn't actually apply the format and make it the
6c822625991844de5475569ff656a69965aa6affrbowen default. Therefore, it will not affect subsequent
7cb7b06acc8700479d4d4080b8c7bc5278f20028slive <directive>TransferLog</directive> directives. In addition,
9061df24b86d55e826426767ca2693d06d9daa78slive <directive>LogFormat</directive> cannot use one nickname
7cb7b06acc8700479d4d4080b8c7bc5278f20028slive to define another nickname.</p>
29150bfcfe19f5b1bf6c2984466b447330815b69rbowen <example>LogFormat "%v %h %l %u %t \"%r\" %>s %b"
29150bfcfe19f5b1bf6c2984466b447330815b69rbowen vhost_common</example>
6c822625991844de5475569ff656a69965aa6affrbowen</directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen<description>Specifly location of a log file</description>
6c822625991844de5475569ff656a69965aa6affrbowen<syntax>TransferLog <em>file</em>|<em>pipe</em></syntax>
6c822625991844de5475569ff656a69965aa6affrbowen<contextlist><context>server config</context><context>virtual
6c822625991844de5475569ff656a69965aa6affrbowen <p>This directive has exactly the same arguments and effect as
6c822625991844de5475569ff656a69965aa6affrbowen the <directive>CustomLog</directive> directive, with the
6c822625991844de5475569ff656a69965aa6affrbowen exception that it does not allow the log format to be specified
6c822625991844de5475569ff656a69965aa6affrbowen explicitly or for conditional logging of requests. Instead, the
6c822625991844de5475569ff656a69965aa6affrbowen log format is determined by the most recently specified
6c822625991844de5475569ff656a69965aa6affrbowen does not define a nickname). Common Log Format is used if no
6c822625991844de5475569ff656a69965aa6affrbowen other format has been specified.</p>
6c822625991844de5475569ff656a69965aa6affrbowen LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""<br />
6c822625991844de5475569ff656a69965aa6affrbowen</directivesynopsis>
6c822625991844de5475569ff656a69965aa6affrbowen</modulesynopsis>