Red Hat Training

A Red Hat training course is available for Red Hat JBoss Core Services

Chapter 2. Apache Tomcat Connector (mod_jk)

The Apache Tomcat Connector, mod_jk, is a plug-in designed to allow request forwarding from Apache HTTP Server to a Servlet container. The module also supports load-balancing HTTP calls to a set of Servlet containers while maintaining sticky sessions.

2.1. Downloading and Installing mod_jk

The mod_jk module is included in the Apache HTTP Server part of a JBoss Core Services installation.

Follow the procedures in the JBoss Core Services Installation Guide to download and install Apache HTTP Server for your operating system.

2.2. Configuring Load Balancing using Apache HTTP Server and mod_jk

You can use the mod_jk connector to configure Apache HTTP Server load balancing. Follow the tasks in this section to configure load balancing using mod_jk, including configuring worker nodes.

Sample configuration files are provided for mod_jk, and are located in JBCS_HOME/httpd/conf.d/. The sample configuration files are: mod_jk.conf.sample, workers.properties.sample, and uriworkermap.properties.sample. To use these samples instead of creating your own configuration files, remove the .sample extension, and modify their content as needed.

Note

Red Hat customers can also use the Load Balancer Configuration Tool on the Red Hat Customer Portal to quickly generate optimal configuration templates for mod_jk and Tomcat worker nodes.

When using this tool for Apache HTTP Server 2.4.29, ensure you select 2.4.x as the Apache version, and select Tomcat as the back-end configuration.

2.2.1. Configuring Apache HTTP Server to load mod_jk

  1. Create a new file JBCS_HOME/httpd/conf.d/mod_jk.conf, and insert the following configuration: 

    # 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>
    Important

    The LoadModule directive must reference the mod_jk native binary you installed.

    Note

    The JkMount directive specifies which URLs that Apache HTTP Server will forward to the mod_jk module. Based on the directive’s configuration, mod_jk forwards the received URL to the correct Servlet containers.

    To enable Apache HTTP Server to serve static content (or PHP content) directly and only use the load balancer for Java applications, the suggested configuration above specifies that only requests with the URL /application/* are sent to the mod_jk load balancer.

    Alternatively, you can forward all URLs to mod_jk by specifying /* in the JkMount directive.

  2. Optional: JKMountFile Directive

    In addition to the JkMount directive, you can use the JkMountFile directive to specify a mount point’s configuration file. The configuration file contains multiple URL mappings for Tomcat forwarding.

    1. Navigate to JBCS_HOME/httpd/conf.d/ and create a file named uriworkermap.properties.

    2. Using the following syntax example as a guide, specify the URL to forward and the worker name.

      The syntax required takes the form: /URL=WORKER_NAME

      The example below configures mod_jk to forward requests for /application to the JBoss Web Server Tomcat back-end. 

      # Simple worker configuration file

# Mount the Servlet context to the ajp13 worker
/application=loadbalancer
/application/*=loadbalancer

    3. In JBCS_HOME/httpd/conf.d/mod_jk.conf , append 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

  3. Optional: Configure Apache HTTP Server Logging

    You can configure the Apache HTTP Server that is doing the load balancing to log which worker node handled a request. This may be useful when troubleshooting your load balancer.

    To enable this for mod_jk, you can either:

    • include %w in your JkRequestLogFormat (which is configured by default in the suggestion above) ; or
    • log the name of the mod_jk worker used by including %{JK_WORKER_NAME}n in your Apache HTTP Server LogFormat(s).

    For more information on JkRequestLogFormat, see the Apache Tomcat connector documentation. For more information on Apache HTTP Server logging (including log rotation), see the Apache HTTP Server documentation on log files.

2.2.2. Configuring Worker Nodes in mod_jk

This procedure demonstrates two mod_jk worker node definitions in a weighted round robin configuration with sticky sessions active between two servlet containers.

Prerequisites

To configure mod_jk worker nodes:

  1. Navigate to JBCS_HOME/httpd/conf.d/, and create a file named workers.properties.

  2. Add the following configuration into workers.properties, customizing it to your environment: 

    # 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

# 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

# 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

2.2.3. Configuring Tomcat to work with mod_jk

Tomcat is configured to receive AJP traffic from mod_jk by default; however, there is one additional step required before you can use a worker with mod_jk. The AJP connector is configured by default in the JWS_HOME/tomcat/conf/server.xml: 

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

In addition to the AJP enabled Connector you also need to configure a unique value for the jvmRoute attribute in the Engine of each worker node: 

<Engine name="Catalina" jvmRoute="node1" >
Important

The jvmRoute attribute value must match the worker name set in workers.properties.