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