Operational Scripts

Introduction

You, the operator or administrator, can use certain scripts and utilities to help you install, test, and maintain BigMemory. Unless indicated otherwise, these tools are included with the BigMemory kit. Detailed guides exist for some of the tools. Check the entry for a specific tool to see if more documentation is available.

Archive Utility (archive-tool)

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:

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

Database Backup Utility (backup-data)

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.

Configuring Backup

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.

Creating a Backup

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\management-console\bin\backup-data.bat <args>

UNIX/Linux

[PROMPT] ${BIGMEMORY_HOME}/tools/management-console/bin/backup-data.sh <args> 

where <args> are:

• [l] <tms-host:port> – The host and port used to connect to the TMS. If ommitted, http://localhost:9889 is used by default.
• [u] <username> – If the TMS requires authentication, a username must be specified.
• [p] <password> – If the TMS requires authentication, a password must be specified.
• [a] <agentID> – Specify the agent ID of a TSA. The agent ID is set as a connection name when the connection to the TSA is configured on the TMS. If no agent ID is provided, the TMS returns a list of configured agent IDs.
• [k] This flag causes invalid TMS SSL certificates to be ignored.

For example, to initiate a backup on a cluster with the agent ID "someConnection":

${BIGMEMORY_HOME}/tools/management-console/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.

Backup Status (backup-status)

The backup-status script is run from the tools/management-console/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/management-console/bin/backup-status -l http://myTMShost:9889 -a myClusterAgent

The backup-status script takes the same arguments as backup-data.

Cluster Thread and State Dumps (debug-tool, cluster-dump)

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 node's state, including information on locks. Note that these tools can generate a substantial amount of data.

Note: Server utility scripts do not work when a server is starting up or when a server is in the process of recovering using the Fast Restart feature.

For more information on operating these tools, run the associated script with the -h flag. For example:

Microsoft Windows

[PROMPT] %BIGMEMORY_HOME%\tools\management-console\bin\debug-tool.bat -h

UNIX/Linux

[PROMPT] ${BIGMEMORY_HOME}/tools/management-console/bin/debug-tool.sh -h

Distributed Garbage Collector (run-dgc)

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\management-console\bin\run-dgc.bat <args>

UNIX/Linux

[PROMPT] ${BIGMEMORY_HOME}/tools/management-console/bin/run-dgc.sh <args>

where <args> are:

• [l] <tms-host:port> – The host and port used to connect to the TMS. If ommitted, http://localhost:9889 is used by default.
• [u] <username> – If the TMS requires authentication, a username must be specified.
• [p] <password> – If the TMS requires authentication, a password must be specified.
• [a] <agentID> – Specify the agent ID of a TSA. The agent ID is set as a connection name when the connection to the TSA is configured on the TMS. If no agent ID is provided, the TMS returns a list of configured agent IDs.
• [k] This flag causes invalid TMS SSL certificates to be ignored.

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.

For more information on distributed garbage collection, see the TSA architecture guide.

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

Start Server

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:

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

Note the following:

• 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.
• If no server is named, and more than one server exists in the configuration file used, an error is printed to standard out and no server is started.

Stop Server

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:

• [f] <file-or-URL> – Specifies the tc-config file to use, as a file path or URL. For an SSL-secured server, a valid path to the self-signed certificate must have been specified in the server's configuration file.

• [--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. For an SSL-secured server, the user specified must have the “admin” role.
• [w] – Specify the JMX password.

Note: If you are using a self-signed certificate (not one signed by a trusted CA), set the following Java system properties as shown:

• -Dtc.ssl.trustAllCerts=true (use any certificates)
• -Dtc.ssl.disableHostnameVerifier=true (bypass hostname verification)

Server Status (server-stat)

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:

• [-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 specified configuration file.
• [-k] – This flag causes invalid TMS SSL certificates to be ignored. Use this option to accept self-signed certificates (not signed by a trusted CA).

The status tool 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-mirror group. Single servers always show ACTIVE. Backups are shown as MIRROR or PASSIVE.
• State – The work state that the server is in. When ready, active servers should show ACTIVE-COORDINATOR, while mirror servers should show MIRROR-STANDBY or PASSIVE-STANDBY.
• JMX port – The TCP port the server is using to listen for JMX events.
• Error – If the status tool fails, the type of error.

Example

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.

Version Utility (version)

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:

• [r] – Produces detailed, raw information in a "property=value" format.
• [v] – Produces more detailed information.

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.