I was just playing with correcting the syntax and wound up with a significant rewrite of mod_log_config.html. So, I decided to post for feedback before I commit.
The full file is available at http://garibaldi.commerce.ubc.ca:8080/ap13/htdocs/manual/mod/mod_log_config.html Joshua Index: mod_log_config.html =================================================================== RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_log_config.html,v retrieving revision 1.41 diff -u -d -b -r1.41 mod_log_config.html --- mod_log_config.html 2000/11/22 03:36:16 1.41 +++ mod_log_config.html 2000/12/09 01:59:54 @@ -45,7 +45,7 @@ <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. +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. @@ -61,7 +61,7 @@ <LI><A HREF="#transferlog">TransferLog</A> </UL> -<H3>Compatibility notes</H3> +<H2>Compatibility notes</H2> <UL> <LI>This module is based on mod_log_config distributed with @@ -75,12 +75,11 @@ <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>As of Apache 1.3.5, this module allows conditional logging based +upon the setting of <a href="../env.html">environment variables</a>. +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 @@ -93,17 +92,17 @@ <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 +<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>. +are set with <CODE>LogFormat</CODE> and <CODE>CustomLog</CODE>.</p> <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: +<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 @@ -186,30 +185,38 @@ %...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 +<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. +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> -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>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>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> @@ -281,8 +288,8 @@ <A HREF="directive-dict.html#Syntax" REL="Help" -><STRONG>Syntax:</STRONG></A> CustomLog <EM>file-pipe</EM> - <EM>format-or-nickname</EM><BR> +><STRONG>Syntax:</STRONG></A> CustomLog <EM>file|pipe</EM> + <EM>format|nickname</EM><BR> <A HREF="directive-dict.html#Context" REL="Help" @@ -301,39 +308,49 @@ 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> +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 previeous <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> + # LogFormat + CustomLog + LogFormat "%h %l %u %t \"%r\" %>s %b" common + CustomLog logs/access_log common + + # CustomLog alone + CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b" +</pre> + <HR> <H2><A NAME="customlog-conditional">CustomLog (conditional)</A> directive</H2> <A HREF="directive-dict.html#Syntax" REL="Help" -><STRONG>Syntax:</STRONG></A> CustomLog <EM>file-pipe</EM> - <EM>format-or-nickname</EM> +><STRONG>Syntax:</STRONG></A> CustomLog <EM>file|pipe</EM> + <EM>format|nickname</EM> env=[!]<EM>environment-variable</EM><BR> <A HREF="directive-dict.html#Context" @@ -383,7 +400,8 @@ <A HREF="directive-dict.html#Syntax" REL="Help" -><STRONG>Syntax:</STRONG></A> LogFormat <EM>format</EM> [<EM>nickname</EM>] +><STRONG>Syntax:</STRONG></A> LogFormat <EM>format|nickname</EM> + [<EM>nickname</EM>] <BR> <A HREF="directive-dict.html#Default" @@ -408,26 +426,28 @@ 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 + +<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 explict <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. +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> @@ -437,7 +457,7 @@ <A HREF="directive-dict.html#Syntax" REL="Help" -><STRONG>Syntax:</STRONG></A> TransferLog <EM>file-pipe</EM><BR> +><STRONG>Syntax:</STRONG></A> TransferLog <EM>file|pipe</EM><BR> <A HREF="directive-dict.html#Default" REL="Help" @@ -455,25 +475,13 @@ 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 +<p>This directive has exactly the same arguments and effect +as the <a href="#customlog">CustomLog</a> directive, with the +exeption that it does not allow the log format to +be specified explictly. Instead, the log format is determined by +the most recently specified specified <a href="#logformat">LogFormat</a> +directive. Common Log Format is used if no other 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" -->
