容器提供的濾網

目錄

簡介

Tomcat 提供多個濾網，可使用 $CATALINA_BASE/conf/web.xml 為所有 Web 應用程式組態，或透過在應用程式的 WEB-INF/web.xml 中組態，為個別 Web 應用程式組態。下列說明每個濾網。

此說明使用變數名稱 $CATALINA_BASE 來指涉大多數相對路徑所解析的基礎目錄。如果您未透過設定 CATALINA_BASE 目錄為 Tomcat 組態多個執行個體，則 $CATALINA_BASE 會設定為 $CATALINA_HOME 的值，亦即您安裝 Tomcat 的目錄。

新增預設字元集濾網

簡介

HTTP 規範明確指出，如果未針對「文字」媒體類型的媒體子類型指定字元集，則必須使用 ISO-8859-1 字元集。不過，瀏覽器可能會嘗試自動偵測字元集。攻擊者可能會利用此漏洞來執行 XSS 攻擊。Internet Explorer 和其他瀏覽器都有選項可以啟用此行為。

此篩選器會透過明確設定字元集來防止攻擊。除非使用者明確覆寫所提供的字元集，否則瀏覽器會遵守明確設定的字元集，進而防止 XSS 攻擊。

濾網類別名稱

新增預設字元集篩選器的篩選器類別名稱為 org.apache.catalina.filters.AddDefaultCharsetFilter 。

初始化參數

新增預設字元集篩選器支援下列初始化參數

屬性 說明
編碼

如果 Servlet 未明確設定其他字元集，則應設定的字元集名稱。此參數有兩個特殊值，預設值和 系統。系統值會使用 JVM 廣泛的預設字元集，通常會由語言環境設定。預設值會使用 ISO-8859-1。

CORS 濾網

簡介

此篩選器是 W3C 的 CORS (跨來源資源共用) 規範 實作，此規範是一種啟用跨來源要求的機制。

此篩選器會將必要的 Access-Control-* 標頭新增到 HttpServletResponse 物件來運作。此篩選器也會防止 HTTP 回應分割。如果要求無效或不被允許，則會以 HTTP 狀態碼 403 (禁止) 拒絕要求。可取得 流程圖，說明此篩選器如何處理要求。

使用此篩選器所需的最小組態為

<filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

上述組態會啟用篩選器，但不會放寬跨來源原則。至少需要新增一個 cors.allowed.origins 初始化參數，如下所述，才能啟用跨來源要求。您可能需要提供其他組態，具體取決於您的需求。

此篩選器的執行個體只能實作一個原則。如果您想將不同的原則 (例如不同的允許來源) 套用至網路應用程式中的不同 URL 或 URL 組，則需要為您想組態的每個原則組態此篩選器的個別執行個體。

濾網類別名稱

CORS 篩選器的篩選器類別名稱為 org.apache.catalina.filters.CorsFilter。

初始化參數

CORS 篩選器支援下列初始化參數

屬性 說明
cors.allowed.origins

允許存取資源的 來源 清單。可以指定 * 來啟用從任何來源存取資源。否則，可以提供逗號分隔的允許來源清單。例如： https://www.w3.org, https://www.apache.org。預設值：空字串。(沒有來源可以存取資源)。

cors.allowed.methods

使用跨來源要求存取資源時，可使用 HTTP 方法的逗號分隔清單。這些方法也會包含在預先飛行回應中的 Access-Control-Allow-Methods 標頭中。例如：GET, POST。預設值：GET, POST, HEAD, OPTIONS

cors.allowed.headers

進行實際要求時，可使用要求標頭的逗號分隔清單。這些標頭也會在預先飛行回應中，包含在 Access-Control-Allow-Headers 標頭中。例如：Origin,Accept。預設值：Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers

cors.exposed.headers

瀏覽器允許存取的標頭，除了簡單回應標頭之外的逗號分隔清單。這些標頭也會包含在預先飛行回應中的 Access-Control-Expose-Headers 標頭中。例如：X-CUSTOM-HEADER-PING,X-CUSTOM-HEADER-PONG。預設值：無。非簡單標頭預設不會公開。

cors.preflight.maxage

瀏覽器允許快取預先飛行要求結果的秒數。這會包含在預先飛行回應中的 Access-Control-Max-Age 標頭中。負值會防止 CORS Filter 將此回應標頭新增到預先飛行回應。預設值：1800

cors.support.credentials

標記，表示資源是否支援使用者憑證。此標記會在預先飛行回應中，包含在 Access-Control-Allow-Credentials 標頭中。它有助於瀏覽器判斷是否可以使用憑證進行實際要求。預設值：false

cors.request.decorate

控制是否應將 CORS 特定屬性新增到 HttpServletRequest 物件的標記。預設值：true

以下是進階組態範例，用來覆寫預設值

<filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
  <init-param>
    <param-name>cors.allowed.origins</param-name>
    <param-value>https://www.apache.org</param-value>
  </init-param>
  <init-param>
    <param-name>cors.allowed.methods</param-name>
    <param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
  </init-param>
  <init-param>
    <param-name>cors.allowed.headers</param-name>
    <param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value>
  </init-param>
  <init-param>
    <param-name>cors.exposed.headers</param-name>
    <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
  </init-param>
  <init-param>
    <param-name>cors.support.credentials</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>cors.preflight.maxage</param-name>
    <param-value>10</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

CORS 濾網和 HttpServletRequest 屬性

CORS Filter 會將有關要求的資訊新增到 HttpServletRequest 物件中，供下游使用。如果 cors.request.decorate 初始化參數為 true，則會設定下列屬性

  • cors.isCorsRequest: 標記，用來判斷要求是否為 CORS 要求。
  • cors.request.origin: 起始 URL，也就是要求來源頁面的 URL。
  • cors.request.type: CORS 要求類型。可能值
    • SIMPLE：未經預先飛行要求的請求。
    • ACTUAL：經過預先飛行要求的請求。
    • PRE_FLIGHT：預先飛行要求。
    • NOT_CORS：正常的同源請求。
    • INVALID_CORS：跨來源請求，無效。
  • cors.request.headers：請求標頭，作為預檢請求的 Access-Control-Request-Headers 標頭傳送。

CSRF 預防濾網

簡介

此過濾器為 Web 應用程式提供基本的 CSRF 保護。此過濾器假設它已對應到 /*，且傳回給用戶端的所有 URL 都透過呼叫 HttpServletResponse#encodeRedirectURL(String) 或 HttpServletResponse#encodeURL(String) 編碼。

此過濾器透過產生隨機數並將其儲存在工作階段中，來防止 CSRF。URL 也會使用相同的隨機數編碼。當收到下一個請求時，會將請求中的隨機數與工作階段中的隨機數進行比較，只有當它們相同時，才會允許請求繼續。

濾網類別名稱

CSRF 防護過濾器的過濾器類別名稱為 org.apache.catalina.filters.CsrfPreventionFilter 。

初始化參數

CSRF 防護過濾器支援下列初始化參數

屬性 說明
denyStatus

拒絕拒絕的請求時使用的 HTTP 回應狀態碼。預設值為 403。

enforce

啟用或停用強制執行的旗標。當強制執行已停用時，CsrfPreventionFilter 將允許所有請求，並將 CSRF 失敗記錄為 DEBUG 訊息。預設為 true，啟用 CSRF 保護的強制執行。

entryPoints

逗號分隔的 URL 清單，不會測試這些 URL 是否有有效的隨機數。它們用於提供一種方法，讓使用者在離開受保護的應用程式後，可以導覽回該應用程式。進入點將限制為 HTTP GET 請求，且不應觸發任何與安全性相關的動作。

nonceCacheSize

先前發出的隨機數數量，會以 LRU 為基礎快取在快取中，以支援平行請求、有限度地使用瀏覽器的重新整理和返回，以及其他可能導致提交先前隨機數（而非目前的隨機數）的類似行為。如果未設定，將使用預設值 5。

nonceRequestParameterName

用於隨機數的請求參數名稱。如果未設定，將使用預設值 org.apache.catalina.filters.CSRF_NONCE。

randomClass

用於產生隨機數的類別名稱。此類別必須是 java.util.Random 的實例。如果未設定，將使用 java.security.SecureRandom 的預設值。

noNonceURLPatterns

不會加入 CSRF 隨機數的 URL 模式清單。您可能不希望在某些 URL 中加入隨機數，以避免建立可能會破壞資源快取等功能的唯一 URL。

支援下列幾種類型的模式

  • 使用以 * 結尾的模式進行字首比對。例如，/images/*。
  • 使用以 * 開頭的模式進行字尾比對。例如，*.css。
  • 以 mime: 開頭的 MIME 類型比對，並指定上述比對之一，此比對將與 URL 檔案名稱的 MIME 類型進行比對。例如，mime:image/*。請注意，MIME 類型將使用 ServletContext.getMimeType 進行判斷。
  • 以 / (斜線 / 實心斜線) 符號開頭和結尾的單一完整正規表示式模式。例如 //images/.*|/scripts/.*/。編譯之前，會從模式中移除開頭和結尾的 / 字元。請注意，只能有一個模式，但該模式當然可以使用正規表示式 | (OR) 運算子，擁有任意數量的替代選項。正規表示式將與整個 URL 進行比對（亦即 match 語意，而非 find 語意），而正規表示式方言為 Java (java.util.regex.Pattern)。

預設為 *.css, *.js, *.gif, *.png, *.jpg, *.svg, *.ico, *.jpeg, *.mjs。

REST API 的 CSRF 預防濾網

簡介

此過濾器為 REST API 提供基本的 CSRF 保護。CSRF 保護僅套用在對受保護資源進行修改的 HTTP 要求（不同於 GET、HEAD、OPTIONS）。它是根據提供有效隨機數的客製化標頭 X-CSRF-Token 為基礎。

REST API 的 CSRF 保護機制包含下列步驟

  • 用戶端要求取得有效的隨機數。這會透過對受保護資源執行非修改的「擷取」要求來進行。
  • 伺服器回應一個對應至目前使用者階段的有效隨機數。
  • 用戶端在同一使用者階段的後續修改要求中提供此隨機數。
  • 伺服器拒絕所有不包含有效隨機數對受保護資源的修改要求。

基本組態範例

在伺服器端

  • 所有 CSRF 保護的 REST API 應使用驗證機制保護。
  • 使用此篩選器保護修改 REST API。
  • 提供至少一個非修改操作。
<filter>
  <filter-name>RestCSRF</filter-name>
  <filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>RestCSRF</filter-name>
  <!-- Modifying operations -->
  <url-pattern>/resources/removeResource</url-pattern>
  <url-pattern>/resources/addResource</url-pattern>
  <!-- Non-modifying operations -->
  <url-pattern>/resources/listResources</url-pattern>
</filter-mapping>

在用戶端

  • 執行非修改「擷取」要求以取得有效的隨機數。這可透過傳送額外的標頭 X-CSRF-Token: Fetch 來完成
  • 快取傳回的階段 ID 和隨機數，以便在後續修改受保護資源的要求中提供它們。
  • 修改要求可能會被拒絕，而標頭 X-CSRF-Token: Required 會在隨機數無效或遺失、階段逾期或伺服器變更階段 ID 的情況下傳回。
Client Request:
GET /rest/resources/listResources HTTP/1.1
X-CSRF-Token: Fetch
Authorization: Basic ...
Host: localhost:8080
...

Server Response:
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=...; Path=/rest; HttpOnly
X-CSRF-Token: ...
...

Client Request:
POST /rest/resources/addResource HTTP/1.1
Cookie: JSESSIONID=...
X-CSRF-Token: ...
Authorization: Basic ...
Host: localhost:8080
...

Server Response:
HTTP/1.1 200 OK
...

RestCsrfPreventionFilter 和 HttpServletRequest 參數

當用戶端無法在其對 REST API 的呼叫中插入自訂標頭時，還有額外的功能來設定 URL，其中有效的隨機數將被接受為要求參數。

注意：如果有一個 X-CSRF-Token 標頭，它將優先於要求中具有相同名稱的任何參數。要求參數無法用於擷取新的隨機數，只有標頭可用於要求新的隨機數。

<filter>
  <filter-name>RestCSRF</filter-name>
  <filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
  <init-param>
    <param-name>pathsAcceptingParams</param-name>
    <param-value>/resources/removeResource,/resources/addResource</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>RestCSRF</filter-name>
  <url-pattern>/resources/*</url-pattern>
</filter-mapping>

濾網類別名稱

REST API 的 CSRF 預防篩選器的篩選器類別名稱為 org.apache.catalina.filters.RestCsrfPreventionFilter 。

初始化參數

REST API 的 CSRF 預防篩選器支援下列初始化參數

屬性 說明
denyStatus

拒絕拒絕的請求時使用的 HTTP 回應狀態碼。預設值為 403。

pathsAcceptingParams

可透過要求參數 X-CSRF-Token 接受隨機數的 URL 清單，以逗號分隔。對於無法透過標頭提供隨機數資訊的用例，可以透過要求參數提供。如果有一個 X-CSRF-Token 標頭，它將優先於要求中具有相同名稱的任何參數。要求參數無法用於擷取新的隨機數，只有標頭可用於要求新的隨機數。

randomClass

用於產生隨機數的類別名稱。此類別必須是 java.util.Random 的實例。如果未設定，將使用 java.security.SecureRandom 的預設值。

Expires 濾網

簡介

ExpiresFilter 是 Apache mod_expires 的 Java Servlet API 埠。此篩選器控制伺服器回應中 Expires HTTP 標頭和 Cache-Control HTTP 標頭的 max-age 指令的設定。到期日期可以設定為相對於原始檔案上次修改的時間，或相對於用戶端存取的時間。

這些 HTTP 標頭是關於文件有效性和持續性的用戶端說明。如果快取，文件可以從快取中擷取，而不是從來源擷取，直到這段時間過後。之後，快取副本會被視為「過期」且無效，必須從來源取得新的副本。

若要修改 max-age 以外的 Cache-Control 指令（請參閱 RFC 2616 第 14.9 節），您可以使用其他 servlet 篩選器或 Apache Httpd mod_headers 模組。

基本組態範例

將「Expires」和「Cache-Control: max-age=」標頭新增至影像、CSS 和 JavaScript 的基本設定。 

<filter>
 <filter-name>ExpiresFilter</filter-name>
 <filter-class>org.apache.catalina.filters.ExpiresFilter</filter-class>
 <init-param>
    <param-name>ExpiresByType image</param-name>
    <param-value>access plus 10 minutes</param-value>
 </init-param>
 <init-param>
    <param-name>ExpiresByType text/css</param-name>
    <param-value>access plus 10 minutes</param-value>
 </init-param>
 <init-param>
    <param-name>ExpiresByType text/javascript</param-name>
    <param-value>access plus 10 minutes</param-value>
 </init-param>
</filter>
...
<filter-mapping>
 <filter-name>ExpiresFilter</filter-name>
 <url-pattern>/*</url-pattern>
 <dispatcher>REQUEST</dispatcher>
</filter-mapping>

替代語法

ExpiresDefault 和 ExpiresByType 指令也可以定義為更易於閱讀的語法形式 

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value><base> [plus] {<num> <type>}*</param-value>
</init-param>

<init-param>
 <param-name>ExpiresByType type</param-name>
 <param-value><base> [plus] {<num> <type>}*</param-value>
</init-param>

<init-param>
 <param-name>ExpiresByType type;encoding</param-name>
 <param-value><base> [plus] {<num> <type>}*</param-value>
</init-param>

其中 <base> 是下列其中之一

  • access
  • now（等於「access」）
  • modification

plus 關鍵字為選用。<num> 應為整數值（Integer.parseInt() 可接受），而 <type> 是下列其中之一

  • year、years
  • month、months
  • week、weeks
  • day、days
  • hour、hours
  • minute、minutes
  • second、seconds

例如，下列任何指令都可以用於讓文件在被存取後 1 個月過期，預設 

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value>access plus 1 month</param-value>
</init-param>

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value>access plus 4 weeks</param-value>
</init-param>

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value>access plus 30 days</param-value>
</init-param>

可以透過新增多個「<num> <type>」子句微調過期時間 

<init-param>
 <param-name>ExpiresByType text/html</param-name>
 <param-value>access plus 1 month 15 days 2 hours</param-value>
</init-param>

<init-param>
 <param-name>ExpiresByType image/gif</param-name>
 <param-value>modification plus 5 hours 3 minutes</param-value>
</init-param>

請注意，如果您使用基於修改日期的設定，則不會將 Expires 標頭新增至並非來自磁碟上檔案的內容。這是因為此類內容沒有修改時間。

過期標頭產生資格

如果符合下列條件，則回應符合 ExpiresFilter 豐富的資格

  1. 未定義過期標頭（Expires 標頭或 Cache-Control 標頭的 max-age 指令），
  2. 指令 ExpiresExcludedResponseStatusCodes 未排除回應狀態碼，
  3. 回應的 Content-Type 符合 ExpiresByType 指令中定義的其中一種類型，或已定義 ExpiresDefault 指令。

注意：如果 Cache-Control 標頭包含除 max-age 以外的其他指令，則會將這些指令與 ExpiresFilter 新增的 max-age 指令串接在一起。

過期組態選取

根據下列演算法選取過期設定

  1. ExpiresByType 符合 HttpServletResponse.getContentType() 傳回的確切內容類型，可能包含字元集（例如「text/xml;charset=UTF-8」），
  2. ExpiresByType 符合內容類型，不含字元集，如果 HttpServletResponse.getContentType() 包含字元集（例如 'text/xml;charset=UTF-8' -> 'text/xml'），
  3. ExpiresByType 符合主要類型（例如 HttpServletResponse.getContentType() 的 '/' 之前的子字串）（例如 'text/xml;charset=UTF-8' -> 'text'），
  4. ExpiresDefault

濾網類別名稱

Expires Filter 的篩選器類別名稱為 org.apache.catalina.filters.ExpiresFilter 。

初始化參數

Expires Filter 支援下列初始化參數

屬性 說明
ExpiresExcludedResponseStatusCodes

此指令定義 ExpiresFilter 將不會產生到期標頭的 HTTP 回應狀態碼。預設情況下，會略過 304 狀態碼（「未修改」）。此值為 HTTP 狀態碼的逗號分隔清單。

此指令有助於簡化 ExpiresDefault 指令的使用。的確，304 未修改（指定 Content-Type 標頭）與 Expires 和 Cache-Control:max-age= 標頭結合的行為可能難以理解。

請參閱表格下方的範例

ExpiresByType <content-type>

此指令定義指定類型（例如 text/html）的文件所產生的 Expires 標頭和 Cache-Control 標頭的 max-age 指令的值。第二個參數設定會新增到基本時間的秒數，以建構到期日期。Cache-Control: max-age 是透過從到期日期減去請求時間，並將結果表示為秒數來計算。

基本時間可能是檔案的最後修改時間，或客戶端存取文件的時間。應使用哪個時間由 <code> 欄位指定；M 表示應使用檔案的最後修改時間作為基本時間，而 A 表示應使用客戶端的存取時間。持續時間以秒表示。A2592000 代表交替語法中的 存取加 30 天。

效果的差異很細微。如果使用 M（交替語法中的 修改），所有快取中文件的當前副本將在同一時間到期，這對於總是可以在相同 URL 找到的每週公告之類的東西來說可能很好。如果使用 A（交替語法中的 存取 或 現在），每個客戶端的到期日期都不同；這對於不太常變更的影像檔案來說可能很好，特別是對於所有參考相同影像的一組相關文件（也就是說，影像會在相對短的時間內重複存取）。

注意：當內容類型包含字元集（例如 'ExpiresByType text/xml;charset=utf-8'）時，Tomcat 會移除 ';' 和 'charset' 關鍵字之間的空白字元。因此，包含字元集的到期設定不得包含此類空格字元。

請參閱表格下方的範例

它僅會針對指定的 MIME 類型，覆寫由 ExpiresDefault 指令設定的任何到期日期。

您也可以使用本文件中先前說明的替代語法，來指定到期時間計算。

ExpiresDefault

此指令會設定受影響範圍中所有文件的到期時間計算預設演算法。它可以透過 ExpiresByType 指令，逐一類型覆寫。有關引數語法的詳細資料，請參閱該指令的說明，以及「替代語法」說明。

範例：排除回應狀態碼 302、500 和 503

<init-param>
 <param-name>ExpiresExcludedResponseStatusCodes</param-name>
 <param-value>302, 500, 503</param-value>
</init-param>

ExpiresByType 初始化參數範例

<init-param>
   <param-name>ExpiresByType text/html</param-name>
   <param-value>access plus 1 month 15   days 2 hours</param-value>
</init-param>

<init-param>
   <!-- 2592000 seconds = 30 days -->
   <param-name>ExpiresByType image/gif</param-name>
   <param-value>A2592000</param-value>
</init-param>

疑難排解

若要進行疑難排解，請在 org.apache.catalina.filters.ExpiresFilter 上啟用記錄。

logging.properties 摘錄 

org.apache.catalina.filters.ExpiresFilter.level = FINE

初始化記錄訊息範例 

Mar 26, 2010 2:01:41 PM org.apache.catalina.filters.ExpiresFilter init
FINE: Filter initialized with configuration ExpiresFilter[
 excludedResponseStatusCode=[304],
 default=null,
 byType={
    image=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
    text/css=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
    text/javascript=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]]}]

ExpiresFilter 新增到期日期的每個要求記錄訊息範例如下。訊息在同一行，在此處換行以增加可讀性。 

Mar 26, 2010 2:09:47 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
FINE: Request "/tomcat.gif" with response status "200"
 content-type "image/gif", set expiration date 3/26/10 2:19 PM

ExpiresFilter 未新增到期日期的每個要求記錄訊息範例 

Mar 26, 2010 2:10:27 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
FINE: Request "/docs/config/manager.html" with response status "200"
 content-type "text/html", no expiration configured

失敗請求濾網

簡介

此篩選器會在要求中觸發參數剖析，如果在參數剖析期間，因為剖析錯誤或要求大小限制（例如 Connector 中的 maxParameterCount 屬性）而略過某些參數，則會拒絕該要求。此篩選器可用於確保用戶端提交的參數值不會遺失。

請注意，參數剖析可能會使用 HTTP 要求的主體，因此如果由這個篩選器保護的 servlet 使用 request.getInputStream() 或 request.getReader() 呼叫，則需要小心。一般來說，新增此篩選器而中斷 Web 應用程式的風險並不高，因為參數剖析會在使用要求主體之前，檢查要求的內容類型。

請注意，為了正確剖析 POST 要求，必須在這個篩選器上方設定 SetCharacterEncodingFilter 篩選器。有關詳細資料，請參閱常見問題集中的字元編碼頁面。

要求會以 HTTP 狀態碼 400（錯誤的要求）遭到拒絕。

濾網類別名稱

失敗要求篩選器的篩選器類別名稱是 org.apache.catalina.filters.FailedRequestFilter 。

初始化參數

失敗要求篩選器不支援任何初始化參數。

HTTP 標頭安全性濾網

簡介

有許多 HTTP 標頭可以新增到回應中，以改善連線安全性。此篩選器提供一種機制，可以新增這些標頭。請注意，具有更複雜需求的安全相關標頭（例如 CORS）實作為個別的篩選器。

濾網類別名稱

HTTP 標頭安全性篩選器的篩選器類別名稱是 org.apache.catalina.filters.HttpHeaderSecurityFilter 。

初始化參數

HTTP 標頭安全性篩選器支援下列初始化參數

屬性 說明
hstsEnabled

是否在安全要求的回應中設定 HTTP 嚴格傳輸安全 (HSTS) 標頭 (Strict-Transport-Security)。任何已存在的 HSTS 標頭都將被取代。請參閱 RFC 6797 以進一步了解 HSTS 的詳細資訊。若未指定，將使用預設值 true。

hstsMaxAgeSeconds

應在 HSTS 標頭中使用的最大年齡值。負值將視為零。若未指定，將使用預設值 0。

hstsIncludeSubDomains

是否應在 HSTS 標頭中包含 includeSubDomains 參數。若未指定，將使用預設值 false。

hstsPreload

是否應在 HSTS 標頭中包含 preload 參數。若未指定，將使用預設值 false。請參閱 https://hstspreload.org 以取得此參數的重要資訊。

antiClickJackingEnabled

是否應在回應中設定防點擊劫持標頭 (X-Frame-Options)。任何已存在的防點擊劫持標頭都將被取代。若未指定，將使用預設值 true。

antiClickJackingOption

應為防點擊劫持標頭使用什麼值？必須為 DENY、SAMEORIGIN、ALLOW-FROM （不區分大小寫）之一。若未指定，將使用預設值 DENY。

antiClickJackingUri

如果將 ALLOW-FROM 用於 antiClickJackingOption，應允許什麼 URI？若未指定，將使用預設值為空字串。

blockContentTypeSniffingEnabled

是否應在每個回應中設定阻擋內容類型偵測的標頭 (X-Content-Type-Options)。如果已存在，標頭將被取代。若未指定，將使用預設值 true。

xssProtectionEnabled

注意：此設定已過時，因為所有主要瀏覽器都已移除對 HTTP 標頭的支援。此設定已從 Tomcat 11.0.x 起移除。

是否應在每個回應中設定啟用瀏覽器跨網站指令碼過濾保護的標頭 (X-XSS-Protection: 1; mode=block)。如果已存在，標頭將被取代。若未指定，將使用預設值 false。

速率限制濾網

簡介

速率限制篩選器可協助減輕阻斷服務 (DoS) 和暴力攻擊，方法是在時間範圍（也稱為時間區段）內限制單一 IP 位址允許的請求數量，例如每 60 秒 300 個請求。

此過濾器透過在時間區段中為每個 IP 位址遞增計數器來運作，如果計數器超過允許的限制，則會以「429 要求過多」回應來捨棄來自該 IP 的後續要求，直到區段時間結束且新的區段開始。

此過濾器經過最佳化，以提高效率並降低負擔，因此它會將一些設定值轉換為更有效率的值。例如，設定 60 秒時間區段的組態會轉換為 65.536 秒。這允許使用位元移位算術來進行非常快速的區段計算。為了保持對使用者意圖的忠實，設定的要求數目會乘以相同的比率，因此每 60 秒 100 個要求的組態，其實際值為每 65 秒 109 個要求。

針對不同的 URI 設定不同的限制很常見。例如，登入頁面或驗證指令碼通常預期會比應用程式的其他部分收到更少的請求，因此您可以新增一個過濾器定義，只允許每 15 秒 5 個請求，並將這些 URI 對應到它。

您可以將 enforce 設定為 false，以停用終止超過允許限制的請求。然後，您的應用程式程式碼可以檢查請求屬性 org.apache.catalina.filters.RateLimitFilter.Count，並根據它所擁有的其他資訊來決定如何處理請求，例如根據角色等允許特定使用者提出更多請求。

警告：如果 Tomcat 位於反向代理程式之後，則您必須確保速率限制過濾器會看到用戶端 IP 位址，因此，例如如果您正在使用 遠端 IP 過濾器，則速率限制過濾器的過濾器對應必須在遠端 IP 過濾器的對應之後，以確保在套用速率限制過濾器之前，每個請求的 IP 位址都已解析。否則，將會在同一個區段中計算來自不同 IP 的請求，並導致自我發動的 DoS 攻擊。

濾網類別名稱

遠端位址過濾器的過濾器類別名稱為 org.apache.catalina.filters.RateLimitFilter 。

初始化參數

速率限制過濾器支援下列初始化參數

屬性 說明
bucketDuration

時間區段中的秒數。預設為 60。

bucketRequests

時間區段中允許的請求數目。預設為 300。

enforce

設定為 false 以允許請求通過，即使它們超過每個時間視窗允許的最大值。您的應用程式程式碼仍然可以檢查請求屬性 org.apache.catalina.filters.RateLimitFilter.Count，以擷取在時間視窗內從該 IP 提出請求的數目。預設為 true。

statusCode

當請求被中斷時要傳回的狀態碼。預設值為 429。

statusMessage

當請求被中斷時要傳回的狀態訊息。預設值為「太多請求」。

範例

將網站速率限制設為每分鐘 300 個請求（預設值）

    <filter>
        <filter-name>RateLimitFilter Global</filter-name>
        <filter-class>org.apache.catalina.filters.RateLimitFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>RateLimitFilter Global</filter-name>
        <url-pattern>*</url-pattern>
    </filter-mapping>

將 /auth/* 腳本速率限制設為每分鐘 20 個請求

    <filter>
        <filter-name>RateLimitFilter Login</filter-name>
        <filter-class>org.apache.catalina.filters.RateLimitFilter</filter-class>
        <init-param>
            <param-name>bucketRequests</param-name>
            <param-value>20</param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>RateLimitFilter Login</filter-name>
        <url-pattern>/auth/*</url-pattern>
    </filter-mapping>

遠端位址濾網

簡介

遠端位址篩選器可讓您將提交此請求的用戶端 IP 位址與一個或多個正規表示式進行比較，並允許請求繼續或拒絕處理來自此用戶端的請求。

正規表示式的語法不同於「標準」萬用字元比對。Tomcat 使用 java.util.regex 套件。有關支援表示式的詳細資料，請參閱 Java 文件。

注意：在將此篩選器與 IPv6 位址搭配使用時，有一個注意事項。此閥處理的 IP 位址格式取決於用於取得 IP 位址的 API。如果位址是使用 Inet6Address 類別從 Java Socket 取得，其格式將為 x:x:x:x:x:x:x:x。也就是說，本機主機的 IP 位址將為 0:0:0:0:0:0:0:1，而不是更廣泛使用的 ::1。請參閱您的存取記錄以取得實際值。

另請參閱：遠端主機篩選器。

濾網類別名稱

遠端位址篩選器的篩選器類別名稱為 org.apache.catalina.filters.RemoteAddrFilter 。

初始化參數

遠端位址篩選器支援下列初始化參數

屬性 說明
allow

遠端用戶端 IP 位址與之進行比較的正規表示式（使用 java.util.regex）。如果指定此屬性，則遠端位址必須符合此正規表示式，才能接受此請求。如果未指定此屬性，則將接受所有請求，除非遠端位址符合 deny 模式。

deny

遠端用戶端 IP 位址與之進行比較的正規表示式（使用 java.util.regex）。如果指定此屬性，則遠端位址不能符合此正規表示式，才能接受此請求。如果未指定此屬性，則請求接受僅受 accept 屬性控管。

denyStatus

拒絕拒絕的請求時使用的 HTTP 回應狀態碼。預設值為 403。例如，可以將其設為 404。

範例

僅允許來自本機主機連線的用戶端存取

    <filter>
      <filter-name>Remote Address Filter</filter-name>
      <filter-class>org.apache.catalina.filters.RemoteAddrFilter</filter-class>
      <init-param>
        <param-name>allow</param-name>
        <param-value>127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1</param-value>
      </init-param>
    </filter>
    <filter-mapping>
      <filter-name>Remote Address Filter</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>

遠端主機濾網

簡介

遠端主機篩選器可讓您將提交此請求的用戶端主機名稱與一個或多個正規表示式進行比較，並允許請求繼續或拒絕處理來自此用戶端的請求。

正規表示式的語法不同於「標準」萬用字元比對。Tomcat 使用 java.util.regex 套件。有關支援表示式的詳細資料，請參閱 Java 文件。

注意：此篩選器會處理 ServletRequest.getRemoteHost() 方法傳回的值。若要讓此方法傳回正確的主機名稱，您必須在 Connector 上啟用「DNS 查詢」功能。

另請參閱：遠端位址篩選器、HTTP Connector 組態。

濾網類別名稱

遠端位址篩選器的篩選器類別名稱為 org.apache.catalina.filters.RemoteHostFilter 。

初始化參數

遠端主機篩選器支援下列初始化參數

屬性 說明
allow

遠端用戶端主機名稱與之進行比較的正規表示式（使用 java.util.regex）。如果指定此屬性，則遠端主機名稱必須符合此正規表示式，才能接受此請求。如果未指定此屬性，則將接受所有請求，除非遠端主機名稱符合 deny 模式。

deny

與遠端客戶端主機名稱進行比較，使用正則表示式（使用 java.util.regex）。如果指定此屬性，則遠端主機名稱不能與此請求相符才能被接受。如果未指定此屬性，則請求接受僅由 accept 屬性控制。

denyStatus

拒絕拒絕的請求時使用的 HTTP 回應狀態碼。預設值為 403。例如，可以將其設為 404。

遠端 CIDR 濾網

簡介

遠端 CIDR 篩選器允許您將提交此請求的客戶端 IP 位址與一個或多個遵循 CIDR 表示法的網路遮罩進行比較，並允許請求繼續或拒絕處理來自此客戶端的請求。IPv4 和 IPv6 都獲得完全支援。

此篩選器模擬 Apache httpd 的 Order、Allow from 和 Deny from 指令，具有以下限制

  • Order 永遠是 allow, deny；
  • 不支援網路遮罩的點狀四元表示法（也就是說，您不能寫 192.168.1.0/255.255.255.0，您必須寫 192.168.1.0/24；
  • 不支援捷徑，例如等於 10.10.0.0/16 的 10.10.；
  • 正如篩選器名稱所說，這只是一個 CIDR 篩選器，因此也不支援子網域表示法，例如 .mydomain.com。

此篩選器的其他一些功能是

  • 如果您省略 CIDR 前綴，此篩選器將變成單一 IP 篩選器；
  • 與 遠端主機篩選器 不同，它可以處理簡寫形式的 IPv6 位址（::1、fe80::/71 等）。

濾網類別名稱

遠端位址篩選器的篩選器類別名稱為 org.apache.catalina.filters.RemoteCIDRFilter 。

初始化參數

遠端 CIDR 篩選器支援以下初始化參數

屬性 說明
allow

遠端客戶端 IP 位址與之進行比對的 IPv4 或 IPv6 網路遮罩或位址的逗號分隔清單。如果指定此屬性，則遠端位址必須與此請求相符才能被接受。如果未指定此屬性，則所有請求都將被接受，除非遠端 IP 與 deny 屬性中的網路遮罩相符。

deny

遠端客戶端 IP 位址與之進行比對的 IPv4 或 IPv6 網路遮罩或位址的逗號分隔清單。如果指定此屬性，則遠端位址不能與此請求相符才能被接受。如果未指定此屬性，則請求接受僅由 accept 屬性控制。

範例

僅允許來自本機端和區域網路 192.68.0.* 的客戶端存取

      <filter>
        <filter-name>Remote CIDR Filter</filter-name>
        <filter-class>org.apache.catalina.filters.RemoteCIDRFilter</filter-class>
        <init-param>
          <param-name>allow</param-name>
          <param-value>127.0.0.1, ::1, 192.68.0.0/24</param-value>
        </init-param>
      </filter>

      <filter-mapping>
        <filter-name>Remote CIDR Filter</filter-name>
        <url-pattern>/*</url-pattern>
      </filter-mapping>

遠端 IP 濾網

簡介

Tomcat 埠的 mod_remoteip，此篩選器會使用代理伺服器或負載平衡器透過請求標頭（例如「X-Forwarded-For」）提供的 IP 位址清單取代請求的明顯客戶端遠端 IP 位址和主機名稱。

此篩選器的另一個功能是使用代理伺服器或負載平衡器透過請求標頭（例如「X-Forwarded-Proto」）取代明顯的通訊協定（http/https）、伺服器埠和 request.secure。

如果與遠端位址/主機篩選器一起使用，則應先定義此篩選器，以確保將正確的客戶端 IP 位址提供給遠端位址/主機篩選器。

注意：預設情況下，此篩選器對寫入存取日誌中的值沒有影響。當請求處理離開篩選器時，原始值會被還原，而且這總是發生在存取記錄之前。若要將此篩選器設定的遠端位址、遠端主機、伺服器埠和通訊協定值傳遞到存取日誌，則將它們放入請求屬性中。預設情況下已啟用在此發佈這些值，但應明確設定 AccessLogValve 以使用它們。請參閱 AccessLogValve 的 requestAttributesEnabled 屬性文件。

此篩選器設定的請求屬性名稱，且可供存取記錄使用，如下所示

  • org.apache.catalina.AccessLog.RemoteAddr
  • org.apache.catalina.AccessLog.RemoteHost
  • org.apache.catalina.AccessLog.Protocol
  • org.apache.catalina.AccessLog.ServerPort
  • org.apache.tomcat.remoteAddr

濾網類別名稱

遠端 IP 篩選器的篩選器類別名稱為 org.apache.catalina.filters.RemoteIpFilter 。

處理「x-forwarded-for」的基本組態

篩選器會處理 x-forwarded-for http 標頭。 

      <filter>
        <filter-name>RemoteIpFilter</filter-name>
        <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
      </filter>

      <filter-mapping>
        <filter-name>RemoteIpFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
      </filter-mapping>

處理「x-forwarded-for」和「x-forwarded-proto」的基本組態

篩選器會處理 x-forwarded-for 和 x-forwarded-proto http 標頭。SSL 連線中 x-forwarded-proto 標頭的預期值為 https (不區分大小寫)。 

      <filter>
        <filter-name>RemoteIpFilter</filter-name>
        <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
        <init-param>
          <param-name>protocolHeader</param-name>
          <param-value>x-forwarded-proto</param-value>
        </init-param>
      </filter>

      <filter-mapping>
        <filter-name>RemoteIpFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
      </filter-mapping>

包含內部代理伺服器的進階組態

RemoteIpFilter 組態 

     <filter>
       <filter-name>RemoteIpFilter</filter-name>
       <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
       <init-param>
         <param-name>allowedInternalProxies</param-name>
         <param-value>192\.168\.0\.10|192\.168\.0\.11</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpHeader</param-name>
         <param-value>x-forwarded-for</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpProxiesHeader</param-name>
         <param-value>x-forwarded-by</param-value>
       </init-param>
       <init-param>
         <param-name>protocolHeader</param-name>
         <param-value>x-forwarded-proto</param-value>
       </init-param>
     </filter>

請求值

屬性 RemoteIpFilter 前的值 RemoteIpFilter 後的值
request.remoteAddr 192.168.0.10 140.211.11.130
request.header['x-forwarded-for'] 140.211.11.130, 192.168.0.10 null
request.header['x-forwarded-by'] null null
request.header['x-forwarded-proto'] https https
request.scheme http https
request.secure false true
request.serverPort 80 443

注意：x-forwarded-by 標頭為 null，因為只有內部代理程式已傳遞請求。x-forwarded-for 為 null，因為所有代理程式都受信任或為內部代理程式。

包含受信任代理伺服器的進階組態

RemoteIpFilter 組態 

     <filter>
       <filter-name>RemoteIpFilter</filter-name>
       <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
       <init-param>
         <param-name>allowedInternalProxies</param-name>
         <param-value>192\.168\.0\.10|192\.168\.0\.11</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpHeader</param-name>
         <param-value>x-forwarded-for</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpProxiesHeader</param-name>
         <param-value>x-forwarded-by</param-value>
       </init-param>
       <init-param>
         <param-name>trustedProxies</param-name>
         <param-value>proxy1|proxy2</param-value>
       </init-param>
     </filter>

請求值

屬性 RemoteIpFilter 前的值 RemoteIpFilter 後的值
request.remoteAddr 192.168.0.10 140.211.11.130
request.header['x-forwarded-for'] 140.211.11.130, proxy1, proxy2 null
request.header['x-forwarded-by'] null proxy1, proxy2

注意：proxy1 和 proxy2 都是 x-forwarded-for 標頭中受信任的代理程式，它們都已移轉至 x-forwarded-by 標頭。x-forwarded-for 為 null，因為所有代理程式都受信任或為內部代理程式。

包含內部和受信任代理伺服器的進階組態

RemoteIpFilter 組態 

     <filter>
       <filter-name>RemoteIpFilter</filter-name>
       <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
       <init-param>
         <param-name>allowedInternalProxies</param-name>
         <param-value>192\.168\.0\.10|192\.168\.0\.11</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpHeader</param-name>
         <param-value>x-forwarded-for</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpProxiesHeader</param-name>
         <param-value>x-forwarded-by</param-value>
       </init-param>
       <init-param>
         <param-name>trustedProxies</param-name>
         <param-value>proxy1|proxy2</param-value>
       </init-param>
     </filter>

請求值

屬性 RemoteIpFilter 前的值 RemoteIpFilter 後的值
request.remoteAddr 192.168.0.10 140.211.11.130
request.header['x-forwarded-for'] 140.211.11.130, proxy1, proxy2, 192.168.0.10 null
request.header['x-forwarded-by'] null proxy1, proxy2

注意：proxy1 和 proxy2 都是 x-forwarded-for 標頭中受信任的代理程式，它們都已移轉至 x-forwarded-by 標頭。由於 192.168.0.10 是內部代理程式，因此不會顯示在 x-forwarded-by 中。x-forwarded-for 為 null，因為所有代理程式都受信任或為內部代理程式。

包含不受信任代理伺服器的進階組態

RemoteIpFilter 組態 

     <filter>
       <filter-name>RemoteIpFilter</filter-name>
       <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
       <init-param>
         <param-name>allowedInternalProxies</param-name>
         <param-value>192\.168\.0\.10|192\.168\.0\.11</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpHeader</param-name>
         <param-value>x-forwarded-for</param-value>
       </init-param>
       <init-param>
         <param-name>remoteIpProxiesHeader</param-name>
         <param-value>x-forwarded-by</param-value>
       </init-param>
       <init-param>
         <param-name>trustedProxies</param-name>
         <param-value>proxy1|proxy2</param-value>
       </init-param>
     </filter>

請求值

屬性 RemoteIpFilter 前的值 RemoteIpFilter 後的值
request.remoteAddr 192.168.0.10 untrusted-proxy
request.header['x-forwarded-for'] 140.211.11.130, untrusted-proxy, proxy1 140.211.11.130
request.header['x-forwarded-by'] null proxy1

注意：x-forwarded-by 包含受信任的代理程式 proxy1。x-forwarded-by 包含 140.211.11.130，因為 untrusted-proxy 不受信任，因此我們無法信任 untrusted-proxy 是實際的遠端 IP。request.remoteAddr 是 untrusted-proxy，其 IP 已由 proxy1 驗證。

初始化參數

遠端 IP 篩選器支援下列初始化參數

屬性 說明
enableLookups

呼叫 ServletRequest#getRemoteHost() 時，是否應執行 DNS 查詢以提供主機名稱。如果未指定，則使用預設值 false。

remoteIpHeader

此閥讀取的 HTTP 標頭名稱，其中包含從請求端客戶端開始傳遞的 IP 位址清單。如果未指定，則使用預設值 x-forwarded-for。

internalProxies

代理程式的 IP 位址必須符合的正規表示式 (使用 java.util.regex) 才會被視為內部代理程式。出現在 remoteIpHeader 中的內部代理程式將受到信任，且不會出現在 proxiesHeader 值中。如果未指定，則會使用預設值 10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|100\.6[4-9]{1}\.\d{1,3}\.\d{1,3}|100\.[7-9]{1}\d{1}\.\d{1,3}\.\d{1,3}|100\.1[0-1]{1}\d{1}\.\d{1,3}\.\d{1,3}|100\.12[0-7]{1}\.\d{1,3}\.\d{1,3}|172\.1[6-9]{1}\.\d{1,3}\.\d{1,3}|172\.2[0-9]{1}\.\d{1,3}\.\d{1,3}|172\.3[0-1]{1}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1 。

proxiesHeader

此閥建立的 HTTP 標頭名稱，用於保存已在傳入 remoteIpHeader 中處理的代理程式清單。如果未指定，則使用預設值 x-forwarded-by。

requestAttributesEnabled

設為 true 以設定 AccessLog 實作所使用的要求屬性，以覆寫要求傳回的遠端位址、遠端主機、伺服器埠和通訊協定的值。要求屬性也用於在 Manager 網路應用程式的狀態頁面上顯示轉送的遠端位址。如果未設定，將使用預設值 true。

trustedProxies

正規表示式 (使用 java.util.regex)，代理伺服器的 IP 位址必須符合此正規表示式，才會被視為受信任的代理伺服器。出現在 remoteIpHeader 中的受信任代理伺服器會被信任，並會出現在 proxiesHeader 值中。如果未指定，則不會信任任何代理伺服器。

protocolHeader

此閥門讀取的 HTTP 標頭名稱，其中包含用戶端用於連線到代理伺服器的通訊協定。如果未指定，則使用預設值 X-Forwarded-Proto。

hostHeader

此閥門讀取的 HTTP 標頭名稱，其中包含用戶端用於連線到代理伺服器的主機。如果未指定，則使用預設值 null。

portHeader

此閥門讀取的 HTTP 標頭名稱，其中包含用戶端用於連線到代理伺服器的埠。如果未指定，則使用預設值 null。

protocolHeaderHttpsValue

protocolHeader 的值，用於表示它是 HTTPS 要求。如果未指定，則使用預設值 https。

httpServerPort

當 protocolHeader 表示 http 通訊協定且沒有 portHeader 時，ServletRequest.getServerPort() 傳回的值。如果未指定，則使用預設值 80。

httpsServerPort

當 protocolHeader 表示 https 通訊協定且沒有 portHeader 時，ServletRequest.getServerPort() 傳回的值。如果未指定，則使用預設值 443。

changeLocalName

如果為 true，則此篩選器會修改 ServletRequest.getLocalName() 和 ServletRequest.getServerName() 傳回的值。如果未指定，則使用預設值 false。

changeLocalPort

如果為 true，則此篩選器會修改 ServletRequest.getLocalPort() 和 ServletRequest.getServerPort() 傳回的值。如果未指定，則使用預設值 false。

請求傾印濾網

簡介

要求傾印過濾器會記錄來自要求和回應物件的資訊，其目的是用於除錯。使用此過濾器時，建議將 org.apache.catalina.filter.RequestDumperFilter 記錄器導向至專用檔案，並使用 org.apache.juli.VerbatimFormatter。

警告：使用此過濾器會有副作用。此過濾器的輸出包含要求中所包含的任何參數。這些參數會使用預設平台編碼進行解碼。在 Web 應用程式中對 request.setCharacterEncoding() 的任何後續呼叫都不會有任何效果。

濾網類別名稱

要求傾印過濾器的過濾器類別名稱為 org.apache.catalina.filters.RequestDumperFilter 。

初始化參數

要求傾印過濾器不支援任何初始化參數。

範例組態

在 Web 應用程式的 web.xml 中的下列項目會為該 Web 應用程式的所有要求啟用要求傾印過濾器。如果將這些項目新增至 CATALINA_BASE/conf/web.xml，則會為所有 Web 應用程式啟用要求傾印過濾器。

<filter>
    <filter-name>requestdumper</filter-name>
    <filter-class>
        org.apache.catalina.filters.RequestDumperFilter
    </filter-class>
</filter>
<filter-mapping>
    <filter-name>requestdumper</filter-name>
    <url-pattern>*</url-pattern>
</filter-mapping>

在 CATALINA_BASE/conf/logging.properties 中的下列項目會為要求傾印過濾器輸出建立一個獨立的記錄檔。

# To this configuration below, 1request-dumper.org.apache.juli.FileHandler
# also needs to be added to the handlers property near the top of the file
1request-dumper.org.apache.juli.FileHandler.level = INFO
1request-dumper.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
1request-dumper.org.apache.juli.FileHandler.prefix = request-dumper.
1request-dumper.org.apache.juli.FileHandler.encoding = UTF-8
1request-dumper.org.apache.juli.FileHandler.formatter = org.apache.juli.VerbatimFormatter
org.apache.catalina.filters.RequestDumperFilter.level = INFO
org.apache.catalina.filters.RequestDumperFilter.handlers = \
  1request-dumper.org.apache.juli.FileHandler

Session 初始化濾網

簡介

在處理要求之前，Session 初始化過濾器會初始化 jakarta.servlet.http.HttpSession。如果在握手階段需要 HttpSession，則 JSR-356 相容的 WebSocket 實作需要此功能。

WebSocket 的 Java API 沒有強制規定在要求時初始化 HttpSession，因此如果未事先初始化 HttpSession，jakarta.servlet.http.HttpServletRequest 的 getSession() 會傳回 null。

此過濾器會解決此問題，方法是為任何符合其 url-pattern 的 HttpServletRequest 初始化 HttpSession。

濾網類別名稱

Session 初始化過濾器的過濾器類別名稱為 org.apache.catalina.filters.SessionInitializerFilter。

初始化參數

Session 初始化過濾器不支援任何初始化參數。

範例組態

在 Web 應用程式部署描述檔 web.xml 中的下列項目會為符合指定 URL 模式（在此範例中為「/ws/*」）的要求啟用 Session 初始化過濾器。

<filter>
    <filter-name>SessionInitializer</filter-name>
    <filter-class>org.apache.catalina.filters.SessionInitializerFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>SessionInitializer</filter-name>
    <url-pattern>/ws/*</url-pattern>
</filter-mapping>

設定字元編碼濾網

簡介

使用者代理並不總是會在要求中包含字元編碼資訊。根據要求的處理方式，通常會使用 ISO-8859-1 的預設編碼。這並不總是理想的。此過濾器提供設定該編碼或強制將其設定為特定值的選項。此過濾器基本上會呼叫 ServletRequest.setCharacterEncoding() 方法。

如果參數分析發生在這個過濾器之後，則在分析 POST 要求中的參數時會使用此過濾器設定的值。因此，過濾器對應的順序很重要。請注意，GET 要求的編碼不是在此設定，而是在 Connector 中設定。有關詳細資訊，請參閱常見問題集中的字元編碼頁面。

濾網類別名稱

設定字元編碼過濾器的過濾器類別名稱為 org.apache.catalina.filters.SetCharacterEncodingFilter 。

初始化參數

設定字元編碼過濾器支援下列初始化參數

屬性 說明
編碼

應設定的字元編碼名稱。

忽略

決定是否忽略使用者代理指定的任何字元編碼。如果此屬性為 true，則會忽略使用者代理提供的任何值。如果為 false，則只有在使用者代理未指定編碼時才會設定編碼。預設值為 false。

WebDAV 修復濾網

簡介

Microsoft 作業系統有兩個 WebDAV 伺服器。一個用於埠 80，另一個用於所有其他埠。用於埠 80 的實作不符合 WebDAV 規範，且在嘗試與 Tomcat WebDAV Servlet 進行通訊時會失敗。此過濾器透過強制使用 WebDAV 實作（即使透過埠 80 連線）來提供修正程式。

濾網類別名稱

WebDAV 修復過濾器的過濾器類別名稱為 org.apache.catalina.filters.WebdavFixFilter 。

初始化參數

WebDAV 修復過濾器不支援任何初始化參數。