Chapter 10. Java Properties

10.1. Configuration Properties

The tables below enumerate the configuration properties available to an application server node. The location for these properties depends on how mod_cluster is configured.

10.1.1. Proxy Discovery Configuration

The list of proxies from which an application expects to receive AJP connections is either defined statically, via the addresses defined in the proxyList configuration property; or discovered dynamically via the advertise mechanism.
Using a special mod_advertise module, proxies can advertise their existence by periodically broadcasting a multicast message containing its address/port.
This functionality is enabled via the advertise configuration property. If configured to listen, a server can learn of the proxy's existence, then notify that proxy of its own existence, and update its configuration accordingly. This frees both the proxy and the server from having to define static, environment-specific configuration values.

Table 10.1. Proxy Discovery

Attribute
Default
Description
proxyList
None
Defines a comma-separated list of httpd proxies with which this node will initially communicate. Value should be of the form:
address1:port1,address2:port2
Using the default configuration, this property can by manipulated via the jboss.modcluster.proxyList system property.
excludedContexts
ROOT,admin-console,invoker,jbossws,jmx-console,juddi,web-console
List of contexts to exclude from httpd registration, of the form:
host1:context1,host2:context2,host3:context3
If no host is indicated, it is assumed to be the default host of the server (e.g. localhost). "ROOT" indicates the root context. Using the default configuration, this property can by manipulated via the jboss.modcluster.excludedContexts system property.
autoEnableContexts
True
If false, the contexts are registered disabled in httpd, they need to be enabled via the enable() MBean method or via mod_cluster_manager.
stopContextTimeout
10
The number of seconds to wait for clean shutdown of a context,. This could be the completion of all pending requests for a distributable context or the destruction/expiration of active sessions for a non-distributable context.
proxyURL
None
If defined, this value will be prepended to the URL of MCMP commands.
socketTimeout
20000
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.
advertise
This is true if proxyList is undefined, false otherwise.
If enabled, httpd proxies will be auto-discovered via multicast announcements. This can be used either in concert or in place of a static proxyList.
advertiseGroupAddress
224.0.1.105
The UDP address on which to listen for httpd proxy multicast advertisements.
advertisePort
23364
The UDP port on which to listen for httpd proxy multicast advertisements.
advertiseSecurityKey
None
If specified, httpd proxy advertisements checksums will be verified using this value as a salt.

10.1.2. Proxy Configuration

The following configuration values are sent to proxies during server startup, when a proxy is detected via the advertise mechanism, or during the resetting of a proxy's configuration during error recovery.

Table 10.2. Proxy Configuration

Attribute
Default
Description
stickySession
true
Indicates whether subsequent requests for a given session should, if possible, be routed to the same node.
stickySessionRemove
false
Indicates whether the httpd proxy should remove session stickiness in the event that the balancer is unable to route a request to the node to which it is stuck. This property is ignored if stickySession is false.
stickySessionForce
true
Indicates whether the httpd proxy should return an error in the event that the balancer is unable to route a request to the node to which it is stuck. This property is ignored if stickySession is false.
workerTimeout
-1
Number of seconds to wait for a worker to become available to handle a request. When all the workers of a balancer are unusable, mod_cluster will retry after a specified period (workerTimeout/100) to find a usable worker.
A value of -1 indicates that the httpd will not wait for a worker to be available and will return an error if none is available.
maxAttempts
1
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.
Note that mod_proxy default is also 1: no retry.
flushPackets
false
Enables/disables packet flushing.
flushWait
-1
Time to wait before flushing packets. A value of -1 means wait forever.
ping
10 seconds
Time to wait for an answer to a ping.
smax
Determined by httpd configuration.
Soft maximum idle connection count (that is the smax in worker mod_proxy documentation). The maximum value depends on the httpd thread configuration (ThreadsPerChild or 1).
ttl
60 seconds
Time to live (in seconds) for idle connections above smax.
nodeTimeout
-1 (none)
Timeout (in seconds) for proxy connections to a node. That is the time mod_cluster will wait for the back-end response before returning an error.
This corresponds to timeout in the worker mod_proxy documentation.
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.
balancer
mycluster
The balancer name.
domain
None
If specified, load will be balanced among jvmRoutes with the same domain. This is primarily used in conjunction with partitioned session replication (e.g. buddy replication).
Note: When nodeTimeout is not defined the ProxyTimeout directive Proxy is used. If ProxyTimeout is not defined the server timeout (Timeout) is used (default 300 seconds). nodeTimeout, ProxyTimeout or Timeout is set at the socket level.

10.1.3. SSL Configuration

The communication channel between application servers and httpd proxies uses HTTP by default. This channel can be secured using HTTPS by setting the ssl parameter to true.
Note: This HTTP/HTTPS channel should not be confused with the processing of HTTP/HTTPS client requests.

Table 10.3. SSL Configuration

Attribute
Default
Description
ssl
false
Should connection to proxy use a secure socket layer.
sslCiphers
The default JSSE cipher suites
Overrides the cipher suites used to init an SSL socket ignoring any unsupported ciphers.
sslProtocol
TLS
Overrides the default SSL socket protocol.
sslCertificateEncodingAlgorithm
The default JSSE key manager algorithm.
The algorithm of the key manager factory.
sslKeyStore
System.getProperty("user.home") + "/.keystore"
The location of the key store containing client certificates.
sslKeyStorePass
changeit
The password granting access to the key store.
sslKeyStoreType
JKS
The type of key store.
sslKeyStoreProvider
The default JSSE security provider.
The key store provider.
sslTrustAlgorithm
The default JSSE trust manager algorithm.
The algorithm of the trust manager factory.
sslKeyAlias
 
The alias of the key holding the client certificates in the key store.
sslCrlFile
 
Certificate revocation list.
sslTrustMaxCertLength
5
The maximum length of a certificate held in the trust store.
sslTrustStore
System.getProperty("javax.net.ssl.trustStorePassword")
The location of the file containing the trust store.
sslTrustStorePassword
System.getProperty("javax.net.ssl.trustStore")
The password granting access to the trust store.
sslTrustStoreType
System.getProperty("javax.net.ssl.trustStoreType")
The trust store type.
sslTrustStoreProvider
System.getProperty("javax.net.ssl.trustStoreProvider")
The trust store provider.

10.1.4. HA Configuration

Additional configuration properties when mod_cluster is configured in clustered mode.

Table 10.4. HA Configuration

Attribute
Default
Description
masterPerDomain
false
If the domain directive is used, should HA partition use a singleton master per domain.

10.1.5. Load Configuration

Additional configuration properties used when mod_cluster is configured in JBoss Web standalone or Tomcat.

Table 10.5. Load Configuration

Attribute
Default
Description
loadMetricClass
org.jboss.modcluster.load.metric.impl.BusyConnectorsLoadMetric
Class name of an object implementing org.jboss.load.metric.LoadMetric.
loadMetricCapacity
1
The capacity of the load metric defined via the loadMetricClass property.
loadHistory
9
The number of historic load values to consider in the load balance factor computation.
loadDecayFactor
2
The factor by which a historic load values should degrade in significance.