mod_log_config

概述

本模块提供了灵活的方法将客户请求记录到日志。日志可以用自定义的格式直接写入文件，或者传送到一个外部程序继续处理。条件日志功能可以实现根据请求的特征来决定一个日志信息是否被包含在最终的日志记录里面。

本模块提供了三个指令：TransferLog指令用来指定日志文件，LogFormat指令用来定义日志格式，CustomLog指令可以同时完成指定日志文件和定义日志格式。TransferLog和CustomLog指令在每个服务器上都可以被多次使用，以便将同一个请求记录到多个文件中。

定制日志文件格式

LogFormat和CustomLog指令的格式化参数是一个字符串。这个字符串会在每次请求发生的时候，被记录到日志中去。它可以包含将被原样写入日志的文本字符串以及C风格的控制字符"\n"和"\t"以实现换行与制表。文本中的引号和反斜杠应通过"\"来转义。

请求本身的情况将通过在格式字符串中放置各种"%"转义符的方法来记录，它们在写入日志文件时，根据下表的定义进行转换：

修饰符

可以紧跟在"%"后面加上一个逗号分隔的状态码列表来限制记录的条目。例如，"%400,501{User-agent}i"只记录状态码400和501发生时的User-agent头内容；不满足条件时用"-"代替。状态码前还可以加上"!"前缀表示否定，"%!200,304,302{Referer}i"记录所有不同于200,304,302的状态码发生时的Referer头内容。

"<"和">"修饰符可以用来指定对于已被内部重定向的请求是选择原始的请求还是选择最终的请求。默认情况下，%s, %U, %T, %D, %r 使用原始请求，而所有其他格式串则选择最终请求。例如，%>s 可以用于记录请求的最终状态，而 %<u 则记录一个已经被内部重定向到非认证资源的请求的原始认证用户。

一些说明

出于安全考虑，从2.0.46版本开始，%r, %i, %o 中的特殊字符，除了双引号(")和反斜线(\)分别用 \" 和 \\ 进行转义、空白字符用C风格(\n, \t 等)进行转义以外，非打印字符和其它特殊字符使用 \xhh 格式进行转义(hh是该字符的16进制编码)。在2.0.46以前的版本中，这些内容会被完整的按原样记录。这种做法将导致客户端可以在日志中插入控制字符，所以你在处理这些日志文件的时候要特别小心。

在2.0版本中(不同于1.3)，%b 和 %B 格式字符串并不表示发送到客户端的字节数，而只是简单的表示HTTP应答字节数(在连接中断或使用SSL时与前者有所不同)。mod_logio提供的 %O 格式字符串将会记录发送的实际字节数。

示例

一些常见的格式串：

通用日志格式(CLF)

"%h %l %u %t \"%r\" %>s %b"

带虚拟主机的通用日志格式

"%v %h %l %u %t \"%r\" %>s %b"

NCSA扩展/组合日志格式

"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""

Referer日志格式

"%{Referer}i -> %U"

Agent(Browser)日志格式

"%{User-agent}i"

安全考虑

如果放置日志文件的目录对除启动Apache服务以外的其他用户可写，可能会对系统的安全性造成威胁，具体的讨论请参见安全方面的提示。

BufferedLogs 指令

BufferedLogs指令使得mod_log_config先在内存中缓冲一些日志内容，然后一次性写入磁盘，而不是立即写入。在一些系统上这样做可以提高磁盘性能。这个设置仅能够针对全局进行设置，不能单独针对虚拟主机进行设置。

CookieLog 指令

CookieLog指令使用cookies作为日志文件名。文件是相对于ServerRoot目录的。包含本指令仅仅是为了保持与mod_cookies模块的兼容，并且反对使用。

CustomLog 指令

CustomLog指令用来对服务器的请求进行日志记录。可以指定日志的格式，也可以使用环境变量根据请求的特征来自由地组织日志。

第一个参数指定了日志记录的位置，可以使用以下两种方式来设定：

file

相对于ServerRoot的日志文件名。

pipe

管道符"|"后面紧跟着一个把日志输出当作标准输入的处理程序路径。

安全

如果这里用到了程序，那么这个程序是以启动httpd的用户来执行的。因此如果启动httpd的用户是root ，那这个程序也将以root身份来运行；你需要确认这个程序是安全的。

注意

当在非UNIX平台上输入文件路径的时候，要特别注意即使平台本身是使用反斜杠(\)来分隔路径的，在这里也只能使用正斜杠(/)。通常在配置文件里只用正斜杠(/)来分隔路径总是不会错的。

第二个参数指定了写入日志文件的内容。它既可以是由前面的LogFormat指令定义的nickname ，也可以是直接按日志格式一节所描述的规则定义的format字符串。

例如：以下两组指令的结果是完全一样的：

# 使用nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common

# 明确使用格式格式字符串
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"

第三个参数是可选的，它根据服务器上特定的环境变量是否被设置来决定是否对某一特定的请求进行日志记录。如果这个特定的环境变量被设置(或者在"env=!name"的情况下未被设置)，那么这个请求将被记录。

可以使用mod_setenvif和/或mod_rewrite模块来为每个请求设置环境变量。例如：如果你想在服务器上将所有对GIF图片的请求记录在不同于主日志文件的另一个日志文件中，你可以使用下面的指令：

SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image

或者为了复制旧有的RefererIgnore指令的行为，你可以使用下面的指令：

SetEnvIf Referer example\.com localreferer
CustomLog referer.log referer env=!localreferer

LogFormat 指令

本指令定义访问日志的记录格式。

LogFormat指令可以使用两种定义格式中的一种。在第一种格式中，指令只带一个参数，以定义后续的TransferLog指令定义的日志格式。这个唯一的参数可以按上述自定义日志格式小节所描述的format来定义。另外它也可以通过下述的方法使用nickname来引用某个之前的LogFormat定义的日志格式。

第二种定义LogFormat指令的格式中，将一个直接的format和一个nickname联系起来。这样在后续的LogFormat或CustomLog指令中，就不用一再重复整个冗长的格式串。定义别名的LogFormat指令仅仅用来定义一个nickname ，而不做其它任何事情：也就是说，它只是定义了这个别名，它既没有实际应用这个别名，也不是把它设为默认的格式。因此，它不会影响后续的TransferLog指令。另外，LogFormat不能用一个别名来定义另一个别名。注意，别名不能包含百分号(%)。

示例

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common

TransferLog 指令

本指令除不允许直接定义日志格式或根据条件进行日志记录外，与CustomLog指令有完全相同的参数和功能。实际应用中，日志的格式是由最近的非别名定义的LogFormat指令指定。如果没有定义任何日志格式，则使用通用日志格式。

示例

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log