Using mod_jk 1.2.x with JBoss/Tomcat bundle and Apache2




This wiki outlines the various steps required to install a basic load-balancing solution based on JBoss/Tomcat and mod_jk 1.2.


Step 1: Download Apache2 Web Server


Get the latest Apache2 package from and install it. We require no special configuration, just use the default settings.

In the following steps, APACHE_HOME will represent the Apache install directory.


Step 2: Download mod_jk 1.2.x


Download the latest package available from Jakarta's 'binary downloads' page . The link is located under the name 'Tomcat Web Server Connectors'. Again, make sure you download mod_jk1.2 (JK 1.2 Binary Releases).


Rename the lib (or mod_jk.dll on Windows) and drop it in APACHE_HOME/modules directory.



  • Note:* the below conf files only work with mod-jk 1.2.10 (or higher), 2.6 does not support several of the directives given



I had to build from source as the supplied binaries did not include RH Enterprise Linux

y build instructions are here


Step 3: Setup Apache


Add this line at the very bottom in APACHE_HOME/conf/httpd.conf :

               # Include mod_jk configuration file
               Include conf/mod-jk.conf


Under APACHE_HOME/conf, create mod-jk.conf and populate it as follows:

               # Load mod_jk module
               # Specify the filename of the mod_jk lib
               LoadModule jk_module modules/
               # Where to find
               JkWorkersFile conf/

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

               # 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></Location>
                   JkMount jkstatus
                   Order deny,allow
                   Deny from all
                   Allow from


mod_jk is ready to forward requests to JBoss instances. We need now to setup the workers


Step 5: Configuring workers


Under APACHE_HOME/conf, create and populate it as follows:

               # Define list of workers that will be used
               # for mapping requests
               # Define Node1
               #worker.node1.local_worker=1 (1)

               # Define Node2
               #worker.node2.local_worker=1 (1)

               # Load-balancing behaviour
               worker.loadbalancer.balanced_workers=node1, node2

               # Status worker for managing load balancer


(1) local_worker should be commented out to enable load-balancing. Otherwise, only fail-over is available.


Basically, this configures mod_jk to perform weighted round-robin load balancing with sticky sessions between two servlet containers node1 and node2(aka: Tomcat) listening on port 8009.


If you specify worker.loadbalancer.sticky_session=0, each request will be load balanced between node1 and node2. But when a user opens a Session on one server, it is a good idea to always forward this user's requests to the same server. Otherwise the user's session data would need to be synchronized between both servers. This is called a "sticky session", as the client is always using the same server he reached on his first request.

To enable session stickiness, you need to set worker.loadbalancer.sticky_session to 1.


Side Note: a non-loadbalanced setup with a single node required the "worker.list=node1" entry before mod_jk would function correctly. Without this setting I would only get a 500 error and no other useful messages in log or otherwise.  -Harlequin516


Side Note: I tried a non-loadbalanced setup with a single node with the "worker.list=loadbalancer" and it did work correctly for me. In fact "worker.list=node1" caused a 500 error and no other useful messages in log or otherwise. I am using apache 2.0.52 with  mod_jk 1.2.6. -amii_2009




Step 6: Restart Apache



Step 7: Configure Tomcat


To complete the configuration, we also need to name each node accordingly to the names specified in


Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/server.xml (replace /all with your own server name)


Locate the <Engine&133;.> element and add an attribute jvmRoute:

               <Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">

The jvmRoute attribute must match the name specified in


Finally, we need to tell Tomcat to add the jvmRoute value to its session cookies so that mod_jk can route incoming requests.


Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml (replace /all with your own server name)


Locate the element with a name of UseJK, and set its value to "true":

               <attribute name="UseJK">true</attribute>




JBoss Clustering Guide: Additional details about HTTP Session replication, and other goodies.


Configuring Tomcat and Apache With JK 1.2


Tomcat - Workers HowTo


Tomcat user-mail archive


mod_jk FAQ