Search
SupportConsoleDevelopersStart a trialContact

17.7. Apache mod_jk

download PDF

17.7.1. About the Apache mod_jk HTTP Connector

Apache mod_jk is a HTTP connector which is provided for customers who need it for compatibility purposes. It provides load balancing, and is a part of the natives package, Red Hat JBoss Enterprise Application Platform 6.X.0 Webserver Connector Natives (zip installation) which is available on the Red Hat Customer Portal at https://access.redhat.com. mod_jk can be installed from the RPMs. For details of installing from RPM, refer Section 17.7.4, “Install the mod_jk Module Into the Apache HTTP Server (RPM)”. For supported platforms, see https://access.redhat.com/articles/111663. The mod_jk connector is maintained by Apache, and its documentation is located at http://tomcat.apache.org/connectors-doc/.
JBoss EAP 6 can accept workloads from an Apache HTTP proxy server. The proxy server accepts client requests from the web front-end, and passes the work to participating JBoss EAP 6 servers. If sticky sessions are enabled, the same client request always goes to the same JBoss EAP 6 server, unless the server is unavailable.
Unlike the JBoss mod_cluster HTTP connector, an Apache mod_jk HTTP connector does not know the status of deployments on servers or server groups, and cannot adapt where it sends its work accordingly.
mod_jk communicates over the AJP 1.3 protocol. mod_cluster supports other protocols. For more information, refer Table HTTP connector features and constraints in Section 17.2.3, “Overview of HTTP Connectors”.

Note

mod_cluster is a more advanced load balancer than mod_jk. mod_cluster provides all of the functionality of mod_jk and additional features. For more information about mod_cluster, see Section 17.6.1, “About the mod_cluster HTTP Connector”.

Next step: Configure a JBoss EAP 6 instance to participate in a mod_jk load balancing group

Report a bug

17.7.2. Configure JBoss EAP 6 to Communicate with Apache mod_jk

Overview

The mod_jk HTTP connector has a single component, the mod_jk.so module loaded by the web server. This module receives client requests and forwards them to the container, in this case JBoss EAP 6. JBoss EAP 6 must also be configured to accept these requests and send replies back to the web server.

Configuring the Apache HTTP Server is covered in Section 17.7.3, “Install the mod_jk Module Into the Apache HTTP Server (ZIP)”.
In order for JBoss EAP 6 to be able to communicate with the Apache HTTP server, it must have the AJP/1.3 connector enabled. This connector is present by default in the following configurations:
  • In a managed domain, in server groups using the ha and full-ha profiles, and the ha or full-ha socket binding group. The other-server-group server group is configured correctly in a default installation.
  • In a standalone server, the standalone-ha and standalone-full-ha profiles are configured for clustered configurations. To start the standalone server with one of these profiles, issue the following command, from the EAP_HOME/ directory. Substitute the appropriate profile name. 
    EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml
    For Windows, enter the following command: 
    EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml
Report a bug

17.7.3. Install the mod_jk Module Into the Apache HTTP Server (ZIP)

Prerequisites

  • To perform this task, you must be using Apache HTTP Server installed on a supported environment or the Apache HTTP Server installed from JBoss Enterprise Web Server. Note that the JBoss Enterprise Web Server is part of the JBoss EAP 6 distribution.
  • If you need to install the Red Hat Enterprise Linux native Apache HTTP Server, use the instructions in the Red Hat Enterprise Linux Deployment Guide.
  • If you need to install the HP-UX native Apache HTTP Server, use the instructions in the HP-UX Web Server Suite Installation Guide, available at https://h20392.www2.hp.com/portal/swdepot/displayInstallInfo.do?productNumber=HPUXWSATW232.
  • If you need to install JBoss Enterprise Web Server, use the instructions in the JBoss Enterprise Web Server Installation Guide.
  • If you are using Apache HTTP Server, download the JBoss EAP 6 Native Components package for your platform from the Red Hat Customer Portal at https://access.redhat.com. This package contains both the mod_jk and mod_cluster precompiled binaries. If you are using JBoss Enterprise Web Server, it already includes the binary for mod_jk.
  • If you are using Red Hat Enterprise Linux (RHEL) 5 and native Apache HTTP server (httpd 2.2.3), load the mod_perl module prior to loading mod_jk module.
  • You must be logged in with administrative (root) privileges.
  • To view the HTTPD variable conventions, see Section 17.4.2, “HTTPD Variable Conventions”

Procedure 17.16. Install the mod_jk Module

  1. Configure the mod_jk module.

    1. Create a new file called HTTPD_HOME/conf.d/mod-jk.conf and add the following to it:

      Note

      The JkMount directive specifies which URLs Apache HTTP Server must forward to the mod_jk module. Based on the directive's configuration, mod_jk sends the received URL to the correct workers.
      To serve static content directly, and only use the load balancer for Java applications, the URL path must be /application/*. To use mod_jk as a load balancer, use the value /*, to forward all URLs to 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/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 -ForwardDirectories

# JkRequestLogFormat
JkRequestLogFormat "%w %V %T"

# Mount your applications
# The default setting only sends Java application data to mod_jk.
# Use the commented-out line to send all URLs through mod_jk.
# JkMount /* loadbalancer
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
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>
      Look over the values and ensure they are reasonable for your setup. When you are satisfied, save the file.

    2. Specify a JKMountFile directive

      In addition to the JKMount directive in the mod-jk.conf, you can specify a file which contains multiple URL patterns to be forwarded to mod_jk.
      1. Add the following to the HTTPD_HOME/conf/mod-jk.conf file: 
        # You can 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/uriworkermap.properties
      2. Create a new file called HTTPD_CONF/uriworkermap.properties, with a line for each URL pattern to be matched. The following example shows examples of the syntax of the file. 
        # Simple worker configuration file
/*=loadbalancer

    3. Copy the mod_jk.so file to the httpd's modules directory

      Note

      This is only necessary if the Apache HTTP server does not have mod_jk.so in its modules/ directory. You can skip this step if you are using the Apache HTTP server included as a download as part of JBoss EAP 6.
      Extract the Native Web Server Connectors Zip package. Locate the mod_jk.so file in either the EAP_HOME/modules/system/layers/base/native/lib/httpd/modules/ or the EAP_HOME/modules/system/layers/base/native/lib64/httpd/modules/ directories, depending on whether your operating system is 32-bit or 64-bit.
      Copy the file to the HTTPD_MODULES/ directory.

  2. Configure the mod_jk worker nodes.

    1. Create a new file called HTTPD_CONF/workers.properties. Use the following example as your starting point, and modify the file to suit your needs. 
      # 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
      For a detailed description of the syntax of the workers.properties file, and advanced configuration options, see Section 17.7.5, “Configuration Reference for Apache mod_jk Workers”.

  3. Restart the Web Server.

    The way to restart the web server depends on whether you are using Red Hat Enterprise Linux's Apache HTTP server or the Apache HTTP server included in JBoss Enterprise Web Server. Choose one of the following methods.

    • Red Hat Enterprise Linux's Apache HTTP Server

      Issue the following command: 
      [root@host]# service httpd restart

    • JBoss Enterprise Web Server Apache HTTP Server

      JBoss Enterprise Web Server runs on both Red Hat Enterprise Linux and Microsoft Windows Server. The method for restarting the web server is different for each.

      • Red Hat Enterprise Linux, installed from RPM

        In Red Hat Enterprise Linux, JBoss Enterprise Web Server installs its web server as a service. To restart the web server, issue the following two commands: 
        [root@host ~]# service httpd stop
[root@host ~]# service httpd start

      • Red Hat Enterprise Linux, installed from Zip

        If you have installed the JBoss Enterprise Web Server Apache HTTP server from a Zip archive, use the apachectl command to restart the web server. Replace EWS_HOME with the directory where you unzipped JBoss Enterprise Web Server Apache HTTP server. 
        [root@host ~]# EWS_HOME/httpd/sbin/apachectl restart

      • Microsoft Windows Server

        Issue the following commands in a command prompt with administrative privileges: 
        net stop Apache2.2
net start Apache2.2

      • Solaris

        Issue the following commands in a command prompt with administrative privileges. Replace EWS_HOME with the directory where you unzipped JBoss Enterprise Web Server Apache HTTP server. 
        [root@host ~] EWS_HOME/httpd/sbin/apachectl restart
Result

The Apache HTTP server is now configured to use the mod_jk load balancer. To configure JBoss EAP 6 to be aware of mod_jk, see Section 17.4.8, “Configure JBoss EAP 6 to Accept Requests From External Web Servers”.

Report a bug

17.7.4. Install the mod_jk Module Into the Apache HTTP Server (RPM)

Prerequisites

  • To perform this task, you must be using the Apache HTTP Server installed in Red Hat Enterprise Linux 6, JBoss Enterprise Web Server, or the standalone Apache HTTP Server included as a separate downloadable component of JBoss EAP 6.
  • You must have an active subscription to the jbappplatform-6-ARCHITECTURE-server-RHEL_VERSION-rpm channel.
  • If you need to install Apache HTTP Server in Red Hat Enterprise Linux 6, use the instructions from the Red Hat Enterprise Linux 6 Deployment Guide.
  • If you need to install the standalone Apache HTTP Server included as a separate downloadable component of JBoss EAP 6, refer to Section 17.4.3, “Install Apache HTTP Server in Red Hat Enterprise Linux 5, 6, and 7 (Zip)” .
  • If you need to install JBoss Enterprise Web Server, use the instructions from the JBoss Enterprise Web Server Installation Guide.
  • You must be logged in with administrative (root) privileges.

Procedure 17.17. Red Hat Enterprise Linux 5: mod_jk with Apache HTTP Server 2.2.3

  1. Install mod_jk-ap22 1.2.37 and its dependency mod_perl from the jbappplatform-6-ARCHITECTURE-server-5-rpm channel: 
    yum install mod_jk
  2. Optional: Copy the sample configuration files for use: 
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf

    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    These files should be edited to suit your needs.
  3. Start the server: 
    service httpd start

Note

The following error message indicates that your mod_jk module had been loaded before mod_perl was present: 
Cannot load /etc/httpd/modules/mod_jk.so into server: /etc/httpd/modules/mod_jk.so: undefined symbol: ap_get_server_description
To ensure mod_perl module is loaded before mod_jk module add the following to the /etc/httpd/conf.d/mod_jk.conf: 
 <IfModule !perl_module>
        LoadModule perl_module modules/mod_perl.so
</IfModule>
LoadModule jk_module modules/mod_jk.so

Procedure 17.18. Red Hat Enterprise Linux 5: mod_jk with JBoss EAP Apache HTTP Server 2.2.26

  1. Install both mod_jk and the latest Apache HTTP Server 2.2.26 provided by the jbappplatform-6-ARCHITECTURE-server-5-rpm channel with this command: 
    yum install mod_jk httpd
  2. Optional: Copy the sample configuration files for use: 
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf

    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    These files should be edited to suit your needs.
  3. Start the server: 
    service httpd start

Procedure 17.19. Red Hat Enterprise Linux 6: mod_jk with JBoss EAP Apache HTTP Server 2.2.26

  1. Install mod_jk-ap22 1.2.37 and Apache HTTP Server 2.2.26 httpd package from the jbappplatform-6-ARCHITECTURE-server-6-rpm channel (any existing versions will be updated): 
    yum install mod_jk httpd
  2. Optional: Copy the sample configuration files for use: 
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf

    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    These files should be edited to suit your needs.
  3. Start the server: 
    service httpd start

Procedure 17.20. Red Hat Enterprise Linux 6: mod_jk with Apache HTTP Server 2.2.15

  1. Install mod_jk with Apache HTTP Server 2.2.15 with the following command: 
    yum install mod_jk
  2. Optional: Copy the sample configuration files for use: 
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd/conf.d/mod_jk.conf

    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd/conf/workers.properties
    These files should be edited to suit your needs.
  3. Start the server: 
    service httpd start

Procedure 17.21. Red Hat Enterprise Linux 7: mod_jk with JBoss EAP Apache HTTP Server 2.2.26

  1. Install mod_jk-ap22 1.2.37 and Apache HTTP Server 2.2.26 httpd22 package from the jbappplatform-6-ARCHITECTURE-server-6-rpm channel (any existing versions will be updated): 
    yum install mod_jk
  2. Optional: Copy the sample configuration files for use: 
    cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample /etc/httpd22/conf.d/mod_jk.conf

    cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample /etc/httpd22/conf/workers.properties
    These files should be edited to suit your needs.
  3. Start the server: 
    systemctl start httpd22.service
Report a bug

17.7.5. Configuration Reference for Apache mod_jk Workers

The workers.properties file defines the behavior of the workers which mod_jk passes client requests to. In Red Hat Enterprise Linux, the file resides in /etc/httpd/conf/workers.properties. The workers.properties file defines where the different application servers are located, and the way the work load should be balanced across them.
The configuration is divided into three sections. The first section deals with global properties, which apply to all workers. The second section contains settings which apply to a specific Load Balancer. The third section contains settings which apply to a specific worker node balanced by the Load Balancer.
The general structure of a property is worker.WORKER_NAME.DIRECTIVE, where WORKER_NAME is a unique name for the worker, and DIRECTIVE is the setting to be applied to the worker.
Configuration reference for Apache mod_jk Load Balancers

Templates specify default per-Load Balancer settings. You can override the template within the Load Balancer settings itself. You can see an example of Load Balancer templates in Example 17.7, “Example workers.properties file”.

Table 17.15. Global properties
Property Description
worker.list The list of Load Balancers names used by mod_jk. These Load Balancers are available to receive requests.
Table 17.16. Mandatory Directives
Property Description
type
The type of the Load Balancer. The default type is ajp13. Other possible values are ajp14, lb, status.
For more information on these directives, refer to the Apache Tomcat Connector AJP Protocol Reference at http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html.
Table 17.17. Load Balancing Directives
Property Description
balance_workers
Specifies the worker nodes that the load balancer must manage. You can use the directive multiple times for the same load balancer. It consists of a comma-separated list of worker node names. This is set per Load Balancer, not per worker node.
sticky_session
Specifies whether requests from the same session are always routed to the same worker. The default is 1, meaning that sticky sessions are enabled. To disable sticky sessions, set it to 0. Sticky sessions should usually be enabled, unless all of your requests are truly stateless. This is set per Load Balancer, not per worker node.
Table 17.18. Connection Directives
Property Description
host
The hostname or IP address of the Load Balancer. The Load Balancer must support the ajp protocol stack. The default value is localhost.
port
The port number of the remote server instance listening for defined protocol requests. The default value is 8009, which is the default listening port for AJP13 Load Balancers. The default value for AJP14 Load Balancers is 8011.
ping_mode
The conditions under which connections are probed for network status. The probe uses an empty AJP13 packet for CPing, and expects a CPong in response. Specify the conditions by using a combination of directive flags. The flags are not separated by a comma or any white-space. The ping_mode can be any combination of C, P, I, and A.
  • C - Connect. Probe the connection one time after connecting to the server. Specify the timeout using the value of connect_timeout. Otherwise, the value of ping_timeout is used.
  • P - Prepost. Probe the connection before sending each request to the server. Specify the timeout using the prepost_timeout directive. Otherwise, the value of ping_timeout is used.
  • I - Interval. Probe the connection at an interval specified by connection_ping_interval, if present. Otherwise, the value of ping_timeout is used.
  • A - All. A shortcut for CPI, which specifies that all connection probes are used.
ping_timeout, connect_timeout, prepost_timeout, connection_ping_interval
The timeout values for the connection probe settings above. The value is specified in milliseconds, and the default value for ping_timeout is 10000.
lbfactor
Specifies the load-balancing factor for an individual Load Balancer, and only applies to a member worker node of a load balancer. This is useful to give a more powerful server more of the work load. To give a worker 3 times the default load, set this to 3: worker.my_worker.lbfactor=3

Example 17.7. Example workers.properties file

worker.balancer1.type=lb
worker.balancer2.type=lb

worker.balancer1.sticky_sessions=1
worker.balancer1.balance_workers=node1
worker.balancer2.sticky_session=1
worker.balancer2.balance_workers=node2,node3

worker.nodetemplate.type=ajp13
worker.nodetemplate.port=8009

worker.node1.template=nodetemplate
worker.node1.host=localhost
worker.node1.ping_mode=CI
worker.node1.connection_ping_interval=9000
worker.node1.lbfactor=1

worker.node2.template=nodetemplate
worker.node2.host=192.168.1.1
worker.node2.ping_mode=A

worker.node3.template=nodetemplate
worker.node3.host=192.168.1.2
The example above demonstrates the use of multiple Load Balancers to serve the content on behalf of a web server. The reasons for such configuration can be:
  • To have different contexts to be served by different Load Balancers, providing a development environment in which all the developers share the same web server but own a Load Balancer of their own.
  • To have different virtual hosts served by different processes, providing a clear separation between sites belonging to different companies.
  • To provide load balancing, that is, run multiple Load Balancers each on its own machine and divide the requests between them.
Further configuration details for Apache mod_jk are out of the scope of this document. Refer to the Apache documentation at http://tomcat.apache.org/connectors-doc/ for further instructions.
Report a bug
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.