By Georges Goebel and Marc Calvisi
03 March 2005
Version : 2.2
This configuration uses the Apache/Tomcat plug-in mod_jk. This plug-in allows use of the Apache HTTP server in front of one or several Tomcat JSP/Servlet engines, and provides the capability of forwarding some of the HTTP requests (typically those 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.
This document describes one architecture with all the clustering functionalities available in JOnAS, the configuration of architectures integrating one of those functionalities, and other possible configurations.
The content of this guide is the following:
The versions assumed here are: Apache 2.0, Mod_jk 1.2.8, JOnAS 4.4..x/Tomcat 5.5.x package.
The architecture presented in this document is shown in the following illustration:
This architecture provides:
This example uses mod_jk, but an alternative configuration using Enhydra Director is also possible. (see config)
Note: this module can also be used for site partitioning.
The easiest way to obtain this plug-in is to download the binary from the Tomcat
Site and place it in the directory libexec (for unix) or modules (for
windows or Mandrake) of the Apache installation directory.
For further installion information, refer to the Tomcat Site.
This depends on the distribution being used. Create a file tomcat_jk.conf and workers.properties in "$APACHE_HOME/conf/jk/".
tomcat_jk.conf:
# Location of the worker file
JkWorkersFile "$APACHE_HOME/conf/jk/workers.properties"
# Location of the log file
JkLogFile "$APACHE_HOME/conf/jk/logs/mod_jk.log"
# Log level : debug, info, error or emerg
JkLogLevel emerg
# Shared Memory Filename ( Only for Unix platform )
# required by loadbalancer
JkShmFile $APACHE_HOME/conf/jk/logs/jk.shm
# Assign specific URL to Tomcat workers
# A mount point from a context to a Tomcat worker
JkMount /admin loadbalancer
JkMount /admin/* loadbalancer
JkMount /examples loadbalancer
JkMount /examples/* loadbalancer
# A mount point to the status worker
JkMount /jkmanager jkstatus
JkMount /jkmanager/* jkstatus
# Enable the Jk manager access only from localhost
<Location /jkmanager/>>
JkMount jkstatus
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>
The following is an example of a worker.properties file:
# List the workers' names
worker.list=loadbalancer,jkstatus
# ----------------
# First worker
# ----------------
worker.worker1.port=9009
worker.worker1.host=server1
worker.worker1.type=ajp13
# Load balance factor
worker.worker1.lbfactor=1
# Define preferred failover node for worker 1
#worker.worker1.redirect=worker2
# ----------------
# Second worker
# ----------------
worker.worker2.port=9010
worker.worker2.host=server2
worker.worker2.type=ajp13
worker.worker2.lbfactor=1
# Disable worker2 for all requests except failover
#worker.worker2.disabled=True
# ----------------------
# Load Balancer worker
# ----------------------
worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=worker1,worker2
#Specifies whether requests with session's id should be routed to the same worker
#worker.loadbalancer.sticky_session=false
# ----------------------
# jkstatus worker
# ----------------------
worker.jkstatus.type=status
Explanations: | |
port: | Port number of the remote Tomcat instance listening for defined protocol requests |
host: | Host name or IP address of the backend Tomcat instance |
type: | Type of the worker (can be one of ajp13, ajp14, jni, status or lb) |
The status worker makes it possible to manage loadbalancing parameters and status through a web interface. In the above example, use URL http://localhost/jkmanager | |
lbfactor: | An integer number indicating how much a worker has to work |
example: worker1.lbfactor = 2 worker2.lbfactor = 1 worker1 receives 2 times more requests than worker2 | |
sticky_session : | Round robin where the mod_jk sends the request to a server. When session replication is activated in JOnAS, the session will not be lost. |
redirect: | worker name to use when the current worker is in error state |
disabled: | True/False - default status of the current worker |
the redirect/disabled parameters makes it possible to define a failover configuration between 2 workers. In the above example, the lb redirects the requests to worker 2 if worker 1 is in error state. In other cases, worker 2 will not receive any requests, thus acting as a hot standby. |
Note: Refer to the workers.properties and workers howto documentation.
Other possible mod_jk configurations (includes mod_jk2, mod_jk, migration mod_jk2 to mod_jk)
Attention: mod_jk2 is deprecated.
LoadModule jk_module modules/mod_jk.so (for windows)
LoadModule jk_module libexec/mod_jk.so (for Unix)
AddModule mod_jk.c
Include $APACHE_HOME/conf/jk/tomcat_jk.conf
<!-- Define an AJP 1.3 Connector on port 9009 -->
<Connector
port="9009" minProcessors="5"
maxProcessors="75"
acceptCount="10" debug="20" protocol="AJP/1.3"/>
Explanations: | |
port: | The TCP port number on which this Connector will create a server socket and await incoming connections. |
minProcessor: | The minimum number of processors to start at intialization time. If not specified, this attribute is set to 5. |
maxProcessor: | The maximum number of processors allowed. |
acceptCount: | The maximum queue length for incoming connection requests when all possible requests processing threads are in use. Any requests received when the queue is full will be refused. |
debug: | The debugging detail level of log messages generated by this component, with higher numbers creating more detailed output. |
protocol: | This attribute must be AJP/1.3 to use the AJP handler. |
Note: Refer to the AJP Connector documentation.
Explanations: | |
name: | Logical name of this Engine, used in log and error messages |
jvmRoute: | Uniquely identifies the Tomcat server to the Apache server Name has been specified in the workers.properties |
defaultHost: | Identifies the Host that will process requests directed to host names on this server |
debug: | The level of debugging detail logged by this Engine |
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.
Refer to the Engine Container documentation.
The following is an example of a 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>
Note: It is mportant to adhere to the launching order; otherwise, it will not work correctly.
The term session replication is used when the current service state is being replicated across multiple application instances. Session replication occurs when the information stored in an HttpSession is replicated from, in this example, one servlet engine instance to another. This could be data such as items contained in a shopping cart or information being entered on an insurance application. Anything being stored in the session must be replicated for the service to failover without a disruption.
The solution chosen for achieving Session replication is called all-to-all replication. Tomcat uses a proprietary protocol based on TCP for the all-to-all replication.
The follow describes the steps for achieving Session replication with JOnAS.
Note: The multicast address and port must be identically configured for all JOnAS/Tomcat instances.
In the case of EJB level clustering (CMI), the client may be either a fat Java client (e.g. a Swing application), or a Web application (i.e. Servlets/JSPs running within JOnAS). In the second case, the JOnAS server running the Web client should be configured in the same way as the other nodes of the cluster.
Note 1: The multicast address and group name must be the same for all JOnAS servers in the cluster.
Note 2: If Tomcat Replication associated to cmi is used, the multicast addresses of the two configurations must be different.
![]() |
A node (computer) that hosts one or more servers | ||
![]() |
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 |