- Introduction
- Attributes
- Nested Components
- Standard Implementations
- APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener
- Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener
- JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener
- Security Lifecycle Listener - org.apache.catalina.security.SecurityListener
- ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener
- UserConfig - org.apache.catalina.startup.UserConfig
- Additional Implementations
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 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. 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. |
SSLRandomSeed |
Entropy source used to seed the SSLEngine's PRNG. The default value
is |
FIPSMode |
Set to |
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.
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
|
AWTThreadProtection |
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 |
gcDaemonProtection |
Enables protection so that calls to
|
java2DDisposerProtection |
Enables protection so that loading the
|
ldapPoolProtection |
Enables protection so that the PoolCleaner thread started by
|
securityLoginConfigurationProtection |
Enables protection so that usage of the
|
securityPolicyProtection |
Enables protection so that usage of the deprecated
|
tokenPollerProtection |
Enables protection so that any token poller thread initialized by
|
urlCacheProtection |
Enables protection so that reading resources from JAR files using
|
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 |
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. If the operating system supports umask then the line in $CATALINA_HOME/bin/catalina.sh that obtains the umask also needs to be uncommented.
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. |
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.
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 |
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. |
Additional Implementations
JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener
This listener requires catalina-jmx-remote.jar
to be placed
in $CATALINA_HOME/lib
. This jar may be found in the extras
directory of the binary download area.
The JMX Remote Lifecycle Listener fixes the ports used by the JMX/RMI Server making things much simpler if you need to connect jconsole or a similar tool to a remote Tomcat instance that is running behind a firewall. Only these ports are configured via the listener. The remainder of the configuration is 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:
Attribute | Description |
---|---|
rmiRegistryPortPlatform |
The port to be used by the JMX/RMI registry for the Platform MBeans.
This replaces the use of the
|
rmiServerPortPlatform |
The port to be used by the Platform JMX/RMI server. |
rmiBindAddress |
The address of the interface to be used by JMX/RMI server.
This option is incompatible with setting the system
property |
useLocalPorts |
Should any clients using these ports be forced to use local ports to
connect to the the JMX/RMI server. This is useful when tunnelling
connections over SSH or similar. Defaults to |
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
.
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.