The Terracotta Configuration File
This document describes the elements of the Terracotta configuration file, which is an XML-formatted file named tc-config.xml by default.
This file serves to configure all the members of a single
Terracotta Server Array (TSA) stripe. Refer to the section
Cluster Architecture for details on various different TSA topologies.
You can use a sample configuration file provided in the kit as the basis for your Terracotta configuration. Some samples have inline comments describing the configuration elements. Be sure to start with a clean file for your configuration.
Explanation of Configuration Sections
The Terracotta configuration file is divided into several main, unordered sections. For general configuration purposes, the most relevant sections are:
Section | Description |
Servers | The servers section defines all the servers which will make up this stripe of a cluster. High-availability is enabled by configuring and running at least 2 servers in this stripe. Note that there is no explicit configuration of which server takes an active or passive role, as that may change over the lifetime of the cluster. Each server element in the servers section is identified by a name given by the name attribute: <server ... name="ServerName"> |
Plugins | The plugins section extends the capabilities of the listed servers by:  Registering and configuring additional services made available to those servers Providing general configuration information made available to all services The use of extension points is required for the server to work with your application end-points. |
Simple Configuration Sample
This is an example of a very simple server configuration file.
<tc-config xmlns="http://www.terracotta.org/config">
<servers>
<server host="localhost" name="testServer0">
<logs>path/to/terracotta-logs</logs>
<tsa-port>26270</tsa-port>
<tsa-group-port>26271</tsa-group-port>
</server>
</servers>
</tc-config>
This shows the key components of a standard configuration but describes only a single server with no extension points used.
Key points:
Only a single server with name
testServer0.
Server name is important as it is used when starting a server so it knows which server it is.
localhost should be replaced with the actual fully-qualified hostname or IP address of the server, in a real deployment.
Note: Using localhost as hostname will not work correctly if clients and operator console are connecting from other hosts, since the configured hostname is sent to clients and other members of the stripe as the authoritative hostname to reach this server.
A relative path to a logs directory is given.
All relative paths are with respect to the location of the containing configuration file.
The
tsa-port is the port that clients will use when connecting to the server (default: 9410).
The
tsa-group-port is for inter-server communication among stripe members, even though there are no other servers in this case (default: 9430).
Neither
persistence nor
high-availability would be possible with the above sample configuration, as restart support requires an extension point which provides that capability, and high-availability requires at least 2 servers in the cluster.
Parameter Substitution
Parameter substitution provides a way to substitute variables with pre-defined system properties in the Terracotta Server configuration file. Thus, a significant number of fields can be intelligently populated based on machine specific properties. Parameter substitution is most commonly done for hostname, IP address and directory path substitutions.
The following predefined substitutions are available for use:
Parameter | Description |
%h | the fully-qualified host name |
%i | the IP address |
%D | the time stamp (yyyyMMddHHmmssSSS) |
%H | the user's home directory corresponding to the user.home Java system property |
%n | the username corresponding to the user.name Java system property |
%o | the operating system name corresponding to the os.name Java system property |
%a | the processor architecture corresponding to the os.arch Java system property |
%v | the operating system version corresponding to the os.version Java system property |
%t | the temporary directory corresponding to the java.io.tmpdir Java system property |
%(system property) | a standard or custom Java system property. If a custom Java property needs to be used, it should be first set in the JVM by setting it in JAVA_OPTS in the -Djava.custom.property=value format. |
These parameters can be used where appropriate, including for elements or attributes that expect strings or paths for values:
the
name,
host and
bind attributes of the
<server> element
the
logs child element of the
<server> element
data-directories
Important: Be careful when you specify substitution parameters in the host attribute of the <server> element in tc-config. If multiple servers from the same stripe containing substitution parameters in host are started on different hosts, they will not be able to communicate with each other since each host substitutes the parameter based on its own host name. Similarly, tools like the cluster tool will not be able to connect to the servers, as they don't know which host the server is running on.
The variable %i is expanded into a value determined by the host's networking setup. In many cases that setup is in a hosts file containing mappings that may influence the value of %i. Test this variable in your production environment to check the value it interpolates.