Child pages
  • JMX Guide

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Wiki Markup
Wiki Markup

h1. JMX Guide


The Terracotta server publishes a number of MBeans to provide information on the operation of the cluster.  The [Terracotta Developer Console] and the [Terracotta Operations Center] use the JMX interface to provide real-time information, but the same interface can be used by any JMX client.  As of Terracotta 3.0, there is also a new [API to report platform cluster events|Cluster Events] such as client nodes joining or leaving the cluster.

h2. JMX Authentication

It is possible to configure the Terracotta Server to require authentication credentials before JMX communications take place. This will secure server shutdown, the [Terracotta Developer Console], the [Terracotta Operations Center], JConsole, and any other processes attempting to connect via JMX. Server authentication will not provide secure message transmission once valid credentials are provided by a listening client. The JMX messages will not be encrypted. For this reason, we recommend that the Terracotta server be placed in a secure location on a private network and only be queried remotely via an encrypted tunnel such as those provided by stunnel or SSH.

Configuring JMX authentication with Terracotta requires that an authentication element be placed in the Terracotta configuration XML file, read by the Terracotta server instance that requires security. Terracotta relies on the standard Java security mechanisms for JMX which involve the creation of a .access and .password file with correct permissions set. The default location for these files is in (for JDK 1.5+) $JAVA_HOME/jre/lib/management.

Once configured properly, the [Terracotta Developer Console] (or the [Terracotta Operations Center]) connection dialog will prompt you for credentials before completing a server connection. The stop-tc-server script located in the bin directory will also prompt for a username and password.

h3. Configuration
See the [Configuration Guide and Reference|Configuration Guide and Reference#server-authentication] for information on configuring the Terracotta server to use JMX authentication.

h3. Permissions
Setting permissions is done with the files *jmxremote.password* and *jmxremote.access.* Java security is very sensitive to the permission settings of these files so you will need to verify that they are properly set. One caveat to pay attention to is that the files must be owned by the system user who will be executing the Terracotta server. If the Terracotta server runs under the user "tcuser" then you must chown tcuser to change the ownership. The password file is most sensitive and requires:

# chmod 500 jmxremote.password 

-rw-r--r-- 1 tcuser tcuser 2375 Feb 12 18:19 jmxremote.access
-r-x------ 1 tcuser tcuser 2873 Feb 12 18:19 jmxremote.password

NOTE: Setting these permissions on Windows is possible but requires a special DOS command. This permission is only available on Windows drives with NTFS formatting. See for more information.

h3. Users/Groups

You may append to the default files located in $JAVA_HOME/jre/lib/management using the following commands:

# echo "myusername mypassword" >> jmxremote.password
# echo "myusername readwrite" >> jmxremote.access

'myusername' defines the desired username and 'mypassword' defines the desired password. In jmxremote.access, myusername is associated with the username defined in jmxremote.password and must declare readwrite permissions for that group.

{panel:title=Sample excerpt from jmxremote.password}
# Following are two commented-out entries. The "measureRole" role has
# password "QED". The "controlRole" role has password "R&D".
# monitorRole QED
# controlRole R&D
myusername mypassword

{panel:title=Sample excerpt from jmxremote.access}
# Default access control entries:
# o The "monitorRole" role has readonly access.
# o The "controlRole" role has readwrite access.

monitorRole readonly
controlRole readwrite
myusername readwrite

h2. Platform Cluster Events and Cluster Node Data

[*A platform cluster-events API*|Cluster Events] that allows events to be communicated using a standard Java programming approach is available as part of the Terracotta API introduced with Terracotta 3.0.0. This Java-based events API can be more easily integrated into a Java applications environment.

Previous versions of Terracotta relied on JMX-based cluster events. This has caused issues for applications attempting to integrate with Terracotta because most Java applications do not use JMX in this way. Beginning with Terracotta 3.0.0, these JMX-based cluster events are no longer supported.	

Applications that rely on the obsoleted JMX API for cluster events must be rewritten to use the new Java API. Support for the JMX cluster events will be removed without further notice. Application code using the TerracottaCluster mbean or registering notifications with it will receive an UnsupportedOperationException. 

h2. Distributed Garbage Collection
*TODO:* Write me.

h2. Rogue/Slow/Unhealthy Client Detection and monitoring 
RogueA rogue Clientclient is a client which is for some reason not healthy e.g its having a lot of pending transactions or its slow.Terracotta server exposes a list of MBeans to monitor the performance of these clients (like pending transactions) so that one can determine the health of a client and can kill any particular unhealthy client.

Here is some sample code for getting client MBeans
MBeanServerConnection mbsc = null;
JMXConnectorProxy jmxc = new JMXConnectorProxy("localhost", Integer.valueOf(appConfig.getAttribute(JMX_PORT)));
try {
  mbsc = jmxc.getMBeanServerConnection();
} catch (IOException e) {
  throw new AssertionError(e);
DSOMBean dsoMBean = (DSOMBean) MBeanServerInvocationHandler
          .newProxyInstance(mbsc, L2MBeanNames.DSO, DSOMBean.class, false);

ObjectName[] clientObjectNames = dsoMBean.getClients();
DSOClientMBean[] clients = new DSOClientMBean[clientObjectNames.length];
for (int i = 0; i < clients.length; i++) {
  clients[i] = (DSOClientMBean) MBeanServerInvocationHandler.newProxyInstance(mbsc, clientObjectNames[i],DSOClientMBean.class, false);

These are the list of MBeans exposed to monitor these clients. The name of the APIs are self explanatory 

* **&mdash;Is the bean registered
* **&mdash;Get the name(class ObjectName) of this bean
* **&mdash;Get the MBean
* **&mdash;Get the name(class ObjectName) of the instrumentation logging MBean)
* **&mdash;Get the Instrumentation logging MBean
* **&mdash;Get the name(Class ObjectName) of te runtime logging MBean
* **&mdash;Get the run time logging MBean
* **&mdash;Get the name(class ObjectName) of the runtime output options MBean
* **&mdash;Get the runtime output options MBean
* **&mdash;Get the channel ID
* **&mdash;Get the remote address of the channel
* **&mdash;Get the transaction rate for the client
* **&mdash;Get the object fault rate for the client
* **&mdash;Get the object flush rate for the client
* **&mdash;Get the pending transactions count for the client
* **&mdash;Get the statistics for the given properties
* **&mdash;Kill this client
*TODO:* Document the rest of the MBeans.