This site hosts historical documentation. Visit www.terracotta.org for recent product information.
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.
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.
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 is inconvenient.
Microsoft Windows
[PROMPT] %TERRACOTTA_HOME%\bin\debug-tool.bat <args>
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/debug-tool.sh <args>
where <args> are:
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 cluster-dump.zip which is saved in the working directory.
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.
| See the tim-get guide for detailed usage information |
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.
The Terracotta Developer Console is a graphical tool for monitoring various aspects of your Terracotta cluster for testing and development purposes.
| 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-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>
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/archive-tool.sh <args>
where <args> are:
tc-config.xml)> | <path to data and/or logs directory>| 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:
<servers>
<server host="%i" name="myServer">
<data-backup>/Users/myBackups</data-backup>
<statistics>terracotta/-server/server-statistics</statistics>
<dso>
<persistence>
<mode>permanent-store</mode>
</persistence>
</dso>
</server>
</servers>
| 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>
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/backup-data.sh <hostname> <jmx port>
${TERRACOTTA_HOME}/bin/backup-data.sh localhost 9520
To restore a backup, see the section Restoring a Backup in Terracotta Operations Center.
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.
| 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>
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/run-dgc.sh <hostname> <jmx-port>
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.
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>]
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh [-f <config specification>]
<config specification> can be one of:
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.
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>]
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/stop-tc-server.sh [<server-host> <jmx-port>]
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.
For more information on securing your server for JMX access see the section /tc:tc-config/servers/server/authentication in Configuration Guide and Reference.
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
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/version.sh&
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:
Microsoft Windows
[PROMPT] %TERRACOTTA_HOME%\bin\server-stat.bat <args>
where <args> are:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/server-stat.sh <args>
<args> are the same as shown for Microsoft Windows.
The following example shows usage of and output from the Server Status tool.
[PROMPT] server-stat.sh -s 0.0.0.0:9520
.0.0.health: OK
.0.0.role: ACTIVE
.0.0.state: ACTIVE-COORDINATOR
.0.0.jmxport: 9520
If no server is specified, by default the Server Status checks the status of localhost at JMX port 9520.
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.
| The following subject matter covers aspects of core Terracotta DSO technology. DSO is recommended for advanced users only. |
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
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/platform/tools/pojo/samples.sh&
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] ./make-boot-jar.sh -f ../tc-config.xml
The configuration file found in the current directory.
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.
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 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.
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_INSTALL_DIR=%TERRACOTTA_HOME%
set TC_CONFIG_PATH=<config specification>
call "%TC_INSTALL_DIR%\bin\dso-env.bat" -q
set JAVA_OPTS=%TC_JAVA_OPTS% %JAVA_OPTS%
call "%JAVA_HOME%\bin\java" %JAVA_OPTS% ...
UNIX/Linux
TC_INSTALL_DIR=${TERRACOTTA_HOME}
TC_CONFIG_PATH=<config specification>
. ${TC_INSTALL_DIR}/platform/bin/dso-env.sh -q
JAVA_OPTS="${TC_JAVA_OPTS} ${JAVA_OPTS}"
${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.
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:
[PROMPT] ${TERRACOTTA_HOME}/samples/start-demo-server.sh&
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:
<server host>:<dso-port> of running Terracotta ServerWhen a <config specification> is comprised of a list of configuration sources, the first configuration successfully obtained is used.