Terracotta Logo (http://www.terracotta.org)

Terracotta 3.2.1 Documentation

Table of Contents •  Back  •  Forward

Terracotta 3.2.1

Support

Services

Training


The content you have selected is available exclusively to Terracotta, Ehcache, and Quartz community members. If you are already a member, please login. If not, please take a moment to become one. Please sign up to join the Terracotta, Ehcache, and Quartz communities. Membership is free and only requires you to complete the form below. In addition to full documentation access, you will also be eligible to attend product briefings, download select early access product releases before the general public, post forum questions, file bug reports, submit patches and receive other member benefits still to come.

Login

 
Login

Register

All fields in bold are required.
(eight characters max)
Title:
City:
State/Province:
Country:
Phone:
Which technologies are you interested in or are already using?
 
Using
 
Hibernate
Ehcache
Distributed Caching
Quartz
Web Sessions Clustering
DSO (Distributed Shared Objects)
Please contact me
about Terracotta products, services, or training:
Please keep me updated on important Terracotta news:
 
Register
registering Register

Account Activated

Congratulations, your account has been activated. Thanks for joining the Terracotta, Ehcache, and Quartz community. You may now login to all of the the community resources, including:

  • forums
  • project issue trackers
  • community content

Account Registration Successful

(But you're not quite done—you still need to validate your account. Please check your email!)

Thanks for joining the Terracotta and Ehcache community. You will recieve an e-mail shortly containing instructions for validating your account and downloading Ehcache EX.

After you validate your account, you will have full access to all Terracotta and Ehcache community resources, such as:

6.1 Working with Terracotta Configuration Files

Terracotta XML configuration files set the characteristics and behavior of Terracotta server instances and Terracotta clients. The easiest way to create your own Terracotta configuration file is by editing a copy of one of the sample configuration files available in /config-examples directory, located in the Terracotta home directory.

Where you locate the Terracotta configuration file, or how your Terracotta server and client configurations are loaded, depends on the stage your project is at and on its architecture. This document covers the following cases:

This document discusses configuration in Terracotta server arrays. To learn more about Terracotta server arrays, see Terracotta Server Arrays.

6.1.1 How Terracotta Servers Get Configured

At startup, Terracotta servers should fetch their configuration from one of the following sources:

These sources are explored below.

6.1.1a 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.

6.1.1b 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.

6.1.1c 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 .

6.1.2 How Terracotta Clients Get Configured

At startup, Terracotta clients should fetch their configuration from one of the following sources:

These sources are explored below.

6.1.2a Local XML File (Default)

See the discussion for local XML file (default) in How Terracotta Servers Get Configured.

6.1.2b Local or Remote Configuration File

To specify a configuration file for a Terracotta client, see Clients in Development.

6.1.2c Terracotta Server

Terracotta clients can load configuration from a running Terracotta server by specifying its hostname and DSO port (see Clients in Production).

6.1.3 Configuration in a Development Environment

In a development environment, using a different configuration file for each Terracotta client facilitates the testing and tuning of configuration options. This is an efficient and effective way to gain valuable insight on best practices for clustering your application with Terracotta DSO.

6.1.3a One-Server Setup in Development

For one Terracotta server, the default configuration is adequate.

To use the default configuration settings, start your Terracotta server using the start-tc-server.sh (or start-tc-server.bat) script in a directory that does not contain the file tc-config.xml :

[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.sh

To specify a configuration file, use one of the approaches discussed in How Terracotta Servers Get Configured.

6.1.3b Two-Server Setup in Development

An two-server setup, sometimes referred to as an active-passive setup, has one active server instance and one "hot standby" (the passive, or backup) that should load the same configuration file.

The configuration file loaded by the Terracotta servers must define each server separately using <server> elements. For example:

<tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-5.xsd" 
xmlns:tc="http://www.terracotta.org/config" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
  <server host="%i" name="Server1">
...
  <server host="%i" name="Server2">
...
</tc:tc-config>

Assuming Server1 is the active server, using the same configuration allows Server2 to be the hot standby and maintain the environment in case of failover.

NOTE: Differences in <server> Child Elements

Some elements in the <server> section, such as <server-logs>, must have different values for each server.
Server Names for Startup

With multiple <server> elements, the name attribute is required to avoid ambiguity when starting a server:

start-tc-server.sh -n Server1 -f <path_to_configuration_file>

6.1.3c Clients in Development

You can explicitly specify a client's Terracotta configuration file by passing -Dtc.config=path/to/my-tc-config.xml when you start your application with the Terracotta client.

DSO users can use the dso-java.sh script (or dso-java.bat for Windows):

dso-java.sh -Dtc.config=path/to/my-tc-config.xml -cp classes myApp.class.Main

where myApp.class.Main is the class used to launch the application you want to cluster with Terracotta.

NOTE: Fetching Configuration from the Server

On startup, Terracotta clients must fetch certain configuration properties from a Terracotta server. A client loading its own configuration will attempt to connect to the Terracotta servers named in that configuration. If none of the servers named in that configuration are available, the client cannot complete its startup.

If tc-config.xml exists in the directory in which you run dso-java, it can be loaded without -Dtc.config .

TIP: Avoiding the dso-java Script

If you do not require DSO, do not use the dso-java script. Terracotta products provide simple configuration setups.
If you are using DSO, you may want to avoid using the dso-java script and start your application with the Terracotta client using your own scripts. See Setting Up the Terracotta Environment.

6.1.4 Configuration in a Production Environment

For an efficient production environment, it's recommended that you maintain one Terracotta configuration file. That file can be loaded by the Terracotta server (or servers) and pushed out to clients. While this is an optional approach, it's an effective way to centralize and decrease maintenance.

If your Terracotta configuration file uses "%i" for the hostname attribute in its server element, change it to the actual hostname in production. For example, if in development you used the following:

<server host="%i" name="Server1">

and the production host's hostname is myHostName, then change the host attribute to the myHostName:

<server host="myHostName" name="Server1">

6.1.4a Clients in Production

For clients in production, you can set up the Terracotta environment before launching your application, or you can use the dso-java script.

Setting Up the Terracotta Environment

To start your application with the Terracotta client using your own scripts, first set the following environment variables:

TC_INSTALL_DIR=<path_to_local_Terracotta_home>
TC_CONFIG_PATH=<path/to/tc-config.xml>

or

TC_CONFIG_PATH=<server_host>:<dso-port>

where <server_host>:<dso-port> points to the running Terracotta Server. The specified Terracotta server will push its configuration to the Terracotta client.

If more than one Terracotta server is available, enter them in a comma-separated list:

TC_CONFIG_PATH=<server_host1>:<dso-port>,<server_host2>:<dso-port>

If <server_host1> is unavailable, <server_host2> is used.

If using DSO, complete setting up the Terracotta client's environment by running the following:

UNIX/Linux
[PROMPT] ${TC_INSTALL_DIR}/bin/dso-env.sh -q
[PROMPT] export JAVA_OPTS="$TC_JAVA_OPTS $JAVA_OPTS"
Microsoft Windows
[PROMPT] %TC_INSTALL_DIR%\bin\dso-env.bat -q
[PROMPT] set JAVA_OPTS=%TC_JAVA_OPTS%;%JAVA_OPTS%

Before starting up your application, confirm that the value of JAVA_OPTS is correct.

6.1.5 terracotta.xml (DSO only)

The file terracotta.xml , which contains a fragment of Terracotta configuration, can be part of a Terracotta integration module (TIM). When the TIM is loaded at runtime, terracotta.xml is inserted into the client configuration. For more information on TIMs and terracotta.xml , see the Terracotta Integration Modules Manual .

NOTE: Element Hierarchy

If the use of terracotta.xml introduces duplicate elements into the client configuration, the value of the last element parsed is used. The last element parsed appears last in order in the configuration file.

6.1.6 Which Configuration?

Each server and client must maintain separate log directories. By default, server logs are written to %(user.home)/terracotta/server-logs and client logs to %(user.home)/terracotta/client-logs .

To find out which configuration a server or client is using, search its logs for an INFO message containing the text "Configuration loaded from".


Top of 6.1 Working with Terracotta Configuration Files