Chapter 3. httpd configuration

3.1. Apache httpd configuration

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

3.2. mod_proxy configuration

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.

3.3. mod_slotmem configuration

The actual version doesn't require any configuration directives.

3.4. mod_proxy_cluster

3.4.1. CreateBalancers

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.

3.4.2. UseAlias

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

Off: Don't check (ignore Aliases)

On: Check aliases

Default: Off Ignore the Alias information from the nodes.

Versions older than 1.3.1.Final only accept values 0 and 1 respectively.

3.4.3. LBstatusRecalTime

LBstatusRecalTime: 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.

3.4.4. WaitForRemove

WaitForRemove: Time in seconds before a removed node is forgotten by httpd

Default: 10 seconds

3.4.5. ProxyPassMatch/ProxyPass

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.

3.4.6. EnableOptions

Use OPTIONS method to periodically check the active connection. Fulfils the same role as the CPING/CPONG used by AJP but for HTTP/HTTPS connections. The endpoint needs to implement at least HTTP/1.1.

On (or no value): Use OPTIONS (default)

Off: Don't use OPTIONS

3.5. mod_manager

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.

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

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.

3.6. mod_advertise

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.

3.6.1. ServerAdvertise

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)

3.6.2. AdvertiseGroup

AdvertiseGroup IP:port: That is the multicast address to use (something like 232.0.0.2:8888 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. If port is missing the default port will be used: 23364.

Default: 224.0.1.105:23364.

3.6.3. AdvertiseFrequency

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

Default: 10 Ten seconds.

3.6.4. AdvertiseSecurityKey

AdvertiseSecurityKey value: key string used to verify advertisements checksums. If configured on either side the verification is required. Both sides must use the same security key.

Default: No default value.

3.6.5. AdvertiseManagerUrl

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.

3.6.6. AdvertiseBindAddress

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: 0.0.0.0:23364

3.7. Minimal 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
 
 Listen 10.33.144.3:6666
 <VirtualHost 10.33.144.3:6666>
 
   <Location />
      Order deny,allow
      Deny from all
      Allow from 10.33.144.
   </Location>
 
 KeepAliveTimeout 60
 MaxKeepAliveRequests 0
 
 ManagerBalancerName mycluster
 ServerAdvertise On
 EnableMCPMReceive
 
 </VirtualHost>