JBoss.orgCommunity Documentation

mod_cluster Documentation


1. Overview
1.1. Platforms
1.2. Advantages
1.3. Requirements
1.4. Limitations
1.5. Downloads
1.6. Configuration
1.7. Migration
1.8. SSL support
1.9. Load Balancing Demo Application
2. Quick Start Guide
2.1. Download mod_cluster components
2.2. Install the httpd binary
2.2.1. Install the whole httpd
2.2.2. Install only the modules
2.2.3. Install in home directory
2.2.4. Install in Windows
2.3. Configure httpd
2.4. Install the server-side binaries
2.4.1. Installing in JBoss AS 6.x
2.4.2. Installing in JBoss AS 5.x
2.4.3. Installing in Tomcat
2.4.4. Installing in JBoss AS 4.2.x or 4.3.x
2.5. Configuring the server-side
2.5.1. Configuring mod_cluster with JBoss AS 5.x+
2.5.2. Configuring mod_cluster with standalone JBoss Web or Tomcat
2.5.3. Integrate mod_cluster with JBoss AS 4.2.x and 4.3.x
2.6. Start httpd
2.7. Start the back-end server
2.7.1. Starting JBoss AS
2.7.2. Starting JBossWeb or Tomcat
2.8. Set up more back-end servers
2.9. Experiment with the Load Balancing Demo Application
3. httpd configuration
3.1. Apache httpd configuration
3.2. mod_proxy configuration
3.3. mod_slotmem configuration
3.4. mod_proxy_cluster
3.4.1. CreateBalancers
3.4.2. UseAlias
3.4.3. LBstatusRecalTime
3.4.4. WaitForRemove
3.4.5. ProxyPassMatch/ProxyPass
3.4.6. EnableOptions
3.5. mod_manager
3.5.1. EnableMCPMReceive
3.5.2. MemManagerFile
3.5.3. Maxcontext
3.5.4. Maxnode
3.5.5. Maxhost
3.5.6. Maxsessionid
3.5.7. MaxMCMPMaxMessSize
3.5.8. ManagerBalancerName
3.5.9. PersistSlots
3.5.10. CheckNonce
3.5.11. AllowDisplay
3.5.12. AllowCmd
3.5.13. ReduceDisplay
3.5.14. SetHandler mod_cluster-manager
3.6. mod_advertise
3.6.1. ServerAdvertise
3.6.2. AdvertiseGroup
3.6.3. AdvertiseFrequency
3.6.4. AdvertiseSecurityKey
3.6.5. AdvertiseManagerUrl
3.6.6. AdvertiseBindAddress
3.7. Minimal Example
4. Building httpd modules
4.1. Build a patched httpd from it sources
4.2. Build the 4 modules of mod_cluster
4.3. Build the mod_proxy module
5. Installing httpd modules
5.1. Configuration
5.2. Installing and using the bundles
6. Server-side Configuration
6.1. JBoss AS
6.1.1. Non-clustered mode
6.1.2. Configuration Properties
6.1.3. Connectors
6.1.4. Node Identity
6.2. JBoss Web & Tomcat
6.2.1. Lifecycle Listener
6.2.2. Additional Tomcat dependencies
6.3. Migrating from 1.1.x
6.3.1. mod_cluster-jboss-beans.xml
6.3.2. server.xml
6.4. Migrating from 1.0.x
6.4.1. Dependency with JBoss Web
6.4.2. server.xml
6.4.3. mod_cluster-jboss-beans.xml
7. AS7 modcluster subsystem Configuration
7.1. ModCluster Subsystem in JBoss AS7
7.2. ModCluster Subsystem minimal configuration
7.3. ModCluster Subsystem configuration
7.3.1. mod-cluster-config Attributes
7.3.2. simple-load-provider Attributes
7.3.3. dynamic-load-provider Attributes
7.3.4. load-metric Configuration
7.3.5. custom-load-metric Configuration
7.3.6. load-metric Configuration with the jboss admin console
8. Building Server-Side Components
8.1. Requirements
8.2. Building
8.3. Build Artifacts
9. Server-side Configuration Properties
9.1. Proxy Discovery Configuration
9.2. Proxy Configuration
9.3. SSL Configuration
9.4. Load Configuration for JBoss Web and Tomcat
10. Server-Side Load Metrics
10.1. Web Container metrics
10.1.1. ActiveSessionsLoadMetric
10.1.2. BusyConnectorsLoadMetric
10.1.3. ReceiveTrafficLoadMetric
10.1.4. SendTrafficLoadMetric
10.1.5. RequestCountLoadMetric
10.2. System/JVM metrics
10.2.1. AverageSystemLoadMetric
10.2.2. HeapMemoryUsageLoadMetric
10.3. Other metrics
10.3.1. ConnectionPoolUsageLoadMetric
11. Installing Server-Side Components
11.1. Installing in JBoss AS 6.0.0.M1 and up
11.2. Installing in JBoss AS 5.x
11.3. Installing in Tomcat
12. Using SSL in mod_cluster
12.1. Using SSL between JBossWEB and httpd
12.1.1. Apache httpd configuration part
12.1.2. ClusterListener configuration part
12.1.3. mod-cluster-jboss-beans configuration part
12.1.4. How the diferent files were created
12.2. Using SSL between httpd and JBossWEB
12.2.1. How the diferent files were created
12.3. Forwarding SSL browser informations when using http/https between httpd and JBossWEB
13. Migration from mod_jk
14. Migration from mod_proxy
14.1. Workers
14.2. Balancers
15. Load Balancing Demo Application
15.1. Overview
15.2. Basic Usage
15.3. Client Driver Configuration Options
15.4. Load Generation Scenarios
16. Change Log
16.1. 1.3.1.Final (6 May 2015)
16.2. 1.3.0.Final (06 February 2014)
16.3. 1.2.6.Final (07 September 2013)
16.4. 1.2.5.Final (30 August 2013)
16.5. 1.2.4.Final (24 April 2013)
16.6. 1.2.3.Final (18 October 2012)
16.7. 1.2.2.Final (06 September 2012)
16.8. 1.2.1.Final (03 May 2012)
16.9. 1.2.0.Final (06 February 2012)
16.10. 1.2.0.Beta4 (26 January 2012)
16.11. 1.2.0.Beta3 (03 January 2012)
16.12. 1.2.0.Beta2 (11 December 2011)
16.13. 1.2.0.Beta1 (06 December 2011)
16.14. 1.1.3.Final (12 August 2011)
16.15. 1.1.2.Final (21 April 2011)
16.16. 1.1.1.Final (31 January 2011)
16.17. 1.1.0.Final (13 August 2010)
16.18. 1.1.0.CR3 (15 June 2010)
16.19. 1.1.0.CR2 (11 May 2010)
16.20. 1.1.0.CR1 (22 March 2010)
16.21. 1.1.0.Beta1 (30 October 2009)
17. Frequently Asked questions
17.1. What is Advertise
17.2. What to do if I don't want to use Advertise (multicast):
17.3. I am using Tomcat 7 / 6 what should I do:
17.4. It is not working what should I do:
17.4.1. No error
17.4.2. Error in server.log or catalina.out
17.4.3. Error in error_log
17.5. I have "HTTP/1.1 501 Method Not Implemented"
17.6. Redirect is not working:
17.7. I have more than one Connector mod_cluster does use the right one
17.8. Chrome can't diplay /mod_cluster_manager page
17.9. Using mod_cluster and SELinux.
17.10. System properties to modify behaviour

mod_cluster is an httpd-based load balancer. Like mod_jk and mod_proxy, mod_cluster uses a communication channel to forward requests from httpd to one of a set of application server nodes. Unlike mod_jk and mod_proxy, mod_cluster leverages an additional connection between the application server nodes and httpd. The application server nodes use this connection to transmit server-side load balance factors and lifecycle events back to httpd via a custom set of HTTP methods, affectionately called the Mod-Cluster Management Protocol (MCMP). This additional feedback channel allows mod_cluster to offer a level of intelligence and granularity not found in other load balancing solutions.

Within httpd, mod_cluster is implemented as a set of modules for httpd with mod_proxy enabled. Much of the logic comes from mod_proxy, e.g. mod_proxy_ajp provides all the AJP logic needed by mod_cluster.

JBoss already prepares binary packages with httpd and mod_cluster so you can quickly try mod_cluster on the following platforms:

  • Linux x86, x64, ia64

  • Solaris x86, SPARC

  • Windows x86, x64, ia64

  • HP-UX PA-RISC, ia64

mod_cluster boasts the following advantages over other httpd-based load balancers:

Dynamic configuration of httpd workers

Traditional httpd-based load balancers require explicit configuration of the workers available to a proxy. In mod_cluster, the bulk of the proxy's configuration resides on the application servers. The set of proxies to which an application server will communicate is determined either by a static list or using dynamic discovery via the advertise mechanism. The application server relays lifecycle events (e.g. server startup/shutdown) to the proxies allowing them to effectively auto-configure themselves. Notably, the graceful shutdown of a server will not result in a failover response by a proxy, as is the case with traditional httpd-based load balancers.

Server-side load balance factor calculation

In contrast with traditional httpd-based load balancers, mod_cluster uses load balance factors calculated and provided by the application servers, rather than computing these in the proxy. Consequently, mod_cluster offers a more robust and accurate set of load metrics than is available from the proxy. See the chapter entitled Server-Side Load Metrics for details.

Fine grained web-app lifecycle control

Traditional httpd-based load balancers do not handle web application undeployments particularly well. From the proxy's perspective requests to an undeployed web application are indistinguishable from a request for an non-existent resource, and will result in 404 errors. In mod_cluster, each server forwards any web application context lifecycle events (e.g. web-app deploy/undeploy) to the proxy informing it to start/stop routing requests for a given context to that server.

AJP is optional

Unlike mod_jk, mod_cluster does not require AJP. httpd connections to application server nodes can use HTTP, HTTPS, or AJP.

The original concepts are described in a wiki.

Download the latest mod_cluster release here.

The release is comprised of the following artifacts:

  • httpd binaries for common platforms

  • JBoss AS/JBossWeb/Tomcat binary distribution

Alternatively, you can build from source using the Git repository:

https://github.com/modcluster/mod_cluster/tagsrelease/

The mod_cluster binary distribution for JBoss AS/JBossWeb/Tomcat includes a demo application that helps demonstrate how different server-side scenarios affect the routing of client requests by the load balancer. The demo application is located in the mod_cluster distribution's demo directory.

Strong cryptography warning

mod_cluster contains mod_ssl, therefore the following warning (copied from OpenSSL) applies:

PLEASE REMEMBER THAT EXPORT/IMPORT AND/OR USE OF STRONG CRYPTOGRAPHY SOFTWARE, PROVIDING CRYPTOGRAPHY HOOKS OR EVEN JUST COMMUNICATING TECHNICAL DETAILS ABOUT CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME PARTS OF THE WORLD. SO, WHEN YOU IMPORT THIS PACKAGE TO YOUR COUNTRY, RE-DISTRIBUTE IT FROM THERE OR EVEN JUST EMAIL TECHNICAL SUGGESTIONS OR EVEN SOURCE PATCHES TO THE AUTHOR OR OTHER PEOPLE YOU ARE STRONGLY ADVISED TO PAY CLOSE ATTENTION TO ANY EXPORT/IMPORT AND/OR USE LAWS WHICH APPLY TO YOU. THE AUTHORS OF OPENSSL ARE NOT LIABLE FOR ANY VIOLATIONS YOU MAKE HERE. SO BE CAREFUL, IT IS YOUR RESPONSIBILITY.

The following are the steps to set up a minimal working installation of mod_cluster on a single httpd server and a single back end server, either JBoss AS, JBossWeb or Tomcat. The steps can be repeated to add as many httpd servers or back end servers to your cluster as is desired.

The steps shown here are not intended to demonstrate how to set up a production install of mod_cluster; for example using SSL to secure access to the httpd-side mod_manager component is not covered. See the httpd-side and java-side configuration documentation for the full set of configuration options.

Download the latest httpd and java release bundles. If there is no pre-built httpd bundle appropriate for your OS or system architecture, you can build the binary from source.

Since 1.1.0.CR2 httpd.conf is preconfigured with the Quick Start values. You should adapt the default values to your configuration with older mod_cluster we will have to add the following to httpd.conf. If you extracted the download bundle to root as shown above and are using that extract as your httpd install, httpd.conf is located in /opt/jboss/httpd/httpd/conf.

LoadModule proxy_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy.so
LoadModule proxy_ajp_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_ajp.so
LoadModule slotmem_module /opt/jboss/httpd/lib/httpd/modules/mod_slotmem.so
LoadModule manager_module /opt/jboss/httpd/lib/httpd/modules/mod_manager.so
LoadModule proxy_cluster_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_cluster.so
LoadModule advertise_module /opt/jboss/httpd/lib/httpd/modules/mod_advertise.so
 
Listen 10.33.144.3:6666
<VirtualHost 10.33.144.3:6666>
 
  <Directory />
    Order deny,allow
    Deny from all
    Allow from 10.33.144.
  </Directory>
 
  KeepAliveTimeout 60
  MaxKeepAliveRequests 0
 
  ManagerBalancerName mycluster
  AdvertiseFrequency 5
 
</VirtualHost>

If you are using your own install of httpd, httpd.conf is found in your install's conf directory. The content to add to httpd.conf is slightly different from the above (different path to the various .so files):

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>
 
  <Directory />
    Order deny,allow
    Deny from all
    Allow from 10.33.144.
  </Directory>
 
  KeepAliveTimeout 60
  MaxKeepAliveRequests 0
 
  ManagerBalancerName mycluster
  AdvertiseFrequency 5
 
</VirtualHost>

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.

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.

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.

To build httpd-2.2.x from its sources see ASF httpd doc

If needed, patch the httpd-2.2.x sources with (The patch prevents long waiting time when the node IP can't be resolved that should not happen so you can skip the patch part if you don't want to rebuild httpd). mod_proxy_ajp.patch

(cd modules/proxy
  patch -p0 < $location/mod_proxy_ajp.patch
 )

Configure httpd with something like:

./configure  --prefix=apache_installation_directory \
             --with-mpm=worker \
             --enable-mods-shared=most \
             --enable-maintainer-mode \
             --with-expat=builtin \
             --enable-ssl \
             --enable-proxy \
             --enable-proxy-http \
             --enable-proxy-ajp \
             --disable-proxy-balancer

Rebuild (make) and reinstall (make install) after that.

Several bundles are available at http://www.jboss.org/mod_cluster/downloads.html.

In case you can't find a prepared package of mod_cluser in the download area, it is possible to build mod_cluster for the sources. You need a distribution of httpd (at least 2.2.8) or (better) a source tarball of httpd and the sources of mod_cluster. Building explains how to build mod_cluster for it sources.

A minimal configuration is needed in httpd (See httpd.conf). A listener must be a added in in JBossWEB conf/server.xml (See Configuring JBoss AS/Web).

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>

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

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

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.

The attributs correspond to the properties

Proxy Discovery Configuration

AttributePropertyDefault
proxy-listproxyListNone
proxy-urlproxyURLNone
advertiseadvertisetrue
advertise-security-keyadvertiseSecurityKeyNone
excluded-contextsexcludedContextsNone
auto-enable-contextsautoEnableContextstrue
stop-context-timeoutstopContextTimeout10 seconds (in seconds)
socket-timeoutnodeTimeout20 seconds (in milli seconds)

Proxy Configuration

AttributePropertyDefault
sticky-sessionstickySessiontrue
sticky-session-removestickySessionRemovefalse
sticky-session-forcestickySessionForcetrue
node-timeoutworkerTimeout-1
max-attemptsmaxAttempts1
flush-packetsflushPacketsfalse
flush-waitflushWait-1
pingping10
smaxsmax-1 it uses default value
ttlttl-1 it uses default value
domainloadBalancingGroupNone
load-balancing-grouploadBalancingGroupNone

SSL Configuration

SSL configuration part needs to be added here too

The load-metric are the "classes" collecting information to allow computation of the load factor sent to httpd

AttributePropertyDefault
typeA Server-Side Load MetricsMandatory
weightweight9
capacitycapacity512
typeCorresponding Server-Side Load Metric
cpuAverageSystemLoadMetric
memSystemMemoryUsageLoadMetric
heapHeapMemoryUsageLoadMetric
sessionsActiveSessionsLoadMetric
requestsRequestCountLoadMetric
send-trafficSendTrafficLoadMetric
receive-trafficReceiveTrafficLoadMetric
busynessBusyConnectorsLoadMetric
connection-poolConnectionPoolUsageLoadMetric

The tables below enumerate the configuration properties available to an application server node. The location for these properties depends on how mod_cluster is configured.

The list of proxies from which an application expects to receive AJP connections is either defined statically, via the addresses defined in the proxyList configuration property; or discovered dynamically via the advertise mechanism. Using a special mod_advertise module, proxies can advertise their existence by periodically broadcasting a multicast message containing its address/port. This functionality is enabled via the advertise configuration property. If configured to listen, a server can learn of the proxy's existence, then notify that proxy of its own existence, and update its configuration accordingly. This frees both the proxy and the server from having to define static, environment-specific configuration values.

AttributeAS7 AttributeDefaultScopeDescription
proxyListproxy-listNoneConfiguration

Defines a comma delimited list of httpd proxies with which this node will initially communicate. Value should be of the form:

address1:port1,address2:port2

Using the default configuration, this property can by manipulated via the jboss.mod_cluster.proxyList system property.

excludedContextsexcluded-contextsROOT, admin-console, invoker, bossws, jmx-console, juddi, web-consoleConfiguration

List of contexts to exclude from httpd registration, of the form:

host1:context1,host2:context2,host3:context3

If no host is indicated, it is assumed to be the default host of the server (e.g. localhost). "ROOT" indicates the root context. Using the default configuration, this property can by manipulated via the jboss.mod_cluster.excludedContexts system property.

autoEnableContextsauto-enable-contextstrueConfiguration

If false the contexts are registered disabled in httpd, they need to be enabled via the enable() mbean method or via mod_cluster_manager.

stopContextTimeoutstop-context-timeout10Configuration

The amount of time, measure in units specified by stopContextTimeoutUnit, for which to wait for clean shutdown of a context (completion of pending requests for a distributable context; or destruction/expiration of active sessions for a non-distributable context).

stopContextTimeoutUnitNoneTimeUnit.SECONDSConfiguration

The unit of time for use with stopContextTimeout

sessionDrainingStrategyNoneorg.jboss.modcluster.SessionDrainingStrategyEnum.DEFAULTConfiguration

Indicates the session draining strategy used during undeployment of a web application. There are three possible values:

DEFAULT

Drain sessions before web application undeploy only if the web application is non-distributable.

ALWAYS

Always drain sessions before web application undeploy, even for distributable web applications.

NEVER

Do not drain sessions before web application undeploy, even for non-distributable web application.

proxyURLproxy-urlNoneApache HTTPD

If defined, this value will be prepended to the URL of MCMP commands.

socketTimeoutsocket-timeout20000Configuration

Number of milliseconds to wait for a response from an httpd proxy to MCMP commands before timing out, and flagging the proxy as in error.

advertisetrue, if proxyList is undefined, false otherwiseConfiguration

If enabled, httpd proxies will be auto-discovered via multicast announcements. This can be used either in concert or in place of a static proxyList.

advertiseGroupAddressadvertise-socket224.0.1.105Apache HTTPD

UDP address on which to listen for httpd proxy multicast advertisements

In AS7 that corresponding to the name of a socket-binding

advertisePortSee advertise-socket23364Apache HTTPD

UDP port on which to listen for httpd proxy multicast advertisements

advertiseSecurityKeyadvertise-security-keyNoneApache HTTPD

If specified, httpd proxy advertisements checksums (using this value as a salt) will be required to be verified on the server side

advertiseThreadFactoryNoneExecutors.defaultThreadFactory()Configuration

The thread factory used to create the background advertisement listener.

jvmRouteFactoryNonenew SystemPropertyJvmRouteFactory(new UUIDJvmRouteFactory(), "jboss.mod_cluster.jvmRoute")Configuration Defines the strategy for determining the jvm route of a node, if none was specified in server.xml. The default factory first consults the jboss.mod_cluster.jvmRoute system property. If this system property is undefined, the jvm route is assigned a UUID.

The following configuration values are sent to proxies during server startup, when a proxy is detected via the advertise mechanism, or during the resetting of a proxy's configuration during error recovery.

AttributeAS7 AttributeDefaultScopeDescription
stickySessionsticky-sessiontrueBalancer

Indicates whether subsequent requests for a given session should be routed to the same node, if possible.

stickySessionRemovesticky-session-removefalseBalancer

Indicates whether the httpd proxy should remove session stickiness in the event that the balancer is unable to route a request to the node to which it is stuck. This property is ignored if stickySession is false.

stickySessionForcesticky-session-forcefalseBalancer

Indicates whether the httpd proxy should return an error in the event that the balancer is unable to route a request to the node to which it is stuck. This property is ignored if stickySession is false.

workerTimeoutworker-timeout-1Balancer

Number of seconds to wait for a worker to become available to handle a request. When no workers of a balancer are usable, mod_cluster will retry after a while (workerTimeout/100). That is timeout in the balancer mod_proxy documentation. A value of -1 indicates that the httpd will not wait for a worker to be available and will return an error if none is available.

maxAttemptsmax-attempts1Balancer

Number of times an httpd proxy will attempt to send a given request to a worker before giving up. The minimum value is 1, meaning try only once. (Note that mod_proxy default is also 1: no retry).

flushPacketsflush-packetsfalseNode

Enables/disables packet flushing

flushWaitflush-wait-1Node

Time to wait before flushing packets in milliseconds. A value of -1 means wait forever.

pingping10Node

Time (in seconds) in which to wait for a pong answer to a ping

smaxsmaxDetermined by httpd configurationNode

Soft maximum idle connection count (that is the smax in worker mod_proxy documentation). The maximum value depends on the httpd thread configuration (ThreadsPerChild or 1).

ttlttl60Node

Time to live (in seconds) for idle connections above smax

nodeTimeoutnode-timeout-1Node

Timeout (in seconds) for proxy connections to a node. That is the time mod_cluster will wait for the back-end response before returning error. That corresponds to timeout in the worker mod_proxy documentation. A value of -1 indicates no timeout. Note that mod_cluster always uses a cping/cpong before forwarding a request and the connectiontimeout value used by mod_cluster is the ping value.

balancerbalancermyclusterNode

The balancer name

loadBalancingGroupdomain load-balancing-groupNoneNode

If specified, load will be balanced among jvmRoutes withing the same load balancing group. A loadBalancingGroup is conceptually equivalent to a mod_jk domain directive. This is primarily used in conjunction with partitioned session replication (e.g. buddy replication).

The communication channel between application servers and httpd proxies uses HTTP by default. This channel can be secured using HTTPS by setting the ssl property to true.

Note

This HTTP/HTTPS channel should not be confused with the processing of HTTP/HTTPS client requests.

AttributeAS7 AttributeDefaultDescription
sslNonefalse

Should connection to proxy use a secure socket layer

sslCipherscipher-suiteThe default JSSE cipher suites

Overrides the cipher suites used to initialize an SSL socket ignoring any unsupported ciphers

sslProtocolprotocolTLS (ALL in AS7)

Overrides the default SSL socket protocol.

sslCertificateEncodingAlgorithmNoneThe default JSSE key manager algorithm

The algorithm of the key manager factory

sslKeyStorecertificate-key-fileSystem.getProperty("user.home") + "/.keystore"

The location of the key store containing client certificates

sslKeyStorePasswordpasswordchangeit

The password granting access to the key store (and trust store in AS7)

sslKeyStoreTypeNoneJKS

The type of key store

sslKeyStoreProviderNoneThe default JSSE security provider

The key store provider

sslTrustAlgorithmNoneThe default JSSE trust manager algorithm

The algorithm of the trust manager factory

sslKeyAliaskey-alias 

The alias of the key holding the client certificates in the key store

sslCrlFileca-revocation-url 

Certificate revocation list

sslTrustMaxCertLengthNone5

The maximum length of a certificate held in the trust store

sslTrustStoreNoneSystem.getProperty("javax.net.ssl.trustStorePassword")

The location of the file containing the trust store

sslTrustStorePasswordNoneSystem.getProperty("javax.net.ssl.trustStore")

The password granting access to the trust store.

sslTrustStoreTypeNoneSystem.getProperty("javax.net.ssl.trustStoreType")

The trust store type

sslTrustStoreProviderNoneSystem.getProperty("javax.net.ssl.trustStoreProvider")

The trust store provider

Additional configuration properties used when mod_cluster is configured in JBoss Web standalone or Tomcat.

AttributeDefaultDescription
loadMetricClassorg.jboss.modcluster.load.metric.impl.BusyConnectorsLoadMetric

Class name of an object implementing org.jboss.load.metric.LoadMetric

loadMetricCapacity1

The capacity of the load metric defined via the loadMetricClass property

loadHistory9

The number of historic load values to consider in the load balance factor computation.

loadDecayFactor2

The factor by which a historic load values should degrade in significance.

A major feature of mod_cluster is the ability to use server-side load metrics to determine how best to balance requests.

The DynamicLoadBalanceFactorProvider bean computes the load balance factor of a node from a defined set of load metrics.

<bean name="DynamicLoadBalanceFactorProvider" class="org.jboss.modcluster.load.impl.DynamicLoadBalanceFactorProvider" mode="On Demand">
  <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=LoadBalanceFactorProvider",exposedInterface=org.jboss.modcluster.load.impl.DynamicLoadBalanceFactorProviderMBean.class)</annotation>
  <constructor>
    <parameter>
      <set elementClass="org.jboss.modcluster.load.metric.LoadMetric">
        <inject bean="BusyConnectorsLoadMetric"/>
        <inject bean="HeapMemoryUsageLoadMetric"/>
      </set>
    </parameter>
  </constructor>
  <property name="history">9</property>
  <property name="decayFactor">2</property>
</bean>

Load metrics can be configured with an associated weight and capacity.

The weight (default is 1) indicates the significance of a metric with respect to the other metrics. For example, a metric of weight 2 will have twice the impact on the overall load factor than a metric of weight 1.

The capacity of a metric serves 2 functions:

  • To normalize the load values from each metric. In some load metrics, capacity is already reflected in the load values. The capacity of a metric should be configured such that 0 <= (load / capacity) >= 1.

  • To favor some nodes over others. By setting the metric capacities to different values on each node, proxies will effectively favor nodes with higher capacities, since they will return smaller load values. This adds an interesting level of granularity to node weighting. Consider a cluster of two nodes, one with more memory, and a second with a faster CPU; and two metrics, one memory-based and the other CPU-based. In the memory-based metric, the first node would be given a higher load capacity than the second node. In a CPU-based metric, the second node would be given a higher load capacity than the first node.

Each load metric contributes a value to the overall load factor of a node. The load factors from each metric are aggregated according to their weights.

In general, the load factor contribution of given metric is: (load / capacity) * weight / total weight.

The DynamicLoadBalanceFactorProvider applies a time decay function to the loads returned by each metric. The aggregate load, with respect to previous load values, can be expressed by the following formula:

L = (L0 + L1/D + L2/D2 + L3/D3 + ... + LH/DH) * (1 + D + D2 + D3 + ... DH)

... or more concisely as:

L = (∑Hi=0 Li/Di) * (∑Hi=0 Di)

... where D = decayFactor, and H = history.

Setting history = 0 effectively disables the time decay function and only the current load for each metric will be considered in the load balance factor computation.

The mod_cluster load balancer expects the load factor to be an integer between 0 and 100, where 0 indicates max load and 100 indicates zero load. Therefore, the final load factor sent to the load balancer

LFinal = 100 - (L * 100)

While you are free to write your own load metrics, the following LoadMetrics are available out of the box:

First, extract the server-side binary to a temporary directory. The following assumes it was extracted to /tmp/mod_cluster

Your next step depends on whether your target server is JBoss AS or JBossWeb/Tomcat.

There are 2 connections between the cluster and the front-end. Both could be encrypted. That chapter describes how to encrypt both connections.

As the ClusterListener allows to configure httpd it is adviced to use SSL for that connection. The most easy is to use a virtual host that will only be used to receive information from JBossWEB. Both side need configuration.

mod_ssl of httpd is using to do that. See in one example how easy the configuration is:

 Listen 6666
 <VirtualHost 10.33.144.3:6666>
     SSLEngine on
     SSLCipherSuite AES128-SHA:ALL:!ADH:!LOW:!MD5:!SSLV2:!NULL
     SSLCertificateFile conf/server.crt
     SSLCertificateKeyFile conf/server.key
     SSLCACertificateFile conf/server-ca.crt
     SSLVerifyClient require
     SSLVerifyDepth  10 
 </VirtualHost>

The conf/server.crt file is the PEM-encoded Certificate file for the VirtualHost it must be signed by a Certificate Authority (CA) whose certificate is stored in the sslTrustStore of the ClusterListener parameter.

The conf/server.key file is the file containing the private key.

The conf/server-ca.crt file is the file containing the certicate of the CA that have signed the client certificate JBossWEB is using. That is the CA that have signed the certificate corresponding to the sslKeyAlias stored in the sslKeyStore of the ClusterListener parameters.

There is a wiki describing the SSL parameters of the ClusterListener. See in one example how easy the configuration is:

 <Listener className="org.jboss.web.cluster.ClusterListener"
           ssl="true"
           sslKeyStorePass="changeit"
           sslKeyStore="/home/jfclere/CERTS/CA/test.p12"
           sslKeyStoreType="PKCS12"
           sslTrustStore="/home/jfclere/CERTS/CA/ca.p12"
           sslTrustStoreType="PKCS12" sslTrustStorePassword="changeit"
           />

The sslKeyStore file contains the private key and the signed certificate of the client certificate JBossWEB uses to connect to httpd. The certificate must be signed by a Cerficate Authority (CA) who certificate is in the conf/server-ca.crt file of the httpd

The sslTrustStore file contains the CA certificate of the CA that signed the certificate contained in conf/server.crt file.

The files were created using OpenSSL utilities see OpenSSL CA.pl (/etc/pki/tls/misc/CA for example) has been used to create the test Certificate authority, the certicate requests and private keys as well as signing the certicate requests.

Using https allows to encrypt communications betwen httpd and JBossWEB. But due to the ressources it needs that no advised to use it in high load configuration.

(See Encrypting connection between httpd and TC for detailed instructions).

httpd is configured to be a client for AS/TC so it should provide a certificate AS/TC will accept and have a private key to encrypt the data, it also needs a CA certificate to valid the certificate AS/TC will use for the connection.

SSLProxyEngine On
SSLProxyVerify require
SSLProxyCACertificateFile conf/cacert.pem
SSLProxyMachineCertificateFile conf/proxy.pem

conf/proxy.pem should contain both key and certificate. The certificate must be trusted by Tomcat via the CA in truststoreFile of <connector/>.

conf/cacert.pem must contain the certificat of the CA that signed the AS/TC certificate. The correspond key and certificate are the pair specificed by keyAlias and truststoreFile of the <connector/>. Of course the <connector/> must be the https one (normally on port 8443).

The files were created using OpenSSL utilities see OpenSSL CA.pl (/etc/pki/tls/misc/CA for example) has been used to create the test Certificate authority, the certicate requests and private keys as well as signing the certicate requests.

(See above)

The certificate and key need to be imported into the java keystore using keytool

make sure you don't use a passphare for the key (don't forget to clean the file when done)

  1. Convert the key and certificate to p12 file:
    openssl pkcs12 -export -inkey key.pem -in newcert.pem -out test.p12
    make sure you use the keystore password as Export passphrase.
  2. Import the contents of the p12 file in the keystore:
    keytool -importkeystore -srckeystore test.p12 -srcstoretype PKCS12
  3. Import the CA certificate in the java trustore: (Fedora13 example).
    keytool -import -trustcacerts -alias "caname" \
    -file  ../../CA/cacert.pem -keystore /etc/pki/java/cacerts
  4. Edit server.xml to have a <connector/> similar to:
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               keyAlias="1" 
               truststoreFile="/etc/pki/java/cacerts"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="true" sslProtocol="TLS" />
    
  5. Start TC/AS and use openssl s_client to test the connection:
    openssl s_client -CAfile /home/jfclere/CA/cacert.pem -cert newcert.pem -key newkey.pem \
    -host localhost -port 8443
    There shouldn't be any error and you should be able to see your CA in the "Acceptable client certificate CA names".

Mod_cluster only support Apache httpd, there are no plan to support IIS or Iplanet.

The migration from mod_jk to mod_cluster is not very complex. Only very few worker properties can't be mapped to mod_cluster parameters.

Here is the table of worker properties and how to transfer them in the ClusterListener parameters.

mod_jk worker property

ClusterListener parameter

Remarks

host

-

It is read from the <Connector/> Address information

port

-

It is read from the <Connector/> Port information

type

-

It is read from the <Connector/> Protocol information

route

-

It is read from the <Engine/> JVMRoute information

domain

domain

That is not supported in this version

redirect

-

The nodes with loadfactor = 0 are standby nodes they will be used no other nodes are available

socket_timeout

nodeTimeout

Default 10 seconds

socket_keepalive

-

KEEP_ALIVE os is always on in mod_cluster

connection_pool_size

-

The max size is calculated to be AP_MPMQ_MAX_THREADS+1 (max)

connection_pool_minsize

smax

The defaut is max

connection_pool_timeout

ttl

Time to live when over smax connections. The defaut is 60 seconds

-

workerTimeout

Max time to wait for a free worker default 1 second

retries

maxAttempts

Max retries before returning an error Default: 3

recovery_options

-

mod_cluster behave like mod_jk with value 7

fail_on_status

-

Not supported

max_packet_size

iobuffersize/receivebuffersize

Not supported in this version. Use ProxyIOBufferSize

max_reply_timeouts

-

Not supported

recovert_time

-

The ClusterListener will tell (via a STATUS message) mod_cluster that the node is up again

activation

-

mod_cluster receives this information via ENABLE/DISABLE/STOP messages

distance

-

mod_cluster handles this via the loadfactor logic

mount

-

The context "mounted" automaticly via the ENABLE-APP messages. ProxyPass could be used too

secret

-

Not supported

connect_timeout

-

Not supported. Use ProxyTimeout or server TimeOut (Default 300 seconds)

prepost_timeout

ping

Default 10 seconds

reply_timeout

-

Not supported. Use ProxyTimeout or server TimeOut? directive (Default 300 seconds)

As mod_cluster is a sophisticated balancer migration from mod_proxy to mod_cluster is strait forward. mod_cluster replaces a reverse proxy with loadbalancing. A reversed proxy is configured like:

ProxyRequests Off
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPass /foo http://foo.example.com/bar
ProxyPassReverse /foo http://foo.example.com/bar

All the general proxy parameters could be used in mod_cluster they work like in mod_proxy, only the balancers and the workers definitions are slightly different.

Mod_proxy Parameter

ClusterListener parameter

Remarks

min

-

Not supported in this version

max

-

mod_cluster uses mod_proxy default value

smax

smax

Same as mod_proxy

ttl

ttl

Same as mod_proxy

acquire

workerTimeout

Same as mod_proxy acquire but in seconds

disablereuse

-

mod_cluster will disable the node in case of error and the ClusterListener will for the reuse via the STATUS message

flushPackets

flushPackets

Same as mod_proxy

flushwait

flushwait

Same as mod_proxy

keepalive

-

Always on: OS KEEP_ALIVE is always used. Use connectionTimeout in the <Connector> if needed

lbset

-

Not supported

ping

ping

Same as mod_proxy Default value 10 seconds

lbfactor

-

The load factor is received by mod_cluster from a calculated value in the ClusterListener

redirect

-

Not supported lbfactor sent to 0 makes a standby node

retry

-

ClusterListener will test when the node is back online

route

JVMRoute

In fact JBossWEB via the JVMRoute in the Engine will add it

status

-

mod_cluster has a finer status handling: by context via the ENABLE/STOP/DISABLE/REMOVE application messages. hot-standby is done by lbfactor = 0 and Error by lbfactor = 1 both values are sent in STATUS message by the ClusterListener

timeout

nodeTimeout

Default wait for ever (http://httpd.apache.org/docs/2.2/mod/mod_proxy.html is wrong there)

ttl

ttl

Default 60 seconds

Mod_proxy Parameter

ClusterListener parameter

Remarks

lbmethod

-

There is only one load balancing method in mod_cluster "cluster_byrequests"

maxattempts

maxAttempts

Default 1

nofailover

stickySessionForce

Same as in mod_proxy

stickysession

StickySessionCookie/StickySessionPath

The 2 parameters in the ClusterListener are combined in one that behaves like in mod_proxy

timeout

workerTimeout

Default 1 seconds

The mod_cluster distribution includes a demo application that helps demonstrate how different server-side scenarios affect the routing of client requests by the load balancer. The demo application is located in the mod_cluster distribution's demo directory.

The demo application consists of two components:

Note that the demo application does not actually depend on mod_cluster in any way. Its only dependency is on JBossWeb/Tomcat. [1] Consequently, the demo can be used to demonstrate the effect of different server-side scenarios on the routing decisions made by any load balancer, including mod_jk, mod_proxy or the various hardware load balancers.

Note also that this demo application is not intended to be used as a load testing tool; i.e. something that can demonstrate the maximum load a cluster configuration can handle. Using it as such has a good chance of showing you the maximum load the client can generate rather than the maximum load your cluster can handle.

To run the demo application:

  1. Unpack the mod_cluster distribution on your filesystem. Here we assume it has been unzipped to ~/mod_cluster or C:\mod_cluster.

  2. Install mod_cluster into your httpd server as described at Installation of the httpd part

  3. Install mod_cluster into your JBossAS/JBossWeb/Tomcat servers as described at Installation on the Java side

  4. In AS7 you have to set org.apache.tomcat.util.ENABLE_MODELER to true, Something like:

        <system-properties>
           <property name="org.apache.tomcat.util.ENABLE_MODELER" value="true"/>
        </system-properties>
              

  5. Start httpd and your JBossAS/JBossWeb/Tomcat servers

  6. Deploy the load-demo.war found in the distribution's demo/server folder to your JBossAS/JBossWeb/Tomcat servers.

  7. Start the demo application:

    1. On *nix:

      cd ~/mod_cluster/demo/client
      ./run-demo.sh

    2. On Windows:

      C:\>cd mod_cluster\demo\client
      C:\mod_cluster\demo\client>run-demo
  8. Configure the hostname and address of the httpd server, the number of client threads, etc and click the "Start" button. See Client Driver Configuration Options for details on the configuration options.

  9. Switch to the "Request Balancing" tab to see how many requests are going to each of your JBossAS/JBossWeb/Tomcat servers.

  10. Switch to the "Session Balancing" tab to see how many active sessions [2] are being hosted by each of your JBossAS/JBossWeb/Tomcat servers.

  11. Stop some of your JBossAS/JBossWeb/Tomcat servers and/or undeploy the load-demo.war from some of the servers and see the effect this has on load balancing.

  12. Restart some of your JBossAS/JBossWeb/Tomcat servers and/or re-deploy the load-demo.war to some of the servers and see the effect this has on load balancing.

  13. Experiment with adding artificial load to one or more servers to see what effect that has on load balancing. See Load Generation Scenarios for details.

Most of the various panels in application interface also present information on the current status on any client threads. "Total Clients" is the number of client threads created since the last time the "Start" button was pushed. "Live Clients" is the number of threads currently running. "Failed Clients" is the number of clients that terminated abnormally; i.e. made a request that resulted in something other than an HTTP 200 response.

The configuration of the client is driver is done via the application's "Clent Control" tab.

The panel includes the following options:

  1. Proxy Hostname: Hostname of the load balancer or the IP address on which it is listening for requests [3]

  2. Proxy Port: Port on which the load balancer is listening for requests [4]

  3. Context Path: Portion of the request URL that specifies the request is for the load-demo.war

  4. Session Life: Number of seconds a client thread should use a session before invalidating or abandoning it. Generally it is good to keep this to a small value; otherwise the use of session stickiness will prevent changes in server load from affecting the load balancer's routing decisions. With sticky sessions enabled (strongly recommended), it is the creation of a new session that allows the load balancer to try to balance load.

  5. Invalidate: Controls what the client thread should do when it stops using a session because Session Life has passed. If checked, the driver will send a request that results in the session being invalidated. If unchecked, the session will just be abandoned, and will continue to exist on the server until Session Timeout seconds have passed. In the future this will likely be changed to a percentage input, so X% can be invalidated, the rest abandoned.

  6. Session Timeout: Number of seconds a session can remain unused before the server is free to expire it. Unchecking Invalidate and setting a high value relative to Session Life allows a significant number of unused sessions to accumulate on the server.

  7. Num Threads: Number of client threads to launch. Each thread repeatedly makes requests until the "Stop" button is pushed or a request receives a response other than HTTP 200.

  8. Sleep Time: Number of ms the client threads should sleep between requests.

  9. Startup Time: Number of seconds over which the application should stagger the start of the client threads. Staggering the start advised as it avoids the unnatural situation where for the life of the demonstation all sessions start at about the same time and then are invalidated or abandoned at the same time. Staggering the start allows the load balancer to continually see new sessions and decide how to route them.

You can use the application's GUI to instruct individual servers to artificially generate various types of load, and then track how that load affects request and session balancing. Load generation is controlled via the application's "Server Load Control" tab.

The panel includes the following options:



[1] The demo's "Datasource Use" load generation scenario requires the use of JBoss Application Server.

[2] For purposes of this chart, a session is considered "active" if a client thread will ever again send a request associated with the session. When client threads stop using a session, they can either send a request to invalidate it or just abandon it by no longer including its session cookie in requests. After a session is abandoned, it will not be reflected in the "Session Balancing" chart, but it will continue to exist on the JBossWeb/Tomcat/JBoss AS server until it is removed due to timeout.

[3] The default value for this field is controlled by the mod_cluster.proxy.host system property, or localhost if not set. Editing the run-demo.sh or run-demo.bat file to change the -Dmod_cluster.proxy.host=localhost passed to java will allow you to avoid re-typing this value every time you launch the demo application.

[4] The default value for this field is controlled by the mod_cluster.proxy.port system property, or 8000 if not set. Editing the run-demo.sh or run-demo.bat file to change the -Dmod_cluster.proxy.port=8000 passed to java will allow you to avoid re-typing this value every time you launch the demo application.

MODCLUSTER-344 Pings for HTTP/HTTPS connections are now sent by default, can be disabled by "EnableOptions Off"

MODCLUSTER-288 Drop SystemMemoryUsageLoadMetric altogether

MODCLUSTER-360 mod_proxy_cluster.h doesn't contain the right information

MODCLUSTER-334 mod_cluster core when use ProxyPass / balancer://bal and CreateBalancers 1

MODCLUSTER-335 Regression in ProxyPass integration

MODCLUSTER-339 "proxy: DNS lookup failure" with IPv6 on Solaris

MODCLUSTER-345 http_handle_cping_cpong with EnableOptions and HTTPS connector

MODCLUSTER-347 mod_cluster-manager may break up aliases from a single VirtualHost, causing a messy page

MODCLUSTER-332 Add Engine.getExecutor() to container SPI

HTTP httpd-2.4.x doesn't like the extra CRLF.

MODCLUSTER-349 mod_manager truncates ENABLE-APP messages.

Fix ap_proxy_make_fake_req in 2.4.x

MODCLUSTER-315 Convert project to use i18n logging and exceptions

MODCLUSTER-328 mod_cluster doesn't recognize ? as a proper context delimiter causing 503s on requests with query strings

JBPAPP-9493 mod_cluster returns "Bad Gateway" HTTP ErrorCode 502 with https

MODCLUSTER-326 rename NMAKEmakefile to NMAKEmakefile.example

JBPAPP-9788 Tomcat with mod_cluster refuses to shut down

JBPAPP-10168 Option sessionDrainingStrategy in mod_cluster listener in tomcat causes an exception

JBPAPP-10147 The shutdown port of tomcat is released before performing actual shut down

JBPAPP-9493 mod_cluster returns "Bad Gateway" HTTP ErrorCode 502 with https

JBPAPP-9791 mod_rewrite + mod_cluster: one kind of "proxying" RewriteRules don't work on Windows

MODCLUSTER-224 when using tomcat manager webapp to stop/start an application the start is ignored by mod_cluster

MODCLUSTER-322 Using AverageSystemLoadMetric can improperly cause a Load Factor of 0

MODCLUSTER-312 port JBPAPP-8956 to 1.2.x

MODCLUSTER-311 mod_manager doesn't handle multiple virtualhosts per node

MODCLUSTER-309 mod_proxy_cluster not checking all available balancers (but only the first one) for an available route

JBPAPP-8957 Segmentation Faut when you run two or more JBoss Server Cluster behind *ONE* Apache Server on RHEL 6

MODCLUSTER-304 Port to httpd 2.4

MODCLUSTER-305 ProxyPass can break StickySession

MODCLUSTER-297 Warnings when compiling mod_cluster

MODCLUSTER-192 Add SSL stuff in the FAQ

MODCLUSTER-298 mod_cluster doesn't work with IPv6.

MODCLUSTER-289 MemManagerFile creates directory but put files in ..

MODCLUSTER-290 mod_cluster's mod_advertise can not start on IPv6-only box

MODCLUSTER-279 mod_cluster returns 503s after STATUS

MODCLUSTER-281 Make stickySessionForce default to false in native part from 1.2.0 release

Fix CVE-2011-4608: Add EnableMCPMReceive in configuration. (JBPAPP-7708)

mod_proxy code for old httpd versions needs to be updated. (MODCLUSTER-227)

Missing Documentation For mod_cluster with JBoss AS5. (MODCLUSTER-248)

sticky-session-force change requires httpd restart. (MODCLUSTER-273)

mod_cluster management console/Status does not show exact mod_cluster version. (MODCLUSTER-256)

read-attribute and :write-attribute Error in AS7. (MODCLUSTER-246)

routing table lookup creates performance issues.. (MODCLUSTER-252)

Error 503 using mod_cluster: CVE-2011-3348. (MODCLUSTER-258)

warning while compiling on some lab boxes. (MODCLUSTER-266)

String index out of range: -1 with a lot of nodes/deploymentswarning while compiling on some lab boxes. (MODCLUSTER-266)

404 while/just after removing a node. (MODCLUSTER-272)

ProxyPass doesn't work with mod_cluster whne mixing mod_cluster and other scheme handlers404 while/just after removing a node. (MODCLUSTER-274)

mod_cluster forgets removed node too fast. (MODCLUSTER-231)

Allow context lengths greater than 40 (MODCLUSTER-236)

Increase the MAXMESSSIZE and allow it to be configurable via a parameter. (MODCLUSTER-244)

Calculate the MAXMESSSIZE dynamically. (MODCLUSTER-245)

Load-demo application does not work with AS7. (MODCLUSTER-259)

Modify jbossweb metrics to use service provider spi, instead of jmx. (MODCLUSTER-151)

mod_cluster throws warnings at shutdown in AS7. (MODCLUSTER-143)

Refactor mod_cluster to allow implementations for other application servers. (MODCLUSTER-105)

AS7 integration. (MODCLUSTER-219)

Refactor project into modules for HA, catalina, core, etc. (MODCLUSTER-112)

request hang with a node is stopped in EC2 (MODCLUSTER-217) (jfclere)

Extra ENABLE-APP/REMOVE-APP event after failover (MODCLUSTER-220) (jfclere)

mod_cluster does not work with Tomcat 7 due to API Change in Connector (MODCLUSTER-240) (jfclere)

kill -HUP httpd process increase the number of open locks (MODCLUSTER-241) (jfclere)

mod_cluster failover does not work for a /webappcontext when the / root context exists (MODCLUSTER-188) (jfclere)

UseAlias broken (MODCLUSTER-212) (jfclere)

mod_rewrite PT doesn't work (MODCLUSTER-213) (jfclere)

memory usage growning in httpd (MODCLUSTER-214) (jfclere)

Second attempt to connect from Jboss to apache module sends incomplete Host Header (MODCLUSTER-216) (jfclere)

when using tomcat manager webapp to stop/start an application the start is ignored by mod_cluster (MODCLUSTER-224) (jfclere)

Unable to override load properties when running in Tomcat 6 (MODCLUSTER-232) (jfclere)

Documentation contains wrong default loadMetric class name (MODCLUSTER-233) (jfclere)

mod_cluster should issue a warning when Maxcontext is reached and no more context will be taken (MODCLUSTER-223) (jfclere)

add a note explaining where Maxcontext must be put in httpd.conf and issue error if in wrong location (MODCLUSTER-225) (jfclere)

NPE when overriding default load metric in ModClusterListener (MODCLUSTER-183) (pferraro)

mod_cluster failover does not work for a /webappcontext when the / root context exists (MODCLUSTER-188) (jfclere)

mod_cluster issues an ENABLE-APP too early in the webapp lifecycle (MODCLUSTER-190) (jfclere)

mod_cluster 1.1.0 docs step 11.1.4.3 is wrong (MODCLUSTER-193) (jfclere)

Incorrect routing of requests when one context root is the prefix of another (MODCLUSTER-196) (jfclere)

Can only rewrite from the root context in httpd if there is a root context deployed in JBoss (MODCLUSTER-198) (jfclere)

the STATUS MCMP message is send before the connector is started (MODCLUSTER-202) (jfclere)

The windoze bundle don't have the default configuration (MODCLUSTER-205) (jfclere)

httpd cores after graceful restart after the mod_cluster configuration is added (MODCLUSTER-206) (jfclere)

Make logging on Tomcat use JDK14LoggerPlugin by default (MODCLUSTER-185) (pferraro)

update mod_cluster to use HTTP/1.1 (MODCLUSTER-201) (jfclere)

Add support for system properties used in 1.0.x (MODCLUSTER-207) (pferraro)

Demo servlets throw InstanceNotFoundException against EAP5 (MODCLUSTER-170) (pferraro)

mod_advertise: Invalid ServerAdvertise Address too often (MODCLUSTER-172) (jfclere)

Fix class name of MBeanAttributeRatioLoadMetric in MC config (MODCLUSTER-174) (pferraro)

Wrong configuration could cause an httpd core (MODCLUSTER-175) (jfclere)

Advertise not configured error message in log is actually a warning (MODCLUSTER-176) (jfclere)

Better no servers connected message (MODCLUSTER-165) (jfclere)

How does the UI deal with 20 or more servers (MODCLUSTER-165) (jfclere)

mod_cluster should use hostname provided in address instead a IP address (MODCLUSTER-168) (pferraro)

Read only view of mod_cluster-manager (MODCLUSTER-181) (jfclere)

Demo client throws Bus Error when run with JDK 1.6 on OSX (MODCLUSTER-169) (jfclere)

Use versioned docs (MODCLUSTER-141) (jfclere, pferraro)

Deprecate use of term "domain" (MODCLUSTER-177) (jfclere, pferraro)

Rpc failure can lead to failure to deploy a webapp (MODCLUSTER-140) (pferraro)

Quotes in jsessionId causing sticky sessions to fail (MODCLUSTER-146) (jfclere)

ManagerBalancerName doesn't work (MODCLUSTER-153) (jfclere)

Parsing of IPv6 loopback address fails (MODCLUSTER-156) (pferraro)

SystemMemoryUsageLoadMetric returns wrong load metric (MODCLUSTER-157) (pferraro)

Clean shutdown logic can still inadvertently kill requests for non-distributed contexts. (MODCLUSTER-159) (pferraro)

NoClassDefFoundError running demo app against AS6 (MODCLUSTER-161) (pferraro)

Allow override of default clean shutdown behavior (MODCLUSTER-139) (pferraro)

Avoid unnecessary open sockets for non-master nodes (MODCLUSTER-158) (pferraro)

Add the lifecycle listener dynamically (MODCLUSTER-20) (pferraro)

Use UUID for auto-generated jvmRoute (MODCLUSTER-142) (pferraro)

improve packaging so that the bundle can run in ~ too (MODCLUSTER-150) (jfclere)

jboss.mod_cluster.proxyList: invalid hosts cause mod-cluster startup to be delayed (MODCLUSTER-155) (pferraro)

mod_cluster 1.1.0.CR1 doesn't work with Tomcat (MODCLUSTER-143) (jfclere/pferraro)

Allow configuration of stopContextTimeout units (MODCLUSTER-138) (pferraro)

Add a solaris10 64 bits sparc in the bundles (MODCLUSTER-137) (jfclere)

INFO and mod_cluster_manager/ displays milliseconds and DUMP second (MODCLUSTER-128) (jfclere)

Make mod_cluster manager tolerant to F5 page refresh when disabled context (MODCLUSTER-124) (jfclere)

Update httpd to 2.2.25. (MODCLUSTER-134) (jfclere)

Apache with mod_cluster refuses to start at first, but after 7 retries it starts up (MODCLUSTER-120) (jfclere)

Add getLoad() to load metric mbean interface (MODCLUSTER-130) (pferraro)

Disable "cnone" request parameter to ease remote invocation on mod_cluster-manager (MODCLUSTER-127) (jfclere)

Microcontainer does not always choose the right constructor when creating ModClusterService (MODCLUSTER-116) (pferraro)

Microcontainer does not choose the right constructor when creating RequestCountLoadMetric (MODCLUSTER-126) (pferraro)

Mod_cluster does support more that 3 Alias in <Host/> (MODCLUSTER-121) (jfclere)

Allow toggling of context auto-enable during mod_cluster startup. (MODCLUSTER-125) (pferraro)

STATUS should retry the worker even if there was an error before. (MODCLUSTER-133) (jfclere)

Split ModClusterServiceMBean.ping(String) into 3 methods (MODCLUSTER-110) (pferraro/jfclere)

Use clean shutdown by default, leveraging STOP-APP-RSP for <distributable/> contexts and session draining for non-distributable contexts.  mod_cluster shutdown now triggered earlier via Connector JMX notification.  (MODCLUSTER-131) (pferraro/jfclere)

move the web site to magnolia (MODCLUSTER-114) (.org team)

ping and nodeTimeout interact. (MODCLUSTER-132) (jfclere)

update mod_jk to 1.2.30  (MODCLUSTER-138) (jfclere)

query string is truncated to (MODCLUSTER-118) (jfclere)

AdvertiseBindAddress does not default to the 23364 port (MODCLUSTER-119) (jfclere)

Skip load balance factor calculation if there are no proxies to receive status message (MODCLUSTER-103) (pferraro)

Disabling contexts does not work (MODCLUSTER-123) (jfclere)

advertise doesn't use new AdvertiseSecurityKey on graceful restarts. (MODCLUSTER-129) (jfclere)

Load-demo.war specifies obsolete servlet in web.xml  (MODCLUSTER-113) (pferraro)

Interaction with mod_rewrite looks weird for end-users. (MODCLUSTER-86) (jfclere)

admin-console should be in the excludedContexts. (MODCLUSTER-87) (pferraro)

ClassCastException upon redeploy after mod-cluster-jboss-beans.xml modification. (MODCLUSTER-88) (pferraro)

Alias from webapps/jboss-web.xml are not handled correctly in mod_cluster. (MODCLUSTER-89) (jfclere)

Display version. (MODCLUSTER-90) (jfclere)

Connector bind address of 0.0.0.0 propagated to proxy. (MODCLUSTER-91) (pferraro)

Display status of the worker. (MODCLUSTER-92) (jfclere)

Update httpd to lastest version. (MODCLUSTER-93) (jfclere)

getProxyInfo failed when there are too many nodes. (MODCLUSTER-94) (jfclere)

mod_cluster-manager display corrupted with jboss starting. (MODCLUSTER-95) (jfclere)

DISABLE application active as STOPPED. (MODCLUSTER-96) (jfclere)

Httpd should remove workers it can't ping. (MODCLUSTER-97) (jfclere)

Linux mod_cluster_manager display zero instead values. (MODCLUSTER-98) (jfclere)

mod_cluster_manager doesn't seem to ENABLE/DISABLE the right context. (MODCLUSTER-99) (jfclere)

load balancing logic doesn't allow manual demo of load-balancing. (MODCLUSTER-100) (jfclere)

404 errors when load is increasing. (MODCLUSTER-102) (jfclere)

Advertise security key verification does not work. (MODCLUSTER-104) (jfclere)

Allow advertise listener to listen on a specific network interface. (MODCLUSTER-106) (pferraro)

Allow thread factory injection for advertise listener. (MODCLUSTER-108) (pferraro)

Create SPI and isolate tomcat/jbossweb usage into service provider implementation. (MODCLUSTER-111) (pferraro)

See at the end of java configuration. You can't use the mod_cluster clustered mode with Tomcat so you get a loadbalancing logic similar to mod_jk but with a dynamic configuration.

Most likely you have a configuration problem. Check the log of the cluster nodes and error_log of httpd.

That happens when Advertise is not working: The nodes don't get the advertise messages from httpd.

  1. Check the modules are loaded and Advertise is started. In httpd.conf activate extended information display, add:

    AllowDisplay On

    When accessing to the mod_cluster_manager you should get something like:

    If not, go to the Minimal Example and add the missing directive(s).

  2. Check that Advertise message are received on the cluster node. A small Java utility could be used to check Advertise. It is in the mod_cluster repository and can be compiled using javac. A compiled version can be found under in /opt/jboss/httpd/tools in the bundles. Run it using java Advertise multicastaddress port. The output should be something like:

    [jfclere@jfcpc java]$ java Advertize 224.0.1.105 23364
    ready waiting...
    received: HTTP/1.0 200 OK
    Date: Mon, 28 Jun 2010 07:30:31 GMT
    Sequence: 1
    Digest: df8a4321fa99e5098174634f2fe2f87c
    Server: 1403c3be-837a-4e76-85b1-9dfe5ddb4378
    X-Manager-Address: test.example.com:6666
    X-Manager-Url: /1403c3be-837a-4e76-85b1-9dfe5ddb4378
    X-Manager-Protocol: http
    X-Manager-Host: test.example.com
  3. No Advertise messages

    Check firewall (don't forget the boxes firewall). Advertise uses UDP port 23364 and multicast addresse 224.0.1.105

  4. Can't get Advertise messages

    Use ProxyList property. In case Advertise can't work you put the address and port of the VirtualHost used in httpd to receive the MCMP. In server/profile/deploy/mod_cluster.sar/META-INF/mod_cluster-jboss-beans.xml

    <property name="proxyList">test.example.com:6666</property>

    or in server.xml:

    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" proxyList="test.example.com:6666"/>

You need to configure EnableMCPMReceive in the VirtualHost where you received the MCMP elements in the Apache httpd configuration. Something like:

<VirtualHost localhost:6666>
    <Directory />
     Order deny,allow
     Deny from all
     Allow from 127.0.0.1
    </Directory>
    ServerAdvertise on http://localhost:6666
    EnableMCPMReceive
</VirtualHost>