Apache Tomcat 11 配置参考 (11.0.8) - 生命周期监听器组件

生命周期监听器组件

简介

一个 Listener 元素定义了一个组件，当特定事件发生时执行操作，通常是 Tomcat 启动或 Tomcat 停止时。

监听器可以嵌套在 Server、Engine、Host 或 Context 中。某些监听器只意图嵌套在特定的元素中。这些约束将在下面的文档中注明。

属性

通用属性

所有 Listener 的实现都支持以下属性：

属性	描述
`className`	要使用的实现类的 Java 类名。此G类必须实现 `org.apache.catalina.LifecycleListener` 接口。

嵌套组件

Listener 内部不能嵌套任何元素。

标准实现

与大多数 Catalina 组件不同，有几个标准 Listener 实现可用。因此，必须使用 className 属性来选择您希望使用的实现。

APR 生命周期监听器 - org.apache.catalina.core.AprLifecycleListener

APR 生命周期监听器检查 Apache Tomcat Native 库是否存在，如果存在则加载该库。更多信息请参阅 APR/native 指南。

此监听器只能嵌套在 Server 元素中。

APR 生命周期监听器支持以下额外属性：

属性	描述
`SSLEngine`	要使用的 SSLEngine 名称。`off`：不使用 SSL；`on`：使用 SSL 但不使用特定 ENGINE。默认值为 on。这会初始化原生 SSL 引擎，该引擎必须通过使用 `SSLEnabled` 属性在 APR/native 连接器中启用。有关支持的 SSL 硬件引擎和制造商的更多详细信息，请参阅OpenSSL 官方网站。 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 命名信息监听器 - org.apache.catalina.core.ContextNamingInfoListener

Context 命名信息监听器从 Context 添加以下环境条目（隐含 java:comp/env）：context/path、context/encodedPath、context/webappVersion、context/name、context/baseName、context/displayName。

此监听器只能嵌套在 Context 元素中。

Context 命名信息监听器支持以下额外属性：

属性描述

属性	描述
`emptyOnRoot`	对于根上下文，`context/path` 和 `context/encodedPath` 是否将包含 `"/"`，以及 `context/name` 是否将包含带版本的 `"ROOT"`（如果有）。默认值为 `true`。

emptyOnRoot

对于根上下文，context/path 和 context/encodedPath 是否将包含 "/"，以及 context/name 是否将包含带版本的 "ROOT"（如果有）。

默认值为 true。

全局资源生命周期监听器 - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener

全局资源生命周期监听器初始化在 server.xml 中定义为全局资源元素一部分的全局 JNDI 资源。如果没有此监听器，则任何全局资源都将不可用。

此监听器只能嵌套在 Server 元素中。

全局资源生命周期监听器不支持任何额外属性。

JNI 库加载监听器 - org.apache.catalina.core.JniLifecycleListener

JNI 库加载监听器使得多个 Web 应用程序能够使用原生库，通过使用共享类加载器（通常是通用类加载器，但在某些配置中可能有所不同）加载原生库。

该监听器支持两个互斥属性，因此必须使用其中一个，但不能同时使用两个。

属性	描述
`libraryName`	原生库的名称，如 `java.lang.System.loadLibrary()` 中所定义。
`libraryPath`	原生库的绝对路径，如 `java.lang.System.load()` 中所定义。

JRE 内存泄漏预防监听器 - org.apache.catalina.core.JreMemoryLeakPreventionListener

JRE 内存泄漏预防监听器提供了已知的 Java 运行时环境使用上下文类加载器加载单例导致内存泄漏的工作方案，因为如果 Web 应用程序类加载器在当时恰好是上下文类加载器，这将导致内存泄漏。工作方案是在此监听器启动时初始化这些单例，因为那时 Tomcat 的通用类加载器是上下文类加载器。它还提供了已知可能导致 JAR 文件锁定的问题的工作方案。

此监听器只能嵌套在 Server 元素中。

JRE 内存泄漏预防监听器支持以下额外属性：

属性	描述
`appContextProtection`	启用保护，以便 Web 应用程序触发的 `sun.awt.AppContext.getAppContext()` 调用不会导致内存泄漏。请注意，除非 Java 以无头模式启动，否则启用此保护将触发对图形环境的要求。默认值为 `false`。
`classesToInitialize`	在此监听器启动期间要加载和初始化的、逗号分隔的完全限定类名列表。这允许预加载已知会在请求处理期间加载时导致类加载器泄漏的类。可以引用非 JRE 类，例如 `oracle.jdbc.driver.OracleTimeoutThreadPerVM`。默认值为空，但此监听器其他属性管理的其他泄漏保护功能会加载特定的 JRE 类。
`driverManagerProtection`	首次使用 `java.sql.DriverManager` 将触发加载当前类加载器及其父级可见的 JDBC 驱动程序。Web 应用程序级别的内存泄漏保护在大多数情况下可以处理这个问题，但在此处触发加载的副作用较少。默认值为 `true`。
`initSeedGenerator`	首次使用 `SeedGenerator`（默认安全 spi 实现的内部类）可能会在某些平台上创建线程。根据首次使用安全随机数的时间，此线程可能会与 Web 应用程序类加载器关联，导致内存泄漏。将其设置为 `true` 将初始化种子。默认值为 `false`，以避免在不需要时消耗随机数。
`urlCacheProtection`	启用保护，以便使用 `java.net.URLConnection` 从 JAR 文件读取资源不会导致 JAR 文件被锁定。请注意，启用此保护默认会禁用通过 `java.net.URLConnection` 获取的所有资源的缓存。可以根据需要逐案重新启用缓存。默认值为 `true`。

JreMemoryLeakPreventionListener 示例

以下是如何配置此监听器的 classesToInitialize 属性的示例。

如果此监听器在 server.xml 中配置为

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

则 OracleTimeoutThreadPerVM 类将在监听器启动期间加载和初始化，而不是在请求处理期间。

OpenSSL 生命周期监听器 - org.apache.catalina.core.OpenSSLLifecycleListener

OpenSSL 生命周期监听器检查 OpenSSL 库是否存在，如果存在则加载该库。这使用 Java 22 的 FFM API 而不是额外的原生代码。当启用并成功加载时，NIO 和 NIO2 连接器将利用 OpenSSL 提供 TLS 功能。这是上述 APR 生命周期监听器的功能替代品。

此监听器只能嵌套在 Server 元素中。

OpenSSL 生命周期监听器支持以下额外属性：

属性	描述
`SSLEngine`	对于 OpenSSL 1.x，要使用的 SSLEngine 名称。有关支持的 SSL 硬件引擎和制造商的更多详细信息，请参阅OpenSSL 官方网站。
`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。

属性角色映射监听器 - org.apache.catalina.core.PropertiesRoleMappingListener

属性角色映射监听器从属性文件填充上下文的角色映射。键代表应用程序角色（例如，admin、user、uservisor 等），而值代表技术角色（例如，DNs、SIDs、UUIDs 等）。如果属性文件还包含通用应用程序配置，例如 app-roles.，则键也可以带有前缀。

此监听器只能嵌套在 Context 元素中。

属性角色映射监听器支持以下额外属性：

属性描述

属性	描述
`roleMappingFile`	角色映射属性文件的路径。您可以使用协议 `webapp:` 和 `ConfigFileLoader` 支持的任何内容。默认值为 `webapp:/WEB-INF/role-mapping.properties`。
`keyPrefix`	要从属性键中过滤的前缀。所有不带此前缀的其他键都将被忽略。

roleMappingFile

角色映射属性文件的路径。您可以使用协议 webapp: 和 ConfigFileLoader 支持的任何内容。

默认值为 webapp:/WEB-INF/role-mapping.properties。

keyPrefix

要从属性键中过滤的前缀。所有不带此前缀的其他键都将被忽略。

安全生命周期监听器 - org.apache.catalina.security.SecurityListener

安全生命周期监听器在 Tomcat 启动时执行一系列安全检查，如果检查失败则阻止 Tomcat 启动。此监听器默认未启用。要启用它，请取消注释 $CATALINA_BASE/conf/server.xml 中的监听器。

此监听器只能嵌套在 Server 元素中。

安全生命周期监听器支持以下额外属性：

属性	描述
`checkedOsUsers`	逗号分隔的 OS 用户列表，这些用户不能用于启动 Tomcat。如果未指定，则使用默认值 root。要禁用此检查，请将属性设置为空字符串。用户名检查不区分大小写。
`minimumUmask`	Tomcat 启动前必须配置的最不严格的 umask。如果未指定，则使用默认值 0007。要禁用此检查，请将属性设置为空字符串。此检查不在 Windows 平台上执行。
`buildDateWarningAgeDays`	此 Tomcat 实例的构建日期与其启动日期之间的最大天数，超过该天数将记录警告。设置为小于 0 的任何值（例如 -1）以禁用此检查。如果未指定，则使用默认值 -1。

StoreConfig 生命周期监听器 - org.apache.catalina.storeconfig.StoreConfigLifecycleListener

StoreConfig 生命周期监听器配置一个 StoreConfig MBean，该 MBean 可用于将当前服务器配置保存到 server.xml 中，或将 Web 应用程序的当前配置保存到 context.xml 文件中。

此监听器只能嵌套在 Server 元素中。

StoreConfig 生命周期监听器支持以下额外属性：

属性	描述
`storeConfigClass`	要使用的 `IStoreConfig` 实现的名称。如果未指定，将使用默认值 `org.apache.catalina.storeconfig.StoreConfig`。
`storeRegistry`	配置 `IStoreConfig` 如何保存配置的配置文件的 URL。如果未指定，将使用内置资源 `/org/apache/catalina/storeconfig/server-registry.xml`。

ThreadLocal 泄漏预防监听器 - org.apache.catalina.core.ThreadLocalLeakPreventionListener

ThreadLocal 泄漏预防监听器在 Context 停止时触发 Executor 池中线程的续订，以避免与线程局部变量相关的内存泄漏。活跃线程在执行完任务返回池后将逐一续订。续订仅针对其 renewThreadsWhenStoppingContext 属性设置为 true 的上下文发生。

此监听器只能嵌套在 Server 元素中。

ThreadLocal 泄漏预防监听器不支持任何额外属性。

TLS 配置重新加载监听器 - org.apache.catalina.security.TLSCertificateReloadListener

此监听器可用于监控 TLS 证书的过期日期，并在 TLS 证书过期前设定的天数触发 TLS 配置的自动重新加载。

此监听器假定有其他进程（certbot、云基础设施等）定期更新证书并用新证书替换当前证书。

此监听器不会重新读取 server.xml 中的 Tomcat 配置。如果您对 server.xml 进行了更改，则必须重新启动 Tomcat 进程才能使这些更改生效。

此监听器只能嵌套在 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`	定义拒绝部署的用户的正则表达式。如果指定此属性，则要部署的用户不得匹配此模式。如果未指定此属性，则用户的部署将由 allow 属性控制。

版本日志生命周期监听器 - 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 监听器 - org.apache.catalina.ha.backend.HeartbeatListener

HTTPD mod_heartmonitor 监听器允许 tomcat 向 Apache HTTPD mod_heartmonitor 模块发送心跳消息。

HTTPD mod_heartmonitor 监听器支持以下额外属性：

属性	描述
`Port`	接收来自 HTTPD 代理流量的连接器端口，默认为第一个连接器。
`Host`	Host 是与接收代理流量的连接器的 address 对应的 IP，默认为空，将使用 Port。
`proxyURL`	proxyURL 是与 httpd 配置中心跳处理程序的 Location 对应的 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。