Apache HTTP Server 版本2.2
Apache HTTP Server 版本2.2
| 說(shuō)明 | 允許記錄日志和定制日志文件格式 |
|---|---|
| 狀態(tài) | 基本(B) |
| 模塊名 | log_config_module |
| 源文件 | mod_log_config.c |
本模塊提供了靈活的方法將客戶請(qǐng)求記錄到日志。日志可以用自定義的格式直接寫(xiě)入文件，或者傳送到一個(gè)外部程序繼續(xù)處理。條件日志功能可以實(shí)現(xiàn)根據(jù)請(qǐng)求的特征來(lái)決定一個(gè)日志信息是否被包含在最終的日志記錄里面。
本模塊提供了三個(gè)指令：TransferLog指令用來(lái)指定日志文件，LogFormat指令用來(lái)定義日志格式，CustomLog指令可以同時(shí)完成指定日志文件和定義日志格式。TransferLog和CustomLog指令在每個(gè)服務(wù)器上都可以被多次使用，以便將同一個(gè)請(qǐng)求記錄到多個(gè)文件中。
LogFormat和CustomLog指令的格式化參數(shù)是一個(gè)字符串。這個(gè)字符串會(huì)在每次請(qǐng)求發(fā)生的時(shí)候，被記錄到日志中去。它可以包含將被原樣寫(xiě)入日志的文本字符串以及C風(fēng)格的控制字符"\n"和"\t"以實(shí)現(xiàn)換行與制表。文本中的引號(hào)和反斜杠應(yīng)通過(guò)"\"來(lái)轉(zhuǎn)義。
請(qǐng)求本身的情況將通過(guò)在格式字符串中放置各種"%"轉(zhuǎn)義符的方法來(lái)記錄，它們?cè)趯?xiě)入日志文件時(shí)，根據(jù)下表的定義進(jìn)行轉(zhuǎn)換：
| 格式字符串 | 描述 | ||||||
|---|---|---|---|---|---|---|---|
%% | 百分號(hào)(Apache2.0.44或更高的版本) | ||||||
%a | 遠(yuǎn)端IP地址 | ||||||
%A | 本機(jī)IP地址 | ||||||
%B | 除HTTP頭以外傳送的字節(jié)數(shù) | ||||||
%b | 以CLF格式顯示的除HTTP頭以外傳送的字節(jié)數(shù)，也就是當(dāng)沒(méi)有字節(jié)傳送時(shí)顯示'-'而不是0。 | ||||||
%{Foobar}C | 在請(qǐng)求中傳送給服務(wù)端的cookieFoobar的內(nèi)容。 | ||||||
%D | 服務(wù)器處理本請(qǐng)求所用時(shí)間，以微為單位。 | ||||||
%{FOOBAR}e | 環(huán)境變量FOOBAR的值 | ||||||
%f | 文件名 | ||||||
%h | 遠(yuǎn)端主機(jī) | ||||||
%H | 請(qǐng)求使用的協(xié)議 | ||||||
%{Foobar}i | 發(fā)送到服務(wù)器的請(qǐng)求頭Foobar:的內(nèi)容。 | ||||||
%l | 遠(yuǎn)端登錄名(由identd而來(lái)，如果支持的話)，除非IdentityCheck設(shè)為"On"，否則將得到一個(gè)"-"。 | ||||||
%m | 請(qǐng)求的方法 | ||||||
%{Foobar}n | 來(lái)自另一個(gè)模塊的注解Foobar的內(nèi)容。 | ||||||
%{Foobar}o | 應(yīng)答頭Foobar:的內(nèi)容。 | ||||||
%p | 服務(wù)器服務(wù)于該請(qǐng)求的標(biāo)準(zhǔn)端口。 | ||||||
%P | 為本請(qǐng)求提供服務(wù)的子進(jìn)程的PID。 | ||||||
%{format}P | 服務(wù)于該請(qǐng)求的PID或TID(線程ID)，format的取值范圍為：pid和tid(2.0.46及以后版本)以及hextid(需要APR1.2.0及以上版本) | ||||||
%q | 查詢(xún)字符串(若存在則由一個(gè)"?"引導(dǎo)，否則返回空串) | ||||||
%r | 請(qǐng)求的第一行 | ||||||
%s | 狀態(tài)。對(duì)于內(nèi)部重定向的請(qǐng)求，這個(gè)狀態(tài)指的是原始請(qǐng)求的狀態(tài)，---%>s則指的是最后請(qǐng)求的狀態(tài)。 | ||||||
%t | 時(shí)間，用普通日志時(shí)間格式(標(biāo)準(zhǔn)英語(yǔ)格式) | ||||||
%{format}t | 時(shí)間，用strftime(3)指定的格式表示的時(shí)間。(默認(rèn)情況下按本地化格式) | ||||||
%T | 處理完請(qǐng)求所花時(shí)間，以秒為單位。 | ||||||
%u | 遠(yuǎn)程用戶名(根據(jù)驗(yàn)證信息而來(lái)；如果返回status(%s)為401，可能是假的) | ||||||
%U | 請(qǐng)求的URL路徑，不包含查詢(xún)字符串。 | ||||||
%v | 對(duì)該請(qǐng)求提供服務(wù)的標(biāo)準(zhǔn)ServerName。 | ||||||
%V | 根據(jù)UseCanonicalName指令設(shè)定的服務(wù)器名稱(chēng)。 | ||||||
%X | 請(qǐng)求完成時(shí)的連接狀態(tài)：
(在1.3以后的版本中，這個(gè)指令是 | ||||||
%I | 接收的字節(jié)數(shù)，包括請(qǐng)求頭的數(shù)據(jù)，并且不能為零。要使用這個(gè)指令你必須啟用mod_logio模塊。 | ||||||
%O | 發(fā)送的字節(jié)數(shù)，包括請(qǐng)求頭的數(shù)據(jù)，并且不能為零。要使用這個(gè)指令你必須啟用mod_logio模塊。 |
可以緊跟在"%"后面加上一個(gè)逗號(hào)分隔的狀態(tài)碼列表來(lái)限制記錄的條目。例如，"%400,501{User-agent}i"只記錄狀態(tài)碼400和501發(fā)生時(shí)的User-agent頭內(nèi)容；不滿足條件時(shí)用"-"代替。狀態(tài)碼前還可以加上"!"前綴表示否定，"%!200,304,302{Referer}i"記錄所有不同于200,304,302的狀態(tài)碼發(fā)生時(shí)的Referer頭內(nèi)容。
"<"和">"修飾符可以用來(lái)指定對(duì)于已被內(nèi)部重定向的請(qǐng)求是選擇原始的請(qǐng)求還是選擇最終的請(qǐng)求。默認(rèn)情況下，%s, %U, %T, %D, %r 使用原始請(qǐng)求，而所有其他格式串則選擇最終請(qǐng)求。例如，%>s 可以用于記錄請(qǐng)求的最終狀態(tài)，而 %<u 則記錄一個(gè)已經(jīng)被內(nèi)部重定向到非認(rèn)證資源的請(qǐng)求的原始認(rèn)證用戶。
出于安全考慮，從2.0.46版本開(kāi)始，%r, %i, %o 中的特殊字符，除了雙引號(hào)(")和反斜線(\)分別用 \" 和 \\ 進(jìn)行轉(zhuǎn)義、空白字符用C風(fēng)格(\n, \t 等)進(jìn)行轉(zhuǎn)義以外，非打印字符和其它特殊字符使用 \xhh 格式進(jìn)行轉(zhuǎn)義(hh是該字符的16進(jìn)制編碼)。在2.0.46以前的版本中，這些內(nèi)容會(huì)被完整的按原樣記錄。這種做法將導(dǎo)致客戶端可以在日志中插入控制字符，所以你在處理這些日志文件的時(shí)候要特別小心。
在2.0版本中(不同于1.3)，%b 和 %B 格式字符串并不表示發(fā)送到客戶端的字節(jié)數(shù)，而只是簡(jiǎn)單的表示HTTP應(yīng)答字節(jié)數(shù)(在連接中斷或使用SSL時(shí)與前者有所不同)。mod_logio提供的 %O 格式字符串將會(huì)記錄發(fā)送的實(shí)際字節(jié)數(shù)。
一些常見(jiàn)的格式串：
"%h %l %u %t \"%r\" %>s %b""%v %h %l %u %t \"%r\" %>s %b""%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"""%{Referer}i -> %U""%{User-agent}i"如果放置日志文件的目錄對(duì)除啟動(dòng)Apache服務(wù)以外的其他用戶可寫(xiě)，可能會(huì)對(duì)系統(tǒng)的安全性造成威脅，具體的討論請(qǐng)參見(jiàn)安全方面的提示。
| 說(shuō)明 | 在將日志寫(xiě)入磁盤(pán)前先在內(nèi)存中進(jìn)行緩沖 |
|---|---|
| 語(yǔ)法 | BufferedLogs On|Off |
| 默認(rèn)值 | BufferedLogs Off |
| 作用域 | server config |
| 狀態(tài) | 基本(B) |
| 模塊 | mod_log_config |
| 兼容性 | 僅在 Apache 2.0.41 及以后的版本中可用 |
BufferedLogs指令使得mod_log_config先在內(nèi)存中緩沖一些日志內(nèi)容，然后一次性寫(xiě)入磁盤(pán)，而不是立即寫(xiě)入。在一些系統(tǒng)上這樣做可以提高磁盤(pán)性能。這個(gè)設(shè)置僅能夠針對(duì)全局進(jìn)行設(shè)置，不能單獨(dú)針對(duì)虛擬主機(jī)進(jìn)行設(shè)置。
| 說(shuō)明 | 設(shè)定針對(duì)cookies的日志文件名 |
|---|---|
| 語(yǔ)法 | CookieLog filename |
| 作用域 | server config, virtual host |
| 狀態(tài) | 基本(B) |
| 模塊 | mod_log_config |
| 兼容性 | 反對(duì)使用該指令 |
CookieLog指令使用cookies作為日志文件名。文件是相對(duì)于ServerRoot目錄的。包含本指令僅僅是為了保持與mod_cookies模塊的兼容，并且反對(duì)使用。
| 說(shuō)明 | 設(shè)定日志的文件名和格式 |
|---|---|
| 語(yǔ)法 | CustomLog file|pipe format|nickname [env=[!]environment-variable] |
| 作用域 | server config, virtual host |
| 狀態(tài) | 基本(B) |
| 模塊 | mod_log_config |
CustomLog指令用來(lái)對(duì)服務(wù)器的請(qǐng)求進(jìn)行日志記錄。可以指定日志的格式，也可以使用環(huán)境變量根據(jù)請(qǐng)求的特征來(lái)自由地組織日志。
第一個(gè)參數(shù)指定了日志記錄的位置，可以使用以下兩種方式來(lái)設(shè)定：
ServerRoot的日志文件名。|"后面緊跟著一個(gè)把日志輸出當(dāng)作標(biāo)準(zhǔn)輸入的處理程序路徑。
如果這里用到了程序，那么這個(gè)程序是以啟動(dòng)httpd的用戶來(lái)執(zhí)行的。因此如果啟動(dòng)httpd的用戶是root ，那這個(gè)程序也將以root身份來(lái)運(yùn)行；你需要確認(rèn)這個(gè)程序是安全的。
當(dāng)在非UNIX平臺(tái)上輸入文件路徑的時(shí)候，要特別注意即使平臺(tái)本身是使用反斜杠(\)來(lái)分隔路徑的，在這里也只能使用正斜杠(/)。通常在配置文件里只用正斜杠(/)來(lái)分隔路徑總是不會(huì)錯(cuò)的。
第二個(gè)參數(shù)指定了寫(xiě)入日志文件的內(nèi)容。它既可以是由前面的LogFormat指令定義的nickname ，也可以是直接按日志格式一節(jié)所描述的規(guī)則定義的format字符串。
例如：以下兩組指令的結(jié)果是完全一樣的：
# 使用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"
第三個(gè)參數(shù)是可選的，它根據(jù)服務(wù)器上特定的環(huán)境變量是否被設(shè)置來(lái)決定是否對(duì)某一特定的請(qǐng)求進(jìn)行日志記錄。如果這個(gè)特定的環(huán)境變量被設(shè)置(或者在"env=!name"的情況下未被設(shè)置)，那么這個(gè)請(qǐng)求將被記錄。
可以使用mod_setenvif和/或mod_rewrite模塊來(lái)為每個(gè)請(qǐng)求設(shè)置環(huán)境變量。例如：如果你想在服務(wù)器上將所有對(duì)GIF圖片的請(qǐng)求記錄在不同于主日志文件的另一個(gè)日志文件中，你可以使用下面的指令：
SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image
或者為了復(fù)制舊有的RefererIgnore指令的行為，你可以使用下面的指令：
SetEnvIf Referer example\.com localreferer
CustomLog referer.log referer env=!localreferer
| 說(shuō)明 | 定義訪問(wèn)日志的記錄格式 |
|---|---|
| 語(yǔ)法 | LogFormat format|nickname [nickname] |
| 默認(rèn)值 | LogFormat "%h %l %u %t \"%r\" %>s %b" |
| 作用域 | server config, virtual host |
| 狀態(tài) | 基本(B) |
| 模塊 | mod_log_config |
本指令定義訪問(wèn)日志的記錄格式。
LogFormat指令可以使用兩種定義格式中的一種。在第一種格式中，指令只帶一個(gè)參數(shù)，以定義后續(xù)的TransferLog指令定義的日志格式。這個(gè)唯一的參數(shù)可以按上述自定義日志格式小節(jié)所描述的format來(lái)定義。另外它也可以通過(guò)下述的方法使用nickname來(lái)引用某個(gè)之前的LogFormat定義的日志格式。
第二種定義LogFormat指令的格式中，將一個(gè)直接的format和一個(gè)nickname聯(lián)系起來(lái)。這樣在后續(xù)的LogFormat或CustomLog指令中，就不用一再重復(fù)整個(gè)冗長(zhǎng)的格式串。定義別名的LogFormat指令僅僅用來(lái)定義一個(gè)nickname ，而不做其它任何事情：也就是說(shuō)，它只是定義了這個(gè)別名，它既沒(méi)有實(shí)際應(yīng)用這個(gè)別名，也不是把它設(shè)為默認(rèn)的格式。因此，它不會(huì)影響后續(xù)的TransferLog指令。另外，LogFormat不能用一個(gè)別名來(lái)定義另一個(gè)別名。注意，別名不能包含百分號(hào)(%)。
LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
| 說(shuō)明 | 指定日志文件的位置 |
|---|---|
| 語(yǔ)法 | TransferLog file|pipe |
| 作用域 | server config, virtual host |
| 狀態(tài) | 基本(B) |
| 模塊 | mod_log_config |
本指令除不允許直接定義日志格式或根據(jù)條件進(jìn)行日志記錄外，與CustomLog指令有完全相同的參數(shù)和功能。實(shí)際應(yīng)用中，日志的格式是由最近的非別名定義的LogFormat指令指定。如果沒(méi)有定義任何日志格式，則使用通用日志格式。
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log