Call us: +1-415-738-4000

Web Sessions Installation Guide

Step 1: Requirements

  • JDK 1.6 or higher.
  • An application server.
  • All clustered objects must be serializable.
  • Download and unpack the BigMemory Max kit, which includes Terracotta Web Sessions.

Step 2: Install the Terracotta Sessions JAR

To cluster your application's web sessions, add the following two JAR files to your application's classpath, and place these files in the WEB-INF/lib folder of the Web Application Archive (WAR) on all of your application servers. These files are under ${TERRACOTTA_HOME}/.

  • sessions/lib/web-sessions-<version>.jar

    <version> is the current version of the Terracotta Web Sessions JAR.

  • apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar

    The Terracotta Toolkit JAR contains the Terracotta client libraries. <version> is the current version of the Terracotta Toolkit JAR.

Step 3: Configure Web-Session Clustering

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 that are not started with a specified configuration will 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 your web.xml file. 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>
<!-- The following init-params are optional. 
 <init-param>
   <param-name>synchronousWrite</param-name>
   <param-value>false</param-value>
 </init-param>
 <init-param>
   <param-name>sessionLocking</param-name>
   <param-value>false</param-value>
 </init-param>
 <init-param>
   <param-name>maxBytesOnHeap</param-name>
   <param-value>128M</param-value>
 </init-param>
 <init-param>
   <param-name>maxBytesOffHeap</param-name>
   <param-value>4G</param-value>
 </init-param>
 <init-param>
   <param-name>rejoin</param-name>
   <param-value>false</param-value>
 </init-param>
 <init-param>
   <param-name>nonStopTimeout</param-name>
   <param-value>-1</param-value>
 </init-param>
 <init-param>
   <param-name>concurrency</param-name>
   <param-value>0</param-value>
 </init-param>
<!-- End of optional init-params. -->
</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>
GlassFish org.terracotta.session.TerracottaGlassfish31xSessionFilter
JBoss 6.1.x org.terracotta.session.TerracottaJboss61xSessionFilter
JBoss 7.1.x org.terracotta.session.TerracottaJboss71xSessionFilter
JBoss 7.2.x org.terracotta.session.TerracottaJboss72xSessionFilter
Jetty 8.1.x org.terracotta.session.TerracottaJetty81xSessionFilter
Jetty 9.0.x org.terracotta.session.TerracottaJetty90xSessionFilter
Resin org.terracotta.session.TerracottaResin40xSessionFilter
Tomcat 6.0.x org.terracotta.session.TerracottaTomcat60xSessionFilter
Tomcat 7.0.x org.terracotta.session.TerracottaTomcat70xSessionFilter
WebLogic 10.3.x org.terracotta.session.TerracottaWeblogic103xSessionFilter
WebLogic 12.1.x org.terracotta.session.TerracottaWeblogic121xSessionFilter
WebSphere 7.0.x org.terracotta.session.TerracottaWebsphere70xSessionFilter
WebSphere 8.0.x org.terracotta.session.TerracottaWebsphere80xSessionFilter
WebSphere 8.5.x org.terracotta.session.TerracottaWebsphere85xSessionFilter

Ensure that the Terracotta filter is the first <filter> element listed in web.xml. Filters processed ahead of the Terracotta filter may disrupt its processing.

web.xml should be in /WEB-INF if you are using a WAR file.

For more information about the optional init-params, refer to the Web Sessions Reference Guide.

Step 4: Start the Cluster

For Terracotta to function properly, make sure that your JAVA_HOME setting is set.

  1. Start the Terracotta server:

    UNIX/Linux

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

    Microsoft Windows

    [PROMPT] ${TERRACOTTA_HOME}\server\bin\start-tc-server.bat
    
  2. Start your application servers.
  3. Start your management console (any JMX monitoring tool is fine) and connect it to your application server. For more information about Terracotta and JMX, refer to JMX Management and Monitoring.

    The console below displays the Web Sessions MBeans.

    Console MBean Panel

The following table describes the Web Sessions MBeans:

MBean Data Type Description
Average Session Lifetime Integer Average local session lifetime (in seconds) @return average session lifetime, or -1 if no sessions have expired.
Average Session Size Long Average local session size (in bytes).
Concurrency (Integer) Number of segments for the map backing the underlying server store managed by the Terracotta Server Array. If concurrency is not explicitly set (or set to "0"), the system selects an optimized value.
Context Path String Context path for this servlet context.
Global Number Of Sessions Long Total number of live sessions that exist in the cluster.
Hit Ratio Double Local hit ratio of the sessions cache @return hit ratio n, or NaN if unavailable.
Max Bytes Off Heap Long Maximum number of bytes allowed in the off-heap tier.
Max Bytes On Heap Long Maximum number of bytes allowed in the heap tier.
Maximum Session Lifetime Integer Maximum local session lifetime (in seconds) @return maximum session lifetime, or -1 if no sessions have expired.
Minimum Session Lifetime Integer Minimum local session lifetime (in seconds) @return minimum session lifetime, or -1 if no sessions have expired.
Nonstop Timeout Long Number of milliseconds an application waits for any cache operation to return before timing out, or -1 if no timeout is configured.
Number Of Sessions Long Number of session objects in local memory.
Rejoin Enabled Boolean Whether client is configured to automatically rejoin its cluster if ejected.
Session Locking Boolean Whether session locking is enabled.
Session Timeout Seconds Integer Number of seconds a session waits before timing out, or -1 if no timeout is configured.
Sessions Created Count Long Number of sessions created locally since initial startup.
Sessions Creation Rate Long Rate of local session creation since initial startup. This number represents the number sessions created in the previous minute.
Synchronous Write Boolean Whether configured to synchronously flush enclosed changes to the Terracotta Server Array, blocking the unlocking thread until changes have been acknowledged as committed.
Total Session Size Long Total local session size (in bytes).

Step 5: Configure Terracotta Clustering

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:

  • Moving the Terracotta server to its own machine
  • Creating a cluster with multiple Terracotta servers
  • Creating multiple application nodes

These tasks bring your cluster closer to a production architecture.

Procedure:

  1. Shut down the Terracotta cluster.
  2. Create a Terracotta configuration file called tc-config.xml with contents similar to the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- All content copyright Terracotta, Inc., unless otherwise indicated.
     All rights reserved. -->
    <tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-9.xsd"
    xmlns:tc="http://www.terracotta.org/config"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    
     <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>
     </servers>
     <!-- Sets where the generated client logs are saved on clients. -->
     <clients>
       <logs>%(user.home)/terracotta/client-logs</logs>
     </clients>
    </tc:tc-config>
    
  3. Install Terracotta on a separate machine for each server you configure in tc-config.xml.
  4. Copy the tc-config.xml to a location accessible to the Terracotta servers.
  5. Perform Step 2: Install the Terracotta Sessions JAR on each application node you want to run in the cluster. Be sure to install your application and any application servers on each node.
  6. Edit web.xml on each application server to list both Terracotta servers:

    <param-value>server.1.ip.address:9510,server.2.ip.address:9510</param-value>
    
  7. 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}/server/bin/start-tc-server.sh -f <path/to/tc-config.xml> \
       -n Server1 
    

    Microsoft Windows

    [PROMPT] ${TERRACOTTA_HOME}\server\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.

  8. Start all application servers.
  9. Start your JMX console tool and view the cluster.

Step 6: Learn More

To learn more about working with a Terracotta cluster, see the following documents: