mirror of
https://github.com/apache/httpd.git
synced 2025-05-17 15:21:13 +03:00
d56f872d3e
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87879 13f79535-47bb-0310-9956-ffa450edef68
477 lines
17 KiB
HTML
477 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_log_config</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
<H1 ALIGN="CENTER">Module mod_log_config</H1>
|
|
<P>
|
|
This module provides for logging of the requests made to
|
|
the server, using the Common Log Format or a user-specified format.
|
|
</P>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_log_config.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> config_log_module
|
|
</P>
|
|
|
|
|
|
<H2>Summary</H2>
|
|
|
|
<p>This module provides for flexible logging of client requests. Logs
|
|
are written in a customizable format, and may be written directly to a
|
|
file, or to an external program. Conditional logging is provided so
|
|
that individual requests may be included or excluded from the logs
|
|
based on characteristics of the request.</p>
|
|
|
|
<P>
|
|
Three directives are provided by this module: <CODE>TransferLog</CODE>
|
|
to create a log file, <CODE>LogFormat</CODE> to set a custom format,
|
|
and <CODE>CustomLog</CODE> to define a log file and format in one step.
|
|
The <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
|
|
be used multiple times in each server to cause each request to be
|
|
logged to multiple files.
|
|
</P>
|
|
|
|
<H2>Directives</H2>
|
|
|
|
<UL>
|
|
<LI><A HREF="#cookielog">CookieLog</A></LI>
|
|
<LI><A HREF="#customlog">CustomLog</A></LI>
|
|
<LI><A HREF="#logformat">LogFormat</A></LI>
|
|
<LI><A HREF="#transferlog">TransferLog</A></LI>
|
|
</UL>
|
|
|
|
<H2>Log File Formats</H2>
|
|
|
|
<p>Unless told otherwise with <TT>LogFormat</TT>, the log files
|
|
created by <TT>TransferLog</TT> will be in standard "Common Log
|
|
Format" (CLF). The contents of each line in a CLF file are explained
|
|
below. Alternatively, the log file can be customized (and if multiple
|
|
log files are used, each can have a different format). Custom formats
|
|
are set with <CODE>LogFormat</CODE> and <CODE>CustomLog</CODE>.</p>
|
|
|
|
<H3>Common Log Format</H3>
|
|
|
|
<p>The Common Log Format (CLF) file contains a separate line for each
|
|
request. A line is composed of several tokens separated by spaces:</p>
|
|
|
|
<BLOCKQUOTE>
|
|
host ident authuser date request status bytes
|
|
</BLOCKQUOTE>
|
|
If a token does not have a value then it is represented by a hyphen (-).
|
|
The meanings and values of these tokens are as follows:
|
|
<DL>
|
|
<DT>host
|
|
<DD>The fully-qualified domain name of the client, or its IP number if the
|
|
name is not available.
|
|
<DT>ident
|
|
<DD>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
|
|
client machine runs identd, then this is the identity information reported
|
|
by the client.
|
|
<DT>authuser
|
|
<DD>If the request was for an password protected document, then this is
|
|
the userid used in the request.
|
|
<DT>date
|
|
<DD>The date and time of the request, in the following format:
|
|
<DL><DD><BLOCKQUOTE><CODE> date = [day/month/year:hour:minute:second zone] <BR>
|
|
day = 2*digit<BR>
|
|
month = 3*letter<BR>
|
|
year = 4*digit<BR>
|
|
hour = 2*digit<BR>
|
|
minute = 2*digit<BR>
|
|
second = 2*digit<BR>
|
|
zone = (`+' | `-') 4*digit</CODE></BLOCKQUOTE></DL>
|
|
<DT>request
|
|
<DD>The request line from the client, enclosed in double quotes
|
|
(<CODE>"</CODE>).
|
|
<DT>status
|
|
<DD>The three digit status code returned to the client.
|
|
<DT>bytes
|
|
<DD>The number of bytes in the object returned to the client, not including
|
|
any headers.
|
|
</DL>
|
|
|
|
<H3><A NAME="formats">Custom Log Formats</A></H3>
|
|
|
|
<p>The format argument to the <CODE>LogFormat</CODE> and
|
|
<CODE>CustomLog</CODE> directives is a string. This string is logged
|
|
to the log file for each request. It can contain literal characters
|
|
copied into the log files and the c-type control characters "\n" and
|
|
"\t" to represent new-lines and tabs. Literal quotes and back-slashes
|
|
should be escaped with back-slashes.</p>
|
|
|
|
<p>The characteristics of the request itself are logged by placing
|
|
"%" directives in the format string, which are replaced in the log file
|
|
by the values as follows:</p>
|
|
|
|
<PRE>
|
|
%...a: Remote IP-address
|
|
%...A: Local IP-address
|
|
%...B: Bytes sent, excluding HTTP headers.
|
|
%...b: Bytes sent, excluding HTTP headers. In CLF format
|
|
i.e. a '-' rather than a 0 when no bytes are sent.
|
|
%...c: Connection status when response is completed.
|
|
'X' = connection aborted before the response completed.
|
|
'+' = connection may be kept alive after the response is sent.
|
|
'-' = connection will be closed after the response is sent.
|
|
%...{Foobar}C: The contents of cookie "Foobar" in the request sent to the
|
|
server.
|
|
%...{FOOBAR}e: The contents of the environment variable FOOBAR
|
|
%...f: Filename
|
|
%...h: Remote host
|
|
%...H The request protocol
|
|
%...{Foobar}i: The contents of Foobar: header line(s) in the request
|
|
sent to the server.
|
|
%...l: Remote logname (from identd, if supplied)
|
|
%...m The request method
|
|
%...{Foobar}n: The contents of note "Foobar" from another module.
|
|
%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
|
|
%...p: The canonical Port of the server serving the request
|
|
%...P: The process ID of the child that serviced the request.
|
|
%...q The query string (prepended with a ? if a query string exists,
|
|
otherwise an empty string)
|
|
%...r: First line of request
|
|
%...s: Status. For requests that got internally redirected, this is
|
|
the status of the *original* request --- %...>s for the last.
|
|
%...t: Time, in common log format time format (standard english format)
|
|
%...{format}t: The time, in the form given by format, which should
|
|
be in strftime(3) format. (potentially localized)
|
|
%...T: The time taken to serve the request, in seconds.
|
|
%...u: Remote user (from auth; may be bogus if return status (%s) is 401)
|
|
%...U: The URL path requested.
|
|
%...v: The canonical ServerName of the server serving the request.
|
|
%...V: The server name according to the UseCanonicalName setting.
|
|
</PRE>
|
|
|
|
<p>The "..." can be nothing at all (<EM>e.g.</EM>, <CODE>"%h %u %r %s
|
|
%b"</CODE>), or it can indicate conditions for inclusion of the item
|
|
(which will cause it to be replaced with "-" if the condition is not
|
|
met). The forms of condition are a list of HTTP status codes, which
|
|
may or may not be preceded by "!". Thus, "%400,501{User-agent}i" logs
|
|
User-agent: on 400 errors and 501 errors (Bad Request, Not
|
|
Implemented) only; "%!200,304,302{Referer}i" logs Referer: on all
|
|
requests which did <STRONG>not</STRONG> return some sort of normal
|
|
status.</p>
|
|
|
|
<p>Note that there is no escaping performed on the strings from
|
|
%...r, %...i and %...o. This is mainly to comply with the requirements
|
|
of the Common Log Format. This implies that clients can insert
|
|
control characters into the log, so care should be taken when dealing
|
|
with raw log files.</p>
|
|
|
|
<p>Some commonly used log format strings are:</p>
|
|
|
|
<dl>
|
|
<dt>Common Log Format (CLF)</dt>
|
|
<dd><CODE>"%h %l %u %t \"%r\" %>s %b"</CODE></dd>
|
|
|
|
<dt>Common Log Format with Virtual Host</dt>
|
|
<dd><code>"%v %h %l %u %t \"%r\" %>s %b"</CODE></dd>
|
|
|
|
<dt>NCSA extended/combined log format</dt>
|
|
<dd> <CODE>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE></dd>
|
|
|
|
<dt>Referer log format</dt>
|
|
<dd><code>"%{Referer}i -> %U"</code></dd>
|
|
|
|
<dt>Agent (Browser) log format</dt>
|
|
<dd><code>"%{User-agent}i"</code></dd>
|
|
</dl>
|
|
|
|
<P>Note that the canonical <A
|
|
HREF="core.html#servername">ServerName</A> and <A
|
|
HREF="core.html#port">Port</A> of the server serving the request are
|
|
used for <CODE>%v</CODE> and <CODE>%p</CODE> respectively. This
|
|
happens regardless of the <A
|
|
HREF="core.html#usecanonicalname">UseCanonicalName</A> setting because
|
|
otherwise log analysis programs would have to duplicate the entire
|
|
vhost matching algorithm in order to decide what host really served
|
|
the request.</p>
|
|
|
|
<H2>Using Multiple Log Files</H2>
|
|
|
|
<p>The <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
|
|
be given more than once to log requests to multiple log files. Unless
|
|
the conditional form of <code>CustomLog</code> is used, each
|
|
request will be logged to all the log files defined by either of these
|
|
directives.</p>
|
|
|
|
<H3>Use with Virtual Hosts</H3>
|
|
|
|
<p>If a <VirtualHost> section does not contain any
|
|
<TT>TransferLog</TT> or <TT>CustomLog</TT> directives, the
|
|
logs defined for the main server will be used. If it does
|
|
contain one or more of these directives, requests serviced by
|
|
this virtual host will only be logged in the log files defined
|
|
within its definition, not in any of the main server's log files.
|
|
See the examples below.</p>
|
|
|
|
<H2>Security Considerations</H2>
|
|
|
|
<p>See the <A HREF="../misc/security_tips.html#serverroot">security tips</A>
|
|
document for details on why your security could be compromised if the
|
|
directory where logfiles are stored is writable by anyone other than
|
|
the user that starts the server.</p>
|
|
|
|
<h2>Resetting the Log Files</h2>
|
|
|
|
<p>The access log file typically grows 1MB or more for each 10,000
|
|
requests. It will probably be necessary to move or delete the log
|
|
file on a regular basis. This cannot be done while the server is
|
|
still running, because Apache will continue writing to the old log
|
|
file. Instead, the server must be <a
|
|
href="../stopping.html">restarted</a> after the log file is moved or
|
|
deleted so that it will open a new log.</p>
|
|
|
|
<p>A typical scenario is:</p>
|
|
|
|
<pre>
|
|
mv access_log access_log.old
|
|
apachectl graceful
|
|
# wait for all requests to the old server to complete
|
|
# before doing anything with access_log.old
|
|
</pre>
|
|
|
|
<p>Alternatively, log files can be <a
|
|
href="../misc/FAQ.html#rotate">rotated automatically</a> be writing
|
|
them through a pipe to a program designed for that purpose such
|
|
as <a href="../programs/rotatelogs.html">rotatelogs</a>.</p>
|
|
|
|
<HR>
|
|
|
|
|
|
<H2><A NAME="cookielog">CookieLog</A> directive</H2>
|
|
<!--%plaintext <?INDEX {\tt CookieLog} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> CookieLog <EM>filename</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_cookies<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.2 and above</p>
|
|
|
|
<p>The CookieLog directive sets the filename for logging of cookies.
|
|
The filename is relative to the <A
|
|
HREF="core.html#serverroot">ServerRoot</A>. This directive is included
|
|
only for compatibility with <A
|
|
HREF="mod_cookies.html">mod_cookies</A>, and is deprecated.</p>
|
|
|
|
<HR>
|
|
<H2><A NAME="customlog">CustomLog</A>
|
|
<a NAME="#customlogconditional">directive</a></H2>
|
|
<p><A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> CustomLog <EM>file</em>|<em>pipe</EM>
|
|
<EM>format</em>|<em>nickname</EM> [env=[!]<EM>environment-variable</EM>]<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3
|
|
or later. Conditional logging available in 1.3.5 or later.
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_log_config</p>
|
|
|
|
<p>The <code>CustomLog</code> directive is used to log requests
|
|
to the server. A log format is specified, and the logging can
|
|
optionally be made conditional on request characteristics
|
|
using environment variables.</p>
|
|
|
|
<P>The first argument, which specifies the location to which the
|
|
logs will be written, can take on one of the following two
|
|
types of values:</p>
|
|
|
|
<dl>
|
|
<dt><em>file</em>
|
|
<dd>A filename, relative to the
|
|
<a href="core.html#serverroot">ServerRoot</a>.</dd>
|
|
|
|
<dt><em>pipe</em>
|
|
<dd>The pipe character "<code>|</code>", followed by the path to a
|
|
program to receive the log information on its standard input.
|
|
<STRONG>Security:</STRONG> if a program is used, then it will be run
|
|
under the user who started httpd. This will be root if the server was
|
|
started by root; be sure that the program is secure.</dd>
|
|
</dl>
|
|
|
|
<P>The second argument specifies what will be written to the
|
|
log file. It can specify either a <em>nickname</em>
|
|
defined by a previous <a href="#logformat">LogFormat</a>
|
|
directive, or it can be an explicit <em>format</em> string
|
|
as described in the <a href="#formats">log formats</a> section.</p>
|
|
|
|
<p>For example, the following two sets of directives have exactly
|
|
the same effect:</p>
|
|
|
|
<pre>
|
|
# CustomLog with format nickname
|
|
LogFormat "%h %l %u %t \"%r\" %>s %b" common
|
|
CustomLog logs/access_log common
|
|
|
|
# CustomLog with explicit format string
|
|
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
|
|
</pre>
|
|
|
|
<p>The third argument is optional and allows the decision on whether
|
|
or not to log a particular request to be based on the presence or
|
|
absence of a particular variable in the server environment. If the
|
|
specified <a href="../env.html">environment variable</a> is set for
|
|
the request (or is not set, in the case of a
|
|
'<CODE>env=!<EM>name</EM></CODE>' clause), then the request will be
|
|
logged.</P>
|
|
|
|
<P>Environment variables can be set on a <EM>per</EM>-request basis
|
|
using the <A HREF="mod_setenvif.html">mod_setenvif</A> and/or <A
|
|
HREF="mod_rewrite.html">mod_rewrite</A> modules. For example, if you
|
|
don't want to record requests for all GIF images on your server in a
|
|
separate logfile but not your main log, you can use:
|
|
</P>
|
|
<PRE>
|
|
SetEnvIf Request_URI \.gif$ gif-image
|
|
CustomLog gif-requests.log common env=gif-image
|
|
CustomLog nongif-requests.log common env=!gif-image
|
|
</PRE>
|
|
|
|
<HR>
|
|
<H2><A NAME="logformat">LogFormat</A> directive</H2>
|
|
<!--%plaintext <?INDEX {\tt LogFormat} directive> -->
|
|
<p><A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> LogFormat <EM>format</em>|<em>nickname</EM>
|
|
[<EM>nickname</EM>]
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <CODE>LogFormat "%h %l %u %t \"%r\"
|
|
%>s %b"</CODE><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3
|
|
or later
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_log_config</p>
|
|
|
|
<p>This directive specifies the format of the access log file.</p>
|
|
|
|
<p>The <code>LogFormat</code> directive can take one of two forms. In
|
|
the first form, where only one argument is specified, this directive
|
|
sets the log format which will be used by logs specified in subsequent
|
|
<a href="#transferlog">TransferLog</a> directives. The single
|
|
argument can specify an explicit <em>format</em> as discussed in <a
|
|
href="#formats">custom log formats</a> section above. Alternatively,
|
|
it can use a <em>nickname</em> to refer to a log format defined
|
|
in a previous <code>LogFormat</code> directive as described below.</p>
|
|
|
|
<p>The second form of the <code>LogFormat</code> directive associates
|
|
an explicit <em>format</em> with a <em>nickname</em>. This
|
|
<em>nickname</em> can then be used in subsequent
|
|
<code>LogFormat</code> or <a href="#customlog">CustomLog</a>
|
|
directives rather than repeating the entire format string. A
|
|
<SAMP>LogFormat</SAMP> directive which defines a nickname <STRONG>does
|
|
nothing else</STRONG> -- that is, it <EM>only</EM> defines the
|
|
nickname, it doesn't actually apply the format and make it the
|
|
default. Therefore, it will not affect subsequent <a
|
|
href="#transferlog">TransferLog</a> directives.
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="transferlog">TransferLog</A> directive</H2>
|
|
<!--%plaintext <?INDEX {\tt TransferLog} directive> -->
|
|
<p><A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> TransferLog <EM>file</em>|<em>pipe</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> none<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_log_config</p>
|
|
|
|
<p>This directive has exactly the same arguments and effect as the <a
|
|
href="#customlog">CustomLog</a> directive, with the exception that it
|
|
does not allow the log format to be specified explicitly or for
|
|
conditional logging of requests. Instead, the log format is
|
|
determined by the most recently specified specified <a
|
|
href="#logformat">LogFormat</a> directive (which does not define a
|
|
nickname). Common Log Format is used if no other format has been
|
|
specified.</p>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre>
|
|
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
|
|
TranferLog logs/access_log
|
|
</pre>
|
|
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|