19.5.2. Configure the mod_cluster Subsystem
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
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") |
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") |
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.
|
/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.
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
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
add-metric
command.
/subsystem=modcluster/mod-cluster-config=configuration/:add-metric(type=sessions)
Example 19.2. Set a Value for an Existing Metric
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
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
remove-metric
command.
/subsystem=modcluster/mod-cluster-config=configuration/:remove-metric(type=sessions)