JConsole: remoting, notifications and log control

In real applications, instrumentation is usually monitored across the network. Following on from our tutorial on JConsole, here's how to network-enable your managed Java applications.

In the last article, we showed how you can use JConsole to manage a local application or just peer into the JVM for a view of how it is working. Useful as this is in development, out in the field, the chances are the application you want to manage is going to be at the far end of a network. The JMX, Java Management Extensions, originally appeared with no standard network support, gaining that in a later revision, JSR 160. That added with a whole raft of networking support to JMX, so much that it can be a bit overwhelming browsing the specification. Let's start with using JConsole remotely without worrying about security first.

The important element in getting a quick remote connection is enabling the application to be monitored to accept remote connections. This can be done by setting some system properties, in the same way you turn JMX on.

To start the example application WatchMe with remote access, you'd start it with:

java -Dcom.sun.management.jmxremote
  -Dcom.sun.management.jmxremote.port=9696
  -Dcom.sun.management.jmxremote.authenticate=false
  -Dcom.sun.management.jmxremote.ssl=false
  -jar WatchMe.jar

This starts JMX and opens port 9696 â€" you are able to use any free port â€" remember to make sure it isn't blocked by a local firewall though. The second pair of parameters disables the password and SSL authentication. Never, ever, use this in a production environment â€" it basically opens the door to all comers to manage your application, though this is useful in the development lab. To connect to the application, start up JConsole as we previously covered, but instead of going to the Local tab in the connections dialogue, go to the Remote tab.

Enter the hostname and port of the target application, leave username and password blank and click connect and that's it. You can now monitor and manage the application with JConsole.

JMX gives two ways to control who logs into your applications management interface, Password and SSL Authentication. Password authentication is the simplest part to set up. In your JRE's home directory you'll find the directory lib, and below that a management directory, which in turn contains JMX's control files. There isn't a password file by default, but there is a template file, jmxremote.password.template. If you copied this file to management.jmxremote.password it would be used as that JRE's default password file.

The password file template is made up of pairs of role names and passwords. Here's the default template (and yes these are commented out; you wouldn't want a template with a password already set up in it).

# monitorRole QED
# controlRole R&D

From which of course, you'd remove the comments and change the passwords. They are, as you can see, plaintext passwords. The names are derived from the roles defined in jmxremote.access file which by default looks like this:

monitorRole readonly
controlRole readwrite

Where the name is followed by what access type the role is granted. There are only two, readonly for users who can read the management information but aren't allowed to update it or invoke methods, and readwrite which gives full access to the management beans.

If you want an application to use a particular password file, you can copy the password template file your home directory and edit it. To run an application with password authentication, first we need to note that the password authentication property is true by default, which is why we had to force it to false in previous examples. Now we can just omit setting that property. What we do need to do is point the application at the password file; for this example, we'll assume we're on Windows and have created a password file as C:\passwords\jmxremote.password containing:

monitorRole watchme
controlRole controlme

To run with this password file, you'd execute

java -Dcom.sun.management.jmxremote
  -Dcom.sun.management.jmxremote.port=9696
  -Dcom.sun.management.jmxremote.ssl=false
  -Dcom.sun.management.jmxremote.password.file=C:\passwords\
jmxremote.password
  -jar WatchMe.jar

and immediately wonder why you got an error about the password file not being restricted. The reason is simple; the passwords are plain text so the JMX authentication demands that the password file is only readable/writable by the same owner as is running the application.

Unix users will immediately reach for the chmod command and execute "chmod 600 passwordfilename", but Windows users have a more fiddly time. Firstly, the Windows file system has to be capable of setting that kind of ownership. If you have a FAT32 file system, you are out of luck; FAT32 doesn't have the concept of ownership.

If you have NTFS, then you can establish ownership. If you go to the Properties of the password file, and select the Security tab, take ownership of the file, remove "inherit from parent" permissions and then remove all but your own permissions, then you will be able to run the application. If you can't see the Security tab, you need to turn off "Simple File Sharing" on the folder. There's a screen by screen version of this process at the Java web site.

Once the application is running, you can connect to it using the Remote tab on JConsole and enter the appropriate username and password. You now have basic authentication.

For production level security, JMX supports SSL authentication. This requires an exchange of keys between the client and server to allow them to authenticate each other and can be used in combination with the password authentication. The bad news is that JConsole itself doesn't let you set up the keystore, so no SSL support.