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.
- 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.)
- 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.
- 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.|
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.
To run GemFire in a peer-to-peer configuration, you must create a tc Server instance using the supplied "gemfire-p2p" template:
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.
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:
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):
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.|
Once you've created a tc Server instance, you are ready to start the instance.
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.|
You can verify that GemFire has successfully started by inspecting the Tomcat log file. For example:
Information is also logged within the GemFire log file, which by default is named "gemfire_modules.log".
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:
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:
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.
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.
After responding to approximately 20 prompts, you should see the following line:
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.|
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:
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.
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.
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.
This example starts a locator that listens on port 10334.
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.
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.
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:
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.
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:
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:
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.
|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.
This section describes each prompt when entering into interactive mode. See "Changing GemFire's Default Configuration" for more information about interactive mode.
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.
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.
The above property determines whether sessions are replicated across the gateway. When true, a GatewayHub must be configured, as discussed in "Multi-site Setup".
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.
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.
The above property determines the GemFire region name.
The above properties are application server properties.
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.
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.
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%.
The above property specifies the list of locators. For more information on locators, refer to "Peer-to-peer Configuration Using Locators".
The above property determines the filename for the GemFire log file.
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".
This property allows you to rebalance a partitioned GemFire cache when a new GemFire peer starts up.
The above property determines the filename for the GemFire statistics file.
The above property determines whether statistics sampling should occur. See the "System Statistics " section of the GemFire System Administrator's Guide for more information.
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.
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.
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.
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.
For information on running GemFire as a standalone product, refer to GemFire Enterprise.
To acquire GemFire module version information, look in the Tomcat log file for the following message: