Red Hat Training

A Red Hat training course is available for Red Hat JBoss Web Server

Chapter 3. mod_cluster Connector

3.1. Overview

The mod_cluster connector is a reduced configuration, intelligent load-balancing solution for JBoss Enterprise Application Platform (JBoss EAP) and Red Hat JBoss Web Server, based on technology originally developed by the JBoss mod_cluster community project.
mod_cluster load-balances HTTP requests to JBoss EAP and JBoss Web Server worker nodes, utilizing Apache HTTP Server as the proxy server. It serves as a load balancing solution for Tomcat in JBoss Web Server as well as for JBoss EAP.

3.1.1. Key Features

The mod_cluster connector has several advantages over the mod_jk connector:
  • The mod_cluster Management Protocol (MCMP) is an additional connection between the Tomcat servers and the Apache HTTP Server with the mod_cluster module enabled. It is used by the Tomcat servers to transmit server-side load figures and lifecycle events back to the Apache HTTP Server via a custom set of HTTP methods.
  • Dynamic configuration of Apache HTTP Server with mod_cluster allows Tomcat servers that have mod_cluster listeners to join the load balancing arrangement without manual configuration.
  • Tomcat servers performs the load calculations, rather than relying on the Apache HTTP Server with mod_cluster. This makes load balancing metrics more accurate than other connectors.
  • The mod_cluster connector gives fine-grained application lifecycle control. Each Tomcat server forwards web application context lifecycle events to the Apache HTTP Server, informing it to start or stop routing requests for a given context. This prevents end users from seeing HTTP errors due to unavailable resources.
  • AJP, HTTP or HTTPS transports can be used.

3.1.2. Components

On the proxy server, mod_cluster consists of four Apache modules.

Table 3.1. Components

Component Description
mod_cluster_slotmem.so The Shared Memory Manager module shares real time worker node information with multiple Apache HTTP Server processes.
mod_manager.so
The Cluster Manager module receives and acknowledges messages from nodes, including worker node registrations, worker node load data, and worker node application life cycle events.
mod_proxy_cluster.so The Proxy Balancer Module handles request routing to cluster nodes. The Proxy Balancer selects the appropriate destination node based on application location in the cluster, current state of each of the cluster nodes, and the Session ID (if a request is part of an established session).
mod_advertise.so
The Proxy Advertisement Module broadcasts the existence of the proxy server via UDP multicast messages. The server advertisement messages contain the IP address and port number where the proxy is listening for responses from nodes that want to join the load-balancing cluster.
See Section A.1, “Apache Modules” for detailed information about the available modules, including user-configurable parameters.

3.1.3. Limitations

mod_cluster uses shared memory to keep the nodes description. The shared memory is created at the startup of Apache HTTP Server, and the structure of each item is fixed. When defining proxy server and worker node properties, ensure that you follow these character limits:
  • Maximum Alias length: 100 characters (Alias corresponds to the network name of the respective virtual host; the name is defined in the Host element)
  • Maximum context length: 40 characters (for example, if myapp.war is deployed in /myapp, then /myapp is the context)
  • Maximum balancer name length: 40 characters (the balancer property in mbean)
  • Maximum JVMRoute string length: 80 characters (JVMRoute in the <Engine> element)
  • Maximum domain name length: 20 characters (the domain property in mbean)
  • Maximum hostname length for a node: 64 characters (hostname address in the <Connector> element)
  • Maximum port length for a node: 7 characters (8009 is 4 characters, the port property in the <Connector> element)
  • Maximum scheme length for a node: 6 characters (possible values are http, https, ajp, the protocol of the connector)
  • Maximum cookie name length: 30 characters (the header cookie name for session ID default value: JSESSIONID from org.apache.catalina.Globals.SESSION_COOKIE_NAME)
  • Maximum path name length: 30 characters (the parameter name for the session ID default value: JSESSIONID from org.apache.catalina.Globals.SESSION_PARAMETER_NAME)
  • Maximum length of a session ID: 120 characters (session ID resembles the following: BE81FAA969BF64C8EC2B6600457EAAAA.node01)