# Apache模块 mod_log_config
| [说明](#calibre_link-11) | 允许记录日志和定制日志文件格式 |
| --- | --- |
| [状态](#calibre_link-12) | 基本(B) |
| [模块名](#calibre_link-13) | log_config_module |
| [源文件](#calibre_link-14) | mod_log_config.c |
### 概述
本模块提供了灵活的方法将客户请求记录到日志。日志可以用自定义的格式直接写入文件，或者传送到一个外部程序继续处理。条件日志功能可以实现根据请求的特征来决定一个日志信息是否被包含在最终的日志记录里面。
本模块提供了三个指令：`TransferLog`指令用来指定日志文件，`LogFormat`指令用来定义日志格式，`CustomLog`指令可以同时完成指定日志文件和定义日志格式。`TransferLog`和`CustomLog`指令在每个服务器上都可以被多次使用，以便将同一个请求记录到多个文件中。
## 定制日志文件格式
`LogFormat`和`CustomLog`指令的格式化参数是一个字符串。这个字符串会在每次请求发生的时候，被记录到日志中去。它可以包含将被原样写入日志的文本字符串以及C风格的控制字符"\n"和"\t"以实现换行与制表。文本中的引号和反斜杠应通过"\"来转义。
请求本身的情况将通过在格式字符串中放置各种"`%`"转义符的方法来记录，它们在写入日志文件时，根据下表的定义进行转换：
| 格式字符串 | 描述 |
| --- | --- |
| `%%` | 百分号(_Apache2.0.44或更高的版本_) |
| `%a` | 远端IP地址 |
| `%A` | 本机IP地址 |
| `%B` | 除HTTP头以外传送的字节数 |
| `%b` | 以CLF格式显示的除HTTP头以外传送的字节数，也就是当没有字节传送时显示'`-`'而不是0。 |
| `%{Foobar}C` | 在请求中传送给服务端的cookieFoobar的内容。 |
| `%D` | 服务器处理本请求所用时间，以微为单位。 |
| `%{FOOBAR}e` | 环境变量FOOBAR的值 |
| `%f` | 文件名 |
| `%h` | 远端主机 |
| `%H` | 请求使用的协议 |
| `%{Foobar}i` | 发送到服务器的请求头`Foobar:`的内容。 |
| `%l` | 远端登录名(由identd而来，如果支持的话)，除非`IdentityCheck`设为"`On`"，否则将得到一个"-"。 |
| `%m` | 请求的方法 |
| `%{Foobar}n` | 来自另一个模块的注解`Foobar`的内容。 |
| `%{Foobar}o` | 应答头`Foobar:`的内容。 |
| `%p` | 服务器服务于该请求的标准端口。 |
| `%P` | 为本请求提供服务的子进程的PID。 |
| `%{format}P` | 服务于该请求的PID或TID(线程ID)，`format`的取值范围为：`pid`和`tid`(_2.0.46及以后版本_)以及`hextid`(需要APR1.2.0及以上版本) |
| `%q` | 查询字符串(若存在则由一个"`?`"引导，否则返回空串) |
| `%r` | 请求的第一行 |
| `%s` | 状态。对于内部重定向的请求，这个状态指的是_原始_请求的状态，---`%>s`则指的是最后请求的状态。 |
| `%t` | 时间，用普通日志时间格式(标准英语格式) |
| `%{format}t` | 时间，用`strftime(3)`指定的格式表示的时间。(默认情况下按本地化格式) |
| `%T` | 处理完请求所花时间，以秒为单位。 |
| `%u` | 远程用户名(根据验证信息而来；如果返回status(`%s`)为401，可能是假的) |
| `%U` | 请求的URL路径，不包含查询字符串。 |
| `%v` | 对该请求提供服务的标准`ServerName`。 |
| `%V` | 根据`UseCanonicalName`指令设定的服务器名称。 |
| `%X` | 请求完成时的连接状态： `X`= 连接在应答完成前中断。 `+`= 应答传送完后继续保持连接。 `-`= 应答传送完后关闭连接。 (在1.3以后的版本中，这个指令是`%c`，但这样就和过去的SSL语法：`%{var}c`冲突了) |
| `%I` | 接收的字节数，包括请求头的数据，并且不能为零。要使用这个指令你必须启用`mod_logio`模块。 |
| `%O` | 发送的字节数，包括请求头的数据，并且不能为零。要使用这个指令你必须启用`mod_logio`模块。 |
### 修饰符
可以紧跟在"%"后面加上一个逗号分隔的状态码列表来限制记录的条目。例如，"`%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服务以外的其他用户可写，可能会对系统的安全性造成威胁，具体的讨论请参见[安全方面的提示](#calibre_link-281)。
## BufferedLogs 指令
| [说明](#calibre_link-18) | 在将日志写入磁盘前先在内存中进行缓冲 |
| --- | --- |
| [语法](#calibre_link-19) | `BufferedLogs On|Off` |
| [默认值](#calibre_link-24) | `BufferedLogs Off` |
| [作用域](#calibre_link-20) | server config |
| [状态](#calibre_link-21) | 基本(B) |
| [模块](#calibre_link-22) | mod_log_config |
| [兼容性](#calibre_link-137) | 仅在 Apache 2.0.41 及以后的版本中可用 |
`BufferedLogs`指令使得`mod_log_config`先在内存中缓冲一些日志内容，然后一次性写入磁盘，而不是立即写入。在一些系统上这样做可以提高磁盘性能。这个设置仅能够针对全局进行设置，不能单独针对虚拟主机进行设置。
这是一个试验性的指令，请在使用中多加小心。
## CookieLog 指令
| [说明](#calibre_link-18) | 设定针对cookies的日志文件名 |
| --- | --- |
| [语法](#calibre_link-19) | `CookieLog filename` |
| [作用域](#calibre_link-20) | server config, virtual host |
| [状态](#calibre_link-21) | 基本(B) |
| [模块](#calibre_link-22) | mod_log_config |
| [兼容性](#calibre_link-137) | 反对使用该指令 |
`CookieLog`指令使用cookies作为日志文件名。文件是相对于`ServerRoot`目录的。包含本指令仅仅是为了保持与`mod_cookies`模块的兼容，并且反对使用。
## CustomLog 指令
| [说明](#calibre_link-18) | 设定日志的文件名和格式 |
| --- | --- |
| [语法](#calibre_link-19) | `CustomLog file|pipe format|nickname [env=[!]environment-variable]` |
| [作用域](#calibre_link-20) | server config, virtual host |
| [状态](#calibre_link-21) | 基本(B) |
| [模块](#calibre_link-22) | mod_log_config |
`CustomLog`指令用来对服务器的请求进行日志记录。可以指定日志的格式，也可以使用环境变量根据请求的特征来自由地组织日志。
第一个参数指定了日志记录的位置，可以使用以下两种方式来设定：
file
相对于`ServerRoot`的日志文件名。
pipe
管道符"`|`"后面紧跟着一个把日志输出当作标准输入的处理程序路径。
### 安全
如果这里用到了程序，那么这个程序是以启动`httpd`的用户来执行的。因此如果启动httpd的用户是root ，那这个程序也将以root身份来运行；你需要确认这个程序是安全的。
### 注意
当在非UNIX平台上输入文件路径的时候，要特别注意即使平台本身是使用反斜杠(\)来分隔路径的，在这里也只能使用正斜杠(/)。通常在配置文件里只用正斜杠(/)来分隔路径总是不会错的。
第二个参数指定了写入日志文件的内容。它既可以是由前面的`LogFormat`指令定义的nickname ，也可以是直接按[日志格式](#calibre_link-72)一节所描述的规则定义的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"
```
第三个参数是可选的，它根据服务器上特定的环境变量是否被设置来决定是否对某一特定的请求进行日志记录。如果这个特定的[环境变量](#calibre_link-232)被设置(或者在"`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 指令
| [说明](#calibre_link-18) | 定义访问日志的记录格式 |
| --- | --- |
| [语法](#calibre_link-19) | `LogFormat format|nickname [nickname]` |
| [默认值](#calibre_link-24) | `LogFormat "%h %l %u %t \"%r\" %>s %b"` |
| [作用域](#calibre_link-20) | server config, virtual host |
| [状态](#calibre_link-21) | 基本(B) |
| [模块](#calibre_link-22) | mod_log_config |
本指令定义访问日志的记录格式。
`LogFormat`指令可以使用两种定义格式中的一种。在第一种格式中，指令只带一个参数，以定义后续的`TransferLog`指令定义的日志格式。这个唯一的参数可以按上述[自定义日志格式](#calibre_link-72)小节所描述的format来定义。另外它也可以通过下述的方法使用nickname来引用某个之前的`LogFormat`定义的日志格式。
第二种定义`LogFormat`指令的格式中，将一个直接的format和一个nickname联系起来。这样在后续的`LogFormat`或`CustomLog`指令中，就不用一再重复整个冗长的格式串。定义别名的`LogFormat`指令仅仅用来定义一个nickname ，而**不做其它任何事情**：也就是说，它_只是_定义了这个别名，它既没有实际应用这个别名，也不是把它设为默认的格式。因此，它不会影响后续的`TransferLog`指令。另外，`LogFormat`不能用一个别名来定义另一个别名。注意，别名不能包含百分号(`%`)。
### 示例
```
LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
```
## TransferLog 指令
| [说明](#calibre_link-18) | 指定日志文件的位置 |
| --- | --- |
| [语法](#calibre_link-19) | `TransferLog file|pipe` |
| [作用域](#calibre_link-20) | server config, virtual host |
| [状态](#calibre_link-21) | 基本(B) |
| [模块](#calibre_link-22) | mod_log_config |
本指令除不允许直接定义日志格式或根据条件进行日志记录外，与`CustomLog`指令有完全相同的参数和功能。实际应用中，日志的格式是由最近的非别名定义的`LogFormat`指令指定。如果没有定义任何日志格式，则使用通用日志格式。
### 示例
```
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log
```
- Apache HTTP Server Version 2.2 文档 [最后更新：2006年3月21日]
- 版本说明
- 从1.3升级到2.0
- 从2.0升级到2.2
- Apache 2.2 新特性概述
- Apache 2.0 新特性概述
- The Apache License, Version 2.0
- 参考手册
- 编译与安装
- 启动Apache
- 停止和重启
- 配置文件
- 配置段(容器)
- 缓冲指南
- 服务器全局配置
- 日志文件
- 从URL到文件系统的映射
- 安全方面的提示
- 动态共享对象(DSO)支持
- 内容协商
- 自定义错误响应
- 地址和端口的绑定(Binding)
- 多路处理模块
- Apache的环境变量
- Apache处理器的使用
- 过滤器(Filter)
- suEXEC支持
- 性能方面的提示
- URL重写指南
- Apache虚拟主机文档
- 基于主机名的虚拟主机
- 基于IP地址的虚拟主机
- 大批量虚拟主机的动态配置
- 虚拟主机示例
- 深入研究虚拟主机的匹配
- 文件描述符限制
- 关于DNS和Apache
- 常见问题
- 经常问到的问题
- Apache的SSL/TLS加密
- SSL/TLS高强度加密：绪论
- SSL/TLS高强度加密：兼容性
- SSL/TLS高强度加密：如何...?
- SSL/TLS Strong Encryption: FAQ
- 如何.../指南
- 认证、授权、访问控制
- CGI动态页面
- 服务器端包含入门
- .htaccess文件
- 用户网站目录
- 针对特定平台的说明
- 在Microsoft Windows中使用Apache
- 在Microsoft Windows上编译Apache
- Using Apache With Novell NetWare
- Running a High-Performance Web Server on HPUX
- The Apache EBCDIC Port
- 服务器和支持程序
- httpd - Apache超文本传输协议服务器
- ab - Apache HTTP服务器性能测试工具
- apachectl - Apache HTTP服务器控制接口
- apxs - Apache 扩展工具
- configure - 配置源代码树
- dbmmanage - 管理DBM格式的用户认证文件
- htcacheclean - 清理磁盘缓冲区
- htdbm - 操作DBM密码数据库
- htdigest - 管理用于摘要认证的用户文件
- httxt2dbm - 生成RewriteMap指令使用的dbm文件
- htpasswd - 管理用于基本认证的用户文件
- logresolve - 解析Apache日志中的IP地址为主机名
- rotatelogs - 滚动Apache日志的管道日志程序
- suexec - 在执行外部程序之前切换用户
- 其他程序
- 杂项文档
- 与Apache相关的标准
- Apache模块
- 描述模块的术语
- 描述指令的术语
- Apache核心(Core)特性
- Apache MPM 公共指令
- Apache MPM beos
- Apache MPM event
- Apache MPM netware
- Apache MPM os2
- Apache MPM prefork
- Apache MPM winnt
- Apache MPM worker
- Apache模块 mod_actions
- Apache模块 mod_alias
- Apache模块 mod_asis
- Apache模块 mod_auth_basic
- Apache模块 mod_auth_digest
- Apache模块 mod_authn_alias
- Apache模块 mod_authn_anon
- Apache模块 mod_authn_dbd
- Apache模块 mod_authn_dbm
- Apache模块 mod_authn_default
- Apache模块 mod_authn_file
- Apache模块 mod_authnz_ldap
- Apache模块 mod_authz_dbm
- Apache模块 mod_authz_default
- Apache模块 mod_authz_groupfile
- Apache模块 mod_authz_host
- Apache模块 mod_authz_owner
- Apache模块 mod_authz_user
- Apache模块 mod_autoindex
- Apache模块 mod_cache
- Apache模块 mod_cern_meta
- Apache模块 mod_cgi
- Apache模块 mod_cgid
- Apache模块 mod_charset_lite
- Apache模块 mod_dav
- Apache模块 mod_dav_fs
- Apache模块 mod_dav_lock
- Apache模块 mod_dbd
- Apache模块 mod_deflate
- Apache模块 mod_dir
- Apache模块 mod_disk_cache
- Apache模块 mod_dumpio
- Apache模块 mod_echo
- Apache模块 mod_env
- Apache模块 mod_example
- Apache模块 mod_expires
- Apache模块 mod_ext_filter
- Apache模块 mod_file_cache
- Apache模块 mod_filter
- Apache模块 mod_headers
- Apache模块 mod_ident
- Apache模块 mod_imagemap
- Apache模块 mod_include
- Apache模块 mod_info
- Apache模块 mod_isapi
- Apache模块 mod_ldap
- Apache模块 mod_log_config
- Apache模块 mod_log_forensic
- Apache模块 mod_logio
- Apache模块 mod_mem_cache
- Apache模块 mod_mime
- Apache模块 mod_mime_magic
- Apache模块 mod_negotiation
- Apache模块 mod_nw_ssl
- Apache模块 mod_proxy
- Apache模块 mod_proxy_ajp
- Apache模块 mod_proxy_balancer
- Apache模块 mod_proxy_connect
- Apache模块 mod_proxy_ftp
- Apache模块 mod_proxy_http
- Apache模块 mod_rewrite
- Apache模块 mod_setenvif
- Apache模块 mod_so
- Apache模块 mod_speling
- Apache模块 mod_ssl
- Apache模块 mod_status
- Apache模块 mod_suexec
- Apache模块 mod_unique_id
- Apache模块 mod_userdir
- Apache模块 mod_usertrack
- Apache模块 mod_version
- Apache模块 mod_vhost_alias
- Developer Documentation for Apache 2.0
- Apache 1.3 API notes
- Debugging Memory Allocation in APR
- Documenting Apache 2.0
- Apache 2.0 Hook Functions
- Converting Modules from Apache 1.3 to Apache 2.0
- Request Processing in Apache 2.0
- How filters work in Apache 2.0
- Apache 2.0 Thread Safety Issues
- 词汇和索引
- 词汇表
- 指令索引
- 指令速查
- 模块索引
- 站点导航