JMX Configuration

This document describes how to configure an application for JMX Management. All parameters defined below are placed in the applications etc/appName.config file:

Remote Monitoring and Management

To enable monitoring and management from remote systems, you must set the following system property when you start the Java VM.

 -XKjmx:port=portNum

In the property above, portNum is the port number through which you want to enable JMX RMI connections. Be sure to specify an unused port number. In addition to publishing an RMI connector for local access, setting this property publishes an additional RMI connector in a private read-only registry at the specified port using a well known name, "jmxrmi".

Remote monitoring and management requires security, to ensure that unauthorized persons cannot control or monitor your application. Password authentication over the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) is enabled by default. You can disable password authentication and SSL separately, as described in the next sections.

Using Password Authentication

In your applications etc directory (or anywhere else secure) create a .password file. Each line consists of two entries in .properties format with the name being the role and the value a password. Neither may contain spaces or tabs. For example, you create the file: etc/myApp.password

 monitorRole QED
 controlRole R&D

You then need to set the following parameter:

 -XKjmx:passwordFile=${configDirectory}/myApp.password

The ${configDirectory} part will be expanded to point to the application's etc directory at runtime.

Disabling Password Authentication

Password authentication for remote monitoring is enabled by default. To disable it, set the following system property when you start the Java VM.

 -XKjmx:authenticate=false

Caution - This configuration is insecure. Any remote user who knows (or guesses) your JMX port number and host name will be able to monitor and control your Java application and platform. While it may be acceptable for development, it is not recommended for production systems.

Using SSL

SSL is enabled by default when you enable remote monitoring and management. To use SSL, you need to set up a digital certificate on the system where the JMX agent (the MBean server) is running and then configure SSL properly. You use the command-line utility keytool to work with certificates. The general procedure is as follows.

To Set up SSL

1. If you do not already have a key pair and certificate set up on the server:
   1. Generate a key pair with the keytool -genkey command.
   2. Request a signed certificate from a certificate authority (CA) with the keytool -certreq command.
   3. Import the certificate into your keystore with the keytool -import command.
2. Configure SSL on the server system.

A full explanation of configuring and customizing SSL is beyond the scope of this document, but you generally need to set the system properties described in the list below.

-XKkeystore:key=

Keystore location

-XKkeystore:key:type=

Default keystore type

-XKkeystore:key:password=

Default keystore password

-XKkeystore:trust=

Truststore location

-XKkeystore:trust:type=

Detault truststore type

-XKkeystore:trust:password=

Default truststore password

Enabling RMI Registry Authentication

When setting up connections for monitoring remote applications, you can optionally bind the RMI connector stub to an RMI registry that is protected by SSL. This allows clients with the appropriate SSL certificates to get the connector stub that is registered in the RMI registry. To protect the RMI registry using SSL, you must set the following system property.

 -XKjmx:rmi:ssl=true

When this property is set to true, an RMI registry protected by SSL will be created and configured by the out-of-the-box management agent when the Java VM is started. The default value of this property is false. If this property is set to true, in order to have full security then SSL client authentication must also be enabled, as described in the next section.

Enabling SSL Client Authentication

To enable SSL client authentication, set the following system property when you start the Java VM.

 -XKjmx:client:ssl=true

SSL must be enabled (the default), to use client SSL authentication. This configuration requires the client system to have a valid digital certificate. You must install a certificate and configure SSL on the client system, as described in Using SSL. As stated in the previous section, if RMI registry SSL protection is enabled, then client SSL authentication must be set to true.

Disabling SSL

To disable SSL when monitoring remotely, you must set the following system property when you start the Java VM.

 -XKjmx:ssl=false

Password authentication will still be required unless you disable it, as specified in Disabling Password Authentication.

Disabling Security

To disable both password authentication and SSL (namely to disable all security), you should set the following system properties when you start the Java VM.

 -XKjmx:authenticate=false
 -XKjmx:ssl=false