JBoss.orgCommunity Documentation
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:
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.
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.
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.
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.
httpd-2.2.8+
JBoss AS 5.0.0+ or JBossWeb 2.1.1+
httpd-2.2.8+ is already in the bundles, so if you use the bundle you don't need to download Apache httpd.
mod_cluster uses shared memory to keep the nodes description, the shared memory is created at the start of httpd and the structure of each item is fixed. The following can't be changed by configuration directives.
Max Alias length 40 characters (Host: hostname header, Alias in <Host/>).
Max context length 40 (for example myapp.war deploys in /myapp /myapp is the context).
Max balancer name length 40 (balancer property in mbean).
Max JVMRoute string length 80 (JVMRoute in <Engine/>).
Max load balancing group name length 20 (domain property in mbean).
Max hostname length for a node 64 (address in the <Connector/>).
Max port length for a node 7 (8009 is 4 characters, port in the <Connector/>).
Max scheme length for a node 6 (possible values are http, https, ajp, liked with the protocol of <Connector/>).
Max cookie name 30 (the header cookie name for sessionid default value: JSESSIONID from org.apache.catalina.Globals.SESSION_COOKIE_NAME).
Max path name 30 (the parameter name for the sessionid default value: jsessionid from org.apache.catalina.Globals.SESSION_PARAMETER_NAME).
Max length for a sessionid 120 (something like BE81FAA969BF64C8EC2B6600457EAAAA.node01).
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/
Building httpd modules
Building server-side components
If you want to skip the details and just set up a minimal working installation of mod_cluster, see the Quick Start Guide.
Configuring httpd
Configuring JBoss AS
Configuring JBoss Web or Tomcat
Migrating from mod_jk or mod_proxy is fairly straight forward. In general, much of the configuration previously found in httpd.conf is now defined in the application server nodes.
Both the request connections between httpd and the application server nodes, and the feedback channel between the nodes and httpd can be secured. The former is achieved via the mod_proxy_https module and a corresponding ssl-enabled HTTP connector in JBoss Web. The latter requires the mod_ssl module and explicit configuration in JBoss AS/Web.
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.
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.