Monitoring and Management Using JMX

The Java virtual machine (JVM) has built-in instrumentation that enables you to monitor and manage it using JMX.  You can also monitor instrumented applications with JMX.

• Setting System Properties for JMX
• Enabling the JMX Agent
  • Local Monitoring and Management
  • Remote Monitoring and Management
• Connecting to the JMX Agent Programmatically
• Using Password and Access Files
• JMX Management and Monitoring Properties

Setting System Properties

To enable the JMX agent and configure its operation, you must set certain system properties when you start the Java virtual machine (JVM).  You set a system property on the command-line as follows:

java -Dproperty=value ...

You can set any number of system properties in this way. If you do not specify a value, then the property is set with its default value. The full set of JMX management properties is described in Table 1. You may also set system properties in a configuration file, as described in JMX Management and Monitoring Properties.

Note: To run java (the Java VM) from the command line, you must add JRE_HOME/bin to your path, where JRE_HOME is the directory containing the Java Runtime Environment (JRE). Alternatively, you can enter the full path when you type the command.

The following documents describe the syntax and full set of command-line options supported by the Java HotSpot VMs:

• Java application launcher for Microsoft Windows
• Java application launcher for Solaris Operating Environment
• Java application launcher for Linux

Enabling the JMX Agent

To monitor a Java platform with JMX:

1. Enable the JMX agent (the MBean server) when you start the JVM. You can enable the JMX agent for:
   • Local monitoring, for a client management application running on the local system.
   • Remote monitoring, for a client management application running on a remote system.
2. Monitor the JVM with a JMX-compliant tool such as jconsole. See Using jconsole for more information.

Local Monitoring and Management

To enable the JMX agent for local access, set this system property when you start the JVM or Java application:

com.sun.management.jmxremote

Setting this property registers the JVM instrumentation MBeans and publishes the RMI connector via a private interface to allow JMX client applications to monitor a local Java platform, that is, a JVM running on the same machine.

For example, to enable the JMX agent for the J2SE sample application Notepad:

cd JDK_HOME/demo/jfc/Notepad
java -Dcom.sun.management.jmxremote -jar Notepad.jar

where JDK_HOME is the directory where the JDK is installed.

Limitation: On Windows, for security reasons, local monitoring and management is only supported if your default Windows temporary directory is on a file system that supports persistent access control lists (for example, on an NTFS file system). It is not supported on a FAT file system that provide insufficient access controls.

Using jconsole

Local monitoring with jconsole is useful for development and prototyping. Using jconsole locally is not recommended for production environments, because jconsole itself consumes significant system resources. Rather, use jconsole on a remote system to isolate it from the platform being monitored.

Start jconsole by typing jconsole in a command shell. When you start jconsole withouth any arguments, it will automatically detect all local Java applications, and display a dialog box that enables you to select the application you want to monitor.  Both jconsole and the application must by executed by the same user name, since the monitoring and monitoring system uses the operating system's file permissions.

Note: To run jconsole from the command line, you must add JAVA_HOME/bin to your path, where JAVA_HOME is the directory containing the JDK. Alternatively, you can enter the full path when you type the command.

For more information on using jconsole, see Using jconsole.

Remote Monitoring and Management

To enable monitoring and management from remote systems, set this system property when you start the JVM:

com.sun.management.jmxremote.port=portNum

where 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 a 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".

Note: You must set the above system property in addition to any properties you set for security, described below.

Remote monitoring and management requires security, to ensure that unauthorized persons cannot control or monitor your application. Password authentication over SSL (secure sockets layer) is enabled by default. You may separately disable password authentication and SSL, as described in the following sections:

• Using password authentication
• Disabling password authentication
• Using SSL
• Using client SSL authentication
• Disabling SSL
• Disabling security

After you have enabled the JMX agent for remote use, you can monitor your application using jconsole, as described in Remote Monitoring with jconsole.

Using Password Authentication

By default, when you enable the JMX agent for remote monitoring, it uses password authentication. However, the way you set it up depends on whether you are in a single-user environment or a multi-user environment.

Since passwords are stored in clear-text in the password file, it is not advisable to use your regular user name and password for monitoring. Instead, use the user names specified in the password file such as monitorRole and controlRole. For more information, see Using Password and Access Files.

Single User Environment: set up the password file in the JRE_HOME/lib/management directory as follows:

1. Copy the password template file, jmxremote.password.template, to management.jmxremote.password.
2. Set file permissions so that only the owner can read and write the password file.
3. Add passwords for roles such as monitorRole and controlRole.

Multi-user Environment: set up the password file in the JRE_HOME/lib/management directory as follows:

1. Copy the password template file, jmxremote.password.template, to your home directory.
2. Set file permissions so that only you can read and write the password file.
3. Add passwords for the roles such as monitorRole and controlRole.
4. Set this system property when you start the JVM:

   com.sun.management.jmxremote.password.file=pwFilePath

   where pwFilePath is the path to the password file.

Disabling password authentication

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

com.sun.management.jmxremote.authenticate=false

where portNum is the port number to use. Be sure to specify an unused port number.

When you disable password authentication, you can also disable SSL, as described in Disabling Security. You may also want to disable passwords, but use SSL client authentication, as described in Enabling Client SSL Authentication. 

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

Using SSL

Secure sockets layer (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 (MBean server) is running and then configure SSL properly. You use the command-line utility keytool to work with certificates. The general procedure is:

1. If you don't already have a keypair 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. See Importing Certificates
      For more information and examples, see keytool - Key and Certificate Management Tool (Solaris and Linux) (Windows).
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 following table. For more information, see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords in the JSSE Guide.

For more information, see keytool - Key and Certificate Management Tool (Solaris and Linux) (Windows), and the JSSE Guide.

Enabling Client SSL Authentication

To enable client SSL authentication, set this system property when you start the JVM:

com.sun.management.jmxremote.ssl.need.client.auth=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.

Disabling SSL

To disable SSL for remote monitoring, set this system property when you start the JVM:

com.sun.management.jmxremote.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 (no security), set these system properties when you start the JVM:

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

Warning: 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.

Remote Monitoring with jconsole

To monitor a remote application, start jconsole as follows:

jconsole hostName:portNum

where hostName is the name of the system running the application and portNum is the port number you specified when you started the JVM.   You can also omit the host name and port number, and enter them in the dialog box that jconsole provides.

Note: To run jconsole from the command line, you must add JAVA_HOME/bin to your path, where JAVA_HOME is the directory containing the JDK. Alternatively, you can enter the full path when you type the command.

For more information on using jconsole, see Using jconsole.

Connecting to the JMX Agent Programmatically

Once you have enabled the JMX agent, a client can use the following URL to access the service:

service:jmx:rmi:///jndi/rmi://hostName:portNum/jmxrmi

where hostName is the host name and portNum is the port number specified when the JMX agent was enabled.

A client can create a connector to the agent by instantiating an javax.management.remote.JMXServiceURL object using the URL, and then creating a connection using the JMXConnectorFactory.connect method as follows:

JMXServiceURL u = new JMXServiceURL(
  "service:jmx:rmi:///jndi/rmi:// “ + hostName + ":" + portNum +  "/jmxrmi");
  JMXConnector c = JMXConnectorFactory.connect(u); 

Using Password and Access Files

The password and access files control security for remote monitoring and management. These files are located by default in JRE_HOME/lib/management and are in the standard Java properties file format. For more information on the format, see the API reference for java.util.properties.

Password File

The password file defines the different roles and their passwords. The access control file (jmxremote.access by default) defines the allowed access for each role. To be functional, a role must have an entry in both the password and the access files.

The JRE contains a password file template named jmxremote.password.template . Copy this file to JRE_HOME/lib/management/jmxremote.password or to your home directory, and add the passwords for the roles defined in the access file.

Ensure that only the owner has read and write permissions on this file, since it contains the passwords in clear text. For security reasons, the system checks that the file is only readable or writeable by the owner and exits with an error if not. Thus in a multi-user environment, store the password file in private location such as your home directory.

Property names are roles, and the associated value is the role's password.

For example, the following are sample entries in the password file:

# The "monitorRole" role has password "QED".
# The "controlRole" role has password "R&D".
monitorRole QED
controlRole R&D

Access File

By default, the access file is named jmxremote.access. Property names are identities from the same space as the password file. The associated value must be either "readonly" or "readwrite".

The access file defines roles and their access levels. By default, the access file defines two primary roles:

• monitorRole, which grants read-only access for monitoring
• controlRole, which grants read-write access for monitoring and management.

An access control entry consists of a role name and an associated access level. The role name cannot contain spaces or tabs and must correspond to an entry in the password file. The access level is either:

• readonly: grants access to read attributes of MBeans. For monitoring, this means that a remote client in this role can read measurements but cannot perform any action that changes the environment of the running program.
• readwrite: grants access to read and write attributes of MBeans, to invoke operations on them, and to create or remove them. This access should be granted to only trusted clients, since they can potentially interfere with the operation of an application.

A role should have only one entry in the access file. If a role has no entry, it has no access. If a role has multiple entries, then the last entry takes precedence.

Typical pre-defined roles in the access file:

# The "monitorRole" role has readonly access.
# The "controlRole" role has readwrite access.
monitorRole readonly
controlRole readwrite

JMX Management and Monitoring Properties

You can set management and monitoring properties in a configuration file or on the command line. Properties specified on the command line override properties in a configuration file. The default location for the configuration file is JRE_HOME/lib/management/management.properties, where JRE_HOME is the directory where the Java runtime environment is installed. The JVM reads this file if either of the command-line properties com.sun.management.jmxremote or com.sun.management.jmxremote.port are set. SNMP management uses the same configuration file; for more information, see SNMP Monitoring and Management.

You can specify a different location for the configuration file with the command-line option:

com.sun.management.config.file=ConfigFilePath

where ConfigFilePath is the path to the configuration file.

The following table describes all the JMX monitoring and management properties.

Configuration Errors

If any errors occur during start up of the MBean server, the RMI registry, or the connector, the JVM will throw an exception and exit. Configuration errors include:

• Failure to bind to the port number
• Invalid password file
• Invalid access file
• Password file is readable by anyone other than the owner.

If your application runs a security manager, then additional permissions are required in the security permissions file.