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 7 some
time after 2020-12-31.
This listener requires catalina-jmx-remote.jar to be placed
in $CATALINA_HOME/lib. This jar may be found in the extras
directory of the binary download area.
The JMX Remote Lifecycle Listener fixes the ports used by
the JMX/RMI Server making things much simpler if you need to connect
jconsole or a similar tool to a remote Tomcat instance that is running
behind a firewall. Only these ports are configured via the listener. The
remainder of the configuration is via the standard system properties for
configuring JMX. For further information on configuring JMX see
Monitoring and Management Using JMX included with the Java SDK
documentation.
This listener must only be nested within a Server
element.
The following additional attributes are supported by the JMX Remote
Lifecycle Listener:
| Attribute | Description |
|---|
rmiRegistryPortPlatform |
The port to be used by the JMX/RMI registry for the Platform MBeans.
This replaces the use of the
com.sun.management.jmxremote.port system property that
should not be set when using this listener.
|
rmiServerPortPlatform |
The port to be used by the Platform JMX/RMI server.
|
rmiBindAddress |
The address of the interface to be used by JMX/RMI server.
|
useLocalPorts |
Should any clients using these ports be forced to use local ports to
connect to the JMX/RMI server. This is useful when tunnelling
connections over SSH or similar. Defaults to false.
|
Using file-based Authentication and Authorisation
If this listener was configured in server.xml as:
<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />
with the following system properties set (e.g. in setenv.sh):
-Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false
$CATALINA_BASE/conf/jmxremote.password containing:
$CATALINA_BASE/conf/jmxremote.access containing:
then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
firewall would enable jconsole to connect to a Tomcat instance running
behind a firewall using a connection string of the form:
service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi
with a user name of admin and a password of
letmein.
Using JAAS
If we use the following system properties instead:
-Dcom.sun.management.jmxremote.login.config=Tomcat
-Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false
$CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:
Tomcat { /* should match to the com.sun.management.jmxremote.login.config property */
/* for illustration purposes only */
com.sun.security.auth.module.LdapLoginModule REQUIRED
userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
authzIdentity="admin"
debug=true;
};
$CATALINA_BASE/conf/jmxremote.access containing:
then we would need to provide LDAP credentials instead.
Note that the examples above do not use SSL. JMX access should
be considered equivalent to administrative access and secured accordingly.
