SSL-Secured Monitoring with JMX
The following describes how to set up an SSL-enabled connection for remote monitoring of a Terracotta Server from a simple Java client using Java Management Extensions (JMX) technology.
Before creating this connection, be sure to complete the instructions described in the BigMemory Max Security Guide.
Note: The JMX port configuration of the Terracotta server is disabled by default. To enable it for monitoring with JMX, add jmx-enabled="true" in the <server> element in the Terracotta configuration file tc-config.xml. For example:
<server host="localhost" name="My Server Name1" jmx-enabled="true">
For an alternative to monitoring with JMX, use the monitoring features provided by the Terracotta Management Console (see the Terracotta Management Console User Guide).
Compile the Client
Use the sample client code below, but adapt the host, port, username, and password variables according to your setup.
Note: The JMX port (specified below in the line String port = "9520") should match the JMX port defined in the Terracotta configuration file tc-config.xml (for example, <jmx-port>9520</jmx-port>).
import java.util.HashMap;
import java.util.Map;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
import javax.management.remote.rmi.RMIConnectorServer;
import javax.rmi.ssl.SslRMIClientSocketFactory;
import javax.rmi.ssl.SslRMIServerSocketFactory;
public class Main {
public static void main(String[] args) throws Exception {
String host = "terracotta-server-host";
String port = "9520";
String username = "terracotta";
String password = "terracotta-user-password";
Object[] credentials = { username, password.toCharArray() };
SslRMIClientSocketFactory csf = new SslRMIClientSocketFactory();
SslRMIServerSocketFactory ssf = new SslRMIServerSocketFactory();
Map<String, Object> env = new HashMap<String, Object>();
env.put(RMIConnectorServer.RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE, csf);
env.put(RMIConnectorServer.RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE, ssf);
env.put("com.sun.jndi.rmi.factory.socket", csf);
env.put("jmx.remote.credentials", credentials);
JMXServiceURL serviceURL = new JMXServiceURL("service:jmx:rmi://" +
host + ":" + port +
"/jndi/rmi://" + host + ":" + port + "/jmxrmi");
JMXConnector jmxConnector = JMXConnectorFactory.connect(serviceURL, env);
// do some work with the JMXConnector
jmxConnector.close();
}
}
Run the Client
After compiling your client, configure the JVM with a truststore containing your Terracotta Server's certificate. You can simply re-use the one created for the Terracotta Server (see "Setting Up Server Security" in the BigMemory Max Security Guide).
% java -Djavax.net.ssl.trustStore=/your/path/to/truststore.jks \
-Djavax.net.ssl.trustStorePassword=your_truststore_password \
Main
About the Credentials
In the example above, the client's credentials are encoded as an array of Objects. The Object array contains the username as a String in the array's first slot, and the password as a char[] in the array's second slot. The Object array is then passed to the connection as the "jmx.remote.credentials" entry. Passing the credentials in this format is necessary to avoid an authentication failure, except for the following exception. If you are using the JConsole tool, the credentials are sent as String[]{String,String} instead of String[]{String,char[]}.