Red Hat Training

A Red Hat training course is available for Red Hat JBoss Web Server

2.2. Configure 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, including configuring worker nodes.
Sample configuration files are provided for mod_jk, and are located in JWS_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 JBoss Web Server 3, 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

Procedure 2.1. Configure Apache HTTP Server to Load mod_jk

  1. Open JWS_HOME/httpd/conf/httpd.conf and add the following lines at the end of the file:
    # Include mod_jk's specific configuration file  
    Include conf.d/mod_jk.conf
  2. Create a new file: JWS_HOME/httpd/conf.d/mod_jk.conf
  3. Add the following configuration to the mod_jk.conf file.
    # 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 SSK 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 library directory location for the native binary you installed.

    Note

    The JkMount directive specifies which URLs Apache HTTP Server will forward to the mod_jk module. Based on the directive's configuration, mod_jk forwards the received URL onto 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 all 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 directive.
  4. 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 Tomcat forwarding URL mappings.
    1. Navigate to JWS_HOME/httpd/conf.d/.
    2. Create a file named uriworkermap.properties.
    3. 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 block below configures mod_jk to forward requests to /jmx-console and /web-console to Apache HTTP Server.
      # Simple worker configuration file
      
      # Mount the Servlet context to the ajp13 worker
      /jmx-console=loadbalancer
      /jmx-console/*=loadbalancer
      /web-console=loadbalancer
      /web-console/*=loadbalancer
    4. In JWS_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
  5. 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; 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 http://tomcat.apache.org/connectors-doc/webserver_howto/apache.html. For more information on Apache HTTP Server logging (including log rotation), see http://httpd.apache.org/docs/2.4/logs.html.

2.2.2. Configuring Worker Nodes in mod_jk

2.2.2.1. 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.

Procedure 2.2. Configure mod_jk Worker Nodes

Prerequisites

To configure mod_jk worker nodes:
  1. Navigate to JWS_HOME/httpd/conf.d/, and create a file named workers.properties.
  2. Add the following configuration into workers.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 
    
    # 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 Apache Tomcat to Work with mod_jk

Tomcat is configured to use mod_jk by default. Specifically, see the JWS_HOME/tomcat<VERSION>/conf/server.xml file, which contains the following configuration for this purpose:
<connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
Additionally, configure the jvmRoute attribute for your engine:
<Engine name="Catalina" jvmRoute="node1" >
The jvmRoute attribute value must match the worker name set in workers.properties.
This default Tomcat configuration is ready for immediate use with mod_jk.