JBoss AS 5.1 Web ApplicationClustering Guide
JBoss AS supports clustered web sessions, where a backup copy ofeach user's HttpSession stateis stored on one or more nodes in the cluster. In case the primary nodehandling the session fails or is shut down, any other node in the cluster canhandle subsequent requests for the session by accessing the backup copy. HTTPsession replication is used to replicate the state associated with web clientsessions to other nodes in a cluster. Thus, in the event one of your nodescrashes, another node in the cluster will be able to recover. Two distinctfunctions must be performed:
Ø Session state replication
Ø Load-balancing of incoming invocations
1. Configuring Session state replication
1.1. Launchinga JBoss AS Cluster
The simplest way to start aJBoss server cluster is to start several JBoss instances on the same localnetwork, using the -c all command line option for each instance. Those serverinstances will detect each other and automatically form a cluster. When you runJBoss in the all configuration, session state replication is enabled bydefault. Just configure your web application as <distributable/> in itsweb.xml (see Section 1.2, “Configuring YourWeb Application for Clustering”), deploy it, and its session state is automaticallyreplicated across all JBoss instances in the cluster.
Ø Scenario1: Nodes on Separate Machines
This is the most common productionscenario. Assume the machines are named "node1" and"node2", while node1 has an IP address of 192.168.0.101 and node2 hasan address of 192.168.0.102. Assume the "ServerPeerID" for node1 is 1and for node2 it's 2. Assume on each machine JBoss is installed in /opt/jboss.
On node1, to launch JBoss:
$ cd /opt/jboss/bin
$ ./run.sh -c all -g damac -b 192.168.0.101 -Djboss.messaging.ServerPeerID=1
On node2, it's the same except fora different -b value and ServerPeerID:
$ cd /opt/jboss/bin
$ ./run.sh -c all -g damac -b 192.168.0.102 -Djboss.messaging.ServerPeerID=2
Ø Scenario 2:Two Nodes on Single Server
Single machine only has one IPaddress available. Two processes can't bind sockets to the same address and port,so we'll have to tell JBoss to use different ports for the two instances. Thiscan be done by configuring the ServiceBindingManager service by setting thejboss.service.binding.set system property. The difference from Scenario 1 is weneed to be sure each AS instance has its own work area. So, instead of usingthe all config, we are going to use the node1 and node2 configs we copied fromall in the previous section.
To launch the first instance,open a console window and:
$ cd /opt/jboss/bin
$ ./run.sh -c node1 -g damac -b 192.168.0.101 -Djboss.messaging.ServerPeerID=1 -Djboss.service.binding.set=ports-default
For the second instance:
$ cd /opt/jboss/bin
$ ./run.sh -c node2 -g damac -b 192.168.0.101 -Djboss.messaging.ServerPeerID=2 -Djboss.service.binding.set=ports-01
That's it; that's all it takes toget a cluster of JBoss AS servers up and running.
1.2. Configuring Your Web Application forClustering
Thisaspect involves telling JBoss you want clustering behavior for a particular webapp, and it couldn't be simpler. Just add an emptydistributable elementto your application's web.xml file:
<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
version="2.5">
<distributable/>
.. .. ..
</web-app>
Simply doing that is enough to getthe default JBoss AS web session clustering behavior, which is appropriate formost applications.
2. Configuringload balancing using Apache and mod_jk
JBoss AS itself doesn't act as anHTTP load balancer. Web applications require an external load balancer tobalance HTTP requests across the cluster of JBoss AS instances. So, you willneed to set up a hardware or software load balancer. There are many possibleload balancer choices, at this document we use mod_jk as the load balancer. Lookfurther for details on how to set up the popular mod_jk software loadbalancer.
2.1. Downloadthe software
First of all, make sure that youhave Apache installed. You can download Apache directly from Apache web site athttp://httpd.apache.org. Itsinstallation is pretty straightforward and requires no specific configuration.As several versions of Apache exist, we advise you to use the latest stable2.2.x version.
Next, download mod_jk binaries.Several versions of mod_jk exist as well. We strongly advise you to use mod_jk1.2.x. The mod_jk 1.2.x binary can be downloaded fromhttp://tomcat.apache.org/download-connectors.cgi/.Unzip the downloaded file and copymod_jk.so
under APACHE_HOME/modules/
.
2.2. ConfigureApache to load mod_jk
Modify APACHE_HOME/conf/httpd.conf and add asingle line at the end of the file:
# Include mod_jk's specific configurationfile
Include conf/mod-jk.conf
Next, create a new file named APACHE_HOME/conf/mod-jk.conf:
# 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
JkOptions +ForwardKeySize +ForwardURICompat-ForwardDirectories
# JkRequestLogFormat
JkRequestLogFormat "%w %V %T"
# Mount your applications
JkMount /* loadbalancer
# 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/>
JkMount status
Order deny,allow
Denyfrom all
Allow from 127.0.0.1
</Location>
Please note that two settings are veryimportant:
Ø The LoadModule directive must reference the mod_jk library you havedownloaded in the previous section. You must indicate the exact same name withthe "modules" file path prefix.
Ø The JkMount directive tells Apache which URLs it should forward to themod_jk module (and, in turn, to the Servlet containers). In the above file, allrequests are sent to the mod_jk load-balancer. This way, you canconfigure Apache to serve static contents (or PHP contents) directly and onlyuse the loadbalancer for Java applications. If you only use mod_jk as aloadbalancer, you can also forward all URLs (i.e., /*) to mod_jk.
You will most probably not change the othersettings in mod_jk.conf. Theyare used to tell mod_jk where to put its logging file, which logging level touse and so on.
2.3. Configureworker nodes in mod_jk
Next, you need to configuremod_jk workers file conf/workers.properties
. This file specifieswhere the different Servlet containers are located and how calls should beload-balanced across them. The configuration file contains one section for eachtarget servlet container and one global section. For a two nodes setup, thefile could look like this:
# Define list of workers that will be used
# for mapping requests
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.cachesize=10
# 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.node2.cachesize=10
# Load-balancing behaviour
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
worker.loadbalancer.sticky_session=1
#worker.list=loadbalancer
# Status worker for managing load balancer
worker.status.type=status
Basically, the above fileconfigures mod_jk to perform weighted round-robin load balancing with stickysessions between two servlet containers (i.e. JBoss AS instances) node1 andnode2 listening on port 8009.
2.4. ConfiguringJBoss to work with mod_jk
Finally, we must configurethe JBoss AS instances on all clustered nodes so that they can expect requestsforwarded from the mod_jk loadbalancer.
On each clustered JBoss node,we have to name the node according to the name specified inworkers.properties
. For instance, on JBossinstance node1, edit theJBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml
file (replace /all
withyour own server name if necessary). Locate the <Engine>
elementand add an attribute jvmRoute
:
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">
... ...
</Engine>
You also need to be sure theAJP connector in server.xml is enabled (i.e., uncommented). It is enabled bydefault.
<!-- An AJP 1.3 Connector on port 8009 -->
<Connector protocol="AJP/1.3" port="8009" address="${jboss.bind.address}"
redirectPort="8443" />
At this point, you have afully working Apache+mod_jk load-balancer setup that will balance call to theServlet containers of your cluster while taking care of session stickiness(clients will always use the same Servlet container).
3. References
· JBoss AS 5.1 Administration and ConfigurationGuide - http://docs.jboss.org/jbossas/docs/Administration_And_Configuration_Guide/5/html_single/index.html
· JBoss AS 5.1 Clustering Guide - http://docs.jboss.org/jbossclustering/cluster_guide/5.1/html-single/index.html
· JBoss mod_cluster Documentation - http://docs.jboss.org/mod_cluster/1.2.0/html/