Call us: +1-415-738-4000

The Terracotta Management Console


The Terracotta Management Console (TMC) is a web-based administration and monitoring application with the following advantages:

  • Multi-level security architecture, with end-to-end SSL secure connections available
  • Feature-rich and easy-to-use interface
  • Remote management capabilities requiring only a web browser and network connection
  • Cross-platform deployment
  • Role-based authentication and authorization
  • Support for LDAP directories and Microsoft Active Directory
  • Aggregate statistics from multiple nodes
  • Flexible deployment model, which can plug into both development environments and secure production architectures

The TMC can monitor BigMemory nodes and clusters through the Terracotta Management Server (TMS). The TMS acts as an aggregator and also provides a connection and security context for the TMC. The TMS must be available and accessible for the TMC to provide management services.

The TMS is included with your BigMemory kit under the tools/management-console directory.

For more information on using the TMC, see:

Installing and Configuring the TMS

The TMS files are stored in the BigMemory kit's management-console directory. Copy this directory to the location where the TMS will run, then place a copy of the license file inside the management-console directory.

Running With a Different Container

The TMS can be run directly with the provided Jetty Java Servlet container. To run it with an application server of your choice, use the file management-console/webapps/tmc.war. Follow the specifications and requirements of your chosen application server for deploying a WAR-based application.


A Terracotta BigMemory Max cluster can be managed directly by connecting the TMC to any one of the servers in the cluster. All other servers and clients become visible to the TMC through that initial connection. Create a new connection and enter the URI to a server in the following form:


To manage a client or standalone node (Terracotta Ehcache client or BigMemory Go) using the TMC, enable the REST management service on that node by setting the following element in the ehcache.xml configuration:

<ehcache ... >
  <managementRESTService enabled="true" bind="<ip_address>:<port>"/>

where <ip_address> is the local network interface's IP address and <port> is the port number used to manage the node. The following defaults are in effect for <managementRESTService>:

  • enabled="false" (This must be set to "true" for standalone caches)
  • bind="" (This IP address binds the specified port all network interfaces on the local node)

The REST management service can also be enabled programmatically:

ManagementRESTServiceConfiguration rest = new ManagementRESTServiceConfiguration(); 

Note: If performance becomes an issue when the TMC is in heavy use, see "Number of Clients Impacts Performance" in TMS Troubleshooting.

Displaying Update Statistics

By default, caches distributed in BigMemory Max generate put events whenever elements are put or updated. To have the TMC track and display updates separately from puts, set the Terracotta property ehcache.clusteredStore.checkContainsKeyOnPut at the top of the Terracotta configuration file (tc-config.xml by default) before starting the Terracotta Server Array:

  <property name="ehcache.clusteredStore.checkContainsKeyOnPut" value="true" />

Enabling this property can substantially degrade performance. Before using in production, test the effect of enabling this property.

Using Multiple Instances of BigMemory Go CacheManagers With the TMC

When loading multiple instances of BigMemory Go CacheManagers with the TMC rest agent enabled in the same JVM, CacheManagers must be loaded by distinct classloaders. Two different web applications (two different WARs), for example, are loaded by two different classloaders.

The TMC Update Checker

The Update Checker automatically checks to see if you have the latest updates, and collects diagnostic information on TMC usage. The Update Checker is on by default. To disable the update checker, use the following system property:

Starting and Connecting to the TMC

Start the TMC by running the following script:


To stop the TMC, use the following script:


Note: The TMC requires that the path have no spaces.

For Microsoft Windows, use start.bat and stop.bat, available in the same directory.

Connect to the TMC using the following URI with a standard web browser:


If you are connecting remotely, substitute the appropriate hostname. If you have set up secure browser connections, use "https:" instead of "http:".

When you first connect to the TMC, the security setup page appears, where you can choose to run the TMC with or without authentication. Authentication can also be enabled/disabled in the TMC Settings panel. For more information, seeSecurity Setup.

For more information on using the TMC, click the Help links available on certain pages within the UI, or access the TMC online help by choosing Help from the toolbar.

Updating the TMS

Installing a new version of a Terracotta kit also installs an updated version of the TMS. When this new version is started, it checks for existing configuration files under <user.home>/.tc/mgmt, backing up any incompatible files (extension .bak). In this case, previously configured connections will not appear in the TMC and must be re-added.

Uninstalling the TMC

If you want to remove the Terracotta Managment Console, delete the ~/.tc/mgmt/ directory.