Terracotta 10.7 | Terracotta Server Administration Guide | Config Tool | Overview
 
Overview
The Config Tool is a command-line utility typically used by administrators of the Terracotta Server Array. It is used to perform a variety of cluster management tasks. The tasks are carried out by executing one or more Config Tool commands against Terracotta servers.
The Config Tool is executed by running the appropriate config-tool script located in the tools/bin folder inside the Terracotta installation directory:
*config-tool.bat - used on Windows platforms
*config-tool.sh - used on Unix/Linux platforms
Config Tool script executions utilize the following syntax:
config-tool.sh|bat [<common_options>] <command> <command_specific_options>
Note that common_options are optional, while one or more of the command_specific_options are required.
Commands
The supported Config Tool commands include:
Command
Description
Activate unconfigured nodes in a cluster.
Attach nodes to a stripe; attach stripes to a cluster.
Detach nodes from a stripe; detach stripes from a cluster.
Read the value of one or more cluster, stripe or node settings in the cluster.
Write a value for one or more cluster, stripe or node settings in the cluster.
Remove a previously set value for one or more cluster, stripe or node settings in the cluster.
Export the complete cluster definition to a configuration properties file.
Import a configuration properties file containing the definition of a cluster and its associated stripes and node.
Retrieve detailed status information for all nodes comprising the cluster.
Repair a node within a cluster which is in an incorrect state.
Retrieve details about all changes made to a node in the cluster.
Refer to the Configuration Terms and Concepts section to gain a deeper understanding of what the Config Tool commands do and under what circumstances you might use them.
Important:
Refer to the Config Tool Troubleshooting Guide when encountering errors that prevent the desired command from executing successfully.
Common Command Options
Each Config Tool command supports a unique set of options (detailed in the sections throughout this document). But all commands support the following common options:
Option
Description
Default
-connection-timeout
Timeout value for connections to be established.
10 seconds
-request-timeout
Timeout value for command requests to be executed.
10 seconds
-security-root-directory
Specifies the location of the security root directory folder. Used to communicate with a server that is configured with any of the supported security schemes (e.g. TLS/SSL). For more details on configuring security in a Terracotta cluster see Security Core Concepts and Cluster Security.
-verbose
Generates a verbose output. Useful for debugging error conditions.
false
-help
Displays help information for commands and their options.
Example Cluster
The Config Tool usage examples used throughout this document reference the example cluster shown below.
*This three-stripe cluster utilizes HA with Stripe-A and Stripe-C employing a single mirror (node2 and node7 respectively) and Stripe-B employing two mirrors (node3 and node4).
*Each node is configured to operate on a distinct port. This is only for illustrative purposes in order to provide clarity when reading the Config Tool commands. In fact, multiple Terracotta servers - each running on a distinct host - may be configured to use the same port, including the default port (9410).
| STRIPE: Stripe-A |
+----------------+----------------+----------------+--------------+
| Node Name | Host-Port | IP Address + Status |
+----------------+----------------+----------------+--------------+
| node1 | host1:9410 | 10.0.0.1 + ACTIVE |
---------------------------------------------------+---------------
| node2 | host2:9412 | 10.0.0.2 + PASSIVE |
+----------------+----------------+----------------+--------------+

| STRIPE: Stripe-B |
+----------------+----------------+----------------+--------------+
| Node Name | Host-Port | IP Address + Status |
+----------------+----------------+----------------+--------------+
| node3 | host3:9413 | 10.0.0.3 + PASSIVE |
---------------------------------------------------+---------------
| node4 | host4:9414 | 10.0.0.4 + PASSIVE |
---------------------------------------------------+---------------
| node5 | host5:9415 | 10.0.0.5 + ACTIVE |
+----------------+----------------+----------------+--------------+

| STRIPE: Stripe-C |
+----------------+----------------+----------------+--------------+
| Node Name | Host-Port | IP Address + Status |
+----------------+----------------+----------------+--------------+
| node6 | host6:9416 | 10.0.0.6 + ACTIVE |
---------------------------------------------------+---------------
| node7 | host7:9417 | 10.0.0.7 + PASSIVE |
+----------------+----------------+----------------+--------------+
Namespace Syntax
Many of the settings permit their values to be accessed (read/write via get, set and unset commands) at different topology levels (i.e. cluster, stripe or node). This is achieved through the use of a namespace syntax where the name of the topology entity is used to qualify the setting’s access level:
[namespace].<setting> --> [(stripe:<stripe_name>: | node:<node_name>:)]<setting>

or

[namespace].<setting> --> [(<stripe_name>: | <node_name>:)]<setting>
The following examples illustrate this namespace usage. For additional details describing this namespace syntax refer to The Terracotta Configuration File.
*Access host7's port setting. The name of host7 is node7:
node:node7.port or node7:port
*Access the backup directories (backup-dir) for all nodes belonging to Stripe-B:
stripe:Stripe-B:backup-dir or Stripe-B:backup-dir
*The log directories (log-dir) for all nodes in the cluster is accessed by NOT including any namespace before the setting:
log-dir
*If a cluster has a node and stripe possessing the same name (e.g. SERVER-A), then accessing a setting at the stripe or node level must incorporate the stripe: qualifier or node: qualifier, otherwise the request would be ambiguous. For example:
node:SERVER-A:backup-dir // the backup directory for node: SERVER-A
stripe:SERVER-A:backup-dir // the backup directory for all nodes belonging to stripe: SERVER-A
SERVER-A:backup-dir // ERROR: because SERVER-A is ambiguous when not qualified