Call us: +1-415-738-4000

Terracotta Tools Catalog


A number of useful tools are available to help you get the most out of installing, testing, and maintaining Terracotta. Many of these tools are included with the Terracotta kit, in the bin directory (unless otherwise noted). Some tools are found only in an enterprise version of Terracotta. To learn more about the many benefits of an enterprise version of Terracotta, see Enterprise Products.

If a tool has a script associated with it, the name of the script appears in parentheses in the title for that tool section. The script file extension is .sh for UNIX/Linux and .bat for Microsoft Windows.

Detailed guides exist for some of the tools. Check the entry for a specific tool to see if more documentation is available.

Terracotta Maven Plugin

The Terracotta Maven Plugin allows you to use Maven to install, integrate, update, run, and test your application with Terracotta.

The Terracotta Maven Plugin, along with more documentation, is available from the Terracotta Forge.

Cluster Thread and State Dumps (debug-tool)

The Terracotta thread- and state-dump debug tool provides a way to easily generate debugging information that can be analyzed locally or forwarded to support personnel. The debug tool is useful in cases where firewalls block the use of standard JMX-based tools, or using the Developer Console cannot is inconvenient.

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\debug-tool.bat <args>



where <args> are:

  • [-d] – Takes a full state dump of all nodes in the cluster (servers and clients), logging output to each node's log. Note that the total amount of information generated by this option can be very large.
  • [-h] &ndash Prints brief help information to standard output.
  • [-n] <hostname> – (--hostname) Allows you to specifies a Terracotta server instance in the target cluster. If a host name is not specified with this argument, "localhost" is assumed.
  • [-p] <jmx-port> – (--jmxport) Specifies a JMX port on the target host. If a JMX port i s not specified with this argument, "9520" is assumed.
  • [-u] <string> – (--username) Specifies a JMX username (if JMX authorization is set up).
  • [-w] <string> – (--password) Specifies a JMX password (if JMX authorization is set up).

Running the debug tool without the -d option produces a cluster thread dump (dumps taken from all nodes). The thread dumps are written to a zipped file called which is saved in the working directory.

TIM Management (tim-get)

The tim-get script provides a simple way to update the JARs in the Terracotta kit as well as manage the catalog of available Terracotta integration modules (TIMs) and other JARs.

TIP: tim-get Documentation
See the tim-get guide for detailed usage information

Sessions Configurator (sessions-configurator)

The Terracotta Sessions Configurator is a graphical tool that assists you in clustering your web application's session data.

See the Terracotta Sessions Configurator Guide for for detailed installation and feature information. See Clustering a Spring Web Application for a tutorial on clustering a Spring web application using the Terracotta Sessions Configurator.

Developer Console (dev-console)

The Terracotta Developer Console is a graphical tool for monitoring various aspects of your Terracotta cluster for testing and development purposes.

Operations Center (ops-center)

TIP: Enterprise Feature
Available in Terracotta enterprise editions.

The Terracotta Operations Center is a console for monitoring and managing various aspects of your Terracotta cluster in production.

See the Terracotta Operations Center for detailed information on the features and use of this graphical tool.

Archive Utility (archive-tool)

archive-tool is used to gather filesystem artifacts generated by a Terracotta Server or DSO client application for the purpose of contacting Terracotta with a support query.

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\archive-tool.bat <args>



where <args> are:

  • [-n] (No Data - excludes data files)
  • [-c] (Client - include files from the dso client)
  • <path to terracotta config xml file (tc-config.xml)> | <path to data and/or logs directory>
  • [<output filename in .zip format>]

Database Backup Utility (backup-data)

TIP: Enterprise Feature
Available in Terracotta enterprise editions.

The Terracotta backup utility creates a backup of the data being shared by your application. Backups are saved to the default directory data-backup. Terracotta automatically creates data-backup in the directory containing the Terracotta server's configuration file (tc-config.xml by default).

However, you can override this default behavior by specifying a different backup directory in the server's configuration file using the <data-backup> property:

   <server host="%i" name="myServer">

Using the Terracotta Operations Center

In the example above, persistence mode is configured for permanent-store, which is required to enable backups.

Backups can be performed from the Terracotta Operations Center (ops-center) using the Backup feature.

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\backup-data.bat <hostname> <jmx port>


[PROMPT] ${TERRACOTTA_HOME}/bin/ <hostname> <jmx port>
Example (UNIX/Linux)
${TERRACOTTA_HOME}/bin/ localhost 9520

To restore a backup, see the section Restoring a Backup in Terracotta Operations Center.

Distributed Garbage Collector (run-dgc)

run-dgc is a utility that causes the specified Terracotta Server to perform distributed garbage collection (DGC). Use run-dgc to force a DGC cycle in addition to or instead of automated DGC cycles. Forced DGC cycles can also be initiated from the Terracotta Developer Console and the Terracotta Operations Center.

NOTE: Running Concurrent DGC Cycles
Two DGC cycles cannot run at the same time. Attempting to run a DGC cycle on a server while another DGC cycle is in progress generates an error.

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\run-dgc.bat <hostname> <jmx-port>


[PROMPT] ${TERRACOTTA_HOME}/bin/ <hostname> <jmx-port>

Further Reading

For more information on distributed garbage collection, see the Concept and Architecture Guide and the Tuning Guide.

For information on monitoring the Terracotta Server's garbage collection, see Terracotta Developer Console.

Start and Stop Server Scripts (start-tc-server, stop-tc-server)

Use the start-tc-server script to run the Terracotta Server, optionally specifying a configuration file:

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\start-tc-server.bat [-f <config specification>]


[PROMPT] ${TERRACOTTA_HOME}/bin/ [-f <config specification>]

<config specification> can be one of:

  • path to configuration file
  • URL to configuration file
  • <server host>:<dso-port> of another running Terracotta Server

If no configuration is specified, a file named tc-config.xml in the current working directory will be used. If no configuration is specified and no file named tc-config.xml is found in the current working directory, a default configuration will be used. The default configuration includes no DSO application element and is therefor useful only in development mode, where each DSO client provides it's own configuration.

For production purposes, DSO clients should obtain their configuration from a Terracotta Server using the tc.config system property.

stop-tc-server uses JMX to ask the server to terminate. If you have secured your server, requiring authenticated access, you will be prompted for a password.

If the stop-tc-server script detects that the passive server in STANDBY state isn't reachable, it issues a warning and fails to shut down the active server. If failover is not a concern, you can override this behavior with the --force flag.

Use the stop-tc-server script to cause the Terracotta Server to gracefully terminate:

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\stop-tc-server.bat [<server-host> <jmx-port>]


[PROMPT] ${TERRACOTTA_HOME}/bin/ [<server-host> <jmx-port>]

where <args> are:

  • [f] <file-or-URL> – Specifies the configuration file to use, as a file path or URL.
  • [--force] – Force shutdown of the active server.

    In production mode, if the stop-tc-server script detects that the mirror server in STANDBY state isn't reachable, it issues a warning and fails to shut down the active server. If failover is not a concern, you can override this behavior with the --force flag.

  • [n] <server-name> – The name of the server to shut down. Defaults to the local host.

  • [s] – If the server is secured with a JMX password, then a username and password must be passed into the script.
  • [u] – Specify the JMX username.
  • [w] – Specify the JMX password.

Stopping an SSL-Secured Server

Stop a server in a secure Terracotta cluster using the stop-tc-server script with the following arguments:

  • -f <tc-config-file> — A valid path to the self-signed certificate must have been specified in the server's configuration file.
  • -u <username> — The user specified must have the "admin" role.
  • -w <password>

For more information, refer to Setting Up Server Security.

Further Reading

For more information on securing your server for JMX access see the section /tc:tc-config/servers/server/authentication in Configuration Guide and Reference.

Version Utility (version)

Terracotta Version Tool is a utility script that outputs information about the Terracotta installation, including the version, date, and version-control change number from which the installation was created. When contacting Terracotta with a support query, please include the output from Version Tool to expedite the resolution of your issue.

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\bin\version.bat



Server Status (server-stat)

The Server Status tool is a command-line utility for checking the current status of one or more Terracotta servers instances.

Server Status returns the following data on each server it queries:

  • Health – OK (server responding normally) or FAILED (connection failed or server not responding correctly).
  • Role – The server's position in an active-passive group. Single servers always show ACTIVE. "Hot standbys" are shown as PASSIVE.
  • State – The work state that the server is in.
  • JMX port – The TCP port the server is using to listen for JMX events.
  • Error – If the Server Status tool fails, the type of error.
  • Microsoft Windows

    [PROMPT] %TERRACOTTA_HOME%\bin\server-stat.bat <args>

where <args> are:

  • [-s] host1,host2,... – Check one or more servers using the given hostnames or IP addresses using the default JMX port (9520).
  • [-s] host1:9520,host2:9521,... – Check one or more servers using the given hostnames or IP addresses with JMX port specified.
  • [-f] <path>/tc-config.xml – Check the servers defined in the current Terracotta configuration file.
  • [-h] – Display help on Server Status.



<args> are the same as shown for Microsoft Windows.


The following example shows usage of and output from the Server Status tool.

.0.0.role: ACTIVE
.0.0.jmxport: 9520

If no server is specified, by default the Server Status checks the status of localhost at JMX port 9520.

Cluster Statistics Recorder (tc-stats)

The Terracotta Cluster Statistics Recorder allows you to configure and manage the recording of statistics for your entire cluster. The Cluster Statistics Recorder has a command-line interface (CLI) useful for scripting statistics-gathering operations. For more information, see the section Command-Line Interface in the Platform Statistics Recorder Guide.

DSO Tools

The following subject matter covers aspects of core Terracotta DSO technology. DSO is recommended for *advanced users only*.

Sample Launcher (samples)

Terracotta Sample Launcher is a graphical tool that provides an easy way to run the Terracotta for POJO samples in a point-and-click manner. When run, Sample Launcher automatically starts up the demo Terracotta Server, which it also shuts down upon termination. A selection of samples demonstrating POJO clustering are listed and can be launched. Descriptions of each sample, including information about how to run the sample from the command-line, as well as sample code and configuration can be browsed.

Run Sample Launcher from the command line.

Microsoft Windows

[PROMPT] %TERRACOTTA_HOME%\platform\tools\pojo\samples.bat


[PROMPT] ${TERRACOTTA_HOME}/platform/tools/pojo/

Make Boot Jar Utility (make-boot-jar)

The make-boot-jar script generates a boot jar file based on the contents of the Terracotta configuration file, determined in the following order:

  • The configuration file specified by -f. For example:

    [PROMPT] ./ -f ../tc-config.xml
  • The configuration file found in the current directory.

  • The default Terracotta configuration file.

If the boot jar exists, make-boot-jar re-creates the boot jar only if it needs to be re-created. It can be forced to create one by passing the -w option. It returns with exit code 1 if the boot jar file is incomplete, otherwise the exit code is 0.

Scan Boot Jar Utility (scan-boot-jar)

The scan-boot-jar script verifies the contents of the boot jar file against an L1 configuration. It will list all of the classes declared in the <additional-boot-jar-classes/> section that is not included in the boot jar, as well as classes in the boot jar that is not listed in the <additional-boot-jar-classes/> section. It returns with exit code 1 if the boot jar file is incomplete, otherwise the exit code is 0.

Boot Jar Path Utility (boot-jar-path)

boot-jar-path is a helper utility used by the dso-env script for determining the full path to the JVM-specific DSO bootjar. This script is not meant to be used directly.

DSO Environment Setter (dso-env)

The dso-env script helps you set up your environment to run a DSO client application, using existing environment variables and setting TC_JAVA_OPTS to a value you can pass to java. It expects JAVA_HOME, TC_INSTALL_DIR, and TC_CONFIG_PATH to be set prior to invocation. dso-env is meant to be executed by your custom startup scripts, and is also used by each Terracotta demo script.

Microsoft Windows

set TC_CONFIG_PATH=<config specification>
call "%TC_INSTALL_DIR%\bin\dso-env.bat" -q
call "%JAVA_HOME%\bin\java" %JAVA_OPTS% ...


TC_CONFIG_PATH=<config specification>
. ${TC_INSTALL_DIR}/platform/bin/ -q
${JAVA_HOME}/bin/java ${JAVA_OPTS} ...

<config specification> above is either the path to a local config file or a <server>:<dso-port> tuple specifying the configuration of a running Terracotta Server. If the config specification is not set, an existing file in the current working directory named tc-config.xml will be used. If no config is specified and no local tc-config.xml is found, the Terracotta runtime will fail to start.

Java Wrapper (dso-java)

dso-java is a script that can be used to run a DSO client application in a manner similar to running a standard java application. For instance, one way to run the jtable POJO sample is to first run the demo server:


then change into the jtable directory and invoke dso-java in the following way:

[PROMPT] cd ${TERRACOTTA_HOME}/samples/pojo/jtable
[PROMPT] ${TERRACOTTA_HOME}/platform/bin/dso-java -cp classes demo.jtable.Main

dso-java uses the DSO Environment Setter (dso-env) helper script to specify the Java runtime options needed to activate the Terracotta runtime. The configuration file, tc-config.xml, is located in the current working directory. If the configuration file was in a different location, specify that location using the tc.config Java system property:

-Dtc.config=<config specification>

<config specification> is a comma-separated list of:

  • path to configuration file
  • URL to configuration file
  • <server host>:<dso-port> of running Terracotta Server

When a <config specification> is comprised of a list of configuration sources, the first configuration successfully obtained is used.