16.5.2. Configure the mod_cluster Subsystem
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
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") |
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) |
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.
|
/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.
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
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")