Apache 模組 mod_http2

H2CopyFiles 指令

此指令會影響檔案內容在回應中的處理方式。當設為 off（預設值）時，檔案處理將從請求處理傳遞到主連線，使用一般的 Apache setaside 處理來管理檔案的生命週期。

當設為 on 時，檔案內容將在處理請求時複製，而暫存資料則傳遞至主連線。如果第三方模組將不同生命週期的檔案插入至回應中，這會比較好。

此類模組的範例是 mod_wsgi，它可能會將 Python 檔案處理插入至回應中。當 Python 認為處理已完成時，這些檔案會關閉。這可能會早於 mod_http2 對它們進行操作的時間。

H2Direct 指令

此指令切換 HTTP/2 直接模式的使用。此指令應在 <VirtualHost> 區段中使用，以針對該虛擬主機啟用直接 HTTP/2 通訊。

直接通訊意指如果伺服器在連線上收到的第一個位元組與 HTTP/2 前置序相同，HTTP/2 協定就會立即切換，而不會有進一步的協商。此模式在 RFC 7540 中有定義，適用於明文 (h2c) 的情況。標準並未要求在 TLS 連線上使用此模式。

如果伺服器/虛擬主機未透過 Protocols 啟用 h2 或 h2c，則此連線永遠不會進行 HTTP/2 前置序檢查。H2Direct 在這種情況下無關緊要。這對於使用協定的連線非常重要，而這種協定中的初始讀取可能會無限期地暫停，例如 NNTP。

對於透過帶外方式得知伺服器支援 h2c 的客戶端來說，直接 HTTP/2 能讓客戶端不必執行 HTTP/1.1 升級，因而能提高效能並避免請求主體的升級限制。

當連線可受信任或透過其他方式進行保護時，這也使得直接 h2c 對於伺服器對伺服器的通訊很有吸引力。

H2Direct on

H2EarlyHint 指令

H2EarlyHint 允許在開始處理真正的要求之前加入回應標頭。此類標頭會挑選給「103 早期提示」中間回應。其主要目的是將「預載」資訊傳送給用戶端瀏覽器。

name 和 value 必須是有效的 HTTP 標頭欄位，否則會導致回應失敗。H2EarlyHints 仍必須啟用才能允許傳送 103 個中間回應。此指令可重複多次，且具有相同名稱的標頭欄位會加入。

H2EarlyHint Link "</my.css>;rel=preload;as=style"

H2EarlyHints Directive

此設定控制是否將 HTTP 狀態 103 中間回應轉寄給用戶端。預設情況下，目前並非如此，因為許多用戶端仍會有意外的中間回應問題。

若設定為 on，則利用 H2PushResource 公告的 PUSH 資源會在最後回應之前觸發中間 103 回應。103 回應會載有建議使用此類資源的 預載的 連結標頭。

H2MaxDataFrameLen Directive

H2MaxDataFrameLen 限制放入單一 HTTP/2 DATA 楨中的最大回應本文位元組數量。將其設定為 0 表示沒有限制（但會遵守此協定所允許的最大大小）。

預設情況下，此模組會嘗試使用最大可能大小，大約在 16KB 左右。這樣設定了最大值。當回應資料較少時，就會傳送較小的楨。

H2MaxSessionStreams Directive

此指令設定伺服器允許每個 HTTP/2 資訊階段（例如連線）可有的最大活動串流數。根據 RFC 7540，若串流並非 閒置中 或 已關閉，則表示為活動中。

H2MaxSessionStreams 20

H2MaxWorkerIdleSeconds Directive

此指令設定 h2 工作執行緒可能閒置的最長秒數，直到它自行關閉。這僅在 h2 工作執行緒數超過 H2MinWorkers 時發生。

H2MaxWorkerIdleSeconds 20

H2MaxWorkers Directive

此指令設定每個子程序在 HTTP/2 處理時最多衍生的工作執行緒數目。如果未使用此指令，mod_http2 會選擇一個適合已載入的 mpm 模組的值。

H2MaxWorkers 20

H2MinWorkers 指令

此指令設定每個子程序在 HTTP/2 處理時衍生的最小工作執行緒數目。如果未使用此指令，mod_http2 會選擇一個適合已載入的 mpm 模組的值。

H2MinWorkers 10

H2ModernTLSOnly 指令

此指令切換 TLS 模式 (https:) 中 HTTP/2 連線上的安全性檢查。此檢查可用於伺服器整體或特定 <VirtualHost>。

安全性檢查要求 TSL 協定至少要為 TLSv1.2，且不可使用 RFC 7540 附錄 A 中列出的任何密碼。當新的安全性要求生效後，此檢查將會擴充。

名稱源自 Mozilla 中定義的 安全性/伺服器端 TLS，其中定義了「現代相容性」。Mozilla Firefox 及其他瀏覽器要求 HTTP/2 連線具有現代相容性。如同 OpSec 中的所有內容一樣，這是一個會變動的目標，而且預期未來會繼續演變。

在 mod_http2 中進行這些檢查的目的之一，是要對所有連線執行此安全性等級，而非僅限於瀏覽器發出的連線。另一個目的是讓這些連線無法協商使用 HTTP/2 作為協定，如果需求不符合規定。

TLS 連線安全性最終是由 mod_ssl 的伺服器組態指令來決定。

H2ModernTLSOnly off

H2OutputBuffering 指令

指令 H2OutputBuffering 控制串流輸出的緩衝。預設值為啟用，這也是先前版本中的行為。停用時，所有位元組會立即提供給主連線，以便將它們傳送給客戶端。這解決了與某些種類 gRPC 產生的互通問題。

H2Padding 指令

預設值為 0，任何負載畫面上不新增填充位元組，例如 HEADERS、DATA 和 PUSH_PROMISE。這是先前版本的行為方式。這表示在特定條件下，網路流量觀察者可以看到 TLS 串流中這類畫面的長度。

在設定數位位元組 1-8 時，會將 [0, 2^numbits[ 範圍內的亂數新增到每個畫面上。此亂數值是由模組送回給客戶端的每個畫面獨立選擇。

雖然較多的填充位元組提供較佳的訊息長度混淆效果，但它們也是額外的流量。因此，最佳數目取決於伺服器承載的網路流量類型。

預設值 0（例如，不填充）是用於實現最大的向後相容性。某些部屬中可能會不需要填充位元組或造成危害。最可能的原因是客戶端的實作有缺陷。

H2ProxyRequests 指令

使用 H2ProxyRequests 來在轉送 Proxy 設定中開啟或關閉 HTTP/2 要求的處理。

與 ProxyRequests 類似，這會在轉送 Proxy 中開啟 HTTP/2 時觸發必要的要求處理。應開啟兩個指令。

H2Push 指令

此指令會切換使用 HTTP/2 伺服器推播通訊協定功能。

HTTP/2 通訊協定允許伺服器在客戶端要求特定資源時，將其他資源推播給客戶端。如果這些資源以某種方式連接，且客戶端預計會要求這些資源，這會很有幫助。推播會節省客戶端自行要求這些資源所花費的時間。但另一方面，如果客戶端永遠不需要或已具備這些資源，推播這些資源會浪費頻寬。

伺服器推播是透過檢查回應的 Link 標頭來偵測的（有關規格，請參閱 https://tools.ietf.org/html/rfc5988）。當如此指定的連結具有 rel=preload 屬性時，將視為待推播資源。

回應中的連結標頭是由應用程式設定，或可透過 H2PushResource 設定，或使用 mod_headers 設定，如下所示：

<Location /index.html>
    Header add Link "</css/site.css>;rel=preload"
    Header add Link "</images/logo.jpg>;rel=preload"
</Location>

如同範例所示，可將多個連結標頭新增到回應，這會觸發多個推播。模組中沒有檢查機制來避免重複將同一資源推播給某個客戶端兩次或更多次。請小心使用。

預設啟用 HTTP/2 伺服器推播。於伺服器或虛擬主機上，你可以為與主機的任何連線啟用/停用此功能。此外，你可以在目錄/位置中停用一組資源的 PUSH。此控制機制決定可能會造成 PUSH 的資源，而非可能會透過 PUSH 傳送的資源。

H2Push off

最後但並非最不重要的一點是，推播只會在客戶端表示願意接收推播時才會發生。大多數瀏覽器都會執行此動作，有些瀏覽器（例如 Safari 9）則不會。此外，推播也只會為與原始回應相同的權限的資源執行。

H2PushDiarySize 指令

此指令切換每個 HTTP/2 連線記住的 HTTP/2 伺服器推播最大數量。這可用於 <VirtualHost> 區段內，以影響與該虛擬主機的所有連線數量。

推播日誌會記錄推播資源 (其 URL) 的摘要，以避免在同一連線上重複推播。這些值未持久化，因此開啟新連線的客戶端將會再次遇到已知的推播。

如果已到達最大大小，較新的記錄會取代最舊的記錄。日誌記錄會使用 8 個位元組，讓具有 256 個記錄的預設日誌使用約 2 KB 的記憶體。

大小為 0 會有效停用推播日誌。

H2PushPriority 指令

此指令根據回應的內容類型定義推播回應的優先處理方式。這通常按伺服器設定進行定義，但也可以出現在虛擬主機中。

HTTP/2 伺服器推播通常與客戶端要求相關。每個這樣的請求/回應配對或串流都有依存關係和權重，共同定義串流的優先順序。

當一個串流依存於另一個串流（例如 X 依存於 Y），則 Y 會在 X 取得任何資源之前取得所有頻寬。請注意，這並不意味著 Y 會封鎖 X。如果 Y 沒有資料可傳送，則 Y 分配的所有頻寬都可用於 X。

當一個串流有多個依存項（例如 X1 和 X2 都依存於 Y）時，權重會決定頻寬分配。如果 X1 和 X2 具有相同的權重，則它們都取得可用頻寬的一半。如果 X1 的權重是 X2 的兩倍，則 X1 取得的頻寬是 X2 的兩倍。

最終，每個資料串流都依賴於根部資料串流，該資料串流取得所有可用的頻寬，但卻從不傳輸任何內容。所有可用的頻寬根據其重要性，以加權的方式分配給子串流。這些子串流含有需要傳輸的資料，或會將頻寬分配給各自的子串流，以此類推。如果沒有任何子串流擁有可傳輸的資料，頻寬會根據相同的規則分配至其他地方。

此優先級系統的目的是在允許特定資料串流優先並加權的同時，盡可能利用可用的頻寬。由於通常，所有資料串流均由客戶端開始，因此也是客戶端設定優先順序。

只有當資料串流導致推播時，伺服器才會決定該推播資料串流的初始優先級。以下範例中，X 是客戶端資料串流，它依賴於 Y，而伺服器決定對 X 推播串流 P1 和 P2。

預設優先順序規則為

H2PushPriority * After 16

其讀法為「傳送依賴於客戶端資料串流，權重為 16、內容類型不限的推播串流」。因此，P1 和 P2 會在 X 之後傳送，並且由於它們具有相同的權重，因此會在兩個串流間平均分配頻寬。

H2PushPriority text/css Interleaved 256

其讀法為「傳送與客戶端串流在相同依賴關係和權重下的任何 CSS 資源」。如果 P1 的內容類型為「text/css」，它將依賴於 Y（如同 X），而且其有效權重會根據下列公式計算：P1ew = Xw * (P1w / 256)。由於 P1w 為 256，因此這會讓有效權重與 X 的權重相同。如果 X 和 P1 都有需要傳送的資料，頻寬會平均分配給兩個串流。

如果 Pw 指定為 512，推播交錯串流可獲得 X 兩倍的權重。如果為 128，則僅獲得一半的權重。請注意有效權重始終上限為 256。

H2PushPriority application/json Before

其表示任何內容類型為「application/json」的推播串流都應該在 X 之前傳送。因此，會讓 P1 依賴 Y，而 X 依賴 P1。因此，只要 P1 擁有要傳送的資料，X 就會擱置。有效權重會承襲自客戶端串流。不允許指定權重。

請注意，優先順序規範會受到可用的伺服器資源限制。如果伺服器沒有可供推播資料串流使用的工作者，資料可能永遠都無法抵達，直到其他資料串流已完成傳送。

最後但並非最不重要的一點，此指令使用的語法具有一些特殊性

1. 「*」是唯一匹配所有其他項目的特殊內容類型。「image/*」無法使用。
2. 預設依賴關係為「之後」。
3. 也有預設權重：對於「之後」，權重為 16；對於「交錯」，權重為 256。

H2PushPriority application/json 32         # an After rule
H2PushPriority image/jpeg before           # weight inherited
H2PushPriority text/css   interleaved      # weight 256 default

H2PushResource 指令

加入目錄/位置 HTTP/2 PUSH 會嘗試透過此指令所加入的所有路徑。此指令可以在同一個位置使用多次。

此指令會比透過 mod_headers 加入 Link 標頭早很多來推送資源。mod_http2 會在對客戶端暫時的回應 103 Early Hints 中宣佈這些資源。這表示不支援 PUSH 的客戶端仍會取得早期預載提示。

與透過 mod_headers 設定 Link 回應標頭相反，此指令只會對 HTTP/2 連接生效。

透過將 critical 加到此類資源後，伺服器會優先處理它並在主請求有資料後立刻送出資料。

H2SerializeHeaders 指令

此指令會切換是否以 HTTP/1.1 格式串列化 HTTP/2 請求以便由 httpd 核心處理，或將接收到的二進位資料直接傳入 request_rec。

串列化會降低效能，但若自訂過濾器/hook 需要的話，會提高向後相容性。

H2SerializeHeaders on

H2StreamMaxMemSize 指令

此指令設定在記憶體中暫存一個 active 串流的最大傳輸資料位元組。該記憶體並非專屬於串流。配置會在執行時計入此限制。當到達限制時，串流處理會暫停，只有在緩衝資料已送到客戶端時才會繼續。

H2StreamMaxMemSize 128000

H2StreamTimeout 指令

H2StreamTimeout 指定一個正在處理的串流等待其資料傳送/接收的最大時間。

H2TLSCoolDownSecs 指令

此指令會設定 TLS 連接上閒置時間的秒數，在其 TLS 寫入大小降回到較小（約 1300 位元組）的長度之前。這可使用於伺服器範圍或特定 <VirtualHost>。

有關 TLS 預熱的說明，請參閱 H2TLSWarmUpSize。對於閒置連線，H2TLSCoolDownSecs 反映了連線可能會隨著時間而惡化的情況（以及調整 TCP 流程）。在沒有傳送資料一段時間後，將 TLS 降回到預熱前階段，可改善整體效能。

在將連線視為可靠連線的部署中，可以透過設定此計時器為 0 來停用它。

下列範例將秒數設定為零，有效停用任何降溫。預熱過的 TLS 連線會維持在最大的記錄大小。

H2TLSCoolDownSecs 0

H2TLSWarmUpSize 指令

此指令設定於 https：HTTP/2 連接上執行最大大小寫入（16k）之前，在小型 TLS 記錄（約 1300 位元組）中傳送的位元組數。這可使用於伺服器範圍或特定 <VirtualHost>。

根據 google 效能實驗室 的測量結果顯示，最佳的 TLS 連接效能，發生於初始記錄大小保持在 MTU 等級以下，以允許一個完整的記錄放進一個 IP 封包中。

雖然 TCP 調整其流量控制和視窗大小，但較長的 TLS 記錄可能卡在佇列中或是遺失且需要重新傳輸。這當然對所有封包都適用。不過 TLS 需要整個記錄才能解密它。尾端任何遺失的位元組將導致收到的位元組無法使用。

在成功傳送足夠的位元組數後，連線的 TCP 狀態是穩定的，且最佳的效能可以使用最大的 TLS 記錄大小（16 KB）。

對於只透過區域網路或可靠連線才能抵達伺服器的部署，可以將值減少，並使用 0 完全停用任何預熱階段。

下列範例將大小設定為零，有效停用任何預熱階段。

H2TLSWarmUpSize 0

H2Upgrade 指令

此指令切換 HTTP/1.1 升級方法，以變更為 HTTP/2。這應該在 <VirtualHost> 區段中使用，以啟用對該虛擬主機的 HTTP/2 升級。

此協定變更方法定義於 HTTP/1.1 中，並使用「Upgrade」標頭（因此得其名）來宣告願意使用另一項協定。這可能會發生於 HTTP/1.1 連線的任何要求中。

預設情況下，此協定切換方法已在明文（潛在 h2c）連線中啟用，而在 TLS（潛在 h2）連線中已停用，RFC 7540 如此規定。

請注意，升級只針對不包含本文的請求。POST 和 PUT 連同內容並不會促發升級到 HTTP/2。有關升級的替代方法，請參閱 H2Direct。

此模式僅在透過 Protocols 啟用 h2 或 h2c 時才會產生效果。

H2Upgrade on

H2WebSockets 指令

使用 H2WebSockets 啟用或停用透過 HTTP/2 協定引導 WebSockets 的串接。此協定擴充套件已在 RFC 8441 中定義。

此類請求以 CONNECT 形式出現，並帶有一個額外的「:protocol」標頭。此類請求在模組內轉換為等效的 HTTP/1.1，然後再傳遞至內部處理。

這表示 HTTP/2 WebSockets 可用於帶有「upgrade=websocket」參數的 ProxyPass，而不需要進行額外的變更。

對於在伺服器中直接處理 WebSocket 的（第三方）模組，協定本身的引導也會有效果。然而，在 HTTP/2 中，資料傳輸需要額外的支援。已協定的 WebSocket 將無法使用客戶端連線 socket 來探詢 IO 相關事件。

因為啟用此功能可能會影響此類第三方模組的向後相容性，因此預設情況下不啟用此功能。

H2WindowSize 指令

此指令設定從客戶端到伺服器的流量控制使用的視窗大小，並限制伺服器必須緩衝的資料數量。一旦達到此限制值，客戶端就會停止在串流中傳送資料，直到伺服器宣告有更多可用空間（當其處理部分資料時）。

此限制只影響請求主體，而不影響其標頭等元資料。此外，它對回應主體沒有影響，因為回應主體的視窗大小是由客戶端管理的。

H2WindowSize 128000