Using jconsole to connect to JMX on AS7

This article describes how to connect to the JBoss AS7 JMX MBeanServer from jconsole.

 

For the management of JBoss AS7 we expose access to the management operative over a native interface build on top of JBoss Remoting, as of the 13th January 2011 we also provide a JSR-160 connector with JBoss AS7 to make JMX remotely accessible over the same Remoting connection.  The first release to contain this will be JBoss AS 7.1.0.Final.

 

As we are using the same Remoting connection as the management interface the same security mechanisms that are used for domain management will be used for accessing JMX so this article describes how to achieve this with jconsole.

 

In JBoss AS 7.1.2 forward, this Remoting connection is also used to allow the integrated CLI GUI to send commands to a standalone AS server or domain controller.

 

Starting JConsole

 

In order to connect to the JMX MBeanServer using Remoting we have created a new JSR-160 connector, so that this can be used with jconsole the ClassPath being used by jconsole needs to be updated to include the additional classes - so that users do not need to manually construct these class paths we have included a jconsole.sh and jconsole.bat script within the AS7 distribution which will construct the correct ClassPath before starting jconsole.

 

NOTE: If you are running jconsole on a machine different than the server you need to have a local JBoss installation: the Java JRE's jconsole will not work out of the box (i.e., without additional jars in the classpath).  In addition, if you are on a remote machine and the target machine is not in DNS, you'll have to add it to your hosts file.

 

 

Before running these scripts you should ensure that the JAVA_HOME environment variable has been set to point to your Java installation, this is required as a couple of jars within the distribution but not normally on the classpath are required and to also delegate to the original jconsole executable after the new classpath has been constructed.

 

After running the JBOSS_HOME/bin/jconsole.sh (linux) or JBOSS_HOME/bin/jconsole.bat (windows) script you should be prompted with the usual connect dialogue: -

 

connect.jpeg

To connect to JMX the URL entered should be in the format

 

service:jmx:remoting-jmx://{host_name}:{port} 

 

Standalone mode

 

where {port} is the native management interface of the AS7 installation being monitored (default=9999).

 

Domain mode

 

where {port} is the JMX subsystem interface of the AS7 installation being monitored (first server=4447, port-offset=150 next server).

 

Manual changes in Jboss-7.1.0.Final in domain.xml -thanks to https://community.jboss.org/thread/196236

 

<subsystem xmlns="urn:jboss:domain:jmx:1.1">

   <show-model value="true"/>

   <remoting-connector use-management-endpoint="false"/>

</subsystem>

 

Both modes

 

Outside localhost you have to set -Djboss.bind.address.management or inside xml (standalone.xml / host.xml).

 

Once connected the capabilities provided by jconsole can be used as normal.

 

Authentication

 

The connector is making use of JBoss Remoting to communicate with the server, for this reason the exact same authentication mechanisms as are used by the CLI will apply here.

 

Local

 

For processes running local to the AS7 installation we support a local authentication mechanism which allows clients to verify their identity by sharing a token on the filesystem with the server - this mechanism runs silently without any further user interaction required.

 

Username / Password

 

Where local authentication is not possible such as if the client is running as a different user than the AS7 process or is running on a remote installation by default the next mechanism to be used is username / password based.  Where this mechanism is used the username and password of a user in the ManagementRealm if using the default management connector (port 9999) or in the ApplicationRealm if using the remoting connector (port 4447) should be supplied in the boxes on the 'New Connection' screen before the 'Connect' button is clicked.

 

The $JBOSS_HOME/bin/add-user.sh (Linux) or $JBOSS_HOME/bin/add-user.bat (Windows) scripts can be used to add these users. Make sure to choose between Management User and ManagementRealm vs Application User and ApplicationRealm depending on whether you're using the default management connector or the remoting connector (usually used with domain mode or when connecting remotely).

 

TLS

 

Where the management interface has been configured with a keystore jconsole will need to be configured to use a trust store so that the connection can be verified.

 

A trust store can be specified by editing the jconsole script and adding the following properties: -

 

  -J-Djavax.net.ssl.trustStore=client.truststore -J-Djavax.net.ssl.trustStorePassword=truststore_password

 

The first property specifies the location of the truststore and the second property is the password to open it.

 

Please note that the properties are prefixed -J-D and not just -D, this is so that the jconsole executable will pass them to the underlying JVM that runs the console.

 

A keystore can also be specified in a similar way by editing the script and adding the following two properties: -

 

-J-Djavax.net.ssl.keyStore=client.keystore -J-Djavax.net.ssl.keyStorePassword=keystore_password

 

As before please note the -J-D form to specify the properties so the values are passed to the JVM.

 

Provided that the server is configured the authenticated based on the clients certificate the certificate in the keystore can now be used for authentication without needing to specify a username and password.