Chapter 6. Install proxy server components

Read this chapter to install the JBoss HTTP Connector, mod_cluster, on a proxy server.

6.1. Apache HTTP Server modules

Read this section for expanded definitions of the Apache HTTP Server proxy server modules discussed in Section 5.2, “Components”. You specify these modules as part of Task: Install Proxy Server Components.

6.1.1. mod_manager.so

The Cluster Manager module, mod_manager, receives and acknowledges messages from nodes, including worker node registrations, worker node load data, and worker node application life-cycle events. 
LoadModule manager_module modules/mod_manager.so
You can also define the following related directives in the <VirtualHost> element:
MemManagerFile
Defines the location for the files in which mod_manager stores configuration details. mod_manager also uses this location to store generated keys for shared memory and lock files. This must be an absolute path name.
It is recommended that this path be set explicitly and on a local drive, not an NFS share. The default value is platform/httpd specific.
Valid paths are:
  • HP-UX: HTTPD_HOME/cache/mod_cluster
  • Red Hat Enterprise Linux: /var/cache/mod_cluster
Maxcontext
The maximum number of contexts JBoss mod_cluster will use. The default value is 100.
Maxnode
The maximum number of worker nodes JBoss mod_cluster will use. The default value is 20.
Maxhost
The maximum number of hosts (aliases) JBoss mod_cluster will use. This is also the maximum number of load balancers. The default value is 10.
Maxsessionid
The maximum number of active session identifiers stored. A session is considered inactive when no information is received from that session within five minutes. The default value is 0, which disables this logic.
ManagerBalancerName
The name of the load balancer to use when the worker node does not provide a load balancer name. The default value is mycluster.
PersistSlots
When set to on, nodes, aliases and contexts are persisted in files. The default value is off.
CheckNonce
When set to on, session identifiers are checked to ensure that they are unique, and have not occurred before. The default is on.

Warning

Setting this directive to off can leave your server vulnerable to replay attacks.
SetHandler
Defines a handler to display information about worker nodes in the cluster. This is defined in the Location element: 
<Location $LOCATION>
  SetHandler mod_cluster-manager
  Order deny,allow
  Deny from all
  Allow from 127.0.0.1
</Location>
When accessing the $LOCATION defined in the Location element in your browser, you will see something like the following. (In this case, $LOCATION was also defined as mod_cluster-handler.)
mod_cluster Status

Figure 6.1. mod_cluster Status

Transferred corresponds to the POST data sent to the worker node. Connected corresponds to the number of requests that had been processed when this status page was requested. Sessions corresponds to the number of active sessions. This field is not present when Maxsessionid is 0.

6.1.2. mod_proxy_cluster.so

The Proxy Balancer module, mod_proxy_cluster, handles the routing of requests to cluster nodes. The Proxy Balancer selects the appropriate node to forward the request to, based on application location in the cluster, current state of each of the cluster nodes, and the Session ID (if a request is part of an established session). 
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
You can also define the following related directives in the <VirtualHost> element to change load-balancing behavior.

mod_proxy_cluster directives

CreateBalancers
Defines how load balancers are created in the Apache HTTP Server virtual hosts. The following values are valid in CreateBalancers :
0
Create load balancers in all virtual hosts defined in Apache HTTP Server. Remember to configure the load balancers in the ProxyPass directive.
1
Do not create balancers. When using this value, you must also define the load balancer name in the ProxyPass or ProxyPassMatch .
2
Create only the main server. This is the default value for CreateBalancers .
UseAlias
Defines whether to check that the defined Alias corresponds to the ServerName . The following values are valid for UseAlias :
0
Ignore Alias information from worker nodes. This is the default value for UseAlias .
1
Verify that the defined alias corresponds to a worker node's server name.
LBstatusRecalTime
Defines the interval in seconds between the proxy calculating the status of a worker node. The default interval is 5 seconds.
ProxyPassMatch; ProxyPass
ProxyPass maps remote servers into the local server namespace. If the local server has an address http://local.com/, then the following ProxyPass directive would convert a local request for http://local.com/requested/file1 into a proxy request for http://worker.local.com/file1. 
ProxyPass /requested/ http://worker.local.com/
ProxyPassMatch uses Regular Expressions to match local paths to which the proxied URL should apply.
For either directive, ! indicates that a specified path is local, and a request for that path should not be routed to a remote server. For example, the following directive specifies that .gif files should be served locally. 
ProxyPassMatch ^(/.*\.gif)$ !

6.1.3. mod_advertise.so

The Proxy Advertisement module, mod_advertise.so, broadcasts the existence of the proxy server via UDP multicast messages. The server advertisement messages contain the IP address and port number where the proxy is listening for responses from nodes that wish to join the load-balancing cluster.
This module must be defined alongside mod_manager in the VirtualHost element. Its identifier in the following code snippet is advertise_module. 
LoadModule advertise_module modules/mod_advertise.so
mod_advertise also takes the following directives:
ServerAdvertise
Enables or disables the advertising mechanism. When set to On, the advertising mechanism is used to tell worker nodes to send status information to this proxy. When set to Off, the advertising mechanism is disabled.
You can also specify a hostname and port with the following syntax: ServerAdvertise On http://hostname:port/. This is only required when using a name-based virtual host, or when a virtual host is not defined.
The default value is Off but it is automatically enabled if any Advertise directive is specified in defining a VirtualHost.
AdvertiseGroup
Defines the multicast address to advertise on. The syntax is AdvertiseGroup address:port, where address should correspond to AdvertiseGroupAddress , and port should correspond to AdvertisePort in your worker nodes.
If your worker node is JBoss Enterprise Application Platform-based, and the -u switch is used at startup, the default AdvertiseGroupAddress is the value passed via the -u switch.
The default value is 224.0.1.105:23364. If port is not specified, the default port used is 23364.
AdvertiseFrequency
The interval (in seconds) between multicast messages advertising the IP address and port. The default value is 10.
AdvertiseSecurityKey
Defines a string used to identify the JBoss HTTP Connector mod_cluster in JBoss Web. By default this directive is not set and no information is sent.
AdvertiseManagerUrl
Defines the URL that the worker node should use to send information to the proxy server. By default this directive is not set and no information is sent.
AdvertiseBindAddress
Defines the address and port over which to send multicast messages. The syntax is AdvertiseBindAddress address:port. This allows an address to be specified on machines with multiple IP addresses. The default value is 0.0.0.0:23364.