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 Red Hat JBoss Core Services (JBCS) and Red Hat Enterprise Linux (RHEL) provide separate distributions of the Apache HTTP Server. The Apache HTTP Server distribution that you install determines whether installation of the mod_jk connector is automatic or requires a manual step. Depending on your installed distribution of the Apache HTTP Server, the installation path for the mod_jk module and configuration files also varies. Note The JBCS Apache HTTP Server supports the use of mod_jk on all supported operating systems. The RHEL Apache HTTP Server supports the use of mod_jk on RHEL 9 only. 2.1.1. Installation of mod_jk when using the JBCS Apache HTTP Server The Apache HTTP Server part of a JBCS installation automatically installs the mod_jk module. You can follow the procedures in the Red Hat JBoss Core Services Apache HTTP Server Installation Guide to install the JBCS Apache HTTP Server for your operating system. For more information, see the Additional resources links. Consider the following guidelines for a mod_jk installation when using the JBCS Apache HTTP Server: The mod_jk.so module is installed in the JBCS_HOME /httpd/modules directory. The mod_jk.conf.sample , workers.properties.sample , and urworkermap.properties.sample configuration files are located in the JBCS_HOME /httpd/conf.d directory. The mod_jk.conf.sample file includes a LoadModule directive for the mod_jk module. Note JBCS_HOME represents the top-level directory for a JBCS installation, which is /opt/jbcs-httpd24-2.4 . Additional resources Installing the JBCS Apache HTTP Server on RHEL from archive files Installing the JBCS Apache HTTP Server on RHEL 7 or RHEL 8 from RPM packages Installing the JBCS Apache HTTP Server on Windows Server 2.1.2. Installing mod_jk by using RHEL Application Streams If you install the RHEL 9 distribution of the Apache HTTP Server from an RPM package by using Application Streams, RHEL does not automatically install the mod_jk package. In this situation, if you want to use the mod_jk connector, you must install the mod_jk package manually. Prerequisites You have installed the Apache HTTP Server on RHEL 9 by using Application Streams. Procedure Enter the following command as the root user: Verification To check that the mod_jk package is successfully installed, enter the following command: The preceding command outputs the full name of the installed package, which includes version and platform information. Consider the following guidelines for a mod_jk installation when using RHEL Application Streams: The mod_jk.so module is installed in the /usr/lib64/httpd/modules directory. The mod_jk.conf.sample , workers.properties.sample , and urworkermap.properties.sample configuration files are located in the /etc/httpd/conf.d directory. The mod_jk.conf.sample file includes a LoadModule directive for the mod_jk module. Additional resources Application Streams Managing software with the DNF tool 2.2. Apache HTTP Server load-balancing configuration when using mod_jk You can configure the Apache HTTP Server to use the mod_jk connector to load-balance requests to a set of servlet containers. This setup includes the configuration of back-end worker nodes. Depending on whether you installed mod_jk through Red Hat JBoss Core Services (JBCS) or by using Red Hat Enterprise Linux (RHEL) Application Streams, consider the following guidelines: JBCS provides example configuration files for mod_jk in the JBCS_HOME /httpd/conf.d/ directory. RHEL provides example configuration files for mod_jk in the /etc/httpd/conf.d/ directory. The example configuration files for mod_jk 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. Note 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.57, ensure that you select 2.4.x as the Apache version, and select Tomcat/JWS as the back-end configuration. Note Red Hat JBoss Core Services 2.4.57 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.2.1. 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. Depending on the Apache HTTP Server distribution that you are using, the location of the configuration file varies. You can also perform the following optional configuration steps: In addition to the JkMount directive, you can use the JkMountFile 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. Prerequisites You have installed the Apache HTTP Server . If you installed the RHEL distribution of the Apache HTTP Server by using Application Streams, you have installed mod_jk manually . Procedure Go to the Apache HTTP Server configuration directory: If you are using the JBCS Apache HTTP Server, go to the JBCS_HOME /httpd/conf.d directory. If you are using the RHEL Apache HTTP Server, go to the /etc/httpd/conf.d directory. Create a new file named mod_jk.conf and enter the following configuration details: Important Ensure that the LoadModule directive references the mod_jk native binary that you have installed. Note The JkMount directive specifies the URLs that the Apache HTTP Server can forward to the mod_jk module. Based on the configuration for the JkMount 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 the mod_jk load balancer. Alternatively, you can configure the Apache HTTP Server to forward all URLs to mod_jk by specifying /* in the JkMount directive. Optional: To use the JkMountFile directive to specify the configuration file for a mount point, perform the following steps: Go to the Apache HTTP Server configuration directory: If you are using the JBCS Apache HTTP Server, go to the JBCS_HOME /httpd/conf.d directory. If you are using the RHEL Apache HTTP Server, go to the /etc/httpd/conf.d directory. Create a file named uriworkermap.properties . Specify the URL that you want to forward and the worker name. For example: Note The 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 mod_jk.conf file, enter the following directive: Optional: To enable Apache HTTP Server logging, perform either of the following steps: Include %w in your JkRequestLogFormat directive, as shown in the preceding step about mod_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 Server LogFormat (s). Additional resources The Apache Tomcat Connectors - Web Server HowTo : mod_jk Directives Apache HTTP Server Documentation: Log Files 2.2.2. 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, by specifying settings in the workers.properties file. Depending on the Apache HTTP Server distribution that you are using, the location of the configuration file varies. 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 Apache HTTP Server configuration directory: If you are using the JBCS Apache HTTP Server, go to the JBCS_HOME /httpd/conf.d directory. If you are using the RHEL Apache HTTP Server, go to the /etc/httpd/conf.d directory. Create a file named workers.properties . Enter the following configuration details: Note In the preceding example, ensure that you replace host , port , and secret settings with values that are relevant for your environment. Important The secret property is required when using the Tomcat AJP Connector. You can specify the secret property for a worker node or a load balancer in the workers.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.2.3. Configuring JBoss Web Server to work with mod_jk By default, JBoss Web Server is configured to receive Apache JServ Protocol (AJP) traffic from the mod_jk connector. On the JBoss Web Server host, the AJP connector is configured by default in the JWS_HOME /tomcat <VERSION> /conf/server.xml file. However, to use a worker node with mod_jk , you must perform the following additional configuration steps: On the JBoss Web Server host, in the server.xml file, you must configure a unique value for the jvmRoute attribute in the Engine of each worker node. On the Apache HTTP Server host, in the workers.properties file, you must specify the secret property for a worker node or a load balancer. Depending on the Apache HTTP Server distribution that you are using, the location of the workers.properties file varies. Note The secret property is required when you use the Tomcat AJP connector. Procedure On the JBoss Web Server host, to configure a unique value for the jvmRoute attribute in the Engine of each worker node: Open JWS_HOME /tomcat_<VERSION>_/conf/server.xml file. Enter the following details: <Engine name="Catalina" jvmRoute="node1" > Important Ensure that the jvmRoute attribute value matches the worker name that you specify in the workers.properties file on the Apache HTTP Server host. On the Apache HTTP Server host, to specify the secret property for a worker node or a load balancer: Go to the Apache HTTP Server configuration directory: If you are using the JBCS Apache HTTP Server, go to the JBCS_HOME /httpd/conf.d directory. If you are using the RHEL Apache HTTP Server, go to the /etc/httpd/conf.d directory. Open the workers.properties file. Ensure that the secret property is specified in the following format: Note Ensure that you replace <WORKER_NAME> and <YOUR_AJP_SECRET> with values that are appropriate for your environment. Note If you set a secret on a load balancer by using the ProxyPass directive, all members of the load balancer inherit this secret . For example:

Commands:
dnf install mod_jk
rpm -q mod_jk
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>
Simple worker configuration file Mount the Servlet context to the ajp13 worker /application=loadbalancer /application/*=loadbalancer
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
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
<Engine name="Catalina" jvmRoute="node1" >
worker. <WORKER_NAME> .secret= <YOUR_AJP_SECRET> `
<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