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
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:
Enabling the JMX Agent
To monitor a Java platform with JMX:
- 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.
- 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 setting permissions on files and directories
(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:
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:
- Copy the password template file,
jmxremote.password.template , to
management.jmxremote.password .
- Set file permissions so that only the owner can read and write
the password file.
- 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:
- Copy the password template file,
jmxremote.password.template , to your home
directory.
- Set file permissions so that only you can read and write the
password file.
- Add passwords for the roles such as
monitorRole and controlRole .
- 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.
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.
|
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:
- If you don't already have a keypair and certificate set up on the server:
- Generate a key pair with the
keytool -genkey command.
- Request a signed certificate from a certificate authority (CA) with the
keytool -certreq command.
- 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).
- 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.
System Properties for SSL Configuration
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.
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 with SSL disabled,
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.
- To monitor a remote application with SSL enabled, you need to
set up the truststore on the system where JConsole is running and
configure SSL properly.
For example, if you create a keystore as
described in the
JSSE Guide and start your application (Server) as follows:
% java -Djavax.net.ssl.keyStore=keystore \ -Djavax.net.ssl.keyStorePassword=password Server
You need to start jconsole as follows:
% jconsole -J-Djavax.net.ssl.trustStore=truststore \ -J-Djavax.net.ssl.trustStorePassword=trustword
The above configuration authenticates the server only. If client authentication
is set up, you will need to provide a similar keystore for the JConsole's keys,
and an appropriate truststore for the application. Please refer to
Customizing the Default Key and Trust Stores, Store Types, and Store Passwords
in the JSSE Guide for details.
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
Tips: On Solaris and Linux systems, you can set the file permissions
for the password file by running:
chmod 600 jmxremote.password
On Windows, see How to Secure Password File
on Windows Systems
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.
Table 1. JMX Management and Monitoring 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.
ssl |
Enables secure monitoring via SSL. If false, then SSL is not
used. |
true / false.
Default is true. |
com.sun.management.jmxremote.
ssl.enabled.protocols |
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.
ssl.enabled.cipher.suites |
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.
ssl.need.client.auth |
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.
authenticate |
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.
password.file |
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/
jmxremote.password |
com.sun.management.jmxremote.
access.file |
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/
jmxremote.access |
com.sun.management.jmxremote.
login.config |
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.
|
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.
|