# Server-side Configuration

## JBoss AS

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:

1. A `ContainerEventHandler` in which to handle events from the web container.

2. 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>

### Non-clustered mode

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:

1. An object containing mod_cluster's configuration properties.

2. An object responsible for calculating the load balance factor for this node. This is described in detail in the chapter entitled java.load.title.

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>

### Configuration Properties

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 java.properties.title.

e.g.

    <bean name="ModClusterConfig" class="org.jboss.modcluster.config.ModClusterConfig" mode="On Demand">
      <!-- Specify configuration properties here -->
    </bean>

### Connectors

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:

1. If an native (APR) AJP connector is available, use it.

2. If an AJP connector is available, use it.

3. Otherwise, choose the HTTP connector with the highest max threads.

### Node Identity

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:

1. Use the value from `server.xml`, `<Engine jvmRoute="..."/>`, if defined.

2. Generate a jvm route using the configured java.properties.jvmRouteFactory. The default implementation does the following:

   1. Use the value of the `jboss.mod_cluster.jvmRoute` system property, if defined.

   2. 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

## JBoss Web & Tomcat

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.

### Lifecycle Listener

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 java.properties.title.

e.g.

    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>

### Additional Tomcat dependencies

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.

## Migrating from 1.1.x

In mod_cluster 1.2.x the web containers now are separed cleanly, that requires you to change standalone and mbean configuration a little.

### mod_cluster-jboss-beans.xml

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".

### server.xml

You need to change the <Listener/> element className to: "org.jboss.modcluster.container.catalina.standalone.ModClusterListener".

## Migrating from 1.0.x

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.

### Dependency with JBoss Web

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.

### server.xml

#### Lifecycle listener

mod_cluster 1.0.x required you to add a lifecycle <Listener/> element to server.xml.

##### JBoss AS

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.

##### JBoss Web & Tomcat

You still need to use a lifecycle <Listener/> element in server.xml, but it's location has changed. In 1.1.x, the ModClusterListener class was refactored into the catalina container SPI implementation package, and the old location was deprecated.

#### JVM Route

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.

#### Connector bind address

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.

### mod_cluster-jboss-beans.xml

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.

#### Configuration changes

The following configuration properties were renamed between 1.0.x and 1.1.x:

Deprecated property name | Replacement property name
domain | loadBalancingGroup
masterPerDomain | masterPerLoadBalancingGroup
sslKeyStorePass | sslKeyStorePassword