diff options
Diffstat (limited to 'docs/manual/mod/mod_log_config.html')
| -rw-r--r-- | docs/manual/mod/mod_log_config.html | 476 |
1 files changed, 0 insertions, 476 deletions
diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html deleted file mode 100644 index c007eb7281..0000000000 --- a/docs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,476 +0,0 @@ -<!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. -%...D: The time taken to serve the request, in microseconds. -%...{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> --> -<p><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 mod_cookies, 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\"" - TransferLog logs/access_log -</pre> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> |