Apache Tomcat 10 組態參考 (10.1.23) - LifeCycle Listener 元件

LifeCycle Listener 元件

簡介

Listener 元素定義一個元件，當特定事件發生時會執行動作，通常是 Tomcat 啟動或停止時。

偵聽器可以巢狀在 Server、Engine、Host 或 Context 中。有些偵聽器只打算巢狀在特定元素中。這些限制會在以下的文件中註明。

屬性

常見屬性

Listener 的所有實作都支援下列屬性

屬性	說明
`className`	要使用的實作的 Java 類別名稱。此類別必須實作 `org.apache.catalina.LifecycleListener` 介面。

巢狀元件

Listener 內部不得嵌套任何元素。

標準實作

與大多數 Catalina 元件不同，有數個標準 Listener 實作可供使用。因此，className 屬性必須用於選取您要使用的實作。

APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener

APR Lifecycle Listener 會檢查 Apache Tomcat Native 函式庫是否存在，並在存在時載入函式庫。如需更多資訊，請參閱 APR/native 指南。

此 listener 只能嵌套在 Server 元素內。

APR Lifecycle Listener 支援下列其他屬性

屬性	說明
`SSLEngine`	要使用的 SSLEngine 的名稱。`off`：不使用 SSL，`on`：使用 SSL 但沒有特定 ENGINE。預設值為 on。這會初始化原生 SSL 引擎，必須使用 `SSLEnabled` 屬性在 APR/native 連接器中啟用此引擎。請參閱官方 OpenSSL 網站，以取得有關支援的 SSL 硬體引擎和製造商的更多詳細資料。 Tomcat Native 2.x 起需要 SSL，因此如果在使用 Tomcat Native 2.x 起時將 SSLEngine 設為 `off`，APR/native 函式庫將會停用。
`SSLRandomSeed`	用於設定 SSLEngine 的 PRNG 種子的熵來源。預設值為 `builtin`。在開發系統上，您可能想要將此設定為 `/dev/urandom`，以允許更快的啟動時間。
`FIPSMode`	此屬性的行為取決於 Tomcat Native 是針對 OpenSSL 1.x 或 OpenSSL 3.x 編譯。對於 OpenSSL 1.x：設為 `on` 以要求 OpenSSL 進入 FIPS 模式（如果 OpenSSL 已在 FIPS 模式，它將保持在 FIPS 模式）。設為 `enter` 以強制 OpenSSL 進入 FIPS 模式（如果 OpenSSL 已在 FIPS 模式，將會發生錯誤）。設為 `require` 以要求 OpenSSL 已經在 FIPS 模式（如果 OpenSSL 尚未在 FIPS 模式，將會發生錯誤）。對於 OpenSSL 3.x：`on`、`enter` 和 `require` 的行為都相同。如果 FIPS 提供者是預設提供者，將會使用它。如果 FIPS 提供者不是預設提供者，將會發生錯誤。 FIPS 模式要求您擁有相容 FIPS 的 OpenSSL 函式庫。如果此屬性設為 `off` 以外的任何值，也必須啟用 SSLEngine。預設值為 `off`。
`useOpenSSL`	此屬性控制 OpenSSL JSSE 實作的自動選取。預設為 `true`，如果本機程式庫可用且使用 NIO 或 NIO2 連接器，則會使用 OpenSSL。

Context Naming Info Listener - org.apache.catalina.core.ContextNamingInfoListener

Context Naming Info Listener 會從 Context 新增下列環境項目（暗示 java:comp/env）：context/path、context/encodedPath、context/webappVersion、context/name、context/baseName、context/displayName。

此 listener 只能嵌套在 Context 元素中。

Context Naming Info Listener 支援下列其他屬性

屬性說明

屬性	說明
`emptyOnRoot`	對於根目錄 `context/path` 和 `context/encodedPath` 是否會包含 `"/"`，而 `context/name` 是否會包含 `"ROOT"` 和版本（如果有）。預設值為 `true`。

emptyOnRoot

對於根目錄 context/path 和 context/encodedPath 是否會包含 "/"，而 context/name 是否會包含 "ROOT" 和版本（如果有）。

預設值為 true。

Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener

Global Resources Lifecycle Listener 會初始化 server.xml 中定義的 Global JNDI 資源，作為 Global Resources 元素的一部分。沒有此 listener，將無法使用任何 Global Resources。

此 listener 只能嵌套在 Server 元素內。

Global Resources Lifecycle Listener 不支援任何其他屬性。

JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener

JNI Library Loading Listener 讓多個 Webapp 可以使用本機程式庫，方法是使用共用類別載入器（通常是 Common 類別載入器，但在某些組態中可能有所不同）載入本機程式庫

此 listener 支援兩個互斥的屬性，因此必須使用其中一個，但不能同時使用兩個。

屬性	說明
`libraryName`	本機程式庫的名稱，如 `java.lang.System.loadLibrary()` 中定義。
`libraryPath`	本機程式庫的絕對路徑，如 `java.lang.System.load()` 中定義。

JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener

JRE Memory Leak Prevention Listener 提供已知 Java 執行環境使用 Context 類別載入器載入單例的解決方案，因為如果 Web 應用程式類別載入器剛好是當時的 Context 類別載入器，就會造成記憶體外洩。解決方案是在此 listener 啟動時初始化這些單例，因為 Tomcat 的 Common 類別載入器在當時是 Context 類別載入器。它也提供已知問題的解決方案，這些問題可能導致 JAR 檔案鎖定。

此 listener 只能嵌套在 Server 元素內。

JRE Memory Leak Prevention Listener 支援下列其他屬性

屬性	說明
`appContextProtection`	啟用保護，讓由網頁應用程式觸發的對 `sun.awt.AppContext.getAppContext()` 的呼叫不會導致記憶體外洩。請注意，啟用此保護會觸發對圖形環境的需求，除非 Java 在無頭模式下啟動。預設值為 `false`。
`classesToInitialize`	此 Listener 啟動期間要載入並初始化的逗號分隔完整類別名稱清單。這允許預先載入已知會在要求處理期間載入時引發類別載入器外洩的類別。可以參照非 JRE 類別，例如 `oracle.jdbc.driver.OracleTimeoutThreadPerVM`。預設值為空，但特定 JRE 類別會由此 Listener 的其他屬性管理的其他外洩保護功能載入。
`driverManagerProtection`	第一次使用 `java.sql.DriverManager` 會觸發載入目前類別載入器及其父代可見的 JDBC 驅動程式。在大部分情況下，網頁應用程式層級的記憶體外洩保護可以處理這個問題，但在此觸發載入的副作用較少。預設值為 `true`。
`initSeedGenerator`	第一次使用預設安全性 spi 實作的內部類別 `SeedGenerator`，可能會在某些平台上建立執行緒。根據第一次使用安全亂數的時間，此執行緒可能會與網頁應用程式類別載入器關聯，導致記憶體外洩。將此設定為 `true` 會初始化種子。預設值為 `false`，以避免在不需要時消耗亂數。
`urlCacheProtection`	啟用保護，讓使用 `java.net.URLConnection` 從 JAR 檔案讀取資源不會導致 JAR 檔案被鎖定。請注意，啟用此保護預設會停用透過 `java.net.URLConnection` 取得的所有資源的快取。視需要，可以逐一重新啟用快取。預設值為 `true`。

JreMemoryLeakPreventionListener 範例

以下是設定此 Listener 的 classesToInitialize 屬性的範例。

如果此 Listener 在 server.xml 中設定為

  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
            classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" />

則 OracleTimeoutThreadPerVM 類別會在 Listener 啟動期間載入並初始化，而不是在要求處理期間載入。

OpenSSL Lifecycle Listener - org.apache.catalina.core.OpenSSLLifecycleListener

OpenSSL Lifecycle Listener 會檢查 OpenSSL 函式庫是否存在，並在存在時載入函式庫。這會使用 Java 22 的 FFM API，而不是額外的原生程式碼。啟用並成功載入後，NIO 和 NIO2 連接器會使用 OpenSSL 進行 TLS 功能。這是上面所述的 APR Lifecycle Listener 的功能性替代方案。

此 listener 只能嵌套在 Server 元素內。

OpenSSL Lifecycle Listener 支援下列額外屬性

屬性	說明
`SSLEngine`	要使用的 SSLEngine 的名稱，適用於 OpenSSL 1.x。請參閱官方 OpenSSL 網站，以取得有關支援的 SSL 硬體引擎和製造商的更多詳細資料。
`SSLRandomSeed`	用於設定 SSLEngine 的 PRNG 種子的熵來源。預設值為 `builtin`。在開發系統上，您可能想要將此設定為 `/dev/urandom`，以允許更快的啟動時間。
`FIPSMode`	此屬性的行為取決於 Tomcat Native 是針對 OpenSSL 1.x 或 OpenSSL 3.x 編譯。對於 OpenSSL 1.x：設為 `on` 以要求 OpenSSL 進入 FIPS 模式（如果 OpenSSL 已在 FIPS 模式，它將保持在 FIPS 模式）。設為 `enter` 以強制 OpenSSL 進入 FIPS 模式（如果 OpenSSL 已在 FIPS 模式，將會發生錯誤）。設為 `require` 以要求 OpenSSL 已經在 FIPS 模式（如果 OpenSSL 尚未在 FIPS 模式，將會發生錯誤）。對於 OpenSSL 3.x：`on`、`enter` 和 `require` 的行為都相同。如果 FIPS 提供者是預設提供者，將會使用它。如果 FIPS 提供者不是預設提供者，將會發生錯誤。 FIPS 模式要求您擁有相容 FIPS 的 OpenSSL 函式庫。如果此屬性設為 `off` 以外的任何值，也必須啟用 SSLEngine。預設值為 `off`。
`useOpenSSL`	此屬性控制 OpenSSL JSSE 實作的自動選取。預設為 `true`，如果 FFM API 可用，將使用 OpenSSL。

Properties Role Mapping Listener - org.apache.catalina.core.PropertiesRoleMappingListener

屬性角色對應監聽器從屬性檔填入內容的角色對應。金鑰代表應用程式角色（例如，管理員、使用者、使用者管理員等），而值代表技術角色（例如，DN、SID、UUID 等）。金鑰也可以加上前綴，例如，如果屬性檔也包含一般應用程式組態：app-roles.。

此 listener 只能嵌套在 Context 元素中。

屬性角色對應監聽器支援下列其他屬性

屬性說明

屬性	說明
`roleMappingFile`	角色對應屬性檔的路徑。您可以使用通訊協定 `webapp:` 和任何 `ConfigFileLoader` 支援的內容。預設值為 `webapp:/WEB-INF/role-mapping.properties`。
`keyPrefix`	從屬性金鑰中濾出的前綴。所有其他沒有前綴的金鑰將會被忽略。

roleMappingFile

角色對應屬性檔的路徑。您可以使用通訊協定 webapp: 和任何 ConfigFileLoader 支援的內容。

預設值為 webapp:/WEB-INF/role-mapping.properties。

keyPrefix

從屬性金鑰中濾出的前綴。所有其他沒有前綴的金鑰將會被忽略。

Security Lifecycle Listener - org.apache.catalina.security.SecurityListener

安全性生命週期監聽器在 Tomcat 啟動時執行多項安全性檢查，如果檢查失敗，將會阻止 Tomcat 啟動。預設未啟用監聽器。若要啟用，請取消 $CATALINA_BASE/conf/server.xml 中監聽器的註解。

此 listener 只能嵌套在 Server 元素內。

安全性生命週期監聽器支援下列其他屬性

屬性	說明
`checkedOsUsers`	不得用來啟動 Tomcat 的作業系統使用者清單，以逗號分隔。如果未指定，將使用預設值 root。若要停用此檢查，請將屬性設定為空字串。使用者名稱會以不區分大小寫的方式進行檢查。
`minimumUmask`	在 Tomcat 啟動前必須組態的最小限制 umask。如果未指定，將使用預設值 0007。若要停用此檢查，請將屬性設定為空字串。檢查不會在 Windows 平台上執行。
`buildDateWarningAgeDays`	此 Tomcat 執行個體的建置日期與其啟動日期之間的天數上限，超過此上限將會記錄警告。設定為小於 0（例如 -1）以停用此檢查。如果未指定，將使用預設值 -1。

StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener

StoreConfig Lifecycle Listener 會設定 StoreConfig MBean，可用於將目前的伺服器設定儲存在 server.xml 中，或將 Web 應用程式的目前設定儲存在 context.xml 檔案中。

此 listener 只能嵌套在 Server 元素內。

StoreConfig Lifecycle Listener 支援下列其他屬性

屬性	說明
`storeConfigClass`	要使用的 `IStoreConfig` 實作名稱。如果未指定，將使用預設值 `org.apache.catalina.storeconfig.StoreConfig`。
`storeRegistry`	設定 `IStoreConfig` 如何儲存設定的組態檔 URL。如果未指定，將使用內建資源 `/org/apache/catalina/storeconfig/server-registry.xml`。

ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener

ThreadLocal Leak Prevention Listener 會在 Executor 池中觸發執行緒更新，當 Context 正在停止時，以避免與執行緒相關的記憶體外洩。執行緒在執行完工作回到池中後，將會逐一更新。更新只會發生在將 renewThreadsWhenStoppingContext 屬性設定為 true 的內容。

此 listener 只能嵌套在 Server 元素內。

ThreadLocal Leak Prevention Listener 不支援其他屬性。

TLS 組態重新載入偵聽器 - org.apache.catalina.security.TLSCertificateReloadListener

此監聽器可用於監控 TLS 憑證的到期日，並在 TLS 憑證到期前設定天數觸發 TLS 組態自動重新載入。

此監聽器假設有其他處理程序 (certbot、雲端基礎架構等) 會定期更新憑證，並將目前的憑證替換為新的憑證。

此監聽器不會從 server.xml 重新讀取 Tomcat 組態。如果您對 server.xml 進行變更，您必須重新啟動 Tomcat 處理程序才能採用這些變更。

此 listener 只能嵌套在 Server 元素內。

屬性	說明
`checkPeriod`	重新載入檢查之間的時間（以秒為單位）。`LifecycleListener` 的定期處理程序通常會比此監聽器要求的執行頻率高很多。此屬性控制檢查之間的期間。如果未指定，將使用預設值 86,400 秒（24 小時）。
`daysBefore`	預期會在 TLS 憑證到期前幾天放置新的憑證，並觸發重新載入。如果未指定，將使用預設值 14 天。

UserConfig - org.apache.catalina.startup.UserConfig

UserConfig 提供使用者 Web 應用程式的功能。使用者 Web 應用程式會將從波浪符號 ("~") 和使用者名稱開始的請求 URI 對應到伺服器上該使用者家目錄中的目錄（通常稱為 public_html）。

請參閱 Host 元素中的使用者 Web 應用程式特殊功能，以取得更多資訊。

UserConfig 支援下列其他屬性

屬性	說明
`directoryName`	要在每個使用者主目錄中搜尋的目錄名稱。預設值為 `public_html`。
`userClass`	使用者資料庫類別的類別名稱。目前有兩個使用者資料庫，`org.apache.catalina.startup.PasswdUserDatabase` 用於使用 /etc/passwd 檔案來識別有效使用者的 Unix 系統。`org.apache.catalina.startup.HomesUserDatabase` 用於未在使用 /etc/passwd 的伺服器。HomesUserDatabase 會部署在指定基本目錄中找到的所有目錄。
`homeBase`	包含使用者主目錄的基本目錄。只有在使用 `org.apache.catalina.startup.HomesUserDatabase` 時才會有效。
`allow`	定義允許部署使用者的正規表示式。如果指定此屬性，則要部署的使用者必須符合此模式。如果未指定此屬性，則所有使用者都將被部署，除非使用者符合拒絕模式。
`deny`	定義拒絕部署使用者的正規表示式。如果指定此屬性，則要部署的使用者不得符合此模式。如果未指定此屬性，則使用者的部署將由允許屬性控制。

Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener

版本記錄生命週期監聽器會在 Tomcat 啟動時記錄 Tomcat、Java 和作業系統資訊。

此監聽器只能嵌套在 Server 元素中，並且應該是定義的第一個監聽器。

版本記錄生命週期監聽器支援下列其他屬性

屬性	說明
`logArgs`	如果為 `true`，則會記錄 Tomcat 啟動時傳遞給 Java 的命令列引數。如果未指定，則會使用預設值 `true`。
`logEnv`	如果為 `true`，則會記錄 Tomcat 啟動時的當前環境變數。如果未指定，則會使用預設值 `false`。
`logProps`	如果為 `true`，則會記錄當前的 Java 系統屬性。如果未指定，則會使用預設值 `false`。

HTTPD mod_heartmonitor Listener - org.apache.catalina.ha.backend.HeartbeatListener

HTTPD mod_heartmonitor 監聽器允許 Tomcat 將心跳訊息傳送給 Apache HTTPD mod_heartmonitor 模組。

HTTPD mod_heartmonitor 偵聽器支援下列額外屬性

屬性	說明
`Port`	連接埠，將從 HTTPD 接收代理流量，預設使用第一個連接埠
`主機`	Host，這是將接收代理流量的連接埠的位址對應的 IP，預設為空值，將使用Port
`proxyURL`	proxyURL 是 httpd 組態中對應於心跳處理常式的位置的 URL，預設為 /HeartbeatListener
`ProxyList`	ProxyList 是 Tomcat 將從中接收要求的代理清單，格式為「address:port,address:port」，填寫後會停用多播邏輯，且會忽略多重參數
`Group`	Group 是用於廣播訊息至 HTTPD 的多播 IP，預設為 224.0.1.105
`Multiport`	Multiport 是用於廣播訊息至 HTTPD 的多播埠，預設為 23364
`Ttl`	Ttl 是廣播訊息的 TTL，預設為 16