From: Andre Malo Date: Mon, 18 Nov 2002 00:28:51 +0000 (+0000) Subject: - reformatting & markup X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3f9b040002b506e5b49cc9ab68210986c98a65b7;p=apache - reformatting & markup - zebra-styled log format table - changed the directive compat notes - mentioned, that nicknames should not contain % Reviewed by: Joshua Slive git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97559 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_log_config.xml b/docs/manual/mod/mod_log_config.xml index 4a9a510005..dbcc2e8886 100644 --- a/docs/manual/mod/mod_log_config.xml +++ b/docs/manual/mod/mod_log_config.xml @@ -10,7 +10,6 @@ log_config_module -

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. @@ -19,21 +18,21 @@ of the request.

Three directives are provided by this module: - TransferLog to create a log file, - LogFormat to set a custom format, and - CustomLog to define a log file and format in one - step. The TransferLog and CustomLog - directives can be used multiple times in each server to cause - each request to be logged to multiple files.

+ TransferLog to create + a log file, LogFormat + to set a custom format, and CustomLog to define a log file and format in one + step. The TransferLog and CustomLog directives can be used multiple times in each + server to cause each request to be logged to multiple files.

 - Apache Log Files -
-Custom Log Formats +
Custom Log Formats -

The format argument to the LogFormat and - CustomLog directives is a string. This string is +

The format argument to the LogFormat and CustomLog 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. @@ -41,212 +40,215 @@ back-slashes.

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:

+ placing "%" directives in the format string, which are + replaced in the log file by the values as follows:

+ + + + -
Format StringDescription
+ + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - +
%...aRemote IP-address
%...a:Remote IP-address
%...ALocal IP-address
%...A:Local IP-address
%...BBytes sent, excluding HTTP headers.
%...B:Bytes sent, excluding HTTP headers.
%...bBytes sent, excluding HTTP headers. In CLF format, i.e. + a '-' rather than a 0 when no bytes are sent.
%...b:Bytes sent, excluding HTTP headers. In CLF format -i.e. a '-' rather than a 0 when no bytes are sent.
%...{Foobar}CThe contents of cookie Foobar in the request sent + to the server.
%...{Foobar}C:The contents of cookie "Foobar" in the request sent to the server.
%...DThe time taken to serve the request, in microseconds.
%...D:The time taken to serve the request, in microseconds.
%...{FOOBAR}eThe contents of the environment variable + FOOBAR
%...{FOOBAR}e:The contents of the environment variable FOOBAR
%...fFilename
%...f:Filename
%...hRemote host
%...h:Remote host
%...HThe request protocol
%...HThe request protocol
%...{Foobar}iThe contents of Foobar: header line(s) + in the request sent to the server.
%...{Foobar}i:The contents of Foobar: header line(s) in the request -sent to the server.
%...lRemote logname (from identd, if supplied)
%...l:Remote logname (from identd, if supplied)
%...mThe request method
%...m:The request method
%...{Foobar}nThe contents of note Foobar from another + module.
%...{Foobar}n:The contents of note "Foobar" from another module.
%...{Foobar}oThe contents of Foobar: header line(s) + in the reply.
%...{Foobar}o:The contents of Foobar: header line(s) in the reply.
%...pThe canonical port of the server serving the request
%...p:The canonical Port of the server serving the request
%...PThe process ID of the child that serviced the request.
%...P:The process ID of the child that serviced the request.
%...qThe query string (prepended with a ? if a query + string exists, otherwise an empty string)
%...q:The query string (prepended with a ? if a query string exists, -otherwise an empty string)
%...rFirst line of request
%...r:First line of request
%...sStatus. For requests that got internally redirected, this is + the status of the *original* request --- %...>s + for the last.
%...s:Status. For requests that got internally redirected, this is -the status of the *original* request --- %...>s for the last.
%...tTime, in common log format time format (standard english + format)
%...t:Time, in common log format time format (standard english format)
%...{format}tThe time, in the form given by format, which should be in + strftime(3) format. (potentially localized)
%...{format}t:The time, in the form given by format, which should -be in strftime(3) format. (potentially localized)
%...TThe time taken to serve the request, in seconds.
%...T:The time taken to serve the request, in seconds.
%...uRemote user (from auth; may be bogus if return status + (%s) is 401)
%...u:Remote user (from auth; may be bogus if return status (%s) is 401)
%...UThe URL path requested, not including any query string.
%...U:The URL path requested, not including any query string.
%...vThe canonical ServerName + of the server serving the request.
%...v:The canonical ServerName of the server serving the request.
%...VThe server name according to the UseCanonicalName setting.
%...V:The server name according to the UseCanonicalName setting.
%...XConnection status when response is completed: -
%...X: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. - -(This directive was %...c in late versions of Apache 1.3, but -this conflicted with the historical ssl %...{var}c syntax.) -
+ + + + + + +
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.
-%...I: -Bytes received, including request and headers, cannot be zero. You need to -enable mod_logio to use this. +

(This directive was %...c in late versions of Apache + 1.3, but this conflicted with the historical ssl + %...{var}c syntax.)

-%...O: -Bytes sent, including headers, cannot be zero. You need to enable -mod_logio to use this. + %...I + Bytes received, including request and headers, cannot be zero. + You need to enable mod_logio to use this. - + %...O + Bytes sent, including headers, cannot be zero. You need to + enable mod_logio to use this. + -

The "..." can be nothing at all (e.g., "%h %u - %r %s %b"), 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 +

The "..." can be nothing at all (e.g., + "%h %u %r %s %b"), 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 not return some sort of normal status.

+ 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 not return some sort of normal status.

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.

+ %...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.

Some commonly used log format strings are:

Common Log Format (CLF)
-
"%h %l %u %t \"%r\" %>s %b"
Common Log Format with Virtual Host
-
"%v %h %l %u %t \"%r\" %>s %b"
NCSA extended/combined log format
-
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Referer log format
-
"%{Referer}i -> %U"
Agent (Browser) log format
-
"%{User-agent}i"
-

Note that the canonical ServerName and Listen of the server serving the +

Note that the canonical ServerName and Listen of the server serving the request are used for %v and %p - respectively. This happens regardless of the UseCanonicalName setting + respectively. This happens regardless of the UseCanonicalName 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.

-
- -
- - Security Considerations +
+
Security Considerations

See the security tips 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.

- -
+
CookieLog Sets filename for the logging of cookies -CookieLog filename -server configvirtual -host -Only available in Apache 1.2 and above +CookieLog filename +server configvirtual host + +This directive is deprecated. -

The CookieLog directive sets the filename for logging of cookies. The filename is relative to the - serverroot. This directive is + ServerRoot. This directive is included only for compatibility with mod_cookies, and is deprecated.

 - CustomLog Sets filename and format of log file -CustomLog - file|pipe format|nickname - [env=[!]environment-variable] -server configvirtual -host -Nickname only available in Apache 1.3 or later. -Conditional logging available in 1.3.5 or later. - +CustomLog file|pipe +format|nickname +[env=[!]environment-variable] +server configvirtual host +

The CustomLog directive is used to @@ -259,73 +261,71 @@ Conditional logging available in 1.3.5 or later. types of values:

-
file
- -
A filename, relative to the ServerRoot.
- -
pipe
+
file
+
A filename, relative to the ServerRoot.
+
pipe
The pipe character "|", followed by the path to a program to receive the log information on its standard - input. Security: 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.
+ input. + + Security: +

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.

+

The second argument specifies what will be written to the - log file. It can specify either a nickname defined by - a previous LogFormat directive, or it - can be an explicit format string as described in the - log formats section.

+ log file. It can specify either a nickname defined by + a previous LogFormat + directive, or it can be an explicit format string as + described in the log formats section.

For example, the following two sets of directives have exactly the same effect:

- - # 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"
- + + # 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" +

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 environment variable is set for the request (or is not set, in the case - of a 'env=!name' clause), then the + of a 'env=!name' clause), then the request will be logged.

-

Environment variables can be set on a per-request +

Environment variables can be set on a per-request basis using the mod_setenvif and/or mod_rewrite modules. For example, if you want to record requests for all GIF images on your server in a separate logfile but not in your main log, you can use:

- - SetEnvIf Request_URI \.gif$ gif-image
- CustomLog gif-requests.log common env=gif-image
- CustomLog nongif-requests.log common env=!gif-image - + + SetEnvIf Request_URI \.gif$ gif-image
+ CustomLog gif-requests.log common env=gif-image
+ CustomLog nongif-requests.log common env=!gif-image + - LogFormat Describes a format for use in a log file -LogFormat - format|nickname [nickname] +LogFormat format|nickname +[nickname] LogFormat "%h %l %u %t \"%r\" %>s %b" -server configvirtual -host -Nickname only available in Apache 1.3 or later. - +server configvirtual host +

This directive specifies the format of the access log @@ -336,63 +336,55 @@ host this directive sets the log format which will be used by logs specified in subsequent TransferLog directives. The single argument can specify an explicit - format as discussed in custom log + format as discussed in custom log formats section above. Alternatively, it can use a - nickname to refer to a log format defined in a + nickname to refer to a log format defined in a previous LogFormat directive as described below.

The second form of the LogFormat - directive associates an explicit format with a - nickname. This nickname can then be used in + directive associates an explicit format with a + nickname. This nickname can then be used in subsequent LogFormat or - CustomLog directives rather than - repeating the entire format string. A - LogFormat - directive that defines a nickname does nothing - else -- that is, it only defines the - nickname, it doesn't actually apply the format and make it the - default. Therefore, it will not affect subsequent - TransferLog directives. In addition, - LogFormat cannot use one nickname - to define another nickname.

- -

For example:

- - LogFormat "%v %h %l %u %t \"%r\" %>s %b" - vhost_common - + CustomLog directives + rather than repeating the entire format string. A + LogFormat directive that defines a nickname + does nothing else -- that is, it only + defines the nickname, it doesn't actually apply the format and make + it the default. Therefore, it will not affect subsequent + TransferLog directives. + In addition, LogFormat cannot use one nickname + to define another nickname. Note, that the nickname should not contain + percent signs (%).

+ + Example + LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common + - TransferLog Specifly location of a log file -TransferLog file|pipe -server configvirtual -host - +TransferLog file|pipe +server configvirtual host + -

This directive has exactly the same arguments and effect as - the CustomLog 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 - LogFormat directive (which - does not define a nickname). Common Log Format is used if no + the CustomLog + 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 + LogFormat directive + (which does not define a nickname). Common Log Format is used if no other format has been specified.

-

Example:

- - LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
- TransferLog logs/access_log - - + Example + LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
+ TransferLog logs/access_log + -