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.
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-dir | 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>
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