Call us: +1-415-738-4000

Terracotta Configuration Reference


This document is a reference to all of the Terracotta configuration elements in the Terracotta configuration file, which is 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.

The Terracotta configuration XML document is divided into the sections <servers> and <clients>. Each of these sections provides a number of configuration options relevant to its particular configuration topic.

Configuration Variables

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

VariableInterpolated Value
%hThe fully-qualified hostname
%iThe IP address
%oThe operating system
%vThe version of the operating system
%aThe CPU architecture
%HThe home directory of the user running the application
%nThe username of the user running the application
%tThe path to the temporary directory (for example, /tmp on *NIX)
%DTime 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
  • the password file location for JMX authentication
  • client logs location
  • server logs location
  • server data location
NOTE: Value of %i
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.

Using Paths as Values

Some configuration elements take paths as values. Relative paths are interpreted relative to the current working directory (the directory from which the server was started). Specifying an absolute path is recommended.


Every Terracotta installation has a default file containing system properties. Normally, the settings in are pre-tuned and should not be edited.

If tuning is required, you can override certain properties in using tc-config.xml. This can make a production environment more efficient by allowing system properties to be pushed out to clients with tc-config.xml. Those system properties would normally have to be configured separately on each client.

Setting System Properties in tc-config

To set a system property with the same value for all clients, you can add it to the Terracotta server's tc-config.xml file using a configuration element with the following format:

<property name="<tc_system_property>" value="<new_value>" />

All <property /> tags must be wrapped in a <tc-properties> section placed at the beginning of tc-config.xml.

For example, to override the values of the system properties l1.cachemanager.enabled and l1.cachemanager.leastCount, add the following to the beginning of tc-config.xml:

  <property name="l1.cachemanager.enabled" value="false" />
  <property name="l1.cachemanager.leastCount" value="4" />

Override Priority

System properties configured in tc-config.xml override the system properties in the default file provided with the Terracotta kit. The default file should not be edited or moved.

If you create a local file in the Terracotta lib directory, system properties set in that file are used by Terracotta and will override system properties in the default file. System properties in the local file are not overridden by system properties configured in tc-config.xml.

System property values passed to Java using -D override all other configured values for that system property. In the example above, if was passed at the command line or through a script, it would override the value in tc-config.xml and The order of precedence is shown in the following list, with highest precedence shown last:

  1. default
  2. tc-config.xml
  3. local, or user-created in Terracotta lib directory
  4. Java system properties set with -D

Failure to Override

If system properties set in tc-config.xml fail to override default system properties, a warning is logged to the Terracotta logs. The warning has the following format:

The property <system_property_name> was set by local settings to <value>. 
This value will not be overridden to <value> from the tc-config.xml file.

System properties used early in the Terracotta initialization process may fail to be overridden. If this happens, a warning is logged to the Terracotta logs. The warning has the following format:

The property <system_property_name> was read before initialization completed. 

The warning is followed by the value assigned to <system_property_name>.

NOTE: The property is known to load before initialization completes and cannot be overridden.

Servers Configuration Section

This section contains the information that defines and configures the Terracotta Server Array (TSA) and its component servers.


This section defines the Terracotta server instances present in your cluster. One or more entries can be defined, either directly under the <servers> element or in mirror groups. If this section is omitted, Terracotta configuration behaves as if there's a single server instance with default values.

This section also defines certain global settings that affect all servers, including the attribute secure. This is a global control for enabling ("true") or disabling ("false" DEFAULT) SSL-based security for the entire cluster.


A server stanza encapsulates the configuration for a Terracotta server instance. The server element takes three optional attributes (see table below).

AttributeDefinitionValueDefault Value
host The address of the machine hosting the Terracotta server Host machine's IP address or resolvable hostname Host machine's IP address
name The symbolic name of the Terracotta server; can be passed to Terracotta scripts such as start-tc-server using -n <name> user-defined string :
bind The network interface on which the Terracotta server listens cluster traffic; specifies all interfacesinterface's IP address

Each Terracotta server instance needs to know which configuration it should use as it starts up. If the server's configured name is the same as the hostname of the host it runs on and no host contains more than one server instance, then configuration is found automatically.

For more information on how to use the Terracotta configuration file with servers, see the Terracotta configuration guide.

Sample configuration snippet:

  <!-- my host is '%i', my name is '%i:tsa-port', my bind is -->
<server host="myhostname">
  <!-- my host is 'myhostname', my name is 'myhostname:tsa-port', my bind is -->
<server host="myotherhostname" name="server1" bind="">
  <!-- my host is 'myotherhostname', my name is 'server1', my bind is -->


This element specifies the path where the server should store its data for persistence.

Default: data (creates the directory data under the working directory)


This section lets you declare where the server should write its logs.

Default: logs (creates the directory logs under the working directory)

You can also specify stderr: or stdout: as the output destination for log messages. For example:


To set the logging level, see this FAQ entry.


This element specifies the path where the server should store its search indexes.

Default: index (creates the directory index under the working directory)


This element specifies the path where the server should store backups (if a backup call is initiated).

Default: data-backup (creates the directory data-backup under the working directory)


This section lets you set the port that the Terracotta server listens to for client traffic.

The default value of "tsa-port" is 9510.

Sample configuration snippet:



This section lets you set the port that the Terracotta server's JMX Connector listens to.

The default value of "jmx-port" is 9520. If tsa-port is set, this port defaults to the value of the tsa-port plus 10.

Sample configuration snippet:



This section lets you set the port that the Terracotta server uses to communicate with other Terracotta servers.

The default value of "tsa-group-port" is 9530. If tsa-port is set, this port defaults to the value of the tsa-port plus 20.

Sample configuration snippet:



This section contains the data necessary for running a secure cluster based on SSL, digital certificates, and node authentication and authorization.

See the advanced-security page for a configuration example.


The element specifying certificate entry and location of the certificate store. The format is:


The Java Keystore (JKS) type is supported by Terracotta 3.7 and higher.


This element contains the following subelements:

  • <class> – Element specifying the class defining the keychain file. If a class is not specified, is used.
  • <url> – The URI for the keychain file. It is passed to the keychain class to specify the keychain file.
  • <secret-provider> – The fully qualified class name of the user implementation of This class can read and provide the keychain file.


This element contains the following subelements:

  • <realm> – Element specifying the class defining the security realm. If a class is not specified, is used.
  • <url> – The URI for the Realm configuration (.ini) file. It is passed to the realm class to specify authentication file. Alternatively, URIs for LDAP or Microsoft Active directory can also be used if one of these schemes is implemented instead.
  • <user> – The username that represents the server and is authenticated by other servers. This name is part of the credentials stored in the .ini file. The default value is "terracotta".


This element contains the subelements needed to allow the Terracotta Management Server (TMS) to make a secure connection to the TSA:

  • ia – The HTTPS URL with the domain of the TMS, followed by the port 9443 and the path /tmc/api/assertIdentity.
  • timeout – The timeout value (in milliseconds) for connections from the server to the TMS.
  • hostname – Used only if the DNS hostname of the server does not match server hostname used in its certificate. If there is a mismatch, enter the DNS address of the server here.


Turn on JMX authentication for the Terracotta server. An empty tag (<authentication />) defaults to the standard Java JMX authentication mechanism referring to password and access files in $JAVA_HOME/jre/lib/management:


You must modify these files as as follows (or, if none exist create them).

jmxremote.password Add a line to the end of the file declaring a username and password followed by a carriage return:

secretusername secretpassword

jmxremote.access Add the following line (with a carriage return) to the end of your file:

secretusername      readwrite

Be sure to assign the appropriate permissions to the file. For example, in *NIX:

$ chmod 500 jmxremote.password
$ chown <user who will run the server> jmxremote.password

For information on alternatives to JMX authentication, see Terracotta Cluster Security.

Note that version 4.x does not support HTTP authentication.


This configuration block includes the required offheap element, as well as the optional hybrid element.

  • <offheap> must be configured for each server; the minimum amount is 4 GB.

  • <dataStorage> specifies the maximum amount of data to store on each server, and represents the hybrid sum of off-heap DRAM plus flash SSD.

  • <hybrid/>, if included, enables the Hybrid option.

Sample configuration snippet:

<dataStorage size=”800g”> 
   <offheap size=”200g”/> 

If the hybrid element is present, then dataStorage size may exceed offheap size, however if the hybrid element is not present, then the dataStorage size must be less than or equal to the offheap size.


A mirror group is a stripe in a TSA, consisting of one active server and one or more mirror (or backup) servers. A configuration that does not use the <mirror-group> element would produce a one-stripe TSA:

  <server name="A">
  <server name="B">
  <server name="C">
  <server name="D">

One of the named servers would assume the role of active (the one started first or that wins the election), while the remaining servers become mirrors. Note that in a typical stripe, having only one or two mirrors is sufficient and less taxing on the active server's resources (as it needs to sync with each mirror).

The following example shows the same servers split into two stripes:

  <mirror-group group-name="team1">
    <server name="A">
    <server name="B">
  <mirror-group group-name="team2">
    <server name="C">
    <server name="D">

Each stripe will have one active and one mirror server.

NOTE: Server vs. Mirror Group
Under <servers>, you may use either <server> or <mirror-group> configurations, but not both. All <server> configurations directly under <servers> work together as one mirror group, with one active server and the rest mirrors. To create more than one stripe, use <mirror-group> configurations directly under <servers>. The mirror group configurations then include one or more <server> configurations.

For more examples and information, see the Terracotta Configuration Guide.


This section lets you configure the periodic distributed garbage collector (DGC) that runs in the TSA. The DGC collects shared data made garbage by Java garbage collection.

For many use cases, there is no need to enable periodic DGC. For caches, the more efficient automatic inline DGC is normally sufficient for clearing garbage. In addition, certain read-heavy applications will never require the periodic DGC as little shared data becomes garbage.

However, in certain situations such as when Terracotta Toolkit data structures are in use, the periodic DGC may need to be enabled. Inline DGC is not available for these data structures.

For more on how DGC functions, see TSA Architecture.

Configuration snippet:


 <!--    Default: false -->

  <!-- If "true", additional information is logged when a
     server performs distributed garbage collection. 

     Default: false

  <!-- How often should distributed garbage collection
     be performed, in seconds?

     Default: 3600 (60 minutes)


The fast-restart persistence mechanism must be explicitly enabled for the TSA using this element:

<restartable enabled="true"/>

In case of TSA failure, fast-restart persistence allows the TSA to reload all shared cluster data.

To function, this feature requires <offheap> to be enabled on each server. To make backups of TSA data, the backup feature requires this feature to be enabled.


This section lets you declare the window of time servers will allow disconnected clients to reconnect to the cluster as the same client. Outside of this window, a client can only rejoin as a new client. The value is specified in seconds and the default is 120 seconds.

If adjusting value, note that a too-short reconnection window can lead to unsuccessful reconnections during failure recovery, while a too-long window lowers the efficiency of the cluster since it is paused for the time the window is in effect.

Further reading: For more information on how client and server reconnection is executed in a Terracotta cluster, and on tuning reconnection properties in a high-availability environment, see Configuring Terracotta Clusters For High Availability.

Clients Configuration Section

The clients section contains configuration about how clients should behave.


This section lets you configure where the Terracotta client writes its logs.

Sample configuration snippet:

   This value undergoes parameter substitution before being used;
   thus, a value like 'client-logs-%h' would expand to
   'client-logs-banana' if running on host 'banana'. See the
   Product Guide for more details.

   If this is a relative path, then it is interpreted relative to
   the current working directory of the client (that is, the directory
   you were in when you started the program that uses Terracotta
   services). It is thus recommended that you specify an absolute
   path here.

   Default: 'logs-%i'; this places the logs in a directory relative
   to the directory you were in when you invoked the program that uses
   Terracotta services (your client), and calls that directory, for example,
   'logs-' if the machine that the client is on has assigned IP

You can also specify stderr: or stdout: as the output destination for log messages. For example:


To set the logging level, see this FAQ entry.