mod_log_config.xml revision 33d6d297ef4fe7ea963e9641c8482d677f557df0
530eba85dbd41b8a0fa5255d3648d1440199a661slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
08cb74ca432a8c24e39f17dedce527e6a47b8001jerenkrantz Licensed to the Apache Software Foundation (ASF) under one or more
08cb74ca432a8c24e39f17dedce527e6a47b8001jerenkrantz contributor license agreements. See the NOTICE file distributed with
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd this work for additional information regarding copyright ownership.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd The ASF licenses this file to You under the Apache License, Version 2.0
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd (the "License"); you may not use this file except in compliance with
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Logging of the requests made to the server</description>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>This module provides for flexible logging of client
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna requests. Logs are written in a customizable format, and may be
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna written directly to a file, or to an external program.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna Conditional logging is provided so that individual requests may
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna be included or excluded from the logs based on characteristics
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna of the request.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>Three directives are provided by this module:
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <directive module="mod_log_config">TransferLog</directive> to create
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna a log file, <directive module="mod_log_config">LogFormat</directive>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna to set a custom format, and <directive module="mod_log_config"
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna >CustomLog</directive> to define a log file and format in one
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna step. The <directive>TransferLog</directive> and <directive
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna >CustomLog</directive> directives can be used multiple times in each
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna server to cause each request to be logged to multiple files.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<seealso><a href="/logs.html">Apache Log Files</a></seealso>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<section id="formats"><title>Custom Log Formats</title>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The format argument to the <directive module="mod_log_config"
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna >LogFormat</directive> and <directive module="mod_log_config"
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna >CustomLog</directive> directives is a string. This string is
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna used to log each request to the log file. It can contain literal
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna characters copied into the log files and the C-style control
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna characters "\n" and "\t" to represent new-lines and tabs.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna Literal quotes and backslashes should be escaped with
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna backslashes.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The characteristics of the request itself are logged by
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna placing "<code>%</code>" directives in the format string, which are
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna replaced in the log file by the values as follows:</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <columnspec><column width=".2"/><column width=".8"/></columnspec>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <td>Client IP address of the request (see the
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <td>Underlying peer IP address of the connection (see the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>Size of response in bytes, excluding HTTP headers.</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>Size of response in bytes, excluding HTTP headers. In CLF format, <em>i.e.</em>
18b4b0fd6056093002ddef488636bf5ebe415ef0erikabele a '<code>-</code>' rather than a 0 when no bytes are sent.</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The contents of cookie <var>VARNAME</var> in the request sent
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to the server. Only version 0 cookies are fully supported.</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The time taken to serve the request, in microseconds.</td></tr>
fb77c505254b6e9c925e23e734463e87574f8f40kess <td>The contents of the environment variable
fb77c505254b6e9c925e23e734463e87574f8f40kess <td>Remote hostname. Will log the IP address if <directive
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code>Off</code>, which is the default. If it logs the hostname
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive for only a few hosts, you probably have access control
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive directives mentioning them by name. See <a
fb77c505254b6e9c925e23e734463e87574f8f40kess href="mod_authz_host.html#reqhost">the Require host
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The contents of <code><var>VARNAME</var>:</code> header line(s)
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive in the request sent to the server. Changes made by other
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive modules (e.g. <module>mod_headers</module>) affect this. If you're
fb77c505254b6e9c925e23e734463e87574f8f40kess interested in what the request header was prior to when most
fb77c505254b6e9c925e23e734463e87574f8f40kess modules would have modified it, use <module>mod_setenvif</module>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to copy the header into an internal environment variable and log
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive that value with the <code>%{<var>VARNAME</var>}e</code> described
fb77c505254b6e9c925e23e734463e87574f8f40kess <td>Number of keepalive requests handled on this connection. Interesting if
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <directive module="core">KeepAlive</directive> is being used, so that,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive for example, a '1' means the first keepalive request after the initial
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive one, '2' the second, etc...;
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive otherwise this is always 0 (indicating the initial request).</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>Remote logname (from identd, if supplied). This will return a
fb77c505254b6e9c925e23e734463e87574f8f40kess dash unless <module>mod_ident</module> is present and <directive
130d299c4b2b15be45532a176604c71fdc7bea5bnd <td>The request log ID from the error log (or '-' if nothing has been
130d299c4b2b15be45532a176604c71fdc7bea5bnd logged to the error log for this request). Look for the
130d299c4b2b15be45532a176604c71fdc7bea5bnd matching error log line to see what request caused what error.</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The contents of <code><var>VARNAME</var>:</code> header line(s)
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The canonical port of the server serving the request.</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The canonical port of the server serving the request, or the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive server's actual port, or the client's actual port. Valid formats
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess are <code>canonical</code>, <code>local</code>, or <code>remote</code>.
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess <td>The process ID of the child that serviced the request.</td></tr>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <td>The process ID or thread ID of the child that serviced the
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd request. Valid formats are <code>pid</code>, <code>tid</code>,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive and <code>hextid</code>. <code>hextid</code> requires APR 1.2.0 or
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The query string (prepended with a <code>?</code> if a query
130d299c4b2b15be45532a176604c71fdc7bea5bnd <td>The handler generating the response (if any).</td></tr>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>Status. For requests that have been internally redirected, this is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive the status of the <em>original</em> request. Use <code>%>s</code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>Time the request was received, in the format <code>[18/Sep/2011:19:18:28 -0400]</code>.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The last number indicates the timezone offset from GMT</td></tr>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <td>The time, in the form given by format, which should be in
530eba85dbd41b8a0fa5255d3648d1440199a661slive an extended <code>strftime(3)</code> format (potentially localized).
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive If the format starts with <code>begin:</code> (default) the time is taken
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive at the beginning of the request processing. If it starts with
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code>end:</code> it is the time when the log entry gets written,
003f0c9fda6664daf5092a0e42f65ede20098153slive close to the end of the request processing. In addition to the formats
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive supported by <code>strftime(3)</code>, the following format tokens are
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <tr><td><code>sec</code></td><td>number of seconds since the Epoch</td></tr>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <tr><td><code>msec</code></td><td>number of milliseconds since the Epoch</td></tr>
684f2a9a422185adda0692a1203c5ad6687fc5c5nd <tr><td><code>usec</code></td><td>number of microseconds since the Epoch</td></tr>
a8ce9095d102e43fecb81093a132b90b9a227f78kess <tr><td><code>msec_frac</code></td><td>millisecond fraction</td></tr>
684f2a9a422185adda0692a1203c5ad6687fc5c5nd <tr><td><code>usec_frac</code></td><td>microsecond fraction</td></tr>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding These tokens can not be combined with each other or <code>strftime(3)</code>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding formatting in the same format string. You can use multiple
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>The time taken to serve the request, in seconds.</td></tr>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <td>Remote user if the request was authenticated. May be bogus if return status
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <td>The URL path requested, not including any query string.</td></tr>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <td>The canonical <directive module="core">ServerName</directive>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <td>The server name according to the <directive module="core"
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <td>Connection status when response is completed:
58699879a562774640b95e9eedfd891f336e38c2nd <columnspec><column width=".2"/><column width=".6"/></columnspec>
fb77c505254b6e9c925e23e734463e87574f8f40kess <td>Connection aborted before the response completed.</td></tr>
58699879a562774640b95e9eedfd891f336e38c2nd <td>Connection may be kept alive after the response is
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <td>Connection will be closed after the response is
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <td>Bytes received, including request and headers. Cannot be zero.
58699879a562774640b95e9eedfd891f336e38c2nd You need to enable <module>mod_logio</module> to use this.</td></tr>
fb77c505254b6e9c925e23e734463e87574f8f40kess <td>Bytes sent, including headers. Cannot be zero. You need to
fb77c505254b6e9c925e23e734463e87574f8f40kess enable <module>mod_logio</module> to use this.</td></tr>
58699879a562774640b95e9eedfd891f336e38c2nd <td>Bytes transferred (received and sent), including request and headers,
58699879a562774640b95e9eedfd891f336e38c2nd cannot be zero. This is the combination of %I and %O. You need to
58699879a562774640b95e9eedfd891f336e38c2nd <p>Particular items can be restricted to print only for
58699879a562774640b95e9eedfd891f336e38c2nd responses with specific HTTP status codes by placing a
fb77c505254b6e9c925e23e734463e87574f8f40kess comma-separated list of status codes immediately following the
fb77c505254b6e9c925e23e734463e87574f8f40kess "%". The status code list may be preceded by a "<code>!</code>" to
fb77c505254b6e9c925e23e734463e87574f8f40kess indicate negation.</p>
58699879a562774640b95e9eedfd891f336e38c2nd <columnspec><column width=".2"/><column width=".8"/></columnspec>
58699879a562774640b95e9eedfd891f336e38c2nd <td>Logs <code>User-agent</code> on 400 errors and 501 errors only. For
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess other status codes, the literal string <code>"-"</code> will be
4a7affccb2f1f5b94cab395e1bf3825aed715ebcnd <p>The modifiers "<" and ">" can be used for requests that
4a7affccb2f1f5b94cab395e1bf3825aed715ebcnd have been internally redirected to choose whether the original
4a7affccb2f1f5b94cab395e1bf3825aed715ebcnd or final (respectively) request should be consulted. By
58699879a562774640b95e9eedfd891f336e38c2nd %D,</code> and <code>%r</code> look at the original request
58699879a562774640b95e9eedfd891f336e38c2nd while all others look at the final request. So for example,
58699879a562774640b95e9eedfd891f336e38c2nd <code>%>s</code> can be used to record the final status of
58699879a562774640b95e9eedfd891f336e38c2nd the request and <code>%<u</code> can be used to record the
58699879a562774640b95e9eedfd891f336e38c2nd original authenticated user on a request that is internally
4a7affccb2f1f5b94cab395e1bf3825aed715ebcnd redirected to an unauthenticated resource.</p>
58699879a562774640b95e9eedfd891f336e38c2nd </section>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <p>For security reasons, starting with version 2.0.46,
77ead9e0262e4f08ec336d1a65b2edef7705c839nd non-printable and other special characters in <code>%r</code>,
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <code>\x<var>hh</var></code> sequences, where <var>hh</var>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd stands for the hexadecimal representation of the raw
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <code>\</code>, which are escaped by prepending a backslash, and
77ead9e0262e4f08ec336d1a65b2edef7705c839nd all whitespace characters, which are written in their C-style
77ead9e0262e4f08ec336d1a65b2edef7705c839nd notation (<code>\n</code>, <code>\t</code>, etc). In versions
77ead9e0262e4f08ec336d1a65b2edef7705c839nd prior to 2.0.46, no escaping was performed on these strings so
77ead9e0262e4f08ec336d1a65b2edef7705c839nd you had to be quite careful when dealing with raw log files.</p>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <code>%B</code> format strings do not represent the number of
77ead9e0262e4f08ec336d1a65b2edef7705c839nd bytes sent to the client, but simply the size in bytes of the
77ead9e0262e4f08ec336d1a65b2edef7705c839nd HTTP response (which will differ, for instance, if the
77ead9e0262e4f08ec336d1a65b2edef7705c839nd connection is aborted, or if SSL is used). The <code>%O</code>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd format provided by <module>mod_logio</module> will log the
9b5e2c5e769dc678a1aca06df75c32022b2f1492trawick actual number of bytes sent over the network.</p>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd quick-handler and not as a standard handler. Therefore, the
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <code>%R</code> format string will not return any handler
77ead9e0262e4f08ec336d1a65b2edef7705c839nd information when content caching is involved.</p>
fb77c505254b6e9c925e23e734463e87574f8f40kess <dd><code>"%v %h %l %u %t \"%r\" %>s %b"</code></dd>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess <dd><code>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
fb77c505254b6e9c925e23e734463e87574f8f40kess <p>You can use the <code>%{format}t</code> directive multiple
fb77c505254b6e9c925e23e734463e87574f8f40kess times to build up a time format using the extended format tokens
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<dd><code>"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"</code></dd>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd </section>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<section id="security"><title>Security Considerations</title>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive href="/misc/security_tips.html#serverroot">security tips</a>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive document for details on why your security could be compromised
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive if the directory where logfiles are stored is writable by
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive anyone other than the user that starts the server.</p>
9ed9eaf871c58d281af02e76125ceadb5060afa5nd<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Buffer log entries in memory before writing to disk</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context></contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The <directive>BufferedLogs</directive> directive causes
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <module>mod_log_config</module> to store several log entries in
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive memory and write them together to disk, rather than writing them
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive after each request. On some systems, this may result in more
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive efficient disk access and hence higher performance. It may be
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive set only once for the entire server; it cannot be configured
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive per virtual-host.</p>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess <note>This directive should be used with caution as a crash might
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive cause loss of logging data.</note>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem</directivesynopsis>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<directivesynopsis>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<description>Sets filename and format of log file</description>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem<contextlist><context>server config</context><context>virtual host</context>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem</contextlist>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <p>The <directive>CustomLog</directive> directive is used to
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem log requests to the server. A log format is specified, and the
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem logging can optionally be made conditional on request
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem characteristics using environment variables.</p>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <p>The first argument, which specifies the location to which
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive the logs will be written, can take one of the following two
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive types of values:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <dd>A filename, relative to the <directive module="core"
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <dd>The pipe character "<code>|</code>", followed by the path
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to a program to receive the log information on its standard
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive input. See the notes on <a href="/logs.html#piped">piped logs</a>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive for more information.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>If a program is used, then it will be run as the user who
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive started <program>httpd</program>. This will be root if the server was
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive started by root; be sure that the program is secure.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When entering a file path on non-Unix platforms, care should be taken
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to make sure that only forward slashed are used even though the platform
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive may allow the use of back slashes. In general it is a good idea to always
9ed9eaf871c58d281af02e76125ceadb5060afa5nd use forward slashes throughout the configuration files.</p>
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna <p>The second argument specifies what will be written to the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive log file. It can specify either a <var>nickname</var> defined by
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive a previous <directive module="mod_log_config">LogFormat</directive>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive directive, or it can be an explicit <var>format</var> string as
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive described in the <a href="#formats">log formats</a> section.</p>
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna <p>For example, the following two sets of directives have
f23fb63b05f89f47d7a3099491f2c68dcce432e9kess exactly the same effect:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive# CustomLog with format nickname
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveLogFormat "%h %l %u %t \"%r\" %>s %b" common
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd# CustomLog with explicit format string
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd </highlight>
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd <p>The third argument is optional and controls whether or
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd not to log a particular request. The condition can be the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive presence or absence (in the case of a '<code>env=!<var>name</var></code>'
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive clause) of a particular variable in the server
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <a href="/env.html">environment</a>. Alternatively, the condition
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive can be expressed as arbitrary boolean <a href="/expr.html"
54bcd0e21a5c79158afd3b78bf707a493a5fb33crbowen >expression</a>. If the condition is not satisfied, the request
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive will not be logged. References to HTTP headers in the expression
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive will not cause the header names to be added to the Vary header.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Environment variables can be set on a per-request
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd example, if you want to record requests for all GIF
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive images on your server in a separate logfile but not in your main
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive log, you can use:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveSetEnvIf Request_URI \.gif$ gif-image
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveCustomLog gif-requests.log common env=gif-image
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveCustomLog nongif-requests.log common env=!gif-image
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </highlight>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Or, to reproduce the behavior of the old RefererIgnore
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive directive, you might use the following:</p>
9ed9eaf871c58d281af02e76125ceadb5060afa5ndSetEnvIf Referer example\.com localreferer
9ed9eaf871c58d281af02e76125ceadb5060afa5ndCustomLog referer.log referer env=!localreferer
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </highlight>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<description>Describes a format for use in a log file</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>LogFormat <var>format</var>|<var>nickname</var>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<default>LogFormat "%h %l %u %t \"%r\" %>s %b"</default>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist><context>server config</context><context>virtual host</context>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>This directive specifies the format of the access log
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The <directive>LogFormat</directive> directive can take one of two
003f0c9fda6664daf5092a0e42f65ede20098153slive forms. In the first form, where only one argument is specified,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive this directive sets the log format which will be used by logs
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive specified in subsequent <directive>TransferLog</directive>
530eba85dbd41b8a0fa5255d3648d1440199a661slive directives. The single argument can specify an explicit
530eba85dbd41b8a0fa5255d3648d1440199a661slive <var>format</var> as discussed in the <a href="#formats">custom log
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive formats</a> section above. Alternatively, it can use a
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <var>nickname</var> to refer to a log format defined in a
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive previous <directive>LogFormat</directive> directive as described
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <p>The second form of the <directive>LogFormat</directive>
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive directive associates an explicit <var>format</var> with a
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <var>nickname</var>. This <var>nickname</var> can then be used in
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <directive module="mod_log_config">CustomLog</directive> directives
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive rather than repeating the entire format string. A
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <directive>LogFormat</directive> directive that defines a nickname
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <strong>does nothing else</strong> -- that is, it <em>only</em>
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive defines the nickname, it doesn't actually apply the format and make
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive it the default. Therefore, it will not affect subsequent
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive <directive module="mod_log_config">TransferLog</directive> directives.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive In addition, <directive>LogFormat</directive> cannot use one nickname
a2920e90d95fa04c15bdbbc03e7f8636eac92423slive to define another nickname. Note that the nickname should not contain
fb77c505254b6e9c925e23e734463e87574f8f40kess LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes </highlight>
fb77c505254b6e9c925e23e734463e87574f8f40kess </example>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes</directivesynopsis>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes<directivesynopsis>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes<description>Specify location of a log file</description>
fb77c505254b6e9c925e23e734463e87574f8f40kess<syntax>TransferLog <var>file</var>|<var>pipe</var></syntax>
fb77c505254b6e9c925e23e734463e87574f8f40kess<contextlist><context>server config</context><context>virtual host</context>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess</contextlist>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes <p>This directive has exactly the same arguments and effect as
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes the <directive module="mod_log_config">CustomLog</directive>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive directive, with the exception that it does not allow the log format
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to be specified explicitly or for conditional logging of requests.
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess Instead, the log format is determined by the most recently specified
fb77c505254b6e9c925e23e734463e87574f8f40kess <directive module="mod_log_config">LogFormat</directive> directive
fb77c505254b6e9c925e23e734463e87574f8f40kess which does not define a nickname. Common Log Format is used if no
fb77c505254b6e9c925e23e734463e87574f8f40kess other format has been specified.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveLogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </highlight>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</modulesynopsis>