httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <sl...@finance.commerce.ubc.ca>
Subject mod_log_config.html update
Date Sat, 09 Dec 2000 02:02:57 GMT

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\" %&gt;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\" %&gt;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\" %&gt;s %b"</CODE></dd>
+
+<dt>NCSA extended/combined log format</dt>
+<dd> <CODE>"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE></dd>
+
+<dt>Referer log format</dt>
+<dd><code>"%{Referer}i -&gt; %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 &quot;%h %l %u %t \&quot;%r\&quot; %&gt;s %b&quot; common
+     CustomLog logs/access_log common
+
+     # CustomLog alone
+     CustomLog logs/access_log &quot;%h %l %u %t \&quot;%r\&quot; %&gt;s
%b&quot;
+</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" -->


Mime
View raw message