Using Mod_jk 1.2 with JBoss
Using mod_jk 1.2.x with JBoss/Tomcat bundle and Apache2
Quick Overview
- Download Apache2
- Download modjk 1.2.x
- Change the main Apache config to include modjk config
- Create the modjk config
- Configure the modjk workers (which JBoss/Tomcat nodes Apache uses)
- Configure the Apache URIs served by modjk (the applications served by JBoss/Tomcat)
- Restart Apache
- Configure Tomcat (Give each JBoss/Tomcat a jvmRoute for session stickness)
- Restart JBoss
- Test it
More Details
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 Apache.org 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 Tomcats’s ‘Download Tomcat connector section’ page . Always download the latest stable release if possible.
Rename the lib mod_jk.so and drop it in APACHE_HOME/modules directory.
NOTE: Don’t use any release prior to mod_jk 1.2.15. Earlier releases are fairly buggy.
Note: Darwin Ports supports the installation of mod_jk on OS X. See http://darwinports.opendarwin.org/ for more info.
Step #3: Setup Apache to use modjk
Add this line at the very bottom in APACHE_HOME/conf/httpd.conf :
# Include mod_jk configuration file
Include conf/mod-jk.conf
Step #4: Create the modjk config
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/mod_jk.so
# Where to find workers.properties
JkWorkersFile conf/workers.properties
# 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
# Note: Changed from +ForwardURICompat.
# See http://tomcat.apache.org/security-jk.html
JkOptions +ForwardKeySize +ForwardURICompatUnparsed -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/uriworkermap.properties
# 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
# Note: Replaced JkShmFile logs/jk.shm due to SELinux issues. Refer to
# https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=225452
JkShmFile run/jk.shm
# Add jkstatus for managing runtime data
<Location /jkstatus/>
JkMount status
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>
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 workers.properties and populate it as follows:
# Define list of workers that will be used
# for mapping requests
# The configuration directives are valid
# for the mod_jk version 1.2.18 and later
#
worker.list=loadbalancer,status
# Define Node1
# modify the host as your host IP or DNS name.
worker.node1.port=8009
worker.node1.host=node1.mydomain.com
worker.node1.type=ajp13
worker.node1.lbfactor=1
# worker.node1.connection_pool_size=10 (1)
# Define Node2
# modify the host as your host IP or DNS name.
worker.node2.port=8009
worker.node2.host= node2.mydomain.com
worker.node2.type=ajp13
worker.node2.lbfactor=1
# worker.node1.connection_pool_size=10 (1)
# Load-balancing behaviour
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
# Status worker for managing load balancer
worker.status.type=status
Important: Please review http://tomcat.apache.org/connectors-doc/reference/workers.html for the directive descriptions. Especially lookout for the comments on cachsize for Apache 1.3.x.
(1) You should only set the connection_pool_size if the number of allowed connection to the Httpd is higher than maxThreads in server.xml
If you specify worker.loadbalancer.sticky_session=Off, 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. Session stickiness is enabled by default.
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 both loadbalanced and single node methods on Fedora 4. Both setups causing jk.shm errno=13 and jk-runtime-status errno=13 in the mod_jk.log. Could only get 500 errors. As a last resort disabled selinux on apache server. Restarted service and connection was made first try. -paulbrown
Step #6: Create the URI to worker map file
Create a uriworkermap.properties file in the APACHE_HOME/conf directory. This file should contain the URL mappings you want Apache to forward to Tomcat. The format of the file is /url=worker_name. To get things started, paste this example into the file you created:
# Simple worker configuration file
#
# Mount the Servlet context to the ajp13 worker
/jmx-console=loadbalancer
/jmx-console/*=loadbalancer
/web-console=loadbalancer
/web-console/*=loadbalancer
This will configure mod_jk to forward requests to /jmx-console and /web-console to Tomcat. Step #7: Restart Apache
Step #8: Configure Tomcat
To complete the configuration, we also need to name each node accordingly to the names specified in workers.properties.
Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/server.xml (replace /all with your own server name)
Locate the <Engine….> element and add an attribute jvmRoute:
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">
.
</Engine>
The jvmRoute attribute must match the name specified in workers.properties. In the server.xml file, make sure that the AJP 1.3 Connector is uncommented, e.g.:
<!-- A AJP 1.3 Connector on port 8009 -->
<Connector port="8009" address="${jboss.bind.address}"
emptySessionPath="true" enableLookups="false" redirectPort="8443"
protocol="AJP/1.3"/>
If you are only accepting requests via mod_jk, you can comment out the regular HTTP Connector; Tomcat then won’t listen on port 8080.
Step #9: Activate the UseJK Valve in JBoss (not needed with Tomcat Standalone)
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 <attribute> element with a name of UseJK, and set its value to “true”:
<attribute name="UseJK">true</attribute>
Note that tomcat version can be 50 or 55 depending on the AS that you use. Step #10: Restart JBoss AS.
Step #11: Access the JBoss AS web-console through Apache by browsing to http://localhost/web-console and you should see the JBoss web console page.
Note: to use mod_jk with Jboss 2 (e.g. jboss 2.4.6), you must edit jboss.jcml. Add the ‘jvmRoute=<<myWorker>>’ to the Engine element under the
EmbeddedCatalinaSX? mbean.
