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

# Apache模塊 mod_headers | [說明](#calibre_link-11) | 允許通過配置文件控制任意的HTTP請求和應答頭信息 | | --- | --- | | [狀態](#calibre_link-12) | 擴展(E) | | [模塊名](#calibre_link-13) | headers_module | | [源文件](#calibre_link-14) | mod_headers.c | | [兼容性](#calibre_link-58) | `RequestHeader`僅在 Apache 2.0 中有效 | ### 概述這個模塊提供了一些指令用于控制和修改HTTP請求頭和應答頭。這些頭可以被合并、替換、刪除。 ## 處理順序由`mod_headers`提供的指令幾乎可以出現在配置文件的任何部分。并可以封裝在[配置段](#calibre_link-256)中以限制其作用范圍。指令的處理順序很重要，它取決于指令本身在配置文件中的位置和所屬[配置段](#calibre_link-452)在配置文件中的位置。下面的指令如果顛倒一下順序將會導致完全不同的結果： ``` RequestHeader append MirrorID "mirror 12" RequestHeader unset MirrorID ``` 當前順序下，`MirrorID`頭不會被設置。若顛倒一下順序，`MirrorID`頭將被設為"mirror 12"。 ## 前處理和后處理 `mod_headers`可以應用在請求被處理之前或之后。通常的模式是"后處理"，也就是在請求處理完畢之后、發送應答之前設置應答頭。[原文：when Request Headers are set immediately before running the content generator and Response Headers just as the response is sent down the wire.]在實際工作的服務器上應當始終使用"后處理"模式。 "前處理"模式應當僅僅作為開發者使用的一種測試/調試輔助工具。可以在指令中使用`early`關鍵字啟用"前處理"模式，此時將在處理請求之前設置請求頭。這樣就可以模擬各種不同的請求以協助調試。由于"前處理"模式的指令在將URL映射到文件系統之前就生效了，不能依賴于所請求的路徑。所以"前處理"模式的指令只能用在主服務器和虛擬主機部分的配置中，而不能用于`<Directory>`或`<Location>`配置段中。 ## 示例 1. 將所有以"TS"開頭的請求頭復制到應答頭中： ``` Header echo ^TS ``` 2. 在應答中添加一個`MyHeader`頭來包含服務端接受到請求的時間戳和經過多少時間以后才完成對該請求的處理并作出應答。這個頭可以讓客戶端知道瓶頸位于服務端還是位于服務端和客戶端之間的線路。 ``` Header add MyHeader "%D %t" ``` 上面的設置將會添加如下應答頭內容： ``` MyHeader: D=3775428 t=991424704447256 ``` 3. 向Joe問好(Hello)： ``` Header add MyHeader "Hello Joe. It took %D microseconds \ for Apache to serve this request." ``` 上面的設置將會添加如下應答頭內容： ``` MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request. ``` 4. 當且僅當"MyRequestHeader"出現在請求頭中的時候才在應答中發送"`MyHeader`"頭。這個對根據特定的客戶端構造特定的應答頭很有用。注意，下面的例子需要`mod_setenvif`模塊的支持。 ``` SetEnvIf MyRequestHeader value HAVE_MyRequestHeader Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader ``` 如果請求中出現"`MyRequestHeader: value`"頭，應答中將會包含下面的頭： ``` MyHeader: D=3775428 t=991424704447256 mytext ``` ## Header 指令 | [說明](#calibre_link-18) | 配置HTTP應答頭 | | --- | --- | | [語法](#calibre_link-19) | `Header [condition] set|append|add|unset|echo header [value] [early|env=[!]variable]` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 擴展(E) | | [模塊](#calibre_link-22) | mod_headers | 這個指令可以替換、合并、刪除HTTP應答頭。應答頭緊跟在內容處理器和輸出過濾器完工之后生成，這時候才能對頭進行修改。 condition選項可以是`onsuccess`或`always` 。它決定了將對哪個內部頭(internal header)表進行操作。`onsuccess`表示"`2xx`"狀態碼，`always`表示所有狀態碼(包含"`2xx`")。特別地，如果你想撤銷由某個模塊設置的頭，你應當做做試驗，以找到是那個表產生的影響。該指令執行的動作是由第二個參數決定的。這個參數取值范圍如下： `set` 設置新的或修改已經存在的同名應答頭。value可以是一個格式字符串。 `append` 向同名應答頭添加新內容而不修改原來已經存在的舊內容。當向一個已經存在的頭添加新值時，將用逗號與原來已經存在的舊值分開。這是向HTTP頭賦以多個值的標準方法。 `add` 向應答中添加新的頭而不修改原來已經存在的頭(即使同名)。這將可能導致有兩個或更多的應答頭具有相同的名字，從而導致意想不到的后果，所以通常不使用這種方法而用`append`來代替它。 `unset` 去除應答中同名的頭(若存在的話)。如果有多個頭同名，則會被全部去除。value必須被省略。 `echo` 將請求中同名的頭復制到應答中。header可以是一個[正則表達式](#calibre_link-67 "see glossary")。value必須被省略。這個參數后面必須要跟一個header名字(結尾的冒號可要可不要)。`set`, `append`, `add`, `unset`是大小寫無關的。用于`echo`的header是大小寫敏感的，并且可以是一個[正則表達式](#calibre_link-67 "see glossary")。對于`add`, `append`, `set`來說，value是第三個參數。如果value包含空格則必須用雙引號(")括起來。value可以是一個普通字符串或包含格式說明符的字符串，value支持下列格式字符串： | 格式 | 描述 | | --- | --- | | `%%` | 百分號(%) | | `%t` | 接收到請求的微秒時間戳(相對于1970-1-1 00:00:00 UCT)，外加一個"`t=`"前綴。 | | `%D` | 從接收到請求到完成對該請求的處理并作出應答共花費了多少微秒，外加一個"`D=`"前綴。 | | `%{FOOBAR}e` | [環境變量](#calibre_link-232)`FOOBAR`的內容 | | `%{FOOBAR}s` | [SSL環境變量](#calibre_link-486)`FOOBAR`的內容(如果啟用了`mod_ssl`) | ### 注意 "`%s`"格式符僅在Apache 2.1及以后的版本中可用。它可以代替"`%e`"以避免"`SSLOptions +StdEnvVars`"帶來的額外開銷。如果因為別的原因必須開啟"`SSLOptions +StdEnvVars`"，那么"`%e`"將比"`%s`"更加合適。 `Header`后面可以跟一個用于指定生效條件的額外參數(或者用`early`表示"[前處理](#calibre_link-956)")。如果在"`env=...`"參數中指定的[環境變量](#calibre_link-232)存在(或用"`env=!...`"表示不存在)，那么`Header`指令指定的動作將會生效，否則將不會生效。除非使用[early](#calibre_link-956)模式，否則`Header`指令將在應答最后被發送到網絡前處理。這意味著可以設置和改寫絕大多數應答頭，除了自己添加的應答頭。 ## RequestHeader 指令 | [說明](#calibre_link-18) | 配置HTTP請求頭 | | --- | --- | | [語法](#calibre_link-19) | `RequestHeader set|append|add|unset header [value] [early|env=[!]variable]` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 擴展(E) | | [模塊](#calibre_link-22) | mod_headers | | [兼容性](#calibre_link-137) | 僅在 Apache 2.0 中有效 | 這個指令可以替換、合并、刪除HTTP應答頭。請求頭將會在內容處理器運行之前被修改。修改的動作由第一個參數決定，其取值范圍如下： `set` 設置新的或修改已經存在的同名請求頭。 `append` 向同名請求頭添加新內容而不修改原來已經存在的舊內容。當向一個已經存在的頭添加新值時，將用逗號與原來已經存在的舊值分開。這是向HTTP頭賦以多個值的標準方法。 `add` 向請求中添加新的頭而不修改原來已經存在的頭(即使同名)。這將可能導致有兩個或更多的請求頭具有相同的名字，從而導致意想不到的后果，所以通常不使用這種方法而用`append`來代替它。 `unset` 去除請求中同名的頭(若存在的話)。如果有多個頭同名，則會被全部去除。value必須被省略。這些參數后面必須要跟一個header名(結尾的冒號可要可不要，且大小寫無關)。對于`add`, `append`, `set`來說，value是第三個參數。如果value包含空格則必須用雙引號(")括起來。對于`unset`來說則不需要value參數。value可以是一個普通字符串或包含格式說明符的字符串，格式字符串的用法與`Header`指令一樣。 `RequestHeader`后面可以跟一個用于指定生效條件的額外參數(或者用`early`表示"[前處理](#calibre_link-956)")。如果在"`env=...`"參數中指定的[環境變量](#calibre_link-232)存在(或用"`env=!...`"表示不存在)，那么`RequestHeader`指令指定的動作將會生效，否則將不會生效。除非使用[early](#calibre_link-956)模式，否則`RequestHeader`將在請求被處理之前生效。這樣，由瀏覽器和Apache輸入過濾器產生的請求頭都可以被該指令處理。