mod_log_config.html revision fc891500135b18740c60ea32a7ea0a069e8eafd7
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen BGCOLOR="#FFFFFF"
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen TEXT="#000000"
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen LINK="#0000FF"
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen VLINK="#000080"
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen ALINK="#FF0000"
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<!--#include virtual="header.html" -->
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenThis module is contained in the <CODE>mod_log_config.c</CODE> file,
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenand is compiled in by default in Apache 1.2. mod_log_config replaces
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenmod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenan optional module. It provides for logging of the requests made to
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenthe server, using the Common Log Format or a user-specified format.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenThree directives are provided by this module: <CODE>TransferLog</CODE>
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainento create a log file, <CODE>LogFormat</CODE> to set a custom format,
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenand <CODE>CustomLog</CODE> to define a log file and format in one go.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenThe <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenbe used multiple times in each server to cause each request to be
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenlogged to multiple files.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<LI>This module is based on mod_log_config distributed with
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenprevious Apache releases, now updated to handle multiple logs.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenThere is now no need to re-configure Apache to use configuration log
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<LI>The module also implements the <CODE>CookieLog</CODE> directive,
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenused to log user-tracking information created by <A
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenHREF="mod_usertrack.html">mod_usertrack</A>. The use of
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<CODE>CookieLog</CODE> is deprecated, and a <CODE>CustomLog</CODE>
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenshould be defined to log user-tracking information instead.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenUnless told otherwise with <TT>LogFormat</TT> the log files created by
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<TT>TransferLog</TT> will be in standard "Common Log Format"
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen(CLF). The contents of each line in a CLF file are explained
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenbelow. Alternatively, the log file can be customized (and if multiple
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenlog files are used, each can have a different format). Custom formats
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenare set with <CODE>LogFormat</CODE> and <CODE>CustomLog</CODE>.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenThe Common Log Format (CLF) file contains a separate line for each
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenrequest. A line is composed of several tokens separated by spaces:
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenhost ident authuser date request status bytes
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenIf a token does not have a value then it is represented by a hyphen (-).
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo SirainenThe meanings and values of these tokens are as follows:
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<DD>The fully-qualified domain name of the client, or its IP number if the
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenname is not available.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<DD>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenclient machine runs identd, then this is the identity information reported
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenby the client.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<DD>If the request was for an password protected document, then this is
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenthe userid used in the request.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<DD>The date and time of the request, in the following format:
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<DL><DD><BLOCKQUOTE><CODE> date = [day/month/year:hour:minute:second zone] <BR>
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenday = 2*digit<BR>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenmonth = 3*letter<BR>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenyear = 4*digit<BR>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenhour = 2*digit<BR>
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenminute = 2*digit<BR>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainensecond = 2*digit<BR>
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenzone = (`+' | `-') 4*digit</CODE></BLOCKQUOTE></DL>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen<DD>The request line from the client, enclosed in double quotes
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen<DD>The three digit status code returned to the client.
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<DD>The number of bytes in the object returned to the client, not including
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen<H3><A NAME="formats">Custom Log Formats</A></H3>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenThe format argument to the <CODE>LogFormat</CODE> and
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen<CODE>CustomLog</CODE> is a string. This string is logged to the log
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenfile for each request. It can contain literal characters copied into
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenthe log files, and `%' directives which are replaced in the log file
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenby the values as follows:
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...b: Bytes sent, excluding HTTP headers.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...{FOOBAR}e: The contents of the environment variable FOOBAR
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...a: Remote IP-address
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen%...{Foobar}i: The contents of Foobar: header line(s) in the request
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen sent to the server.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...l: Remote logname (from identd, if supplied)
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainen%...{Foobar}n: The contents of note "Foobar" from another module.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...p: The canonical Port of the server serving the request
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...P: The process ID of the child that serviced the request.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...r: First line of request
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...s: Status. For requests that got internally redirected, this
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen is status of the *original* request --- %...>s for the last.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...t: Time, in common log format time format
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...{format}t: The time, in the form given by format, which should
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen be in strftime(3) format.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...T: The time taken to serve the request, in seconds.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...u: Remote user (from auth; may be bogus if return status (%s) is 401)
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...U: The URL path requested.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...v: The canonical ServerName of the server serving the request.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenThe `...' can be nothing at all (<EM>e.g.</EM>, <CODE>"%h %u %r %s %b"</CODE>), or it can
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenindicate conditions for inclusion of the item (which will cause it
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainento be replaced with `-' if the condition is not met). Note that
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenthere is no escaping performed on the strings from %r, %...i and
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%...o; some with long memories may remember that I thought this was
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainena bad idea, once upon a time, and I'm still not comfortable with
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenit, but it is difficult to see how to `do the right thing' with all
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenof `%..i', unless we URL-escape everything and break with CLF.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenThe forms of condition are a list of HTTP status codes, which may
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenor may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenUser-agent: on 400 errors and 501 errors (Bad Request, Not
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenImplemented) only; `%!200,304,302{Referer}i' logs Referer: on all
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenrequests which did <STRONG>not</STRONG> return some sort of normal status.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenNote that the common log format is defined by the string <CODE>"%h %l
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen%u %t \"%r\" %s %b"</CODE>, which can be used as the basis for
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenextending for format if desired (<EM>e.g.</EM>, to add extra fields at the end).
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenNCSA's extended/combined log format would be <CODE>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE>.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenNote that the canonical <A HREF="core.html#servername">ServerName</A>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenand <A HREF="core.html#port">Port</A> of the server serving the request
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenare used for <CODE>%v</CODE> and <CODE>%p</CODE> respectively. This
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenhappens regardless of the
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen<A HREF="core.html#usecanonicalname">UseCanonicalName</A> setting because
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenotherwise log analysis programs would have to duplicate the entire
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenvhost matching algorithm in order to decide what host really served
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenThe <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenbe given more than once to log requests to multiple log files. Each
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenrequest will be logged to all the log files defined by either of these
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenIf a <VirtualHost> section does not contain any
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainen<TT>TransferLog</TT> or <TT>CustomLog</TT> directives, the
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenlogs defined for the main server will be used. If it does
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainencontain one or more of these directives, requests serviced by
1358e2c58ce29231485a5cfa454756d429ad3d2cTimo Sirainenthis virtual host will only be logged in the log files defined
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenwithin its definition, not in any of the main server's log files.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenSee the examples below.
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo SirainenSee the <A HREF="/misc/security_tips.html#security">security tips</A>
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainendocument for details on why your security could be compromised if the
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainendirectory where logfiles are stored is writable by anyone other than
637ec4c33b4715737a41f7e58c9b6d1f693c27e2Timo Sirainenthe user that starts the server.
HREF="directive-dict.html#Syntax"
HREF="directive-dict.html#Context"
HREF="directive-dict.html#Module"
HREF="directive-dict.html#Compatibility"
HREF="directive-dict.html#Syntax"
HREF="directive-dict.html#Context"
HREF="directive-dict.html#Status"
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"
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" -->