This site hosts historical documentation. Visit www.terracotta.org for recent product information.
This document shows you how to cluster web sessions without the requirements imposed by Terracotta DSO, such as cluster-wide locking, class instrumentation, and class portability. If you must use DSO, see Terracotta DSO Installation.
For guaranteed compatibility, use the JAR files included with the Terracotta kit you are installing. Mixing with older components may cause errors or unexpected behavior.
To cluster your application’s web sessions, add the following JAR files to your application's classpath:
${TERRACOTTA_HOME}/sessions/terracotta-session-<version>.jar
<version> is the current version of the Terracotta Sessions JAR. For use with WebSphere, you must have Terracotta Sessions JAR version 1.0.2 or higher.
${TERRACOTTA_HOME}/common/terracotta-toolkit-<API-version>-runtime-ee-<version>.jar
The Terracotta Toolkit JAR contains the Terracotta client libraries. <API-version> refers to the Terracotta Toolkit API version. <version> is the current version of the Terracotta Toolkit JAR.
If you are using the open-source edition of the Terracotta kit, no JAR files will have "-ee-" as part of their name.
See the following table on suggestions on where to add the sessions and toolkit JAR files based on application server.
Application Server | Suggested Location for Terracotta Sessions JAR File |
---|---|
JBoss AS (earlier than 6.0) | <jboss install dir>/lib |
JBoss AS 6.0 | <jboss install dir>/common/lib |
JBoss AS 7.0 or 7.1 | <jboss install dir>/WEB-INF/lib |
Jetty | WEB-INF/lib |
Tomcat 5.0 and 5.5 | $CATALINA_HOME/server/lib |
Tomcat 6.0 and 7.0 | $CATALINA_HOME/lib |
WebLogic | WEB-INF/lib |
The table above lists the only application servers supported by the express installation. See Platform Support to obtain the latest versions for the listed application servers. |
Terracotta servers, and Terracotta clients running on the application servers in the cluster, are configured with a Terracotta configuration file, tc-config.xml
by default. Servers not started with a specified configuration use a default configuration.
To add Terracotta clustering to your application, you must specify how Terracotta clients get their configuration by including the source in web.xml
or context.xml
.
Find the configuration to use for your application server in the sections below.
Add the following configuration snippet to web.xml
:
<filter>
<filter-name>terracotta</filter-name>
<!-- The filter class is specific to the application server. -->
<filter-class>org.terracotta.session.{container-specific-class}</filter-class>
<init-param>
<param-name>tcConfigUrl</param-name>
<!-- <init-param> of type tcConfigUrl has a <param-value> element containing the URL or filepath (for example, /lib/tc-config.xml) to tc-config.xml. If the Terracotta configuration source changes at a later time, it must be updated in configuration. -->
<param-value>localhost:9510</param-value>
</init-param>
</filter>
<filter-mapping>
<!-- Must match filter name from above. -->
<filter-name>terracotta</filter-name>
<url-pattern>/*</url-pattern>
<!-- Enable all available dispatchers. -->
<dispatcher>ERROR</dispatcher>
<dispatcher>INCLUDE</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-name> can contain a string of your choice. However, the value of <filter>/<filter-name> must match <filter-mapping>/<filter-name>.
Choose the appropriate value for <filter-class> from the following table.
Container | Value of <filter-class> |
---|---|
Jetty 6.1 |
org.terracotta.session.TerracottaJetty61xSessionFilter
|
Jetty 7.4.1 |
org.terracotta.session.TerracottaJetty74xSessionFilter
|
WebLogic 9 |
org.terracotta.session.TerracottaWeblogic9xSessionFilter
|
WebLogic 10 |
org.terracotta.session.TerracottaWeblogic10xSessionFilter
|
WebSphere 6.1 |
org.terracotta.session.TerracottaWebsphere61xSessionFilter
|
WebSphere 7.0 |
org.terracotta.session.TerracottaWebsphere70xSessionFilter
|
TerracottaWebsphere70xSessionFilter.java
If you have customized a Terracotta configuration file and want to include its contents rather than providing an URL, use an <init-param> of type tcConfig
:
<init-param>
<param-name>tcConfig</param-name>
<param-value>&lt;tc:tc-config ... &lt;/tc:tc-config&gt;</param-value>
</init-param>
Use URL-safe codes (also known as "URL escaping") or HTML names for all special characters such as angle brackets ("<" and ">").
Ensure that the Terracotta filter is the first <filter> element listed in web.xml
. Filters processed ahead of the Terracotta valve may disrupt its processing.
web.xml
should be in /WEB-INF
if you are using a WAR file.
Add the following to context.xml
:
<Valve className="org.terracotta.session.{container-specific-class}" tcConfigUrl="localhost:9510"/>
where tcConfigUrl
contains an URL or file path (for example, tcConfigURL="/lib/tc-config.xml"
) to tc-config.xml
. If the Terracotta configuration source changes at a later time, it must be updated in configuration.
If you have customized a Terracotta configuration file and want to include its contents rather than providing an URL, replace tcConfigUrl with tcConfig:
<Valve className="org.terracotta.session.{container-specific-class}" tcConfig="&lt;tc:tc-config ... &lt;/tc:tc-config&gt;"/>
Use URL-safe codes (also known as "URL escaping") or HTML names for all special characters such as angle brackets ("<" and ">"). Choose the appropriate value of className from the following table.
Container | Value of className |
---|---|
JBoss Application Server 4.0 |
org.terracotta.session.TerracottaJboss40xSessionValve
|
JBoss Application Server 4.2 |
org.terracotta.session.TerracottaJboss42xSessionValve
|
JBoss Application Server 5.1 |
org.terracotta.session.TerracottaJboss51xSessionValve
|
JBoss Application Server 6.0 |
org.terracotta.session.TerracottaJboss60xSessionValve
|
Tomcat 5.0 |
org.terracotta.session.TerracottaTomcat50xSessionValve
|
Tomcat 5.5 |
org.terracotta.session.TerracottaTomcat55xSessionValve
|
Tomcat 6.0 |
org.terracotta.session.TerracottaTomcat60xSessionValve
|
Tomcat 7.0 | org.terracotta.session.TerracottaTomcat70xSessionValve |
For example, to use Tomcat 6.0, the content of context.xml
should be similar to the following:
<Context>
<Valve className="org.terracotta.session.TerracottaTomcat60xSessionValve" tcConfigUrl="localhost:9510"/>
</Context>
Ensure that the Terracotta valve is the first <Valve> element listed in context.xml
. Valves processed ahead of the Terracotta valve may disrupt its processing.
If you use one of the authenticator valves available with Tomcat, you may encounter an UnsupportedOperationException when running with Terracotta clustering. With Tomcat 5.5 and above, users can prevent this error by disabling changeSessionIdOnAuthentication . For example:
|
If you are using a WAR file, context.xml
should be in /META-INF
for Tomcat and in /WEB-INF
for JBoss Application Server.
Add the following to WEB-INF/jboss-web.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
...
<valve>
<class-name>org.terracotta.session.TerracottaJboss7xSessionValve</class-name>
<param>
<param-name>tcConfigUrl</param-name>
<param-value>localhost:9510</param-value>
</param>
</valve>
...
</jboss-web>
where the value for tcConfigUrl
contains an URL or file path (for example, /lib/tc-config.xml
) to tc-config.xml
. If the Terracotta configuration source changes at a later time, it must be updated in configuration.
If you have customized a Terracotta configuration file and want to include its contents rather than providing an URL, replace tcConfigUrl with tcConfig:
<param-name>tcConfig</param-name>
<param-value>&lt;tc:tc-config ... &lt;/tc:tc-config&gt;</param-value>
Use URL-safe codes (also known as "URL escaping") or HTML names for all special characters such as angle brackets ("<" and ">").
Start the Terracotta server:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh &
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat
Start the Terracotta Developer Console:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/dev-console.sh &
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\bin\dev-console.bat
Connect to the Terracotta cluster. Click Connect... in the Terracotta Developer Console.
Click the Topology node in the cluster navigation window to see the Terracotta servers and clients (application servers) in the Terracotta cluster. Your console should have a similar appearance to the following figure.
This step shows you how to run clients and servers on separate machines and add failover (High Availability). You will expand the Terracotta cluster and add High Availability by doing the following:
These tasks bring your cluster closer to a production architecture.
Create a Terracotta configuration file called tc-config.xml
with contents similar to the following:
<servers>
<!-- Sets where the Terracotta server can be found. Replace the value of host with the server's IP address. -->
<server host="server.1.ip.address" name="Server1">
<data>%(user.home)/terracotta/server-data</data>
<logs>%(user.home)/terracotta/server-logs</logs>
</server>
<!-- If using a standby Terracotta server, also referred to as an ACTIVE-PASSIVE configuration, add the second server here. -->
<server host="server.2.ip.address" name="Server2">
<data>%(user.home)/terracotta/server-data</data>
<logs>%(user.home)/terracotta/server-logs</logs>
</server>
<!-- If using more than one server, add an <ha> section. -->
<ha>
<mode>networked-active-passive</mode>
<networked-active-passive>
<election-time>5</election-time>
</networked-active-passive>
</ha>
</servers>
<!-- Sets where the generated client logs are saved on clients. -->
<clients>
<logs>%(user.home)/terracotta/client-logs</logs>
</clients>
</tc:tc-config>
tc-config.xml
.tc-config.xml
to a location accessible to the Terracotta servers.Edit web.xml
or context.xml
on each application server to list both Terracotta servers:
<param-value>server.1.ip.address:9510,server.2.ip.address:9510</param-value>
or
tcConfigUrl="server.1.ip.address:9510,server.2.ip.address:9510"
Start the Terracotta server in the following way, replacing "Server1" with the name you gave your server in tc-config.xml
:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh -f <path/to/tc-config.xml> -n Server1 &
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat -f <path\to\tc-config.xml> -n Server1 &
If you configured a second server, start that server in the same way on its machine, entering its name after the -n
flag. The second server to start up becomes the "hot" standby, or PASSIVE. Any other servers you configured will also start up as standby servers.
To learn more about working with a Terracotta cluster, see the following documents:
tc-config.xml
is propagated and loaded in a Terracotta cluster in different environments.