19.5.2. Configure the mod_cluster Subsystem

In the management console, the mod_cluster options are available as part of the Web subsystem configuration area. Click the Configuration tab. If you use a managed domain, select the correct profile to configure from the Profile selection box at the top left. 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. Expand the Web menu in the and select mod_cluster. 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 ha and full-ha profiles. For a managed domain these profiles are ha and full-ha, and for a standalone server they are standalone-ha and standalone-full-ha.

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

Table 19.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.
/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 but instead it fails. This defaults to false.
/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session-force,value=false)
Sticky Session Remove
Remove session information on failover. This defaults to false.
/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session-remove,value=false)

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

Table 19.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.
/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.
/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 19.5, “mod_cluster Session Configuration Options”), the settings below tell mod_cluster where to find the information to encrypt the connection.

Table 19.8. mod_cluster SSL Configuration Options

Option Description CLI Command
ssl
Whether to enable SSL. Defaults to false.
/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.
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-alias,value=jboss)
Key Store
The location of the key store containing client certificates.
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store,value=System.getProperty("user.home") + "/.keystore")
Key Store Type
The key store type
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=key-store-type,value=JKS)
Key Store Provider
The key store provider.
/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.
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=password,value=changeit)
Trust Algorithm
The algorithm of the trust manager factory.
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=trust-algorithm,value=PKIX)
Cert File
The location of the certificate file.
/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.
/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.
/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.
/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.
/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.
/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.
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=ca-revocation-url,value=jboss.crl)
Protocol
The SSL protocols, which are enabled.
You can also specify a combination of protocols, which is comma separated. For example, TLSv1, TLSv1.1,TLSv1.2.

Warning

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2 in all affected packages.
/subsystem=modcluster/mod-cluster-config=configuration/ssl=configuration/:write-attribute(name=protocol,value="TLSv1, TLSv1.1,TLSv1.2")
Configure mod_cluster Networking Options

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

Table 19.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.
/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.
/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).
/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-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.
/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.
/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=max-attempts,value=1)
Flush Packets
Whether or not to enable packet flushing to the Web server. Defaults to false.
/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 Web server. Defaults to -1. A value of -1 means to wait forever before flushing packets.
/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.
/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.
/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 Web server to process a request. Defaults to -1, which means that mod_cluster waits indefinitely for the httpd worker to process the request.
/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 management console, but can only be set using the management CLI.

A simple load provider is used if no dynamic load provider is present. It assigns each cluster member a load factor of 1, and distributes work evenly without applying a load balancing algorithm. To add it, use the following management CLI command.
/subsystem=modcluster/mod-cluster-config=configuration/simple-load-provider:add
A dynamic load provider can be configured to use a variety of algorithms in combination, in order to determine which cluster node receives the next request. You can create a load provider and configure it to suit your environment, and you can have more than one load metric active simultaneously by adding them via the CLI. The default dynamic load provider uses busyness as the determining load metric. The dynamic load provider options and possible load metrics are shown below.

Table 19.10. mod_cluster Dynamic Load Provider Options

Option Description CLI Command
Decay
The factor by which historical metrics should decay in significance.
/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.
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/:write-attribute(name=history,value=9)
Load Metric
The default load metric included with the dynamic load provider in JBoss EAP 6 is busyness, which calculates the load of the worker node from the amount of threads in the thread pool being busy serving requests. You can set the capacity of this metric by which the actual load is divided: calculated_load / capacity. You can set multiple load metrics within the dynamic load provider.
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=capacity,value=1.0)
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=busyness/:write-attribute(name=type,value=busyness)
/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 memory as a load metric. 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 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 19.1. Add a Load Metric

To add a load metric, use the add-metric command.
/subsystem=modcluster/mod-cluster-config=configuration/:add-metric(type=sessions)

Example 19.2. Set a Value for an Existing Metric

To set a value for an existing metric, use the write-attribute command.
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=cpu/:write-attribute(name="weight",value="3")

Example 19.3. Change the Value of an Existing Metric

To change the value of an existing metric, use the write-attribute command.
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-load-provider=configuration/load-metric=cpu/:write-attribute(name="type",value="busyness")

Example 19.4. Remove an Existing Metric

To remove an existing metric, use the remove-metric command.
/subsystem=modcluster/mod-cluster-config=configuration/:remove-metric(type=sessions)