You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2019/12/18 10:28:10 UTC
[tomcat] branch master updated: Deprecate the
JmxRemoteLifecycleListener
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/master by this push:
new 07a44db Deprecate the JmxRemoteLifecycleListener
07a44db is described below
commit 07a44dbf56224e74b582d7357f3a60f354e5af79
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Wed Dec 18 10:27:51 2019 +0000
Deprecate the JmxRemoteLifecycleListener
---
.../mbeans/JmxRemoteLifecycleListener.java | 12 ++-
.../apache/catalina/mbeans/LocalStrings.properties | 1 +
webapps/docs/changelog.xml | 6 ++
webapps/docs/config/listeners.xml | 96 ++++++++++++----------
webapps/docs/monitoring.xml | 51 +++++++++---
5 files changed, 107 insertions(+), 59 deletions(-)
diff --git a/java/org/apache/catalina/mbeans/JmxRemoteLifecycleListener.java b/java/org/apache/catalina/mbeans/JmxRemoteLifecycleListener.java
index d01ed8e..4256fb3 100644
--- a/java/org/apache/catalina/mbeans/JmxRemoteLifecycleListener.java
+++ b/java/org/apache/catalina/mbeans/JmxRemoteLifecycleListener.java
@@ -62,7 +62,13 @@ import org.apache.tomcat.util.res.StringManager;
* instance that is running behind a firewall. Only the ports are configured via
* the listener. The remainder of the configuration is via the standard system
* properties for configuring JMX.
+ *
+ * @deprecated The features provided by this listener 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.0.x some time after 2020-12-31.
*/
+@Deprecated
public class JmxRemoteLifecycleListener extends SSLHostConfig implements LifecycleListener {
private static final long serialVersionUID = 1L;
@@ -293,8 +299,10 @@ public class JmxRemoteLifecycleListener extends SSLHostConfig implements Lifecyc
@Override
public void lifecycleEvent(LifecycleEvent event) {
- // When the server starts, configure JMX/RMI
- if (Lifecycle.START_EVENT.equals(event.getType())) {
+ if (Lifecycle.BEFORE_INIT_EVENT.equals(event.getType())) {
+ log.warn(sm.getString("jmxRemoteLifecycleListener.deprecated"));
+ } else if (Lifecycle.START_EVENT.equals(event.getType())) {
+ // When the server starts, configure JMX/RMI
// Configure using standard JMX system properties
init();
diff --git a/java/org/apache/catalina/mbeans/LocalStrings.properties b/java/org/apache/catalina/mbeans/LocalStrings.properties
index 21251d4..9f71bdc 100644
--- a/java/org/apache/catalina/mbeans/LocalStrings.properties
+++ b/java/org/apache/catalina/mbeans/LocalStrings.properties
@@ -25,6 +25,7 @@ globalResources.userDatabaseCreateError=Exception creating UserDatabase MBeans f
jmxRemoteLifecycleListener.createRegistryFailed=Unable to create the RMI registry for the [{0}] server using port [{1}]
jmxRemoteLifecycleListener.createServerFailed=The JMX connector server could not be created or failed to start for the [{0}] server
+jmxRemoteLifecycleListener.deprecated=The JmxRemoteLifecycleListener is deprecated as 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 2019-12-31.
jmxRemoteLifecycleListener.destroyServerFailed=The JMX connector server could not be stopped for the [{0}] server
jmxRemoteLifecycleListener.invalidRmiBindAddress=Invalid RMI bind address [{0}]
jmxRemoteLifecycleListener.invalidSSLConfiguration=SSL configuration error
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index f69a971..14774e6 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -69,6 +69,12 @@
<bug>64008</bug>: Clarify/expand the Javadoc for the
<code>Tomcat#addWebapp()</code> and related methods. (markt)
</fix>
+ <scode>
+ Deprecate the <code>JmxRemoteLifecycleListener</code> 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.0.x some time after 2020-12-31. (markt)
+ </scode>
</changelog>
</subsection>
<subsection name="Coyote">
diff --git a/webapps/docs/config/listeners.xml b/webapps/docs/config/listeners.xml
index 983793b..918b1f3 100644
--- a/webapps/docs/config/listeners.xml
+++ b/webapps/docs/config/listeners.xml
@@ -504,8 +504,60 @@
</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 boardcast messages to HTTPD, default 224.0.1.105</p>
+ </attribute>
+
+ <attribute name="Multiport" required="false">
+ <p>Multiport is the Multicast port to boardcast messages to HTTPD, default 23364</p>
+ </attribute>
+
+ <attribute name="Ttl" required="false">
+ <p>Ttl is the TTL for the boardcast 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 2019-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
@@ -656,50 +708,6 @@
</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 boardcast messages to HTTPD, default 224.0.1.105</p>
- </attribute>
-
- <attribute name="Multiport" required="false">
- <p>Multiport is the Multicast port to boardcast messages to HTTPD, default 23364</p>
- </attribute>
-
- <attribute name="Ttl" required="false">
- <p>Ttl is the TTL for the boardcast messages, default 16</p>
- </attribute>
-
- </attributes>
- </subsection>
-
</section>
</body>
diff --git a/webapps/docs/monitoring.xml b/webapps/docs/monitoring.xml
index 65194cd..9b6471b 100644
--- a/webapps/docs/monitoring.xml
+++ b/webapps/docs/monitoring.xml
@@ -47,26 +47,45 @@
to monitor it locally, using the same user that Tomcat runs with.</p>
<p>The Oracle website includes the list of options and how to configure
- JMX Remote on Java 6:
- <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html">
+ JMX Remote on Java 8:
+ <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html">
http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html</a>.
</p>
- <p>The following is a quick configuration guide for Java 6:</p>
+ <p>The following is a quick configuration guide for Java 8:</p>
<p>Add the following parameters to <code>setenv.bat</code> script of your
Tomcat (see <a href="RUNNING.txt">RUNNING.txt</a> for details).<br/>
<em>Note:</em> This syntax is for Microsoft Windows. The command has
to be on the same line. It is wrapped to be more readable. If Tomcat is
running as a Windows service, use its configuration dialog to set
java options for the service.
- For un*xes remove <code>"set "</code> from beginning of the line.
+ For Linux, MacOS, etc, remove <code>"set "</code> from beginning of the
+ line.
</p>
-<source><![CDATA[set CATALINA_OPTS=-Dcom.sun.management.jmxremote
- -Dcom.sun.management.jmxremote.port=%my.jmx.port%
+<source><![CDATA[set CATALINA_OPTS=-Dcom.sun.management.jmxremote.port=%my.jmx.port%
+ -Dcom.sun.management.jmxremote.rmi.port=%my.rmi.port%
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false]]></source>
+<p>If you don't set <code>com.sun.management.jmxremote.rmi.port</code> then the
+JSR 160 JMX-Adaptor will select a port at random which will may it difficult to
+configure a firewall to allow access.</p>
+<p>If you require TLS:</p>
<ol>
- <li>If you require authorization, add and change this:
+ <li>change and add this:
+<source><![CDATA[ -Dcom.sun.management.jmxremote.ssl=true
+ -Dcom.sun.management.jmxremote.registry.ssl=true
+]]></source></li>
+ <li>to configure the protocols and/or cipher suites use:
+<source><![CDATA[ -Dcom.sun.management.jmxremote.ssl.enabled.protocols=%my.jmx.ssl.protocols%
+ -Dcom.sun.management.jmxremote.ssl.enabled.cipher.suites=%my.jmx.cipher.suites%
+]]></source></li>
+ <li>to client certificate authentication use:
+<source><![CDATA[ -Dcom.sun.management.jmxremote.ssl.need.client.auth=%my.jmx.ssl.clientauth%]]></source></li>
+ </ol>
+<p>If you require authorization (it is strongly recommended that TLS is always
+used with authentication):</p>
+ <ol>
+ <li>change and add this:
<source><![CDATA[ -Dcom.sun.management.jmxremote.authenticate=true
-Dcom.sun.management.jmxremote.password.file=../conf/jmxremote.password
-Dcom.sun.management.jmxremote.access.file=../conf/jmxremote.access]]></source>
@@ -81,17 +100,23 @@ controlRole tomcat]]></source>
<b>Tip</b>: The password file should be read-only and only accessible by the
operating system user Tomcat is running as.
</li>
+ <li>Alterantively, you can configure a JAAS login module with:
+<source><![CDATA[ -Dcom.sun.management.jmxremote.login.config=%login.module.name%]]></source></li>
</ol>
- <p><strong>Note:</strong> The JSR 160 JMX-Adaptor opens a second data channel
- on a random port. That is a problem when you have a local firewall installed.
- To fix it, configure a <code>JmxRemoteLifecycleListener</code>, as described
- in <a href="config/listeners.html">listeners</a> documentation.
- </p>
+
+<p>If you need to specify a host name to be used in the RMI stubs sent to the
+client (e.g. because the public host name that must be used to connect is not
+the same as the local host name) then you can set:</p>
+<source><![CDATA[set CATALINA_OPTS=-Djava.rmi.server.hostname]]></source>
+
+<p>If you need to specify a specific interface for the JMX service to bind to
+then you can set:</p>
+<source><![CDATA[set CATALINA_OPTS=-Dcom.sun.management.jmxremote.host]]></source>
</section>
<section name="Manage Tomcat with JMX remote Ant Tasks">
- <p>To simplify JMX usage with Ant 1.6.x, a set of tasks is provided that may
+ <p>To simplify JMX usage with Ant, a set of tasks is provided that may
be used with antlib.</p>
<p><b>antlib</b>: Copy your catalina-ant.jar from $CATALINA_HOME/lib to $ANT_HOME/lib.</p>
<p>The following example shows the JMX Accessor usage:<br/>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org