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

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