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

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $Revision: 1.29 $ -->
   5
   6 <!--
   7  Copyright 2002-2004 The Apache Software Foundation
   8
   9  Licensed under the Apache License, Version 2.0 (the "License");
  10  you may not use this file except in compliance with the License.
  11  You may obtain a copy of the License at
  12
  13      http://www.apache.org/licenses/LICENSE-2.0
  14
  15  Unless required by applicable law or agreed to in writing, software
  16  distributed under the License is distributed on an "AS IS" BASIS,
  17  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  See the License for the specific language governing permissions and
  19  limitations under the License.
  20 -->
  21
  22 <modulesynopsis metafile="mod_log_config.xml.meta">
  23
  24 <name>mod_log_config</name>
  25 <description>Logging of the requests made to the server</description>
  26 <status>Base</status>
  27 <sourcefile>mod_log_config.c</sourcefile>
  28 <identifier>log_config_module</identifier>
  29
  30 <summary>
  31     <p>This module provides for flexible logging of client
  32     requests. Logs are written in a customizable format, and may be
  33     written directly to a file, or to an external program.
  34     Conditional logging is provided so that individual requests may
  35     be included or excluded from the logs based on characteristics
  36     of the request.</p>
  37
  38     <p>Three directives are provided by this module:
  39     <directive module="mod_log_config">TransferLog</directive> to create
  40     a log file, <directive module="mod_log_config">LogFormat</directive>
  41     to set a custom format, and <directive module="mod_log_config"
  42     >CustomLog</directive> to define a log file and format in one
  43     step. The <directive>TransferLog</directive> and <directive
  44     >CustomLog</directive> directives can be used multiple times in each
  45     server to cause each request to be logged to multiple files.</p>
  46 </summary>
  47 <seealso><a href="../logs.html">Apache Log Files</a></seealso>
  48
  49 <section id="formats"><title>Custom Log Formats</title>
  50
  51     <p>The format argument to the <directive module="mod_log_config"
  52     >LogFormat</directive> and <directive module="mod_log_config"
  53     >CustomLog</directive> directives is a string. This string is
  54     used to log each request to the log file. It can contain literal
  55     characters copied into the log files and the C-style control
  56     characters "\n" and "\t" to represent new-lines and tabs.
  57     Literal quotes and back-slashes should be escaped with
  58     back-slashes.</p>
  59
  60     <p>The characteristics of the request itself are logged by
  61     placing "<code>%</code>" directives in the format string, which are
  62     replaced in the log file by the values as follows:</p>
  63
  64     <table border="1" style="zebra">
  65     <columnspec><column width=".2"/><column width=".8"/></columnspec>
  66     <tr><th>Format&nbsp;String</th>
  67         <th>Description</th></tr>
  68
  69     <tr><td><code>%%</code></td>
  70         <td>The percent sign</td></tr>
  71
  72     <tr><td><code>%...a</code></td>
  73         <td>Remote IP-address</td></tr>
  74
  75     <tr><td><code>%...A</code></td>
  76         <td>Local IP-address</td></tr>
  77
  78     <tr><td><code>%...B</code></td>
  79         <td>Bytes sent, excluding HTTP headers.</td></tr>
  80
  81     <tr><td><code>%...b</code></td>
  82         <td>Bytes sent, excluding HTTP headers. In CLF format, <em>i.e.</em>
  83         a '<code>-</code>' rather than a 0 when no bytes are sent.</td></tr>
  84
  85     <tr><td><code>%...{<var>Foobar</var>}C</code></td>
  86         <td>The contents of cookie <var>Foobar</var> in the request sent
  87         to the server.</td></tr>
  88
  89     <tr><td><code>%...D</code></td>
  90         <td>The time taken to serve the request, in microseconds.</td></tr>
  91
  92     <tr><td><code>%...{<var>FOOBAR</var>}e</code></td>
  93         <td>The contents of the environment variable
  94         <var>FOOBAR</var></td></tr>
  95
  96     <tr><td><code>%...f</code></td>
  97         <td>Filename</td></tr>
  98
  99     <tr><td><code>%...h</code></td>
 100         <td>Remote host</td></tr>
 101
 102     <tr><td><code>%...H</code></td>
 103         <td>The request protocol</td></tr>
 104
 105     <tr><td><code>%...{<var>Foobar</var>}i</code></td>
 106         <td>The contents of <code><var>Foobar</var>:</code> header line(s)
 107         in the request sent to the server.</td></tr>
 108
 109     <tr><td><code>%...l</code></td>
 110         <td>Remote logname (from identd, if supplied). This will return a
 111         dash unless <module>mod_ident</module> is present and <directive
 112         module="mod_ident">IdentityCheck</directive> is set
 113         <code>On</code>.</td></tr>
 114
 115     <tr><td><code>%...m</code></td>
 116         <td>The request method</td></tr>
 117
 118     <tr><td><code>%...{<var>Foobar</var>}n</code></td>
 119         <td>The contents of note <var>Foobar</var> from another
 120         module.</td></tr>
 121
 122     <tr><td><code>%...{<var>Foobar</var>}o</code></td>
 123         <td>The contents of <code><var>Foobar</var>:</code> header line(s)
 124         in the reply.</td></tr>
 125
 126     <tr><td><code>%...p</code></td>
 127         <td>The canonical port of the server serving the request</td></tr>
 128
 129     <tr><td><code>%...P</code></td>
 130         <td>The process ID of the child that serviced the request.</td></tr>
 131
 132     <tr><td><code>%...{<var>format</var>}P</code></td>
 133         <td>The process ID or thread id of the child that serviced the
 134         request.  Valid formats are <code>pid</code> and <code>tid</code>.
 135         </td></tr>
 136
 137     <tr><td><code>%...q</code></td>
 138         <td>The query string (prepended with a <code>?</code> if a query
 139         string exists, otherwise an empty string)</td></tr>
 140
 141     <tr><td><code>%...r</code></td>
 142         <td>First line of request</td></tr>
 143
 144     <tr><td><code>%...s</code></td>
 145         <td>Status. For requests that got internally redirected, this is
 146         the status of the *original* request --- <code>%...&gt;s</code>
 147         for the last.</td></tr>
 148
 149     <tr><td><code>%...t</code></td>
 150         <td>Time, in common log format time format (standard english
 151         format)</td></tr>
 152
 153     <tr><td><code>%...{<var>format</var>}t</code></td>
 154         <td>The time, in the form given by format, which should be in
 155         <code>strftime(3)</code> format. (potentially localized)</td></tr>
 156
 157     <tr><td><code>%...T</code></td>
 158         <td>The time taken to serve the request, in seconds.</td></tr>
 159
 160     <tr><td><code>%...u</code></td>
 161         <td>Remote user (from auth; may be bogus if return status
 162         (<code>%s</code>) is 401)</td></tr>
 163
 164     <tr><td><code>%...U</code></td>
 165         <td>The URL path requested, not including any query string.</td></tr>
 166
 167     <tr><td><code>%...v</code></td>
 168         <td>The canonical <directive module="core">ServerName</directive>
 169         of the server serving the request.</td></tr>
 170
 171     <tr><td><code>%...V</code></td>
 172         <td>The server name according to the <directive module="core"
 173         >UseCanonicalName</directive> setting.</td></tr>
 174
 175     <tr><td><code>%...X</code></td>
 176         <td>Connection status when response is completed:
 177
 178         <table>
 179         <columnspec><column width=".2"/><column width=".6"/></columnspec>
 180         <tr><td><code>X</code> =</td>
 181             <td>connection aborted before the response completed.</td></tr>
 182         <tr><td><code>+</code> =</td>
 183             <td>connection may be kept alive after the response is
 184             sent.</td></tr>
 185         <tr><td><code>-</code> = </td>
 186             <td>connection will be closed after the response is
 187             sent.</td></tr>
 188         </table>
 189
 190         <p>(This directive was <code>%...c</code> in late versions of Apache
 191         1.3, but this conflicted with the historical ssl
 192         <code>%...{<var>var</var>}c</code> syntax.)</p></td></tr>
 193
 194     <tr><td><code>%...I</code></td>
 195         <td>Bytes received, including request and headers, cannot be zero.
 196         You need to enable <module>mod_logio</module> to use this.</td></tr>
 197
 198     <tr><td><code>%...O</code></td>
 199         <td>Bytes sent, including headers, cannot be zero. You need to
 200         enable <module>mod_logio</module> to use this.</td></tr>
 201     </table>
 202
 203     <p>The "<var>...</var>" can be nothing at all (<em>e.g.</em>,
 204     <code>"%h %u %r %s %b"</code>), or it can indicate conditions for
 205     inclusion of the item (which will cause it to be replaced with "-" if
 206     the condition is not met). The forms of condition are a list of
 207     HTTP status codes, which may or may not be preceded by "!".
 208     Thus, "%400,501{User-agent}i" logs <code>User-agent:</code> on 400
 209     errors and 501 errors (Bad Request, Not Implemented) only;
 210     "%!200,304,302{Referer}i" logs <code>Referer:</code> on all requests
 211     which did <em>not</em> return some sort of normal status.</p>
 212
 213     <p>The modifiers "&lt;" and "&gt;" can be used for requests that
 214     have been internally redirected to choose whether the original or
 215     final (respectively) request should be consulted.  By default, the
 216     <code>%</code> directives <code>%s, %U, %T, %D,</code> and
 217     <code>%r</code> look at the original request while all others look
 218     at the final request.  So for example, <code>%&gt;s</code> can be
 219     used to record the final status of the request and
 220     <code>%&lt;u</code> can be used to record the original
 221     authenticated user on a request that is internally redirected to an
 222     unauthenticated resource.</p>
 223
 224     <p>Note that in httpd 2.0 versions prior to 2.0.46, no escaping was performed
 225     on the strings from <code>%...r</code>, <code>%...i</code> and
 226     <code>%...o</code>. This was mainly to comply with the requirements of
 227     the Common Log Format. This implied that clients could insert control
 228     characters into the log, so you had to be quite careful when dealing
 229     with raw log files.</p>
 230
 231     <p>For security reasons, starting with 2.0.46, non-printable and
 232     other special characters are escaped mostly by using
 233     <code>\x<var>hh</var></code> sequences, where <var>hh</var> stands for
 234     the hexadecimal representation of the raw byte. Exceptions from this
 235     rule are <code>"</code> and <code>\</code> which are escaped by prepending
 236     a backslash, and all whitespace characters which are written in their
 237     C-style notation (<code>\n</code>, <code>\t</code> etc).</p>
 238
 239     <p>Some commonly used log format strings are:</p>
 240
 241     <dl>
 242       <dt>Common Log Format (CLF)</dt>
 243       <dd><code>"%h %l %u %t \"%r\" %&gt;s %b"</code></dd>
 244
 245       <dt>Common Log Format with Virtual Host</dt>
 246       <dd><code>"%v %h %l %u %t \"%r\" %&gt;s %b"</code></dd>
 247
 248       <dt>NCSA extended/combined log format</dt>
 249       <dd><code>"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\"
 250       \"%{User-agent}i\""</code></dd>
 251
 252       <dt>Referer log format</dt>
 253       <dd><code>"%{Referer}i -&gt; %U"</code></dd>
 254
 255       <dt>Agent (Browser) log format</dt>
 256       <dd><code>"%{User-agent}i"</code></dd>
 257     </dl>
 258
 259     <p>Note that the canonical <directive module="core"
 260     >ServerName</directive> and <directive module="mpm_common"
 261     >Listen</directive> of the server serving the
 262     request are used for <code>%v</code> and <code>%p</code>
 263     respectively. This happens regardless of the <directive
 264     module="core">UseCanonicalName</directive> setting
 265     because otherwise log analysis programs would have to duplicate
 266     the entire vhost matching algorithm in order to decide what
 267     host really served the request.</p>
 268 </section>
 269
 270 <section id="security"><title>Security Considerations</title>
 271     <p>See the <a
 272     href="../misc/security_tips.html#serverroot">security tips</a>
 273     document for details on why your security could be compromised
 274     if the directory where logfiles are stored is writable by
 275     anyone other than the user that starts the server.</p>
 276 </section>
 277
 278 <directivesynopsis>
 279 <name>CookieLog</name>
 280 <description>Sets filename for the logging of cookies</description>
 281 <syntax>CookieLog <var>filename</var></syntax>
 282 <contextlist><context>server config</context><context>virtual host</context>
 283 </contextlist>
 284 <compatibility>This directive is deprecated.</compatibility>
 285
 286 <usage>
 287     <p>The <directive>CookieLog</directive> directive sets the
 288     filename for logging of cookies. The filename is relative to the
 289     <directive module="core">ServerRoot</directive>. This directive is
 290     included only for compatibility with <code>mod_cookies</code>,
 291     and is deprecated.</p>
 292 </usage>
 293 </directivesynopsis>
 294
 295 <directivesynopsis>
 296 <name>CustomLog</name>
 297 <description>Sets filename and format of log file</description>
 298 <syntax>CustomLog  <var>file</var>|<var>pipe</var>
 299 <var>format</var>|<var>nickname</var>
 300 [env=[!]<var>environment-variable</var>]</syntax>
 301 <contextlist><context>server config</context><context>virtual host</context>
 302 </contextlist>
 303
 304 <usage>
 305     <p>The <directive>CustomLog</directive> directive is used to
 306     log requests to the server. A log format is specified, and the
 307     logging can optionally be made conditional on request
 308     characteristics using environment variables.</p>
 309
 310     <p>The first argument, which specifies the location to which
 311     the logs will be written, can take one of the following two
 312     types of values:</p>
 313
 314     <dl>
 315       <dt><var>file</var></dt>
 316       <dd>A filename, relative to the <directive module="core"
 317       >ServerRoot</directive>.</dd>
 318
 319       <dt><var>pipe</var></dt>
 320       <dd>The pipe character "<code>|</code>", followed by the path
 321       to a program to receive the log information on its standard
 322       input.
 323
 324       <note type="warning"><title>Security:</title>
 325       <p>If a program is used, then it will be run as the user who
 326       started httpd. This will be root if the server was started by root;
 327       be sure that the program is secure.</p>
 328       </note>
 329       <note type="warning"><title>Note</title>
 330         <p>When entering a file path on non-Unix platforms, care should be taken
 331         to make sure that only forward slashed are used even though the platform
 332         may allow the use of back slashes. In general it is a good idea to always
 333         use forward slashes throughout the configuration files.</p>
 334       </note></dd>
 335     </dl>
 336
 337     <p>The second argument specifies what will be written to the
 338     log file. It can specify either a <var>nickname</var> defined by
 339     a previous <directive module="mod_log_config">LogFormat</directive>
 340     directive, or it can be an explicit <var>format</var> string as
 341     described in the <a href="#formats">log formats</a> section.</p>
 342
 343     <p>For example, the following two sets of directives have
 344     exactly the same effect:</p>
 345
 346     <example>
 347       # CustomLog with format nickname<br />
 348       LogFormat "%h %l %u %t \"%r\" %&gt;s %b" common<br />
 349       CustomLog logs/access_log common<br />
 350       <br />
 351       # CustomLog with explicit format string<br />
 352       CustomLog logs/access_log "%h %l %u %t \"%r\" %&gt;s %b"
 353     </example>
 354
 355     <p>The third argument is optional and controls whether or
 356     not to log a particular request based on the
 357     presence or absence of a particular variable in the server
 358     environment. If the specified <a href="../env.html">environment
 359     variable</a> is set for the request (or is not set, in the case
 360     of a '<code>env=!<var>name</var></code>' clause), then the
 361     request will be logged.</p>
 362
 363     <p>Environment variables can be set on a per-request
 364     basis using the <module>mod_setenvif</module>
 365     and/or <module>mod_rewrite</module> modules. For
 366     example, if you want to record requests for all GIF
 367     images on your server in a separate logfile but not in your main
 368     log, you can use:</p>
 369
 370     <example>
 371       SetEnvIf Request_URI \.gif$ gif-image<br />
 372       CustomLog gif-requests.log common env=gif-image<br />
 373       CustomLog nongif-requests.log common env=!gif-image
 374     </example>
 375 </usage>
 376 </directivesynopsis>
 377
 378 <directivesynopsis>
 379 <name>LogFormat</name>
 380 <description>Describes a format for use in a log file</description>
 381 <syntax>LogFormat <var>format</var>|<var>nickname</var>
 382 [<var>nickname</var>]</syntax>
 383 <default>LogFormat "%h %l %u %t \"%r\" %>s %b"</default>
 384 <contextlist><context>server config</context><context>virtual host</context>
 385 </contextlist>
 386
 387 <usage>
 388     <p>This directive specifies the format of the access log
 389     file.</p>
 390
 391     <p>The <directive>LogFormat</directive> directive can take one of two
 392     forms. In the first form, where only one argument is specified,
 393     this directive sets the log format which will be used by logs
 394     specified in subsequent <directive>TransferLog</directive>
 395     directives. The single argument can specify an explicit
 396     <var>format</var> as discussed in the <a href="#formats">custom log
 397     formats</a> section above. Alternatively, it can use a
 398     <var>nickname</var> to refer to a log format defined in a
 399     previous <directive>LogFormat</directive> directive as described
 400     below.</p>
 401
 402     <p>The second form of the <directive>LogFormat</directive>
 403     directive associates an explicit <var>format</var> with a
 404     <var>nickname</var>. This <var>nickname</var> can then be used in
 405     subsequent <directive>LogFormat</directive> or
 406     <directive module="mod_log_config">CustomLog</directive> directives
 407     rather than repeating the entire format string. A
 408     <directive>LogFormat</directive> directive that defines a nickname
 409     <strong>does nothing else</strong> -- that is, it <em>only</em>
 410     defines the nickname, it doesn't actually apply the format and make
 411     it the default. Therefore, it will not affect subsequent
 412     <directive module="mod_log_config">TransferLog</directive> directives.
 413     In addition, <directive>LogFormat</directive> cannot use one nickname
 414     to define another nickname. Note that the nickname should not contain
 415     percent signs (<code>%</code>).</p>
 416
 417     <example><title>Example</title>
 418       LogFormat "%v %h %l %u %t \"%r\" %&gt;s %b" vhost_common
 419     </example>
 420 </usage>
 421 </directivesynopsis>
 422
 423 <directivesynopsis>
 424 <name>TransferLog</name>
 425 <description>Specify location of a log file</description>
 426 <syntax>TransferLog <var>file</var>|<var>pipe</var></syntax>
 427 <contextlist><context>server config</context><context>virtual host</context>
 428 </contextlist>
 429
 430 <usage>
 431     <p>This directive has exactly the same arguments and effect as
 432     the <directive module="mod_log_config">CustomLog</directive>
 433     directive, with the exception that it does not allow the log format
 434     to be specified explicitly or for conditional logging of requests.
 435     Instead, the log format is determined by the most recently specified
 436     <directive module="mod_log_config">LogFormat</directive> directive
 437     which does not define a nickname. Common Log Format is used if no
 438     other format has been specified.</p>
 439
 440     <example><title>Example</title>
 441       LogFormat "%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-agent}i\""<br />
 442       TransferLog logs/access_log
 443     </example>
 444 </usage>
 445 </directivesynopsis>
 446
 447 </modulesynopsis>