mod_log_forensic.xml revision 158222078a98fb13cddf2793b42f7eb8eafe51ae
beaad6ac31022179c44d88536811e9ccd9425696nd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
beaad6ac31022179c44d88536811e9ccd9425696nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
6fbd2e53c97ea6976d93e0ac521adabc55e0fb73nd<!-- $LastChangedRevision$ -->
beaad6ac31022179c44d88536811e9ccd9425696nd Licensed to the Apache Software Foundation (ASF) under one or more
beaad6ac31022179c44d88536811e9ccd9425696nd contributor license agreements. See the NOTICE file distributed with
beaad6ac31022179c44d88536811e9ccd9425696nd this work for additional information regarding copyright ownership.
beaad6ac31022179c44d88536811e9ccd9425696nd The ASF licenses this file to You under the Apache License, Version 2.0
beaad6ac31022179c44d88536811e9ccd9425696nd (the "License"); you may not use this file except in compliance with
beaad6ac31022179c44d88536811e9ccd9425696nd the License. You may obtain a copy of the License at
beaad6ac31022179c44d88536811e9ccd9425696nd Unless required by applicable law or agreed to in writing, software
beaad6ac31022179c44d88536811e9ccd9425696nd distributed under the License is distributed on an "AS IS" BASIS,
beaad6ac31022179c44d88536811e9ccd9425696nd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
01c674544bd4c211141bcd9fb09b96ffc18c6c3dnd See the License for the specific language governing permissions and
7e68fce3cbd2246164e045a51ecd77f9f26680ednd limitations under the License.
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<description>Forensic Logging of the requests made to the server</description>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>This module provides for forensic logging of client
7e68fce3cbd2246164e045a51ecd77f9f26680ednd requests. Logging is done before and after processing a request, so the
7e68fce3cbd2246164e045a51ecd77f9f26680ednd forensic log contains two log lines for each request.
7e68fce3cbd2246164e045a51ecd77f9f26680ednd The forensic logger is very strict, which means:</p>
9a658bb3989694b409e700f2842c892224fc9700nd <li>The format is fixed. You cannot modify the logging format at
7e68fce3cbd2246164e045a51ecd77f9f26680ednd runtime.</li>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <li>If it cannot write its data, the child process
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd exits immediately and may dump core (depending on your
9a658bb3989694b409e700f2842c892224fc9700nd <directive module="mpm_common">CoreDumpDirectory</directive>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd configuration).</li>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>The <code>check_forensic</code> script, which can be found in the
9a658bb3989694b409e700f2842c892224fc9700nd distribution's support directory, may be helpful in evaluating the
8cfbcde8e416fd60132dd4324c42a5098da156cfnd forensic log output.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<seealso><a href="/logs.html">Apache Log Files</a></seealso>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>Each request is logged two times. The first time is <em>before</em> it's
7e68fce3cbd2246164e045a51ecd77f9f26680ednd processed further (that is, after receiving the headers). The second log
7e68fce3cbd2246164e045a51ecd77f9f26680ednd entry is written <em>after</em> the request processing at the same time
7e68fce3cbd2246164e045a51ecd77f9f26680ednd where normal logging occurs.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>In order to identify each request, a unique request ID is assigned.
7e68fce3cbd2246164e045a51ecd77f9f26680ednd This forensic ID can be cross logged in the normal transfer log using the
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <code>%{forensic-id}n</code> format string. If you're using
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <module>mod_unique_id</module>, its generated ID will be used.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>The first line logs the forensic ID, the request line and all received
7e68fce3cbd2246164e045a51ecd77f9f26680ednd headers, separated by pipe characters (<code>|</code>). A sample line
7e68fce3cbd2246164e045a51ecd77f9f26680ednd looks like the following (all on one line):</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd HTTP/1.1|Host:localhost%3a8080|User-Agent:Mozilla/5.0 (X11;
7e68fce3cbd2246164e045a51ecd77f9f26680ednd </example>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>The plus character at the beginning indicates that this is the first log
7e68fce3cbd2246164e045a51ecd77f9f26680ednd line of this request. The second line just contains a minus character and
7e68fce3cbd2246164e045a51ecd77f9f26680ednd the ID again:</p>
9a658bb3989694b409e700f2842c892224fc9700nd -yQtJf8CoAB4AAFNXBIEAAAAA
9a658bb3989694b409e700f2842c892224fc9700nd </example>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>The <code>check_forensic</code> script takes as its argument the name
7e68fce3cbd2246164e045a51ecd77f9f26680ednd of the logfile. It looks for those <code>+</code>/<code>-</code> ID pairs
7e68fce3cbd2246164e045a51ecd77f9f26680ednd and complains if a request was not completed.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<section id="security"><title>Security Considerations</title>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd href="/misc/security_tips.html#serverroot">security tips</a>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd document for details on why your security could be compromised
7e68fce3cbd2246164e045a51ecd77f9f26680ednd if the directory where logfiles are stored is writable by
7e68fce3cbd2246164e045a51ecd77f9f26680ednd anyone other than the user that starts the server.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>The log files may contain sensitive data such as the contents of
9a658bb3989694b409e700f2842c892224fc9700nd <code>Authorization:</code> headers (which can contain passwords), so
7e68fce3cbd2246164e045a51ecd77f9f26680ednd they should not be readable by anyone except the user that starts the
7e68fce3cbd2246164e045a51ecd77f9f26680ednd server.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<directivesynopsis>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<description>Sets filename of the forensic log</description>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<syntax>ForensicLog <var>filename</var>|<var>pipe</var></syntax>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd<contextlist><context>server config</context><context>virtual host</context>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd</contextlist>
9a658bb3989694b409e700f2842c892224fc9700nd <p>The <directive>ForensicLog</directive> directive is used to
7e68fce3cbd2246164e045a51ecd77f9f26680ednd log requests to the server for forensic analysis. Each log entry
7e68fce3cbd2246164e045a51ecd77f9f26680ednd is assigned a unique ID which can be associated with the request
7e68fce3cbd2246164e045a51ecd77f9f26680ednd using the normal <directive module="mod_log_config">CustomLog</directive>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd directive. <module>mod_log_forensic</module> creates a token called
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <code>forensic-id</code>, which can be added to the transfer log
7e68fce3cbd2246164e045a51ecd77f9f26680ednd using the <code>%{forensic-id}n</code> format string.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>The argument, which specifies the location to which
480bee29abcc415b6b8c18d2ecbf2c5f88f1f05bnd the logs will be written, can take one of the following two
7e68fce3cbd2246164e045a51ecd77f9f26680ednd types of values:</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <dd>The pipe character "<code>|</code>", followed by the path
7e68fce3cbd2246164e045a51ecd77f9f26680ednd to a program to receive the log information on its standard
7e68fce3cbd2246164e045a51ecd77f9f26680ednd input. The program name can be specified relative to the <directive
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>If a program is used, then it will be run as the user who
7e68fce3cbd2246164e045a51ecd77f9f26680ednd started <program>httpd</program>. This will be root if the server was
7e68fce3cbd2246164e045a51ecd77f9f26680ednd started by root; be sure that the program is secure or switches to a
7e68fce3cbd2246164e045a51ecd77f9f26680ednd less privileged user.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd <p>When entering a file path on non-Unix platforms, care should be taken
7e68fce3cbd2246164e045a51ecd77f9f26680ednd to make sure that only forward slashes are used even though the platform
7e68fce3cbd2246164e045a51ecd77f9f26680ednd may allow the use of back slashes. In general it is a good idea to always
7e68fce3cbd2246164e045a51ecd77f9f26680ednd use forward slashes throughout the configuration files.</p>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd</directivesynopsis>
7e68fce3cbd2246164e045a51ecd77f9f26680ednd</modulesynopsis>