Tools Catalog

Introduction

To help you get the most out of installing, testing, and maintaining Terracotta, many useful tools are included with the Terracotta kit. This page is a comprehensive listing and overview of these tools.

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.

TIM Update Center (tim-get)

The Terracotta Integration Module (TIM) Update Center uses the tim-get script to provide a simple way to manage the catalog of integration modules available for Terracotta.

See the TIM Update Center guide for detailed usage information. See the Terracotta Integration Guides for more information on TIMs and available integrations.

Eclipse Plugin

The Terracotta Eclipse Plugin provides a self-contained Terracotta runtime environment for developing your clustered applications.

See the Eclipse Plugin Guide for detailed installation and feature information. See the Clustering a Simple Swing Application Tutorial for a walk-through clustering a simple POJO using the plug-in.

Sessions Configurator (sessions-configurator)

The Terracotta Sessions Configuration is a graphical tool that assists you in clustering your webapps session data.

See the Terracotta Sessions Quick Start for for detailed installation and feature information.

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. The console can record a number of statistics that can be viewed over time using the Snapshot Visualization Tool (SVT).

See the Terracotta Developer Console for detailed information on the features of the console and SVT.

Welcome Application (welcome)

Terracotta Welcome is a graphical tool that serves as an easy introduction to the Terracotta platform. From Terracotta Welcome you can access the Quick Start Guides, run the POJO Samples Launcher, Developer Console, and Sessions Configurator, as well as read the various tutorials.

The Terracotta Welcome can be run by invoking the welcome script in the bin directory of the Terracotta installation:

Microsoft Windows

> %TERRACOTTA_HOME%\bin\welcome.bat

UNIX/Linux

> ${TERRACOTTA_HOME}/bin/welcome.sh&

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.

Sample Launcher can be accessed directly from Terracotta Welcome or it can be run from the command-line.

Microsoft Windows

> %TERRACOTTA_HOME%\tools\pojo\samples.bat

UNIX/Linux

> ${TERRACOTTA_HOME}/tools/pojo/samples.sh&

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

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

UNIX/Linux

> ${TERRACOTTA_HOME}/bin/archive-tool.sh <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>]

Enterprise Edition Feature

Database Backup Utility (backup-data)

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.

Using the Terracotta Operations Center

Backups can be performed from the Terracotta Operations Center using the Backup feature.

Microsoft Windows

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

UNIX/Linux

> ${TERRACOTTA_HOME}/bin/backup-data.sh <hostname> <jmx port>

Example (UNIX/Linux)

${TERRACOTTA_HOME}/bin/backup-data.sh localhost 9520

To restore a backup, see Restoring a Backup.

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] ./make-boot-jar.sh -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_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}/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.

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:

> ${TERRACOTTA_HOME}/samples/start-demo-server.sh&

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

> cd ${TERRACOTTA_HOME}/samples/pojo/jtable
> ${TERRACOTTA_HOME}/bin/dso-java -cp classes demo.jtable.Main

dso-java uses the 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, e.g.: -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 will be used.

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.

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

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

UNIX/Linux

> ${TERRACOTTA_HOME}/bin/run-dgc.sh <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 the 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

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

UNIX/Linux

> ${TERRACOTTA_HOME}/bin/start-tc-server.sh [-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.

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

Microsoft Windows

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

UNIX/Linux

> ${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.

Further reading:
For more information on securing your server for JMX access see the 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

> %TERRACOTTA_HOME%\bin\version.bat

UNIX/Linux

> ${TERRACOTTA_HOME}/bin/version.sh&

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.

UNIX/Linux

[PROMPT] $\{TERRACOTTA_HOME\}/bin/server-stat.sh <args>

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

Example

This following example displays output from the Server Status tool:

[PROMPT] server-stat.sh -s 0.0.0.0:9520
0.0.0.0.health: OK
0.0.0.0.role: ACTIVE
0.0.0.0.state: ACTIVE-COORDINATOR
0.0.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 Cluster Statistics Recorder CLI.