mod_log_config.xml revision 1ad1c5f9a82d056966dcca9c6108c5ace8eed446
7d32c065c7bb56f281651ae3dd2888f32ce4f1d9Bob Halley<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley<!-- $LastChangedRevision$ -->
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley Licensed to the Apache Software Foundation (ASF) under one or more
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley contributor license agreements. See the NOTICE file distributed with
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley this work for additional information regarding copyright ownership.
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley The ASF licenses this file to You under the Apache License, Version 2.0
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley (the "License"); you may not use this file except in compliance with
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley the License. You may obtain a copy of the License at
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley Unless required by applicable law or agreed to in writing, software
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley distributed under the License is distributed on an "AS IS" BASIS,
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley See the License for the specific language governing permissions and
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley limitations under the License.
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley<modulesynopsis metafile="mod_log_config.xml.meta">
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley<description>Logging of the requests made to the server</description>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <p>This module provides for flexible logging of client
2504b0a58600c1156a6b829c816d13c58a069453Bob Halley requests. Logs are written in a customizable format, and may be
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley written directly to a file, or to an external program.
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley Conditional logging is provided so that individual requests may
00e7d7a0e8529998c78b73371dc90fbf680b57efBob Halley be included or excluded from the logs based on characteristics
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley of the request.</p>
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington <p>Three directives are provided by this module:
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <directive module="mod_log_config">TransferLog</directive> to create
290074dd410acdd003f67f99409d75e0dcacd97bAndreas Gustafsson a log file, <directive module="mod_log_config">LogFormat</directive>
070d058606dff606710f320b071891bf16e02076Andreas Gustafsson to set a custom format, and <directive module="mod_log_config"
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley >CustomLog</directive> to define a log file and format in one
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley step. The <directive>TransferLog</directive> and <directive
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley >CustomLog</directive> directives can be used multiple times in each
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley server to cause each request to be logged to multiple files.</p>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley<seealso><a href="/logs.html">Apache Log Files</a></seealso>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley<section id="formats"><title>Custom Log Formats</title>
6f44af1c8320e84d6b0c0c42bacadfe3020d9a91Mark Andrews <p>The format argument to the <directive module="mod_log_config"
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley >LogFormat</directive> and <directive module="mod_log_config"
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley >CustomLog</directive> directives is a string. This string is
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley used to log each request to the log file. It can contain literal
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley characters copied into the log files and the C-style control
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley characters "\n" and "\t" to represent new-lines and tabs.
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley Literal quotes and back-slashes should be escaped with
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley back-slashes.</p>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <p>The characteristics of the request itself are logged by
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley placing "<code>%</code>" directives in the format string, which are
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley replaced in the log file by the values as follows:</p>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <columnspec><column width=".2"/><column width=".8"/></columnspec>
6d39d25c557d3778ea8dc1d032cb443302879aa7Andreas Gustafsson <td>Size of response in bytes, excluding HTTP headers.</td></tr>
143c2d39fafc0e36e0fa291b7708b60309e5a1b6Andreas Gustafsson <td>Size of response in bytes, excluding HTTP headers. In CLF format, <em>i.e.</em>
143c2d39fafc0e36e0fa291b7708b60309e5a1b6Andreas Gustafsson a '<code>-</code>' rather than a 0 when no bytes are sent.</td></tr>
143c2d39fafc0e36e0fa291b7708b60309e5a1b6Andreas Gustafsson <tr><td><code>%{<var>VARNAME</var>}C</code></td>
143c2d39fafc0e36e0fa291b7708b60309e5a1b6Andreas Gustafsson <td>The contents of cookie <var>VARNAME</var> in the request sent
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The time taken to serve the request, in microseconds.</td></tr>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The contents of the environment variable
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson <td>The contents of <code><var>VARNAME</var>:</code> header line(s)
2504b0a58600c1156a6b829c816d13c58a069453Bob Halley in the request sent to the server. Changes made by other
38980568375a6505452550b5677104ab44291b66Bob Halley modules (e.g. <module>mod_headers</module>) affect this.
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>Number of keepalive requests handled on this connection. Interesting if
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <directive module="core">KeepAlive</directive> is being used, so that,
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley for example, a '1' means the first keepalive request after the initial
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley one, '2' the second, etc...;
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley otherwise this is always 0 (indicating the initial request).</td></tr>
f93d33e24fdf76eb2558168f018b8992bcfc5681Andreas Gustafsson <td>Remote logname (from identd, if supplied). This will return a
72f8abc08b889aeca5768104e8a6d670ed1c9ffbAndreas Gustafsson dash unless <module>mod_ident</module> is present and <directive
9e565c950b7eef312b2f56125fde371bf1e3f4b7Andreas Gustafsson module="mod_ident">IdentityCheck</directive> is set
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <td>The contents of note <var>VARNAME</var> from another
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The contents of <code><var>VARNAME</var>:</code> header line(s)
9e565c950b7eef312b2f56125fde371bf1e3f4b7Andreas Gustafsson <td>The canonical port of the server serving the request</td></tr>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews <tr><td><code>%{<var>format</var>}p</code></td>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews <td>The canonical port of the server serving the request or the
00e7d7a0e8529998c78b73371dc90fbf680b57efBob Halley server's actual port or the client's actual port. Valid formats
143c2d39fafc0e36e0fa291b7708b60309e5a1b6Andreas Gustafsson are <code>canonical</code>, <code>local</code>, or <code>remote</code>.
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The process ID of the child that serviced the request.</td></tr>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The process ID or thread id of the child that serviced the
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley request. Valid formats are <code>pid</code>, <code>tid</code>,
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley and <code>hextid</code>. <code>hextid</code> requires APR 1.2.0 or
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The query string (prepended with a <code>?</code> if a query
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley string exists, otherwise an empty string)</td></tr>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <td>Status. For requests that got internally redirected, this is
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley the status of the *original* request --- <code>%>s</code>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>Time the request was received (standard english
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The time, in the form given by format, which should be in
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <code>strftime(3)</code> format. (potentially localized)</td></tr>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>The time taken to serve the request, in seconds.</td></tr>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>Remote user (from auth; may be bogus if return status
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <td>The URL path requested, not including any query string.</td></tr>
f93d33e24fdf76eb2558168f018b8992bcfc5681Andreas Gustafsson <td>The canonical <directive module="core">ServerName</directive>
72f8abc08b889aeca5768104e8a6d670ed1c9ffbAndreas Gustafsson of the server serving the request.</td></tr>
726290e9d5b720b736fa39d9f7d92c2efb7d1f24Bob Halley <td>The server name according to the <directive module="core"
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <td>Connection status when response is completed:
2504b0a58600c1156a6b829c816d13c58a069453Bob Halley <columnspec><column width=".2"/><column width=".6"/></columnspec>
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson <td>connection aborted before the response completed.</td></tr>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews <td>connection may be kept alive after the response is
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <td>connection will be closed after the response is
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <p>(This directive was <code>%c</code> in late versions of Apache
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley 1.3, but this conflicted with the historical ssl
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <code>%{<var>var</var>}c</code> syntax.)</p></td></tr>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <td>Bytes received, including request and headers, cannot be zero.
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley You need to enable <module>mod_logio</module> to use this.</td></tr>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <td>Bytes sent, including headers, cannot be zero. You need to
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley enable <module>mod_logio</module> to use this.</td></tr>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <p>Particular items can be restricted to print only for
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley responses with specific HTTP status codes by placing a
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley comma-separated list of status codes immediately following the
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley "%". For example, <code>"%400,501{User-agent}i"</code> logs
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <code>User-agent</code> on 400 errors and 501 errors only. For
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley other status codes, the literal string <code>"-"</code> will be
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley logged. The status code list may be preceded by a
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <code>"%!200,304,302{Referer}i"</code> logs <code>Referer</code>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley on all requests that do <em>not</em> return one of the three
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley specified codes.</p>
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley <p>The modifiers "<" and ">" can be used for requests that
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley have been internally redirected to choose whether the original
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley or final (respectively) request should be consulted. By
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley default, the <code>%</code> directives <code>%s, %U, %T,
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley %D,</code> and <code>%r</code> look at the original request
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley while all others look at the final request. So for example,
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <code>%>s</code> can be used to record the final status of
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley the request and <code>%<u</code> can be used to record the
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley original authenticated user on a request that is internally
f94f59d746daffc38356d0a019b64eb01d2341c0Bob Halley redirected to an unauthenticated resource.</p>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <section id="format-notes"><title>Some Notes</title>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <p>For security reasons, starting with version 2.0.46,
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley non-printable and other special characters in <code>%r</code>,
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <code>%i</code> and <code>%o</code> are escaped using
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <code>\x<var>hh</var></code> sequences, where <var>hh</var>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley stands for the hexadecimal representation of the raw
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley byte. Exceptions from this rule are <code>"</code> and
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <code>\</code>, which are escaped by prepending a backslash, and
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley all whitespace characters, which are written in their C-style
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley notation (<code>\n</code>, <code>\t</code>, etc). In versions
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley prior to 2.0.46, no escaping was performed on these strings so
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley you had to be quite careful when dealing with raw log files.</p>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <p>In httpd 2.0, unlike 1.3, the <code>%b</code> and
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <code>%B</code> format strings do not represent the number of
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley bytes sent to the client, but simply the size in bytes of the
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley HTTP response (which will differ, for instance, if the
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley connection is aborted, or if SSL is used). The <code>%O</code>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley format provided by <module>mod_logio</module> will log the
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley actual number of bytes sent over the network.</p>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <p>Some commonly used log format strings are:</p>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <dd><code>"%h %l %u %t \"%r\" %>s %b"</code></dd>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <dd><code>"%v %h %l %u %t \"%r\" %>s %b"</code></dd>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <dd><code>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
38980568375a6505452550b5677104ab44291b66Bob Halley<section id="security"><title>Security Considerations</title>
e3027d397f237ff018174fd17bf377a4a1890c6bBob Halley href="/misc/security_tips.html#serverroot">security tips</a>
e3027d397f237ff018174fd17bf377a4a1890c6bBob Halley document for details on why your security could be compromised
e3027d397f237ff018174fd17bf377a4a1890c6bBob Halley if the directory where logfiles are stored is writable by
0df20c101eea3ffa57d9554ec20a1b710fa63064Bob Halley anyone other than the user that starts the server.</p>
38980568375a6505452550b5677104ab44291b66Bob Halley<directivesynopsis>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley<description>Buffer log entries in memory before writing to disk</description>
726290e9d5b720b736fa39d9f7d92c2efb7d1f24Bob Halley<contextlist><context>server config</context></contextlist>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<compatibility>Available in versions 2.0.41 and later.</compatibility>
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley <p>The <directive>BufferedLogs</directive> directive causes
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <module>mod_log_config</module> to store several log entries in
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley memory and write them together to disk, rather than writing them
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley after each request. On some systems, this may result in more
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley efficient disk access and hence higher performance. It may be
e485d16462b0a66b835107fae04fe9d562e77af0Bob Halley set only once for the entire server; it cannot be configured
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley per virtual-host.</p>
0df20c101eea3ffa57d9554ec20a1b710fa63064Bob Halley <note>This directive is experimental and should be used with
0df20c101eea3ffa57d9554ec20a1b710fa63064Bob Halley caution.</note>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley</directivesynopsis>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley<directivesynopsis>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley<description>Sets filename for the logging of cookies</description>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley<contextlist><context>server config</context><context>virtual host</context>
726290e9d5b720b736fa39d9f7d92c2efb7d1f24Bob Halley</contextlist>
726290e9d5b720b736fa39d9f7d92c2efb7d1f24Bob Halley<compatibility>This directive is deprecated.</compatibility>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <p>The <directive>CookieLog</directive> directive sets the
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley filename for logging of cookies. The filename is relative to the
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley <directive module="core">ServerRoot</directive>. This directive is
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley included only for compatibility with <code>mod_cookies</code>,
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley and is deprecated.</p>
205790a755849f9b9ec12dd7836dcd87ca580d89Bob Halley</directivesynopsis>
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley<directivesynopsis>
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson<description>Sets filename and format of log file</description>
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson[env=[!]<var>environment-variable</var>]</syntax>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<contextlist><context>server config</context><context>virtual host</context>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley</contextlist>
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley <p>The <directive>CustomLog</directive> directive is used to
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson log requests to the server. A log format is specified, and the
726290e9d5b720b736fa39d9f7d92c2efb7d1f24Bob Halley logging can optionally be made conditional on request
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson characteristics using environment variables.</p>
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson <p>The first argument, which specifies the location to which
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson the logs will be written, can take one of the following two
fd15c8e32ed0c1cfd3ed737858a81966e7fbaeacAndreas Gustafsson types of values:</p>
38980568375a6505452550b5677104ab44291b66Bob Halley <dd>A filename, relative to the <directive module="core"
38980568375a6505452550b5677104ab44291b66Bob Halley <dd>The pipe character "<code>|</code>", followed by the path
38980568375a6505452550b5677104ab44291b66Bob Halley to a program to receive the log information on its standard
38980568375a6505452550b5677104ab44291b66Bob Halley <p>If a program is used, then it will be run as the user who
38980568375a6505452550b5677104ab44291b66Bob Halley started <program>httpd</program>. This will be root if the server was
38980568375a6505452550b5677104ab44291b66Bob Halley started by root; be sure that the program is secure.</p>
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington <p>When entering a file path on non-Unix platforms, care should be taken
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington to make sure that only forward slashed are used even though the platform
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington may allow the use of back slashes. In general it is a good idea to always
c8d4fd89265d8a574eea84f084f594b9eb6f8569Andreas Gustafsson use forward slashes throughout the configuration files.</p>
c8d4fd89265d8a574eea84f084f594b9eb6f8569Andreas Gustafsson <p>The second argument specifies what will be written to the
f93d33e24fdf76eb2558168f018b8992bcfc5681Andreas Gustafsson log file. It can specify either a <var>nickname</var> defined by
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington a previous <directive module="mod_log_config">LogFormat</directive>
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington directive, or it can be an explicit <var>format</var> string as
b984520acca2532d048eae929dc0682dd334c7a3Brian Wellington described in the <a href="#formats">log formats</a> section.</p>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews <p>For example, the following two sets of directives have
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley exactly the same effect:</p>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews # CustomLog with format nickname<br />
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley LogFormat "%h %l %u %t \"%r\" %>s %b" common<br />
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley # CustomLog with explicit format string<br />
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <p>The third argument is optional and controls whether or
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley not to log a particular request based on the
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley presence or absence of a particular variable in the server
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley environment. If the specified <a href="/env.html">environment
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley variable</a> is set for the request (or is not set, in the case
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley of a '<code>env=!<var>name</var></code>' clause), then the
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley request will be logged.</p>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <p>Environment variables can be set on a per-request
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley example, if you want to record requests for all GIF
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley images on your server in a separate logfile but not in your main
2429ed58a2d4732887a8efd9797087004fae1b28Bob Halley log, you can use:</p>
2429ed58a2d4732887a8efd9797087004fae1b28Bob Halley SetEnvIf Request_URI \.gif$ gif-image<br />
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley CustomLog gif-requests.log common env=gif-image<br />
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley CustomLog nongif-requests.log common env=!gif-image
e7dbdb25475cdca583dd41f053da2d7c53622b6cBob Halley <p>Or, to reproduce the behavior of the old RefererIgnore
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews directive, you might use the following:</p>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews SetEnvIf Referer example\.com localreferer<br />
e7dbdb25475cdca583dd41f053da2d7c53622b6cBob Halley CustomLog referer.log referer env=!localreferer
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews</directivesynopsis>
e7dbdb25475cdca583dd41f053da2d7c53622b6cBob Halley<directivesynopsis>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews<description>Describes a format for use in a log file</description>
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews<syntax>LogFormat <var>format</var>|<var>nickname</var>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<default>LogFormat "%h %l %u %t \"%r\" %>s %b"</default>
8f5df5f1fe5aa989dee774cbc2c37c84bfd251d8Bob Halley<contextlist><context>server config</context><context>virtual host</context>
8f5df5f1fe5aa989dee774cbc2c37c84bfd251d8Bob Halley</contextlist>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <p>This directive specifies the format of the access log
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <p>The <directive>LogFormat</directive> directive can take one of two
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley forms. In the first form, where only one argument is specified,
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews this directive sets the log format which will be used by logs
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley specified in subsequent <directive>TransferLog</directive>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley directives. The single argument can specify an explicit
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <var>format</var> as discussed in the <a href="#formats">custom log
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley formats</a> section above. Alternatively, it can use a
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <var>nickname</var> to refer to a log format defined in a
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley previous <directive>LogFormat</directive> directive as described
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <p>The second form of the <directive>LogFormat</directive>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley directive associates an explicit <var>format</var> with a
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <var>nickname</var>. This <var>nickname</var> can then be used in
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <directive module="mod_log_config">CustomLog</directive> directives
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley rather than repeating the entire format string. A
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <directive>LogFormat</directive> directive that defines a nickname
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <strong>does nothing else</strong> -- that is, it <em>only</em>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley defines the nickname, it doesn't actually apply the format and make
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley it the default. Therefore, it will not affect subsequent
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <directive module="mod_log_config">TransferLog</directive> directives.
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews In addition, <directive>LogFormat</directive> cannot use one nickname
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley to define another nickname. Note that the nickname should not contain
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
c627721fedbb33c18bf577c46ff281a8c3bc082fMark Andrews</directivesynopsis>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<directivesynopsis>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<description>Specify location of a log file</description>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<syntax>TransferLog <var>file</var>|<var>pipe</var></syntax>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley<contextlist><context>server config</context><context>virtual host</context>
19f08273e2592fa48608ec1ac5e021b4b3489030Bob Halley</contextlist>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <p>This directive has exactly the same arguments and effect as
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley the <directive module="mod_log_config">CustomLog</directive>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley directive, with the exception that it does not allow the log format
8f5df5f1fe5aa989dee774cbc2c37c84bfd251d8Bob Halley to be specified explicitly or for conditional logging of requests.
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley Instead, the log format is determined by the most recently specified
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley <directive module="mod_log_config">LogFormat</directive> directive
8d3b82dc8c38549de3d92c694e389a17196f17adBob Halley which does not define a nickname. Common Log Format is used if no
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley other format has been specified.</p>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""<br />
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley</directivesynopsis>
c56c5586b49ccddbaf7e2b5c6c06adee1c509253Bob Halley</modulesynopsis>