diff options
Diffstat (limited to 'docs/manual/mod/mod_log_config.html')
| -rw-r--r-- | docs/manual/mod/mod_log_config.html | 449 |
1 files changed, 0 insertions, 449 deletions
diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html deleted file mode 100644 index e9bb199a42..0000000000 --- a/docs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,449 +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 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> -%...b: Bytes sent, excluding HTTP headers. -%...f: Filename -%...{FOOBAR}e: The contents of the environment variable FOOBAR -%...h: Remote host -%...a: Remote IP-address -%...{Foobar}i: The contents of Foobar: header line(s) in the request - sent to the server. -%...l: Remote logname (from identd, if supplied) -%...{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. -%...r: First line of request -%...s: Status. For requests that got internally redirected, this - is 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> |