The Terracotta Configuration File
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>.
The <servers> section contains parameters you use to configure the behavior and characteristics of the Terracotta Server Array and its component servers.
The <clients> section contains parameters you use to configure client behavior.
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
the password file location for JMX authentication
client logs location
server logs location
server data location
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.
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.
Overriding tc.properties
Every Terracotta installation has a default tc.properties file containing system properties. Normally, the settings in tc.properties are pre-tuned and should not be edited.
If tuning is required, you can override certain properties in tc.properties 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:
Override Priority
System properties configured in tc-config.xml override the system properties in the default tc.properties file provided with the Terracotta kit. The default tc.properties file should not be edited or moved.
If you create a local tc.properties file in the Terracotta lib directory, system properties set in that file are used by Terracotta and will override system properties in the default tc.properties file. System properties in the local tc.properties 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 -Dcom.tc.l1.cachemanager.leastcount=5 was passed at the command line or through a script, it would override the value in tc-config.xml and tc.properties. The order of precedence is shown in the following list, with highest precedence shown last:
1. default tc.properties
2. tc-config.xml
3. local, or user-created tc.properties 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 tc.management.mbeans.enabled is known to load before initialization completes and cannot be overridden.