| <!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> |