The Tomcat Web container provides a native clustering solution that can be configured through Geronimo using gbean definitions within config.xml or your deployment descriptors . This document will go through the available GBeans and how to configure them for clustering in a Geronimo server with a tomcat web container.
A cluster configuration should be considered when you want to improve the scalability and availability of your Web application. The following sections provide detailed instructions on how to set up your cluster nodes and how to deploy your applications with tomcat clustering enabled.

Setting up a clustering environment

Generally, to set up a small cluster you will need at least 2 nodes and 1 HTTP server. The HTTP server is used to serve requests from clients and ensure well-balanced traffic load among different nodes. Similarly, each node is configured to use the same logical Tomcat engine and enable session affinity.

Planning your cluster

The Tomcat cluster replicates HTTP session data via memory to memory multicast communication.

Every node transmits its session data to every node in the cluster. This algorithm is only efficient when the clusters are small. If the clusters grow too large, the overhead in storage utilization and network traffic becomes excessive. To avoid excessive overhead, consider dividing your nodes into several smaller clusters.

HTTP session data is replicated among the nodes in the cluster using a multicast broadcast. All nodes in the cluster must be on the same physical subnet and multicast broadcast must be supported by that subnet.

Preparing your Web application

To participate in a cluster configuration, your Web application must be implemented correctly.

Ensure that every object placed in the HTTP session implements java.io.Serializable. The clustering feature serializes the objects when it distributes them to the other nodes in the cluster.

The deployment descriptor for your Web application, that is the web.xml file in the Web archive, must indicate that your Web application is distributable. To do this, insert the distributable element in the deployment descriptor.

Excerpt from web.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
    <display-name> ... </display-name>
    <description> ... </description>
    <distributable> <distributable/>
  ...
</web-app>

Do not use stateful session Enterprise JavaBeans (EJBs). The clustering feature does not replicate stateful EJBs among the nodes in the cluster.
If your Web application uses a database, make sure the database can be accessed from every node in the cluster. Ensure that the proper JDBC drivers are installed on every node and that the datasource objects are defined correctly on every node.
Do not depend on dynamic updates to the Java Naming and Directory Interface (JNDI). You will need to configure all the JNDI names used by your application in every node of the cluster. The clustering feature does not replicate JNDI changes among the nodes in the cluster.

Enable Session Affinity

Support for session affinity, also known as sticky session support, allows a load balancing service to route an HTTP request back to the same node that created the HTTP session associated with that request until that node fails. You must use session affinity if you configure an asynchronous type of session replication. With asynchronous replication, the reply is returned before the HTTP session is replicated so there is always a chance that the next request using that session arrives before the replication is complete. In this case, the only way to ensure that the request is processed using the correct session data is to route the request to the node that sent the reply to the last request and originated the replication.

For every node in the cluster, update config.xml as follows after the server is stopped

Excerpt from config.xml

<gbean name="TomcatEngine">
  <attribute name="initParams">
    name=geronimo
    jvmRoute=nodeId
  </attribute>
</gbean>

Engaging load balancing and failover

Initially, the server configuration includes an AJP connector suitable for exchanging messages with a load balancing service. See Configuring a remote Apache HTTP server for more information about the HTTP server configuration.

Deploying your application to a cluster

To deploy your application to a cluster and make sure HTTP sessions are replicated successfully, cluster configuration elements of Tomcat Web containers must be configured using GBean definitions within deployment plans.

If you want to deploy your Web application to a cluster, install your WAR files to the appropriate cluster member, assuring that you use the correct deployment plan for each member. Here is the template for your Web application deployment plan

Sample geronimo-web.xml for geronimo 2.1.4 and below

geronimo-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-2.0.1"
         xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">

    <dep:environment>
        <dep:moduleId>
        <dep:groupId>org.mygroup</dep:groupId>
        <dep:artifactId>web-cluster-server1</dep:artifactId>
        <dep:version>2.1.1.2</dep:version>
        <dep:type>war</dep:type>
        </dep:moduleId>
        <dep:dependencies/>
        <dep:hidden-classes/>
        <dep:non-overridable-classes/>
    </dep:environment>

    <context-root>/servlet-examples-cluster</context-root>

    <security-realm-name>geronimo-properties-realm</security-realm-name>
    <security>
        <default-principal>
        <principal name="anonymous" class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"/>
      </default-principal>
      <role-mappings>
        <role role-name="tomcat">
          <principal name="admin" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"/>
        </role>
      </role-mappings>
    </security>

    <cluster>TomcatCluster</cluster>
    <gbean class="org.apache.geronimo.tomcat.cluster.CatalinaClusterGBean" name="TomcatCluster">
        <attribute name="className">org.apache.catalina.ha.tcp.SimpleTcpCluster</attribute>
        <attribute name="initParams">
            managerClassName=org.apache.catalina.ha.session.DeltaManager
            expireSessionsOnShutdown=false
            useDirtyFlag=true
            notifyListenersOnReplication=true
        </attribute>
        <reference name="TomcatValveChain">
            <name>ReplicationValve</name>
        </reference>
        <reference name="ClusterListenerChain">
            <name>ClusterSessionListener</name>
        </reference>
        <reference name="Channel">
            <name>TomcatGroupChannel</name>
        </reference>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.ChannelGBean" name="TomcatGroupChannel">
        <attribute name="className">org.apache.catalina.tribes.group.GroupChannel</attribute>
        <attribute name="initParams"/>
        <reference name="Membership">
            <name>TomcatMembership</name>
        </reference>
        <reference name="Receiver">
            <name>TomcatReceiver</name>
        </reference>
        <reference name="Sender">
            <name>TomcatSender</name>
        </reference>
        <reference name="ChannelInterceptor">
            <name>TomcatChannelInterceptor</name>
        </reference>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.MembershipServiceGBean" name="TomcatMembership">
        <attribute name="className">org.apache.catalina.tribes.membership.McastService</attribute>
        <attribute name="initParams">
            mcastAddr=228.0.0.4
            mcastPort=45564
            mcastFrequency=500
            mcastDropTime=3000
        </attribute>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.ReceiverGBean" name="TomcatReceiver">
        <attribute name="className">org.apache.catalina.tribes.transport.nio.NioReceiver</attribute>
        <attribute name="initParams">
            tcpListenAddress=IPAddressIn
            tcpListenPort=4001
            tcpSelectorTimeout=100
            tcpThreadCount=6
        </attribute>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.SenderGBean" name="TomcatSender">
        <attribute name="className">org.apache.catalina.tribes.transport.ReplicationTransmitter</attribute>
        <attribute name="initParams">
            replicationMode=pooled
            waitForAck=true
        </attribute>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.ValveGBean" name="ReplicationValve">
        <attribute name="className">org.apache.catalina.ha.tcp.ReplicationValve</attribute>
        <attribute name="initParams">filter=.*\.gif;.*\.js;.*\.css;.*\.png;.*\.jpeg;.*\.jpg;.*\.htm;.*\.html;.*\.txt;</attribute>
        <reference name="NextValve">
            <name>JvmRouteBinderValve</name>
        </reference>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.ValveGBean" name="JvmRouteBinderValve">
        <attribute name="className">org.apache.catalina.ha.session.JvmRouteBinderValve</attribute>
        <attribute name="initParams">enabled=true</attribute>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.ClusterListenerGBean" name="ClusterSessionListener">
        <attribute name="className">org.apache.catalina.ha.session.ClusterSessionListener</attribute>
        <reference name="NextListener">
            <name>JvmRouteSessionIDBinderListener</name>
        </reference>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.ClusterListenerGBean" name="JvmRouteSessionIDBinderListener">
        <attribute name="className">org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener</attribute>
    </gbean>
    <gbean class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean" name="TomcatChannelInterceptor">
        <attribute name="className">org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</attribute>
    </gbean>
</web-app>

Sample geronimo-web.xml for geronimo versions above 2.1.4. This does not include g 2.2
After applying fix to 2.1 through GERONIMO-4187 there are some modifications which needs to picked up by your configuration through geronimo-web.xml