Terracotta 10.3 | Terracotta Server Administration Guide | The Terracotta Configuration File
 
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">
To start the server with the name "ServerName", you pass the option -n ServerName to the start script. Refer to the section Starting and Stopping the Terracotta Server for more details.
Plugins
The plugins section extends the capabilities of the listed servers by (1) registering and configuring additional services made available to those servers, and (2) 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.
Refer to the section Configuring the Terracotta Server for concrete examples.
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">
<servers>
<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>
</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.
*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: 9530).
*Neither restartability nor failover would be possible with the above sample configuration, as restart support requires an extension point which provides that capability, and failover 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
%H
the user's home directory
%n
the username
%o
the operating system name
%a
the processor architecture
%v
the operating system version
%t
the temporary directory (on Linux or Solaris, e.g., /tmp)
%(property)
the Java system property of the JVM (e.g. %(java.home), %(logs.path) )
%D
the time stamp (yyyyMMddHHmmssSSS)
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-roots
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.
Copyright © 2010-2019 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.