mod_log_config.html revision 3271c6d2998f53b0ac3d798f237e6e4cebd3bd51
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
c58f1213e628a545081c70e26c6b67a841cff880vboxsync<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
6ec4e1827eab6a424d672ef0e5a17b065e52db20vboxsync BGCOLOR="#FFFFFF"
6ec4e1827eab6a424d672ef0e5a17b065e52db20vboxsync TEXT="#000000"
6ec4e1827eab6a424d672ef0e5a17b065e52db20vboxsync LINK="#0000FF"
6ec4e1827eab6a424d672ef0e5a17b065e52db20vboxsync VLINK="#000080"
6ec4e1827eab6a424d672ef0e5a17b065e52db20vboxsync ALINK="#FF0000"
6ec4e1827eab6a424d672ef0e5a17b065e52db20vboxsync<!--#include virtual="header.html" -->
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncThis module provides for logging of the requests made to
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncthe server, using the Common Log Format or a user-specified format.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncHREF="module-dict.html#SourceFile"
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncHREF="module-dict.html#ModuleIdentifier"
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync><STRONG>Module Identifier:</STRONG></A> config_log_module
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync<p>This module provides for flexible logging of client requests. Logs
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncare written in a customizable format, and may be written directly to a
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsyncfile, or to an external program. Conditional logging is provided so
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsyncthat individual requests may be included or excluded from the logs
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsyncbased on characteristics of the request.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncThree directives are provided by this module: <CODE>TransferLog</CODE>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncto create a log file, <CODE>LogFormat</CODE> to set a custom format,
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncand <CODE>CustomLog</CODE> to define a log file and format in one step.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncThe <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncbe used multiple times in each server to cause each request to be
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynclogged to multiple files.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>See also: <a href="/logs.html">Apache Log Files</a>.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>The format argument to the <CODE>LogFormat</CODE> and
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<CODE>CustomLog</CODE> directives is a string. This string is logged
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncto the log file for each request. It can contain literal characters
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynccopied into the log files and the c-type control characters "\n" and
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync"\t" to represent new-lines and tabs. Literal quotes and back-slashes
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsyncshould be escaped with back-slashes.</p>
9463a771c826d5b93c993eb36baaabf59be55f5evboxsync<p>The characteristics of the request itself are logged by placing
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync"%" directives in the format string, which are replaced in the log file
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncby the values as follows:</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...a: Remote IP-address
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...A: Local IP-address
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...B: Bytes sent, excluding HTTP headers.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...b: Bytes sent, excluding HTTP headers. In CLF format
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync i.e. a '-' rather than a 0 when no bytes are sent.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync%...c: Connection status when response is completed.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync 'X' = connection aborted before the response completed.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync '+' = connection may be kept alive after the response is sent.
a04100f955c08c93b063cf3d9c4f963637996f3cvboxsync '-' = connection will be closed after the response is sent.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...{Foobar}C: The contents of cookie "Foobar" in the request sent to the
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...D: The time taken to serve the request, in microseconds.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...{FOOBAR}e: The contents of the environment variable FOOBAR
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...h: Remote host
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...H The request protocol
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync%...{Foobar}i: The contents of Foobar: header line(s) in the request
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync sent to the server.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync%...l: Remote logname (from identd, if supplied)
98427c0ab08697e468c26dc33ee9571308577867vboxsync%...m The request method
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...{Foobar}n: The contents of note "Foobar" from another module.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...p: The canonical Port of the server serving the request
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...P: The process ID of the child that serviced the request.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...q The query string (prepended with a ? if a query string exists,
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync otherwise an empty string)
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...r: First line of request
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync%...s: Status. For requests that got internally redirected, this is
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync the status of the *original* request --- %...>s for the last.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...t: Time, in common log format time format (standard english format)
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...{format}t: The time, in the form given by format, which should
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync be in strftime(3) format. (potentially localized)
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...T: The time taken to serve the request, in seconds.
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync%...u: Remote user (from auth; may be bogus if return status (%s) is 401)
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync%...U: The URL path requested, not including any query string.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync%...v: The canonical ServerName of the server serving the request.
0f81043c307886fc3e8d0479c4e4120b35c6d0b9vboxsync%...V: The server name according to the UseCanonicalName setting.
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync<p>The "..." can be nothing at all (<EM>e.g.</EM>, <CODE>"%h %u %r %s
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%b"</CODE>), or it can indicate conditions for inclusion of the item
021c939a9e3f688c0c3bbd759354be906bb2dcabvboxsync(which will cause it to be replaced with "-" if the condition is not
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncmet). The forms of condition are a list of HTTP status codes, which
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncmay or may not be preceded by "!". Thus, "%400,501{User-agent}i" logs
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncUser-agent: on 400 errors and 501 errors (Bad Request, Not
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncImplemented) only; "%!200,304,302{Referer}i" logs Referer: on all
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncrequests which did <STRONG>not</STRONG> return some sort of normal
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>Note that there is no escaping performed on the strings from
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync%...r, %...i and %...o. This is mainly to comply with the requirements
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncof the Common Log Format. This implies that clients can insert
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynccontrol characters into the log, so care should be taken when dealing
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncwith raw log files.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<dd><CODE>"%h %l %u %t \"%r\" %>s %b"</CODE></dd>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<dd><code>"%v %h %l %u %t \"%r\" %>s %b"</CODE></dd>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<dd> <CODE>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE></dd>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncHREF="core.html#port">Port</A> of the server serving the request are
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncused for <CODE>%v</CODE> and <CODE>%p</CODE> respectively. This
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynchappens regardless of the <A
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncHREF="core.html#usecanonicalname">UseCanonicalName</A> setting because
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncotherwise log analysis programs would have to duplicate the entire
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncvhost matching algorithm in order to decide what host really served
19d2bd74156f55ea7fd654c35cc421abb0dc55cfvboxsyncthe request.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>See the <A HREF="/misc/security_tips.html#serverroot">security tips</A>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncdocument for details on why your security could be compromised if the
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncdirectory where logfiles are stored is writable by anyone other than
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncthe user that starts the server.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<H2><A NAME="cookielog">CookieLog</A> directive</H2>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<!--%plaintext <?INDEX {\tt CookieLog} directive> -->
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync><STRONG>Syntax:</STRONG></A> CookieLog <EM>filename</EM><BR>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync><STRONG>Context:</STRONG></A> server config, virtual host<BR>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync HREF="directive-dict.html#Compatibility"
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.2 and above</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>The CookieLog directive sets the filename for logging of cookies.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncThe filename is relative to the <A
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncHREF="core.html#serverroot">ServerRoot</A>. This directive is included
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynconly for compatibility with mod_cookies, and is deprecated.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync><STRONG>Syntax:</STRONG></A> CustomLog <EM>file</em>|<em>pipe</EM>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync <EM>format</em>|<em>nickname</EM> [env=[!]<EM>environment-variable</EM>]<BR>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync><STRONG>Context:</STRONG></A> server config, virtual host<BR>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync HREF="directive-dict.html#Compatibility"
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync or later. Conditional logging available in 1.3.5 or later.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>The <code>CustomLog</code> directive is used to log requests
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncto the server. A log format is specified, and the logging can
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncoptionally be made conditional on request characteristics
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncusing environment variables.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<P>The first argument, which specifies the location to which the
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynclogs will be written, can take on one of the following two
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsynctypes of values:</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<dd>A filename, relative to the
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<dd>The pipe character "<code>|</code>", followed by the path to a
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncprogram to receive the log information on its standard input.
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<STRONG>Security:</STRONG> if a program is used, then it will be run
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncunder the user who started httpd. This will be root if the server was
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncstarted by root; be sure that the program is secure.</dd>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<P>The second argument specifies what will be written to the
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncdefined by a previous <a href="#logformat">LogFormat</a>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncdirective, or it can be an explicit <em>format</em> string
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncas described in the <a href="#formats">log formats</a> section.</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>For example, the following two sets of directives have exactly
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncthe same effect:</p>
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync # CustomLog with format nickname
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync LogFormat "%h %l %u %t \"%r\" %>s %b" common
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync # CustomLog with explicit format string
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync<p>The third argument is optional and allows the decision on whether
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncor not to log a particular request to be based on the presence or
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncabsence of a particular variable in the server environment. If the
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncspecified <a href="/env.html">environment variable</a> is set for
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsyncthe request (or is not set, in the case of a
a33af978add1a03aab11b2895f441af5cb2a11a6vboxsync'<CODE>env=!<EM>name</EM></CODE>' clause), then the request will be
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image
HREF="directive-dict.html#Syntax"
HREF="directive-dict.html#Default"
HREF="directive-dict.html#Context"
HREF="directive-dict.html#Status"
HREF="directive-dict.html#Compatibility"
HREF="directive-dict.html#Module"
HREF="directive-dict.html#Syntax"
HREF="directive-dict.html#Default"
HREF="directive-dict.html#Context"
HREF="directive-dict.html#Status"
HREF="directive-dict.html#Module"
<!--#include virtual="footer.html" -->