JBoss.orgCommunity Documentation

Chapter 3. native configuration

3.1. Apache httpd configuration
3.2. mod_proxy configuration
3.3. mod_slotmem configuration
3.4. mod_proxy_cluster
3.5. mod_manager
3.6. mod_advertise
3.7. Minimal Example

You need to load the modules that are needed for mod_cluster for example:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule slotmem_module modules/mod_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so

mod_proxy and mod_proxy_ajp are standard httpd modules. mod_slotmem is a shared slotmem memory provider. mod_manager is the module that reads information from JBoss AS/JBossWeb/Tomcat and updates the shared memory information. mod_proxy_cluster is the module that contains the balancer for mod_proxy. mod_advertise is an additional module that allows httpd to advertise via multicast packets the IP and port where the mod_cluster is listening. This multi-module architecture allows the modules to easily be changed depending on what the customer wants to do. For example when using http instead of AJP, only

LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

needs to be changed to:

LoadModule proxy_http_module modules/mod_proxy_http.so

mod_proxy directives like ProxyIOBufferSize could be used to configure mod_cluster. There is no need to use ProxyPass directives because mod_cluster automatically configures which URLs have to be forwarded to JBossWEB.

The actual version doesn't require any configuration directives.

CreateBalancers: Define how the balancer are created in the httpd VirtualHosts, this is to allow directives like:

ProxyPass / balancer://mycluster1/

0: Create in all VirtualHosts defined in httpd.

1: Don't create balancers (requires at least one ProxyPass/ProxyPassMatch to define the balancer names).

2: Create only the main server.

Default: 2

Note: When using 1 don't forget to configure the balancer in the ProxyPass directive, because the default is empty stickysession and nofailover=Off and the values received via the MCMP CONFIG message are ignored.


UseAlias: Check that the Alias corresponds to the ServerName (See Host Name Aliases)

0: Don't (ignore Aliases)

1: Check it

Default: 0 Ignore the Alias information from the nodes.


Time interval in seconds for loadbalancing logic to recalculate the status of a node: (Default: 5 seconds)

The actual formula to recalculate the status of a node is:

status = lbstatus + (elected - oldelected) * 1000)/lbfactor;

lbfactor is received for the node via STATUS messages.lbstatus is recalculated every LBstatusRecalTime seconds using the formula:

lbstatus = (elected - oldelected) * 1000)/lbfactor;

elected is the number of time the worker was elected.oldelected is elected last time the lbstatus was recalculated.The node with the lowest status is selected. Nodes with lbfactor ≤ 0 are skipped by the both calculation logic.


ProxyPassMatch/ProxyPass: ProxyPassMatch and ProxyPass are mod_proxy directives that when using ! (instead the back-end url) prevent to reverse-proxy in the path. This could be used allow httpd to serve static information like images.

ProxyPassMatch ^(/.*\.gif)$ !  

The above for example will allow httpd to server directly the .gif files.


The Context of a mod_manger directive is VirtualHost except mentioned otherwise. server config means that it must be outside a VirtualHost configuration. If not an error message will be displayed and httpd won't start.

MemManagerFile: That is the base name for the names mod_manager will use to store configuration, generate keys for shared memory or lock files. That must be an absolute path name; the directories will created if needed. It is highly recommended that those files are placed on a local drive and not an NFS share. (Context: server config) Default: $server_root/logs/

Maxcontext: That is the number max of contexts supported by mod_cluster. (Context: server config) Default: 100

Maxnode: That is the number max nodes supported by mod_cluster. (Context: server config) Default: 20

Maxhost: That is the number max host (Aliases) supported by mod_cluster. That is also the max number of balancers. (Context: server config) Default: 10

Maxsessionid: That is the number of active sessionid we store to give number of active sessions in the mod_cluster-manager handler. A session is unactive when mod_cluster doesn't receive any information from the session in 5 minutes. (Context: server config) Default: 0 (the logic is not activated).

ManagerBalancerName: That is the name of balancer to use when the JBoss AS/JBossWeb/Tomcat doesn't provide a balancer name. That is not supported in the current version. (Default value is used). Default: mycluster

PersistSlots: Tell mod_slotmem to persist the nodes, Alias and Context in files. (Context: server config) Default: Off

CheckNonce: Switch check of nonce when using mod_cluster-manager handler on | off (Default: on Nonce checked) Since 1.1.0.CR1

SetHandler mod_cluster-manager: That is the handler to display the node mod_cluster sees from the cluster. It displays the information about the nodes like INFO and additionaly counts the number of active sessions.

<Location /mod_cluster-manager>
SetHandler mod_cluster-manager
Order deny,allow
Deny from all
Allow from

When accessing the location you define in httpd.conf you get something like:


Note that:

Transferred: Corresponds to the POST data send to the back-end server.

Connected: Corresponds to the number of requests been processed when the mod_cluster status page was requested.

sessions: Corresponds to the number of sessions mod_cluster report as active (on which there was a request during the past 5 minutes). That field is not present when Maxsessionid is zero.

mod_advertise uses multicast packets to advertise the VirtualHost where it is configured that must be the same VirtualHost where mod_manager is defined. Of course at least one mod_advertise must be in the VirtualHost to allow mod_cluster to find the right IP and port to give to the ClusterListener.

ServerAdvertise On: Use the advertise mechanism to tell the JBoss AS/JBossWeb/Tomcat to whom it should send the cluster information.

ServerAdvertise On http://hostname:port: Tell the hostname and port to use. Only needed if the VirtualHost is not defined correctly, if the VirtualHost is a Name-based Virtual Host or when VirtualHost is not used.

ServerAdvertise Off: Don't use the advertise mechanism.

Default: Off. (Any Advertise directive in a VirtualHost sets it to On in the VirtualHost)

AdvertiseGroup IP:port: That is the multicast address to use (something like for example). IP should correspond to AdvertiseGroupAddress and port to AdvertisePort in the JBoss AS/JBossWeb/Tomcat configuration. Note that if JBoss AS is used and the -u startup switch is included in the AS startup command, the default AdvertiseGroupAddress is the value passed via the -u. Default: If port is missing the default port will be used: 23364.

AdvertiseFrequency seconds[.miliseconds]: Time between the multicast messages advertising the IP and port. Default: 10 Ten seconds.

AdvertiseSecurityKey value: key string to identify the mod_cluster in JBossWEB. Default: No default value. Information not sent.

AdvertiseManagerUrl value: Not used in this version (It is sent in the X-Manager-Url: value header). That is the URL that JBoss AS/JBossWeb/Tomcat should use to send information to mod_cluster. Default: No default value. Information not sent.

AdvertiseBindAddress IP:port: That is the address and port httpd is bind to send the multicast messages. This allow to specify an address on multi IP address boxes. Default:

LoadModule proxy_module modules/mod_proxy.so
 LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
 LoadModule slotmem_module modules/mod_slotmem.so
 LoadModule manager_module modules/mod_manager.so
 LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
 LoadModule advertise_module modules/mod_advertise.so
   <Location />
      Order deny,allow
      Deny from all
      Allow from 10.33.144.
 KeepAliveTimeout 60
 MaxKeepAliveRequests 0
 ManagerBalancerName mycluster
 ServerAdvertise on