How Terracotta Servers Get Configured
To configure the Terracotta server, create a tc-config.xml configuration file, or update the one that is provided in the config-samples/ directory of the BigMemory Max kit. For example:
<?xml version="1.0" encoding="UTF-8" ?>
<tc:tc-config xmlns:tc="http://www.terracotta.org/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-9.xsd">
<servers>
<server host="localhost" name="My Server Name1">
<!-- Specify the path where the server should store its data. -->
<data>/local/disk/path/to/terracotta/server1-data</data>
<!-- Specify the port where the server should listen for client
traffic. -->
<tsa-port>9510</tsa-port>
<jmx-port>9520</jmx-port>
<tsa-group-port>9530</tsa-group-port>
<management-port>9540</management-port>
<!-- Enable BigMemory on the server. -->
<dataStorage size="800g">
<offheap size="200g"/>
<!-- Hybrid storage is optional. -->
<hybrid/>
</dataStorage>
</server>
<server host="localhost" name="My Server Name2">
<data>/local/disk/path/to/terracotta/server2-data</data>
<tsa-port>9510</tsa-port>
<jmx-port>9520</jmx-port>
<tsa-group-port>9530</tsa-group-port>
<management-port>9540</management-port>
<dataStorage size="200g">
<offheap size="200g"/>
</dataStorage>
</server>
<!-- Add the restartable element for Fast Restartability (optional). -->
<restartable enabled="true"/>
</servers>
<clients>
<logs>logs-%i</logs>
</clients>
</tc:tc-config>
To successfully configure a Terracotta Server Array using the Terracotta configuration file, note the following:
Two or more servers should be defined in the <servers> section of the Terracotta configuration file.
<tsa-port> is the port that the Terracotta server listens to for client traffic.
<jmx-port> is the port that the Terracotta server's JMX Connector listens to.
Note:
Listening on the <jmx-port> is deprecated. Alternatively, use the monitoring features provided by the Terracotta Management Console (see the Terracotta Management Console User Guide) and the WAN Replication Service (see the WAN Replication User Guide).
<jmx-port> is disabled by default. If you want to enable it, add jmx-enabled="true" in the <server> elements. For example:
<server host="localhost" name="My Server Name1" jmx-enabled="true">
<tsa-group-port> is the port used by the Terracotta server to communicate with other Terracotta servers.
<management-port> is the port that the Terracotta Management Console (TMC) uses.
Under <servers>, use either <server> or <mirror-group> configurations, but not a mixture. You may configure multiple servers or multiple mirror groups. <server> instances under <servers> work together as a mirror group. To create more than one stripe, use <mirror-group> instances.
Terracotta server instances must not share data directories. Each server's <data> element should point to a different and preferably local data directory.
For data persistence, configure fast restartability. Enabling <restartable> means that the shared in-memory data is backed up and, in case of failure, it is automatically restored. Setting <restartable> to "false" or omitting the <restartable> element are two ways to configure no persistence.
Each server requires an off-heap store, which allows all data to be stored in-memory, limited only by the amount of memory in your server. The minimum <offheap> size is 4 GB. Additional hybrid storage is optional. Specify the <dataStorage> size and the <offheap> size. The <offheap> size can be set to the amount of memory available in your server for data. If you enable <hybrid>, then the <dataStorage> size can exceed the <offheap> size.
All servers and clients should be running the same version of Terracotta and Java.
Server Startup Behavior
At startup, Terracotta servers load their configuration from one of the following sources:
A default configuration included with the Terracotta kit
A local or remote XML file
These sources are explored below.
Default Configuration
If no configuration file is specified and no tc-config.xml exists in the directory in which the Terracotta instance is started, then default configuration values are used.
Local XML File (Default)
The file tc-config.xml is used by default if it is located in the directory in which a Terracotta instance is started and no configuration file is explicitly specified.
Local or Remote Configuration File
You can explicitly specify a configuration file by passing the -f option to the script used to start a Terracotta server. For example, to start a Terracotta server on UNIX/Linux using the provided script, enter:
start-tc-server.sh -f <path_to_configuration_file>
where <path_to_configuration_file> can be a URL or a relative directory path. In Microsoft Windows, use start-tc-server.bat.
Note:
Cygwin (on Windows) is not supported for this feature.
Usage note for Terracotta Server Array on Linux
If your Terracotta Server Array operates in a Linux environment and you encounter file descriptor errors in the BigMemory server log (whose location is specified in your tc-config.xml file) you need to adjust your ulimit setting.
BigMemory uses the Apache Lucene search engine for indexes, and the number of file descriptors needed depends on the number of indexes you have created. If you are running on a 64bit processor, you can safely set the ulimit to unlimited; for older machines Lucene suggests that a limit of 64K is appropriate.