Terracotta DB 10.1 | Terracotta Server Administration Guide | The Cluster Tool
 
The Cluster Tool
The cluster tool is a command-line utility that allows administrators of the Terracotta Server Array to perform a variety of cluster management tasks. For example, the cluster tool can be used to:
*Configure or re-configure a cluster
*Obtain the status of running servers
*Dump the state of running servers
*Stop the running servers
*Take backups of running servers
*Configure IP white-list based security on running servers
The cluster tool script is located in tools/cluster-tool/bin under the product installation directory as cluster-tool.bat for Windows platforms, and as cluster-tool.sh for Unix/Linux.
Usage Flow
The following is a typical flow in a cluster setup and usage:
1. Create Terracotta configuration files for each stripe in the deployment. See the section The Terracotta Configuration File for details.
2. Start up the servers in each stripe. See the section Starting and Stopping the Terracotta Server for details.
3. Make sure the stripes are online and ready.
4. Configure the cluster using the configure command of the cluster tool. See the section The "configure" Command" below for details.
5. Check the current status of the cluster or specific servers in the cluster using the status command. See the section The "status" Command below for details.
Cluster Tool commands
The cluster tool provides several commands. To list them and their respective options, run cluster-tool.sh (or cluster-tool.bat on Windows) without any arguments, or use the option -h (long option --help). Option -v (long option --verbose) gives you verbose output, and is useful to debug error conditions.
Each command has the option -h (long option --help), which can be used to display the usage for the command.
The following sections give a comprehensive explanation of the available commands.
The "configure" Command
The configure command creates a cluster from Terracotta configuration files and a license. No functionality is available on the server until a valid license is installed. See the section Licensing for details.
All servers in any given stripe should be started with the same configuration file. The configure command configures the cluster based on the configuration(s) of the currently known active server(s) only. If there is a configuration mismatch among the active and passive server(s) within the same stripe, this command can configure the cluster while taking down any passive server(s) with configuration mismatches. This validation also happens upon server restart and changes will prevent the server from starting. See the section on the reconfigure command for more information on how to update server configurations.
The command will fail if any of the following checks do not pass:
1. License checks
a. The license is valid.
b. The provided configuration files do not violate the license.
2. Configuration checks
*The provided configuration files are consistent across all the stripes.
The following items are validated within the plugins section of the configuration files:
1. config:
a. offheap-resources: Offheap resources present in one configuration file must be present in all the files with the same sizes.
b. data-directories: Data directory identifiers present in one configuration file must be present in all the files. However, the data directories they map to can differ.
2. service
* security
*white-list: If this element is present in one configuration file, it must be present in all the files.
*backup-restore: If this element is present in one configuration file, it must be present in all the files.
Refer to the section The Terracotta Configuration File for more information on these plugin elements.
The servers section of the configuration files is also validated. Note that it is not validated between stripes but rather against the configuration used to start the servers themselves.
*server
*host: It must be a strict match
*name: It must be a strict match
*tsa-port: It must be a strict match
Note: Once a cluster is configured, a similar validation will take place upon server restart. It will cause the server to fail to start if there are differences.
Usage:

configure -n CLUSTER-NAME [-l LICENSE-FILE] TC-CONFIG [TC-CONFIG...]
configure -n CLUSTER-NAME [-l LICENSE-FILE] -s HOST[:PORT] [-s HOST[:PORT]]... ]
Parameters:
*-n CLUSTER-NAME: A name that is to be assigned to the cluster.
*-l LICENSE-FILE: The path to the license file. If you omit this option, the cluster tool looks for a license file named license.xml in the location tools/cluster-tool/conf under the product installation directory.
*TC-CONFIG [TC-CONFIG ...]: A whitespace-separated list of configuration files (minimum 1) that describes the stripes to be added to the cluster.
*-s HOST[:PORT] [-s HOST[:PORT]...]: The host:port(s) or host(s) (default port being 9410) of running servers, each specified using the -s option . Any one server from each stripe can be provided. However, multiple servers from the same stripe will work as well. The cluster will be configured with the configurations which were originally used to start the servers.
Note: The command configures the cluster only once. To update the configuration of an already configured cluster, the reconfigure command should be used.
Examples
*The example below shows a successful execution for a two stripe configuration and a valid license.
./cluster-tool.sh configure -l ~/license.xml -n tc-cluster
~/tc-config-stripe-1.xml ~/tc-config-stripe-2.xml
Command completed successfully.

*The example below shows a failed execution because of an invalid license.
./cluster-tool.sh configure -l ~/license.xml
-n tc-cluster ~/tc-config-stripe-1.xml ~/tc-config-stripe-2.xml
Configure a cluster
Usage:
configure -n CLUSTER-NAME [-l LICENSE-FILE] TC-CONFIG [TC-CONFIG...]
configure -n CLUSTER-NAME [-l LICENSE-FILE] -s HOST[:PORT] [-s HOST[:PORT]]... ]
Options:
-h, --help
Help
-l
License file
-n (required)
Cluster name
-s
List of server host:port(s), default port(s) being optional

Error (BAD_REQUEST): com.terracottatech.LicenseException: Invalid license
*The example below shows a failed execution with two stripe configurations mis-matching in their offheap resource sizes.
./cluster-tool.sh configure -n tc-cluster -l
~/license.xml ~/tc-config-stripe-1.xml ~/tc-config-stripe-2.xml
Configure a cluster
Usage:
configure -n CLUSTER-NAME [-l LICENSE-FILE] TC-CONFIG [TC-CONFIG...]
configure -n CLUSTER-NAME [-l LICENSE-FILE] -s HOST[:PORT] [-s HOST[:PORT]]... ]
Options:
-h, --help
Help
-l
License file
-n (required)
Cluster name
-s
List of server host:port(s), default port(s) being optional

Error (BAD_REQUEST): Mismatched off-heap resources in provided config files
(in order): [[primary-server-resource: 64M], [primary-server-resource: 128M]]
The "reconfigure" Command
The reconfigure command updates the configuration of a cluster which was configured using the configure command. With reconfigure, it is possible to:
1. Update the license on the cluster.
2. Add new offheap resources, or grow existing ones.
3. Add new data directories.
4. Change server host, name and/or ports.
The command will fail if any of the following checks do not pass:
1. License checks
a. The new license is valid.
b. The new configuration files do not violate the license.
2. Configuration checks
a. Stripe consistency checks
The new configuration files are consistent across all the stripes. Refer to the above description of the plugins section of the configuration files for details.
b. Offheap checks
The new configuration has all the previously configured offheap resources, and the new sizes are not smaller than the old sizes.
c. Data directories checks
The new configuration has all the previously configured data directory names.
Usage:

reconfigure -n CLUSTER-NAME TC-CONFIG [TC-CONFIG...]
reconfigure -n CLUSTER-NAME -l LICENSE-FILE [ -s HOST[:PORT] | TC-CONFIG [TC-CONFIG...] ]
Parameters:
*-n CLUSTER-NAME: The name of the configured cluster.
*TC-CONFIG [TC-CONFIG ...]: A whitespace-separated list of configuration files (minimum 1) that describe the new configurations for the stripes.
*-l LICENSE-FILE: The path to the new license file.
*-s HOST[:PORT]: A single host:port or host (default port being 9410) of any running server in the cluster.
reconfigure command usage scenarios:
1. License update
When it is required to update the license, most likely because the existing license has expired, the following reconfigure command syntax should be used:
reconfigure -n CLUSTER-NAME -l LICENSE-FILE -s HOST[:PORT]
Note: A license update does not require the servers to be restarted.
2. Configuration update
When it is required to update the cluster configuration, the following reconfigure command syntax should be used:
reconfigure -n CLUSTER-NAME TC-CONFIG [TC-CONFIG...]
The steps below should be followed in order:
a. Update the Terracotta configuration files with the new configuration, ensuring that it meets the reconfiguration criteria mentioned above.
b. Run the reconfigure command with the new configuration files.
c. Restart the servers for the new configuration to take effect.
3. License and configuration update at once
In the rare event that it is desirable to update the license and the cluster configuration in one go, the following reconfigure command syntax should be used:
cluster-tool.sh reconfigure -n
CLUSTER-NAME -l LICENSE-FILE TC-CONFIG [TC-CONFIG...]
The steps to be followed here are the same as those mentioned in the Configuration update section above.
Examples
*The example below shows a successful re-configuration of a two stripe cluster tc-cluster with new stripe configurations.
./cluster-tool.sh reconfigure -n tc-cluster
~/tc-config-stripe-1.xml ~/tc-config-stripe-2.xml
Command completed successfully.
*The example below shows a failed re-configuration because of a license violation.
./cluster-tool.sh reconfigure -n tc-cluster
-l ~/license.xml -s localhost:9410
Prepares the configuration update of a cluster -
requires restart of server(s) with updated configuration(s)
Usage:
reconfigure -n CLUSTER-NAME TC-CONFIG [TC-CONFIG...]
reconfigure -n CLUSTER-NAME -l LICENSE-FILE [ -s HOST[:PORT] | TC-CONFIG [TC-CONFIG...] ]
Options:
-h, --help
Help
-l
License file
-n (required)
Cluster name
-s
Server host:port, default port being optional

Error (BAD_REQUEST): Cluster offheap resource is not within the limit of the license.
Provided: 2000 MB, but license allows: 1000 MB only
*The example below shows a failed re-configuration of a two stripe cluster with new stripe configurations having fewer data directories than existing configuration.
./cluster-tool.sh reconfigure -n tc-cluster
~/tc-config-stripe-1.xml ~/tc-config-stripe-2.xml
Error (CONFLICT): Mismatched data directories. Provided: [use-for-platform, myData],
but previously configured: [use-for-platform, data, myData]
The "status" Command
The status command displays the status of a cluster, or particular server(s) in the same or different clusters..
Usage:
status -n CLUSTER-NAME HOST[:PORT]
status HOST[:PORT] [HOST[:PORT]...]
Parameters:
*-n CLUSTER-NAME HOST[:PORT]: The name of the cluster and the host:port or host (default port being 9410) of a running server in the cluster.
*HOST[:PORT] [HOST[:PORT]…​]: A list of server host:port(s) or host(s) in the same or different clusters, the minimum being one.
Examples
*The example below shows the execution of a cluster-level status command.
./cluster-tool.sh status -n tc-cluster localhost:9410

------------------------------| CLUSTER: tc-cluster |------------------------------

| STRIPE 1 |
Server Name Host:Port Status
----------- --------- ------
server-1 localhost:9410 ACTIVE-COORDINATOR
server-2 localhost:9610 PASSIVE-STANDBY

| STRIPE 2 |
Server Name Host:Port Status
----------- --------- ------
server-3 localhost:9710 ACTIVE-COORDINATOR
server-4 localhost:9910 PASSIVE-STANDBY
*The example below shows the execution of a server-level status command. No server is running at localhost:9510, hence the UNKNOWN status.

./cluster-tool.sh status localhost:9410 localhost:9510 localhost:9910
Host:Port Status
--------- ------
localhost:9410 ACTIVE-COORDINATOR
localhost:9510 UNKNOWN
localhost:9910 PASSIVE-STANDBY
The "dump" Command
The dump command dumps the state of a cluster, or particular server(s) in the same or different clusters. The dump of each server can be found in its logs.
Usage:
dump -n CLUSTER-NAME HOST[:PORT]
dump HOST[:PORT] [HOST[:PORT]...] ]
Parameters:
*-n CLUSTER-NAME HOST[:PORT]: The name of the cluster and the host:port or host (default port being 9410) of a running server in the cluster.
*HOST[:PORT] [HOST[:PORT]…​]: A list of server host:port(s) or host(s) in the same or different clusters, the minimum being one.
Examples
*The example below shows the execution of a cluster-level dump command.
./cluster-tool.sh dump -n tc-cluster localhost

Command completed successfully.
*The example below shows the execution of a server-level dump command. No server is running at localhost:9510, hence the dump failure.
./cluster-tool.sh dump localhost:9410 localhost:9510 localhost:9910
Dump successful for server at: localhost:9410
Connection refused from server at: localhost:9510
Dump successful for server at: localhost:9910
Error (PARTIAL_FAILURE): Command completed with errors.
The "stop" Command
The stop command stops the cluster, or particular server(s) in the same or different clusters.
Usage:
stop -n CLUSTER-NAME HOST[:PORT]
stop HOST[:PORT] [HOST[:PORT]...]
Parameters:
*-n CLUSTER-NAME HOST[:PORT]: The name of the cluster and the host:port or host (default port being 9410) of a running server in the cluster.
*HOST[:PORT] [HOST[:PORT]…​]: A list of server host:port(s) or host(s) in the same or different clusters, the minimum being one.
Examples
*The example below shows the execution of a cluster-level stop command.
./cluster-tool.sh stop -n tc-cluster localhost
Command completed successfully.
*The example below shows the execution of a server-level stop command. No server is running at localhost:9510, hence the stop failure.
./cluster-tool.sh stop localhost:9410 localhost:9510 localhost:9910
Stop successful for server at: localhost:9410
Connection refused from server at: localhost:9510
Stop successful for server at: localhost:9910
Error (PARTIAL_FAILURE): Command completed with errors.
The "ipwhitelist-reload" Command
The ipwhitelist-reload command reloads the IP white-list on a cluster, or particular server(s) in the same or different clusters. See the section IP white-listing for details.
Usage:
ipwhitelist-reload -n CLUSTER-NAME HOST[:PORT]
ipwhitelist-reload HOST[:PORT] [HOST[:PORT]...] ]
Parameters:
*-n CLUSTER-NAME HOST[:PORT]: The name of the cluster and thehost:port or host (default port being 9410) of a running server in the cluster.
*HOST[:PORT] [HOST[:PORT]…​]: A list of server host:port(s) or host(s) in the same or different clusters, the minimum being one.
Examples
*The example below shows the execution of a cluster-level ipwhitelist-reload command.
./cluster-tool.sh ipwhitelist-reload -n tc-cluster localhost
IP white-list reload successful for server at: localhost:9410
IP white-list reload successful for server at: localhost:9610
IP white-list reload successful for server at: localhost:9710
IP white-list reload successful for server at: localhost:9910
Command completed successfully.
*The example below shows the execution of a server-level ipwhitelist-reload command. No server is running at localhost:9510, hence the IP white-list reload failure.
./cluster-tool.sh ipwhitelist-reload
localhost:9410 localhost:9510 localhost:9910
IP white-list reload successful for server at: localhost:9410
Connection refused from server at: localhost:9510
IP white-list reload successful for server at: localhost:9910
Error (PARTIAL_FAILURE): Command completed with errors.
The "backup" Command
The backup command takes a backup of the running Terracotta cluster.
Usage:
cluster-tool.sh backup -n CLUSTER-NAME HOST[:PORT]
Parameters:
*-n CLUSTER-NAME HOST[:PORT]: The name of the cluster and thehost:port or host (default port being 9410) of a running server in the cluster.
*HOST[:PORT]: A singlehost:port or host (default being 9410) of any running server in the cluster.
Note: If there is a problem accessing the given server (for example, a slow network connection or an unknown server), the command times out after 60 seconds.
Examples
*The example below shows the execution of a cluster-level successful backup command.
./cluster-tool.sh backup -n tc-cluster localhost
PHASE 0: SETTING BACKUP NAME TO : 93cdb93d-ad7c-42aa-9479-6efbdd452302
localhost:9410: SUCCESS
localhost:19410: SUCCESS
localhost:9510: SUCCESS
localhost:19510: SUCCESS

PHASE (1/4): PREPARE_FOR_BACKUP
localhost:9410: SUCCESS
localhost:19410: SUCCESS
localhost:9510: NOOP
localhost:19510: NOOP

PHASE (2/4): ENTER_ONLINE_BACKUP_MODE
localhost:9410: SUCCESS
localhost:19410: SUCCESS

PHASE (3/4): START_BACKUP
localhost:9410: SUCCESS
localhost:19410: SUCCESS

PHASE (4/4): EXIT_ONLINE_BACKUP_MODE
localhost:9410: SUCCESS
localhost:19410: SUCCESS
Command completed successfully!
*The example below shows the execution of a cluster-level failed backup command.
./cluster-tool.sh backup -n tc-cluster localhost
PHASE 0: SETTING BACKUP NAME TO : 93cdb93d-ad7c-42aa-9479-6efbdd452302
localhost:9410: SUCCESS
localhost:19410: SUCCESS
localhost:9510: SUCCESS
localhost:19510: SUCCESS

PHASE (1/4): PREPARE_FOR_BACKUP
localhost:9410: SUCCESS
localhost:19410: SUCCESS
localhost:9510: NOOP
localhost:19510: NOOP

PHASE (2/4): ENTER_ONLINE_BACKUP_MODE
localhost:9410: BACKUP_FAILURE
localhost:19410: SUCCESS

PHASE (CLEANUP): ABORT_BACKUP
localhost:9410: SUCCESS
localhost:19410: SUCCESS
Backup failed as some servers '[Server{name='server-1',
host='localhost', port=9410}, [Server{name='server-2',
host='localhost', port=19410}]]', failed to enter online backup mode.
Copyright © 2010-2019 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
Innovation Release