mod_log_config.html revision f9b3be308809978f797e0c57b296147532a4313c
28ec5e4f5c4a71428affc986304e894eda600925takashi<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding BGCOLOR="#FFFFFF"
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding TEXT="#000000"
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding LINK="#0000FF"
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding VLINK="#000080"
acc36ab93565d2880447d535da6ca6e5feac7a70nd ALINK="#FF0000"
acc36ab93565d2880447d535da6ca6e5feac7a70nd<!--#include virtual="header.html" -->
acc36ab93565d2880447d535da6ca6e5feac7a70ndThis module is contained in the <CODE>mod_log_config.c</CODE> file,
acc36ab93565d2880447d535da6ca6e5feac7a70ndand is compiled in by default in Apache 1.2. mod_log_config replaces
acc36ab93565d2880447d535da6ca6e5feac7a70ndmod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
acc36ab93565d2880447d535da6ca6e5feac7a70ndan optional module. It provides for logging of the requests made to
acc36ab93565d2880447d535da6ca6e5feac7a70ndthe server, using the Common Log Format or a user-specified format.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThree directives are provided by this module: <CODE>TransferLog</CODE>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveto create a log file, <CODE>LogFormat</CODE> to set a custom format,
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveand <CODE>CustomLog</CODE> to define a log file and format in one go.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivebe used multiple times in each server to cause each request to be
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivelogged to multiple files.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<LI>This module is based on mod_log_config distributed with
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveprevious Apache releases, now updated to handle multiple logs.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThere is now no need to re-configure Apache to use configuration log
5f48875017569cc7610b17d852c44e02684d9d5aerikabele<LI>The module also implements the <CODE>CookieLog</CODE> directive,
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveused to log user-tracking information created by <A
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveHREF="mod_usertrack.html">mod_usertrack</A>. The use of
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<CODE>CookieLog</CODE> is deprecated, and a <CODE>CustomLog</CODE>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveshould be defined to log user-tracking information instead.
3114b83fa8f03492a3e36809e875dec55b68a79dpepperUnless told otherwise with <TT>LogFormat</TT> the log files created by
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<TT>TransferLog</TT> will be in standard "Common Log Format"
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive(CLF). The contents of each line in a CLF file are explained
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivebelow. Alternatively, the log file can be customized (and if multiple
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivelog files are used, each can have a different format). Custom formats
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveare set with <CODE>LogFormat</CODE> and <CODE>CustomLog</CODE>.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe Common Log Format (CLF) file contains a separate line for each
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliverequest. A line is composed of several tokens separated by spaces:
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<BLOCKQUOTE>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivehost ident authuser date request status bytes
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive</BLOCKQUOTE>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveIf a token does not have a value then it is represented by a hyphen (-).
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe meanings and values of these tokens are as follows:
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>The fully-qualified domain name of the client, or its IP number if the
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivename is not available.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveclient machine runs identd, then this is the identity information reported
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveby the client.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DT>authuser
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>If the request was for an password protected document, then this is
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivethe userid used in the request.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>The date and time of the request, in the following format:
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DL><DD><BLOCKQUOTE><CODE> date = [day/month/year:hour:minute:second zone] <BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveday = 2*digit<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivemonth = 3*letter<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveyear = 4*digit<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivehour = 2*digit<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveminute = 2*digit<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivesecond = 2*digit<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>The request line from the client, enclosed in double quotes
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>The three digit status code returned to the client.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>The number of bytes in the object returned to the client, not including
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveany headers.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<CODE>CustomLog</CODE> is a string. This string is logged to the log
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivefile for each request. It can contain literal characters copied into
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivethe log files, and `%' directives which are replaced in the log file
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveby the values as follows:
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...b: Bytes sent, excluding HTTP headers.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...{FOOBAR}e: The contents of the environment variable FOOBAR
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...h: Remote host
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...{Foobar}i: The contents of Foobar: header line(s) in the request
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive sent to the server.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...l: Remote logname (from identd, if supplied)
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...{Foobar}n: The contents of note "Foobar" from another module.
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgun%...p: The port the request was served to
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...P: The process ID of the child that serviced the request.
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...r: First line of request
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...s: Status. For requests that got internally redirected, this
5f48875017569cc7610b17d852c44e02684d9d5aerikabele is status of the *original* request --- %...>s for the last.
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...t: Time, in common log format time format
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...{format}t: The time, in the form given by format, which should
5f48875017569cc7610b17d852c44e02684d9d5aerikabele be in strftime(3) format.
5f48875017569cc7610b17d852c44e02684d9d5aerikabele%...T: The time taken to serve the request, in seconds.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...u: Remote user (from auth; may be bogus if return status (%s) is 401)
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgun%...U: The URL path requested.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...v: The name of the server (i.e. which virtual host?)
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe `...' can be nothing at all (e.g. <CODE>"%h %u %r %s %b"</CODE>), or it can
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveindicate conditions for inclusion of the item (which will cause it
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveto be replaced with `-' if the condition is not met). Note that
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivethere is no escaping performed on the strings from %r, %...i and
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive%...o; some with long memories may remember that I thought this was
181e56d8b348d301d615ccf5465ae600fee2867berikabelea bad idea, once upon a time, and I'm still not comfortable with
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveit, but it is difficult to see how to `do the right thing' with all
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveof `%..i', unless we URL-escape everything and break with CLF.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe forms of condition are a list of HTTP status codes, which may
181e56d8b348d301d615ccf5465ae600fee2867berikabeleor may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveUser-agent: on 400 errors and 501 errors (Bad Request, Not
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveImplemented) only; `%!200,304,302{Referer}i' logs Referer: on all
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliverequests which did <STRONG>not</STRONG> return some sort of normal status.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveNote that the common log format is defined by the string <CODE>"%h %l
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabele%u %t \"%r\" %s %b"</CODE>, which can be used as the basis for
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgunextending for format if desired (e.g. to add extra fields at the end).
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveNCSA's extended/combined log format would be <CODE>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE>.
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabeleThe <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabelebe given more than once to log requests to multiple log files. Each
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabelerequest will be logged to all the log files defined by either of these
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgunIf a <VirtualHost> section does not contain any
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<TT>TransferLog</TT> or <TT>CustomLog</TT> directives, the
181e56d8b348d301d615ccf5465ae600fee2867berikabelelogs defined for the main server will be used. If it does
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivecontain one or more of these directives, requests serviced by
181e56d8b348d301d615ccf5465ae600fee2867berikabelethis virtual host will only be logged in the log files defined
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivewithin its definition, not in any of the main server's log files.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveSee the examples below.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveSee the <A HREF="/misc/security_tips.html#security">security tips</A>
181e56d8b348d301d615ccf5465ae600fee2867berikabeledocument for details on why your security could be compromised if the
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivedirectory where logfiles are stored is writable by anyone other than
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivethe user that starts the server.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<!--%plaintext <?INDEX {\tt CookieLog} directive> -->
181e56d8b348d301d615ccf5465ae600fee2867berikabele<STRONG>Syntax:</STRONG> CookieLog <EM>filename</EM><BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<Strong>Context:</STRONG> server config, virtual host<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<STRONG>Compatibility:</STRONG> Only available in Apache 1.2 and above<P>
181e56d8b348d301d615ccf5465ae600fee2867berikabeleThe CookieLog directive sets the filename for logging of cookies.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe filename is relative to the <A
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveHREF="core.html#serverroot">ServerRoot</A>. This directive is included
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveonly for compatibility with <A
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveHREF="mod_cookies.html">mod_cookies</A>, and is deprecated.
5f48875017569cc7610b17d852c44e02684d9d5aerikabele<STRONG>Syntax:</STRONG> CustomLog <EM>file-pipe</EM>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<STRONG>Context:</STRONG> server config, virtual host<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<STRONG>Compatibility: </STRONG> Nickname only available in Apache 1.3
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe first argument is the filename to which log records should be
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivewritten. This is used
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveexactly like the argument to
181e56d8b348d301d615ccf5465ae600fee2867berikabele HREF="#transferlog"
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivethat is, it is either a full path or relative to the current
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveserver root.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe format argument specifies a format for each line of the log file.
181e56d8b348d301d615ccf5465ae600fee2867berikabeleThe options available for the format are exactly the same as for
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivethe argument of the <TT>LogFormat</TT> directive. If the format
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveincludes any spaces (which it will do in almost all cases) it
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveshould be enclosed in double quotes.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveInstead of an actual format string, you can use a format nickname defined with
5f48875017569cc7610b17d852c44e02684d9d5aerikabele HREF="#logformat"
181e56d8b348d301d615ccf5465ae600fee2867berikabele<!--%plaintext <?INDEX {\tt LogFormat} directive> -->
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<STRONG>Syntax:</STRONG> LogFormat <EM>format</EM> [<EM>nickname</EM>]
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<STRONG>Default:</STRONG> <CODE>LogFormat "%h %l %u %t \"%r\"
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgun<Strong>Context:</STRONG> server config, virtual host<BR>
181e56d8b348d301d615ccf5465ae600fee2867berikabele<STRONG>Compatibility: </STRONG> Nickname only available in Apache 1.3
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabeleThis sets the format of the default logfile named by the
181e56d8b348d301d615ccf5465ae600fee2867berikabele HREF="#transferlog"
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivedirective . See the section on
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<A HREF="#formats">Custom Log Formats</A> for details on the format
181e56d8b348d301d615ccf5465ae600fee2867berikabeleIf you include a nickname for the format on the directive line, you can
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive HREF="#customlog"
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivedirectives rather than repeating the entire format string.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<SAMP>LogFormat</SAMP> directive which defines a nickname <STRONG>does
181e56d8b348d301d615ccf5465ae600fee2867berikabelenothing else</STRONG> -- that is, it <EM>only</EM> defines the nickname,
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveit doesn't actually apply the format and make it the default.
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabele<!--%plaintext <?INDEX {\tt TransferLog} directive> -->
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgun<STRONG>Syntax:</STRONG> TransferLog <EM>file-pipe</EM><BR>
181e56d8b348d301d615ccf5465ae600fee2867berikabele<Strong>Context:</STRONG> server config, virtual host<BR>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveThe TransferLog directive adds a log file in the format defined by the
41dd95074cc6924ee56c53ba11aa6faf59b2ee13erikabele HREF="#logformat"
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slivedirective, or Common Log Format if no other default format has been
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DT> `|' followed by a command
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<DD>A program to receive the agent log information on its standard input.
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliveNote the a new program will not be started for a VirtualHost if it inherits
60fdc5709bfeedd9539e279b5a5f46b3c610483bnilgunthe TransferLog from the main server.
181e56d8b348d301d615ccf5465ae600fee2867berikabele<STRONG>Security:</STRONG> if a program is used, then it will be
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383sliverun under the user who started httpd. This will be root if the server
181e56d8b348d301d615ccf5465ae600fee2867berikabelewas started by root; be sure that the program is secure.<P>
ca0e3098838c1f9aa77bcdfc3df99cf9aa0f9383slive<!--#include virtual="footer.html" -->