Load balancing with Mod_JK

The Apache mod_jk plugin is a tried and true module used in for many years. While there are newer AJP plugins, mod_jk is still quite functional and popular.

Prerequisites

Apache should already have been installed and tested. Installation is beyond this document, but it should be easy to find instructions if needed. Application servers should be configured and tested as well. This is crucial to avoid wasting time as the many configuration changes are ripe for human error.

Network

Connectivity needs to be verified. In many enterprise networks, security is is critical. Many network administrators and server administrators implement firewalls of varying limits. With differing ownership, having all the firewalls modified to allow traffic can be daunting at certain institutions. Below is table of firewall rules for a typical installation.

Etc.

Allowing all traffic from Apache to the Tomcat servers on the network firewall is usually secure enough.

Once the firewall updates are completed, make sure to verify that requests to port 8009 on the Tomcat servers from Apache are working. At this point Tomcats
are not configured to listen on this port. I recommend using NetCat to test. NetCat can be configured to listen on a port and send a message to a port. To test
if a connection can be made, NetCat will need to be run on both sides to be tested. On the Tomcat server run NetCat listening on port 8009 -- `nc -l 8009`. The terminal should not return a prompt until NetCat receives a request. So to send a request from Apache, run NetCat with with the following parameters -- `nc -zw 2 <Tomcat IP> 8009`, substituting "<Tomcat IP>" with the actual value. This shout return a message if successful.

The prerequisites are the hard part.

Tomcat Configuration

Server.xml Connector Addition

Tomcats will need to have a new connector configured in server.xml. The new
connector stanza should look something like the following:

<Connector port="8009" minSpareThreads="5" maxThreads="800"
    protocol="AJP/1.3" redirectPort="8443"
    enableLookups="false" connectionTimeout="10000"
/>

Thread counts and connection timeout should be adjusted to your needs.

Server.xml jvmRoute Addition

To enable sticky sessions, the jvmRoute attribute needs to be set on the Engine stanza.

    <Engine name="Catalina" defaultHost="localhost" jvmRoute="tomcat1">

The value for jvmRoute needs to match the identifier for the Tomcat server defined in workers.properties in Apache. (See below.)

Apache Configuration

Install Mod_JK

Installing Mod_JK varies between OSes. Debian/Ubuntu servers have it easy. Running `apt-get install libapache2-mod-jk` will perform the installation. Some other Linux distributions may have have mod_jk in their repos, so search for the package. The fallback is onerous. For OSes without a mod_jk package, you will have to download from http://tomcat.apache.org/download-connectors.cgi and follow instructions in the download.

Configuring Apache httpd.conf

The plugin needs to be loaded and configured. This can be done directly in httpd.conf or included from another file. First check if the jk_module has already been loaded in another file during installation. Simply search the Apache config files. If not, you will need to load the module manually by adding `LoadModule jk_module "<path_to_lib>/mod_jk.so"`.

Next, configure mod_jk, specifying the worker configuration file, logging, and URLs to forward.

<IfModule mod_jk.c>
    JkWorkersFile "<path_to_apache_config>/workers.properties"
    JkLogFile "|<path_to_apache_bin>/rotatelogs <path_to_apache_logs>/mod_jk.log 86400"
    JkLogLevel error
    JkLogStampFormat "[%a %b %d %H:%M:%S %Y]"
    JkRequestLogFormat "%w %V %T %U %q"
    JkMount /uPortal* loadbalancer
    JkMount /uPortal/* loadbalancer
    ...
</IfModule>

Additional JkMount entries can be included for load balancing requests to portlet APIs such as `/ResourceServingWebapp/*` to loadbalancer.

Optionally, the JK Manager can be configured for monitoring. This can be limited to privileged IPs. A few example IPs are including in the snippet below.

    <Location /jkmanager/>
        JkMount jkstatus
        Order deny,allow
        Deny from all
        Allow from 169.236.10.91
        Allow from 127.0.0.1
        Allow from 169.236.250.48/28
    </Location>
</IfModule>

This snippet goes between the JkMount entries and the closing </IfModule>.

Visit http://<apache_server>/jkmanager/ to see the manager page.

Configuring `workers.properties`

The `workers.properties` file is where the Tomcat servers are specified, along  with the load balancer settings and the JK Manager JkMount. In the following snippet Two Tomcat servers are configured with one receiving twice the traffic.

worker.list=loadbalancer,jkstatus

# Properties for worker1
worker.tomcat1.port=8009
worker.tomcat1.host=<Tomcat 1 server name or IP>
worker.tomcat1.type=ajp13
worker.tomcat1.lbfactor=10
worker.tomcat1.connection_pool_size=1

# Properties for worker2
worker.tomcat2.port=8009
worker.tomcat1.host=<Tomcat 2 server name or IP>
worker.tomcat2.type=ajp13
worker.tomcat2.lbfactor=20
worker.tomcat2.connection_pool_size=1

# Properties for loadbalancer
worker.loadbalancer.type=lb
#worker.lodbalancer.balanced_workers=tomcat2,tomcat1
worker.loadbalancer.sticky_session=1

# Properties for jkstatus
worker.jkstatus.type=status

Test Configuration

Restart Apache and test that the configuration is working. Open a browser and visit the JK Manager. If you have issues review the changes to httpd.conf files and the worker.properties file. Once you can reach the JK Manager, test that traffic is redirecting to the portal by pointing a browser at http://<apache_server>/uPortal/ .