Google Git
Sign in
apache / tomcat / HEAD / . / webapps / docs / config / listeners.xml
blob: 8f7d9ce17f5eb234549a9627152ab131c63e2803 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="listeners.html">
&project;
<properties>
<title>The LifeCycle Listener Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Listener</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.LifecycleListener</code>
interface.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No element may be nested inside a <strong>Listener</strong>.</p>
</section>
<section name="Standard Implementations">
<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>
<subsection name="APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener">
<p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
the Apache Tomcat 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>
<attributes>
<attribute name="SSLEngine" required="false">
<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>
<p>Tomcat Native 2.x onwards requires SSL so if SSLEngine is set to
<code>off</code> when using Tomcat Native 2.x onwards, the APR/native
library will be disabled.</p>
</attribute>
<attribute name="SSLRandomSeed" required="false">
<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>
</attribute>
<attribute name="FIPSMode" required="false">
<p>The behaviour of this attribute depends on whether Tomcat Native has
been compiled against OpenSSL 1.x or OpenSSL 3.x.</p>
<p>For OpenSSL 1.x: 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>For OpenSSL 3.x: <code>on</code>, <code>enter</code> and
<code>require</code> all behave the same way. If the FIPS provider is
the default provider, it will be used. If the FIPS provider is not the
default provider, an error will occur.</p>
<p>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library</em>.
If this attribute is set to anything other than <code>off</code>, the
<b>SSLEngine</b> must be enabled as well.</p>
<p>The default value is <code>off</code>.</p>
</attribute>
<attribute name="useOpenSSL" required="false">
<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 connector is used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Context Naming Info Listener - org.apache.catalina.core.ContextNamingInfoListener">
<p>The <strong>Context Naming Info Listener</strong> adds the following
environment entries (<code>java:comp/env</code> implied) from the
<a href="context.html">Context</a>: <code>context/path</code>,
<code>context/encodedPath</code>, <code>context/webappVersion</code>,
<code>context/name</code>, <code>context/baseName</code>,
<code>context/displayName</code>.</p>
<p>This listener must only be nested within
<a href="context.html">Context</a> elements.</p>
<p>The following additional attributes are supported by the
<strong>Context Naming Info Listener</strong>:</p>
<attributes>
<attribute name="emptyOnRoot" required="false">
<p>Whether for the root context <code>context/path</code> and
<code>context/encodedPath</code> will contain <code>"/"</code> and
<code>context/name</code> will contain <code>"ROOT"</code> with a version,
if any.</p>
<p>The default value is <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">
<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>
</subsection>
<subsection name="JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener">
<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>
<attributes>
<attribute name="libraryName" required="false">
<p>The name of the native library, as defined in
<code>java.lang.System.loadLibrary()</code>
</p>
</attribute>
<attribute name="libraryPath" required="false">
<p>The absolute path of the native library, as defined in
<code>java.lang.System.load()</code>
</p>
</attribute>
</attributes>
</subsection>
<subsection name="JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener">
<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>
<attributes>
<attribute name="appContextProtection" required="false">
<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>.
</p>
</attribute>
<attribute name="classesToInitialize" required="false">
<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>
</attribute>
<attribute name="driverManagerProtection" required="false">
<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>
</attribute>
<attribute name="initSeedGenerator" required="false">
<p>The first use of <code>SeedGenerator</code>, an internal class of
the default security spi implementation, might create a thread on some
platforms. Depending on the timing of the first use of a secure random
this thread might become associated with a webapp classloader, causing
a memory leak. Setting this to <code>true</code> will initialize the
seed. The default is <code>false</code> to avoid consuming random if
not needed.</p>
</attribute>
<attribute name="urlCacheProtection" required="false">
<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>
</attribute>
</attributes>
<subsection name="JreMemoryLeakPreventionListener Examples">
<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>
<source><![CDATA[ <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" />]]></source>
<p>then the <code>OracleTimeoutThreadPerVM</code> class would be loaded
and initialized during listener startup instead of during request
processing.</p>
</subsection>
</subsection>
<subsection name="OpenSSL Lifecycle Listener - org.apache.catalina.core.OpenSSLLifecycleListener">
<p>The <strong>OpenSSL Lifecycle Listener</strong> 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, the NIO connector will then make use
of OpenSSL for TLS functionality. This is a functional replacement to the
<strong>APR Lifecycle Listener</strong> described above.</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>OpenSSL
Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="SSLEngine" required="false">
<p>Name of the SSLEngine to use, for OpenSSL 1.x.</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>
</attribute>
<attribute name="SSLRandomSeed" required="false">
<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>
</attribute>
<attribute name="FIPSMode" required="false">
<p>The behaviour of this attribute depends on whether Tomcat Native has
been compiled against OpenSSL 1.x or OpenSSL 3.x.</p>
<p>For OpenSSL 1.x: 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>For OpenSSL 3.x: <code>on</code>, <code>enter</code> and
<code>require</code> all behave the same way. If the FIPS provider is
the default provider, it will be used. If the FIPS provider is not the
default provider, an error will occur.</p>
<p>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library</em>.
If this attribute is set to anything other than <code>off</code>, the
<b>SSLEngine</b> must be enabled as well.</p>
<p>The default value is <code>off</code>.</p>
</attribute>
<attribute name="useOpenSSL" required="false">
<p>This attribute controls the auto-selection of the OpenSSL JSSE
implementation. The default is <code>true</code> which will use OpenSSL
if the FFM API is available.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Properties Role Mapping Listener - org.apache.catalina.core.PropertiesRoleMappingListener">
<p>The <strong>Properties Role Mapping Listener</strong> 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: <code>app-roles.</code>.</p>
<p>This listener must only be nested within
<a href="context.html">Context</a> elements.</p>
<p>The following additional attributes are supported by the
<strong>Properties Role Mapping Listener</strong>:</p>
<attributes>
<attribute name="roleMappingFile" required="false">
<p>The path to the role mapping properties file. You can use protocol <code>webapp:</code>
and whatever <code>ConfigFileLoader</code> supports.</p>
<p>The default value is <code>webapp:/WEB-INF/role-mapping.properties</code>.</p>
</attribute>
<attribute name="keyPrefix" required="false">
<p>The prefix to filter from property keys. All other keys will be ignored which do
not have the prefix.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Security Lifecycle Listener - org.apache.catalina.security.SecurityListener">
<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.</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>
<attributes>
<attribute name="checkedOsUsers" required="false">
<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>
</attribute>
<attribute name="minimumUmask" required="false">
<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>
</attribute>
<attribute name="buildDateWarningAgeDays" required="false">
<p>The maximum 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 <b>-1</b> is used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener">
<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>
<attributes>
<attribute name="storeConfigClass" required="false">
<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>
</attribute>
<attribute name="storeRegistry" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener">
<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>
</subsection>
<subsection name="TLS configuration reload listener - org.apache.catalina.security.TLSCertificateReloadListener">
<p>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.</p>
<p>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.</p>
<p>This listener does <b>NOT</b> 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.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<attributes>
<attribute name="checkPeriod" required="false">
<p>The time, in seconds, between reloading checks. The periodic process
for <code>LifecycleListener</code> typically runs much more frequently
than this listener requires. This attribute controls the period between
checks. If not specified, a default of 86,400 seconds (24 hours) is
used.</p>
</attribute>
<attribute name="daysBefore" required="false">
<p>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.</p>
</attribute>
</attributes>
</subsection>
<subsection name="UserConfig - org.apache.catalina.startup.UserConfig">
<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>
<attributes>
<attribute name="directoryName" required="false">
<p>The directory name to be searched for within each user home directory.
The default is <code>public_html</code>.</p>
</attribute>
<attribute name="userClass" required="false">
<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>
</attribute>
<attribute name="homeBase" required="false">
<p>The base directory containing user home directories. This is effective
only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is
used.</p>
</attribute>
<attribute name="allow" required="false">
<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>
</attribute>
<attribute name="deny" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener">
<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>
<attributes>
<attribute name="logArgs" required="false">
<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>
</attribute>
<attribute name="logEnv" required="false">
<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>
</attribute>
<attribute name="logProps" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="HTTPD mod_heartmonitor Listener - org.apache.catalina.ha.backend.HeartbeatListener">
<p>The <strong>HTTPD mod_heartmonitor Listener</strong> allows tomcat to send heart beat message to
the Apache HTTPD mod_heartmonitor module.</p>
<p>The following additional attributes are supported by the <strong>HTTPD mod_heartmonitor
Listener</strong>:</p>
<attributes>
<attribute name="Port" required="false">
<p>Port the connector that will received proxied traffic from HTTPD, default the first connector will be used</p>
</attribute>
<attribute name="Host" required="false">
<p>Host it is the IP corresponding the <strong>address</strong> of the connector that will received proxied traffic,
default empty the <strong>Port</strong> will be used</p>
</attribute>
<attribute name="proxyURL" required="false">
<p>proxyURL is the URL corresponding to the <strong>Location</strong> in httpd configuration of the heartbeat Handler,
default /HeartbeatListener</p>
</attribute>
<attribute name="ProxyList" required="false">
<p>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</p>
</attribute>
<attribute name="Group" required="false">
<p>Group is the Multicast IP to broadcast messages to HTTPD, default 224.0.1.105</p>
</attribute>
<attribute name="Multiport" required="false">
<p>Multiport is the Multicast port to broadcast messages to HTTPD, default 23364</p>
</attribute>
<attribute name="Ttl" required="false">
<p>Ttl is the TTL for the broadcast messages, default 16</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>