<?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 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>

    <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>
      </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>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>
      </attribute>

      <attribute name="useAprConnector" required="false">
        <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>
      </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 or NIO2 connector is used.</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="AWTThreadProtection" required="false">
        <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>
      </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="forkJoinCommonPoolProtection" required="false">
        <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 disabled if running on
        Java 9 onwards since the leak has been fixed for Java 9 onwards.</p>
      </attribute>

      <attribute name="gcDaemonProtection" required="false">
        <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>
      </attribute>

      <attribute name="ldapPoolProtection" required="false">
        <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>
      </attribute>

      <attribute name="tokenPollerProtection" required="false">
        <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>
      </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>

      <attribute name="xmlParsingProtection" required="false">
        <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>
      </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="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. 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.</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>

    </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="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>

<section name="Deprecated Implementations">

  <subsection name="JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener">

    <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 9 some
    time after 2020-12-31.</strong></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
    visualvm or a similar tool to a remote Tomcat instance that is running
    behind a firewall.</p>

    <p>The remainder of the configuration can be done 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>, in addition to the SSL related attributes noted below
    in the "SSL Configurations" section:</p>

    <attributes>

      <attribute name="accessFile" required="false">
        <p>Defines the access file used. The attribute will be set to the
        value of the <code>com.sun.management.jmxremote.access.file</code>
        system property if it is defined.</p>
      </attribute>

      <attribute name="authenticate" required="false">
        <p>Defines if authentication is used. Defaults to
        <code>true</code>. The attribute will be set to the value of the
        <code>com.sun.management.jmxremote.authenticate</code> system property
        if it is defined.</p>
      </attribute>

      <attribute name="loginModuleName" required="false">
        <p>Defines the login module used. The attribute will be set to the
        value of the <code>com.sun.management.jmxremote.login.config</code>
        system property if it is defined.</p>
      </attribute>

      <attribute name="passwordFile" required="false">
        <p>Defines the password file used. The attribute will be set to the
        value of the  <code>com.sun.management.jmxremote.password.file</code>
        system property if it is defined.</p>
      </attribute>

      <attribute name="rmiBindAddress" required="false">
        <p>The address of the interface to be used by JMX/RMI server.</p>
      </attribute>

      <attribute name="rmiRegistryPortPlatform" required="true">
        <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>
      </attribute>

      <attribute name="rmiRegistrySSL" required="false">
        <p>Defines if the RMI registry will use SSL. Defaults to
        <code>true</code>. The attribute will be set to the value of the
        <code>com.sun.management.jmxremote.registry.ssl</code> system property
        if it is defined.</p>
      </attribute>

      <attribute name="rmiServerPortPlatform" required="true">
        <p>The port to be used by the Platform JMX/RMI server.</p>
      </attribute>

      <attribute name="rmiServerSSL" required="false">
        <p>Defines if the JMX remote server will use SSL. Defaults to
        <code>true</code>. The attribute will be set to the value of the
        <code>com.sun.management.jmxremote.ssl</code> system property
        if it is defined.</p>
      </attribute>

      <attribute name="useLocalPorts" required="false">
        <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>
      </attribute>

    </attributes>

    <h3>Using file-based Authentication and Authorisation</h3>

    <p>If this listener was configured in server.xml as:</p>
  <source><![CDATA[  <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />]]></source>
    <p>with the following system properties set (e.g. in setenv.sh):</p>
  <source>  -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
  -Dcom.sun.management.jmxremote.registry.ssl=false</source>
    <p>$CATALINA_BASE/conf/jmxremote.password containing:</p>
  <source>admin letmein</source>
    <p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
  <source>admin readwrite</source>
    <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>
  <source>service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi</source>
    <p>
    with a user name of <code>admin</code> and a password of
    <code>letmein</code>.
    </p>

    <h3>SSL Configurations</h3>

    <p>Note: SSL configuration can be done with attributes identical to those
    of <a href="http.html#SSL_Support_-_SSLHostConfig">SSLHostConfig</a> and the
    properties of the default certificate as defined for
    <a href="http.html#SSL_Support_-_Certificate">SSLHostConfigCertificate</a>.
    This will create a JSSE SSLContext which will be given to the JMX/RMI registry
    when creating the server socket. OpenSSL specific attributes <strong>cannot
    </strong> be used in the configuration as JMX remote can only use a regular
    SSLContext.</p>

    <p>A certificate can be defined for the server using a keystore:</p>
  <source><![CDATA[  <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
               rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002"
               certificateKeystoreFile="${catalina.home}/conf/mykeystore.jks" />]]></source>

    <h3>Using JAAS</h3>

    <p>If we use the following system properties instead:</p>
  <source>  -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
  -Dcom.sun.management.jmxremote.registry.ssl=false</source>
    <p>$CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:</p>
  <source>  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="(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))"
      authzIdentity="admin"
      debug=true;
  };</source>
    <p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
  <source>admin readwrite</source>
    <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>

  </subsection>

  <subsection name="Load external properties files - org.apache.catalina.core.LoadExternalPropertiesListener">

    <p>The <strong>Load External Properties Lifecycle Listener</strong> loads
    properties files specified by the listener's <code>file.N</code> attributes
    in the server.xml</p>

    <p>The listener must be nested within a <a href="server.html">Server</a>
    element, and it is recommended that this listener be the first nested
    element in the <a href="server.html">Server</a>. XML is processed in the
    order it appears, and defining this listener first allows properties to
    be defined and used later in the file.</p>

    <p>The following additional attributes are supported by the <strong>Load
    External Properties Lifecycle Listener</strong>:</p>

    <attributes>

      <attribute name="file.N" required="true">

        <p>External files to include. This is a special attribute that uses a
        dynamic name, allowing for up to 100 files include with values for N
        ranging from 0 to 99. Any values beyond 99 will result in files not
        being included and a warning being logged. These files will be
        loaded in order based on the index, N.</p>

        <p>For example, you could add two file attributes to the listener
        such as:

        <code>file.0="/path/to/file1.properties"
        file.1="/path/to/file2.properties"</code>
        </p>

      </attribute>

      <attribute name="overwrite" required="false">

        <p> Controls if previously defined system properties may be ovewritten.
        The default behavior is <code>true</code>, allowing for overwriting
        system properties.</p>

      </attribute>

      <attribute name="loadFirst" required="false">

        <p>Determines if any specified external files will be loaded before the
        rest of <code>server.xml</code>. The default is <code>false</code>,
        indicating that the contents of <code>server.xml</code> will be
        loaded and procesed before external files.</p>

      </attribute>

    </attributes>

  </subsection>

</section>

</body>

</document>
