5544N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
5544N/A<
TITLE>Apache module mod_log_config</
TITLE>
5544N/A<!-- Background white, links blue (unvisited), navy (visited), red (active) --> 5544N/A<
H1 ALIGN="CENTER">Module mod_log_config</
H1>
5544N/Aand is compiled in by default in Apache 1.2. mod_log_config replaces
5544N/Amod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
5544N/Aan optional module. It provides for logging of the requests made to
5544N/Athe server, using the Common Log Format or a user-specified format.
5544N/AThree directives are provided by this module: <
CODE>TransferLog</
CODE>
5544N/Ato create a log file, <
CODE>LogFormat</
CODE> to set a custom format,
5544N/Aand <
CODE>CustomLog</
CODE> to define a log file and format in one go.
5544N/AThe <
CODE>TransferLog</
CODE> and <
CODE>CustomLog</
CODE> directives can
5544N/Abe used multiple times in each server to cause each request to be
5544N/A<
h3>Compatibility notes</
h3>
5544N/A<
LI>This module is based on mod_log_config distributed with
5544N/Aprevious Apache releases, now updated to handle multiple logs.
5544N/AThere is now no need to re-configure Apache to use configuration log
5544N/A<
LI>The module also implements the <
CODE>CookieLog</
CODE> directive,
5544N/Aused to log user-tracking information created by <
A 5544N/A<
CODE>CookieLog</
CODE> is deprecated, and a <
CODE>CustomLog</
CODE>
5544N/Ashould be defined to log user-tracking information instead.
5544N/AUnless told otherwise with <
TT>LogFormat</
TT> the log files created by
5544N/A<
TT>TransferLog</
TT> will be in standard "Common Log Format"
5544N/A(CLF). The contents of each line in a CLF file are explained
5544N/Abelow. Alternatively, the log file can be customized (and if multiple
5544N/Alog files are used, each can have a different format). Custom formats
5544N/Aare set with <
CODE>LogFormat</
CODE> and <
CODE>CustomLog</
CODE>.
5544N/AThe Common Log Format (CLF) file contains a separate line for each
5544N/Arequest. A line is composed of several tokens separated by spaces:
5544N/Ahost ident authuser date request status bytes
5544N/AIf a token does not have a value then it is represented by a hyphen (-).
5544N/AThe meanings and values of these tokens are as follows:
5544N/A<
DD>The fully-qualified domain name of the client, or its IP number if the
5544N/A<
DD>If <
A HREF="core.html#identitycheck">IdentityCheck</
A> is enabled and the
5544N/Aclient machine runs identd, then this is the identity information reported
5544N/A<
DD>If the request was for an password protected document, then this is
5544N/Athe userid used in the request.
5544N/A<
DD>The date and time of the request, in the following format:
5544N/Azone = (`+' | `-') 4*digit</
CODE></
BLOCKQUOTE></
DL>
5544N/A<
DD>The request line from the client, enclosed in double quotes
5544N/A<
DD>The three digit status code returned to the client.
5544N/A<
DD>The number of bytes in the object returned to the client, not including
5544N/A<
h3><
A NAME="formats">Custom Log Formats</
A></
h3>
5544N/AThe format argument to the <
CODE>LogFormat</
CODE> and
5544N/A<
CODE>CustomLog</
CODE> is a string. This string is logged to the log
5544N/Afile for each request. It can contain literal characters copied into
5544N/Athe log files, and `%' directives which are replaced in the log file
5544N/A%...{FOOBAR}e: The contents of the environment variable FOOBAR
5544N/A%...{Foobar}i: The contents of Foobar: header line(s) in the request
5544N/A%
...l: Remote logname (from identd, if supplied)
5544N/A%...{Foobar}n: The contents of note "Foobar" from another module.
5544N/A%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
5544N/A%
...P: The process ID of the child that serviced the request.
5544N/A%
...s: Status. For requests that got internally redirected, this
5544N/A is status of the *original* request --- %...>s for the last.
5544N/A%...{format}t: The time, in the form given by format, which should
5544N/A%
...T: The time taken to serve the request, in seconds.
5544N/A%
...u: Remote user (from auth; may be bogus if return status (%s) is 401)
5544N/AThe `...' can be nothing at all (
e.g. <
CODE>"%h %u %r %s %b"</
CODE>), or it can
5544N/Aindicate conditions for inclusion of the item (which will cause it
5544N/Ato be replaced with `-' if the condition is not met). Note that
5544N/Athere is no escaping performed on the strings from %r, %
...i and
5544N/A%
...o; some with long memories may remember that I thought this was
5544N/Aa bad idea, once upon a time, and I'm still not comfortable with
5544N/Ait, but it is difficult to see how to `do the right thing' with all
5544N/Aof `%
..i', unless we URL-escape everything and break with CLF.
5544N/AThe forms of condition are a list of HTTP status codes, which may
5544N/Aor may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs
5544N/AUser-agent: on 400 errors and 501 errors (Bad Request, Not
5544N/AImplemented) only; `%!200,304,302{Referer}i' logs Referer: on all
5544N/Arequests which did <
STRONG>not</
STRONG> return some sort of normal status.
5544N/ANote that the common log format is defined by the string <
CODE>"%h %l
5544N/A%u %t \"%r\" %s %b"</
CODE>, which can be used as the basis for
5544N/Aextending for format if desired (
e.g. to add extra fields at the end).
5544N/ANCSA's
extended/
combined log format would be <
CODE>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</
CODE>.
5544N/A<
h2>Using Multiple Log Files</
h2>
5544N/AThe <
CODE>TransferLog</
CODE> and <
CODE>CustomLog</
CODE> directives can
5544N/Abe given more than once to log requests to multiple log files. Each
5544N/Arequest will be logged to all the log files defined by either of these
5544N/A<
h3>Use with Virtual Hosts</
h3>
5544N/AIf a <VirtualHost> section does not contain any
5544N/A<
TT>TransferLog</
TT> or <
TT>CustomLog</
TT> directives, the
5544N/Alogs defined for the main server will be used. If it does
5544N/Acontain one or more of these directives, requests serviced by
5544N/Athis virtual host will only be logged in the log files defined
5544N/Awithin its definition, not in any of the main server's log files.
5544N/A<
h2>Security Considerations</
h2>
5544N/Adocument for details on why your security could be compromised if the
5544N/Adirectory where logfiles are stored is writable by anyone other than
5544N/Athe user that starts the server.
5544N/A<
LI><
A HREF="#cookielog">CookieLog</
A>
5544N/A<
LI><
A HREF="#customlog">CustomLog</
A>
5544N/A<
LI><
A HREF="#logformat">LogFormat</
A>
5544N/A<
LI><
A HREF="#transferlog">TransferLog</
A>
5544N/A<
h2><
A name="cookielog">CookieLog</
A></
h2>
5544N/A<!--%plaintext <?INDEX {\tt CookieLog} directive> --> 5544N/A><
STRONG>Syntax:</
STRONG></
A> CookieLog <
EM>filename</
EM><
BR>
5544N/A><
STRONG>Context:</
STRONG></
A> server config, virtual host<
BR>
5544N/A><
STRONG>Module:</
STRONG></
A> mod_cookies<
BR>
5544N/A><
STRONG>Compatibility:</
STRONG></
A> Only available in Apache 1.2 and above<
P>
5544N/AThe CookieLog directive sets the filename for logging of cookies.
5544N/AThe filename is relative to the <
A 5544N/Aonly for compatibility with <
A 5544N/A<
H2><
A NAME="customlog">CustomLog</
A></
H2>
5544N/A><
STRONG>Syntax:</
STRONG></
A> CustomLog <
EM>file-pipe</
EM>
5544N/A <
EM>format-or-nickname</
EM><
BR>
5544N/A><
STRONG>Context:</
STRONG></
A> server config, virtual host<
BR>
5544N/A><
STRONG>Status:</
STRONG></
A> Base<
BR>
5544N/A<
STRONG>Compatibility: </
STRONG> Nickname only available in Apache 1.3
5544N/A><
STRONG>Module:</
STRONG></
A> mod_log_config
5544N/AThe first argument is the filename to which log records should be
5544N/Aexactly like the argument to
5544N/A><
SAMP>TransferLog</
SAMP></
A>;
5544N/Athat is, it is either a full path or relative to the current
5544N/AThe format argument specifies a format for each line of the log file.
5544N/AThe options available for the format are exactly the same as for
5544N/Athe argument of the <
TT>LogFormat</
TT> directive. If the format
5544N/Aincludes any spaces (which it will do in almost all cases) it
5544N/Ashould be enclosed in double quotes.
5544N/AInstead of an actual format string, you can use a format nickname defined with
5544N/A<
h2><
A name="logformat">LogFormat</
A></
h2>
5544N/A<!--%plaintext <?INDEX {\tt LogFormat} directive> --> 5544N/A><
STRONG>Syntax:</
STRONG></
A> LogFormat <
EM>format</
EM> [<
EM>nickname</
EM>]
5544N/A><
STRONG>Default:</
STRONG></
A> <
CODE>LogFormat "%h %l %u %t \"%r\"
5544N/A><
STRONG>Context:</
STRONG></
A> server config, virtual host<
BR>
5544N/A><
STRONG>Status:</
STRONG></
A> Base<
BR>
5544N/A<
STRONG>Compatibility: </
STRONG> Nickname only available in Apache 1.3
5544N/A><
STRONG>Module:</
STRONG></
A> mod_log_config
5544N/AThis sets the format of the default logfile named by the
5544N/A><
SAMP>TransferLog</
SAMP></
A>
5544N/Adirective . See the section on
5544N/A<
A HREF="#formats">Custom Log Formats</
A> for details on the format
5544N/AIf you include a nickname for the format on the directive line, you can
5544N/Ause it in other <
SAMP>LogFormat</
SAMP> and
5544N/Adirectives rather than repeating the entire format string.
5544N/A<
SAMP>LogFormat</
SAMP> directive which defines a nickname <
STRONG>does
5544N/Anothing else</
STRONG> -- that is, it <
EM>only</
EM> defines the nickname,
5544N/Ait doesn't actually apply the format and make it the default.
5544N/A<
h2><
A name="transferlog">TransferLog</
A></
h2>
5544N/A<!--%plaintext <?INDEX {\tt TransferLog} directive> --> 5544N/A><
STRONG>Syntax:</
STRONG></
A> TransferLog <
EM>file-pipe</
EM><
BR>
5544N/A><
STRONG>Default:</
STRONG></
A> none<
BR>
5544N/A><
STRONG>Context:</
STRONG></
A> server config, virtual host<
BR>
5544N/A><
STRONG>Status:</
STRONG></
A> Base<
BR>
5544N/A><
STRONG>Module:</
STRONG></
A> mod_log_config<
P>
5544N/AThe TransferLog directive adds a log file in the format defined by the
5544N/Adirective, or Common Log Format if no other default format has been
5544N/A<
DD>A filename relative to the <
A HREF="core.html#serverroot">ServerRoot</
A>.
5544N/A<
DT> `|' followed by a command
5544N/A<
DD>A program to receive the agent log information on its standard input.
5544N/ANote the a new program will not be started for a VirtualHost if it inherits
5544N/Athe TransferLog from the main server.
5544N/A<
STRONG>Security:</
STRONG> if a program is used, then it will be
5544N/Arun under the user who started httpd. This will be root if the server
5544N/Awas started by root; be sure that the program is secure.<
P>