Clustering with JOnAS
This guide describes how to configure Apache, Tomcat and JOnAS to install
a cluster.
This configuration uses the Apache/Tomcat plug-in mod_jk. This plug-in
allows to use Apache HTTP server in front of one or several Tomcat JSP/Servlet
engines, and to forward some of the HTTP requests (generally the ones concerning
the dynamic pages, i.e. JSP and Servlet requests) to Tomcat instances.
It also uses the In-Memory-Session-Replication technique based on the
group communication protocol JavaGroups to provide failover at servlet/JSP
level.
For the Load balancing at EJB level, a clustered JNDI called cmi is
used.
Here after is described one architecture with all the clustering functionalities
available in JOnAS, the configuration of architures integrating one of
those functionalities, and other possible configurations.
Architecture
The architecture with all the clustering functionalities available in JOnAS
is : Apache as the front-end HTTP server, JOnAS/Tomcat as J2EE Container,
and a shared database.
At the Servlet / JSP level, the mod_jk plug-in will
provide Load Balancing / High Availability and the Tomcat-Replication module
provides Failover.
At the EJB level, the clustered JNDI cmi provides
Load Balancing / High Availability.
The database is shared by the JOnAS servers.
The versions considered here are : Apache 2.0, JOnAS 3.1.x/Tomcat 4.1.x
package.
The architecture presented in this document is :

This architecture provides :
-
Load balancing : Requests may be dispatched over a set of servers
in order to distribute the load. This improves the "scalability" by allowing
to process more requests concurrently.
-
High Availability (HA) : having several servers able to fulfill
a resquest makes possible to ensure that if a server dies, the request
may be sent to an available server (so the load balancing algorithme may
just ensure that the server to which the request will be sent is available).
Thus "Service Availability" may be achieved.
-
Failover at Servlet / JSP Level : This feature insures that if one
JSP/servlet server goes down, then another server is able to transparently
take over, i.e. the request will be switched to another server, without
service disruption. This means that the user will not have to start over.
This way Continuity may be achieved.
However, failover at EJB level is not provided yet. This means that
no State Replication is provided. The mechanism to provide failover at
EJB level is under development and will be available in a coming version
of JOnAS.
Products Installation
First of all, you need to install the different products. The version considered
here are : Apache 2.0 and the package JOnAS 3.1.x /Tomcat 4.1.x.
Installing Apache
-
Download Apache HTTP server source code at Apache
site
-
Extract the source code
gunzip httpd-2_0_XX.tar.gz
tar xvf httpd-2_0_XX.tar
-
Compile and Install
./configure
make
make install
You may also install a binary version. See on the Apache site.
Installing the package JOnAS / Tomcat
See Installing JOnAS with a
web container from scratch.
Load balancing at web level with mod_jk
The aim of this chapter is to configure Apache, Tomcat and JOnAS to run
the following architecture :

Configuring the JK Module
JK module principles
Mod_jk is a plug-in that handles the communication between Apache and Tomcat.
Mod_jk uses the concept of worker . A worker is a Tomcat instance that
is running to serve servlet requests coming from the web server. Each worker
is identified to the web server by the host where it is located, the port
where it listen and the communication protocol used to exchange messages.
In our configuration there is one worker for each Tomcat instance and one
worker that will handle the load balancing (this is a particular worker
with no host and no port number). All those workers are defined in a file
worker.properties.
Note : this module can also be used for site partitioning.
install Mod_jk
The easiest is to download the binary on the Tomcat
Site. Put this file in the directory libexec (for unix) or modules
(for windows or Mandrake) of the installation directory of Apache.
Configure Apache
-
httpd.conf
Create a file tomcat_jk.conf that has to be included in $APACHE_HOME/conf/httpd.conf
This file should load the module mod_jk :
LoadModule jk_module modules/mod_jk.so (for windows)
LoadModule jk_module libexec/mod_jk.so (for Unix)
AddModule mod_jk.c
And configure mod_jk :
# Location of the worker file
JkWorkersFile "/etc/httpd/conf/jk/workers.properties"
# Location of the log file
JkLogFile "/etc/httpd/jk/logs/mod_jk.log"
# Log level : debug, info, error or emerg
JkLogLevel emerg
# Assign specific URL to Tomcat workers
JkMount /admin loadbalancer
JkMount /admin/* loadbalancer
JkMount /examples loadbalancer
JkMount /examples/* loadbalancer
-
worker.properties
This file should first contain the list of workers :
worker.list=<a comma separated list of worker names>
then the properties of each worker :
worker.<worker name>.<property>=<property value>
Here is an example of what a worker.properties file should look like
:
# List the workers name
worker.list=worker1,worker2,loadbalancer
# ----------------
# First worker
# ----------------
worker.worker1.port=8009
worker.worker1.host=server1
worker.worker1.type=ajp13
# Load balance factor
worker.worker1.lbfactor=1
# ----------------
# Second worker
# ----------------
worker.worker2.port=8009
worker.worker2.host=server2
worker.worker2.type=ajp13
worker.worker2.lbfactor=1
# ----------------------
# Load Balancer worker
# ----------------------
worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=worker1,worker2
Configure Tomcat
The following configuration steps should be done for each Tomcat server.
-
Configure Tomcat for the connector AJP13
In the file conf/server.xml of your JOnAS installation directory, add
(if not already there) :
<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
port="8009" minProcessors="5" maxProcessors="75"
acceptCount="10" debug="20"/>
-
Define the jvmRoute
In the file conf/server.xml of your JOnAS installation directory, a
unique route to the Catalina engine should be added :
Replace the line :
<Engine name="Standalone" defaultHost="localhost" debug="0">
with :
<Engine jvmRoute="worker1" name="Standalone" defaultHost="localhost"
debug="0">
Note : the jvmRoute name should be the same as the name of the associated
worker defined in worker.properties. This will ensure the Session affinity.
Configuring JOnAS
In the JOnAS specific deployment descriptor you should add the tag shared
for the involved entity beans and set it to true. When this flag
is set to true, multiple instance of the same entity bean in different
JOnAS servers can access a common database concurrently.
Here is an example of deployment descriptor with the flag shared:
<jonas-ejb-jar>
<jonas-entity>
<ejb-name>Id_1</ejb-name>
<jndi-name>clusterId_1</jndi-name>
<shared>true</shared>
<jdbc-mapping>
<jndi-name>jdbc_1</jndi-name>
<jdbc-table-name>clusterIdentityEC</jdbc-table-name>
<cmp-field-jdbc-mapping>
<field-name>name</field-name>
<jdbc-field-name>c_name</jdbc-field-name>
</cmp-field-jdbc-mapping>
<cmp-field-jdbc-mapping>
<field-name>number</field-name>
<jdbc-field-name>c_number</jdbc-field-name>
</cmp-field-jdbc-mapping>
<finder-method-jdbc-mapping>
<jonas-method>
<method-name>findByNumber</method-name>
</jonas-method>
<jdbc-where-clause>where
c_number = ?</jdbc-where-clause>
</finder-method-jdbc-mapping>
<finder-method-jdbc-mapping>
<jonas-method>
<method-name>findAll</method-name>
</jonas-method>
<jdbc-where-clause></jdbc-where-clause>
</finder-method-jdbc-mapping>
</jdbc-mapping>
</jonas-entity>
</jonas-ejb-jar>
Running your Web Application
You are now ready to run your web application:
-
start the jonas servers : jonas start
-
Restart Apache : /usr/local/apache2/bin/apachectl restart
-
Use your browser to access the welcome page, usually index.html
Session Replication
The aim of this chapter is to configure Apache, Tomcat and JOnAS to run
the following architecture :

Session replication is the term that is used when your current service
state is being replicated across multiple application instances. Session
replication occurs when we replicate the information that is stored in
your HttpSession from, in our case, one servlet engine instance to another.
This could be data like the items that you have in your shopping cart.
It could also be the information that your are entering on an insurance
application. Whatever is being stored in your session has to be replicated
in order for the service to fail over without a disruption.
The solution chosen to achieve Session replication is called in-memory-session-replication.
It uses a group communication protocol written entirely in Java called
JavaGroups. JavaGroups is a communication protocol based on the idea of
virtual synchrony and probabilistic broadcasting.
Hereafter are the steps to achieve Session replication with JOnAS.
-
To illustrate the Session Replication, we chose to use the mod_jk. So you
have to perform the configuration steps presented in the chapter Load Balancing
at Web level with mod_jk
-
On the JOnAS servers, open the <JONAS_BASE>/conf/server.xml
file and configure your <context> as described :
<Context path="/replication-example" docBase="replication-example"
debug="99"
reloadable="true" crossContext="true"
className="org.objectweb.jonas.web.catalina41.JOnASStandardContext">
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="localhost_replication_log." suffix=".txt"
timestamp="true"/>
<Valve className="org.apache.catalina.session.ReplicationValve"
filter=".*\.gif;.*\.jpg;.*\.jpeg;.*\.js" debug="0"/>
<Manager className="org.apache.catalina.session.InMemoryReplicationManager"
debug="10"
printToScreen="true"
saveOnRestart="false"
maxActiveSessions="-1"
minIdleSwap="-1"
maxIdleSwap="-1"
maxIdleBackup="-1"
pathname="null"
printSessionInfo="true"
checkInterval="10"
expireSessionsOnShutdown="false"
serviceclass="org.apache.catalina.cluster.mcast.McastService"
mcastAddr="237.0.0.1"
mcastPort="45566"
mcastFrequency="500"
mcastDropTime="5000"
tcpListenAddress="auto"
tcpListenPort="4001"
tcpSelectorTimeout="100"
tcpThreadCount="2"
useDirtyFlag="true">
</Manager>
</Context>
Note : The multicast address and port have to be identically configured
for
all JOnAS/Tomcat instances.
Running your Web Application
You are now ready to run your web application in the cluster :
-
start the JOnAS servers : jonas start
-
Restart Apache : /usr/local/apache2/bin/apachectl restart
-
Use your browser to access the welcome page, usually index.html
Load Balancing at EJB level
The aim of this chapter is to configure JOnAS to run
the following architecture :
CMI Principles
CMI is a new ORB used by JOnAS to provide clustering for load balancing and
high availability. Several instances of JOnAS may be started together in a
cluster to share their EJBs. It is possible to start the same EJB on each
JOnAS, or to distribute their repartition. An URL referencing several JOnAS
instances may be provided to the clients. At lookup time, a client chooses
randomly one of the servers available, to ask the bean it is looking for.
Each JOnAS instance has the knowledge (through Javagroups) of the repartition
of the Beans in the cluster. An answer to a lookup is a special clustered
stub, containing stubs to each instance known in the cluster. Each method
call on the Home of the bean can be issued by the stub to a new instance, to
balance the load on the cluster. The default algorithm used for load
repartition is currently a weighted round robin.
CMI Configuration
-
In the build.properties of your application, the protocol name has to be set to cmi
before compilation :
protocols.names=cmi
-
In the file carol.properties of the directory $JONAS_BASE/conf the protocol should be set to cmi :
carol.protocols=cmi
-
In the file carol.properties, you can also configure the multicast address, the group name,
the round robin weight factor...
Hereafter is an example of configuration :
# java.naming.provider.url property
carol.cmi.url=cmi://localhost:2002
# Multicast address used by the registries in the cluster
carol.cmi.multicast.address=224.0.0.35:35467
# Groupname for Javagroups
carol.cmi.multicast.groupname=G1
# Factor used for this server in wheighted round robin algorithms
carol.cmi.rr.factor=100
-
For the client, you have to specify in the carol.properties file the list of registries available :
carol.cmi.url=cmi://server1:port1[,server2:port2...]
Note 1 : the multicast address and group name have to be the same for all the JOnAS servers in
the cluster
Note 2 : if you are using Tomcat Replication associated to cmi, the multicast addresses of the
2 configurations have to be different
In a coming version...
We are currently developing a solution to enable failover at EJB level. This means state replication
for statefull session beans and entity beans.
This will enable the following architecture :
Used symbols
 |
A node (computer) that hosts one or more server |
 |
A web container |
 |
An ejb container |
 |
A JOnAS instance that hosts a web container |
 |
A JOnAS instance that hosts an ejb container |
 |
A JOnAS instance that hosts a web container and an ejb container |
 |
An Apache server with the mod_jk module |
References