The pros and cons of using Tomcat JMX

If you're an administrator of a large, enterprise-level installation of Tomcat, you've probably realized that the more Tomcat servers you add to your infrastructure, the more important it becomes to have a reliable, hassle-free, and powerful system of managing your network.  

You may have tried to supplement Tomcat Manager's administrative capabilities with custom command line scripts, in which case you've most likely found yourself frustrated with the clumsiness of this solution.  You're tired of worrying about SSH keys, cobbled together scripts, and lack of documentation when something breaks.  It's time for a management solution that makes you feel more like an administrator and less like Mr. Fix-It.

Need real control over your enterprise Tomcat infrastructure?  Tcat Server is a lifesaver for administrators. Download Tcat Server today.

Managing Tomcat with JMX

Java Management Extensions, or JMX, is a Java technology designed for remote administration and monitoring of Java components.  All versions of Tomcat 5.x or later natively support the JMX protocol.  In fact, the Tomcat Manager includes a lightweight JMX HTTP proxy, which allows simple commands to be run through URI requests.    

In this article, we'll look at ways you can integrate JMX into your Tomcat administration scheme.  We'll start with a basic overview of how JMX works, get Tomcat and JMX talking to one another, and look at some sample administrative applications.  We'll also look at some of the limitations of using JMX as your only administrative solution, and explore some additional schemes that will deliver the kind of elegant administrative power you're looking for.

Understanding Java management extensions

The simplest way to understand the way that JMX works is to pide its functionality into three layers: the Instrumentation Level, the Agent Level, and the Remote Management Level.   

The Instrumentation Level contains the components and resources that you would like to manage.  These resources are represented by one or more specialized JavaBeans known as Managed Beans, or MBeans for short.  MBeans are Java Beans that implement additional components which allow them to be managed and monitored via the JMX framework.  Each MBean represents a single resource running on the JVM, which is exposed for remote management using JMX.

There are a few different types of MBeans, each with different functionalities, which offer a greater degree flexibility when designing your administrative framework.  Any MBean that you wish to expose is registered with the MBeanServer, which makes up JMX's Agent Level.

The Agent Level is composed of an intermediate agent called MBeanServer.  The job of this layer is to receive requests or commands from the Remote Management Level, and relay them to the appropriate MBean.  It also can receive notifications from its MBeans, such as state changes, and forward them to the Remote Management Layer.

The Remote Management Layer is made up of client programs, connectors, and adaptors, and allows the user to send requests to the Agent layer for relay and receive the results of these requests.  Users can connect to the MBeanServer either through a connector, using a client program such as JConsole and a protocol such as RMI or IIOP, or through an adaptor, which adapts the MBeanServer API to another protocol, such as HTTP, allowing JMX to be used with custom web-based GUIs.

In summary, a user at the Remote Management Level sends a request or command to the Agent Level, which contacts the appropriate MBean at the Instrumentation Level, and relays the response back to the user.  

This distributed system allows users to build highly customized administrative frameworks from scratch.

Getting JMX talking to Tomcat

Now that we understand what JMX is and how it works, let's get it talking to Apache Tomcat.  Although JMX was first supported in Tomcat 4.1, as of Tomcat 5, support for JMX administration has been explicitly built into Catalina.  This means means that once you've enabled JMX connections, you'll immediately have access to all Tomcat's standard internal components.  

Exposing Catalina as an MBean is a matter of starting Tomcat with appropriate start-up switches by editing the JAVA_OPTS environment variable.

If you are only planning on using JMX to monitor Tomcat in a local network setting, use the following settings:

  JAVA_OPTS=" \ \


However, if you're reading this article, you're most likely looking for a solution that you can use from any location to monitor your servers, in which case you'll need to enable remote connections, and configure security to keep your network information private.  To do so, use the following settings, substituting the appropriate port numbers and paths:


  -Dcom.sun.mangement.jmxremote.ssl=false \ \"

  You can place the password and permissions files in any logical location, such as "$CATALINA_HOME/conf/".

Make sure to modify the permissions of these files so that they can only be viewed by users with appropriate access:

  $ chmod 600 /path/to/pw/file

  $ chmod 600 /path/to/access/file

Restart Tomcat and run a client program such as JConsole.  Enter your server information and attempt to connect.  If you are successful, JMX has been configured correctly, and you should be able to start exploring the kinds of data offered by JMX management.

Using JMXProxy

As mentioned earlier, Tomcat Manager contains a lightweight servlet called JMXProxy, which can be used to send JMX commands and queries in a URI format.  Though it is not particularly user-friendly, it can be very useful if you want to quickly send commands and queries in an integrated format.  Here's an overview of JMXProxy's command syntax.

The Query command

This command uses the syntax "http:/yourhost/manager/jmxproxy/?qry=YOURQUERY".

YOURQUERY represents the specific JMX command you wish to send.  

As an example, let's assume you have a web application named "myapp", with a JDNI environment string of "i/need".  

A simple JMXProxy search command for this value would look like this:


This command might return the following information:


  modelerType: org.apache.catalina.mbeans.ContextEnvironmentMBean

  className: org.apache.catalina.deploy.ContextEnvironment

  name: i/need

  override: false

  type: java.lang.String

  value: less cowbell

Setting values

Now let's assume you want to set the value "less cowbell" to "more cowbell".  The JMXProxy string you would use to accomplish this looks like this:


More information on using JMXProxy can be found in the Apache Tomcat Manager Documentation.

Enabling JMX lifecycle listeners

If you are running Tomcat 5.5.25 or later, you can enable JMX adaptors on a Server by Server basis by using the JMXAdaptorLifecycleListener class.  This will allow you to automatically start a JMX Adaptor with naming and port pre-configured simply by editing your server.xml file.

Before you can use it, you'll have to build the class from the Tomcat source tree and move it to the copy it to the correct location.

After making sure that CATALINA_HOME is set to the root of your unpacked Tomcat 5.5.x binary, build the JMXAdaptorLifecycleListener class using the following command:

  $ javac -classpath $CATALINA_HOME/server/lib/catalina.jar:$CATALINA_HOME/bin/commons-logging-api-1.1.1.jar container/catalina/src/share/org/apache/catalina/mbeans/

Next, copy the resulting class file into place using these two commands:

  mkdir -p $CATALINA_HOME/server/lib/org/apache/catalina/mbeans

  cp container/catalina/src/share/org/apache/catalina/mbeans/JMXAdaptorLifecycleListener.class $CATALINA_HOME/server/lib/org/apache/catalina/mbeans

Now you can nest the JMXAdaptorLifecycleListener in any Server component, using the following syntax, substituting the appropriate attribute values:

  <Server ...>


  <Listener className="org.apache.catalina.mbeans.JMXAdaptorLifecycleListener"

  namingPort="8083" port="8084" host="myhost" /> 



To run methods against these listeners, run jconsole with the following options, substituting the appropriate values:

  jconsole service:jmx:rmi/myhost:8084/jndi/rmi:/myhost:8083/server

Using JSP with JMX

One method of utilizing JMX capabilities after you have enabled them in Tomcat is to use JSP to create web-based methods of calling and dynamically displaying data obtained through JMX.  As an example of this, here is a simple use of JSP to test that JMX has been configured correctly:

  %@ page import="java.util.*,*" %>

JMX testing..


    ArrayList list = MBeanServerFactory.findMBeanServer(null);

    MBeanServer mbeanServer = (MBeanServer) list.get(0);

    out.print("MBeanServer: " + mbeanServer + "<br>");

    String domain = mbeanServer.getDefaultDomain();

    out.print("Default domain: " + domain + "<br>");

    Set namesSet = mbeanServer.queryNames(null, null);

    Object[] objectNames = namesSet.toArray();

    for (int x = 0; x < objectNames.length; x++)


        out.print(objectNames[x] + "<br>");



If JMX has been configured correctly, this JSP will return a list of all available MBeans.  Otherwise, it will return an error.  You can use JSP in conjunction with JMX to build custom tools to quickly obtain information about your Tomcat servers.

Limitations of JMX management

Now that we've explored some of the ways that using JMX can help you administrate your Tomcat servers, let's look at some of the reasons why JMX may not be the total solution you are looking for.

Lack of Security

Ideally, if you're managing large-scale Tomcat infrastructures, you will want to use JMX to handle both application management and monitoring, and also to control large clusters of Tomcat servers.  

However, putting all that power on the back of a custom-built administration system raises some significant security concerns.  The most compelling of these is that you'll be responsible for understanding and patching all the holes.  While it may be possible to secure JMX to a level suitable for Enterprise Tomcat administration, there isn't much of a precedent for it, and so if your system is compromised, you're on your own.

You have to build from scratch

When managing Enterprise-level infrastructures, you want streamlined, well-documented, and reliable systems that make your job as an administrator less complicated, instead of adding to your workload.  

While JMX is a very flexible system, allowing for very elegant and specialized solutions to be built, someone still has to build these systems, document them, keep them updated, and be prepared to change them as the needs of the site change over time.  Advanced features such as cluster control will have to be custom built.  All that work means a lot of developer hours.

Limited JVM visibility

While JMX can give you some information about the JVM, it may not be enough to diagnose your application problems.  Let's say you're tuning Tomcat memory allocation for a certain application, which is running on a cluster.  To test real-time load using JMX, you'd have to wrangle some kind of solution that would query each server, come up with a way to display the information graphically in a useful manner, and then manually edit the configuration files of each Tomcat instance.   

The solution: MuleSoft Tcat server

MuleSoft Tcat Server makes Enterprise-Level Tomcat administration simple right out of the box.  


Running in front of your existing Tomcat infrastructure, Tcat Server delivers all the Enterprise-Level administrative power you could ever need, including: 

  • advanced deployment tools with rollback capabilities 
  • deep diagnostics 
  • configuration management - save a configuration profile and apply it to new servers with one click 
  • reliable restarts
  • API integration into your existing processes
  • comprehensive support and documentation 

Tcat Server is a lifesaver for administrators - download Tcat Server today!