The following article is provided on an advice basis only. This article references 3rd party software that may require licensing. When experiencing performance issues with a Diffusion server, JMX via remote access can be required. It should be confirmed that it is possible to use JMX remotely on all servers in production.
Enabling JMX Access
The jconsole graphical user interface is a monitoring tool that complies with the JMX specification. jconsole uses the extensive instrumentation of the Java Virtual Machine to provide information about the performance and resource consumption of applications running on the Java platform. jconsole is included in the JDK. The JDK should be installed on all servers that are in development, QA and production. The ports used by Diffusion for JMX access are defined in etc/Management.xml. By default the ports used are 1099 and 1100. Depending on your configuration it may be necessary to set the <host> parameter. By default this value is blank, which equates to localhost.
Warning: The port specified for the <registry-port> must be accessible externally. This should be configured in your load balancer / firewall.
If your Diffusion server is running on a Unix based machine and the command hostname -i returns 127.0.1.1 you are required to add a record to your hosts file, this should map your hostname to the IP that the server is accessible on.
Using JConsole
On the remote machine, the jconsole executable can be found in JDK_HOME/bin, where JDK_HOME is the directory in which the Java Development Kit (JDK) is installed. If this directory is in your system path, you can start JConsole by simply typing jconsole in a command (shell) prompt. Otherwise, you have to type the full path to the executable file. Once jconsole has started select ‘Remote Process’. Enter the IP address and port for your Diffusion server. It is also necessary to enter a username and password. By default these are as follows. These values can be changed in etc/Management.xml.
Click connect, secure connections may fail (see “Configuring Diffusion to handle JMX over SSL” below). If so choose insecure. You will now see the following overview of your Diffusion server statistics.
Configuring Diffusion to handle JMX over TLS/SSL
All Java processes, including your Diffusion servers include a default JMX connector. This is discrete from the JMX connectors configured in ./etc/Management.xml and is configured via system properties. As of version 5.8 the JMX connectors configured as part of Diffusion cannot handle connections over TLS/SSL. Security is an important concern in production circumstances and when connecting over public networks. This section details configuring the default connector to accept JMX connections over TLS/SSL.
Generating a certificate
Production scenarios will commonly use TLS/SSL to secure communications which mandates an SSL certificate. This is most likely in use on the load balancer as Push advises SSL offloading be performed on the load balancer for performance reasons. If reuse of the SSL certificate is impractical or otherwise impossible generate a self-signed SSL certificate as follows: Generate the private-key/public-key pair:
keytool -genkeypair -alias certificatekey -keyalg RSA -validity 7 -keystore keystore.jks
Enter the required details and this creates a new file keystore.jks holding a single entry of type certificatekey. This is to say that it holds a private key and a certificate (a signed public key). The certificate is signed by itself, rather than by any of the publicly trusted certificating authorities.
Validate it:
keytool -list -v -keystore ./keystore.jks
Once the password is given, the output details the content of the keystore. Keystore Explorer provides similar functionality and may be preferable.
Export the self signed certificate into a Truststore
keytool -export -alias certificatekey -keystore keystore.jks -rfc -file selfsignedcert.cer
keytool -import -alias certificatekey -file selfsignedcert.cer -keystore truststore.jks
The truststore holds only the certificate. It is not used by the server, but by JConsole as we shall see below. The truststore/keystore distinction is an artificial one, as we can see they’re both keystore files.
Configuring the default JMX connector
Configure the following system properties and restart the Diffusion server.
- com.sun.management.jmxremote.port=6789
- com.sun.management.jmxremote.authenticate=false
- com.sun.management.jmxremote.ssl=true
- javax.net.ssl.keyStore=/path/to/the/keystore.jks
- javax.net.ssl.keyStorePassword=secr3t
This is most often done by editing ./bin/diffusion.sh.
Connecting with JConsole
JConsole requires no configuration to use TLS/SSL as JConsole places a secure connection before falling back to an unsecured one. If the certificate provided by the server is signed by a CA then run the following to connect to the JMX connector securely.
jconsole localhost:6789
If the certificate is self signed supply the previously generated truststore on the commandline thus:
jconsole
-J-Djavax.net.ssl.trustStore=/path/to/the/truststore.jks
-J-Djavax.net.ssl.trustStorassword=secr3t localhost:6789
Supplying the truststore containing the certificate is an explicit instruction that it should trusted, even though it is unsigned by a CA.
Connecting to JMX on an AWS Server
When Diffusion is running on an AWS instance the following extra steps need to be performed to enable access to JMX.
- Add ports 1099 and 1100 to AWS security policy
- Change the <host> in ./etc/Management.xml to the public DNS of the AWS instance
- Add to ./bin/diffusion.sh the system property -Djava.rmi.server.hostname=(AWS public DNS)