Performing configuration changes
Examples shown in this section follow the
Namespace Syntax where the
namespace determines the scope of the
get,
set and
unset commands. The formats are:
stripe.<stripeId>.node.<nodeId> to read/write settings for a single, specific node.
stripe.<stripeId> to read/write settings for all nodes within a stripe.
no namespace to read/write settings for all nodes of the cluster.
Note:
Refer to
Configuration Rules for UNCONFIGURED (not Activated) Nodes and Clusters and
Configuration Rules for CONFIGURED (Activated) Nodes and Clusters to understand exactly which of
get,
set and
unset are supported for each setting and at what cluster/stripe/node scope they are supported.
Note:
The get, set, and unset commands support specifying multiple setting <setting> parameters on the command line in order to read/write multiple settings simultaneously. Together, these settings constitute a change-set which is applied transactionally (i.e. applied fully or not applied at all).
Get
The get command is used to read the configuration data that defines the cluster, its stripes, and their nodes.
Syntax:
get -connect-to <hostname[:port]> [-runtime] [-output-format <cfg|properties>] -setting <[namespace:]setting> -setting <[namespace:]setting> ...
Option | Description |
-connect-to <hostname[:port] | Terracotta server instance to which the Config Tool will connect and execute the command. |
-setting <[namespace:]setting> -setting <[namespace:]setting> … | List of settings for which to retrieve the values. |
-runtime | Returns the current, runtime values of the specified setting(s). When using this option, the connect-to node should be the node for which you wish to retrieve the runtime values. |
Examples
1. Get the offheap-resources cluster-wide setting:
config-tool.sh get -connect-to host2:9412 -setting offheap-resources
2. Get each offheap-resource separately (there are two in our example cluster):
config-tool.sh get -connect-to host2:9412 -setting offheap-resources.main -setting offheap-resources.other
offheap-resources.main=512MB
offheap-resources.other=512MB
3. Get the cluster-name:
config-tool.sh get -connect-to host2:9412 -setting cluster-name
4. Get the hostname for all nodes in Stripe-B:
config-tool.sh get -connect-to host2:9412 -setting Stripe-B:hostname
node:node3:hostname=host3
node:node4:hostname=host4
node:node5:hostname=host5
5. Get the log-dir location belonging to node7 :
config-tool.sh get -connect-to host2:9412 -setting node7:log-dir
6. Get the runtime value for a setting.
In this example we assume the log directory for node7 was previously updated to dirs\node7\logs\updated. But the node was not restarted, which is required for the change to take effect. In this case, since the node was not restarted, the current runtime log directory will continue to use the original folder location until the node is restarted. We can see this by querying for log-dir using the runtime option:
config-tool.sh get -connect-to host7:9417 -setting node7:log-dir -runtime
Without specifying the runtime option, the updated value will be returned:
config-tool.sh get -connect-to host7:9417 -setting node7:log-dir
Note:
Whenever querying for a particular node's runtime setting value, the connect-to server should always be that particular node. For example, in the previous example, we queried for the node7 runtime value using the stripe.3.node.2 namespace. Therefore, we needed to connect-to node7 as host7:9417. We could have connected-to any node in the cluster. But any node other than node7 would have returned the updated setting value, even if we had specified the runtime option.
Set
The set command is used to make configuration changes for the cluster, its stripes, and their nodes by writing values for the various supported settings.
Syntax:
set -connect-to <hostname[:port]> -setting <[namespace:]setting=value> -setting <[namespace:]setting=value> ...
Option | Description |
-connect-to <hostname[:port] | Terracotta server instance to which the Config Tool will connect and execute the command. |
-setting <[namespace:]setting =value> -setting <[namespace:]setting=value> … | List of settings and their values to set. |
-auto-restart | Will automatically restart passive servers then active servers if a change requires some nodes to be restarted |
-restart-wait-time <duration> | Maximum time to wait for the nodes to restart. Default: 120 seconds. |
-restart-delay <duration> | Delay before the server restarts itself. Default: 2 seconds. |
Examples
1. Change the name of the cluster:
config-tool.sh set -connect-to host3:9413 -setting cluster-name=MyCluster
2. Establish a new offheap resource:
config-tool.sh set -connect-to host3:9413 -setting offheap-resources.other=512MB
3. Simultaneously update the size of each of the cluster's offheap resources:
config-tool.sh set -connect-to host4:9414 -setting offheap-resources.main=1GB -setting offheap-resources.other=1GB
4. Configure the cluster's failover priority (consistency) to include 1 voter. Refer to
Failover Tuning.
config-tool.sh set -connect-to host4:9414 -setting failover-priority=consistency:1
5. Attempt to change the name for node4 (post activation):
config-tool.sh set -connect-to host1:9410 -setting node4:name=new-node4-name
Error: Invalid input: 'node4:name=new-node4-name'. Reason: Setting 'name' cannot be set when node is activated
6. Update a cluster's license
config-tool.sh set -connect-to host1:9410 -setting license-file=path/to/license.xml
It is also possible to remove an installed license file. For example, a misplaced license file can be removed using:
config-tool.sh unset -connect-to host1:9410 -setting license-file
Pay attention that if a license file is removed from an activated cluster with some connected clients, some features could then be refused and clients could malfunction because the cluster would become unlicensed.
7. Configure SSL/TLS security for the cluster. Note that in this example, every node in the cluster is assigned the same security root directory path on their local nodes:
config-tool.sh set -connect-to host1:9410 -setting security-dir=path/to/server/security-dir
-setting authc=certificate -setting ssl-tls=true
8. After having configured security for our cluster in the previous example, we now set the backup directories for all seven nodes of our
example cluster to a unique folder location. In this example, we
connect-to a node using a secure connection:
config-tool.sh -security-root-directory path/to/client/security-root-directory set
-connect-to host1:9410 -setting node1:backup-dir=node1/backup/folder
-setting node2:backup-dir=node2/backup/folder
-setting node3:backup-dir=node3/backup/folder
-setting node4:backup-dir=node4/backup/folder
-setting node5:backup-dir=node5/backup/folder
-setting node6:backup-dir=node6/backup/folder
-setting node7:backup-dir=node7/backup/folder
Unset
The unset command is used to remove (i.e. undo) previously configured setting for the cluster, its stripes, and their nodes.
Syntax:
unset -connect-to <hostname[:port]> -setting <[namespace:]setting> -setting <[namespace:]setting> ... [-auto-restart] [-restart-wait-time <duration>] [-restart-delay <duration>]
Option | Description |
-connect-to <hostname[:port] | Terracotta server instance to which the Config Tool will connect and execute the command. |
-setting <[namespace:]setting> -setting <[namespace:]setting> … | List of settings and their values to unset. |
-auto-restart | Will automatically restart passive servers then active servers if a change requires some nodes to be restarted. |
-restart-wait-time <duration> | Maximum time to wait for the nodes to restart. Default: 120 seconds. |
-restart-delay <duration> | Delay before the server restarts itself. Default: 2 seconds. |
Examples
1. Remove logger-overrides for a particular node:
config-tool.sh unset -connect-to host1:9410 -setting node1:logger-overrides
2. Remove the backup directory configuration from each node in the cluster:
config-tool.sh unset -connect-to host1:9410 -setting backup-dir
3. When configured as a secure cluster, the audit log directory is an optional, all-or-none setting. Here we remove the audit log directory configuration from all nodes in the cluster.
config-tool.sh -security-root-directory path/to/client/security-root-directory unset -connect-to host1:9410 -setting audit-log-dir
Export
The export command is used to export all information pertaining to the cluster, its stripes, and their nodes.
Syntax:
export -connect-to <hostname[:port]> [-output-file <config-file>] [-include-defaults] [-runtime]
Option | Description |
-connect-to <hostname[:port] | Terracotta server instance to which the Config Tool will connect and execute the command. |
-output-file <config-file> | The output configuration file. If this option is not specified, the configuration is displayed on the console. |
-include-defaults | Include the settings having system default values as well. Default: false |
-runtime | Export the runtime configuration instead of the on-disk configuration. Default: false |
Examples
1. Export the on-disk configuration of our 3-stripe, 7-node
example cluster to the console (line spacings added for readability):
config-tool.sh export -connect-to host1:9410 -include-defaults
# Timestamp of configuration export: 2021-05-01T12:00:00.000Z
# User-defined configurations
stripe-names=Stripe-A,Stripe-B,Stripe-C
stripe:Stripe-A:node-names=node1,node2
stripe:Stripe-B:node-names=node3,node4,node5
stripe:Stripe-C:node-names=node6,node7
cluster-name=MyCluster
failover-priority=consistency
offheap-resources=main:1GB,other:1GB
node:node1:backup-dir=dirs\node1\backup
node:node1:bind-address=0.0.0.0
node:node1:data-dirs=main:dirs\node1\main
node:node1:group-bind-address=0.0.0.0
node:node1:group-port=8430
node:node1:hostname=host1
node:node1:log-dir=dirs\node1\logs
node:node1:metadata-dir=dirs\node1\metadata
node:node1:port=9410
node:node2:backup-dir=dirs\node2\backup
node:node2:bind-address=0.0.0.0
node:node2:data-dirs=main:dirs\node2\main
node:node2:group-bind-address=0.0.0.0
node:node2:group-port=8432
node:node2:hostname=host2
node:node2:log-dir=dirs\node2\logs
node:node2:metadata-dir=dirs\node2\metadata
node:node2:port=9412
node:node3:backup-dir=dirs\node3\backup
node:node3:bind-address=0.0.0.0
node:node3:data-dirs=main:dirs\node3\main
node:node3:group-bind-address=0.0.0.0
node:node3:group-port=8433
node:node3:hostname=host3
node:node3:log-dir=dirs\node3\logs
node:node3:metadata-dir=dirs\node3\metadata
node:node3:port=9413
node:node4:backup-dir=dirs\node4\backup
node:node4:bind-address=0.0.0.0
node:node4:data-dirs=main:dirs\node4\main
node:node4:group-bind-address=0.0.0.0
node:node4:group-port=8434
node:node4:hostname=host4
node:node4:log-dir=dirs\node4\logs
node:node4:metadata-dir=dirs\node4\metadata
node:node4:port=9414
node:node5:backup-dir=dirs\node5\backup
node:node5:bind-address=0.0.0.0
node:node5:data-dirs=main:dirs\node5\main
node:node5:group-bind-address=0.0.0.0
node:node5:group-port=8435
node:node5:hostname=host5
node:node5:log-dir=dirs\node5\logs
node:node5:metadata-dir=dirs\node5\metadata
node:node5:port=9415
node:node6:backup-dir=dirs\node6\backup
node:node6:bind-address=0.0.0.0
node:node6:data-dirs=main:dirs\node6\main
node:node6:group-bind-address=0.0.0.0
node:node6:group-port=8436
node:node6:hostname=host6
node:node6:log-dir=dirs\node6\logs
node:node6:metadata-dir=dirs\node6\metadata
node:node6:port=9416
node:node7:backup-dir=dirs\node7\backup
node:node7:bind-address=0.0.0.0
node:node7:data-dirs=main:dirs\node7\main
node:node7:group-bind-address=0.0.0.0
node:node7:group-port=8437
node:node7:hostname=host7
node:node7:log-dir=dirs\node7\logs
node:node7:metadata-dir=dirs\node7\metadata
node:node7:port=9417
# Default configurations
client-lease-duration=150s
client-reconnect-window=120s
ssl-tls=false
whitelist=false
# Hidden internal system configurations (only for informational, import and repair purposes): please do not alter, get, set, unset them.
cluster-uid=bBxeCPytSX6zzu6QE17YUw
node:node1:node-uid=MDIUxIFuS3e9oljgAnqa6w
node:node2:node-uid=ezlBtxKHRMuQ8mff_fWjXg
stripe:Stripe-A:stripe-uid=eQR_OuF9QeupUaf1UH40yg
node:node3:node-uid=kA43NxI1QVi8T3AwZeOPiw
node:node4:node-uid=dtPHkx0CRJOfTd5_uaKqcg
node:node5:node-uid=8y6eHs1EQqayuK2iD-zgRQ
stripe:Stripe-B:stripe-uid=M7zsScxITXu68cA4_6vkAg
node:node6:node-uid=W5oQW761RhSU2da1zK4ElA
node:node7:node-uid=j2YmJoyRTGCSXZt4i3MFsA
stripe:Stripe-C:stripe-uid=jEZZ6hXyR-mpNWz0Jly4JA
2. Export the on-disk configuration of a cluster, omitting default values and saving it to a file:
config-tool.sh export -connect-to host1:9410 -output-file /path/to/output/configuration.cfg
Import
The import command is used to define a cluster topology including its stripes and nodes by importing those configuration settings via a configuration file. This import operation can only be executed on an UNCONFIGURED cluster (i.e. an unactivated cluster).
Syntax:
import -config-file <configuration-file> [-connect-to <hostname[:port]>]
Option | Description |
-config-file <configuration-file> | |
-connect-to <hostname[:port]> | A single node to which the configuration file will be imported. If this setting is omitted, then all nodes represented in the configuration file will be updated. |
Examples
1. Assume we have multiple unconfigured nodes started in diagnostic mode for which we want to form an activated cluster. First we import a configuration file (similar to the one we exported in our export example above) containing the detailed cluster, stripe, and node configuration information for all the nodes making up the cluster. We import that file to one of the running nodes (node1 in this example):
config-tool.sh import -config-file configuration.cfg -connect-to host1:9410
Then we activate the cluster as we showed earlier in our
activate example (note that we can omit the
cluster-name setting because our
configuration.properties file happened to already contain an entry for that):
config-tool.sh activate -connect-to host1:9410 -license-file /path/to/license.xml
Note:
If any one of the nodes listed in the configuration.cfg file is not online, running as an unconfigured node (i.e. started in diagnostic mode) or is already activated, then the activate command will fail.