mod_log_config.html revision 25206f2bd629db68b1d644cf1e16f2c0c971c830
bcb4e51a409d94ae670de96afb8483a4f7855294Stephan Bosch<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
02b32cf39a098edf60981fc228e4b034f11f3b90Timo Sirainen<!--#include virtual="header.html" -->
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThis module is contained in the <code>mod_log_config.c</code> file,
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenand is compiled in by default in Apache 1.2. mod_log_config replaces
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenmod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
9e86ad9eb313004cd4c8b5427daeb4c241b57af6Timo Sirainenan optional module. It provides for logging of the requests made to
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenthe server, using the Common Log Format or a user-specified format.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThree directives are provided by this module: <code>TransferLog</code>
1ea0aa8e14e843f2776746776a429b0a1aae299dTimo Sirainento create a log file, <code>LogFormat</code> to set a custom format,
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenand <code>CustomLog</code> to define a log file and format in one go.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThe <code>TransferLog</code> and <code>CustomLog</code> directives can
68332e3a49dea15013aa8f4daa16b5e07eb3d543Timo Sirainenbe used multiple times in each server to cause each request to be
65f9a90ef5ed4c86fb9e44f22e472509126ae9f5Timo Sirainenlogged to multiple files.
4a7e04d325db0c03f575f98f045246fceb0de279Timo Sirainen<li>This module is based on mod_log_config distributed with
1ea0aa8e14e843f2776746776a429b0a1aae299dTimo Sirainenprevious Apache releases, now updated to handle multiple logs.
1ea0aa8e14e843f2776746776a429b0a1aae299dTimo SirainenThere is now no need to re-configure Apache to use configuration log
6e77746e501c2b45850b1c530836058ed75e09eeTimo Sirainen<li>The module also implements the <code>CookieLog</code> directive,
6e77746e501c2b45850b1c530836058ed75e09eeTimo Sirainenused to log user-tracking information created by <a
6e77746e501c2b45850b1c530836058ed75e09eeTimo Sirainenhref="mod_usertrack.html">mod_usertrack</a>. The use of
6e77746e501c2b45850b1c530836058ed75e09eeTimo Sirainen<code>CookieLog</code> is deprecated, and a <code>CustomLog</code>
6e77746e501c2b45850b1c530836058ed75e09eeTimo Sirainenshould be defined to log user-tracking information instead.
6e77746e501c2b45850b1c530836058ed75e09eeTimo SirainenUnless told otherwise with <tt>LogFormat</tt> the log files created by
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainen<tt>TransferLog</tt> will be in standard "Common Log Format"
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainen(CLF). The contents of each line in a CLF file are explained
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainenbelow. Alternatively, the log file can be customized (and if multiple
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainenlog files are used, each can have a different format). Custom formats
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainenare set with <code>LogFormat</code> and <code>CustomLog</code>.
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo SirainenThe Common Log Format (CLF) file contains a separate line for each
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainenrequest. A line is composed of several tokens separated by spaces:
8c8f7ac580b661aee3d8b8dd37df4a9b41c77000Timo Sirainenhost ident authuser date request status bytes
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenIf a token does not have a value then it is represented by a hyphen (-).
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThe meanings and values of these tokens are as follows:
48f78a48f2e1cf299026544444666471ae16ad97Timo Sirainen<dd>The fully-qualified domain name of the client, or its IP number if the
48f78a48f2e1cf299026544444666471ae16ad97Timo Sirainenname is not available.
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
0dc7891233a973829f00371b27810f849b987c66Timo Sirainenclient machine runs identd, then this is the identity information reported
0dc7891233a973829f00371b27810f849b987c66Timo Sirainenby the client.
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<dd>If the request was for an password protected document, then this is
0dc7891233a973829f00371b27810f849b987c66Timo Sirainenthe userid used in the request.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<dd>The date and time of the request, in the following format:
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<dl><dd><blockquote><code> date = [day/month/year:hour:minute:second zone] <br>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenday = 2*digit<br>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenmonth = 3*letter<br>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenyear = 4*digit<br>
efe78d3ba24fc866af1c79b9223dc0809ba26cadStephan Boschhour = 2*digit<br>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenminute = 2*digit<br>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainensecond = 2*digit<br>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenzone = (`+' | `-') 4*digit</code></blockquote></dl>
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<dd>The request line from the client, enclosed in double quotes
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<dd>The three digit status code returned to the client.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<dd>The number of bytes in the object returned to the client, not including
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenThe format argument to the <code>LogFormat</code> and
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<code>CustomLog</code> is a string. This string is logged to the log
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenfile for each request. It can contain literal characters copied into
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenthe log files, and `%' directives which are replaced in the log file
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenby the values as follows:
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...b: Bytes sent, excluding HTTP headers.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...{Foobar}i: The contents of Foobar: header line(s) in the request
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen sent to the server.
d9a7e950a9cd21f2b4a90ec7759fca9e8fcc7995Timo Sirainen%...l: Remote logname (from identd, if supplied)
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...{Foobar}n: The contents of note "Foobar" from another module.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...p: The port the request was served to
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...P: The process ID of the child that serviced the request.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...r: First line of request
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...s: Status. For requests that got internally redirected, this
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen is status of the *original* request --- %...>s for the last.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...t: Time, in common log format time format
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...{format}t: The time, in the form given by format, which should
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen be in strftime(3) format.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...T: The time taken to serve the request, in seconds.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...u: Remote user (from auth; may be bogus if return status (%s) is 401)
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...U: The URL path requested.
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...v: The name of the server (i.e. which virtual host?)
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenThe `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can
14cac26dcb71108abfdc95ea524e74be1f95774cPhil Carmodyindicate conditions for inclusion of the item (which will cause it
14cac26dcb71108abfdc95ea524e74be1f95774cPhil Carmodyto be replaced with `-' if the condition is not met). Note that
14cac26dcb71108abfdc95ea524e74be1f95774cPhil Carmodythere is no escaping performed on the strings from %r, %...i and
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%...o; some with long memories may remember that I thought this was
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainena bad idea, once upon a time, and I'm still not comfortable with
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenit, but it is difficult to see how to `do the right thing' with all
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenof `%..i', unless we URL-escape everything and break with CLF.
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenThe forms of condition are a list of HTTP status codes, which may
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenor may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenUser-agent: on 400 errors and 501 errors (Bad Request, Not
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenImplemented) only; `%!200,304,302{Referer}i' logs Referer: on all
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenrequests which did <b>not</b> return some sort of normal status.
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenNote that the common log format is defined by the string <code>"%h %l
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen%u %t \"%r\" %s %b"</code>, which can be used as the basis for
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenextending for format if desired (e.g. to add extra fields at the end).
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenThe <code>TransferLog</code> and <code>CustomLog</code> directives can
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenbe given more than once to log requests to multiple log files. Each
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenrequest will be logged to all the log files defined by either of these
b5ff746939712c6a9bef71405fa786d5471cf177Timo SirainenIf a <VirtualHost> section does not contain any
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainen<tt>TransferLog</tt> or <tt>CustomLog</tt> directives, the
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainenlogs defined for the main server will be used. If it does
b5ff746939712c6a9bef71405fa786d5471cf177Timo Sirainencontain one or more of these directives, requests serviced by
4eb418849d5c6bf77b2721e4e6aef2e97deaa197Timo Sirainenthis virtual host will only be logged in the log files defined
4eb418849d5c6bf77b2721e4e6aef2e97deaa197Timo Sirainenwithin its definition, not in any of the main server's log files.
4eb418849d5c6bf77b2721e4e6aef2e97deaa197Timo SirainenSee the examples below.
a8b37b688ceaa3ed3d40b3ccbdba5bb75cfb64b0Timo SirainenSee the <A HREF="/misc/security_tips.html">security tips</A> document
4eb418849d5c6bf77b2721e4e6aef2e97deaa197Timo Sirainenfor details on why your security could be compromised if the directory
4eb418849d5c6bf77b2721e4e6aef2e97deaa197Timo Sirainenwhere logfiles are stored is writable by anyone other than the user
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenthat starts the server.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<!--%plaintext <?INDEX {\tt CookieLog} directive> -->
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<strong>Syntax:</strong> CookieLog <em>filename</em><br>
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<Strong>Context:</strong> server config, virtual host<br>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<strong>Compatibility:</strong> Only available in Apache 1.2 and above<p>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThe CookieLog directive sets the filename for logging of cookies.
0dc7891233a973829f00371b27810f849b987c66Timo SirainenThe filename is relative to the <A
0dc7891233a973829f00371b27810f849b987c66Timo SirainenHREF="core.html#serverroot">ServerRoot</A>. This directive is included
0dc7891233a973829f00371b27810f849b987c66Timo Sirainenonly for compatibility with <a
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenhref="mod_cookies.html">mod_cookies</a>, and is deprecated.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<STRONG>Syntax:</STRONG> CustomLog <em>file-pipe</em> <em>format</em><BR>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<STRONG>Context:</STRONG> server config, virtual host<BR>
4a7e04d325db0c03f575f98f045246fceb0de279Timo SirainenThe first argument is the filename to log to. This is used
4a7e04d325db0c03f575f98f045246fceb0de279Timo Sirainenexactly like the argument to <tt>TransferLog</tt>, that is,
f83fd83f9c6708d198748e714aa947cad9362c02Timo Sirainenit is either a full path, or relative to the current
4a7e04d325db0c03f575f98f045246fceb0de279Timo Sirainenserver root. <p>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThe format argument specifies a format for each line of the log file.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThe options available for the format are exactly the same as for
02b32cf39a098edf60981fc228e4b034f11f3b90Timo Sirainenthe argument of the <tt>LogFormat</tt> directive. If the format
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenincludes any spaces (which it will do in almost all cases) it
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenshould be enclosed in double quotes.
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<!--%plaintext <?INDEX {\tt LogFormat} directive> -->
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<strong>Syntax:</strong> LogFormat <em>string</em><br>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<strong>Default:</strong> <code>LogFormat "%h %l %u %t \"%r\"
9e86ad9eb313004cd4c8b5427daeb4c241b57af6Timo Sirainen<Strong>Context:</strong> server config, virtual host<br>
9e86ad9eb313004cd4c8b5427daeb4c241b57af6Timo Sirainen<!--%plaintext <?INDEX {\tt TransferLog} directive> -->
9e86ad9eb313004cd4c8b5427daeb4c241b57af6Timo Sirainen<strong>Syntax:</strong> TransferLog <em>file-pipe</em><br>
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<strong>Default:</strong> <code>TransferLog logs/transfer_log</code><br>
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<Strong>Context:</strong> server config, virtual host<br>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenThe TransferLog directive adds a log file in Common Log Format.
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>.
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<dt> `|' followed by a command
0dc7891233a973829f00371b27810f849b987c66Timo Sirainen<dd>A program to receive the agent log information on its standard input.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo SirainenNote the a new program will not be started for a VirtualHost if it inherits
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenthe TransferLog from the main server.
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<strong>Security:</strong> if a program is used, then it will be
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenrun under the user who started httpd. This will be root if the server
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainenwas started by root; be sure that the program is secure.<p>
d9fdacd5fb3e07997e5c389739d2054f0c8441d8Timo Sirainen<!--#include virtual="footer.html" -->