Terracotta 10.7 | Terracotta Server Administration Guide | Starting and Stopping the Terracotta Server
 
Starting and Stopping the Terracotta Server
Starting the Terracotta Server
The command line script to start the Terracotta Server is located in the server/bin/ directory of the server kit. UNIX users use start-tc-server.sh while Windows users use start-tc-server.bat. All arguments are the same for both.
Options to the script
1. -port
Port to be used for this node. Default: 9410.
2. -bind-address
Bind address to be used for the node port. Default: 0.0.0.0.
3. -group-port
Port to be used for intra-stripe communication. Default: 9430.
4. -group-bind-address
Bind address to be used for node group port. Default: 0.0.0.0.
5. -hostname
Host name for this node. Must be a valid DNS name, or an IP address. Default: %h.
6. -name
Name to be used for this node. Needs to be unique in the cluster. Default: a randomly generated string.
7. -public-hostname
Public host name for this node. Needs to be set on all the nodes in the cluster. See Terracotta in Network Environments with Subnets for more details about this feature.
8. -public-port
Public node port for this node. Needs to be set on all the nodes in the cluster. See Terracotta in Network Environments with Subnets for more details about this feature.
9. -config-dir
Directory containing configuration bookkeeping information generated by the node. Default: %H/terracotta/config.
10. -backup-dir
Directory to be used to contain cluster backups. Needs to be set on all nodes in the cluster. See the section The "backup" Command of the cluster tool for more details about performing backups.
11. -log-dir
Directory to be used to contain logs for this node. Default: %H/terracotta/logs.
12. -metadata-dir
Directory to be used to contain server persistence data. Default: %H/terracotta/metadata. See the section Server Persistence for more details about this setting.
13. -repair-mode
Whether to start the node in repair mode. Default: false.
14. -client-lease-duration
Lease duration for the client connections. Default: 150s. Needs to be the same throughout the cluster. See Connection Leasing for more details about this property.
15. -client-reconnect-window
Time window for clients to reconnect to a new Active server after failover. Default: 120s. Needs to be the same throughout the cluster.
16. -cluster-name
Name to assign to the cluster this node will become a part of. Needs to be the same throughout the cluster.
17. -config-file
Config file to start the node with. See the section The TerracottaConfiguration File for more details about this property.
18. -failover-priority
The failover priority setting to be used. Valid values are availability and consistency. Needs to be the same throughout the cluster. This is the only mandatory option if the node is started using console parameters. See Failover Tuning for more details about this property.
19. -data-dirs
Directory to contain client data. Default: main:%H/terracotta/user-data/main. Data directory names needs to be the same throughout the cluster - the disk locations could vary. See Configuring the Terracotta Server for more details about this property.
20. -offheap-resources
Offheap resources to be used. Default: main:512MB. Needs to be the same throughout the cluster. See Configuring the Terracotta Server for more details about this property. Offheap resources is the only property which is validated against the license. The total offheap-resources for the cluster (i.e. offheap-resources for all stripes summed up) should be within the license limit. See Licensing for more details about licensing.
21. -audit-log-dir
Directory containing the node's security audit logs. Needs to be set on all the nodes. Needs some form of security to be enabled.
22. -authc
Security authentication setting to be used. Valid values are file,ldap and certificate. Needs to be the same throughout the cluster.
23. -security-dir
The security root directory for this node.
24. -ssl-tls
Whether to enable SSL/TLS based security. Default: false. Needs to be the same throughout the cluster.
25. -whitelist
Whether to enable IP whitelist security. Default: false. Needs to be the same throughout the cluster.
See Cluster Security for more details about configuring security.
Use cases
The server startup script can be used in different ways, depending on the needs and convenience of the server admin:
Starting nodes with console parameters
A server can be started in unconfigured node, with console parameters alone (i.e. without the need of having any config files).
Example:
./start-tc-server.sh -config-dir /data/tc/node1
-port 9410 -group-port 9430 -name node1 -failover-priority consistency
-offheap-resources primary:250GB,caching:100GB
Note: the config-dir in question must be empty, as it only makes sense to use the command with these parameters to load a new server with its initial set of configuration properties.
After startup, it will then be necessary to execute the config tool attach and activate commands respectively to define the cluster topology and to make the cluster ready for client operations. Before activating, the config tool could also be used to set various other configuration options on the node.
Starting nodes with config file
An unconfigured server can be also be started with a parameter specifying a config file which was exported from an existing cluster, or constructed by hand. See the section Export for related information.
Example:
./start-tc-server.sh -config-dir /data/tc/node1
-config-file myCluster.properties
In this case it is not necessary to execute the config tool attach command since the cluster topology is already defined in the config file. The execution of the activate command, however, would still be required to make the cluster ready for client operations.
Note:
The config-dir in question must be empty, as it only makes sense to use the command with these parameters to load a new server with its initial set of configuration properties.
Note:
It is important to understand that the configuration file used in this command is not what will be used by the server each time it starts. Rather, it is simply a convenience for passing the initial configuration properties to the server, instead of specifying each config property on the command line and/or setting it via config tool. Once the config file is read, the server's internal configuration is stored in its config-dir. The config-dir contains the configuration that will be used on subsequent restarts.
Starting nodes with config dir
A previously configured server can be started with the specification of a configuration directory (config-dir), in activated mode directly.
Example:
./start-tc-server.sh -config-dir /data/tc/node1
This is used when the server was restarted after having been activated previously, but can also be used on a fresh server startup after completing the migration process from an older Terracotta cluster. See the sections Migrating from older Terracotta versions to 10.7 or Migrating from 10.7 to a newer 10.7 version for related details
Note that when you start a server this way (which will be the most common way, over time), any other parameters passed will be effectively ignored, because the server will use its internal configuration.
After starting a node this way, it is not necessary to run the config tool attach or activate commands since the cluster topology and configuration are ready.
Environment variables read by the script
*JAVA_HOME - Points to the JRE installation which the server should use (the Java launcher in this JRE will be used to start the server).
*JAVA_OPTS - Any additional options which should be passed to the underlying JVM can be passed via this environment variable and they will be added to the Java command line.
Stopping the Terracotta Server
If your server is not running in a Terracotta cluster, you can use the standard procedure offered by your operating system to terminate the server process.
If you are running the server as part of a Terracotta cluster, you can safely shut down all servers in the cluster using the cluster tool. See the section Safe Cluster Shutdown of the cluster tool for details.