The Terracotta Configuration File

Terracotta Server Administration Guide : The Terracotta Configuration File

This document describes the Terracotta configuration elements in the Terracotta configuration file, which is an XML-formatted file named tc-config.xml by default.

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 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 having at least 2 servers in this section. 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"> To start the server with the name "ServerName", you pass the option -n ServerName to the start script.
Properties	The tc.properties section exposes a list of key-value pairs to further customize the behavior of the cluster. Note that this section is normally empty.

Simple Configuration Sample

This is an example of a very simple server configuration file.

<tc-config xmlns="http://www.terracotta.org/config" >
<plugins>
</plugins>
<entities>
</entities>
<tc-properties/>
<servers secure="false">
<server host="localhost" name="testServer0">
<logs>terracotta-kit-test/testServer0/logs</logs>
<tsa-port>26270</tsa-port>
<tsa-group-port>26271</tsa-group-port>
</server>
<client-reconnect-window>120</client-reconnect-window>
</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:

Configuration namespace: http://www.terracotta.org/config

Empty plugins and entities sections

No additional tc-properties specified

Only a single server (note that localhost should be replaced with the actual hostname or IP of the server, in a real deployment) with name testServer0

Server name is important as it is used when starting a server so it knows which server it is

A relative path to a logs directory is given

The tsa-port is required as this is the port clients will use when connecting to the server

The tsa-group-port is required as this is the port other servers will use when acting as part of the cluster (even though there are no other servers in this case)

The client-reconnect-window is the time, in seconds, which will be reserved for clients to reconnect and pick up the previous state in the case of a restart or fail-over

Neither restart nor failover would be possible with this configuration, as restart support requires a plugged in service which provides that capability, and fail-over requires at least 2 servers in the cluster

Configuration Variables

Certain variables can be used that are interpolated by the configuration subsystem using local values:

Variable	Interpolated Value
%h	The fully-qualified hostname
%i	The IP address
%o	The operating system
%v	The version of the operating system
%a	The CPU architecture
%H	The home directory of the user running the application
%n	The username of the user running the application
%t	The path to the temporary directory (for example, /tmp on *NIX)
%D	Time stamp (yyyyMMddHHmmssSSS)
%(system property)	The value of the given Java system property

These variables 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

client logs location

server logs location

data-roots

Note:

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.

Contact Support | Community | Feedback