JBoss.orgCommunity Documentation
mod_cluster is supported in AS7 via the modcluster subsystem See AS7.
In other AS version mod_cluster's configuration resides within the following file:
$JBOSS_HOME/server/$PROFILE/deploy/mod_cluster.sar/META-INF/mod_cluster-jboss-beans.xml file.
The entry point for mod_cluster's server-side configuration is the ModClusterListener bean, which delegates web container (i.e. JBoss Web) specific events to a container agnostic event handler.
In general, the ModClusterListener bean defines:
A ContainerEventHandler in which to handle events from the web container.
There are two available implementations, the choice of which dictates the mode in which mod_cluster will operate: clustered or non-clustered.
A reference to the JBoss mbean server.
e.g.
<bean name="ModClusterListener" class="org.jboss.modcluster.catalina.CatalinaEventHandlerAdapter">
<constructor>
<parameter class="org.jboss.modcluster.ContainerEventHandler">
<inject bean="ModClusterService"/><!-- Non-clustered mode -->
<!--inject bean="HAModClusterService"/--><!-- Clustered mode -->
</parameter>
<parameter class="javax.management.MBeanServer">
<inject bean="JMXKernel" property="mbeanServer"/>
</parameter>
</constructor>
</bean>
In non-clustered mode, each JBoss AS node communicates with the load balancer directly, and do not communicate with each other.
Non-clustered mode is configured via the ModClusterService bean.
In general, the ModClusterService bean defines:
An object containing mod_cluster's configuration properties.
An object responsible for calculating the load balance factor for this node. This is described in detail in the chapter entitled Server-Side Load Metrics.
e.g.
<bean name="ModClusterService" class="org.jboss.modcluster.ModClusterService" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=ModCluster",exposedInterface=org.jboss.modcluster.ModClusterServiceMBean.class)</annotation>
<constructor>
<parameter class="org.jboss.modcluster.config.ModClusterConfig">
<inject bean="ModClusterConfig"/>
</parameter>
<parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider">
<inject bean="DynamicLoadBalanceFactorProvider"/>
</parameter>
</constructor>
</bean>
In clustered mode, a single JBoss node (the HA singleton master) communicates with the load balancer on behalf of the other nodes in the cluster.
Clustered mode is configured via the HAModClusterService bean.
This mode offers the following advantages over non-clustered mode:
The state of the load balancer will be kept in sync on each node in the cluster.
mod_cluster will proactively notify the load balancer of view changes (i.e. crashed members), allowing the load balancer to gracefully reconfigure itself thus avoiding costly failover processing.
Clustered-mode allows load balancing group management, adding the ability to enable, disable, or gracefully stop all nodes sharing the same load balancing group. Once a given session is associated with a specific node, subsequent requests for the same session will always prefer to be routed to a node with the same load balancing group. Grouping nodes in this way is useful for limiting the number of nodes to which a given session must replicate to support high-availability. When used in conjunction with sessions affinity, a load balancing group effectively narrows the set of preferred failover nodes to members of the same load balancing group. A load balancing group is conceptually similar to a domain in mod_jk.
In general, HAModClusterService defines:
An object containing mod_cluster's configuration properties.
An object responsible for calculating the load balance factor for this node. This is described in detail in the chapter entitled Server-Side Load Metrics.
An HAPartition, the JBoss clustering group communication building block.
The default HAPartition is defined in:
$JBOSS_HOME/server/$PROFILE/deploy/cluster/hapartition-jboss-beans.xml
A policy for determining which group member should be designated as the singleton master.
e.g.
<bean name="HAModClusterService" class="org.jboss.modcluster.ha.HAModClusterService" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=ModCluster",exposedInterface=org.jboss.modcluster.ha.HAModClusterServiceMBean.class)</annotation>
<constructor>
<parameter class="org.jboss.modcluster.config.ha.HAModClusterConfig">
<inject bean="ModClusterConfig"/>
</parameter>
<parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider">
<inject bean="DynamicLoadBalanceFactorProvider"/>
</parameter>
<parameter class="org.jboss.ha.framework.interfaces.HAPartition">
<inject bean="HAPartition"/>
</parameter>
<parameter class="org.jboss.ha.framework.interfaces.HASingletonElectionPolicy">
<bean class="org.jboss.ha.singleton.HASingletonElectionPolicySimple"/>
</parameter>
</constructor>
</bean>
The ModClusterConfig bean enumerates the configuration properties used by mod_cluster.
For the complete list of configuration properties and their default values, see the chapter entitled Server-side Configuration Properties.
e.g.
<bean name="ModClusterConfig" class="org.jboss.modcluster.config.ha.HAModClusterConfig" mode="On Demand"> <!-- Specify configuration properties here --> </bean>
Like mod_jk and mod_proxy_balancer, mod_cluster requires a connector in your server.xml to which to forward web requests. Unlike mod_jk and mod_proxy_balancer, mod_cluster is not confined to AJP, but can use HTTP as well. While AJP is generally faster, an HTTP connector can optionally be secured via SSL. If multiple possible connectors are defined in your server.xml, mod_cluster uses the following algorithm to choose between them:
If an native (APR) AJP connector is available, use it.
If an AJP connector is available, use it.
Otherwise, choose the HTTP connector with the highest max threads.
Like mod_jk and mod_proxy_balancer, mod_cluster identifies each node via a unique jvm route. By default, mod_cluster uses the following algorithm to assign the jvm route for a given node:
Use the value from server.xml, <Engine jvmRoute="..."/>, if defined.
Generate a jvm route using the configured ???. The default implementation does the following:
Use the value of the jboss.mod_cluster.jvmRoute system property, if defined.
Generate a UUID.
While UUIDs are ideal for production systems, in a development or testing environment, it is useful to know which node served a given request just by looking at the jvm route.
In this case, you can utilize the org.jboss.modcluster.SimpleJvmRouteFactory.
The factory generates jvm routes of the form:
bind-address:port:engine-name
mod_cluster's entire configuration for JBoss Web or Tomcat resides entirely within $CATALINA_HOME/conf/server.xml.
This limits the adds the following constraints to mod_cluster's feature set:
Only non-clustered mode is supported
Only one load metric can be used to calculate a load factor.
The entry point for JBoss Web and Tomcat configuration is the ModClusterListener.
All mod_cluster configuration properties are defined as attributes of the <Listener/> element.
For the complete list of configuration properties and their default values, see the chapter entitled Server-side Configuration Properties.
e.g.
<Listener className="org.jboss.modcluster.catalina.ModClusterListener" advertise="true"/>
mod_cluster uses jboss-logging, which exists in JBoss Web, but not in Tomcat. Consequently, to use mod_cluster with Tomcat, it is necessary to add jboss-logging-spi.jar to $CATALINA_HOME/lib.
In mod_cluster 1.0.x, you were required to make several manual configuration changes to the jbossweb service before mod_cluster would be usable. mod_cluster 1.1.x eliminates much of this hassle - and is designed to be fully functional out of the box.
In 1.0.x, mod_cluster needed to be deployed before JBoss Web. This ensured that mod_cluster was available to handle web application deployment lifecycle events during triggered during server startup. To achieve this, you had to add an explicit dependency on mod_cluster to jbossweb's jboss-beans.xml config file.
mod_cluster 1.1.x reverses this dependency, such that mod_cluster now depends on JBoss Web. Consequently, you no longer need to make any changes to JBoss Web's jboss-beans.xml file.
As an additional consequence of this dependency reversal, mod_cluster can now be hot-deployed or undeployed to a running server without consequence to the JBoss Web service.
mod_cluster 1.0.x required you to add a lifecycle <Listener/> element to server.xml.
The ModClusterListener bean now registers itself with the JBoss Web server upon deploying the mod_cluster service; and deregisters itself upon undeploy. Consequently, you no longer need to manually add a <Listener/> to server.xml.
In mod_cluster 1.0.x, you needed to add a unique jvmRoute to the <Engine/> element within server.xml. In 1.1.x, this is now optional. The auto-assignment of a jvm route is described in the previous section.
In mod_cluster 1.0.x, you had the option of manually setting the connector bind address, to restrict the network interface on which mod_cluster would listen for proxied requests from the load balancer. In mod_cluster 1.1.x, this no longer necessary. mod_cluster will set the bind address automatically, based on the interface on which mod_cluster's internal connection was established.
The JBoss microcontainer configuration for mod_cluster 1.0.x is *not* compatible with the configuration for 1.1.x. If you had customized your mod_cluster 1.0.x configuration, please start with the default configuration contained in the 1.1.x mod_cluster.sar and reapply any changes.