This documentation relates to uPortal 4.0
If you are using a different version, please click on "Click for all versions" on the left side of the page and select the relevant version.

Load balancing with Mod_JK

Skip to end of metadata
Go to start of metadata
All Versions
Page not found
Table of Contents
Page not found

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.


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.


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.

ConnectionSource IP Source Port Target IPTarget Port
Open HTTP (80)AnyAnyApache IP80
Open HTTP (443)AnyAnyApache IP443
Apache to Tomcat 1Apache IPAnyTomcat 1 IP8009
Apache to Tomcat 2Apache IPAnyTomcat 2 IP8009
Apache to Tomcat 3Apache IPAnyTomcat 3 IP8009


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 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 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>/"`.

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


<IfModule mod_jk.c>
    JkWorkersFile "<path_to_apache_config>/"
    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

Configuration with VirtualHosts

If your installation uses virtual hosts, you may need to add JkMountCopy On into the Virtual Host entry.


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
        Allow from
        Allow from

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

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

Configuring ``

The `` 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.



# Properties for worker1
worker.tomcat1.port=8009<Tomcat 1 server name or IP>

# Properties for worker2
worker.tomcat2.port=8009<Tomcat 2 server name or IP>

# Properties for loadbalancer

# Properties for jkstatus


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


Having problems with these instructions?

Please send us feedback at

  • No labels