geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Geronimo v3.0 > Tomcat Native Clustering
Date Wed, 26 Jan 2011 02:35:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/4/_/styles/combined.css?spaceKey=GMOxDOC30&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Tomcat+Native+Clustering">Tomcat Native Clustering</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~maojia508">maojia</a>
    </h4>
        <br/>
                         <h4>Changes (32)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-unchanged" >{scrollbar} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >{excerpt}The Tomcat Web container provides a native clustering solution that can be configured through Geronimo <span class="diff-added-words"style="background-color: #dfd;">by</span> using gbean definitions within {{config.xml}} or <span class="diff-added-words"style="background-color: #dfd;">by</span> using {{server.xml}} starting from v2.2 just like you did for a standalone Tomcat server.{excerpt}  This document will go through the available GBeans and how to configure them for clustering in a Geronimo server with a tomcat web container. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{toc} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Cluster Configuration Elements <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Following are parameters or attributes <span class="diff-added-words"style="background-color: #dfd;">that</span> you will need to configure for a Tomcat native clustering. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>* Cluster <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >** ClusterManager <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Although sufficient for many applications, Tomcat clusters have some <span class="diff-changed-words">limitations<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">.</span><span class="diff-added-chars"style="background-color: #dfd;">:</span></span> <br></td></tr>
            <tr><td class="diff-changed-lines" >* This feature does not replicate stateful session Enterprise JavaBeans (EJBs). <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">You will have to avoid</span> <span class="diff-added-words"style="background-color: #dfd;">Do not use</span> stateful session EJBs in your distributed applications. <br></td></tr>
            <tr><td class="diff-changed-lines" >* This feature does not replicate dynamic updates to the Java Naming and Directory Interface (JNDI). You will have to configure all the JNDI names <span class="diff-added-words"style="background-color: #dfd;">that are</span> used by your distributed applications in every node of the cluster. <br></td></tr>
            <tr><td class="diff-unchanged" >* This feature does not replicate distributable Web applications to other nodes in the cluster. You will have to deploy your distributable Web applications to every node. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Consider a cluster configuration to improve the scalability and availability of your Web application. The following sections provide detailed instructions about how to set up your cluster nodes. <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br>h1. Setting up a clustering environment <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Generally, to</span> <span class="diff-added-words"style="background-color: #dfd;">To</span> set up a small <span class="diff-changed-words">cluster<span class="diff-added-chars"style="background-color: #dfd;">,</span></span> you <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">will</span> 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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Planning your cluster <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The Tomcat cluster replicates HTTP session data <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">via memory to memory</span> <span class="diff-added-words"style="background-color: #dfd;">by memory-to-memory</span> multicast communication. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >Every node transmits its session data to every <span class="diff-added-words"style="background-color: #dfd;">other</span> node in the cluster. This algorithm is <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">only</span> efficient <span class="diff-added-words"style="background-color: #dfd;">only</span> 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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >HTTP session data is replicated among the nodes in the cluster <span class="diff-added-words"style="background-color: #dfd;">by</span> 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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Preparing your Web application <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br>* Do not use stateful session Enterprise JavaBeans (EJBs). The clustering feature does not replicate stateful EJBs among the nodes in the cluster. <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">* 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. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">* If your Web application uses a database, every node in the cluster can access the database. Ensure that the JDBC drivers are installed on every node and that the datasource objects are defined correctly on every node. <br></td></tr>
            <tr><td class="diff-changed-lines" >* Do not depend on dynamic updates to the Java Naming and Directory Interface (JNDI). You <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">will</span> 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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. Enabling session affinity <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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, and the next request using that session might arrive before the replication is complete. In this case, route the request to the node that sent the reply to the last request and originated the replication to ensure that the request is processed using the correct session data.. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >In Geronimo servers, users can have the same experiences as in Tomcat Web container to configure session affinity. To enable session affinity, you must modify {{servel.xml}} under <span class="diff-added-words"style="background-color: #dfd;">the</span> {{&lt;GERONIMO_HOME&gt;/var/catalina}} directory and configure the *&lt;Engine&gt;* with a *jvmRoute* attribute value that is unique for each node in the cluster. The load balancer will return this value in the session cookie or the encoded URL returned to the browser. When a related request <span class="diff-changed-words">arrives<span class="diff-added-chars"style="background-color: #dfd;">,</span></span> it can use the value to route the request to the correct node. See <span class="diff-added-words"style="background-color: #dfd;">the following example:</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" ># For every node in the cluster, update {{server.xml}} as <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">followed</span> <span class="diff-added-words"style="background-color: #dfd;">follows</span> after the server is stopped: <br></td></tr>
            <tr><td class="diff-unchanged" >{code:XML|borderStyle=solid|title=Excerpt from server.xml} <br> ... <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Configuring the cluster at application level <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">To configure applicaiton level clustering, you have to input all related GBean settings in your deployment plan to 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.  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">To configure application level clustering, you have to input all related GBean settings in your deployment plan to make sure HTTP sessions are replicated successfully. Moreover, you must use the gbean definitions within deployment plans to configure the cluster configuration elements of Tomcat Web containers. 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.  <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Sample Tomcat clustering with multicast Configuration <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Here is the template for your Web application deployment plan. See [Creating deployment plans for Web applications] for more information about the parameters. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The template for your Web application deployment plan is shown as follows. See [Creating deployment plans for Web applications] for more information about the parameters. <br></td></tr>
            <tr><td class="diff-unchanged" >{code:XML|borderStyle=solid|title=geronimo-web.xml} <br>&lt;web-app xmlns=&quot;http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.2&quot; <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >* _web-cluster-server1_ should match the WAR file name. It can be different for each node in the cluster. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >On each node, deploy your Web application, <span class="diff-added-words"style="background-color: #dfd;">by using</span> either <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">via admin</span> <span class="diff-added-words"style="background-color: #dfd;">the administration</span> console or <span class="diff-added-words"style="background-color: #dfd;">the</span> *deploy* command, following this syntax: <br></td></tr>
            <tr><td class="diff-unchanged" >{panel:borderStyle=solid} <br>{{deploy --user _name_ --password _word_ deploy _archive_ _plan_}} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >* _plan_ is replaced with a file specification to your deployment plan. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Note: After <span class="diff-added-words"style="background-color: #dfd;">the</span> server installation, the default user name is <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">initially</span> *system*, and the default password is *manager*. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Sample Tomcat clustering with unicast configuration <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The following code snippet is part of a clustering example that uses unicast configuration. Static members are defined using {{org.apache.geronimo.tomcat.cluster.StaticMemberGBean}}. You have to define each static member within your deployment plan to make sure <span class="diff-added-words"style="background-color: #dfd;">that</span> your application is clustered successfully, and make sure that TCP ports for session replication are defined consistently on each node. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code:XML|borderStyle=solid|title=excerpt from geronimo-web.xml} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>Where <br></td></tr>
            <tr><td class="diff-changed-lines" >* _IPAddress1_ is the IP address or host name of <span class="diff-added-words"style="background-color: #dfd;">the</span> current static member. <br></td></tr>
            <tr><td class="diff-unchanged" >* _TCP_port1_ is the TCP port on the current node to listen for session replication data from other static members. <br>* _IPAddress2_ is the IP address or host name of the second static member. <br>* _TCP_port2_ is the TCP port on the second static member to listen for session replication data from other static members <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">To convert this example to a multicast configuration, the DisableMCastInterceptor, StaticMemberInterceptor, and StaticMember definitions need to be removed.  Also, the value for the &quot;address&quot; attribute for the TomcatReceiver definition should be changed to &quot;auto&quot;.  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">To convert this example to a multicast configuration, removed the DisableMCastInterceptor, StaticMemberInterceptor, and StaticMember definitions. Also, change the value for the &quot;address&quot; attribute for the TomcatReceiver definition to &quot;auto&quot;.  <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >h1.  Configuring the cluster at <span class="diff-changed-words">Engine<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">e</span></span> or Host level <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">You can configure the cluster just like you always did for a standalone Tomcat Web container, input all the clustering configuration into {{var/catalina/server.xml}} file according to your requirement in Geronimo. Both multicast and unicat are supported well.  Refer to the following sample codes when you want to configure a Enginee/Host level cluster, make sure these segments are enclosed within *&lt;Enginee&gt;* or *&lt;Host&gt;* element in {{server.xml}}. _$\{clusterName}_ is from {{var/config/config-substitutions.properties}}, which should be identical within all nodes in a cluster. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">You can configure the cluster just like you always did for a standalone Tomcat Web container. Input all the clustering configuration into the {{var/catalina/server.xml}} file according to your requirements in Geronimo. Both multicast and unicat are supported.  See the following sample codes when you want to configure an Engine or Host level cluster. Make sure that these segments are enclosed within the *&lt;Engine&gt;* or *&lt;Host&gt;* element in {{server.xml}}. _$\{clusterName}_ is from {{var/config/config-substitutions.properties}}, which should be identical within all nodes in a cluster. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Details about each component of the cluster and configuration options can be found in the tomcat documentation at [Tomcat6 clustering|http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html|Tomcat6 Clustering]. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Where <br>* _IPAddress_ is the IP address or host name of the second static member. <br></td></tr>
            <tr><td class="diff-changed-lines" >* _TCP_port_ is the TCP port on the second static member to listen for session replication data from other static <span class="diff-changed-words">members<span class="diff-added-chars"style="background-color: #dfd;">.</span></span> <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td class='ScrollbarPrevIcon'><a href="/confluence/display/GMOxDOC30/Plugin+based+Farming"><img border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td width='33%' class='ScrollbarPrevName'><a href="/confluence/display/GMOxDOC30/Plugin+based+Farming">Plugin based Farming</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a href="/confluence/display/GMOxDOC30/Clustering+and+farming"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a href="/confluence/display/GMOxDOC30/Clustering+and+farming">Clustering and farming</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/GMOxDOC30/WADI+Clustering">WADI Clustering</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/GMOxDOC30/WADI+Clustering"><img border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>

<p>The Tomcat Web container provides a native clustering solution that can be configured through Geronimo by using gbean definitions within <tt>config.xml</tt> or by using <tt>server.xml</tt> starting from v2.2 just like you did for a standalone Tomcat server.  This document will go through the available GBeans and how to configure them for clustering in a Geronimo server with a tomcat web container.</p>

<div>
<ul>
    <li><a href='#TomcatNativeClustering-ClusterConfigurationElements'>Cluster Configuration Elements</a></li>
    <li><a href='#TomcatNativeClustering-Settingupaclusteringenvironment'>Setting up a clustering environment</a></li>
<ul>
    <li><a href='#TomcatNativeClustering-Planningyourcluster'>Planning your cluster</a></li>
    <li><a href='#TomcatNativeClustering-PreparingyourWebapplication'>Preparing your Web application</a></li>
<ul>
    <li><a href='#TomcatNativeClustering-Enablingsessionaffinity'>Enabling session affinity</a></li>
</ul>
    <li><a href='#TomcatNativeClustering-Engagingloadbalancingandfailover'>Engaging load balancing and failover</a></li>
</ul>
    <li><a href='#TomcatNativeClustering-Configuringtheclusteratapplicationlevel'>Configuring the cluster at application level</a></li>
<ul>
    <li><a href='#TomcatNativeClustering-SampleTomcatclusteringwithmulticastConfiguration'>Sample Tomcat clustering with multicast Configuration</a></li>
    <li><a href='#TomcatNativeClustering-SampleTomcatclusteringwithunicastconfiguration'>Sample Tomcat clustering with unicast configuration</a></li>
</ul>
    <li><a href='#TomcatNativeClustering-ConfiguringtheclusteratEngineorHostlevel'>Configuring the cluster at Engine or Host level</a></li>
<ul>
    <li><a href='#TomcatNativeClustering-Samplemulticastconfigurationcode'>Sample multicast configuration code</a></li>
    <li><a href='#TomcatNativeClustering-Sampleunicastconfigurationcode'>Sample unicast configuration code</a></li>
</ul>
</ul></div>

<h1><a name="TomcatNativeClustering-ClusterConfigurationElements"></a>Cluster Configuration Elements</h1>

<p>Following are parameters or attributes that you will need to configure for a Tomcat native clustering. </p>

<ul>
	<li>Cluster
	<ul>
		<li>ClusterListenerChain</li>
		<li>TomcatValveChain</li>
		<li>Channel
		<ul>
			<li>Membership</li>
			<li>Receiver</li>
			<li>Sender</li>
			<li>ChannelInterceptor
			<ul>
				<li>StaticMember</li>
			</ul>
			</li>
		</ul>
		</li>
		<li>ClusterManager</li>
	</ul>
	</li>
</ul>


<p>Although sufficient for many applications, Tomcat clusters have some limitations:</p>
<ul>
	<li>This feature does not replicate stateful session Enterprise JavaBeans (EJBs). Do not use stateful session EJBs in your distributed applications.</li>
	<li>This feature does not replicate dynamic updates to the Java Naming and Directory Interface (JNDI). You will have to configure all the JNDI names that are used by your distributed applications in every node of the cluster.</li>
	<li>This feature does not replicate distributable Web applications to other nodes in the cluster. You will have to deploy your distributable Web applications to every node.</li>
</ul>


<p>Consider a cluster configuration to improve the scalability and availability of your Web application. The following sections provide detailed instructions about how to set up your cluster nodes.</p>


<h1><a name="TomcatNativeClustering-Settingupaclusteringenvironment"></a>Setting up a clustering environment</h1>
<p>To set up a small cluster, you 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.</p>

<h2><a name="TomcatNativeClustering-Planningyourcluster"></a>Planning your cluster</h2>

<p>The Tomcat cluster replicates HTTP session data by memory-to-memory multicast communication.</p>

<p>Every node transmits its session data to every other node in the cluster. This algorithm is efficient only 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.</p>

<p>HTTP session data is replicated among the nodes in the cluster by 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.</p>

<h2><a name="TomcatNativeClustering-PreparingyourWebapplication"></a>Preparing your Web application</h2>

<p>To participate in a cluster configuration, your Web application must be implemented correctly.</p>
<ul>
	<li>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.</li>
	<li>The deployment descriptor for your Web application, that is the <tt>web.xml</tt> file in the Web archive, must indicate that your Web application is distributable. To do this, insert the <b>distributable</b> element in the deployment descriptor.
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>Excerpt from web.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"ISO-8859-1"</span>?&gt;</span>
&lt;!DOCTYPE web-app
    PUBLIC <span class="code-quote">"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"</span>
    <span class="code-quote">"http://java.sun.com/dtd/web-app_2_3.dtd"</span>&gt;

<span class="code-tag">&lt;web-app&gt;</span>
    <span class="code-tag">&lt;display-name&gt;</span> ... <span class="code-tag">&lt;/display-name&gt;</span>
    <span class="code-tag">&lt;description&gt;</span> ... <span class="code-tag">&lt;/description&gt;</span>
    <span class="code-tag">&lt;distributable&gt;</span> <span class="code-tag">&lt;distributable/&gt;</span>
  ...
<span class="code-tag">&lt;/web-app&gt;</span>
</pre>
</div></div></li>
	<li>Do not use stateful session Enterprise JavaBeans (EJBs). The clustering feature does not replicate stateful EJBs among the nodes in the cluster.</li>
	<li>If your Web application uses a database, every node in the cluster can access the database. Ensure that the JDBC drivers are installed on every node and that the datasource objects are defined correctly on every node.</li>
	<li>Do not depend on dynamic updates to the Java Naming and Directory Interface (JNDI). You 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.</li>
</ul>


<h3><a name="TomcatNativeClustering-Enablingsessionaffinity"></a>Enabling session affinity</h3>

<p>Support for <em>session affinity</em>, also known as <em>sticky session</em> 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, and the next request using that session might arrive before the replication is complete. In this case, route the request to the node that sent the reply to the last request and originated the replication to ensure that the request is processed using the correct session data..</p>

<p>In Geronimo servers, users can have the same experiences as in Tomcat Web container to configure session affinity. To enable session affinity, you must modify <tt>servel.xml</tt> under the <tt>&lt;GERONIMO_HOME&gt;/var/catalina</tt> directory and configure the <b>&lt;Engine&gt;</b> with a <b>jvmRoute</b> attribute value that is unique for each node in the cluster. The load balancer will return this value in the session cookie or the encoded URL returned to the browser. When a related request arrives, it can use the value to route the request to the correct node. See the following example:</p>

<ol>
	<li>For every node in the cluster, update <tt>server.xml</tt> as follows after the server is stopped:
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>Excerpt from server.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
 ...
 <span class="code-tag">&lt;Engine name=<span class="code-quote">"Catalina"</span> defaultHost=<span class="code-quote">"${ServerHostname}"</span> jvmRoute=<span class="code-quote">"nodeId"</span>&gt;</span>
 ...
</pre>
</div></div>
<p>where</p>
	<ul>
		<li><em>nodeId</em> is a node identifier that is unique among all the nodes in the cluster. If you are using mod_jk, make sure that the jvmRoute attribute value matches your worker name in <tt>workers.properties</tt>.</li>
	</ul>
	</li>
	<li>Restart the server to enable the new configuration.</li>
</ol>


<h2><a name="TomcatNativeClustering-Engagingloadbalancingandfailover"></a>Engaging load balancing and failover</h2>

<p>Initially, the server configuration includes an <em>AJP connector</em> suitable for exchanging messages with a load balancing service. See <a href="/confluence/display/GMOxDOC30/Configuring+a+remote+Apache+HTTP+server" title="Configuring a remote Apache HTTP server">Configuring a remote Apache HTTP server</a> for more information about the HTTP server configuration.</p>


<h1><a name="TomcatNativeClustering-Configuringtheclusteratapplicationlevel"></a>Configuring the cluster at application level</h1>

<p>To configure application level clustering, you have to input all related GBean settings in your deployment plan to make sure HTTP sessions are replicated successfully. Moreover, you must use the gbean definitions within deployment plans to configure the cluster configuration elements of Tomcat Web containers. 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. </p>

<h2><a name="TomcatNativeClustering-SampleTomcatclusteringwithmulticastConfiguration"></a>Sample Tomcat clustering with multicast Configuration</h2>
<p>The template for your Web application deployment plan is shown as follows. See <a href="/confluence/display/GMOxDOC30/Creating+deployment+plans+for+Web+applications" title="Creating deployment plans for Web applications">Creating deployment plans for Web applications</a> for more information about the parameters.</p>
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>geronimo-web.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
&lt;web-app xmlns=<span class="code-quote">"http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.2"</span>
         <span class="code-keyword">xmlns:dep</span>=<span class="code-quote">"http://geronimo.apache.org/xml/ns/deployment-1.2"</span>&gt;

    <span class="code-tag">&lt;dep:environment&gt;</span>
      <span class="code-tag">&lt;dep:moduleId&gt;</span>
        <span class="code-tag">&lt;dep:groupId&gt;</span>org.mygroup<span class="code-tag">&lt;/dep:groupId&gt;</span>
        <span class="code-tag">&lt;dep:artifactId&gt;</span>web-cluster-server1<span class="code-tag">&lt;/dep:artifactId&gt;</span>
        <span class="code-tag">&lt;dep:version&gt;</span>2.2<span class="code-tag">&lt;/dep:version&gt;</span>
        <span class="code-tag">&lt;dep:type&gt;</span>war<span class="code-tag">&lt;/dep:type&gt;</span>
      <span class="code-tag">&lt;/dep:moduleId&gt;</span>
      <span class="code-tag">&lt;dep:dependencies&gt;</span>
      	<span class="code-tag">&lt;dep:dependency&gt;</span>
      	<span class="code-tag">&lt;dep:groupId&gt;</span>console.realm<span class="code-tag">&lt;/dep:groupId&gt;</span>
        <span class="code-tag">&lt;dep:artifactId&gt;</span>geronimo-properties-realm<span class="code-tag">&lt;/dep:artifactId&gt;</span>
        <span class="code-tag">&lt;dep:version&gt;</span>1.0<span class="code-tag">&lt;/dep:version&gt;</span>
        <span class="code-tag">&lt;dep:type&gt;</span>car<span class="code-tag">&lt;/dep:type&gt;</span>
        <span class="code-tag">&lt;/dep:dependency&gt;</span>
      <span class="code-tag">&lt;/dep:dependencies&gt;</span>
      <span class="code-tag">&lt;dep:hidden-classes/&gt;</span>
      <span class="code-tag">&lt;dep:non-overridable-classes/&gt;</span>
    <span class="code-tag">&lt;/dep:environment&gt;</span>

    <span class="code-tag">&lt;context-root&gt;</span>/servlet-examples-cluster<span class="code-tag">&lt;/context-root&gt;</span>

    <span class="code-tag">&lt;security-realm-name&gt;</span>geronimo-properties-realm<span class="code-tag">&lt;/security-realm-name&gt;</span>
    <span class="code-tag">&lt;security&gt;</span>
      <span class="code-tag">&lt;default-principal&gt;</span>
        <span class="code-tag">&lt;principal name=<span class="code-quote">"anonymous"</span> class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"</span>/&gt;</span>
      <span class="code-tag">&lt;/default-principal&gt;</span>
      <span class="code-tag">&lt;role-mappings&gt;</span>
        <span class="code-tag">&lt;role role-name=<span class="code-quote">"tomcat"</span>&gt;</span>
          <span class="code-tag">&lt;principal name=<span class="code-quote">"admin"</span> class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"</span>/&gt;</span>
        <span class="code-tag">&lt;/role&gt;</span>
      <span class="code-tag">&lt;/role-mappings&gt;</span>
    <span class="code-tag">&lt;/security&gt;</span>

    <span class="code-tag">&lt;cluster&gt;</span>TomcatCluster<span class="code-tag">&lt;/cluster&gt;</span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.CatalinaClusterGBean"</span> name=<span class="code-quote">"TomcatCluster"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.tcp.SimpleTcpCluster<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"ClusterManager"</span>&gt;</span>          
            <span class="code-tag">&lt;name&gt;</span>TomcatClusterManager<span class="code-tag">&lt;/name&gt;</span>                
        <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"TomcatValveChain"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>ReplicationValve<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"ClusterListenerChain"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>ClusterSessionListener<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"Channel"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>TomcatGroupChannel<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Manager --&gt;</span></span>
    <span class="code-tag">&lt;gbean name=<span class="code-quote">"TomcatClusterManager"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ClusterManagerGBean"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.DeltaManager<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>name=${clusterName}
           channelSendOptions=6
           expireSessionsOnShutdown=false
           notifyListenersOnReplication=true
           mapSendOptions=6<span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Channel --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelGBean"</span> name=<span class="code-quote">"TomcatGroupChannel"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.GroupChannel<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"Membership"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>TomcatMembership<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"Receiver"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>TomcatReceiver<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"Sender"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>TomcatSender<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"ChannelInterceptor"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>TomcatChannelInterceptor<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Membership --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.MembershipServiceGBean"</span> name=<span class="code-quote">"TomcatMembership"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.membership.McastService<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>
            mcastAddr=228.0.0.4
            mcastPort=45564
            mcastFrequency=500
            mcastDropTime=3000
        <span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Receiver --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ReceiverGBean"</span> name=<span class="code-quote">"TomcatReceiver"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.transport.nio.NioReceiver<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>
            tcpListenAddress=auto
            tcpListenPort=4001
            tcpSelectorTimeout=100
            tcpThreadCount=6
        <span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Sender --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.SenderGBean"</span> name=<span class="code-quote">"TomcatSender"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.transport.ReplicationTransmitter<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>
            replicationMode=pooled
            waitForAck=true
        <span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Valves--&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.ValveGBean"</span> name=<span class="code-quote">"ReplicationValve"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.tcp.ReplicationValve<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>filter=.*\.gif;.*\.js;.*\.css;.*\.png;.*\.jpeg;.*\.jpg;.*\.htm;.*\.html;.*\.txt;<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"NextValve"</span>&gt;</span>
        	<span class="code-tag">&lt;name&gt;</span>JvmRouteBinderValve<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Route Binder --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.ValveGBean"</span> name=<span class="code-quote">"JvmRouteBinderValve"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.JvmRouteBinderValve<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>enabled=true<span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Listener --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ClusterListenerGBean"</span> name=<span class="code-quote">"ClusterSessionListener"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.ClusterSessionListener<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;reference name=<span class="code-quote">"NextListener"</span>&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>JvmRouteSessionIDBinderListener<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;/reference&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Binder Listener--&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ClusterListenerGBean"</span> name=<span class="code-quote">"JvmRouteSessionIDBinderListener"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener<span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- Cluster Channel Interceptor --&gt;</span></span>
    <span class="code-tag">&lt;gbean class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span> name=<span class="code-quote">"TomcatChannelInterceptor"</span>&gt;</span>
        <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector<span class="code-tag">&lt;/attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>
<span class="code-tag">&lt;/web-app&gt;</span>
</pre>
</div></div>
<p>where </p>
<ul>
	<li><em>web-cluster-server1</em> should match the WAR file name. It can be different for each node in the cluster.</li>
</ul>


<p>On each node, deploy your Web application, by using either the administration console or the <b>deploy</b> command, following this syntax:</p>
<div class="panel" style="border-style: solid;border-width: 1px;"><div class="panelContent">
<p><tt>deploy --user <em>name</em> --password <em>word</em> deploy <em>archive</em> <em>plan</em></tt></p>
</div></div>
<p>where </p>
<ul>
	<li><em>name</em> is replaced with a user name authorized to manage the server. If you omit this option, you will be prompted to enter a user name.</li>
	<li><em>word</em> is replaced with the password used to authenticate the user. If you omit this option, you will be prompted to enter a password.</li>
	<li><em>archive</em> is replaced with a file specification to your Web application WAR file.</li>
	<li><em>plan</em> is replaced with a file specification to your deployment plan.</li>
</ul>


<p>Note: After the server installation, the default user name is <b>system</b>, and the default password is <b>manager</b>.</p>

<h2><a name="TomcatNativeClustering-SampleTomcatclusteringwithunicastconfiguration"></a>Sample Tomcat clustering with unicast configuration</h2>

<p>The following code snippet is part of a clustering example that uses unicast configuration. Static members are defined using <tt>org.apache.geronimo.tomcat.cluster.StaticMemberGBean</tt>. You have to define each static member within your deployment plan to make sure that your application is clustered successfully, and make sure that TCP ports for session replication are defined consistently on each node.</p>

<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>excerpt from geronimo-web.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
...
    <span class="code-tag">&lt;cluster&gt;</span>TomcatCluster<span class="code-tag">&lt;/cluster&gt;</span>
        <span class="code-tag">&lt;gbean name=<span class="code-quote">"TomcatCluster"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.CatalinaClusterGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.tcp.SimpleTcpCluster<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"ClusterListenerChain"</span>&gt;</span> 
                    <span class="code-tag">&lt;name&gt;</span>TomcatClusterListenerChain<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"TomcatValveChain"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>ReplicationValve<span class="code-tag">&lt;/name&gt;</span>  
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"Channel"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>TomcatChannel<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"ClusterManager"</span>&gt;</span> 
                    <span class="code-tag">&lt;name&gt;</span>TomcatClusterManager<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"TomcatClusterListenerChain"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ClusterListenerGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.ClusterSessionListener<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"ReplicationValve"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.ValveGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.tcp.ReplicationValve<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>.*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"NextValve"</span>&gt;</span>
        			<span class="code-tag">&lt;type&gt;</span>TomcatValve<span class="code-tag">&lt;/type&gt;</span>
            	                <span class="code-tag">&lt;name&gt;</span>JvmRouteBinderValve<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"JvmRouteBinderValve"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.ValveGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.JvmRouteBinderValve<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>enabled=true<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"TomcatClusterManager"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ClusterManagerGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.ha.session.DeltaManager<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>name=${clusterName}
                                         channelSendOptions=6
                                         expireSessionsOnShutdown=false
                                         notifyListenersOnReplication=true
                                         mapSendOptions=6
            <span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"TomcatChannel"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.GroupChannel<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"Membership"</span>&gt;</span> 
                    <span class="code-tag">&lt;name&gt;</span>ClusterMembership<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"Receiver"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>ClusterReceiver<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"Sender"</span>&gt;</span>                
                    <span class="code-tag">&lt;name&gt;</span>ClusterSender<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"ChannelInterceptor"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>DisableMcastInterceptor<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"ClusterMembership"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.MembershipServiceGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.membership.McastService<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>address=228.0.0.4
                                         port=45564
                                         frequency=500
                                         dropTime=3000
            <span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"ClusterReceiver"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ReceiverGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.transport.nio.NioReceiver<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>address=IPAddress1
                                         port=TCP_port1
                                         selectorTimeout=100
                                         maxThreads=6
            <span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"ClusterSender"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.SenderGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.transport.ReplicationTransmitter<span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"DisableMcastInterceptor"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.geronimo.tomcat.interceptor.DisableMcastInterceptor<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"NextInterceptor"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>TcpPingInterceptor<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"TcpPingInterceptor"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>Interval=60<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"NextInterceptor"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>TcpFailureDetector<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"TcpFailureDetector"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"NextInterceptor"</span>&gt;</span>                
                    <span class="code-tag">&lt;name&gt;</span>StaticMember1Interceptor<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"StaticMember1Interceptor"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"StaticMember"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>StaticMember2<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"NextInterceptor"</span>&gt;</span>                
                    <span class="code-tag">&lt;name&gt;</span>MessageDispatch15Interceptor<span class="code-tag">&lt;/name&gt;</span> 
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"MessageDispatch15Interceptor"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
            <span class="code-tag">&lt;reference name=<span class="code-quote">"NextInterceptor"</span>&gt;</span>
                    <span class="code-tag">&lt;name&gt;</span>ThroughputInterceptor<span class="code-tag">&lt;/name&gt;</span>                
            <span class="code-tag">&lt;/reference&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"ThroughputInterceptor"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>/&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>

        <span class="code-tag">&lt;gbean name=<span class="code-quote">"StaticMember2"</span> class=<span class="code-quote">"org.apache.geronimo.tomcat.cluster.StaticMemberGBean"</span>&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"className"</span>&gt;</span>org.apache.catalina.tribes.membership.StaticMember<span class="code-tag">&lt;/attribute&gt;</span>
            <span class="code-tag">&lt;attribute name=<span class="code-quote">"initParams"</span>&gt;</span>port=TCP_port2
                                         securePort=-1
                                         host=IPAddress2
                                         domain=test-domain
                                         UniqueId={2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}
            <span class="code-tag">&lt;/attribute&gt;</span>
        <span class="code-tag">&lt;/gbean&gt;</span>
...
</pre>
</div></div>

<p>Where</p>
<ul>
	<li><em>IPAddress1</em> is the IP address or host name of the current static member.</li>
	<li><em>TCP_port1</em> is the TCP port on the current node to listen for session replication data from other static members.</li>
	<li><em>IPAddress2</em> is the IP address or host name of the second static member.</li>
	<li><em>TCP_port2</em> is the TCP port on the second static member to listen for session replication data from other static members</li>
</ul>


<p>To convert this example to a multicast configuration, removed the DisableMCastInterceptor, StaticMemberInterceptor, and StaticMember definitions. Also, change the value for the "address" attribute for the TomcatReceiver definition to "auto". </p>

<h1><a name="TomcatNativeClustering-ConfiguringtheclusteratEngineorHostlevel"></a>Configuring the cluster at Engine or Host level</h1>
<p>You can configure the cluster just like you always did for a standalone Tomcat Web container. Input all the clustering configuration into the <tt>var/catalina/server.xml</tt> file according to your requirements in Geronimo. Both multicast and unicat are supported.  See the following sample codes when you want to configure an Engine or Host level cluster. Make sure that these segments are enclosed within the <b>&lt;Engine&gt;</b> or <b>&lt;Host&gt;</b> element in <tt>server.xml</tt>. <em>${clusterName}</em> is from <tt>var/config/config-substitutions.properties</tt>, which should be identical within all nodes in a cluster.</p>

<p>Details about each component of the cluster and configuration options can be found in the tomcat documentation at <a href="http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html" title="Tomcat6 Clustering" class="external-link" rel="nofollow">Tomcat6 clustering</a>.</p>

<h2><a name="TomcatNativeClustering-Samplemulticastconfigurationcode"></a>Sample multicast configuration code</h2>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>server.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
...
     <span class="code-tag">&lt;Cluster className=<span class="code-quote">"org.apache.catalina.ha.tcp.SimpleTcpCluster"</span> channelSendOptions=<span class="code-quote">"8"</span>&gt;</span>
                    <span class="code-tag">&lt;Manager className=<span class="code-quote">"org.apache.catalina.ha.session.DeltaManager"</span> expireSessionsOnShutdown=<span class="code-quote">"false"</span> notifyListenersOnReplication=<span class="code-quote">"true"</span> name=<span class="code-quote">"${clusterName}"</span> channelSendOptions=<span class="code-quote">"6"</span> mapSendOptions=<span class="code-quote">"6"</span>/&gt;</span>
                    <span class="code-tag">&lt;Channel className=<span class="code-quote">"org.apache.catalina.tribes.group.GroupChannel"</span>&gt;</span>
                        <span class="code-tag">&lt;Membership className=<span class="code-quote">"org.apache.catalina.tribes.membership.McastService"</span> address=<span class="code-quote">"228.0.0.4"</span> port=<span class="code-quote">"45564"</span> frequency=<span class="code-quote">"500"</span> dropTime=<span class="code-quote">"3000"</span> /&gt;</span>
                        <span class="code-tag">&lt;Receiver className=<span class="code-quote">"org.apache.catalina.tribes.transport.nio.NioReceiver"</span> address=<span class="code-quote">"auto"</span> port=<span class="code-quote">"4000"</span> autoBind=<span class="code-quote">"100"</span> selectorTimeout=<span class="code-quote">"5000"</span> maxThreads=<span class="code-quote">"6"</span> /&gt;</span>
                        <span class="code-tag">&lt;Sender className=<span class="code-quote">"org.apache.catalina.tribes.transport.ReplicationTransmitter"</span>&gt;</span>
                            <span class="code-tag">&lt;Transport className=<span class="code-quote">"org.apache.catalina.tribes.transport.nio.PooledParallelSender"</span> /&gt;</span>
                        <span class="code-tag">&lt;/Sender&gt;</span>                        
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"</span> interval=<span class="code-quote">"60"</span>/&gt;</span>                        
                        
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"</span> /&gt;</span>
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"</span> /&gt;</span>                        
                    <span class="code-tag">&lt;/Channel&gt;</span>
                    <span class="code-tag">&lt;Valve className=<span class="code-quote">"org.apache.catalina.ha.tcp.ReplicationValve"</span> filter=<span class="code-quote">".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"</span> /&gt;</span>
                    <span class="code-tag">&lt;Valve className=<span class="code-quote">"org.apache.catalina.ha.session.JvmRouteBinderValve"</span> /&gt;</span>
                    <span class="code-tag">&lt;ClusterListener className=<span class="code-quote">"org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"</span> /&gt;</span>
                    <span class="code-tag">&lt;ClusterListener className=<span class="code-quote">"org.apache.catalina.ha.session.ClusterSessionListener"</span> /&gt;</span>
      <span class="code-tag">&lt;/Cluster&gt;</span>
...
</pre>
</div></div>

<h2><a name="TomcatNativeClustering-Sampleunicastconfigurationcode"></a>Sample unicast configuration code</h2>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>server.xml</b></div><div class="codeContent panelContent">
<pre class="code-xml">
...
    <span class="code-tag">&lt;Cluster className=<span class="code-quote">"org.apache.catalina.ha.tcp.SimpleTcpCluster"</span> channelSendOptions=<span class="code-quote">"8"</span>&gt;</span>
                    <span class="code-tag">&lt;Manager className=<span class="code-quote">"org.apache.catalina.ha.session.DeltaManager"</span> expireSessionsOnShutdown=<span class="code-quote">"false"</span> notifyListenersOnReplication=<span class="code-quote">"true"</span> name=<span class="code-quote">"${clusterName}"</span> channelSendOptions=<span class="code-quote">"6"</span> mapSendOptions=<span class="code-quote">"6"</span>/&gt;</span>
                    <span class="code-tag">&lt;Channel className=<span class="code-quote">"org.apache.catalina.tribes.group.GroupChannel"</span>&gt;</span>
                        <span class="code-tag">&lt;Membership className=<span class="code-quote">"org.apache.catalina.tribes.membership.McastService"</span> address=<span class="code-quote">"228.0.0.4"</span> port=<span class="code-quote">"45564"</span> frequency=<span class="code-quote">"500"</span> dropTime=<span class="code-quote">"3000"</span> /&gt;</span>
                        <span class="code-tag">&lt;Receiver className=<span class="code-quote">"org.apache.catalina.tribes.transport.nio.NioReceiver"</span> address=<span class="code-quote">"auto"</span> port=<span class="code-quote">"4000"</span> autoBind=<span class="code-quote">"100"</span> selectorTimeout=<span class="code-quote">"5000"</span> maxThreads=<span class="code-quote">"6"</span> /&gt;</span>
                        <span class="code-tag">&lt;Sender className=<span class="code-quote">"org.apache.catalina.tribes.transport.ReplicationTransmitter"</span>&gt;</span>
                            <span class="code-tag">&lt;Transport className=<span class="code-quote">"org.apache.catalina.tribes.transport.nio.PooledParallelSender"</span> /&gt;</span>
                        <span class="code-tag">&lt;/Sender&gt;</span>
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.geronimo.tomcat.interceptor.DisableMcastInterceptor"</span> /&gt;</span>
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"</span> interval=<span class="code-quote">"60"</span>/&gt;</span>                        
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor"</span>&gt;</span>
                            <span class="code-tag">&lt;Member port=<span class="code-quote">"TCP_port"</span> securePort=<span class="code-quote">"-1"</span> host=<span class="code-quote">"IPAddress"</span> domain=<span class="code-quote">"test-domain"</span> UniqueId=<span class="code-quote">"{1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}"</span> /&gt;</span>
                        <span class="code-tag">&lt;/Interceptor&gt;</span>
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"</span> /&gt;</span>
                        <span class="code-tag">&lt;Interceptor className=<span class="code-quote">"org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"</span> /&gt;</span>                        
                    <span class="code-tag">&lt;/Channel&gt;</span>
                    <span class="code-tag">&lt;Valve className=<span class="code-quote">"org.apache.catalina.ha.tcp.ReplicationValve"</span> filter=<span class="code-quote">".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"</span> /&gt;</span>
                    <span class="code-tag">&lt;Valve className=<span class="code-quote">"org.apache.catalina.ha.session.JvmRouteBinderValve"</span> /&gt;</span>
                    <span class="code-tag">&lt;ClusterListener className=<span class="code-quote">"org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"</span> /&gt;</span>
                    <span class="code-tag">&lt;ClusterListener className=<span class="code-quote">"org.apache.catalina.ha.session.ClusterSessionListener"</span> /&gt;</span>
      <span class="code-tag">&lt;/Cluster&gt;</span>
...
</pre>
</div></div>

<p>Where</p>
<ul>
	<li><em>IPAddress</em> is the IP address or host name of the second static member.</li>
	<li><em>TCP_port</em> is the TCP port on the second static member to listen for session replication data from other static members.</li>
</ul>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Tomcat+Native+Clustering">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=20645454&revisedVersion=3&originalVersion=2">View Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Tomcat+Native+Clustering?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message