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