| <!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> |
| %...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. |
| %...{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 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> |