生命周期监听器组件

目录

简介

侦听器元素定义在特定事件（通常是 Tomcat 启动或停止）发生时执行操作的组件。

侦听器可以嵌套在 服务器、引擎、主机 或 上下文 中。某些侦听器仅用于嵌套在特定元素中。这些约束在下面的文档中进行了说明。

属性

通用属性

侦听器的所有实现都支持以下属性

属性 说明
className

要使用的实现的 Java 类名。此类必须实现 org.apache.catalina.LifecycleListener 接口。

嵌套组件

不得在 侦听器中嵌套任何元素。

标准实现

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

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

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

此侦听器只能嵌套在 服务器 元素中。

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。

上下文命名信息监听器 - org.apache.catalina.core.ContextNamingInfoListener

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

此侦听器只能嵌套在 上下文 元素中。

上下文命名信息侦听器支持以下附加属性

属性 说明
emptyOnRoot

对于根上下文，context/path 和 context/encodedPath 是否将包含 "/"，context/name 是否将包含 "ROOT"（如果存在版本）。

默认值为 true。

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

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

此侦听器只能嵌套在 服务器 元素中。

全局资源生命周期侦听器不支持任何附加属性。

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 文件锁定的已知问题提供解决方法。

此侦听器只能嵌套在 服务器 元素中。

JRE 内存泄漏预防侦听器支持以下其他属性

属性 说明
appContextProtection

启用保护，以便由 Web 应用程序触发的 sun.awt.AppContext.getAppContext() 调用不会导致内存泄漏。请注意，启用此保护将触发对图形环境的需求，除非 Java 在 headless 模式下启动。默认值为 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 生命周期侦听器 的功能性替代品。

此侦听器只能嵌套在 服务器 元素中。

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

属性角色映射侦听器从属性文件中填充上下文的 role mapping。键表示应用程序角色（例如，admin、user、uservisor 等），而值表示技术角色（例如，DN、SID、UUID 等）。如果属性文件也包含通用应用程序配置，则键也可以加上前缀：app-roles.。

此侦听器只能嵌套在 上下文 元素中。

属性角色映射侦听器 支持以下其他属性

属性 说明
roleMappingFile

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

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

keyPrefix

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

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

安全生命周期侦听器在 Tomcat 启动时执行多项安全检查，并在检查失败时阻止 Tomcat 启动。侦听器默认情况下未启用。要启用它，请取消注释 $CATALINA_BASE/conf/server.xml 中的侦听器。

此侦听器只能嵌套在 服务器 元素中。

安全生命周期侦听器支持以下附加属性

属性 说明
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 文件中。

此侦听器只能嵌套在 服务器 元素中。

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 泄漏预防侦听器在 Executor 池中触发线程的续订，当 Context 停止时，以避免与线程本地相关的内存泄漏。执行任务后，活动线程将逐个续订，直到它们返回池中。续订仅针对将 renewThreadsWhenStoppingContext 属性设置为 true 的上下文执行。

此侦听器只能嵌套在 服务器 元素中。

ThreadLocal 泄漏预防侦听器不支持任何附加属性。

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

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

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

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

此侦听器只能嵌套在 服务器 元素中。

属性 说明
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 用于在 Unix 系统上使用 /etc/passwd 文件来识别有效用户。org.apache.catalina.startup.HomesUserDatabase 用于在不使用 /etc/passwd 的服务器上。HomesUserDatabase 部署在指定基本目录中找到的所有目录。

homeBase

包含用户主目录的基本目录。仅当使用 org.apache.catalina.startup.HomesUserDatabase 时才有效。

allow

定义允许部署用户的正则表达式。如果指定此属性，则要部署的用户必须匹配此模式。如果未指定此属性，则将部署所有用户，除非用户匹配拒绝模式。

deny

定义拒绝部署用户的正则表达式。如果指定此属性，则要部署的用户不能匹配此模式。如果未指定此属性，则用户的部署将受允许属性控制。

版本记录生命周期监听器 - 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 是与将接收代理流量的连接器的地址相对应的 IP，默认情况下为空，将使用端口

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