13.3.2. Configure the mod_cluster Subsystem

In the web-based Management Console, the mod_cluster options are available as part of the Web subsystem configuration area. Click the Profiles tab at the top left. If you use a managed domain, select the correct profile to configure from the Profile selection box at the upper right. By default, the ha and full-ha profiles have the mod_cluster subsystem enabled. If you use a standalone server, you need to use the standalone-ha profile to start the server. Click the Web item in the left-hand menu, and choose Modcluster from the sub-menu. The options are explained in the tables below. Overall configuration is shown first, followed by configuration of sessions, web contexts, proxies, SSL, and Networking. Each of these has its own tab within the Modcluster configuration screen.


The Modcluster configuration page is only visible for profiles with the HA Clustering subsystem enabled. These profiles are ha and full-ha for a managed domain, or standalone-ha for a standalone server.

Table 13.7. mod_cluster Configuration Options

Option Description CLI Command
Load Balancing Group
If this is not null, requests are sent to a specific load balancing group on the load balancer. Leave this blank if you do not want to use load balancing groups. This is unset by default.
The name of the balancer. This should match the configuration of the HTTPD proxy.
Advertise Socket
The name of the socket binding to use for cluster advertising.
Advertise Key
A string containing the security key for advertising.
Whether or not advertising is enabled. Defaults to true.

Table 13.8. mod_cluster Session Configuration Options

Option Description CLI Command
Sticky Session
Whether to use sticky sessions for requests. This means that after the client makes a connection to a specific cluster node, further communication is routed to that same node unless it becomes unavailable. This defaults to true, which is the recommended setting.
Sticky Session Force
If true, a request is not redirected to a new cluster node if its initial node becomes unavailable. Instead, it fails. This defaults to false.
Sticky Session Remove
Remove session information on failover. Disabled by default.

Table 13.9. mod_cluster Web Context Configuration Options

Option Description CLI Command
Auto Enable Contexts
Whether to add new contexts to mod_cluster by default or not. This defaults to true. If you change the default and need to enable context manually, the Web Application can enable its context using the enable() MBean method, or via the mod_cluster manager, which is a web application which runs on the HTTPD proxy on a named virtual host or port which is specified in that HTTPD's configuration.
Excluded Contexts
A comma-separated list of contexts that mod_cluster should ignore. If no host is indicated, the host is assumed to be localhost. ROOT indicates the root context of the Web Application. The default value is ROOT,invoker,jbossws,juddi,console.

Table 13.10. mod_cluster Proxy Configuration Options

Option Description CLI Command
Proxy URL
If defined, this value will be prepended to the URL of MCMP commands.
Proxy List
A comma-separated list of HTTPD proxy addresses, in the format hostname:port. This indicates the list of proxies that the mod_cluster process will attempt to communicate with initially.
Configure SSL Communication for mod_cluster

By default, mod_cluster communication happens over an unencrypted HTTP link. If you set the connector scheme to HTTPS (refer to Table 13.8, “mod_cluster Session Configuration Options”), the settings below tell mod_cluster where to find the information to encrypt the connection.

Table 13.11. mod_cluster SSL Configuration Options

Option Description CLI Command
Key Alias
The key alias, which was chosen when the certificate was created.
The password, which was chosen when the certificate was created.
Cert File
The location of the certificate file.
Key File
The location of the key file for the certificate.
Cipher Suite
The allowed encryption cipher suite.
Revocation URL
The URL of the Certificate Authority revocation list.
The SSL protocols which are enabled.
Configure mod_cluster Networking Options

The available mod_cluster networking options control several different timeout behaviors for different types of services that the mod_cluster service communicates with.

Table 13.12. mod_cluster Networking Configuration Options

Option Description CLI Command
Node Timeout
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.
Socket Timeout
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.
Stop Context Timeout
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).
Max Attempts
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. The mod_proxy default is also 1, which means that no retry occurs.
Flush Packets
Whether or not to enable packet flushing to the HTTPD server. Defaults to false.
Flush Wait
How long, in seconds, to wait before flushing packets to the HTTPD server. Defaults to -1. A value of -1 means to wait forever before flushing packets.
How long, in seconds, to wait for a response to a ping from a cluster node. Defaults to 10 seconds.
Time to live (in seconds) for idle connections above smax, default is 60
When nodeTimeout is not defined the ProxyTimeout directive Proxy is used. If ProxyTimeout is not defined the server timeout Timeout is used. This defaults to 300 seconds. nodeTimeout, ProxyTimeout, are Timeout are set at the socket level.
Worker Timeout
How long, in seconds, to wait for an available worker process from the external HTTPD server to process a request. Defaults to -1, which means that Modcluster waits indefinitely for the HTTPD worker to process the request.
mod_cluster Load Provider Configuration Options

The following mod_cluster configuration options are not available in the web-based Management Console, but can only be set using the command-line Management CLI.

The simple load processor is used if no dynamic load processor is present. It gives each cluster member a load factor of 1, and distributes work evenly without taking any sort of load balancing algorithm into account. To add it, use the following CLI command: /profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/simple-load-provider:add
A dynamic load provider can be configured to use a variety of different algorithms, in combination, to determine which cluster node receives the next request. The default dynamic load provider uses busyness as the determining factor. The list of possible factors is shown below. You can create your own load provider to suit your own environment, as well. The following options of the dynamic load provider can be changed. .

Table 13.13. mod_cluster Dynamic Load Provider Options

Option Description CLI Command
The factor by which historical metrics should decay in significance.
The number of historic load metric records to consider when determining the load.
Load Metric
The only load metric included in the dynamic load provider is busyness, which tries to send each new request to the least busy worker. You can set the capacity of your worker (1 means 100% capacity) and the weight assigned to the busyness metric overall. .

Load Metric Algorithms

The cpu load metric uses average CPU load to determine which cluster node receives the next work load.
The mem load metric uses free native RAM as a load factor. Usage of this metric is discouraged because it provides a value that includes buffers and cache, so it is always a very low figure on every decent system with a good memory management.
The heap load metric uses the heap usage to determine which cluster receives the next work load.
The session load metric uses the number of active sessions as a metric.
The requests load metric uses the number of client requests to determine which cluster node receives the next work load. For instance, capacity 1000 means that 1000 requests/sec is considered to be a "full load".
The send-traffic load metric uses the amount of traffic sent from the worker node to the clients. E.g. the default capacity of 512 indicates that the node should be considered under full load if the average outbound traffic is 512 KB/s or higher.
The receive-traffic load metric uses the amount of traffic sent to the worker node from the clients.E.g. the default capacity of 1024 indicates that the node should be considered under full load if the average inbound traffic is 1024 KB/s or higher.
This metric represents the amount of threads from the thread pool being busy serving requests.

Example 13.5. Set a Load Balancer Metric