mirror of
https://github.com/apache/httpd.git
synced 2025-05-19 02:21:09 +03:00
376ad0e880
PR: 4366, 679 Submitted by: Petr Lampa <lampa@fee.vutbr.cz> git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@83211 13f79535-47bb-0310-9956-ffa450edef68
450 lines
15 KiB
HTML
450 lines
15 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 is contained in the <CODE>mod_log_config.c</CODE> file,
|
|
and is compiled in by default in Apache 1.2. mod_log_config replaces
|
|
mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
|
|
an optional module. It provides for logging of the requests made to
|
|
the server, using the Common Log Format or a user-specified format.
|
|
</P>
|
|
|
|
<H2>Summary</H2>
|
|
<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 go.
|
|
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>
|
|
|
|
<H3>Compatibility notes</H3>
|
|
|
|
<UL>
|
|
<LI>This module is based on mod_log_config distributed with
|
|
previous Apache releases, now updated to handle multiple logs.
|
|
There is now no need to re-configure Apache to use configuration log
|
|
formats.
|
|
|
|
<LI>The module also implements the <CODE>CookieLog</CODE> directive,
|
|
used to log user-tracking information created by <A
|
|
HREF="mod_usertrack.html">mod_usertrack</A>. The use of
|
|
<CODE>CookieLog</CODE> is deprecated, and a <CODE>CustomLog</CODE>
|
|
should be defined to log user-tracking information instead.
|
|
|
|
<LI>As of Apache 1.3.5, this module allows conditional logging
|
|
based upon the setting of environment variables. That is,
|
|
you can control whether a request should be logged or not
|
|
based upon whether an arbitrary environment variable is
|
|
defined or not. This is settable on a <EM>per</EM>-logfile
|
|
basis.
|
|
|
|
<LI>Beginning with Apache 1.3.5, the mod_log_config module has
|
|
also subsumed the <CODE>RefererIgnore</CODE> functionality from
|
|
<A HREF="mod_log_referer.html">mod_log_referer</A>. The effect
|
|
of <CODE>RefererIgnore</CODE> can be achieved by combinations of
|
|
<A HREF="mod_setenvif.html"><CODE>SetEnvIf</CODE></A> directives
|
|
and conditional <CODE>CustomLog</CODE> definitions.
|
|
|
|
</UL>
|
|
|
|
<H2>Log File Formats</H2>
|
|
|
|
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>.
|
|
|
|
<H3>Common Log Format</H3>
|
|
|
|
The Common Log Format (CLF) file contains a separate line for each
|
|
request. A line is composed of several tokens separated by spaces:
|
|
|
|
<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>
|
|
|
|
The format argument to the <CODE>LogFormat</CODE> and
|
|
<CODE>CustomLog</CODE> 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 `%' directives which are replaced in the log file
|
|
by the values as follows:
|
|
|
|
<PRE>
|
|
%...b: Bytes sent, excluding HTTP headers.
|
|
%...f: Filename
|
|
%...{FOOBAR}e: The contents of the environment variable FOOBAR
|
|
%...h: Remote host
|
|
%...a: Remote IP-address
|
|
%...{Foobar}i: The contents of Foobar: header line(s) in the request
|
|
sent to the server.
|
|
%...l: Remote logname (from identd, if supplied)
|
|
%...{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.
|
|
%...r: First line of request
|
|
%...s: Status. For requests that got internally redirected, this
|
|
is 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 localised)
|
|
%...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>
|
|
|
|
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). Note that
|
|
there is no escaping performed on the strings from %r, %...i and
|
|
%...o; some with long memories may remember that I thought this was
|
|
a bad idea, once upon a time, and I'm still not comfortable with
|
|
it, but it is difficult to see how to `do the right thing' with all
|
|
of `%..i', unless we URL-escape everything and break with CLF.
|
|
|
|
<P>
|
|
|
|
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>
|
|
|
|
Note that the common log format is defined by the string <CODE>"%h %l
|
|
%u %t \"%r\" %s %b"</CODE>, which can be used as the basis for
|
|
extending for format if desired (<EM>e.g.</EM>, to add extra fields at the end).
|
|
NCSA's extended/combined log format would be <CODE>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE>.
|
|
|
|
<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.
|
|
|
|
<H2>Using Multiple Log Files</H2>
|
|
|
|
The <CODE>TransferLog</CODE> and <CODE>CustomLog</CODE> directives can
|
|
be given more than once to log requests to multiple log files. Each
|
|
request will be logged to all the log files defined by either of these
|
|
directives.
|
|
|
|
<H3>Use with Virtual Hosts</H3>
|
|
|
|
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>
|
|
|
|
See the <A HREF="../misc/security_tips.html#security">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>Directives</H2>
|
|
|
|
<UL>
|
|
<LI><A HREF="#cookielog">CookieLog</A>
|
|
<LI><A HREF="#customlog">CustomLog</A>
|
|
<LI><A HREF="#customlog-conditional">CustomLog (conditional)</A>
|
|
<LI><A HREF="#logformat">LogFormat</A>
|
|
<LI><A HREF="#transferlog">TransferLog</A>
|
|
</UL>
|
|
<HR>
|
|
|
|
|
|
<H2><A NAME="cookielog">CookieLog</A></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>
|
|
|
|
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></H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> CustomLog <EM>file-pipe</EM>
|
|
<EM>format-or-nickname</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
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_log_config
|
|
<P>
|
|
The first argument is the filename to which log records should be
|
|
written. This is used
|
|
exactly like the argument to
|
|
<A
|
|
HREF="#transferlog"
|
|
><SAMP>TransferLog</SAMP></A>;
|
|
that is, it is either a full path or relative to the current
|
|
server root.
|
|
</P>
|
|
<P>
|
|
The format argument specifies a format for each line of the log file.
|
|
The options available for the format are exactly the same as for
|
|
the argument of the <TT>LogFormat</TT> directive. If the format
|
|
includes any spaces (which it will do in almost all cases) it
|
|
should be enclosed in double quotes.
|
|
</P>
|
|
<P>
|
|
Instead of an actual format string, you can use a format nickname defined with
|
|
the
|
|
<A
|
|
HREF="#logformat"
|
|
><SAMP>LogFormat</SAMP></A>
|
|
directive.
|
|
</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="customlog-conditional">CustomLog (conditional)</A></H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> CustomLog <EM>file-pipe</EM>
|
|
<EM>format-or-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> Only available in Apache 1.3.5
|
|
or later
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_log_config
|
|
<P>
|
|
|
|
The behaviour of this form of the <SAMP>CustomLog</SAMP> directive is almost
|
|
identical to the <A HREF="#customlog">standard <CODE>CustomLog</CODE></A>
|
|
directive. The difference is that the '<CODE>env=</CODE>' clause controls
|
|
whether a particular request will be logged in the specified file or
|
|
not. If the specified environment variable 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></H2>
|
|
<!--%plaintext <?INDEX {\tt LogFormat} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> LogFormat <EM>format</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>
|
|
This sets the format of the default logfile named by the
|
|
<A
|
|
HREF="#transferlog"
|
|
><SAMP>TransferLog</SAMP></A>
|
|
directive . See the section on
|
|
<A HREF="#formats">Custom Log Formats</A> for details on the format
|
|
arguments.
|
|
</P>
|
|
<P>
|
|
If you include a nickname for the format on the directive line, you can
|
|
use it in other <SAMP>LogFormat</SAMP> and
|
|
<A HREF="#customlog"><SAMP>CustomLog</SAMP></A>
|
|
directives rather than repeating the entire format string.
|
|
</P>
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="transferlog">TransferLog</A></H2>
|
|
<!--%plaintext <?INDEX {\tt TransferLog} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> TransferLog <EM>file-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>
|
|
|
|
The TransferLog directive adds a log file in the format defined by the
|
|
most recent
|
|
<A
|
|
HREF="#logformat"
|
|
><SAMP>LogFormat</SAMP></A>
|
|
directive, or Common Log Format if no other default format has been
|
|
specified.
|
|
<EM>File-pipe</EM> is one
|
|
of
|
|
<DL><DT>A filename
|
|
<DD>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>.
|
|
<DT> `|' followed by a command
|
|
<DD>A program to receive the agent log information on its standard input.
|
|
Note the a new program will not be started for a VirtualHost if it inherits
|
|
the TransferLog from the main server.
|
|
</DL>
|
|
<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.<P>
|
|
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|