granicus.if.org Git - apache/blob - docs/manual/mod/mod_log_config.html.en

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><!--
   2         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   3               This file is generated from xml source: DO NOT EDIT
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5       --><title>mod_log_config - Apache HTTP Server</title><link href="../style/manual.css" type="text/css" rel="stylesheet"></head><body><blockquote><div align="center"><img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]"><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_log_config</h1><table cellspacing="1" cellpadding="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap" valign="top"><span class="help">Description:
   6                       </span></td><td>Logging of the requests made to the server</td></tr><tr><td nowrap="nowrap"><a href="module-dict.html#Status" class="help">Status:
   7                       </a></td><td>Base</td></tr><tr><td nowrap="nowrap"><a href="module-dict.html#ModuleIdentifier" class="help">Module&nbsp;Identifier:
   8                         </a></td><td>log_config_module</td></tr></table></td></tr></table><h2>Summary</h2>
   9
  10     <p>This module provides for flexible logging of client
  11     requests. Logs are written in a customizable format, and may be
  12     written directly to a file, or to an external program.
  13     Conditional logging is provided so that individual requests may
  14     be included or excluded from the logs based on characteristics
  15     of the request.</p>
  16
  17     <p>Three directives are provided by this module:
  18     <code>TransferLog</code> to create a log file,
  19     <code>LogFormat</code> to set a custom format, and
  20     <code>CustomLog</code> to define a log file and format in one
  21     step. The <code>TransferLog</code> and <code>CustomLog</code>
  22     directives can be used multiple times in each server to cause
  23     each request to be logged to multiple files.</p>
  24 <h2>Directives</h2><ul><li><a href="#cookielog">CookieLog</a></li><li><a href="#customlog">CustomLog</a></li><li><a href="#logformat">LogFormat</a></li><li><a href="#transferlog">TransferLog</a></li></ul><p><strong>See also </strong></p><ul><li><a href="../logs.html">Apache Log Files</a></li></ul><h2><a name="formats">Custom Log Formats</a></h2>
  25
  26
  27     <p>The format argument to the <code>LogFormat</code> and
  28     <code>CustomLog</code> directives is a string. This string is
  29     logged to the log file for each request. It can contain literal
  30     characters copied into the log files and the c-type control
  31     characters "\n" and "\t" to represent new-lines and tabs.
  32     Literal quotes and back-slashes should be escaped with
  33     back-slashes.</p>
  34
  35     <p>The characteristics of the request itself are logged by
  36     placing "%" directives in the format string, which are replaced
  37     in the log file by the values as follows:</p>
  38
  39 <table>
  40
  41 <tr><td>%...a:</td>
  42 <td>Remote IP-address</td></tr>
  43
  44 <tr><td>%...A:</td>
  45 <td>Local IP-address</td></tr>
  46
  47 <tr><td>%...B:</td>
  48 <td>Bytes sent, excluding HTTP headers.</td></tr>
  49
  50 <tr><td>%...b:</td>
  51 <td>Bytes sent, excluding HTTP headers. In CLF format
  52 i.e. a '-' rather than a 0 when no bytes are sent.</td></tr>
  53
  54 <tr><td>%...{Foobar}C:</td>
  55 <td>The contents of cookie "Foobar" in the request sent to the server.</td></tr>
  56
  57 <tr><td>%...D:</td>
  58 <td>The time taken to serve the request, in microseconds.</td></tr>
  59
  60 <tr><td>%...{FOOBAR}e:</td>
  61 <td>The contents of the environment variable FOOBAR</td></tr>
  62
  63 <tr><td>%...f:</td>
  64 <td>Filename</td></tr>
  65
  66 <tr><td>%...h:</td>
  67 <td>Remote host</td></tr>
  68
  69 <tr><td>%...H</td>
  70 <td>The request protocol</td></tr>
  71
  72 <tr><td>%...{Foobar}i:</td>
  73 <td>The contents of Foobar: header line(s) in the request
  74 sent to the server.</td></tr>
  75
  76 <tr><td>%...l:</td>
  77 <td>Remote logname (from identd, if supplied)</td></tr>
  78
  79 <tr><td>%...m:</td>
  80 <td>The request method</td></tr>
  81
  82 <tr><td>%...{Foobar}n:</td>
  83 <td>The contents of note "Foobar" from another module.</td></tr>
  84
  85 <tr><td>%...{Foobar}o:</td>
  86 <td>The contents of Foobar: header line(s) in the reply.</td></tr>
  87
  88 <tr><td>%...p:</td>
  89 <td>The canonical Port of the server serving the request</td></tr>
  90
  91 <tr><td>%...P:</td>
  92 <td>The process ID of the child that serviced the request.</td></tr>
  93
  94 <tr><td>%...q:</td>
  95 <td>The query string (prepended with a ? if a query string exists,
  96 otherwise an empty string)</td></tr>
  97
  98 <tr><td>%...r:</td>
  99 <td>First line of request</td></tr>
 100
 101 <tr><td>%...s:</td>
 102 <td>Status.  For requests that got internally redirected, this is
 103 the status of the *original* request --- %...&gt;s for the last.</td></tr>
 104
 105 <tr><td>%...t:</td>
 106 <td>Time, in common log format time format (standard english format)</td></tr>
 107
 108 <tr><td>%...{format}t:</td>
 109 <td>The time, in the form given by format, which should
 110 be in strftime(3) format. (potentially localized)</td></tr>
 111
 112 <tr><td>%...T:</td>
 113 <td>The time taken to serve the request, in seconds.</td></tr>
 114
 115 <tr><td>%...u:</td>
 116 <td>Remote user (from auth; may be bogus if return status (%s) is 401)</td></tr>
 117
 118 <tr><td>%...U:</td>
 119 <td>The URL path requested, not including any query string.</td></tr>
 120
 121 <tr><td>%...v:</td>
 122 <td>The canonical ServerName of the server serving the request.</td></tr>
 123
 124 <tr><td>%...V:</td>
 125 <td>The server name according to the UseCanonicalName setting.</td></tr>
 126
 127 <tr><td>%...X:</td>
 128 <td>Connection status when response is completed.
 129 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 130 'X' = connection aborted before the response completed.<br>
 131 '+' = connection may be kept alive after the response is sent.<br>
 132 '-' = connection will be closed after the response is sent.
 133 </code></td></tr></table></blockquote>
 134 <blockquote><table><tr><td bgcolor="#e0e5f5">(This directive was %...c in late versions of Apache 1.3, but
 135 this conflicted with the historical ssl %...{var}c syntax.)</td></tr></table></blockquote>
 136 </td></tr>
 137
 138 </table>
 139
 140     <p>The "..." can be nothing at all (<em>e.g.</em>, <code>"%h %u
 141     %r %s %b"</code>), or it can indicate conditions for inclusion
 142     of the item (which will cause it to be replaced with "-" if the
 143     condition is not met). The forms of condition are a list of
 144     HTTP status codes, which may or may not be preceded by "!".
 145     Thus, "%400,501{User-agent}i" logs User-agent: on 400 errors
 146     and 501 errors (Bad Request, Not Implemented) only;
 147     "%!200,304,302{Referer}i" logs Referer: on all requests which
 148     did <strong>not</strong> return some sort of normal status.</p>
 149
 150     <p>Note that there is no escaping performed on the strings from
 151     %...r, %...i and %...o. This is mainly to comply with the
 152     requirements of the Common Log Format. This implies that
 153     clients can insert control characters into the log, so care
 154     should be taken when dealing with raw log files.</p>
 155
 156     <p>Some commonly used log format strings are:</p>
 157
 158     <dl>
 159       <dt>Common Log Format (CLF)</dt>
 160
 161       <dd><code>"%h %l %u %t \"%r\" %&gt;s %b"</code></dd>
 162
 163       <dt>Common Log Format with Virtual Host</dt>
 164
 165       <dd><code>"%v %h %l %u %t \"%r\" %&gt;s %b"</code></dd>
 166
 167       <dt>NCSA extended/combined log format</dt>
 168
 169       <dd><code>"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\"
 170       \"%{User-agent}i\""</code></dd>
 171
 172       <dt>Referer log format</dt>
 173
 174       <dd><code>"%{Referer}i -&gt; %U"</code></dd>
 175
 176       <dt>Agent (Browser) log format</dt>
 177
 178       <dd><code>"%{User-agent}i"</code></dd>
 179     </dl>
 180
 181     <p>Note that the canonical <a href="core.html#servername">ServerName</a> and <a href="mpm_common.html#listen">Listen</a> of the server serving the
 182     request are used for <code>%v</code> and <code>%p</code>
 183     respectively. This happens regardless of the <a href="core.html#usecanonicalname">UseCanonicalName</a> setting
 184     because otherwise log analysis programs would have to duplicate
 185     the entire vhost matching algorithm in order to decide what
 186     host really served the request.</p>
 187     <h2>Security Considerations</h2>
 188
 189
 190
 191     <p>See the <a href="../misc/security_tips.html#serverroot">security tips</a>
 192     document for details on why your security could be compromised
 193     if the directory where logfiles are stored is writable by
 194     anyone other than the user that starts the server.</p>
 195
 196     <hr><h2><a name="CookieLog">CookieLog</a> <a name="cookielog">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description:
 197                   </strong></td><td>Sets filename for the logging of cookies</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:
 198                   </a></td><td>CookieLog <em>filename</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:
 199                   </a></td><td>server config, virtual
 200 host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:
 201                   </a></td><td>Base</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:
 202                   </a></td><td>mod_log_config</td></tr><tr><td nowrap="nowrap" align="left" valign="top"><a href="directive-dict.html#Compatibility" class="help">Compatibility:
 203                     </a></td><td>Only available in Apache 1.2 and above</td></tr></table></td></tr></table>
 204
 205     <p>The <code class="directive">CookieLog</code> directive sets the
 206     filename for logging of cookies. The filename is relative to the
 207     <a href="../mod/core.html#serverroot" class="directive"><code class="directive">serverroot</code></a>. This directive is
 208     included only for compatibility with <code><a href="../mod/mod_cookies.html">mod_cookies</a></code>,
 209     and is deprecated.</p>
 210 <hr><h2><a name="CustomLog">CustomLog</a> <a name="customlog">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description:
 211                   </strong></td><td>Sets filename and format of log file</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:
 212                   </a></td><td>CustomLog
 213     <em>file</em>|<em>pipe</em> <em>format</em>|<em>nickname</em>
 214     [env=[!]<em>environment-variable</em>]</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:
 215                   </a></td><td>server config, virtual
 216 host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:
 217                   </a></td><td>Base</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:
 218                   </a></td><td>mod_log_config</td></tr><tr><td nowrap="nowrap" align="left" valign="top"><a href="directive-dict.html#Compatibility" class="help">Compatibility:
 219                     </a></td><td>Nickname only available in Apache 1.3 or later.
 220 Conditional logging available in 1.3.5 or later.</td></tr></table></td></tr></table>
 221     <p>The <code class="directive">CustomLog</code> directive is used to
 222     log requests to the server. A log format is specified, and the
 223     logging can optionally be made conditional on request
 224     characteristics using environment variables.</p>
 225
 226     <p>The first argument, which specifies the location to which
 227     the logs will be written, can take on one of the following two
 228     types of values:</p>
 229
 230     <dl>
 231       <dt><em>file</em></dt>
 232
 233       <dd>A filename, relative to the <a href="core.html#serverroot">ServerRoot</a>.</dd>
 234
 235       <dt><em>pipe</em></dt>
 236
 237       <dd>The pipe character "<code>|</code>", followed by the path
 238       to a program to receive the log information on its standard
 239       input. <strong>Security:</strong> if a program is used, then
 240       it will be run under the user who started httpd. This will be
 241       root if the server was started by root; be sure that the
 242       program is secure.</dd>
 243     </dl>
 244
 245     <p>The second argument specifies what will be written to the
 246     log file. It can specify either a <em>nickname</em> defined by
 247     a previous <a href="#logformat">LogFormat</a> directive, or it
 248     can be an explicit <em>format</em> string as described in the
 249     <a href="#formats">log formats</a> section.</p>
 250
 251     <p>For example, the following two sets of directives have
 252     exactly the same effect:</p>
 253
 254 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 255      # CustomLog with format nickname<br>
 256      LogFormat "%h %l %u %t \"%r\" %&gt;s %b" common<br>
 257      CustomLog logs/access_log common<br>
 258 <br>
 259      # CustomLog with explicit format string<br>
 260      CustomLog logs/access_log "%h %l %u %t \"%r\" %&gt;s %b"<br>
 261 </code></td></tr></table></blockquote>
 262
 263     <p>The third argument is optional and allows the decision on
 264     whether or not to log a particular request to be based on the
 265     presence or absence of a particular variable in the server
 266     environment. If the specified <a href="../env.html">environment
 267     variable</a> is set for the request (or is not set, in the case
 268     of a '<code>env=!<em>name</em></code>' clause), then the
 269     request will be logged.</p>
 270
 271     <p>Environment variables can be set on a <em>per</em>-request
 272     basis using the <code><a href="../mod/mod_setenvif.html">mod_setenvif</a></code>
 273     and/or <code><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> modules. For
 274     example, if you want to record requests for all GIF
 275     images on your server in a separate logfile but not in your main
 276     log, you can use:</p>
 277
 278 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 279     SetEnvIf Request_URI \.gif$ gif-image<br>
 280     CustomLog gif-requests.log common env=gif-image<br>
 281     CustomLog nongif-requests.log common env=!gif-image
 282 </code></td></tr></table></blockquote>
 283 <hr><h2><a name="LogFormat">LogFormat</a> <a name="logformat">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description:
 284                   </strong></td><td>Describes a format for use in a log file</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:
 285                   </a></td><td>LogFormat
 286     <em>format</em>|<em>nickname</em> [<em>nickname</em>]</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:
 287                   </a></td><td>server config, virtual
 288 host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:
 289                   </a></td><td>Base</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:
 290                   </a></td><td>mod_log_config</td></tr><tr><td nowrap="nowrap" align="left" valign="top"><a href="directive-dict.html#Compatibility" class="help">Compatibility:
 291                     </a></td><td>Nickname only available in Apache 1.3 or later.
 292 </td></tr></table></td></tr></table>
 293     <p>This directive specifies the format of the access log
 294     file.</p>
 295
 296     <p>The <code class="directive">LogFormat</code> directive can take one of two
 297     forms. In the first form, where only one argument is specified,
 298     this directive sets the log format which will be used by logs
 299     specified in subsequent <code class="directive">TransferLog</code>
 300     directives. The single argument can specify an explicit
 301     <em>format</em> as discussed in <a href="#formats">custom log
 302     formats</a> section above. Alternatively, it can use a
 303     <em>nickname</em> to refer to a log format defined in a
 304     previous <code class="directive">LogFormat</code> directive as described
 305     below.</p>
 306
 307     <p>The second form of the <code class="directive">LogFormat</code>
 308     directive associates an explicit <em>format</em> with a
 309     <em>nickname</em>. This <em>nickname</em> can then be used in
 310     subsequent <code class="directive">LogFormat</code> or
 311     <code class="directive">CustomLog</code> directives rather than
 312     repeating the entire format string. A
 313     <code class="directive">LogFormat</code>
 314     directive which defines a nickname <strong>does nothing
 315     else</strong> -- that is, it <em>only</em> defines the
 316     nickname, it doesn't actually apply the format and make it the
 317     default. Therefore, it will not affect subsequent
 318     <code class="directive">TransferLog</code> directives.</p>
 319
 320     <p>For example:</p>
 321
 322     <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>LogFormat "%v %h %l %u %t \"%r\" %&gt;s %b"
 323     vhost_common</code></td></tr></table></blockquote>
 324
 325 <hr><h2><a name="TransferLog">TransferLog</a> <a name="transferlog">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td nowrap="nowrap"><strong>Description:
 326                   </strong></td><td>Specifly location of a log file</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Syntax" class="help">Syntax:
 327                   </a></td><td>TransferLog <em>file</em>|<em>pipe</em></td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Context" class="help">Context:
 328                   </a></td><td>server config, virtual
 329 host</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Status" class="help">Status:
 330                   </a></td><td>Base</td></tr><tr><td nowrap="nowrap"><a href="directive-dict.html#Module" class="help">Module:
 331                   </a></td><td>mod_log_config</td></tr><tr><td nowrap="nowrap" align="left" valign="top"><a href="directive-dict.html#Compatibility" class="help">Compatibility:
 332                     </a></td><td></td></tr></table></td></tr></table>
 333
 334     <p>This directive has exactly the same arguments and effect as
 335     the <code class="directive">CustomLog</code> directive, with the
 336     exception that it does not allow the log format to be specified
 337     explicitly or for conditional logging of requests. Instead, the
 338     log format is determined by the most recently specified
 339     specified <code class="directive">LogFormat</code> directive (which
 340     does not define a nickname). Common Log Format is used if no
 341     other format has been specified.</p>
 342
 343     <p>Example:</p>
 344 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
 345    LogFormat "%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-agent}i\""<br>
 346    TransferLog logs/access_log
 347 </code></td></tr></table></blockquote>
 348
 349 <hr></blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img src="../images/index.gif" alt="Index"></a><a href="../"><img src="../images/home.gif" alt="Home"></a></body></html>