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.
A reference to the JBoss mbean server.
e.g.
<bean name="ModClusterListener" class="org.jboss.modcluster.container.jbossweb.JBossWebEventHandlerAdapter">
<constructor>
<parameter class="org.jboss.modcluster.container.ContainerEventHandler">
<inject bean="ModClusterService"/>
</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>
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.ModClusterConfig" 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.container.catalina.standalone.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.2.x the web containers now are separed cleanly, that requires you to change standalone and mbean configuration a little.
The JBoss microcontainer configuration for mod_cluster 1.1.x is not compatible with the configuration for 1.2.x. you need to change the ModClusterListener mbean class to: "org.jboss.modcluster.container.jbossweb.JBossWebEventHandlerAdapter".
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.