Apache模塊 mod_log_config · Apache 2.2 中文官方文檔

# 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 ```