Appendix A. Apache HTTP Server Reference
A.1. Apache HTTP Server Modules
This section contains expanded definitions of the Apache HTTP Server proxy modules discussed in mod_cluster components.
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
Configurable directives in the
<VirtualHost> element are as follows:
VirtualHostto receive the mod_cluster Protocol Message
(MCPM)from nodes. Add one
EnableMCPMReceivedirective to the Apache HTTP Server configuration to allow
mod_clusterto operate correctly.
EnableMCPMReceivemust be added in the
VirtualHostconfiguration at the location where
Defines the maximum size of mod_cluster Management Protocol
(MCMP)messages. The default value is calculated from other
Maxdirectives. The minimum value is
Toggles the additional display on the
mod_cluster-managermain page. The default value is
off, which causes only version information to display on the
Toggles permissions for commands using
mod_cluster-managerURL. The default value is
on, which allows commands.
Toggles the reduction of information displayed on the
mod_cluster-managerpage. Reducing the information allows more nodes to display on the page. The default value is
off, which allows all the available information to display.
Defines the location for the files in which mod_manager stores configuration details. mod_manager also uses this location for generated keys for shared memory and lock files. This must be an absolute path name. It is recommended that this path be on a local drive, and not an NFS share. The default value is
The maximum number of contexts mod_cluster will use. The default value is
The maximum number of worker nodes mod_cluster will use. The default value is
The maximum number of hosts (aliases) mod_cluster will use. This is also the maximum number of load balancers. The default value is
The maximum number of active session identifiers stored. A session is considered inactive when no information is received from that session for five minutes. This is used for demonstration and debugging purposes only. The default value is
0, which disables this logic.
The name of the load balancer to use when the worker node does not provide a load balancer name. The default value is
When set to
on, nodes, aliases, and contexts are persisted in files. The default value is
When set to
on, session identifiers are checked to ensure that they are unique and have not occurred before. The default is
Setting this directive to
offcan leave your server vulnerable to replay attacks.
- SetHandler mod_cluster-manager
Defines a handler to display information about worker nodes in the cluster. This is defined in the
<Location $LOCATION> SetHandler mod_cluster-manager Require ip 127.0.0.1 </Location>
When accessing the
$LOCATIONdefined in the
Locationelement in your browser, you will see something like the following. (In this case,
$LOCATIONwas also defined as
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
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 the application location in the cluster, the 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 configure the following directives in the
<VirtualHost> element to change the load balancing behavior.
Defines how load balancers are created in the Apache HTTP Server virtual hosts. The following values are valid in
0: Create load balancers in all virtual hosts defined in Apache HTTP Server. Remember to configure the load balancers in the
1: Do not create balancers. When using this value, you must also define the load balancer name in
2: Create only the main server. This is the default value for
Defines whether to check that the defined
Aliascorresponds to the
ServerName. The following values are valid for
0: Ignore alias information from worker nodes. This is the default value for
1: Verify that the defined alias corresponds to a worker node’s server name.
Defines the interval in seconds between the proxy calculating the status of a worker node. The default interval is
- ProxyPassMatch; ProxyPass
ProxyPassmaps remote servers into the local server namespace. If the local server has an address
http://local.com/, then the following
ProxyPassdirective would convert a local request for
http://local.com/requested/file1into a proxy request for
ProxyPass /requested/ http://worker.local.com/
ProxyPassMatchuses 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
giffiles should be served locally.
ProxyPassMatch ^(/.*\.gif)$ !
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 example is
LoadModule advertise_module modules/mod_advertise.so
mod_advertise is configurable using the following directives:
Defines how the advertising mechanism is used.
The default value is
Off. When set to
Off, the proxy does not advertise its location.
When set to
On, the advertising mechanism is used to tell worker nodes to send status information to this proxy. You can also specify a host name 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.
Defines the multicast address to advertise on. The syntax is
AdvertiseGroup ADDRESS:PORT, where
ADDRESSmust correspond to
PORTmust correspond to
AdvertisePortin your worker nodes.
If your worker node is JBoss EAP-based, and the
-uswitch is used at startup, the default
AdvertiseGroupAddressis the value passed via the
The default value is
220.127.116.11:23364. If a port is not specified, the port defaults to
The interval (in seconds) between multicast messages advertising the IP address and port. The default value is
- Defines a string used to identify mod_cluster in Apache HTTP Server. By default this directive is not set and no information is sent.
- 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.
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
mod_proxy.so is a standard Apache HTTP Server module. This module lets the server act as proxy for data transferred over AJP (Apache JServe Protocol), FTP, CONNECT (for SSL), and HTTP. This module does not require additional configuration. Its identifier is
Mod_proxy directives such as
ProxyIOBufferSize are used to configure
mod_proxy_ajp.so is a standard Apache HTTP Server module that provides support for AJP (Apache JServe Protocol) proxying.
mod_proxy.so is required to use this module.
mod_cluster_slotmem does not require any configuration directives.
Apache HTTP Server worker nodes are servlet containers that are mapped to the
mod_jk load balancer. The worker nodes are defined in
JBCS_HOME/httpd/conf/workers.properties. This file specifies where the different servlet containers are located, and how calls should be load-balanced across them.
workers.properties file contains two sections:
- Global Properties
- This section contains directives that apply to all workers.
- Worker Properties
- This section contains directives that apply to each individual worker.
Each node is defined using the worker properties naming convention. The worker name can only contain lowercase letters, uppercase letters, numbers, and specific special characters (
The structure of a worker property is
- The constant prefix for all worker properties.
The arbitrary name given to the worker. For example:
- The specific directive required.
The main directives required to configure worker nodes are described below.
For the full list of
worker.properties configuration directives, see the Apache Tomcat Connector - Reference Guide.
worker.properties Global Directives
Specifies the list of worker names used by mod_jk. The workers in this list are available to map requests to.Note
A single node configuration which is not managed by a load balancer must be set to
workers.properties Mandatory Directives
Specifies the type of worker, which determines the directives applicable to the worker. The default value is
ajp13, which is the preferred worker type to select for communication between the web server and Apache HTTP Server.
Other values include
For detailed information about AJPv13, see the Apache Tomcat Connector - AJP Protocol Reference.
workers.properties Connection Directives
The hostname or IP address of the worker. The worker node must support the ajp13 protocol stack. The default value is
You can specify the
portdirective as part of the host directive by appending the port number after the host name or IP address. For example:
The port number of the remote server instance listening for the defined protocol requests. The default value is
8009, which is the default listen port for AJPv13 workers.
Specifies the conditions under which connections are probed for their current network health.
The probe uses an empty AJPv13 packet for the
CPing, and expects a
CPongin return, within a specified timeout.
You specify the conditions by using a combination of the directive flags. The flags are not comma-separated. For example, a correct directive flag set is
- C (connect)
Specifies the connection is probed once after connecting to the server. You specify the timeout using the
connect_timeoutdirective, otherwise the value for
- P (prepost)
Specifies that the connection is probed before sending each request to the server. You specify the timeout using the
prepost_timeoutdirective, otherwise the value for
- I (interval)
Specifies that the connection is probed during regular internal maintenance cycles. You specify the idle time between each interval using the
connection_ping_intervaldirective, otherwise the value for
- A (all)
The most common setting, which specifies that all directive flags are applied. For information about the
\*_timeoutadvanced directives, see the Apache Tomcat Connector - Reference Guide.
Specifies the time to wait for
CPonganswers to a
CPingconnection probe (see
ping_mode). The default value is
worker.properties Load Balancing Directives
Specifies the load-balancing factor for an individual worker, and is only specified for a member worker of a load balancer.
This directive defines the relative amount of HTTP request load distributed to the worker compared to other workers in the cluster.
A common example where this directive applies is where you want to differentiate servers with greater processing power than others in the cluster. For example, if you require a worker to take three times the load than other workers, specify
Specifies the worker nodes that the load balancer must manage. The directive can be used multiple times for the same load balancer, and consists of a comma-separated list of worker names as specified in the
Specifies whether requests for workers with SESSION IDs are routed back to the same worker. The default is
0(false). When set to
1(true), load balancer persistence is enabled.
For example, if you specify
worker.loadbalancer.sticky_session=0, each request is load balanced between each node in the cluster. In other words, different requests for the same session can go to different servers based on server load.
If you specify
worker.loadbalancer.sticky_session=1, each session is persisted (locked) to one server until the session is terminated, providing that server is available.
A.3. Multi-Processing Modules (MPMs)
Red Hat JBoss Core Services includes a variety of multi-processing modules (MPMs), allowing for users to customize how the Apache HTTP Server answers incoming requests.
A.3.1. MPM Overview
An overview of the MPMs available per Operating System are outlined below.
A.3.1.1. Unix MPMs
preforkMPM implements a non-threaded, pre-forking web server. A single control process is responsible for launching child processes, which listen for incoming connections and service them when they arrive. Each request is handled by a single process, ensuring that each request is isolated, and will not affect any other requests.
workerMPM implements a hybrid multi-process, multi-threaded server. Each child process creates a fixed number of server threads, allowing the server to handle a large number of requests with fewer system resources.
eventMPM is based off the
workerMPM, but allows additional requests to be served simultaneously by passing off some processing work to the listener threads, therefore freeing up the worker threads to serve new requests.
A.3.1.2. Windows MPMs
winntMPM is the only one available for Windows systems. It uses a single control process, which launches a single process used to create threads for incoming requests.
A.3.2. Switching the MPM
The server selects the MPM based on the
LoadModule directive found in
JBCS_HOME/httpd/conf.modules.d/00-mpm.conf. By default the
prefork MPM is selected, as seen in the following line:
# prefork MPM: Implements a non-threaded, pre-forking web server # See: http://httpd.apache.org/docs/2.4/mod/prefork.html LoadModule mpm_prefork_module modules/mod_mpm_prefork.so
To adjust the MPM perform the following steps.
JBCS_HOME/httpd/conf.modules.d/00-mpm.confto comment out the
LoadModuledirective for the
preforkMPM. The following XML displays this MPM successfully commented.
# prefork MPM: Implements a non-threaded, pre-forking web server # See: http://httpd.apache.org/docs/2.4/mod/prefork.html #LoadModule mpm_prefork_module modules/mod_mpm_prefork.so
In the same file, uncomment the
LoadModuledirective for the desired MPM. These lines are found immediately below the
preforkMPM. For instance, to load the
workerMPM the following would be used.
# worker MPM: Multi-Processing Module implementing a hybrid # multi-threaded multi-process web server # See: http://httpd.apache.org/docs/2.4/mod/worker.html LoadModule mpm_worker_module modules/mod_mpm_worker.so
Confirm the MPM has been configured correctly by running
apachectl -V. This command displays the current MPM.
$ sbin/apachectl -V [...] Server MPM: worker [...]