Apache HTTP Server Connectors and Load Balancing Guide
For Use with Red Hat JBoss Core Services 2.4.37
Abstract
Providing feedback on Red Hat documentation
We appreciate your feedback on our technical content and encourage you to tell us what you think. If you’d like to add comments, provide insights, correct a typo, or even ask a question, you can do so directly in the documentation.
You must have a Red Hat account and be logged in to the customer portal.
To submit documentation feedback from the customer portal, do the following:
- Select the Multi-page HTML format.
- Click the Feedback button at the top-right of the document.
- Highlight the section of text where you want to provide feedback.
- Click the Add Feedback dialog next to your highlighted text.
- Enter your feedback in the text box on the right of the page and then click Submit.
We automatically create a tracking issue each time you submit feedback. Open the link that is displayed after you click Submit and start watching the issue or add more comments.
Thank you for the valuable feedback.
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Chapter 1. HTTP connector modules
Red Hat JBoss Core Services includes two different HTTP connector modules that you can use to load-balance HTTP requests to a set of back-end servlet containers:
-
The Apache Tomcat connector (
mod_jk
) supports the load balancing of HTTP requests to a set of servlet containers, while maintaining sticky sessions and communicating over the Apache JServ Protocol (AJP). -
The JBoss HTTP connector (
mod_cluster
) is a more advanced load balancer thanmod_jk
. Themod_cluster
module provides all the functionality ofmod_jk
and additional features such as real-time load-balancing calculations, application life-cycle control, automatic proxy discovery, and multiple protocol support.
The Apache HTTP Server Connectors and Load Balancing Guide describes how to install and configure the mod_proxy
and mod_cluster
connectors. This guide also provides information about Online Certificate Status Protocol (OCSP) and includes a set of working examples for basic load balancing and Kerberos authentication using mod_auth_kerb.
Most file and directory paths shown in this guide are for an archive installation of JBoss Core Services on Red Hat Enterprise Linux. For other platforms, use the correct paths for your respective installation, as specified in the JBoss Core Services Installation Guide.
Red Hat Enterprise Linux 6 is no longer supported and subsequently was removed from the documentation.
Chapter 2. Load balancing with the Apache Tomcat connector (mod_jk
)
The Apache Tomcat Connector, mod_jk
, is a plug-in that allows the Apache HTTP Server to forward web requests to a back-end servlet container. The mod_jk
module also allows the Apache HTTP Server to load-balance requests to a set of servlet containers, while maintaining sticky sessions.
2.1. Mod_jk
installation
The mod_jk
module is included in the Apache HTTP Server part of a JBoss Core Services installation.
You can follow the procedures in the Red Hat JBoss Core Services Apache HTTP Server Installation Guide to download and install the Apache HTTP Server for your operating system.
Additional resources
2.2. Apache HTTP Server load-balancing configuration when using mod_jk
You can configure the Apache HTTP Server to use mod_jk
to load-balance requests to a set of servlet containers. This setup includes the configuration of back-end worker nodes.
Red Hat JBoss Core Services provides example configuration files for mod_jk
in the JBCS_HOME/httpd/conf.d/
directory. These example configuration files are named mod_jk.conf.sample
, workers.properties.sample
, and uriworkermap.properties.sample
. To use these examples instead of creating your own configuration files, you can remove the .sample
extension, and modify the file content as needed.
You can also use the Load Balancer Configuration tool on the Red Hat Customer Portal to generate optimal configuration templates quickly for mod_jk
and Tomcat worker nodes.
When you use the Load Balancer Configuration tool for Apache HTTP Server 2.4.37, ensure that you select 2.4.x
as the Apache version, and select Tomcat
as the back-end configuration.
When the Apache HTTP Server (httpd
) is installed on Red Hat Enterprise Linux 8, the base operating system modules are located in the /usr/lib64/httpd/modules
directory. The Red Hat JBoss Core Services modules are currently located in the /opt/rh/jbcs/root/usr/lib64/httpd/modules
directory.
The Red Hat JBoss Core Services modules include mod_jk
, mod_cluster
, mod_rt
, and mod_bmx
. These modules follow all Red Hat JBoss Core Services rules for naming, directories, and prefixes. If you want to use these modules, create or modify a configuration file to add the LoadModule
command. For example:
LoadModule jk_module /opt/rh/jbcs/root/usr/lib64/httpd/modules/mod_jk.so
Alternatively, you can include the directory of the installed Red Hat JBoss Core Services modules in the JBCS_HOME/httpd/conf.d
directory.
Consider the following differences between the httpd
implementations that are provided by JBoss Core Services and Red Hat Enterprise Linux:
-
You can install JBoss Core Services
httpd
from an archive file or RPM package. -
You can also install JBoss Core Services
httpd
in a Windows Server environment. -
JBoss Core Services
httpd
does not provide or support themod_php
module. Red Hat Enterprise Linuxhttpd
supports themod_php
module. -
JBoss Core Services
httpd
provides themod_jk
andmod_cluster
load balancer modules. Red Hat Enterprise Linuxhttpd
does not provide themod_jk
andmod_cluster
modules.
The use case for JBoss Core Services httpd
is to connect to the back end with a proxy. You can use mod_jk
, mod_proxy_cluster
, or mod_proxy
as a proxy. There is no difference between these modules in the httpd
implementations that are provided by Red Hat JBoss Core Services and Red Hat Enterprise Linux.
Since the 2.4.37 Service Pack 10 release, Red Hat JBoss Core Services does not support the tunneling of non-upgraded connections to a back-end WebSockets server. This means that when you are configuring the ProxyPass
directive for the mod_proxy_wstunnel
module, you must ensure that the upgrade parameter is not set to NONE
. For more information about mod_proxy_wstunnel
, see the Apache documentation.
2.3. Configuring the Apache HTTP Server to load mod_jk
You can configure the Apache HTTP Server to load mod_jk
, by specifying configuration settings in the mod_jk.conf
file.
You can also perform the following optional configuration steps:
-
In addition to the
JkMount
directive, you can use theJkMountFile
directive to specify the configuration file for a mount point. The configuration file contains multiple URL mappings for Tomcat forwarding. - You can configure the Apache HTTP Server that is functioning as the load balancer to log details of each worker node that handles a request. This can be useful if you need to troubleshoot your load balancer.
Procedure
-
Go to the
JBCS_HOME/httpd/conf.d
directory. Create a new file named
mod_jk.conf
and enter the following configuration details:# Load mod_jk module # Specify the filename of the mod_jk lib LoadModule jk_module modules/mod_jk.so # Where to find workers.properties JkWorkersFile conf.d/workers.properties # Where to put jk logs JkLogFile logs/mod_jk.log # Set the jk log level [debug/error/info] JkLogLevel info # Select the log format JkLogStampFormat "[%a %b %d %H:%M:%S %Y]" # JkOptions indicates to send SSL KEY SIZE JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories # JkRequestLogFormat JkRequestLogFormat "%w %V %T" # Mount your applications JkMount /application/* loadbalancer # Add shared memory. # This directive is present with 1.2.10 and # later versions of mod_jk, and is needed for # for load balancing to work properly JkShmFile logs/jk.shm # Add jkstatus for managing runtime data <Location /jkstatus/> JkMount status Require ip 127.0.0.1 </Location>
ImportantEnsure that the
LoadModule
directive references themod_jk
native binary that you have installed.NoteThe
JkMount
directive specifies the URLs that the Apache HTTP Server can forward to themod_jk
module. Based on the configuration for theJkMount
directive,mod_jk
forwards the received URL to the correct servlet containers.To enable the Apache HTTP Server to serve static content (or PHP content) directly, and only use the load balancer for Java applications, the preceding configuration example specifies that the Apache HTTP Server sends only requests with the URL
/application/*
to themod_jk
load balancer.Alternatively, you can configure the Apache HTTP Server to forward all URLs to
mod_jk
by specifying/*
in theJkMount
directive.Optional: To use the
JkMountFile
directive to specify the configuration file for a mount point, perform the following steps:-
Go to the
JBCS_HOME/httpd/conf.d/
directory. -
Create a file named
uriworkermap.properties
. Specify the URL that you want to forward and the worker name.
For example:
# Simple worker configuration file # Mount the Servlet context to the ajp13 worker /application=loadbalancer /application/*=loadbalancer
NoteThe required syntax is in the format:
/URL=WORKER_NAME
The preceding example configures
mod_jk
to forward requests for/application
to the JBoss Web Server Tomcat back end.In the
JBCS_HOME/httpd/conf.d/mod_jk.conf
file, enter the following directive:# Use external file for mount points. # It will be checked for updates each 60 seconds. # The format of the file is: /url=worker # /examples/*=loadbalancer JkMountFile conf.d/uriworkermap.properties
-
Go to the
Optional: To enable Apache HTTP Server logging, perform either of the following steps:
-
Include
%w
in yourJkRequestLogFormat
directive, as shown in the preceding step aboutmod_jk.conf
settings. -
Log the name of the
mod_jk
worker that you want to use, by including%{JK_WORKER_NAME}n
in your Apache HTTP ServerLogFormat
(s).
-
Include
Additional resources
2.4. Configuring worker nodes in mod_jk
You can configure multiple worker nodes to handle the requests that the Apache HTTP Server forwards to the servlet containers.
The example in this procedure shows how to define two mod_jk
worker nodes in a weighted round-robin configuration that uses sticky sessions between two servlet containers.
Prerequisites
-
You are familiar with the format of the
workers.properties
directives. -
You have configured the Apache HTTP Server to load
mod_jk
.
Procedure
-
Go to the
JBCS_HOME/httpd/conf.d/
directory. -
Create a file named
workers.properties
. Enter the following configuration details:
# Define list of workers that will be used # for mapping requests worker.list=loadbalancer,status # Define Node1 # modify the host as your host IP or DNS name. worker.node1.port=8009 worker.node1.host=node1.mydomain.com worker.node1.type=ajp13 worker.node1.ping_mode=A worker.node1.lbfactor=1 worker.node1.secret=<YourSecret> # Define Node2 # modify the host as your host IP or DNS name. worker.node2.port=8009 worker.node2.host=node2.mydomain.com worker.node2.type=ajp13 worker.node2.ping_mode=A worker.node2.lbfactor=1 worker.node1.secret=<YourSecret> # Load-balancing behavior worker.loadbalancer.type=lb worker.loadbalancer.balance_workers=node1,node2 worker.loadbalancer.sticky_session=1 # Status worker for managing load balancer worker.status.type=status
NoteIn the preceding example, ensure that you replace
host
,port
, andsecret
settings with values that are relevant for your environment.ImportantThe
secret
property is required when using the Tomcat AJP Connector. You can specify thesecret
property for a worker node or a load balancer in theworkers.properties
file. For example:worker.<WORKER_NAME>.secret=<YOUR_AJP_SECRET>
In the preceding example, replace
<WORKER_NAME>
and<YOUR_AJP_SECRET>
with values that are relevant for your environment.
2.5. Configuring Tomcat to work with mod_jk
Tomcat is configured to receive Apache JServ Protocol (AJP) traffic from mod_jk
by default. However, before you can use a worker node with mod_jk
, you must perform the following additional configuration steps:
- Configure the AJP connector. The AJP connector is not configured by default.
-
Configure a unique value for the
jvmRoute
attribute in the Engine of each worker node. -
Specify the
secret
property for a worker node or a load balancer. Thesecret
property is required when you use the Tomcat AJP connector.
Procedure
To configure the AJP connector, perform the following steps:
-
Open the
JBCS_HOME/tomcat<VERSION>/conf/server.xml
file. In the
server.xml
file, enter the following line:<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
-
Open the
To configure a unique value for the
jvmRoute
attribute in the Engine of each worker node, enter the following details:<Engine name="Catalina" jvmRoute="node1" >
ImportantEnsure that the
jvmRoute
attribute value matches the worker name that is specified in theworkers.properties
file.To specify the
secret
property for a worker node or a load balancer, perform the following steps:-
Open the
JBCS_HOME/httpd/conf.d/workers.properties
file. In the
workers.properties
file, ensure that thesecret
property is specified in the following format:worker.<WORKER_NAME>.secret=<YOUR_AJP_SECRET>`
NoteEnsure that you replace
<WORKER_NAME>
and<YOUR_AJP_SECRET>
with values that are relevant for your environment.NoteIf you set a
secret
on a load balancer by using theProxyPass
directive, all of its members inherit thissecret
. For example:<Proxy balancer://mycluster>` BalancerMember ajp://node1:8009 route=node1 secret=YOUR_AJP_SECRET BalancerMember ajp://node2:8009 route=node2 secret=YOUR_AJP_SECRET </Proxy> ProxyPass /example/ balancer://mycluster/example/ stickysession=JSESSIONID|jsessionid
-
Open the
Chapter 3. Load balancing with the JBoss HTTP connector (mod_cluster
)
The mod_cluster
connector is a reduced configuration, intelligent load-balancing solution for JBoss EAP and Apache HTTP Server Tomcat. The mod_cluster
module is based on technology originally developed by the JBoss mod_cluster
community project.
3.1. JBoss HTTP connector (mod_cluster
)
The mod_cluster
module load-balances HTTP requests to JBoss EAP and Apache HTTP Server Tomcat worker nodes. The mod_cluster
module uses the Apache HTTP Server as the proxy server.
Key features of mod_cluster
The mod_cluster
connector has several advantages over the mod_jk
connector:
-
When the
mod_cluster
module is enabled, themod_cluster
Management Protocol (MCMP) is an additional connection between the Tomcat servers and the Apache HTTP Server. The Tomcat servers use MCMP to transmit server-side load figures and lifecycle events back to the Apache HTTP Server, by using a custom set of HTTP methods. -
Dynamic configuration of Apache HTTP Server with
mod_cluster
allows Tomcat servers that havemod_cluster
listeners to join the load-balancing arrangement without the need for manual configuration. - Tomcat servers perform the load calculations rather than rely on the Apache HTTP Server. This makes load-balancing metrics more accurate than other connectors.
-
The
mod_cluster
connector provides fine-grained application lifecycle control. Each Tomcat server forwards web application context lifecycle events to the Apache HTTP Server. These lifecycle events include informing the Apache HTTP Server to start or stop routing requests for a specific context. This prevents end users from seeing HTTP errors because of unavailable resources. -
You can use Apache JServ Protocol (AJP), Hypertext Transfer Protocol (HTTP), or Hypertext Transfer Protocol Secure (HTTPS) transports with
mod_cluster
.
Mod_cluster
components
On the proxy server, mod_cluster
consists of four Apache modules:
Component | Description |
---|---|
| The Shared Memory Manager module shares real-time worker node information with multiple Apache HTTP Server processes. |
| The Cluster Manager module receives and acknowledges messages from worker nodes, including node registrations, node load data, and node application life cycle events. |
| The Proxy Balancer Module handles request routing to cluster nodes. The Proxy Balancer selects the appropriate destination node based on 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). |
| The Proxy Advertisement Module 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 server is listening for responses from worker nodes that want to join the load-balancing cluster. |
Additional resources
3.2. Mod_cluster
character limits
The mod_cluster
module uses shared memory to keep the nodes description. The shared memory is created at the startup of Apache HTTP Server, and the structure of each item is fixed.
When you define proxy server and worker node properties, ensure that you adhere to the following character limits:
Property | Maximum character limit | Description |
---|---|---|
Alias length | 100 characters |
Alias corresponds to the network name of the respective virtual host; the name is defined in the |
Context length | 40 characters |
For example, if |
Balancer name length | 40 characters |
This is the balancer property in |
| 80 characters |
|
Domain name length | 20 characters |
This is the domain property in |
Hostname length for a node | 64 characters |
This is hostname address in the |
Port length for a node | 7 characters |
This is the port property in the |
Scheme length for a node | 6 characters |
This is the protocol of the connector. Possible values are |
Cookie name length | 30 characters |
This is the header cookie name for the session ID. The default value is |
Path name length | 30 characters |
This is the parameter name for the session ID. The default value is |
Session ID length | 120 characters |
A session ID is in the following type of format: |
3.3. Mod_cluster
installation
The mod_cluster
module is included in the Apache HTTP Server part of a JBoss Core Services installation.
You can follow the procedures in the Red Hat JBoss Core Services Apache HTTP Server Installation Guide to download and install the Apache HTTP Server for your operating system.
Additional resources
3.4. Apache HTTP Server load-balancing configuration when using mod_cluster
In Apache HTTP Server 2.1 and higher, mod_cluster
is configured correctly for Apache HTTP Server by default. For more information about setting a custom configuration, see Configuring a basic proxy server.
You can also use the Load Balancer Configuration tool on the Red Hat Customer Portal to generate optimal configuration templates quickly for mod_cluster
and Tomcat worker nodes.
When you use the Load Balancer Configuration tool for Apache HTTP Server 2.4.37, ensure that you select 2.4.x
as the Apache version, and select Tomcat
as the back-end configuration.
When the Apache HTTP Server (httpd
) is installed on Red Hat Enterprise Linux 8, the base operating system modules are located in the /usr/lib64/httpd/modules
directory. The Red Hat JBoss Core Services modules are currently located in the /opt/rh/jbcs/root/usr/lib64/httpd/modules
directory.
The Red Hat JBoss Core Services modules include mod_jk
, mod_cluster
, mod_rt
, and mod_bmx
. These modules follow all Red Hat JBoss Core Services rules for naming, directories, and prefixes. If you want to use these modules, create or modify a configuration file to add the LoadModule
command. For example:
LoadModule jk_module /opt/rh/jbcs/root/usr/lib64/httpd/modules/mod_jk.so
Alternatively, you can include the directory of the installed Red Hat JBoss Core Services modules in the JBCS_HOME/httpd/conf.d
directory.
-
When you want to use the
mod_proxy_cluster
module, you must enable themod_proxy
module and disable themod_proxy_balancer
module. -
If you want
mod_proxy_cluster
to use the Apache JServ Protocol (AJP), you must enable theproxy_ajp_module
. -
Use AJPSecret
your_secret
to provide the secret for the AJP backend. Ifyour_secret
does not correspond to the value configured in the back end, the back end sends a503
error response for any request that is sent through the proxy.
Since the 2.4.37 Service Pack 10 release, Red Hat JBoss Core Services does not support the tunneling of non-upgraded connections to a backend websockets server. This means that when you are configuring the ProxyPass directive for the mod_proxy_wstunnel module, you must ensure that the upgrade parameter is not set to NONE. For more information about mod_proxy_wstunnel, see the Apache documentation.
Additional resources
3.5. Configuring a basic proxy server
You can configure the Apache HTTP Server to function as a proxy server that forwards requests and responses between web clients and back-end web servers. You must configure a proxy server listener to receive connection requests and responses from the back-end worker nodes. When you want to configure a load-balancing proxy server that uses mod_cluster
, you must also configure a virtual host for the management channel.
Prerequisites
-
You have installed the Apache HTTP Server and configured the
mod_cluster
modules for your installation. For more information, see the Red Hat JBoss Core Services Apache HTTP Server Installation Guide. - The port that you specify for the proxy server listener must be open for incoming TCP connections.
Procedure
Open the
mod_cluster
configuration file.NoteThe
mod_cluster
configuration file is typically located in theJBCS_HOME/httpd/conf.d/mod_cluster.conf
directory.To create a
Listen
directive for the proxy server, enter the following line in themod_cluster.conf
file:Listen IP_ADDRESS:PORT_NUMBER
NoteIn the preceding example, replace
IP_ADDRESS
with the address of the server network interface that the proxy server uses to communicate with the worker nodes, and replacePORT_NUMBER
with the port that the proxy server listens on.Ensure that the port is open for incoming TCP connections.
To create a virtual host, enter the following details in the
mod_cluster.conf
file:<VirtualHost IP_ADDRESS:PORT_NUMBER> <Directory /> Require ip IP_ADDRESS </Directory> KeepAliveTimeout 60 MaxKeepAliveRequests 0 ManagerBalancerName mycluster AdvertiseFrequency 5 EnableMCPMReceive On </VirtualHost>
NoteIn the preceding example, replace
IP_ADDRESS
andPORT_NUMBER
with the address of the server network interface and port number that you have specified for theListen
directive.This address and port combination is only used for
mod_cluster
management messages. This address and port combination is not used for general traffic.
For more information about configuring mod_jk
and starting the Apache HTTP Server service, see the Red Hat JBoss Core Services Apache HTTP Server Installation Guide.
Additional resources
3.5.1. Disabling server advertisement
The proxy server uses UDP multicast to advertise itself. The AdvertiseFrequency
directive instructs the server to send server advertisement messages every 10 seconds by default. Server advertisement messages contain the IP_ADDRESS
and PORT_NUMBER
that you specify in the VirtualHost
definition. Worker nodes that are configured to respond to server advertisements use this information to register themselves with the proxy server. If you want to prevent worker nodes from registering with the proxy server, you can optionally disable server advertisement.
When UDP multicast is available between the proxy server and the worker nodes, server advertisement adds worker nodes without requiring further configuration on the proxy server. Server advertisement requires only minimal configuration on the worker nodes.
Prerequisites
- You have configured a basic proxy server.
Procedure
Open the
mod_cluster
configuration file.NoteThe
mod_cluster
configuration file is typically located in theJBCS_HOME/httpd/conf.d/mod_cluster.conf
directory.Add the following directive to the
VirtualHost
definition:ServerAdvertise Off
NoteIf server advertisements are disabled, or UDP multicast is not available on the network between the proxy server and the worker nodes, you can configure worker nodes with a static list of proxy servers. In either case, you do not need to configure the proxy server with a list of worker nodes.
Additional resources
3.5.2. Logging worker node details
When you configure a load-balancing proxy server that uses mod_cluster
, you can optionally configure the Apache HTTP Server to log details of each worker node that handles a request. Logging worker node details can be useful if you need to troubleshoot your load balancer.
Prerequisites
- You have configured a basic proxy server.
Procedure
Open the
mod_cluster
configuration file.NoteThe
mod_cluster
configuration file is typically located in theJBCS_HOME/httpd/conf.d/mod_cluster.conf
directory.Add the following details to your Apache HTTP Server
LogFormat
directive(s):%{BALANCER_NAME}e :: The name of the balancer that served the request. %{BALANCER_WORKER_NAME}e :: The name of the worker node that served the request.
Additional resources
3.6. Configuring a Tomcat worker node in mod_cluster
When you use mod_cluster
, you can configure a Tomcat worker node as an Apache HTTP Server Tomcat service that operates in non-clustered mode only. In this situation, only one load metric can be used at a time when calculating the load-balance factor.
Apache HTTP Server Tomcat worker nodes support only a subset of mod_cluster
functionality. Full mod_cluster
functionality is available with JBoss EAP.
Prerequisites
- You have installed a supported instance of Apache HTTP Server.
-
You are familiar with the
mod_cluster
proxy and proxy discovery configuration parameters.
Procedure
To add a listener to Tomcat, add the following
Listener
element beneath the otherListener
elements in theJWS_HOME/tomcat<VERSION>/conf/server.xml
file:<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true" stickySession="true" stickySessionForce="false" stickySessionRemove="true" />
To give the worker node a unique identity, edit the
JWS_HOME/tomcat<VERSION>/conf/server.xml
file, to add thejvmRoute
attribute and value to theEngine
element:<Engine name="Catalina" defaultHost="localhost" jvmRoute="worker01">
To configure
STATUS MCMP
message frequency, modify theorg.jboss.modcluster.container.catalina.status-frequency
Java system property.For example:
-Dorg.jboss.modcluster.container.catalina.status-frequency=6
NoteTomcat worker nodes periodically send status messages that contain their current load status to the Apache HTTP Server balancer. The default frequency of these messages is 10 seconds. If you have hundreds of worker nodes, the
STATUS MCMP
messages can increase traffic congestion on your Apache HTTP Server network.You can configure the
MCMP
message frequency by modifying theorg.jboss.modcluster.container.catalina.status-frequency
Java system property. By default, the property accepts values that are specified in seconds multiplied by 10. For example, setting the property to1
means 10 seconds. In the preceding example, the property is set to6
, which means 60 seconds.Optional: To configure the firewall for proxy server advertisements, complete either of the following steps to open port
23364
for UDP connections on the worker node’s firewall:For Red Hat Enterprise Linux 7:
firewall-cmd --permanent --zone=public --add-port=23364/udp
For Microsoft Windows using PowerShell
Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=in action=allow protocol=UDP localport=23364"' Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=out action=allow protocol=UDP localport=23364"'
NoteWhen a proxy server uses
mod_cluster
, the proxy server can use UDP multicast to advertise itself. Most operating system firewalls block the server advertisement feature by default. To enable server advertisement and receive these multicast messages, you can open port23364
for UDP connections on the worker node’s firewall, as shown in the preceding examples.
Red Hat Enterprise Linux 6 is no longer supported and subsequently was removed from the documentation.
3.7. Configuring a worker node to operate with a static list of proxy servers
Server advertisement allows worker nodes to discover and register themselves with proxy servers dynamically. If UDP multicast is not available or server advertisement is disabled, you must configure Apache HTTP Server worker nodes with a static list of proxy server addresses and ports.
Prerequisites
- You have configured an Apache HTTP Server worker node.
- You are familiar with the proxy configuration parameters for Tomcat.
Procedure
-
Open the
JWS_HOME/tomcat<VERSION>/conf/server.xml
file. To define a
mod_cluster
listener and disable dynamic proxy discovery, add or change theListener
element forModClusterListener
.For example:
<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="false" stickySession="true" stickySessionForce="false" stickySessionRemove="true"/>
NoteEnsure that you set the
advertise
property tofalse
.To create a static proxy server list, update the
proxyList
property by adding a comma-separated list of proxies in the following format:IP_ADDRESS:PORT,IP_ADDRESS:PORT
For example:
<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="false" stickySession="true" stickySessionForce="false" stickySessionRemove="true" proxyList="10.33.144.3:6666,10.33.144.1:6666"/>
Chapter 4. Securing connections by using OCSP
Online Certificate Status Protocol (OCSP) is a technology that allows web browsers and web servers to communicate over a secured connection. The encrypted data is sent from one side and decrypted by the other side before processing. The web browser and the web server both encrypt and decrypt the data.
4.1. Online Certificate Status Protocol
When a web browser and a web server communicate over a secured connection, the server presents a set of credentials in the form of a certificate. The browser then validates the certificate and sends a request for certificate status information. The server responds with a certificate status of current, expired, or unknown.
The certificate contains the following types of information:
- Syntax for communication
- Control information such as start time, end time, and address information to access an Online Certificate Status Protocol (OCSP) responder.
The web server uses an OCSP responder to check the certificate status. You can configure the web server to use the OCSP responder that is listed in the certificate or another OCSP responder. OCSP allows a grace period for expired certificates, which allows access to a server for a limited time before renewing the certificate.
OCSP overcomes limitations of the older Certificate Revocation List (CRL) method.
Additional resources
4.2. Configuring the Apache HTTP Server for SSL connections
You can configure the Apache HTTP Server to support SSL connections, by installing the mod_ssl
package and specifying configuration settings in the ssl.conf
file.
Prerequisites
- You have generated an SSL certificate and private key.
- You know the location of the SSL certificate and private key file.
- You have obtained the Common Name (CN) that is associated with the SSL certificate.
Procedure
To install
mod_ssl
, enter the following command:# yum install jbcs-httpd24-mod_ssl
To specify SSL configuration settings:
-
Open the
JBCS_HOME/httpd/conf.d/ssl.conf
file. Enter details for the
ServerName
,SSLCertificateFile
, andSSLCertificateKeyFile
.For example:
<VirtualHost _default_:443> ServerName www.example.com:443 SSLCertificateFile /opt/rh/jbcs-httpd24/root/etc/pki/tls/certs/localhost.crt SSLCertificateKeyFile /opt/rh/jbcs-httpd24/root/etc/pki/tls/private/localhost.key
Note-
The
ServerName
must match the Common Name (CN) that is associated with the SSL certificate. If theServerName
does not match the CN, client browsers display domain name mismatch errors. -
The
SSLCertificateFile
specifies the path to the SSL certificate file. -
The
SSLCertificateKeyFile
specifies the path to the private key file that is associated with the SSL certificate.
-
The
-
Open the
-
Verify that the
Listen
directive matches the hostname or IP address for thehttpd
service for your deployment. To restart the Apache HTTP Server, enter the following command:
# service jbcs-httpd24-httpd restart
4.3. Using OCSP with the Apache HTTP Server
You can use the Online Certificate Status Protocol (OCSP) for secure connections with the Apache HTTP Server.
Prerequisites
Procedure
Configure a certificate authority.
NoteEnsure that your CA can issue OCSP certificates. The CA must be able to append the following attributes to the certificate:
[ usr_cert ] ... authorityInfoAccess=OCSP;URI:http://<HOST>:<PORT> ... [ v3_OCSP ] basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment extendedKeyUsage = OCSP Signing
In the preceding example, replace
HOST
andPORT
with the details of the OCSP responder that you will configure.- Configure an OCSP responder.
Additional resources
4.4. Configuring the Apache HTTP Server to validate OCSP certificates
You can configure the Apache HTTP Server to validate OCSP certificates, by defining OCSP settings in the ssl_conf
file.
Prerequisites
- You have configured a Certificate Authority (CA).
- You have configured an OCSP Responder.
Procedure
-
Open the
JBCS_HOME/httpd/conf.d/ssl.conf
file. Specify the appropriate OCSP configuration details for your deployment.
For example:
# Require valid client certificates (mutual auth) SSLVerifyClient require SSLVerifyDepth 3 # Enable OCSP SSLOCSPEnable on SSLOCSPDefaultResponder http://<HOST>:<PORT> SSLOCSPOverrideResponder on
NoteThe preceding example shows how to enable OCSP validation of client certificates. In the preceding example, replace
<HOST>
and<PORT>
with the IP address and port of the default OCSP Responder.
4.5. Verifying the OCSP configuration for the Apache HTTP Server
You can use the OpenSSL command-line tool to verify the OCSP configuration for the Apache HTTP Server.
Procedure
On the command line, enter the
openssl
command in the following format:# openssl ocsp -issuer cacert.crt -cert client.cert -url http://HOST:PORT -CA ocsp_ca.cert -VAfile ocsp.cert
In the preceding command, ensure that you specify the following details:
-
Use the
-issuer
option to specify the CA certificate. -
Use the
-cert
option to specify the client certificate that you want to verify. -
Use the
-url
option to specify the HTTP server validating Certificate (OCSP). -
Use the
-CA
option to specify the is the CA certificate for verifying the Apache HTTP Server server certificate. -
Use the
-VAfile
option to specify the OCSP responder certificate.
-
Use the
Chapter 5. Configuration example for load-balancing with mod_cluster
You can configure JBoss Core Services to use the mod_cluster
connector for load-balancing in a Red Hat Enterprise Linux system.
When you want to configure a load-balancing solution that uses mod_cluster
, you must perform the following tasks:
5.1. Setting up JBoss Core Services as a proxy server
When you configure JBoss Core Services to use mod_cluster
, you must set up JBoss Core Services as a proxy server by specifying configuration details in the mod_cluster.conf
file.
Procedure
-
Go to the
JBCS_HOME/httpd/conf.d/
directory. -
Create a file named
mod_cluster.conf
. Enter the following configuration details:
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so LoadModule cluster_slotmem_module modules/mod_cluster_slotmem.so LoadModule manager_module modules/mod_manager.so LoadModule advertise_module modules/mod_advertise.so MemManagerFile cache/mod_cluster <IfModule manager_module> Listen 6666 <VirtualHost *:6666> <Directory /> Require ip 127.0.0.1 </Directory> ServerAdvertise on EnableMCPMReceive <Location /mod_cluster_manager> SetHandler mod_cluster-manager Require ip 127.0.0.1 </Location> </VirtualHost> </IfModule>
NoteThe preceding example shows how to set up JBoss Core Services as a proxy server that is listening on
localhost
.
5.2. Configuring a Tomcat worker node
When you configure JBoss Core Services to use mod_cluster
, you must configure a Tomcat worker node by adding a Listener
element to the server.xml
file.
Prerequisites
Procedure
-
Open the
JWS_HOME/tomcat<VERSION>/conf/server.xml
file. Add the following
Listener
element:<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>
5.3. Defining iptables firewall rules example
When you configure JBoss Core Services to use mod_cluster
, you must define firewall rules by using iptables
.
Prerequisites
- You have configured a Tomcat worker node.
Procedure
Use
iptables
to define a set of firewall rules.For example:
/sbin/iptables -I INPUT 5 -p udp -d 224.0.1.0/24 -j ACCEPT -m comment --comment "mod_cluster traffic" /sbin/iptables -I INPUT 6 -p udp -d 224.0.0.0/4 -j ACCEPT -m comment --comment "JBoss Cluster traffic" /sbin/iptables -I INPUT 9 -p udp -s 192.168.1.0/24 -j ACCEPT -m comment --comment "cluster subnet for inter-node communication" /sbin/iptables -I INPUT 10 -p tcp -s 192.168.1.0/24 -j ACCEPT -m comment --comment "cluster subnet for inter-node communication" /etc/init.d/iptables save
NoteThe preceding example shows to define firewall rules for a cluster node on the
192.168.1.0/24
subnet.
Chapter 6. Configuration example for Kerberos authentication with mod_auth_kerb
You can configure Kerberos authentication with the JBoss Core Services Apache HTTP Server and the mod_auth_kerb
module on Red Hat Enterprise Linux.
When you want to configure Kerberos authentication, you must perform the following tasks:
6.1. Prerequisites
-
You have installed the
curl
command-line utility with Generic Security Services (GSS)-negotiated support. - You have configured and run a Kerberos or LDAP server, such as ApacheDS, on the same host as JBoss Core Services.
If you are using an LDAP server, you have created LDAP users called
krbtgt
,ldap
,HTTP
, and a test LDAP user calledhnelson
.To create the
krbtgt
user, enter the following details:dn: uid=krbtgt,ou=Users,dc=example,dc=com objectClass: top objectClass: person objectClass: inetOrgPerson objectClass: krb5principal objectClass: krb5kdcentry cn: KDC Service sn: Service uid: krbtgt userPassword: secret krb5PrincipalName: krbtgt/EXAMPLE.COM@EXAMPLE.COM krb5KeyVersionNumber: 0
To create the
ldap
user, enter the following details:dn: uid=ldap,ou=Users,dc=example,dc=com objectClass: top objectClass: person objectClass: inetOrgPerson objectClass: krb5principal objectClass: krb5kdcentry cn: LDAP sn: Service uid: ldap userPassword: randall krb5PrincipalName: ldap/localhost@EXAMPLE.COM krb5KeyVersionNumber: 0
To create the
HTTP
user, enter the following details:dn: uid=HTTP,ou=Users,dc=example,dc=com objectClass: top objectClass: person objectClass: inetOrgPerson objectClass: krb5principal objectClass: krb5kdcentry cn: HTTP sn: Service uid: HTTP userPassword: secretpwd krb5PrincipalName: HTTP/localhost@EXAMPLE.COM krb5KeyVersionNumber: 0
To create the test user,
hnelson
, enter the following details:dn: uid=hnelson,ou=Users,dc=example,dc=com objectClass: top objectClass: person objectClass: inetOrgPerson objectClass: krb5principal objectClass: krb5kdcentry cn: Horatio Nelson sn: Nelson uid: hnelson userPassword: secret krb5PrincipalName: hnelson@EXAMPLE.COM krb5KeyVersionNumber: 0
6.2. Configuring the Kerberos client
When you configure Kerberos authentication, you must configure the Kerberos client by performing the following steps:
-
Specify configuration settings in the
krb5.conf
file. -
Create a key tab in the
JBCS_HOME/httpd/conf
file. - Assign permissions to the key tab.
-
Ensure that
localhost
is included in the/etc/hosts
file.
Prerequisites
- You are compliant with all prerequisites for configuring Kerberos authentication.
Procedure
To specify configuration settings in the
krb5.conf
file:-
Go to the
/etc
directory. -
Create a file named
krb5.conf
. Enter the following configuration details:
[logging] default = FILE:/var/log/krb5libs.log kdc = FILE:/var/log/krb5kdc.log admin_server = FILE:/var/log/kadmind.log [libdefaults] default_realm = EXAMPLE.COM default_tgs_enctypes = des-cbc-md5,des3-cbc-sha1-kd default_tkt_enctypes = des-cbc-md5,des3-cbc-sha1-kd dns_lookup_realm = false dns_lookup_kdc = false allow_weak_crypto = yes ticket_lifetime = 24h renew_lifetime = 7d forwardable = yes [realms] EXAMPLE.COM = { kdc = localhost:60088 admin_server = localhost:60088 } [domain_realm] .example.com = EXAMPLE.COM example.com = EXAMPLE.COM
-
Go to the
To create a key tab:
-
Open the
JBCS_HOME/httpd/conf
file. Enter the following details:
# ktutil ktutil: addent -password -p HTTP/localhost@EXAMPLE.COM -k 0 -e des-cbc-md5 Password for HTTP/localhost@EXAMPLE.COM: secretpwd ktutil: list slot KVNO Principal ---- ---- --------------------------------------------------------------------- 1 0 HTTP/localhost@EXAMPLE.COM ktutil: wkt JBCS_HOME/httpd/conf/krb5.keytab ktutil: quit
ImportantEnvironment variables are not expanded within the
ktutil
prompt. You must substitute the full path for theJBCS_HOME
variable.
-
Open the
To apply the correct group and permissions to the key tab, enter the following commands as the root user:
# chgrp apache JBCS_HOME/httpd/conf/krb5.keytab # chmod 640 JBCS_HOME/httpd/conf/krb5.keytab
Ensure that the following host configuration is included in the
/etc/hosts
file:127.0.0.1 localhost
6.3. Configuring mod_auth_kerb
When you configure Kerberos authentication, you must configure mod_auth_kerb
by specifying settings in the auth_kerb.conf
file.
Prerequisites
- You have configured the Kerberos client.
Procedure
-
Go to the
JBCS_HOME/httpd/conf.d/
directory. -
Create a file named
auth_kerb.conf
. Enter the following configuration details:
# # The mod_auth_kerb module implements Kerberos authentication over HTTP, following the "Negotiate" protocol. # # The LoadModule statement is done in conf.d/10-auth_kerb.conf # LoadModule auth_kerb_module modules/mod_auth_kerb.so <Location /kerberostest> AuthType Kerberos AuthName "Kerberos Login" KrbMethodNegotiate On KrbMethodK5Passwd Off KrbAuthRealms EXAMPLE.COM KrbServiceName HTTP Krb5KeyTab $JBCS_HOME/httpd/krb5.keytab require valid-user </Location>
Environment variables are not expanded within the configuration files. In the preceding example, ensure that you substitute the full path for the JBCS_HOME
variable.
6.4. Testing the Kerberos authentication
When you configure Kerberos authentication, you can use a test page to test the Kerberos authentication.
Prerequisites
-
You have configured
mod_auth_kerb
.
Procedure
To create a test page, perform the following steps:
-
Go to the
JBCS_HOME/httpd/www/html/kerberostest
directory. -
Create a test page named
auth_kerb_page.html
. Enter the following details:
<html> <body> <h1>mod_auth_kerb successfully authenticated!</h1> </body> </html>
-
Go to the
-
Optional: In the
JBCS_HOME/httpd/conf/httpd.conf
file, set the log level to debugging. - Start the Apache HTTP Server. For more information, see the Red Hat JBoss Core Services Apache HTTP Server Installation Guide.
To initiate Kerberos authentication for the test user,
hnelson
, enter the following command:$ kinit hnelson
To view the details for the test user,
hnelson
, enter the following command:$ klist
The
klist
command produces the following type of output:Ticket cache: FILE:/tmp/krb5cc_18602 Default principal: hnelson@EXAMPLE.COM Valid starting Expires Service principal 06/03/13 14:21:13 06/04/13 14:21:13 krbtgt/EXAMPLE.COM@EXAMPLE.COM renew until 06/10/13 14:21:13
Verification
To test Kerberos authentication, enter the following command:
$ curl --negotiate -u : http://localhost/kerberostest/auth_kerb_page.html
If Kerberos authentication is working correctly, the
curl
command produces the following output:<html> <body> <h1>mod_auth_kerb successfully authenticated!</h1> </body> </html>
6.5. Additional resources (or Next steps)
- Kerberos Module for Apache website.
Appendix A. Apache HTTP Server proxy modules
This section contains expanded definitions of the Apache HTTP Server proxy modules that mod_cluster
includes.
A.1. Mod_manager
module and directives
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 for mod_manager
Configurable directives in the <VirtualHost>
element are as follows:
- EnableMCPMReceive
-
Allows the
VirtualHost
to receive the mod_cluster Protocol Message(MCPM)
from nodes. Add oneEnableMCPMReceive
directive to the Apache HTTP Server configuration to allowmod_cluster
to operate correctly.EnableMCPMReceive
must be added in theVirtualHost
configuration at the location whereadvertise
is configured. - MaxMCMPMaxMessSize
-
Defines the maximum size of mod_cluster Management Protocol
(MCMP)
messages. The default value is calculated from otherMax
directives. The minimum value is1024
. - AllowDisplay
-
Toggles the additional display on the
mod_cluster-manager
main page. The default value isoff
, which causes only version information to display on themod_cluster-manager
main page. - AllowCmd
-
Toggles permissions for commands using
mod_cluster-manager
URL. The default value ison
, which allows commands. - ReduceDisplay
-
Toggles the reduction of information displayed on the
mod_cluster-manager
page. Reducing the information allows more nodes to display on the page. The default value isoff
, which allows all the available information to display. - MemManagerFile
-
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
/logs/
. - Maxcontext
-
The maximum number of contexts mod_cluster will use. The default value is
100
. - Maxnode
-
The maximum number of worker nodes mod_cluster will use. The default value is
20
. - Maxhost
-
The maximum number of hosts (aliases) mod_cluster will use. This is also the maximum number of load balancers. The default value is
20
. - Maxsessionid
-
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. - 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 isoff
. - CheckNonce
When set to
on
, session identifiers are checked to ensure that they are unique and have not occurred before. The default ison
.NoteSetting this directive to
off
can 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
element:<Location $LOCATION> SetHandler mod_cluster-manager Require ip 127.0.0.1 </Location>
When accessing the
$LOCATION
defined in theLocation
element in your browser, you will see something like the following. (In this case,$LOCATION
was also defined asmod_cluster-handler
.)
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
.
A.2. Mod_proxy_cluster
module and directives
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
Configurable directives for mod_proxy_cluster
You can also configure the following directives in the <VirtualHost>
element to change the load balancing behavior.
- 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 theProxyPass
directive. -
1
: Do not create balancers. When using this value, you must also define the load balancer name inProxyPass
orProxyPassMatch
. -
2
: Create only the main server. This is the default value forCreateBalancers
.
-
- UseAlias
Defines whether to check that the defined
Alias
corresponds to theServerName
. The following values are valid forUseAlias
:-
0
: Ignore alias information from worker nodes. This is the default value forUseAlias
. -
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 such ashttp://local.com/
, the followingProxyPass
directive converts a local request forhttp://local.com/requested/file1
into a proxy request forhttp://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 thatgif
files should be served locally.ProxyPassMatch ^(/.*\.gif)$ !
A.3. Mod_advertise
module and directives
The Proxy Advertisement Module, mod_advertise
, 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.
The mod_advertise
module must be defined along with the mod_manager
module in the VirtualHost
element. In the following example, the identifier for the mod_advertise
module is advertise_module
:
LoadModule advertise_module modules/mod_advertise.so
Configurable directives for mod_advertise
The mod_advertise
module is configurable by using the following directives:
- ServerAdvertise
Defines how the advertising mechanism is used.
The default value is
Off
. When set toOff
, 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.- AdvertiseGroup
Defines the multicast address to advertise on. The syntax is
AdvertiseGroup ADDRESS:PORT
, whereADDRESS
must correspond toAdvertiseGroupAddress
, andPORT
must correspond toAdvertisePort
in your worker nodes.If your worker node is JBoss EAP-based, and the
-u
switch is used at startup, the defaultAdvertiseGroupAddress
is the value passed via the-u
switch.The default value is
224.0.1.105:23364
. If a port is not specified, the port defaults to23364
.- AdvertiseFrequency
-
The interval (in seconds) between multicast messages advertising the IP address and port. The default value is
10
. - AdvertiseSecurityKey
-
Defines a string that is used to identify
mod_cluster
in Apache HTTP Server. 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 is0.0.0.0:23364
.
A.4. Mod_proxy
module and directives
The mod_proxy
module is a standard Apache HTTP Server module that enables the server to act as a proxy for data transferred over the AJP (Apache JServe Protocol), FTP, CONNECT (for SSL), and HTTP protocols. The mod_proxy
module does not require additional configuration. The identifier for the mod_proxy
module is proxy_module
.
The configurable directives for mod_proxy
, such as ProxyIOBufferSize
, are used to configure the mod_cluster
module.
A.5. Mod_proxy_ajp
module and directives
The mod_proxy_ajp
module is a standard Apache HTTP Server module that provides support for AJP (Apache JServe Protocol) proxying. The mod_proxy
module is also required if you want to use mod_proxy_ajp
. Additionally, the secret
property is required when using the Tomcat AJP Connector. The secret
property can be added to the ProxyPass
settings using the following command:
ProxyPass /example/ ajp://localhost:8009/example/ secret=YOUR_AJP_SECRET
If you set a secret
on a load balancer, all of its members inherit this secret
.
A.6. Mod_cluster_slotmem
module and directives
The mod_cluster_slotmem
module is a shared memory provider for creating and accessing a shared memory segment in which the data sets are organized in "slots".
The mod_cluster_slotmem
module does not require any configuration directives.
Appendix B. Workers.properties
file
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.
B.1. Workers.properties
overview
The workers.properties
file contains a global properties section and a worker properties section.
- 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 worker.WORKER_NAME.DIRECTIVE
.
worker
- The constant prefix for all worker properties.
WORKER_NAME
-
The arbitrary name given to the worker. For example:
node1
,node_01
,Node_1
. DIRECTIVE
- The specific directive required.
B.2. Workers.properties
directives
The workers.properties
file directives are divided into global, mandatory, connection, and load-balancing classifications.
Global directives for workers.properties
- worker.list
Specifies the list of worker names that
mod_jk
uses. The workers in this list are available to map requests to.NoteA single node configuration which is not managed by a load balancer must be set to
worker.list=WORKER_NAME
.
Mandatory directives for workers.properties
- type
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
lb
andstatus
.For detailed information about AJPv13, see the Apache Tomcat Connector - AJP Protocol Reference.
Connection directives for workers.properties
- host
The hostname or IP address of the worker. The worker node must support the ajp13 protocol stack. The default value is
localhost
.You can specify the
port
directive as part of the host directive by appending the port number after the host name or IP address. For example:worker.node1.host=192.168.2.1:8009
orworker.node1.host=node1.example.com:8009
.- port
-
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. - ping_mode
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 aCPong
in 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
worker.node1.ping_mode=CI
.- C (connect)
-
Specifies the connection is probed once after connecting to the server. You specify the timeout using the
connect_timeout
directive, otherwise the value forping_timeout
is used. - P (prepost)
-
Specifies that the connection is probed before sending each request to the server. You specify the timeout using the
prepost_timeout
directive, otherwise the value forping_timeout
is used. - 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_interval
directive, otherwise the value forping_timeout
is used. - A (all)
-
The most common setting, which specifies that all directive flags are applied. For information about the
\*_timeout
advanced directives, see the Apache Tomcat Connector - Reference Guide.
- ping_timeout
-
Specifies the time to wait for
CPong
answers to aCPing
connection probe (seeping_mode
). The default value is10000
(milliseconds).
Load balancing directives for workers.properties
- lbfactor
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
worker.WORKER_NAME.lbfactor=3
.- balance_workers
-
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
workers.properties
file. - sticky_session
Specifies whether requests for workers with SESSION IDs are routed back to the same worker. The default is
0
(false). When set to1
(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.
Additional resources
Appendix C. Multi-processing modules (MPMs)
Red Hat JBoss Core Services includes a variety of multi-processing modules (MPMs). You can use these MPMs to customize how the Apache HTTP Server responds to incoming requests.
C.1. MPMs overview
Multi-processing modules (MPMs) are available for both Red Hat Enterprise Linux and Microsoft Windows.
MPMs for Red Hat Enterprise Linux
prefork
-
The
prefork
MPM 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. worker
-
The
worker
MPM 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. event
-
The
event
MPM is based off theworker
MPM, 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.
MPMs for Microsoft Windows
winnt
-
The
winnt
MPM 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.
C.2. Switching the MPM
The server selects the MPM based on the LoadModule
directives in the JBCS_HOME/httpd/conf.modules.d/00-mpm.conf
file. You can select a specific MPM by removing the comment character (#
) from the LoadModule
directive for that MPM in the 00-mpm.conf
file.
By default, the prefork
MPM is selected. For example:
# 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
Procedure
Edit the
JBCS_HOME/httpd/conf.modules.d/00-mpm.conf
to add a comment (#
) character to theLoadModule
directive for theprefork
MPM. For example:# 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
00-mpm.conf
file, remove the comment (#
) character from theLoadModule
directive for the MPM that you want to switch to. These lines are located immediately below theprefork
MPM.For example, to load the
worker
MPM, remove the comment (#
) character from theLoadModule
directive for theworker
MPM:# 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
To verify the MPM is configured correctly, enter the following command:
$ sbin/apachectl -V
This command displays the current MPM. For example:
Server MPM: worker
Appendix D. Worker node configuration
Configuration values are sent to proxies under the following conditions:
- During server startup
- When a proxy is detected through the advertise mechanism
- During error recovery when a proxy’s configuration is reset
Table D.1. Proxy Configuration Values for Tomcat
Value | Default | Description |
---|---|---|
| true | Specifies whether subsequent requests for a given session should be routed to the same node, if possible. |
| false |
Specifies whether the Apache HTTP Server proxy should remove session stickiness if the balancer is unable to route a request to the node to which it is stuck. This property is ignored if |
| true |
Specifies whether the Apache HTTP Server proxy should return an error if the balancer is unable to route a request to the node to which it is stuck. This property is ignored if |
| -1 |
Specifies the 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 while ( |
| 1 |
Specifies the number of times the Apache HTTP Server proxy will attempt to send a given request to a worker before aborting. The minimum value is |
| false | Specifies whether packet flushing is enabled or disabled. |
| -1 |
Specifies the time to wait before flushing packets. A value of |
| 10 | Time to wait (in seconds) for a pong answer to a ping. |
|
Specifies the soft maximum idle connection count. The maximum value is determined by the Apache HTTP Server thread configuration ( | |
| 60 |
Specifies the time (in seconds) idle connections persist, above the |
| -1 |
Specifies the time (in seconds) mod_cluster waits for the back-end server response before returning an error. mod_cluster always uses a |
| mycluster | Specifies the name of the load-balancer. |
|
Specifies the load balancing among |
Appendix E. Mod_cluster
proxy and proxy discovery configuration attributes
The following tables contain attributes and information about mod_cluster
proxy and proxy discovery configuration attributes.
Table E.1. Proxy discovery configuration attributes for mod_cluster
Attribute | Property | Default Value |
---|---|---|
proxy-list |
| |
proxy-url |
| |
advertise |
| true |
advertise-security-key |
| |
excluded-contexts |
| |
auto-enable-contexts |
| true |
stop-context-timeout |
| 10 seconds (in seconds) |
socket-timeout |
| 20 seconds (in milliseconds) |
When nodeTimeout
is not defined, the ProxyTimeout
directive, Proxy
, is used. If ProxyTimeout
is not defined, the server timeout (Timeout
) is used (120 seconds by default in the JBCS httpd.conf). nodeTimeout
, ProxyTimeout
, and Timeout
are set at the socket level.
Table E.2. Proxy configuration attributes for mod_cluster
Attribute | Property | Default Value |
---|---|---|
sticky-session |
| true |
sticky-session-remove |
| false |
sticky-session-force |
| true |
node-timeout |
| -1 |
max-attempts |
| 1 |
flush-packets |
| false |
flush-wait |
| -1 |
ping |
| 10 (seconds) |
smax |
| -1 (uses the default value) |
ttl |
| -1 (uses the default value) |
domain |
| |
load-balancing-group |
|
Appendix F. Load configuration for Tomcat
You can configure the following additional properties for load metrics when you want to use mod_cluster
with Apache Tomcat.
Table F.1. Load Configuration for Tomcat
Attribute | Default Value | Description |
---|---|---|
loadMetricClass |
|
The class name of an object that is implementing |
loadMetricCapacity | 1 |
The capacity of the load metric defined via the |
loadHistory | 9 | The number of historic load values that must be considered in the load balance factor computation |
loadDecayFactor | 2 | The factor by which the historic load values decrease in significance |