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.
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:
To monitor a Java platform with JMX:
jconsole
. See Using
jconsole for more information.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.
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.
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:
After you have enabled the JMX agent for remote use, you can monitor your application using jconsole, as described in Remote Monitoring with jconsole.
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:
jmxremote.password.template
, to
management.jmxremote.password
.monitorRole
and controlRole
.Multi-user Environment: set up the password file in the
JRE_HOME/lib/
management
directory
as follows:
jmxremote.password.template
, to your home
directory.monitorRole
and controlRole
.com.sun.management.jmxremote.password.file=pwFilePathwhere pwFilePath is the path to the password file.
WARNING: A potential security issue has been identified with password authentication
for JMX remote connectors when the client obtains the remote connector from an insecure RMI registry (the default).
If an attacker starts a bogus RMI registry on the
target server before the legitmate one is started, then the attacker can steal clients' passwords.
This scenario includes the case where you launch a JVM with remote management enabled, using the
system property com.sun.management.jmxremote.port=portNum , even when SSL is enabled.
Although such attacks are likely to be noticed, it is nevertheless a vulnerability.
To avoid this problem, use SSL client certificates for authentication instead of passwords, or ensure that the client obtains the remote connector object securely, for example through a secure LDAP server or a file in a shared secure filesystem. A future release will fix this problem. |
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.
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:
keytool -genkey
command. keytool -certreq
command. keytool -import
command.
See Importing Certificates
System Property | Description |
---|---|
javax.net.ssl.keyStore | Keystore location. |
javax.net.ssl.trustStore | Truststore location. |
javax.net.ssl.keyStoreType | Default keystore type.
|
javax.net.ssl.keyStorePassword | Default keystore password. |
javax.net.ssl.trustStoreType | Default truststore type. |
javax.net.ssl.trustStorePassword | Default truststore password. |
For more information, see keytool - Key and Certificate Management Tool (Solaris and Linux) (Windows), and the JSSE Guide.
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.
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.
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.
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.
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);
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
.
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
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 monitoringcontrolRole
, 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:
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
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.
Property Name | Description | Values |
---|---|---|
com.sun.management.jmxremote |
Enables the JMX remote agent and local monitoring via JMX
connector published on a private interface used by
jconsole . The jconsole tool can use this connector if it is executed by the same
user ID as the user ID that started the agent. No password or access files are
checked for requests coming via this connector. |
true / false. Default is true. |
com.sun.management.jmxremote.
port |
Enables the JMX remote agent and creates a remote JMX connector
to listen through the specified port. By default, SSL, password,
and access files properties are used for this connector. Also
enables local monitoring as described for the
com.sun.management.jmxremote property. |
Port number. No default. |
com.sun.management.jmxremote. |
Enables secure monitoring via SSL. If false, then SSL is not used. | true / false. Default is true. |
com.sun.management.jmxremote. |
Comma-delimited list of SSL/TLS protocol versions to enable.
Used in conjunction with
com.sun.management.jmxremote.ssl |
Default SSL/TLS protocol version. |
com.sun.management.jmxremote. |
A comma-delimited list of SSL/TLS cipher suites to enable. Used
in conjunction with
com.sun.management.jmxremote.ssl . |
Default SSL/TLS cipher suites. |
com.sun.management.jmxremote. |
If this property is true and the property
com.sun.management.jmxremote.ssl is true, then client
authentication will be performed. |
true / false. Default is false |
com.sun.management.jmxremote. |
If this property is false then JMX does not use passwords or access files: all users are allowed all access. | true / false. Default is true. |
com.sun.management.jmxremote. |
Specifies location for password file. If
com.sun.management.jmxremote.password is false, then
this property and the password and access files are ignored.
Otherwise, the password file must exist and be in valid format. If
the password file is empty or non-existent, then no access is
allowed. |
JRE_HOME/lib/management/ |
com.sun.management.jmxremote. |
Specifies location for the access file. If
com.sun.management.jmxremote.password is false, then
this property and the password and access files are ignored.
Otherwise, the access file must exist and be in the valid format.
If the access file is empty or non-existent, then no access is
allowed. |
JRE_HOME/lib/management/ |
com.sun.management.jmxremote. |
Specifies the name of a JAAS login configuration entry
to use when authenticating users of RMI monitoring.
When using this property to override the default login configuration,
the named configuration entry must be in a file that gets loaded
by JAAS. In addition, the login modules specified in the configuration
should use the name and password callbacks to acquire the user's
credentials.
For more information, see javax.security.auth.callback.NameCallback and
javax.security.auth.callback.PasswordCallback .
If com.sun.management.jmxremote.authenticate is
false, then this property and the password and access files are ignored.
|
Default login configuration is a file-based password authentication. |
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:
If your application runs a security manager, then additional permissions are required in the security permissions file.