The Terracotta Configuration File
This document describes the elements of the Terracotta configuration file, which is which is a Java properties file.
The config file serves to describe the initial configuration for all members of a Terracotta cluster. Refer to the section
Cluster Architecture for details on various different TSA topologies.
A sample config file is provided in the kit under server/conf, which can be used as the starting point. Some samples have inline comments describing the configuration elements. Be sure to start with a clean file for your configuration.
Use cases
Unlike previous Terracotta releases, a config file isn't needed to configure or start the servers. However, a config file is handy for the following purposes:
2. Backing up and version-controlling the configuration of a given cluster
3. Using the current configuration as a foundation to build up a new configuration
It is important to understand that in these cases the configuration file is only used as a convenience to "feed" all of the configuration settings into unconfigured servers. Once that is done, the servers will never again utilize or reference the config file, but will instead utilize their internal configuration (stored in the server's config-dir).
Examples
This section describes the various properties supported in a config file.
Minimal configuration
A config file can get pretty large, especially when the cluster contains a large number of nodes. However, most configuration properties have default values, because of which the config file can be reduced in size if the default values are acceptable. The only two mandatory properties for a single-node cluster are:
failover-priority=availability
stripe.1.node.1.hostname=localhost
which specifies the failover-priority of the cluster to availability, and the hostname to localhost. The following default values are used:
Property | Default value | Comments |
offheap-resources | main:512MB | |
client-lease-duration | 150 seconds | Defines the lease duration for the client connections as 150 seconds. See
Connection Leasing. |
client-reconnect-window | 120 seconds | Defines the client reconnect time window as 120 seconds |
stripe.1.node.1.name | <randomly-generated> | A randomly-generated name for the node. |
stripe.1.node.1.hostname | %h | Sets the host name of the node to the fully-qualified host name of the machine. |
stripe.1.node.1.port | 9410 | Sets the port for this server process to 9410 |
stripe.1.node.1.bind-address | 0.0.0.0 | Sets the bind address for the port to the wildcard address 0.0.0.0 |
stripe.1.node.1.group-port | 9430 | Sets the intra-stripe communication port for this server process to 9430 |
stripe.1.node.1.group-bind-address | 0.0.0.0 | Sets the bind address for the group port to the wildcard address 0.0.0.0 |
stripe.1.node.1.metadata-dir | %H/terracotta/metadata | |
stripe.1.node.1.data-dirs | main:%H/terracotta/user-data/main | Defines a user data directory with name main and path %H/terracotta/user-data/main. See
Data Directories. |
stripe.1.node.1.log-dir | %H/terracotta/logs | Sets the server logging directory to %H/terracotta/logs |
Note:
%h and
%H in the above default values point to the hostname of the machine and home directory of the current user respectively. See the section
Parameter Substitution for more information.
Several other configuration properties are omitted (i.e. not assumed to have defaults), which are:
Property | Comments |
cluster-name | The name of the cluster |
whitelist | Whether to enable IP whitelist security |
ssl-tls | Whether to enable SSL/TLS based security |
authc | Security authentication setting to be used |
security-dir | The security root directory for this node |
audit-log-dir | Directory containing the node's security audit logs |
backup-dir | |
public-hostname | |
public-port | |
Security configuration
The following snippet demonstrates how to enable IP whitelisting and SSL/TLS based security (see the section
SSL / TLS Security Configuration in Terracotta) along with security event auditing on a single node cluster:
failover-priority=availability
whitelist=true
ssl-tls=true
authc=certificate
stripe.1.node.1.hostname=localhost
stripe.1.node.1.audit-log-dir=/path/to/audit/dir
stripe.1.node.1.security-dir=/path/to/security/dir
High availability configuration
High-availability can be enabled by configuring more than one node in a stripe. The following snippet defines two nodes in a cluster containing a single stripe:
failover-priority=availability
stripe.1.node.1.hostname=localhost
stripe.1.node.1.port=9410
stripe.1.node.1.group-port=9430
stripe.1.node.2.hostname=localhost
stripe.1.node.2.port=9510
stripe.1.node.2.group-port=9530
Multistripe with HA configuration
Stripes can be added to a Terracotta cluster to scale it out. Additionally, high-availability in a stripe can be enabled by configuring more than one node. The following snippet defines a cluster with two stripes with two nodes each:
failover-priority=availability
stripe.1.node.1.hostname=localhost
stripe.1.node.1.port=9410
stripe.1.node.1.group-port=9430
stripe.1.node.2.hostname=localhost
stripe.1.node.2.port=9510
stripe.1.node.2.group-port=9530
stripe.2.node.1.hostname=localhost
stripe.2.node.1.port=9610
stripe.2.node.1.group-port=9630
stripe.2.node.2.hostname=localhost
stripe.2.node.2.port=9710
stripe.2.node.2.group-port=9730