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 org.apache.catalina.LifecycleListener interface.

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 APR/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. off: do not use SSL, on: use SSL but no specific ENGINE.

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 SSLEnabled attribute.

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 builtin. On development systems, you may want to set this to /dev/urandom to allow quicker start times.

FIPSMode

Set to on to request that OpenSSL be in FIPS mode (if OpenSSL is already in FIPS mode, it will remain in FIPS mode). Set to enter to force OpenSSL to enter FIPS mode (an error will occur if OpenSSL is already in FIPS mode). Set to require to require that OpenSSL already be in FIPS mode (an error will occur if OpenSSL is not already in FIPS mode).

FIPS mode requires you to have a FIPS-capable OpenSSL library which you must build yourself. If this attribute is set to any of the above values, the SSLEngine must be enabled as well.

The default value is off.

useAprConnector

This attribute controls the auto-selection of the connector implementation. When the protocol is specified as HTTP/1.1 or AJP/1.3 then if this attribute is true the APR/native connector will be used but if this attribute is false the NIO connector will be used.

useOpenSSL

This attribute controls the auto-selection of the OpenSSL JSSE implementation. The default is true which will use OpenSSL if the native library is available and a NIO or NIO2 connector is used.

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 java.lang.System.loadLibrary()

libraryPath

The absolute path of the native library, as defined in java.lang.System.load()

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 sun.awt.AppContext.getAppContext() triggered by a web application do not result in a memory leak. Note that enabling this protection will trigger a requirement for a graphical environment unless Java is started in head-less mode. The default is false.

AWTThreadProtection

Enables protection so that calls to java.awt.Toolkit.getDefaultToolkit() triggered by a web application do not result in a memory leak. Defaults to false because an AWT thread is launched. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

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 oracle.jdbc.driver.OracleTimeoutThreadPerVM. The default value is empty, but specific JRE classes are loaded by other leak protection features managed by other attributes of this Listener.

driverManagerProtection

The first use of java.sql.DriverManager will trigger the loading of JDBC Drivers visible to the current class loader and its parents. The web application level memory leak protection can take care of this in most cases but triggering the loading here has fewer side-effects. The default is true.

forkJoinCommonPoolProtection

Enables protection so the threads created for ForkJoinPool.commonPool() do not result in a memory leak. The protection is enabled by setting the java.util.concurrent.ForkJoinPool.common.threadFactory system property. If this property is set when Tomcat starts, Tomcat will not over-ride it even if this protection is explicitly enabled. The default is true. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

gcDaemonProtection

Enables protection so that calls to sun.misc.GC.requestLatency(long) triggered by a web application do not result in a memory leak. Use of RMI is likely to trigger a call to this method. A side effect of enabling this protection is the creation of a thread named "GC Daemon". The protection uses reflection to access internal Sun classes and may generate errors on startup on non-Sun JVMs. The default is true. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

ldapPoolProtection

Enables protection so that the PoolCleaner thread started by com.sun.jndi.ldap.LdapPoolManager does not result in a memory leak. The thread is started the first time the LdapPoolManager class is used if the system property com.sun.jndi.ldap.connect.pool.timeout is set to a value greater than 0. Without this protection, if a web application uses this class the PoolCleaner thread will be configured with the thread's context class loader set to the web application class loader which in turn will trigger a memory leak on reload. Defaults to true. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

tokenPollerProtection

Enables protection so that any token poller thread initialized by sun.security.pkcs11.SunPKCS11.initToken() does not result in a memory leak. The thread is started depending on various conditions as part of the initialization of the Java Cryptography Architecture. Without the protection this can happen during Webapp deployment when the MessageDigest for generating session IDs is initialized. As a result the thread has the Webapp class loader as its thread context class loader. Enabling the protection initializes JCA early during Tomcat startup. Defaults to true. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

urlCacheProtection

Enables protection so that reading resources from JAR files using java.net.URLConnections does not result in the JAR file being locked. Note that enabling this protection disables caching by default for all resources obtained via java.net.URLConnections. Caching may be re-enabled on a case by case basis as required. Defaults to true.

xmlParsingProtection

Enables protection so that parsing XML files within a web application does not result in a memory leak. Note that memory profilers may not display the GC root associated with this leak making it particularly hard to diagnose. Defaults to true. This protection is disabled if running on Java 9 onwards since the leak has been fixed for Java 9 onwards.

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.

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. For Tomcat versions before 9.0.7, if the operating system supports umask then the line in $CATALINA_HOME/bin/catalina.sh that obtains the umask also needs to be uncommented. For Tomcat 9.0.7 and later, the umask is automatically passed-into Tomcat.

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.

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 IStoreConfig implementation to use. If not specified the default of org.apache.catalina.storeconfig.StoreConfig will be used.

storeRegistry

The URL of the configuration file that configures how the IStoreConfig is to save the configuration. If not specified the built in resource /org/apache/catalina/storeconfig/server-registry.xml will be used.

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.

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 public_html.

userClass

The class name of the user database class. There are currently two user database, the org.apache.catalina.startup.PasswdUserDatabase is used on a Unix system that uses the /etc/passwd file to identify valid users. The org.apache.catalina.startup.HomesUserDatabase is used on a server where /etc/passwd is not in use. HomesUserDatabase deploy all directories found in a specified base directory.

homeBase

The base directory containing user home directories. This is effective only when org.apache.catalina.startup.HomesUserDatabase is used.

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 true, the command line arguments passed to Java when Tomcat started will be logged. If not specified, the default value of true will be used.

logEnv

If true, the current environment variables when Tomcat starts will be logged. If not specified, the default value of false will be used.

logProps

If true, the current Java system properties will be logged. If not specified, the default value of false will be used.

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 boardcast messages to HTTPD, default 224.0.1.105

Multiport

Multiport is the Multicast port to boardcast messages to HTTPD, default 23364

Ttl

Ttl is the TTL for the boardcast messages, default 16

Deprecated Implementations

JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener

This listener is now deprecated as the features it provides are now available in the remote JMX capability included with the JRE. This listener will be removed in Tomcat 10 and may be removed from Tomcat 9 some time after 2020-12-31.

The JMX Remote Lifecycle Listener fixes the ports used by the JMX/RMI Server making things much simpler if you need to connect visualvm or a similar tool to a remote Tomcat instance that is running behind a firewall.

The remainder of the configuration can be done via the standard system properties for configuring JMX. For further information on configuring JMX see Monitoring and Management Using JMX included with the Java SDK documentation.

This listener must only be nested within a Server element.

The following additional attributes are supported by the JMX Remote Lifecycle Listener, in addition to the SSL related attributes noted below in the "SSL Configurations" section:

Attribute Description
accessFile

Defines the access file used. The attribute will be set to the value of the com.sun.management.jmxremote.access.file system property if it is defined.

authenticate

Defines if authentication is used. Defaults to true. The attribute will be set to the value of the com.sun.management.jmxremote.authenticate system property if it is defined.

loginModuleName

Defines the login module used. The attribute will be set to the value of the com.sun.management.jmxremote.login.config system property if it is defined.

passwordFile

Defines the password file used. The attribute will be set to the value of the com.sun.management.jmxremote.password.file system property if it is defined.

rmiBindAddress

The address of the interface to be used by JMX/RMI server.

rmiRegistryPortPlatform

The port to be used by the JMX/RMI registry for the Platform MBeans. This replaces the use of the com.sun.management.jmxremote.port system property that should not be set when using this listener.

rmiRegistrySSL

Defines if the RMI registry will use SSL. Defaults to true. The attribute will be set to the value of the com.sun.management.jmxremote.registry.ssl system property if it is defined.

rmiServerPortPlatform

The port to be used by the Platform JMX/RMI server.

rmiServerSSL

Defines if the JMX remote server will use SSL. Defaults to true. The attribute will be set to the value of the com.sun.management.jmxremote.ssl system property if it is defined.

useLocalPorts

Should any clients using these ports be forced to use local ports to connect to the JMX/RMI server. This is useful when tunnelling connections over SSH or similar. Defaults to false.

Using file-based Authentication and Authorisation

If this listener was configured in server.xml as:

  <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />

with the following system properties set (e.g. in setenv.sh):

  -Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
  -Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
  -Dcom.sun.management.jmxremote.ssl=false

$CATALINA_BASE/conf/jmxremote.password containing:

admin letmein

$CATALINA_BASE/conf/jmxremote.access containing:

admin readwrite

then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your firewall would enable jconsole to connect to a Tomcat instance running behind a firewall using a connection string of the form:

service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi

with a user name of admin and a password of letmein.

SSL Configurations

Note: SSL configuration can be done with attributes identical to those of SSLHostConfig and the properties of the default certificate as defined for SSLHostConfigCertificate. This will create a JSSE SSLContext which will be given to the JMX/RMI registry when creating the server socket. OpenSSL specific attributes cannot be used in the configuration as JMX remote can only use a regular SSLContext.

A certificate can be defined for the server using a keystore:

  <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
               rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002"
               certificateKeystoreFile="${catalina.home}/conf/mykeystore.jks" />

Using JAAS

If we use the following system properties instead:

  -Dcom.sun.management.jmxremote.login.config=Tomcat
  -Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
  -Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
  -Dcom.sun.management.jmxremote.ssl=false

$CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:

  Tomcat { /* should match to the com.sun.management.jmxremote.login.config property */

    /* for illustration purposes only */
    com.sun.security.auth.module.LdapLoginModule REQUIRED
      userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
      userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
      authzIdentity="admin"
      debug=true;
  };

$CATALINA_BASE/conf/jmxremote.access containing:

admin readwrite

then we would need to provide LDAP credentials instead.

Note that the examples above do not use SSL. JMX access should be considered equivalent to administrative access and secured accordingly.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.