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 BigMemory. Unless indicated otherwise, these tools are included with the BigMemory kit.
If a tool has a script associated with it, the name of the script (and its path within 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.
archive-tool
is used to gather logs generated by a Terracotta server or client for the purpose of contacting Terracotta with a support query.
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\archive-tool.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/archive-tool.sh <args>
where <args>
are:
The backup utility creates a backup of the data being shared by your application by taking a snapshot of the data held by the Terracotta Server Array (TSA). Unless a different directory is specified in configuration, backups are saved to the default directory ${user.dir}/terracotta/backups
.
You can override this default behavior by specifying a different backup directory in the server's configuration file using the <data-backup>
property:
<servers>
<restartable enabled="true"/>
...
<server host="%i" name="myServer">
...
<data-backup>/Users/myBackups</data-backup>
</server>
...
</servers>
Note that enabling <restartable>
mode is required for using the backup utility.
The backup utility relies on the Terracotta Management Server (TMS) to locate and execute backups. The TMS must be running and connected to the TSA for the backup to take place.
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\tools\security\bin\backup-data.bat <args>
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/backup-data.sh <args>
where <args>
are:
http://localhost:9889
is used by default.For example, to initiate a backup on a cluster with the agent ID "someConnection":
${BIGMEMORY_HOME}/tools/security/bin/backup-data.sh -l http://my-tms-host:9889 \
-u admin -p admin -a someConnection -k
If initiation is successful, the script reports that the backup process has started. Once the backup is complete, the backup data files can be used to restore data in place of the current data files.
The backup-status script is run from the tools/security/bin
directory. This script complements the backup-data utility by checking on the status of executed backups for a specified cluster. For example, to return a list of backup operations on the agent myClusterAgent:
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/backup-status -l http://myTMShost:9889 -a myClusterAgent
The backup-status script takes the same arguments as backup-data.
The cluster and thread- and state-dump debug tools provide a way to easily generate debugging information that can be analyzed locally or forwarded to support personnel. These tools work against the Terracotta Management Server that is monitoring the target Terracotta cluster. All components must be running at the time a tool is used.
debug-tool generates thread dumps for all nodes in the cluster, with each node's dump saved its log file. A flag is available for saving the thread dumps to a single zip file. cluster-dump provides a similar service, but adds each nodes state, including information on locks. Note that these tools can generate a substantial amount of data.
For more information on operating these tools, run the associated script with the -h
flag. For example:
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\tools\security\bin\debug-tool.bat -h
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/debug-tool.sh -h
run-dgc
is a utility that causes the specified cluster to perform distributed garbage collection (DGC). Use run-dgc to force a periodic DGC cycle in environments where inline DGC is not in effect, such as when using Terracotta Toolkit data structures. In most situations, however, automated DGC collection is sufficient for most environments.
This utility relies on the Terracotta Management Server (TMS) to locate and execute backups. The TMS must be running and connected to the TSA for the DGC to be initiated.
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\tools\security\bin\run-dgc.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/tools/security/bin/run-dgc.sh <args>
where <args>
are:
http://localhost:9889
is used by default.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. |
For more information on distributed garbage collection, see the TSA architecture guide.
Use the start-tc-server
script to run the Terracotta Server, optionally specifying a configuration file:
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\start-tc-server.bat ^
[-n <name of server>] [-f <config specification>]
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/start-tc-server.sh \
[-n <name of server>] [-f <config specification>]
<config specification>
can be one of:
Note the following:
tc-config.xml
in the current working directory will be used. tc-config.xml
is found in the current working directory, a default configuration will be used. Use the stop-tc-server
script to cause the Terracotta Server to gracefully terminate:
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\stop-tc-server.bat <host-name> <jmx-port> <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/stop-tc-server.sh <host-name> <jmx-port> <args>
where <args>
are:
<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.
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.
The status tool is a command-line utility for checking the current status of one or more Terracotta server instances.
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\server-stat.bat <args>
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/server-stat.sh <args>
where <args>
are:
The status tool returns the following data on each server it queries:
The following example shows usage of and output from the status tool.
[PROMPT] server-stat.sh -s myhost:9521
localhost.health: OK
localhost.role: ACTIVE
localhost.state: ACTIVE-COORDINATOR
localhost.jmxport: 9521
If no server is specified, by default the tool checks the status of localhost at JMX port 9520.
The version tool is a utility script that outputs information about the BigMemory 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 the version tool to expedite the resolution of your issue.
Microsoft Windows
[PROMPT] %BIGMEMORY_HOME%\server\bin\version.bat
UNIX/Linux
[PROMPT] ${BIGMEMORY_HOME}/server/bin/version.sh&
Use the following flags to produce more information:
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.