<!DOCTYPE html SYSTEM "about:legacy-compat">
|
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 8 Configuration Reference (8.5.73) - The LifeCycle Listener Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 8 Configuration Reference</h1><div class="versionInfo">
|
Version 8.5.73,
|
<time datetime="2021-11-11">Nov 11 2021</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The LifeCycle Listener Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Standard_Implementations">Standard Implementations</a><ol><li><a href="#APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener</a></li><li><a href="#Global_Resources_Lifecycle_Listener_-_org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener</a></li><li><a href="#JNI_Library_Loading_Listener_-_org.apache.catalina.core.JniLifecycleListener">JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener</a></li><li><a href="#JRE_Memory_Leak_Prevention_Listener_-_org.apache.catalina.core.JreMemoryLeakPreventionListener">JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener</a><ol><li><a href="#JreMemoryLeakPreventionListener_Examples">JreMemoryLeakPreventionListener Examples</a></li></ol></li><li><a href="#Security_Lifecycle_Listener_-_org.apache.catalina.security.SecurityListener">Security Lifecycle Listener - org.apache.catalina.security.SecurityListener</a></li><li><a href="#StoreConfig_Lifecycle_Listener_-_org.apache.catalina.storeconfig.StoreConfigLifecycleListener">StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener</a></li><li><a href="#ThreadLocal_Leak_Prevention_Listener_-_org.apache.catalina.core.ThreadLocalLeakPreventionListener">ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener</a></li><li><a href="#UserConfig_-_org.apache.catalina.startup.UserConfig">UserConfig - org.apache.catalina.startup.UserConfig</a></li><li><a href="#Version_Logging_Lifecycle_Listener_-_org.apache.catalina.startup.VersionLoggerListener">Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener</a></li></ol></li><li><a href="#Additional_Implementations">Additional Implementations</a><ol><li><a href="#System_property_replacement_-_org.apache.catalina.util.SystemPropertyReplacerListener">System property replacement - org.apache.catalina.util.SystemPropertyReplacerListener</a></li></ol></li><li><a href="#Deprecated_Implementations">Deprecated Implementations</a><ol><li><a href="#JMX_Remote_Lifecycle_Listener_-_org.apache.catalina.mbeans.JmxRemoteLifecycleListener">JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener</a></li></ol></li></ul>
|
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
|
<p>A <strong>Listener</strong> element defines a component that performs
|
actions when specific events occur, usually Tomcat starting or Tomcat
|
stopping.</p>
|
|
<p>Listeners may be nested inside a <a href="server.html">Server</a>,
|
<a href="engine.html">Engine</a>, <a href="host.html">Host</a> or
|
<a href="context.html">Context</a>. Some Listeners are only intended to be
|
nested inside specific elements. These constraints are noted in the
|
documentation below.</p>
|
|
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
|
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
|
<p>All implementations of <strong>Listener</strong>
|
support the following attributes:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
<p>Java class name of the implementation to use. This class must
|
implement the <code>org.apache.catalina.LifecycleListener</code>
|
interface.</p>
|
</td></tr></table>
|
|
</div></div>
|
|
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
|
<p>No element may be nested inside a <strong>Listener</strong>.</p>
|
|
</div><h3 id="Standard_Implementations">Standard Implementations</h3><div class="text">
|
|
<p>Unlike most Catalina components, there are several standard
|
<strong>Listener</strong> implementations available. As a result,
|
the <code>className</code> attribute MUST be used to select the
|
implementation you wish to use.</p>
|
|
<div class="subsection"><h4 id="APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener</h4><div class="text">
|
|
<p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
|
the APR/native library and loads the library if it is present. For more
|
information see the <a href="../apr.html">APR/native guide</a>.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements.</p>
|
|
<p>The following additional attributes are supported by the <strong>APR
|
Lifecycle Listener</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">SSLEngine</code></td><td>
|
<p>Name of the SSLEngine to use. <code>off</code>: do not use SSL,
|
<code>on</code>: use SSL but no specific ENGINE.</p>
|
<p>The default value is <b>on</b>. This initializes the
|
native SSL engine, which must be enabled in the APR/native connector by
|
the use of the <code>SSLEnabled</code> attribute.</p>
|
<p>See the <a href="http://www.openssl.org/">Official OpenSSL website</a>
|
for more details on supported SSL hardware engines and manufacturers.
|
</p>
|
</td></tr><tr><td><code class="attributeName">SSLRandomSeed</code></td><td>
|
<p>Entropy source used to seed the SSLEngine's PRNG. The default value
|
is <code>builtin</code>. On development systems, you may want to set
|
this to <code>/dev/urandom</code> to allow quicker start times.</p>
|
</td></tr><tr><td><code class="attributeName">FIPSMode</code></td><td>
|
<p>Set to <code>on</code> to request that OpenSSL be in FIPS mode
|
(if OpenSSL is already in FIPS mode, it will remain in FIPS mode).
|
Set to <code>enter</code> to force OpenSSL to enter FIPS mode (an error
|
will occur if OpenSSL is already in FIPS mode).
|
Set to <code>require</code> to require that OpenSSL <i>already</i> be
|
in FIPS mode (an error will occur if OpenSSL is not already in FIPS
|
mode).</p>
|
<p>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library which
|
you must build yourself</em>.
|
If this attribute is set to any of the above values, the <b>SSLEngine</b>
|
must be enabled as well.</p>
|
<p>The default value is <code>off</code>.</p>
|
</td></tr><tr><td><code class="attributeName">useAprConnector</code></td><td>
|
<p>This attribute controls the auto-selection of the connector
|
implementation. When the <strong>protocol</strong> is specified as
|
<code>HTTP/1.1</code> or <code>AJP/1.3</code> then if this attribute is
|
<code>true</code> the APR/native connector will be used but if this
|
attribute is false the NIO connector will be used.</p>
|
</td></tr><tr><td><code class="attributeName">useOpenSSL</code></td><td>
|
<p>This attribute controls the auto-selection of the OpenSSL JSSE
|
implementation. The default is <code>true</code> which will use OpenSSL
|
if the native library is available and a NIO or NIO2 connector is used.</p>
|
</td></tr></table>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="Global_Resources_Lifecycle_Listener_-_org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener</h4><div class="text">
|
|
<p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
|
Global JNDI resources defined in server.xml as part of the <a href="globalresources.html">Global Resources</a> element. Without this
|
listener, none of the Global Resources will be available.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements.</p>
|
|
<p>No additional attributes are supported by the <strong>Global Resources
|
Lifecycle Listener</strong>.</p>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="JNI_Library_Loading_Listener_-_org.apache.catalina.core.JniLifecycleListener">JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener</h4><div class="text">
|
|
<p>The <strong>JNI Library Loading Listener</strong> 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)</p>
|
|
<p>The listener supports two mutually exclusive attributes, so one of them must be used, but you can not use both together:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">libraryName</code></td><td>
|
<p>The name of the native library, as defined in
|
<code>java.lang.System.loadLibrary()</code>
|
</p>
|
</td></tr><tr><td><code class="attributeName">libraryPath</code></td><td>
|
<p>The absolute path of the native library, as defined in
|
<code>java.lang.System.load()</code>
|
</p>
|
</td></tr></table>
|
</div></div>
|
|
<div class="subsection"><h4 id="JRE_Memory_Leak_Prevention_Listener_-_org.apache.catalina.core.JreMemoryLeakPreventionListener">JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener</h4><div class="text">
|
|
<p>The <strong>JRE Memory Leak Prevention Listener</strong> 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.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements.</p>
|
|
<p>The following additional attributes are supported by the <strong>JRE
|
Memory Leak Prevention Listener</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">appContextProtection</code></td><td>
|
<p>Enables protection so that calls to
|
<code>sun.awt.AppContext.getAppContext()</code> 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 <code>false</code>.
|
This protection is disabled if running on Java 8 onwards since the leak
|
has been fixed for Java 8 onwards.
|
</p>
|
</td></tr><tr><td><code class="attributeName">AWTThreadProtection</code></td><td>
|
<p>Enables protection so that calls to
|
<code>java.awt.Toolkit.getDefaultToolkit()</code> triggered by a web
|
application do not result in a memory leak.
|
Defaults to <code>false</code> 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.</p>
|
</td></tr><tr><td><code class="attributeName">classesToInitialize</code></td><td>
|
<p>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
|
<code>oracle.jdbc.driver.OracleTimeoutThreadPerVM</code>.
|
The default value is empty, but specific JRE classes are loaded by other leak
|
protection features managed by other attributes of this Listener.</p>
|
</td></tr><tr><td><code class="attributeName">driverManagerProtection</code></td><td>
|
<p>The first use of <code>java.sql.DriverManager</code> 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 <code>true</code>.</p>
|
</td></tr><tr><td><code class="attributeName">forkJoinCommonPoolProtection</code></td><td>
|
<p>Enables protection so the threads created for
|
<code>ForkJoinPool.commonPool()</code> do not result in a memory leak.
|
The protection is enabled by setting the
|
<code>java.util.concurrent.ForkJoinPool.common.threadFactory</code>
|
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 <code>true</code>. This protection is only used when running
|
on Java 8. The common pool does not exist in earlier versions and the
|
leak has been fixed for Java 9 onwards.</p>
|
</td></tr><tr><td><code class="attributeName">gcDaemonProtection</code></td><td>
|
<p>Enables protection so that calls to
|
<code>sun.misc.GC.requestLatency(long)</code> 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 <code>true</code>. This
|
protection is disabled if running on Java 9 onwards since the leak has
|
been fixed for Java 9 onwards.</p>
|
</td></tr><tr><td><code class="attributeName">ldapPoolProtection</code></td><td>
|
<p>Enables protection so that the PoolCleaner thread started by
|
<code>com.sun.jndi.ldap.LdapPoolManager</code> does not result in a
|
memory leak. The thread is started the first time the
|
<code>LdapPoolManager</code> class is used if the system property
|
<code>com.sun.jndi.ldap.connect.pool.timeout</code> 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
|
<code>true</code>. This protection is disabled if running on Java 9
|
onwards since the leak has been fixed for Java 9 onwards.</p>
|
</td></tr><tr><td><code class="attributeName">securityLoginConfigurationProtection</code></td><td>
|
<p>Enables protection so that usage of the
|
<code>javax.security.auth.login.Configuration</code> class by a web
|
application does not provoke a memory leak. The first access of this
|
class will trigger the initializer that will retain a static reference
|
to the context class loader. The protection loads the class with the
|
system class loader to ensure that the static initializer is not
|
triggered by a web application. Defaults to <code>true</code>. This
|
protection is disabled if running on Java 8 onwards since the leak has
|
been fixed for Java 8 onwards.</p>
|
</td></tr><tr><td><code class="attributeName">securityPolicyProtection</code></td><td>
|
<p>Enables protection so that usage of the deprecated
|
<code>javax.security.auth.Policy</code> class by a web application does
|
not result in a memory leak. The first access of this class will trigger
|
the static initializer that will retain a static reference to the
|
context class loader. The protection calls the <code>getPolicy()</code>
|
method of this class to ensure that the static initializer is not
|
triggered by a web application. Defaults to <code>true</code>.</p>
|
<p>Note: The underlying leak has been fixed in Java 7 update 51 onwards
|
and Java 8 onwards. This protection is therefor disabled if running on
|
Java 8 onwards.</p>
|
</td></tr><tr><td><code class="attributeName">tokenPollerProtection</code></td><td>
|
<p>Enables protection so that any token poller thread initialized by
|
<code>sun.security.pkcs11.SunPKCS11.initToken()</code> 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 <code>true</code>. This
|
protection is disabled if running on Java 9 onwards since the leak has
|
been fixed for Java 9 onwards.</p>
|
</td></tr><tr><td><code class="attributeName">urlCacheProtection</code></td><td>
|
<p>Enables protection so that reading resources from JAR files using
|
<code>java.net.URLConnection</code>s does not result in the JAR file
|
being locked. Note that enabling this protection disables caching by
|
default for all resources obtained via
|
<code>java.net.URLConnection</code>s. Caching may be re-enabled on a
|
case by case basis as required. Defaults to <code>true</code>.</p>
|
</td></tr><tr><td><code class="attributeName">xmlParsingProtection</code></td><td>
|
<p>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 <code>true</code>. This protection is
|
disabled if running on Java 9 onwards since the leak has been fixed for
|
Java 9 onwards.</p>
|
</td></tr></table>
|
|
<div class="subsection"><h4 id="JreMemoryLeakPreventionListener_Examples">JreMemoryLeakPreventionListener Examples</h4><div class="text">
|
|
<p>The following is an example of how to configure the
|
<code>classesToInitialize</code> attribute of this listener.</p>
|
|
<p>If this listener was configured in server.xml as:</p>
|
|
<div class="codeBox"><pre><code> <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
|
classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" /></code></pre></div>
|
|
<p>then the <code>OracleTimeoutThreadPerVM</code> class would be loaded
|
and initialized during listener startup instead of during request
|
processing.</p>
|
|
</div></div>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="Security_Lifecycle_Listener_-_org.apache.catalina.security.SecurityListener">Security Lifecycle Listener - org.apache.catalina.security.SecurityListener</h4><div class="text">
|
|
<p>The <strong>Security Lifecycle Listener</strong> 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 8.5.30,
|
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 8.5.30 and later, the umask is automatically
|
passed-into Tomcat.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements.</p>
|
|
<p>The following additional attributes are supported by the <strong>Security
|
Lifecycle Listener</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">checkedOsUsers</code></td><td>
|
<p>A comma separated list of OS users that must not be used to start
|
Tomcat. If not specified, the default value of <b>root</b> is used. To
|
disable this check, set the attribute to the empty string. Usernames
|
are checked in a case-insensitive manner.</p>
|
</td></tr><tr><td><code class="attributeName">minimumUmask</code></td><td>
|
<p>The least restrictive umask that must be configured before Tomcat
|
will start. If not specified, the default value of <b>0007</b> is used.
|
To disable this check, set the attribute to the empty string. The check
|
is not performed on Windows platforms.</p>
|
</td></tr></table>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="StoreConfig_Lifecycle_Listener_-_org.apache.catalina.storeconfig.StoreConfigLifecycleListener">StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener</h4><div class="text">
|
|
<p>The <strong>StoreConfig Lifecycle Listener</strong> 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.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements.</p>
|
|
<p>The following additional attributes are supported by the
|
<strong>StoreConfig Lifecycle Listener</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">storeConfigClass</code></td><td>
|
<p>The name of the <code>IStoreConfig</code> implementation to use. If
|
not specified the default of
|
<code>org.apache.catalina.storeconfig.StoreConfig</code> will be
|
used.</p>
|
</td></tr><tr><td><code class="attributeName">storeRegistry</code></td><td>
|
<p>The URL of the configuration file that configures how the
|
<code>IStoreConfig</code> is to save the configuration. If not specified
|
the built in resource
|
<code>/org/apache/catalina/storeconfig/server-registry.xml</code> will
|
be used.</p>
|
</td></tr></table>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="ThreadLocal_Leak_Prevention_Listener_-_org.apache.catalina.core.ThreadLocalLeakPreventionListener">ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener</h4><div class="text">
|
|
<p>The <strong>ThreadLocal Leak Prevention Listener</strong> triggers the
|
renewal of threads in <a href="executor.html">Executor</a> pools when a
|
<a href="context.html">Context</a> 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 <code>renewThreadsWhenStoppingContext</code>
|
attribute set to <code>true</code>.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements.</p>
|
|
<p>No additional attributes are supported by the <strong>ThreadLocal Leak
|
Prevention Listener</strong>.</p>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="UserConfig_-_org.apache.catalina.startup.UserConfig">UserConfig - org.apache.catalina.startup.UserConfig</h4><div class="text">
|
|
<p>The <strong>UserConfig</strong> 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.</p>
|
|
<p>See the <a href="host.html#User_Web_Applications">User Web Applications</a>
|
special feature on the <strong>Host</strong> element for more information.</p>
|
|
<p>The following additional attributes are supported by the
|
<strong>UserConfig</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">directoryName</code></td><td>
|
<p>The directory name to be searched for within each user home directory.
|
The default is <code>public_html</code>.</p>
|
</td></tr><tr><td><code class="attributeName">userClass</code></td><td>
|
<p>The class name of the user database class.
|
There are currently two user database, the
|
<code>org.apache.catalina.startup.PasswdUserDatabase</code> is used on a
|
Unix system that uses the /etc/passwd file to identify valid users.
|
The <code>org.apache.catalina.startup.HomesUserDatabase</code> is used on
|
a server where /etc/passwd is not in use. HomesUserDatabase deploy all
|
directories found in a specified base directory.</p>
|
</td></tr><tr><td><code class="attributeName">homeBase</code></td><td>
|
<p>The base directory containing user home directories. This is effective
|
only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is
|
used.</p>
|
</td></tr><tr><td><code class="attributeName">allow</code></td><td>
|
<p>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.</p>
|
</td></tr><tr><td><code class="attributeName">deny</code></td><td>
|
<p>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.</p>
|
</td></tr></table>
|
|
</div></div>
|
|
<div class="subsection"><h4 id="Version_Logging_Lifecycle_Listener_-_org.apache.catalina.startup.VersionLoggerListener">Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener</h4><div class="text">
|
|
<p>The <strong>Version Logging Lifecycle Listener</strong> logs Tomcat, Java
|
and operating system information when Tomcat starts.</p>
|
|
<p>This listener must only be nested within <a href="server.html">Server</a>
|
elements and should be the first listener defined.</p>
|
|
<p>The following additional attributes are supported by the <strong>Version
|
Logging Lifecycle Listener</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><code class="attributeName">logArgs</code></td><td>
|
<p>If <code>true</code>, the command line arguments passed to Java when
|
Tomcat started will be logged. If not specified, the default value of
|
<code>true</code> will be used.</p>
|
</td></tr><tr><td><code class="attributeName">logEnv</code></td><td>
|
<p>If <code>true</code>, the current environment variables when Tomcat
|
starts will be logged. If not specified, the default value of
|
<code>false</code> will be used.</p>
|
</td></tr><tr><td><code class="attributeName">logProps</code></td><td>
|
<p>If <code>true</code>, the current Java system properties will be
|
logged. If not specified, the default value of
|
<code>false</code> will be used.</p>
|
</td></tr></table>
|
|
</div></div>
|
|
</div><h3 id="Additional_Implementations">Additional Implementations</h3><div class="text">
|
|
<div class="subsection"><h4 id="System_property_replacement_-_org.apache.catalina.util.SystemPropertyReplacerListener">System property replacement - org.apache.catalina.util.SystemPropertyReplacerListener</h4><div class="text">
|
|
<p>This listener performs system property replacement using the property
|
source configured on the digester. When <code>${parameter}</code>
|
denoted parameters are found in the values of system properties,
|
the property source will be invoked to attempt to replace it.</p>
|
|
</div></div>
|
|
</div><h3 id="Deprecated_Implementations">Deprecated Implementations</h3><div class="text">
|
|
<div class="subsection"><h4 id="JMX_Remote_Lifecycle_Listener_-_org.apache.catalina.mbeans.JmxRemoteLifecycleListener">JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener</h4><div class="text">
|
|
<p><strong>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 8 some
|
time after 2020-12-31.</strong></p>
|
|
<p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
|
in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
|
directory of the binary download area.</p>
|
|
<p>The <strong>JMX Remote Lifecycle Listener</strong> 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
|
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html">
|
Monitoring and Management Using JMX</a> included with the Java SDK
|
documentation.</p>
|
|
<p>This listener must only be nested within a <a href="server.html">Server</a>
|
element.</p>
|
|
<p>The following additional attributes are supported by the <strong>JMX Remote
|
Lifecycle Listener</strong>:</p>
|
|
<table class="defaultTable"><tr><th style="width: 15%;">
|
Attribute
|
</th><th style="width: 85%;">
|
Description
|
</th></tr><tr><td><strong><code class="attributeName">rmiRegistryPortPlatform</code></strong></td><td>
|
<p>The port to be used by the JMX/RMI registry for the Platform MBeans.
|
This replaces the use of the
|
<code>com.sun.management.jmxremote.port</code> system property that
|
should not be set when using this listener.</p>
|
</td></tr><tr><td><strong><code class="attributeName">rmiServerPortPlatform</code></strong></td><td>
|
<p>The port to be used by the Platform JMX/RMI server.</p>
|
</td></tr><tr><td><code class="attributeName">rmiBindAddress</code></td><td>
|
<p>The address of the interface to be used by JMX/RMI server.</p>
|
</td></tr><tr><td><code class="attributeName">useLocalPorts</code></td><td>
|
<p>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 <code>false</code>.</p>
|
</td></tr></table>
|
|
<h3>Using file-based Authentication and Authorisation</h3>
|
|
<p>If this listener was configured in server.xml as:</p>
|
<div class="codeBox"><pre><code> <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
|
rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /></code></pre></div>
|
<p>with the following system properties set (e.g. in setenv.sh):</p>
|
<div class="codeBox"><pre><code> -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</code></pre></div>
|
<p>$CATALINA_BASE/conf/jmxremote.password containing:</p>
|
<div class="codeBox"><pre><code>admin letmein</code></pre></div>
|
<p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
|
<div class="codeBox"><pre><code>admin readwrite</code></pre></div>
|
<p>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:</p>
|
<div class="codeBox"><pre><code>service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi</code></pre></div>
|
<p>
|
with a user name of <code>admin</code> and a password of
|
<code>letmein</code>.
|
</p>
|
|
<h3>Using JAAS</h3>
|
|
<p>If we use the following system properties instead:</p>
|
<div class="codeBox"><pre><code> -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</code></pre></div>
|
<p>$CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:</p>
|
<div class="codeBox"><pre><code> 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;
|
};</code></pre></div>
|
<p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
|
<div class="codeBox"><pre><code>admin readwrite</code></pre></div>
|
<p>
|
then we would need to provide LDAP credentials instead.
|
</p>
|
|
<p><strong>Note that the examples above do not use SSL. JMX access should
|
be considered equivalent to administrative access and secured accordingly.
|
</strong></p>
|
|
</div></div>
|
|
</div></div></div></div></div><footer><div id="footer">
|
Copyright © 1999-2021, The Apache Software Foundation
|
</div></footer></div></body></html>
|
