Use Tomcat Connector for Load Balancing Glassfish or SJSAS

In this tutorial i describe how you can use the Tomcat Connector (mod_jk module) as a load balancer for the Glassfish or Sun Java System Application Server (SJSAS). It’s availabe as a loadable module for the Apache webserver and for the Microsoft IIS.

The Tomcat Connector uses the packet oriented binary AJP13 protocol for the communication between the servlet container and the webserver. This architecture is optimized for speed and is much faster as a proxy configuration.

Download components

  1. Download the actual mod_jk distribution for either Apache or IIS webserver.
  2. Download the actual Tomcat 5.5 distribution.
  3. Download commons-logging and commons-modeler from the Jakarta Project.

Installation for Apache Webserver

Copy the mod_jk distribution files to your apache libexec directory, e.g. /srv/apache/libexec under Linux OS.

Edit the server configuration file httpd.conf and add the following configuration options:

# Load mod_jk module
LoadModule jk_module libexec/mod_jk.so
AddModule mod_jk.c


  # Tells the module the location of the workers.properties file
  JkWorkersFile /srv/apache/conf/workers.properties

  # Specifies the location for this module's specific log file
  JkLogFile /var/log/mod_jk.log

  # Sets the module's log level to info
  JkLogLevel info

  # Sets the module's log time stamp format
  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "

  # JkOptions for SSL
  JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories

  # Set mount points for load balancer
  JkMount /app1   loadbalancer1
  JkMount /app1/* loadbalancer1
  JkMount /app2   loadbalancer1
  JkMount /app2/* loadbalancer1

Installation for Microsoft IIS

  1. In the registry, create a new registry key named “HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0”
  2. Add a string value with the name extension_uri and a value of /jakarta/isapi_redirect.dll.
  3. Add a string value with the name log_file and a value pointing to where you want your log file to be (for example c:\mod_jk\isapi.log).
  4. Add a string value with the name log_level and a value for your log level (can be debug, info, error or emerg).
  5. Add a string value with the name worker_file and a value which is the full path to your workers.properties file (for example c:\mod_jk\workers.properties)
  6. Add a string value with the name worker_mount_file and a value which is the full path to your uriworkermap.properties file (for example c:\mod_jk\uriworkermap.properties)
  7. Using the IIS management console, add a new virtual directory to your IIS/PWS web site. The name of the virtual directory must be jakarta. Its physical path should be the directory where you placed isapi_redirect.dll (in our example it is c:\mod_jk). While creating this new virtual directory assign it with execute access.
  8. Using the IIS management console, add isapi_redirect.dll as a filter in your IIS/PWS web site. The name of the filter should reflect its task (I use the name glassfish), its executable must be our c:\mod_jk\isapi_redirect.dll. For PWS, you’ll need to use regedit and add/edit the “Filter DLLs” key under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters. This key contains a “,” separated list of dlls (full paths) – you need to insert the full path to isapi_redirect.dll.
  9. Restart IIS (stop + start the IIS service), make sure that the tomcat filter is marked with a green up-pointing arrow. Under Win98 you may need to cd WINDOWS\SYSTEM\inetsrv and type PWS /stop ( the DLL and log files are locked – even if you click the stop button, PWS will still keep the DLLs in memory. ). Type pws to start it again.

Setup uriworkermap.properties (IIS only)

In the uriworkermap.properties file you define the mappings for URL’s which should be connected to your load balancer:

# Mapping for app1
/app1=loadbalancer1
/app1/*=loadbalancer1

# Mapping for app2
/app2=loadbalancer1
/app2/*=loadbalancer1

Configuration of Tomcat Connector

Edit the file workers.properties which you have specified in your webserver configuration file:

# Define all worker nodes
worker.list=loadbalancer1

# Set properties for server1 (ajp13)
worker.server1.type=ajp13
worker.server1.host=server1
worker.server1.port=8009
worker.server1.lbfactor=50
worker.server1.cachesize=10
worker.server1.cache_timeout=600
worker.server1.socket_keepalive=1
worker.server1.socket_timeout=300

# Set properties for server2 (ajp13)
worker.server2.type=ajp13
worker.server2.host=server2
worker.server2.port=8009
worker.server2.lbfactor=50
worker.server2.cachesize=10
worker.server2.cache_timeout=600
worker.server2.socket_keepalive=1
worker.server2.socket_timeout=300

# Set properties for loadbalancer1
worker.loadbalancer1.type=lb
worker.loadbalancer1.balance_workers=server1,server2
worker.loadbalancer1.sticky_session=true
worker.loadbalancer1.sticky_session_force=false
worker.loadbalancer1.method=request
worker.loadbalancer1.lock=optimistic
worker.loadbalancer1.retries=3

Restart your Apache webserver.

Installing AJP13 connector into application server

To install the AJP13 connector into your application server you must copy the file

$TOMCAT_HOME/server/lib/tomcat_ajp.jar

from the Tomcat server distribution to your application server’s lib directory. It seems that the actual Tomcat 5.5.25 tomcat_ajp.jar doesn’t work and throws a java.lang.NoSuchMethodError exception. So use the library bundled with Tomcat 5.5.16 and all works ok. You also need to copy the downloaded commons-logging.jar and commons-modeler.jar to this directory.

To activate the connector use the console application to add the following JVM option to your server instance:

-Dcom.sun.enterprise.web.connector.enableJK=8009

Restart your application server.

All requests to the definded mount points on the webserver should now be delegated to one of your application servers.

You can download the sample configuration files, jar archives and mod_jk modules for windows and linux here.