- Introduction
- Attributes
- Nested Components
- Standard Implementations
- APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener
- Context Naming Info Listener - org.apache.catalina.core.ContextNamingInfoListener
- Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener
- JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener
- JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener
- OpenSSL Lifecycle Listener - org.apache.catalina.core.OpenSSLLifecycleListener
- Properties Role Mapping Listener - org.apache.catalina.core.PropertiesRoleMappingListener
- Security Lifecycle Listener - org.apache.catalina.security.SecurityListener
- StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener
- ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener
- TLS configuration reload listener - org.apache.catalina.security.TLSCertificateReloadListener
- UserConfig - org.apache.catalina.startup.UserConfig
- Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener
- HTTPD mod_heartmonitor Listener - org.apache.catalina.ha.backend.HeartbeatListener
The LifeCycle Listener Component
Table of Contents
Introduction
A Listener element defines a component that performs actions when specific events occur, usually Tomcat starting or Tomcat stopping.
Listeners may be nested inside a Server, Engine, Host or Context. Some Listeners are only intended to be nested inside specific elements. These constraints are noted in the documentation below.
Attributes
Common Attributes
All implementations of Listener support the following attributes:
Attribute | Description |
---|---|
className |
Java class name of the implementation to use. This class must
implement the |
Nested Components
No element may be nested inside a Listener.
Standard Implementations
Unlike most Catalina components, there are several standard
Listener implementations available. As a result,
the className
attribute MUST be used to select the
implementation you wish to use.
APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener
The APR Lifecycle Listener checks for the presence of the Apache Tomcat Native library and loads the library if it is present. For more information see the APR/native guide.
This listener must only be nested within Server elements.
The following additional attributes are supported by the APR Lifecycle Listener:
Attribute | Description |
---|---|
SSLEngine |
Name of the SSLEngine to use. The default value is on. This initializes the
native SSL engine, which must be enabled in the APR/native connector by
the use of the See the Official OpenSSL website for more details on supported SSL hardware engines and manufacturers. Tomcat Native 2.x onwards requires SSL so if SSLEngine is set to
|
SSLRandomSeed |
Entropy source used to seed the SSLEngine's PRNG. The default value
is |
FIPSMode |
The behaviour of this attribute depends on whether Tomcat Native has been compiled against OpenSSL 1.x or OpenSSL 3.x. For OpenSSL 1.x: Set to For OpenSSL 3.x: FIPS mode requires you to have a FIPS-capable OpenSSL library.
If this attribute is set to anything other than The default value is |
useOpenSSL |
This attribute controls the auto-selection of the OpenSSL JSSE
implementation. The default is |
Context Naming Info Listener - org.apache.catalina.core.ContextNamingInfoListener
The Context Naming Info Listener adds the following
environment entries (java:comp/env
implied) from the
Context: context/path
,
context/encodedPath
, context/webappVersion
,
context/name
, context/baseName
,
context/displayName
.
This listener must only be nested within Context elements.
The following additional attributes are supported by the Context Naming Info Listener:
Attribute | Description |
---|---|
emptyOnRoot |
Whether for the root context The default value is |
Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener
The Global Resources Lifecycle Listener initializes the Global JNDI resources defined in server.xml as part of the Global Resources element. Without this listener, none of the Global Resources will be available.
This listener must only be nested within Server elements.
No additional attributes are supported by the Global Resources Lifecycle Listener.
JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener
The JNI Library Loading Listener makes it possible for multiple Webapps to use a native library, by loading the native library using a shared class loader (typically the Common class loader but may vary in some configurations)
The listener supports two mutually exclusive attributes, so one of them must be used, but you can not use both together:
Attribute | Description |
---|---|
libraryName |
The name of the native library, as defined in
|
libraryPath |
The absolute path of the native library, as defined in
|
JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener
The JRE Memory Leak Prevention Listener provides work-arounds for known places where the Java Runtime environment uses the context class loader to load a singleton as this will cause a memory leak if a web application class loader happens to be the context class loader at the time. The work-around is to initialise these singletons when this listener starts as Tomcat's common class loader is the context class loader at that time. It also provides work-arounds for known issues that can result in locked JAR files.
This listener must only be nested within Server elements.
The following additional attributes are supported by the JRE Memory Leak Prevention Listener:
Attribute | Description |
---|---|
appContextProtection |
Enables protection so that calls to
|
classesToInitialize |
List of comma-separated fully qualified class names to load and initialize
during the startup of this Listener. This allows to pre-load classes that are
known to provoke classloader leaks if they are loaded during a request
processing. Non-JRE classes may be referenced, like
|
driverManagerProtection |
The first use of |
initSeedGenerator |
The first use of |
urlCacheProtection |
Enables protection so that reading resources from JAR files using
|
JreMemoryLeakPreventionListener Examples
The following is an example of how to configure the
classesToInitialize
attribute of this listener.
If this listener was configured in server.xml as:
<Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" />
then the OracleTimeoutThreadPerVM
class would be loaded
and initialized during listener startup instead of during request
processing.
OpenSSL Lifecycle Listener - org.apache.catalina.core.OpenSSLLifecycleListener
The OpenSSL Lifecycle Listener checks for the presence of the OpenSSL library and loads the library if it is present. This uses the FFM API from Java 22 instead of additional native code. When enabled and successfully loaded, NIO and NIO2 connector will then make use of OpenSSL for TLS functionality. This is a functional replacement to the APR Lifecycle Listener described above.
This listener must only be nested within Server elements.
The following additional attributes are supported by the OpenSSL Lifecycle Listener:
Attribute | Description |
---|---|
SSLEngine |
Name of the SSLEngine to use, for OpenSSL 1.x. See the Official OpenSSL website for more details on supported SSL hardware engines and manufacturers. |
SSLRandomSeed |
Entropy source used to seed the SSLEngine's PRNG. The default value
is |
FIPSMode |
The behaviour of this attribute depends on whether Tomcat Native has been compiled against OpenSSL 1.x or OpenSSL 3.x. For OpenSSL 1.x: Set to For OpenSSL 3.x: FIPS mode requires you to have a FIPS-capable OpenSSL library.
If this attribute is set to anything other than The default value is |
useOpenSSL |
This attribute controls the auto-selection of the OpenSSL JSSE
implementation. The default is |
Properties Role Mapping Listener - org.apache.catalina.core.PropertiesRoleMappingListener
The Properties Role Mapping Listener populates the context's role mapping
from a properties file. The keys represent application roles (e.g., admin, user, uservisor,
etc.) while the values represent technical roles (e.g., DNs, SIDs, UUIDs, etc.). A key can
also be prefixed if, e.g., the properties file contains generic application configuration
as well: app-roles.
.
This listener must only be nested within Context elements.
The following additional attributes are supported by the Properties Role Mapping Listener:
Attribute | Description |
---|---|
roleMappingFile |
The path to the role mapping properties file. You can use protocol The default value is |
keyPrefix |
The prefix to filter from property keys. All other keys will be ignored which do not have the prefix. |
Security Lifecycle Listener - org.apache.catalina.security.SecurityListener
The Security Lifecycle Listener performs a number of security checks when Tomcat starts and prevents Tomcat from starting if they fail. The listener is not enabled by default. To enabled it uncomment the listener in $CATALINA_BASE/conf/server.xml.
This listener must only be nested within Server elements.
The following additional attributes are supported by the Security Lifecycle Listener:
Attribute | Description |
---|---|
checkedOsUsers |
A comma separated list of OS users that must not be used to start Tomcat. If not specified, the default value of root is used. To disable this check, set the attribute to the empty string. Usernames are checked in a case-insensitive manner. |
minimumUmask |
The least restrictive umask that must be configured before Tomcat will start. If not specified, the default value of 0007 is used. To disable this check, set the attribute to the empty string. The check is not performed on Windows platforms. |
buildDateWarningAgeDays |
The maximim number of days between the build-date of this instance of Tomcat and its startup date can be before warnings will be logged. Set to anything less than 0 (e.g. -1) to disable this check. If not specified, the default value of -1 is used. |
StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener
The StoreConfig Lifecycle Listener configures a StoreConfig MBean that may be used to save the current server configuration in server.xml or the current configuration for a web application in a context.xml file.
This listener must only be nested within Server elements.
The following additional attributes are supported by the StoreConfig Lifecycle Listener:
Attribute | Description |
---|---|
storeConfigClass |
The name of the |
storeRegistry |
The URL of the configuration file that configures how the
|
ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener
The ThreadLocal Leak Prevention Listener triggers the
renewal of threads in Executor pools when a
Context is being stopped to avoid thread-local
related memory leaks. Active threads will be renewed one by one when they
come back to the pool after executing their task. The renewal happens
only for contexts that have their renewThreadsWhenStoppingContext
attribute set to true
.
This listener must only be nested within Server elements.
No additional attributes are supported by the ThreadLocal Leak Prevention Listener.
TLS configuration reload listener - org.apache.catalina.security.TLSCertificateReloadListener
This listener may be used to monitor the expiration dates of TLS certificates and trigger automatic reloading of the TLS configuration a set number of days before the TLS certificate expires.
This listener assumes there is some other process (certbot, cloud infrastructure, etc) that renews the certificate on a regular basis and replaces the current certificate with the new one.
This listener does NOT re-read the Tomcat configuration from server.xml. If you make changes to server.xml you must restart the Tomcat process to pick up those changes.
This listener must only be nested within Server elements.
Attribute | Description |
---|---|
checkPeriod |
The time, in seconds, between reloading checks. The periodic process
for |
daysBefore |
The number of days before the expiry of a TLS certificate that it is expected that the new certificate will be in place and the reloading can be triggered. If not specified, a default of 14 days is used. |
UserConfig - org.apache.catalina.startup.UserConfig
The UserConfig provides feature of User Web Applications. User Web Applications map a request URI starting with a tilde character ("~") and a username to a directory (commonly named public_html) in that user's home directory on the server.
See the User Web Applications special feature on the Host element for more information.
The following additional attributes are supported by the UserConfig:
Attribute | Description |
---|---|
directoryName |
The directory name to be searched for within each user home directory.
The default is |
userClass |
The class name of the user database class.
There are currently two user database, the
|
homeBase |
The base directory containing user home directories. This is effective
only when |
allow |
A regular expression defining user who deployment is allowed. If this attribute is specified, the user to deploy must match for this pattern. If this attribute is not specified, all users will be deployed unless the user matches a deny pattern. |
deny |
A regular expression defining user who deployment is denied. If this attribute is specified, the user to deploy must not match for this pattern. If this attribute is not specified, deployment of user will be governed by a allow attribute. |
Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener
The Version Logging Lifecycle Listener logs Tomcat, Java and operating system information when Tomcat starts.
This listener must only be nested within Server elements and should be the first listener defined.
The following additional attributes are supported by the Version Logging Lifecycle Listener:
Attribute | Description |
---|---|
logArgs |
If |
logEnv |
If |
logProps |
If |
HTTPD mod_heartmonitor Listener - org.apache.catalina.ha.backend.HeartbeatListener
The HTTPD mod_heartmonitor Listener allows tomcat to send heart beat message to the Apache HTTPD mod_heartmonitor module.
The following additional attributes are supported by the HTTPD mod_heartmonitor Listener:
Attribute | Description |
---|---|
Port |
Port the connector that will received proxied traffic from HTTPD, default the first connector will be used |
Host |
Host it is the IP corresponding the address of the connector that will received proxied traffic, default empty the Port will be used |
proxyURL |
proxyURL is the URL corresponding to the Location in httpd configuration of the heartbeat Handler, default /HeartbeatListener |
ProxyList |
ProxyList is the list of proxies from which tomcat is going to receive requests, formatted like "address:port,address:port" once filled the multicast logic is disable and the multi parameters are ignored |
Group |
Group is the Multicast IP to broadcast messages to HTTPD, default 224.0.1.105 |
Multiport |
Multiport is the Multicast port to broadcast messages to HTTPD, default 23364 |
Ttl |
Ttl is the TTL for the broadcast messages, default 16 |