16.5.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 or standalone-full-ha profile to start the server. Click the Web item in the left-hand menu, and choose mod_cluster 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 mod_cluster configuration screen.

Note

The mod_cluster 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 and standalone-full-ha for a standalone server.

Table 16.4. 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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=load-balancing-group,value=myGroup)
Balancer
The name of the balancer. This should match the configuration of the HTTPD proxy.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=balancer,value=myBalancer)
Advertise Socket
The name of the socket binding to use for cluster advertising.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise-socket,value=modcluster)
Advertise Security Key
A string containing the security key for advertising.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise-security-key,value=myKey)
Advertise
Whether or not advertising is enabled. Defaults to true.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise,value=true)

Table 16.5. 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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session,value=true)
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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session-force,value=false)
Sticky Session Remove
Remove session information on failover. Disabled by default.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session-remove,value=false)

Table 16.6. 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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=auto-enable-contexts,value=true)
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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=excluded-contexts,value="ROOT,invoker,jbossws,juddi,console")

Table 16.7. mod_cluster Proxy Configuration Options

Option Description CLI Command
Proxy URL
If defined, this value will be prepended to the URL of MCMP commands.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=proxy-url,value=myhost)
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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=proxy-list,value="127.0.0.1,127.0.0.2")
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 16.5, “mod_cluster Session Configuration Options”), the settings below tell mod_cluster where to find the information to encrypt the connection.

Table 16.8. mod_cluster SSL Configuration Options

Option Description CLI Command
ssl
Whether to enable SSL. Defaults to false.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ssl,value=true)
Key Alias
The key alias, which was chosen when the certificate was created.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-alias,value=jboss)
Key Store
TThe location of the key store containing client certificates
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store,value=System.getProperty("user.home") + "/.keystore")
Key Store Type
TThe key store type
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store-type,value=JKS)
Key Store Provider
The key store provider
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store-provider,value=IBMJCE)
Password
The password, which was chosen when the certificate was created.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=password,value=changeit)
Trust Algorithm
The algorithm of the trust manager factory.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=trust-algorithm,value=PKIX)
Cert File
The location of the certificate file.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-certificate-file,value=${user.home}/jboss.crt)
CRL File
Certificate revocation list file.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-crl-file,value=${user.home}/jboss.crl)
Max Certificate Length
The maximum length of a certificate held in the trust store. Defaults to 5.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=trust-max-cert-length,value=5)
Key File
The location of the key file for the certificate.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=certificate-key-file,value=${user.home}/.keystore)
Cipher Suite
The allowed encryption cipher suite.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=cipher-suite,value=ALL)
Certificate Encoding Algorithms
The algorithm of the key manager factory.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=encoding-algorithms,value=ALL)
Revocation URL
The URL of the Certificate Authority revocation list.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-revocation-url,value=jboss.crl)
Protocol
The SSL protocols which are enabled.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=protocol,value=SSLv3)
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 16.9. 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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=node-timeout,value=-1)
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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=socket-timeout,value=20)
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).
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=stop-context-timeout,value=10)
Session Draining Strategy
Whether to drain sessions before undeploying a web application.
DEFAULT
Drain sessions before web application undeploy only if the web application is non-disributable.
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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=session-draining-strategy,value=DEFAULT)
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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=max-attempts,value=1)
Flush Packets
Whether or not to enable packet flushing to the HTTPD server. Defaults to false.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=flush-packets,value=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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=flush-wait,value=-1)
Ping
How long, in seconds, to wait for a response to a ping from a cluster node. Defaults to 10 seconds.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=ping,value=10)
SMAX
Soft maximum idle connection count (the same as smax in worker mod_proxy documentation). The maximum value depends on the httpd thread configuration, and can be either ThreadsPerChild or 1.
profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=smax,value=ThreadsPerChild)
TTL
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, and Timeout are set at the socket level.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=ttl,value=-1)
Node 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 mod_cluster waits indefinitely for the HTTPD worker to process the request.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=node-timeout,value=-1)
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. Note that you can have more than one of these factors (metric) at anytime by simply adding them via the CLI.
:add-metric(type=cpu)

Table 16.10. mod_cluster Dynamic Load Provider Options

Option Description CLI Command
Decay
The factor by which historical metrics should decay in significance.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/:write-attribute(name=decay,value=2)
History
The number of historic load metric records to consider when determining the load.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/:write-attribute(name=history,value=9)
Load Metric
The only load metric included with the dynamic load provider in JBoss EAP 6 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.
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=capacity,value=1.0)
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=type,value=busyness)
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=weight,value=1)

Load Metric Algorithms

cpu
The cpu load metric uses average CPU load to determine which cluster node receives the next work load.
mem
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.
heap
The heap load metric uses the heap usage to determine which cluster receives the next work load.
sessions
The session load metric uses the number of active sessions as a metric.
requests
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".
send-traffic
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.
receive-traffic
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.
busyness
This metric represents the amount of threads from the thread pool being busy serving requests.

Example 16.1. Set a Load Balancer Metric

/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=cpu/:write-attribute(name="weight",value="3")