Setting Up GemFire HTTP Session Management for tc Server

This page provides instructions for setting up and using VMware HTTP Session Management Module for vFabric tc Server. These instructions take advantage of tc Server templates. If you would prefer to manually change the server.xml and context.xml files rather than use tc Server templates, refer to Setting Up GemFire HTTP Session Management for Tomcat.

For an overview of this module, refer to HTTP Session Management Module.

Unknown macro: {toc}

Installing the Module

  1. If you do not already have tc Server, download and install a trial version from the SpringSource download center . These instructions require tc Server 2.1 or greater. (If you are using an older version of tc Server, you should set up the plug-in without templates: Setting Up GemFire HTTP Session Management for Tomcat.)
  2. If you do not already have the GemFire module, download an evaluation copy of HTTP Session Management for tc Server Module from the SpringSource download center. Note that the GemFire module includes within it the GemFire 6.5 Enterprise software.
  3. Unpack the module into the "$CATALINA_HOME$/templates" directory, so that it creates gemfire-p2p and gemfire-cs subdirectories within the tc Server templates directory.
The GemFire evaluation license allows you to create up to three GemFire processes. In order to use GemFire with additional processes, refer to the section on GemFire Licenses in the System Administrator's Guide. When using a license file, be sure to place it in the root directory of the tc Server template in use.

Setting Up the Module

A simple configuration requires that you start a tc Server instance with the appropriate tc Server template depending on your preferred topology. Refer to "Common GemFire Topologies" for more information.

Newer versions of tc Server (for example 2.5.0) allow for the use of either Tomcat 6.x or 7.x with 7.x being the default. Version 1.1 of the HTTP Session Management module is not compatible with Tomcat 7.x. When creating an instance using tcruntime-instance.sh, you must use the --version option to explicitly select Tomcat 6.x for use with the HTTP Session Management module.

Peer-to-Peer Setup

To run GemFire in a peer-to-peer configuration, you must create a tc Server instance using the supplied "gemfire-p2p" template:

Peer-to-peer instance creation with a tc Server template
In Unix:
  prompt$ ./tcruntime-instance.sh create my_instance_name --template gemfire-p2p

In Windows:
  prompt> tcruntime-instance.bat create my_instance_name --template gemfire-p2p

Without making any further configuration changes, peers attempt to locate each other using a default multicast channel. You can change the multicast port, as shown in "Using a Different Multicast Port". Alternatively, peers can discover each other using Locators, which provide both discovery and load balancing services. Refer to "Peer-to-peer Configuration Using Locators" for more information.

Client/Server Setup

To run GemFire in a client/server configuration, the application server will operate as a GemFire client. You must create a tc Server instance using the supplied "gemfire-cs" template:

Client/server instance creation with a tc Server template
In Unix: 
  prompt$ ./tcruntime-instance.sh create my_instance_name --template gemfire-cs

In Windows:
  prompt> tcruntime-instance.bat create my_instance_name --template gemfire-cs

Since the application server operates as a GemFire client in this configuration, you must manually launch a GemFire cache server. You can do this with the following script (which should be installed into the bin subdirectory for the applicable template):

Launching a cache server
In Unix: 
  prompt$ ./cacheserver.sh start
  
In Windows:
  prompt> cacheserver.bat start

See the "cacheserver Command-Line Utility" section of the GemFire System Administrator's Guide for more information on using this script.

If you plan to use the cacheserver script that comes with the standalone GemFire Enterprise product, you will need to manually add the following items to the classpath: INSTANCE_DIR/lib/servlet-api.jar, INSTANCE_DIR/lib/catalina.jar, INSTANCE_DIR/bin/tomcat-juli.jar, INSTANCE_DIR/conf (where 'INSTANCE_DIR' is the location of the tc Server instance you created with the GemFire template). Note that these items are automatically added to the classpath by the supplied cacheserver.sh (or cacheserver.bat) script that comes with the GemFire HTTP Session Management module.

Without making any further configuration changes, the client and server attempt to locate each other on the same system using a default port (40404). Though useful for testing purposes, you would not normally deploy a client/server configuration in this way. Refer to "Client/Server Configuration Using Locators" for information on creating and using Locators, which provide both discovery and load balancing services.

Since the client/server configuration uses a local client cache by default, it is important to set up your application server for sticky sessions so that application clients access the same application server across a session interval. See Sticky Load Balancers for more information.

Starting the Application Server

Once you've created a tc Server instance, you are ready to start the instance.

Starting the instance
In Unix: 
  prompt$ ./tcruntime-ctl.sh my_instance_name start
  
In Windows:
  prompt$ ./tcruntime-ctl.bat my_instance_name start

Refer to the tc Server documentation for more information. Once started, GemFire will automatically launch within the application server process.

GemFire session state management provides its own clustering functionality. If you are using GemFire, you should NOT turn on Tomcat clustering as well.

Verifying that GemFire Started

You can verify that GemFire has successfully started by inspecting the Tomcat log file. For example:

Verifying GemFire started
Nov 8, 2010 12:12:12 PM
com.gemstone.gemfire.modules.session.catalina.ClientServerCacheLifecycleListener
createOrRetrieveCache
INFO: Created GemFireCache[id = 2066231378; isClosing = false; 
   created = Mon Nov 08 12:12:12 PDT 2010; server = false; 
   copyOnRead = false; lockLease = 120; lockTimeout = 60]

Information is also logged within the GemFire log file, which by default is named "gemfire_modules.log".

Changing GemFire's Default Configuration

By default, the GemFire module will run GemFire automatically with pre-configured settings. Specifically:

  • GemFire peer-to-peer members are discovered using a default multicast channel.
  • GemFire locators are not used for member discovery.
  • The region name is set to gemfire_modules_sessions.
  • The cache region is replicated for peer-to-peer configurations and partitioned (with redundancy turned on) for client/server configurations.
  • GemFire clients have local caching turned on and when the local cache needs to evict data, it will evict least-recently-used (LRU) data first.

If you were to manually define the default cache region for a peer-to-peer configuration, you would place this XML content into GemFire's cache.xml file:

Default Peer-to-peer Region Configuration
<region name="gemfire_modules_sessions">
  <region-attributes scope="distributed-ack" enable-gateway="false" data-policy="replicate" statistics-enabled="true">
    <entry-idle-time>
      <expiration-attributes timeout="0" action="invalidate">
        <custom-expiry>
          <class-name>com.gemstone.gemfire.modules.util.SessionCustomExpiry</class-name>
        </custom-expiry>
      </expiration-attributes>
    </entry-idle-time>
  </region-attributes>
</region>

If you were to manually define the default cache region for a client/server configuration, you would place this XML content into GemFire's cache.xml file:

Default Client/Server Region Configuration
<region name="gemfire_modules_sessions">
  <region-attributes enable-gateway="false" data-policy="partition" statistics-enabled="true">
    <entry-idle-time>
      <expiration-attributes timeout="0" action="invalidate">
        <custom-expiry>
          <class-name>com.gemstone.gemfire.modules.util.SessionCustomExpiry</class-name>
        </custom-expiry>
      </expiration-attributes>
    </entry-idle-time>
    <partition-attributes redundant-copies="1" total-num-buckets="113"/>
  </region-attributes>
</region>

You may want to change this default configuration. For example, you might want to change the region from replicated to partitioned, or use locators for discovery, or set up a multi-site configuration. To change GemFire settings – rather than manipulate these XML files by hand – you can change the most common configuration values using tc Server's "--interactive" mode when creating your instance.

Running the tc Server templates in interactive mode
In Unix:
  prompt$ ./tcruntime-instance.sh create my_instance_name --template gemfire-p2p --interactive
  prompt$ ./tcruntime-instance.sh create my_instance_name --template gemfire-cs --interactive

In Windows:
  prompt> tcruntime-instance.bat create my_instance_name --template gemfire-p2p --interactive
  prompt> tcruntime-instance.bat create my_instance_name --template gemfire-cs --interactive

In interactive mode, you will be prompted to specify a series of property values. Hit <return> for any property where you would like to use the default value.

Starting interactive mode
  Creating instance 'my_instance_name' ...
  Using separate layout
  Please enter a value for 'gemfire.maximum.vm.heap.size.mb'. Default '512':
  Please enter a value for 'gemfire.initial.vm.heap.size.mb'. Default '512':
  ...
  ...

After responding to approximately 20 prompts, you should see the following line:

Completing interactive mode
Instance created.

For information on setting up your instance for the most common types of configurations, refer to the sections below. For more information about each interactive prompt, refer to Interactive Mode Reference. If you plan to change GemFire configuration information manually, refer to the complete GemFire Documentation.

By default, the inactive interval for session expiration is set to 30 minutes. To change this value, refer to Session Expiration.

Using a Different Multicast Port

For a GemFire peer-to-peer member to communicate on a different multicast port than the default (10334), answer the following question in interactive mode:

Interactive mode example: changing multicast port
  Please enter the port used by GemFire members to discover each other using multicast
  networking. Default '10334': 10335

This example changes the multicast port to 10335.

You typically should change the multicast port so that you don't inadvertently join another GemFire cluster on the same network.

Peer-to-peer Configuration Using Locators

By default, GemFire peers discover each other using multicast communication on a known port. Alternatively, you can configure member discovery using one or more dedicated locators. A locator provides both discovery and load balancing services.

To run GemFire with one or more locators, turn off multicast discovery (by setting it to 0) and specify the list of locators.

Interactive mode example: using peer-to-peer locators
  Please enter the port used by GemFire members to discover each other using multicast
  networking. Default '10334': 0
  
  Please enter the list of locators used by GemFire members to discover each other. 
  The format is a comma-separated list of host[port]. Default ' ': hostname[10334]

This example turns off multicast discovery and uses a locator at hostname on port 10334.

You must be sure when you specify a locator that you specifically launch a locator correctly at this location. You can do this using the gemfire command-line tool found in the bin subdirectory.

Launching a locator
In Unix:
  ./gemfire.sh start-locator -port=10334
  
In Windows:
  gemfire.bat start-locator -port=10334

This example starts a locator that listens on port 10334.

Client/Server Configuration Using Locators

By default, GemFire clients and servers discover each other on a pre-defined port on the localhost. This is not typically the way you would deploy a client/server configuration. A preferred solution is to use one or more dedicated locators. A locator provides both discovery and load balancing services.

To run GemFire with one or more locators instead of a multicast port, add locator information to the cache-client.xml file in the conf subdirectory of the applicable instance.

Using a locator with a GemFire client
  <pool name="sessions">
    <locator host="hostname" port="10334"/>
  </pool>

This example tells the GemFire client (which is the process running the application server) to use a locator at hostname on port 10334.

You must now launch a locator correctly at this location. You can do this using the gemfire command-line tool found in the bin subdirectory.

Launching a locator
./gemfire start-locator -port=10334

This example starts a locator that listens on port 10334.

You also need to tell the GemFire server to use a locator when you launch the server. You can do this through a command-line argument when you start up the server with the script provided in the bin subdirectory wherever you installed GemFire:

Launching a cache server with a locator
In Unix: 
  prompt$ ./cacheserver.sh start locators=hostname[port]
  
In Windows:
  prompt> cacheserver.bat start locators=hostname[port]

If you are running more than one locator, use a comma-separated list of locators. See the "cacheserver Command-Line Utility" section of the GemFire System Administrator's Guide for more information on using this script.

Multi-site Setup

For information on when to use this topology, refer to "Common GemFire Topologies". Setting up a gateway for multi-site communication requires a few configuration changes. You should first create an instance in interactive mode and respond to the following prompt by typing true:

Interactive mode example: multi-site / gateway setup
  Please specify whether session modifications should be replicated across the WAN. 
  Default 'false': true

After creating the instance, you will need to modify the GemFire configuration file (either cache-peer.xml for a peer-to-peer configuration or cache-server.xml for a client/server configuration) in the conf subdirectory of the system that will operate as the gateway hub. For example, if you were setting up a gateway between a site named "SITE1" and a site named "SITE2", this is how you would set up the information for site 1:

Setting up gateway hub
	<gateway-hub id="SITE1" port="22222" socket-buffer-size="256000">
		<gateway id="SITE2_CLUSTERA" socket-buffer-size="256000">
			<gateway-endpoint id="SITE2_CLUSTERA_server1" host="site2_hostname" port="22222"/>
		</gateway>
	</gateway-hub>

And at site 2, you would need to set up another gateway hub that communicates with site 1. Notice that the endpoint for site 1 references information about site 2 while the endpoint for site 2 references information about site 1.

Setting up gateway hub
	<gateway-hub id="SITE2" port="22222" socket-buffer-size="256000">
		<gateway id="SITE1_CLUSTERA" socket-buffer-size="256000">
			<gateway-endpoint id="SITE1_CLUSTERA_server1" host="site1_hostname" port="22222"/>
		</gateway>
	</gateway-hub>
To successfully run a configuration using a multi-site topology, you must start at least one server and one client in each site before creating or accessing your session. If a GemFire client is not started in one site, the region data containing the session information will not get initialized. This means that a tc Server instance must be started on each site before creating or accessing session data.

See Configuring Multi-site Installations in the GemFire Developer's Guide for complete information on setting up a multi-site configuration.

Interactive Mode Reference

This section describes each prompt when entering into interactive mode. See "Changing GemFire's Default Configuration" for more information about interactive mode.

  Please enter a value for 'gemfire.maximum.vm.heap.size.mb'. Default '512':
  Please enter a value for 'gemfire.initial.vm.heap.size.mb'. Default '512':
  Please enter a value for 'gemfire.cms.initiating.heap.percentage'. Default '50':

The above properties allow you to fine-tune your VM heap and garbage collector. For information on fine-tuning your VM heap, refer to "Setting your VM's GC tuning parameters" in the GemFire Developer's Guide.

  Please specify whether to enable a GemFire listener that logs session create, update,
  destroy and expiration events. Default 'false':

The above property determines whether a debug cache listener is added to the session region. When true, info-level messages are logged to the GemFire log when sessions are created, updated, invalidated, or expired.

  Please specify whether session modifications should be replicated across the WAN. 
  Default 'false':

The above property determines whether sessions are replicated across the gateway. When true, a GatewayHub must be configured, as discussed in "Multi-site Setup".

With the gemfire-p2p template:
  Please specify whether to maintain a local GemFire cache. Default 'false':
  
With the gemfire-cs template:
  Please specify whether to maintain a local GemFire cache. Default 'true':

The above property determines whether a local cache is enabled; if this parameter is set to true, the app server load balancer should be configured for sticky session mode.

With the gemfire-p2p template:
  Please enter the id of the attributes of the GemFire region used to cache sessions.
  Default 'REPLICATE':

With the gemfire-cs template:
  Please enter the id of the attributes of the GemFire region used to cache sessions.
  Default 'PARTITION_REDUNDANT':

The above property determines the ID of the attributes for the cache region; possible values include PARTITION, PARTITION_REDUNDANT, PARTITION_PERSISTENT, REPLICATE, REPLICATE_PERSISTENT, and any other region shortcut that can be found in the "Region Shortcuts and Custom Named Region Attributes" section of the GemFire Developer's Guide. When using a partitioned region attribute, it is recommended that you use PARTITION_REDUNDANT (rather than PARTITION) to ensure that the failure of a server does not result in lost session data.

  Please enter the name of the GemFire region used to cache sessions. 
  Default 'gemfire_modules_sessions':

The above property determines the GemFire region name.

  Please enter the port that Tomcat Shutdown should listen on. Default '-1':
  Please enter the port that the JMX socket listener should listen on. Default '6969':

The above properties are application server properties.

  Please enter a value for 'bio.http.port'. Default '8080':
  Please enter a value for 'bio.https.port'. Default '8443':

tc Server requires information about connector ports. bio.http.port is the http port for tc Server and bio.https.port is the secure http port for tc Server.

With the gemfire-p2p template:
  Please enter the name of the GemFire cache configuration file. 
  Default 'cache-peer.xml':
  
With the gemfire-cs template:
  Please enter the name of the GemFire cache configuration file. 
  Default 'cache-client.xml':

You can change the name of the cache configuration file with the above property. If you do change this value, be sure to include an xml file by that name in the conf subdirectory.

  Please enter the percentage of heap at which updates to the cache are refused.
  0.0 means disabled. Default '0.0':
  Please enter the percentage of heap at which sessions will be evicted from the 
  local cache. Default '80.0':

The above properties allow you to control the critical and eviction watermarks for the heap. By default, the critical watermark is disabled (set to 0.0) and the eviction watermark is set to 80%.

Applicable to the gemfire-p2p template ONLY:
  Please enter the list of locators used by GemFire members to discover each other. 
  The format is a comma-separated list of host[port]. Default ' ':

The above property specifies the list of locators. For more information on locators, refer to "Peer-to-peer Configuration Using Locators".

  Please enter the name of the file used to log GemFire messages. 
  Default 'gemfire_modules.log':

The above property determines the filename for the GemFire log file.

Applicable to the gemfire-p2p template ONLY:
  Please enter the port used by GemFire members to discover each other using multicast
  networking. Default '10334': 

The above property specifies the port used for multicast discovery. When using locators, this value should be 0. For more information on multicast discovery, refer to "Using a Different Multicast Port".

Applicable to the gemfire-p2p template ONLY:
  Please specify whether to rebalance the GemFire cache at startup. Default 'false':

This property allows you to rebalance a partitioned GemFire cache when a new GemFire peer starts up.

  Please enter the name of the file used to store GemFire statistics. 
  Default 'gemfire_modules.gfs':

The above property determines the filename for the GemFire statistics file.

  Please specify whether GemFire statistic sampling should be enabled. Default 'false':

The above property determines whether statistics sampling should occur. See the "System Statistics " section of the GemFire System Administrator's Guide for more information.

Additional Information

Relevant Links

Sticky Load Balancers

Typically, session replication will be used in conjunction with a load balancer enabled for sticky sessions. This involves, among other things, establishing a JVM route (JVMRoute=value). Refer to SpringSource ERS as a possible load balancing solution.

Session Expiration

To set the session expiration value, you must change the session-timeout value specified in Tomcat's WEB-INF/web.xml file. This value will override the GemFire inactive interval specified by maxInactiveInterval within context.xml.

Making Additional GemFire Property Changes

If you want to change additional GemFire property values that are not specified in this documentation, refer to instructions on manually changing property values as specified in the GemFire module documentation for Tomcat: Changing GemFire's Configuration Manually.

Using the gemfire Command-line Tool

GemFire provides the gemfire command-line tool to perform basic administrative tasks. gemfire.sh (for Unix) and gemfire.bat (for Windows) should be located in the /bin subdirectory. Consult the "gemfire Command-line Utility" section of the GemFire System Administrator's Guide for more information on this tool.

Running GemFire as a Standalone Product

For information on running GemFire as a standalone product, refer to GemFire Enterprise.

Module Version Information

To acquire GemFire module version information, look in the Tomcat log file for the following message:

Nov 8, 2010 12:12:12 PM 
com.gemstone.gemfire.modules.session.catalina.AbstractCacheLifecycleListener lifecycleEvent
INFO: Initializing GemFire Modules Version 1.0

top

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.