JBoss Enterprise Application

Platform 5
HTTP Connectors Load Balancing
Guide
HTTP load-balancing for JBoss Enterprise Application Platform
Edition 5.2.0

Jared Morgan
Samuel Mendenhall

Joshua Wulf
James Livingston

Laura Bailey
Jim Tyrell

JBoss Enterprise Application Platform 5 HTTP Connectors Load

Balancing Guide

HTTP load-balancing for JBoss Enterprise Application Platform

Edition 5.2.0

Jared Mo rgan
Jo shua Wulf
Laura Bailey
Samuel Mendenhall
James Livingsto n
Jim Tyrell

Edited by
Eva Ko palo va
Petr Penicka
Russell Dickenso n
Sco tt Mumfo rd

Legal Notice
Copyright 2012 Red Hat, Inc.
T his document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported
License. If you distribute this document, or a modified version of it, you must provide attribution to Red
Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be
removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section
4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo,
and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux is the registered trademark of Linus T orvalds in the United States and other countries.
Java is a registered trademark of Oracle and/or its affiliates.
XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL is a registered trademark of MySQL AB in the United States, the European Union and other
countries.
Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related to or
endorsed by the official Joyent Node.js open source or commercial project.
T he OpenStack Word Mark and OpenStack Logo are either registered trademarks/service marks or
trademarks/service marks of the OpenStack Foundation, in the United States and other countries and
are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
Read this guide to install and configure the supported HT T P connectors for use with JBoss Enterprise
Application Platform and JBoss Enterprise Web Server. T his guide covers the Apache T omcat
Connector (mod_jk), JBoss HT T P Connector (mod_cluster), Internet Server API (ISAPI) and Netscape
Server API (NSAPI), and discusses clustering and load-balancing with regard to each.

Table of Contents

Table of Contents
.Preface
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . .
1. File Name Conventions
5
2. Document Conventions
5
2.1. T ypographic Conventions
6
2.2. Pull-quote Conventions
7
2.3. Notes and Warnings
8
3. Getting Help and Giving Feedback
8
3.1. Do You Need Help?
8
3.2. Give us Feedback
8
. . . . . I.
Part
. . Apache
........T
. .omcat
. . . . . . .Connector
. . . . . . . . . . . (mod_jk)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
............
. . . . . . . . . 1.
Chapter
. . .Overview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
............
. . . . . . . . . 2.
Chapter
. . .Download
. . . . . . . . . . .and
. . . .install
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
............
.Chapter
. . . . . . . . 3.
. . .Configure
. . . . . . . . . . load
. . . . . balancing
. . . . . . . . . . .using
. . . . . . Apache
. . . . . . . . HT
. . .T
. .P. .Server
. . . . . . . and
. . . . .mod_jk
. . . . . . . . . . . . . . . . . . . .13
...........
3.1. Configure worker nodes in mod_jk
15
3.2. Configuring JBoss to work with mod_jk
16
.Chapter
........4
. ...T. roubleshooting
. . . . . . . . . . . . . . . . .and
. . . .optimizing
. . . . . . . . . . . mod_jk
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
............
4.1. Common Problems
18
4.2. General Diagnostics
23
4.3. Getting Further Help
24
. . . . . II.
Part
. . .JBoss
. . . . . . .HT
..T
. .P. .Connector
. . . . . . . . . . . (mod_cluster)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
............
.Chapter
. . . . . . . . 5.
. . .Overview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
............
5.1. Key features
26
5.2. Components
26
5.3. Limitations
27
.Chapter
. . . . . . . . 6.
. . .Install
. . . . . . .proxy
. . . . . .server
. . . . . . . components
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
............
6.1. Apache HT T P Server modules
29
6.1.1. mod_manager.so
29
6.1.2. mod_proxy_cluster.so
31
6.1.3. mod_advertise.so
32
6.2. Install proxy server components
33
.Chapter
. . . . . . . . 7.
. . .Configure
. . . . . . . . . . .basic
. . . . . .proxy
. . . . . .server
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
...........
7.1. Basic proxy configuration overview
35
7.2. Configure a load-balancing proxy using the HT T P Connector
35
.Chapter
. . . . . . . . 8.
. . .Install
. . . . . . .node
. . . . . with
. . . . . basic
. . . . . . configuration
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
...........
8.1. Worker node requirements
37
8.2. Install and configure a worker node
37
.Chapter
. . . . . . . . 9.
. . .Advanced
. . . . . . . . . . .configuration
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. .1. . . . . . . . . .
9.1. Static proxy configuration
41
9.2. Clustered node operation
42
.Chapter
. . . . . . . . 10.
. . . . Java
. . . . . .Properties
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. .4. . . . . . . . . .
10.1. Configuration Properties
44
10.1.1. Proxy Discovery Configuration
44

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

10.1.2. Proxy Configuration

10.1.3. SSL Configuration
10.1.4. HA Configuration
10.1.5. Load Configuration

46
48
49
50

.Chapter
. . . . . . . . 11.
. . . . Load
. . . . . .Metrics
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
............
11.1. Server-Side Load Metrics
51
11.2. Web Container metrics
52
11.3. System/JVM metrics
54
11.4. Other metrics
55
.Chapter
. . . . . . . . 12.
. . . . Load
. . . . . .balancing
. . . . . . . . . . demonstration
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
............
12.1. Set up the demonstration
56
12.2. Configure the demo client
58
12.3. Interact with the demonstration
59
12.3.1. Generate artificial load
60
. . . . . III.
Part
. . . Internet
. . . . . . . . . Server
. . . . . . . .API
. . . .(ISAPI)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
...........
.Chapter
. . . . . . . . 13.
. . . .Overview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
............
13.1. What is Internet Server API
64
.Chapter
. . . . . . . . 14
. . . .. Configuring
. . . . . . . . . . . . .the
. . . .ISAPI
. . . . . .connector
. . . . . . . . . . .on
. . .Windows
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
............
14.1. Prerequisites and configuration assumptions
65
14.2. Configure server instance as a worker node
65
14.3. Microsoft IIS 6 initial clustering configuration
66
14.4. Microsoft IIS 7 initial clustering configuration
67
14.5. Configure a basic cluster with ISAPI
69
14.6. Configure a load-balancing cluster with ISAPI
72
. . . . . IV.
Part
. . . Netscape
. . . . . . . . . . .Server
. . . . . . . API
. . . . (NSAPI)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
............
. . . . . . . . . 15.
Chapter
. . . . What
. . . . . .is
. . Netscape
. . . . . . . . . . .Server
. . . . . . .API?
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
............
.Chapter
. . . . . . . . 16.
. . . . Configuring
. . . . . . . . . . . . .the
. . . .NSAPI
. . . . . . .connector
. . . . . . . . . . .on
. . .Solaris
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
............
16.1. Prerequisites and configuration assumptions
78
16.2. Configure server instance as a worker node
78
16.3. Initial clustering configuration
79
16.4. Configure a basic cluster with NSAPI
80
16.5. Configure a load-balanced cluster with NSAPI
82
. . . . . V.
Part
. . .Common
. . . . . . . . . load
. . . . . balancing
. . . . . . . . . . .tasks
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
............
.Chapter
. . . . . . . . 17.
. . . . HT
. . .T. P
. . session
. . . . . . . . .state
. . . . . .replication
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
............
17.1. Enabling session replication in your application
86
17.2. HttpSession passivation and activation
90
17.2.1. Configuring HttpSession passivation
90
17.3. Configure the JBoss Cache instance used for session state replication
91
.Chapter
. . . . . . . . 18.
. . . . High-Availability
. . . . . . . . . . . . . . . . . Web
. . . . . Sessions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
...........
18.1. DataSourcePersistentManager Configuration Attributes
95
.Chapter
. . . . . . . . 19.
. . . . Using
. . . . . . clustered
. . . . . . . . . . .Single
. . . . . . .Sign-on
. . . . . . . . (SSO)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
............
19.1. Configuration
99
19.2. SSO behavior
100
19.3. Limitations
100
19.4. Configuring the cookie domain
100

Table of Contents

. . . . . . . . . 20.
Chapter
. . . . Complete
. . . . . . . . . . .working
. . . . . . . . example
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
.............
. . . . . . . . . . . . workers.properties
Reference:
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
.............
.Reference:
. . . . . . . . . . . Java
. . . . . .properties
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
.............
B.1. Proxy configuration
108
. . . . . . . . . .history
Revision
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
.............

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Preface

Preface
1. File Name Conventions
T he following naming conventions are used in file paths for readability. Each convention is styled so that
it stands out from the rest of text:
JBOSS_EAP_DIST
T he installation root of the JBoss Enterprise Application Platform instance. T his folder contains
the main folders that comprise the server such as /jboss-as, /seam , and /resteasy.
JBOSS_EWP_DIST
T he installation root of the JBoss Enterprise Web Platform instance. T his folder contains the
main folders that comprise the server such as /jboss-as-web, /seam , and /resteasy.
JBOSS_EWS_DIST
T he installation root of the JBoss Enterprise Web Server instance. T his folder contains the
main folders that comprise the server such as /extras, /httpd, and the /tom cat6 folders.
NATIVE
T he installation root of the JBoss Native zip, extracted to the same directory level as
JBOSS_EAP_DIST.
SJWS
T he installation root of the Sun Java Web Server instance. T he default file locations for this
naming convention are:
for Solaris 10 x86 or SPARC 64: /opt/SUNWwbsrv70/
HTTPD_DIST
T he installation root of the Apache HT T P Server. T his folder contains the main folders that
comprise the server such as /conf, /webapps, and /bin. T he JBoss Enterprise Web Server
JBOSS_EWS_DIST directory contains the root installation of HTTPD_DIST.
PROFILE
T he name of the server profile you use as part of your testing or production configuration. T he
server profiles reside in JBOSS_EAP_DIST/jboss-as/server or JBOSS_EWP_DIST/jbossas-web/server.

2. Document Conventions
T his manual uses several conventions to highlight certain words and phrases and draw attention to
specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. T he

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Liberation Fonts set is also used in HT ML editions if the set is installed on your system. If not, alternative
but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation
Fonts set by default.

2.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. T hese
conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight
keys and key combinations. For example:
T o see the contents of the file m y_next_bestselling_novel in your current working
directory, enter the cat m y_next_bestselling_novel command at the shell prompt
and press Enter to execute the command.
T he above includes a file name, a shell command and a key, all presented in mono-spaced bold and all
distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of
a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
T he first example highlights a particular key to press. T he second example highlights a key combination:
a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values
mentioned within a paragraph will be presented as above, in m ono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for
directories. Each class has its own associated set of permissions.
Proportional Bold
T his denotes words or phrases encountered on a system, including application names; dialog box text;
labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose System Preferences Mouse from the main menu bar to launch Mouse
Preferences. In the Buttons tab, select the Left-handed m ouse check box and click
Close to switch the primary mouse button from the left to the right (making the mouse
suitable for use in the left hand).
T o insert a special character into a gedit file, choose Applications Accessories
Character Map from the main menu bar. Next, choose Search Find from the
Character Map menu bar, type the name of the character in the Search field and click
Next. T he character you sought will be highlighted in the Character T able. Double-click
this highlighted character to place it in the T ext to copy field and then click the Copy
button. Now switch back to your document and choose Edit Paste from the gedit menu
bar.
T he above text includes application names; system-wide menu names and items; application-specific
menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all

Preface

distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable
text. Italics denotes text you do not input literally or displayed text that changes depending on
circumstance. For example:
T o connect to a remote machine using ssh, type ssh username@ domain.name at a shell
prompt. If the remote machine is exam ple.com and your username on that machine is
john, type ssh john@ exam ple.com .
T he m ount -o rem ount file-system command remounts the named file system. For
example, to remount the /hom e file system, the command is m ount -o rem ount /hom e.
T o see the version of a currently installed package, use the rpm -q package command. It
will return a result as follows: package-version-release.
Note the words in bold italics above username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and
important term. For example:
Publican is a DocBook publishing system.

2.2. Pull-quote Conventions

T erminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in m ono-spaced rom an and presented thus:
books
books_tests

Desktop
Desktop1

documentation
downloads

drafts
images

mss
notes

photos
scripts

stuff
svgs

svn

Source-code listings are also set in m ono-spaced rom an but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object
ref
= iniCtx.lookup("EchoBean");
EchoHome
home
= (EchoHome) ref;
Echo
echo
= home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

2.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should
have no negative consequences, but you might miss out on a trick that makes your life easier.

Important
Important boxes detail things that are easily missed: configuration changes that only apply to the
current session, or services that need restarting before an update will apply. Ignoring a box
labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

3. Getting Help and Giving Feedback

3.1. Do You Need Help?
If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer
Portal at http://access.redhat.com. T hrough the customer portal, you can:
search or browse through a knowledgebase of technical support articles about Red Hat products.
submit a support case to Red Hat Global Support Services (GSS).
access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and
technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo.
Click on the name of any mailing list to subscribe to that list or to access the list archives.

3.2. Give us Feedback

If you find a typographical error, or know how this guide can be improved, we would love to hear from
you. Submit a report in Bugzilla against the product JBoss Enterprise Application Platform
5 and the component doc-HT T P_Connectors_Guide. T he following link will take you to a pre-filled
bug report for this product: http://bugzilla.redhat.com/.
Fill out the following template in Bugzilla's Description field. Be as specific as possible when
describing the issue; this will help ensure that we can fix it quickly.

Preface

Document URL:

Section Number and Name:

Describe the issue:

Suggestions for improvement:

Additional information:

Be sure to give us your name so that you can receive full credit for reporting the issue.

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Part I. Apache Tomcat Connector (mod_jk)

10

Chapter 1. Overview

Chapter 1. Overview
Apache HT T P Server ("Apache") is a well-known web server which can be extended using plug-ins. T he
Apache T omcat Connector mod_jk is a plug-in designed to allow request forwarding from Apache HT T P
Server to a servlet container. T he module also supports load-balancing HT T P calls to a set of servlet
containers while maintaining sticky sessions.
HT T P session replication is used to replicate the state associated with web client sessions to other
nodes in a cluster. If one node becomes unavailable, another node in the cluster continues to service the
failed node's requests. T his involves two distinct operations:
Session state replication
Load-balancing HT T P Requests
Session state replication is handled by JBoss per application, providing the application is configured to
make use of this feature (refer to Section 17.1, Enabling session replication in your application).
Load balancing must be handled externally to JBoss, via either hardware or software. A cost-effective
way of enabling load balancing is to set up a software load balancer using Apache HT T P Server and the
Apache T omcat Connector (mod_jk).

11

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 2. Download and install

Apache HT T P Server is included in the JBoss Enterprise Web Server binary you download from
https://access.redhat.com.
Apache mod_jk is included in the native installation binaries for JBoss Enterprise Application Platform
and JBoss Enterprise Web Server.
Follow the procedures in the JBoss Enterprise Application Platform or JBoss Enterprise Web Server
Installation Guide to download and install the correct platform and native binaries.

12

Chapter 3. Configure load balancing using Apache HTTP Server and mod_jk

Chapter 3. Configure load balancing using Apache HTTP

Server and mod_jk
Follow the tasks in this chapter to correctly configure load balancing using Apache HT T P Server and the
mod_jk connector.
T ask: Configure Apache HT T P Server to Load mod_jk
Complete this task to configure Apache HT T P Server to load mod_jk.
Prerequisites
Apache HT T P Server and mod_jk installed (Refer to Chapter 2, Download and install).

1. Open HTTPD_DIST/conf/httpd.conf and add the following text at the end of the file.
# Include mod_jk's specific configuration file
Include conf/mod-jk.conf

2. Create a new file named HTTPD_DIST/conf/m od-jk.conf

3. Add the following configuration block to m od-jk.conf.

13

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

# 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 /application/* 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
Deny from all
Allow from 127.0.0.1
</Location>

4. Confirm that the LoadModule directive references the right path for the mod_jk library. If not, edit
the path.
5. T he default configuration specifies that static content is served directly by Apache HT T P Server
and all requests with URL path /application/* are sent to the load balancer. If mod_jk is only
to be used as a load balancer, change the directive to /* .
6. Optional: JKMountFile Directive
In addition to the JkMount directive, you can use the JkMountFile directive to specify a mount
point's configuration file. T he configuration file contains multiple T omcat forwarding URL mappings.
a. Navigate to HTTPD_DIST/conf.
b. Create a file named uriworkerm ap.properties.
c. Specify the URL whose requests are to be forwarded and the name of the worker node to
which they are to be forwarded, using the following syntax example as a guide.
T he example block will configure mod_jk to forward requests to /jm x-console and
/web-console to Apache HT T P Server.
T he syntax required takes the form /url=worker_nam e.

14

Chapter 3. Configure load balancing using Apache HTTP Server and mod_jk

# Simple worker configuration file

# Mount the Servlet context to the ajp13 worker
/jmx-console=loadbalancer
/jmx-console/*=loadbalancer
/web-console=loadbalancer
/web-console/*=loadbalancer

d. In HTTPD_DIST/conf/m od-jk.conf, append the following directive.

# 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

3.1. Configure worker nodes in mod_jk

T ask: Configure mod_jk Worker Nodes
Complete this task to configure two mod_jk worker node definitions in a weighted round-robin
configuration with sticky sessions active between two servlet containers.
Prerequisites
Understand the format of the workers.properties directives, as specified in Appendix A, Reference:
workers.properties.

1. Navigate to HTTPD_DIST/conf/.
2. Create a file named workers.properties.
3. Append the following information to workers.properties.

15

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

# 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.ping_mode=A
worker.node1.lbfactor=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.ping_mode=A
worker.node2.lbfactor=1
# Load-balancing behavior
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
worker.loadbalancer.sticky_session=1
# Status worker for managing load balancer
worker.status.type=status

3.2. Configuring JBoss to work with mod_jk

T ask: Configure JBoss Enterprise Application Platform to Operate Using mod_jk
Complete this task to correctly prepare a JBoss Enterprise Application Platform instance on a clustered
node to receive forwarded requests from the mod_jk load balancer.
Repeat this task for each server instance you require, observing the warnings at each step.
Prerequisites
Complete T ask: Configure mod_jk Worker Nodes.

1. Navigate to the location of the clustered server instance.

2. Open JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy/jbossweb.sar/server.xm l.
3. Specify the node name by appending the jvm Route attribute to the <Engine> element in
server.xm l. T he jvmRoute attribute value is the node name defined in
HTTPD_DIST/conf/workers.properties.
<!--Preceeding syntax removed for readability -->
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">
<!--Proceeding syntax removed for readability -->
</Engine>

16

Chapter 3. Configure load balancing using Apache HTTP Server and mod_jk

Important
If you intend to configure more than one server node in a cluster, ensure you change the
jvmRoute attribute value to a unique name each time you repeat this step.
4. In server.xm l, ensure the AJP protocol <connector> element is enabled (uncommented). T he
element is uncommented by default in new installations.
<Connector protocol="AJP/1.3" port="8009" address="${jboss.bind.address}"
redirectPort="8443" />

5. You now have a correctly configured Apache HT T P Server with m od_jk load balancer, which
balances calls to the servlet containers in the cluster, and ensures clients will always use the
same servlet container (sticky sessions).

Note
For supplementary information about using mod_jk with JBoss, refer to the JBoss wiki page at
https://community.jboss.org/wiki/UsingModjk12WithJBoss.

17

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 4. Troubleshooting and optimizing mod_jk

While optimizing the configuration in Apache HT T P Server, mod_jk, mod_proxy, mod_cluster and JBoss
Enterprise Application Platform typically resolves any and all problems and errors in load balancing,
there are exceptions (such as long running servlets that require additional optimization).
In most cases, a correctly tuned configuration is the catch all for mod_jk issues. T his section discusses
some problems and how the configuration can be improved to avoid them.
Optimization Considerations
Ensure you are on the latest supported component versions.
Ensure the relevant configurations are tuned correctly. T he Red Hat Global Support Services staff
can use interactive tools to assist you with tailored configuration settings. Find the appropriate
contact details at https://access.redhat.com/support/.
If optimizing the configuration does not resolve the issue the problem is most likely on the JBoss/JVM
side. Refer to Procedure 4.5, JBoss/JVM Problems for advice about these issues.

4.1. Common Problems

T he list below outlines some common configuration problems. Ensuring your implementation is not
subject to one of these may assist to resolve your issue.
Specific errors and general performance issues are discussed later in this section.
Common Configuration Issues
JkShm File on a NFS share
Placing the JkShm File on a NFS share can cause unexplained pauses in mod_jk and odd
behavior. It is strongly recommended that the JkShm File always be placed on local storage to
avoid problems.
A firewall between Apache HT T P Server and JBoss Enterprise Application Platform
If there is a firewall between Apache HT T P Server and JBoss Enterprise Application Platform
and no socket_keepalive parameter is set, the firewall can close connections unexpectedly.
MaxClients higher than maxThreads
Setting the MaxClients parameter in Apache HT T P Server higher than the maxThreads setting
in JBoss (with a high load on the server) will result in Apache HT T P Server overwhelming the
JBoss instance with threads which will cause hung and/or dropped connections.
No connectionTimeout parameter set
T he connectionTimeout parameter set in JBoss is required for proper maintenance of old
connections.
No CPing/CPong set
T he CPing/CPong property in mod_jk is the most important worker property setting, allowing
mod_jk to test and detect faulty connections. Not setting this parameter can lead to bad
connections not being detected as quickly which can lead to web requests behaving as if
'hung'.

18

Chapter 4. Troubleshooting and optimizing mod_jk

Running an old version of mod_jk.

T here are known issues with sticky sessions in versions prior to mod_jk 1.2.27.
Running an older version of EAP.
T here is a bug in EAP 4.2 base and EAP 4.2 CP01 which causes sockets to be left in the
CLOSE_WAIT state, thus causing the appearance of hung requests again. T his issue has
been reported and fixed https://jira.jboss.org/jira/browse/JBPAPP-366
Unresponsive back end server
java.lang.OutOfMem oryError errors or high pause times can cause the back end server
to become unresponsive.

All of the problems listed above are typically resolved after optimizing the configuration in Apache HT T P
Server, mod_jk, and JBoss.
Common Errors
"CPing/CPong" Errors
Presents with errors like the following:
[info] ajp_handle_cping_cpong::jk_ajp_common.c (865): timeout in reply
cpong
...
[error] ajp_connect_to_endpoint::jk_ajp_common.c (957): (nodeA) cping/cpong
after connecting to the backend server failed (errno=110)
[error] ajp_send_request::jk_ajp_common.c (1507): (nodeA) connecting to
backend failed. Tomcat is probably not started or is listening on the
wrong port (errno=110)

T hese CPing/CPong messages do not indicate a problem with mod_jk at all, they indicate that
JBoss did not respond in the defined CPing/CPong time.
T his is seen many times when there is high load on the JVM JBoss is running on causing high
garbage collection or potentially thread contention. It could also be that the JBoss instance is
overloaded, or even that a firewall is blocking the connection or there are network issues.
T he following workflow may assist to correct these type of issues:
Procedure 4 .1. Resolving "CPing/CPong" Errors
1. Optimize your Apache HT T P Server and JBoss Enterprise Application Platform
configuration. You can contact Red Hat's Global Support Services for assistance with
this.
If this does not resolve the issue, proceed to Step 2
2. Confirm that there is no firewall blocking or dropping the AJP connections.
"T omcat is down" Errors
Presents with errors like the following:

19

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

1.

[error] ajp_get_reply::jk_ajp_common.c (2020): (node1) Timeout with

waiting reply from tomcat. Tomcat is down, stopped or network
problems (errno=110)

T he above error means that JBoss did not respond in the configured reply_timeout time.
T he solution can be one (or both) of the following:
a. Increase the reply_timeout.
b. Verify there are no garbage collection issues/long pause times in JBoss that may
prevent the request from responding thus causing that error.
2.

[Fri May 25 11:53:37 2012][11159:3086420192] [debug]

init_ws_service::mod_jk.c (977): Service protocol=HTTP/1.1
method=POST ssl=false host=(null) addr=127.0.0.1 name=localhost
port=80 auth=(null) user=(null) laddr=127.0.0.1 raddr=127.0.0.1
uri=/foo/bar
...
[Fri May 25 11:58:39 2012][11159:3086420192] [debug]
jk_shutdown_socket::jk_connect.c (681): About to shutdown socket 17
[Fri May 25 11:58:39 2012][11159:3086420192] [debug]
jk_shutdown_socket::jk_connect.c (689): Failed sending SHUT_WR for
socket 17
[Fri May 25 11:58:39 2012][11159:3086420192] [info]
ajp_connection_tcp_get_message::jk_ajp_common.c (1150): (node1) can not
receive the response header message from tomcat, network problems or
tomcat (127.0.0.1:8009) is down (errno=104)
[Fri May 25 11:58:39 2012][11159:3086420192] [error]
ajp_get_reply::jk_ajp_common.c (1962): (node1) Tomcat is down or
refused connection. No response has been sent to the client (yet)

T he above error likely means that JBoss Enterprise Application Platform did not respond
within the configured core Apache HT T P Server timeout period.
Note that with these messages the [11159:30864 20192] portion of the message
serves as an identifier for the connection/request in question. T herefore tracing back
from the point of the error in logs can help clarify the activity around the
connection/request that lead to the error.
In this case, that helps clarify that the error was experienced five minutes after the
response was sent to JBoss, which likely points to a five minute timeout (this is Apache
HT T P Server's T imeout directive default if not specified). If the T imeout is interrupting
mod_jk requests, then it should be increased from the current value to allow for the
maximum acceptable response time.
Procedure 4 .2. Resolving "T omcat is down" Errors
a. Optimize your Apache HT T P Server and JBoss Enterprise Application Platform
configuration. You can contact Red Hat's Global Support Services for assistance
with this.
If this does not resolve the issue, proceed to Step 2
b. Confirm that there is no firewall blocking or dropping the AJP connections.
General Performance Issues
Presents with errors like the following:
ERROR [org.apache.coyote.ajp.AjpMessage] (ajp-192.168.0.101-8001-13)
Invalid message received with signature 12336

20

Chapter 4. Troubleshooting and optimizing mod_jk

T he above exception when using mod_jk in JBoss Web typically indicates a non AJP request
sent to the AJP connector.
Workflows that may assist in resolving these kinds of issues is below:
Procedure 4 .3. General Performance Problems
1. Optimize your Apache HT T P Server and JBoss Enterprise Application Platform
configuration. You can contact Red Hat's Global Support Services for assistance with
this.
If this does not resolve the issue, proceed to Step 2
2. Gather garbage collection logs for analysis.
If the logs show long garbage collection pause times then you should optimize the Java
Virtual Machine to reduce the garbage collection pauses and gather/recheck updated
logs. Refer to https://access.redhat.com/knowledge/solutions/19932 (Red Hat account
required) for more information.
If this is not the case, or did not resolve the issue, try Step 3, Step 4 and/or Step 5 until
your issue is resolved.
3. Determine how long the longest request should take. Factor in transaction times. You
may need to increase the reply_timeout to resolve the problem.
If this does not resolve the issue, continue to Step 4 .
4. Determine if your current environment can handle the given load. If not, you may need to
upgrade or add more machines.
If this does not resolve the issue, continue to Step 5.
5. Confirm that there is no firewall blocking or dropping the AJP connections.
Procedure 4 .4 . 503 Errors
1. Optimize your Apache HT T P Server and JBoss Enterprise Application Platform
configuration. You can contact Red Hat's Global Support Services for assistance with
this.
If this does not resolve the issue, proceed to Step 2
2. Gather garbage collection logs for analysis.
If the logs show long garbage collection pause times then you should optimize the Java
Virtual Machine to reduce the garbage collection pauses and gather/recheck updated
logs. Refer to https://access.redhat.com/knowledge/solutions/19932 (Red Hat account
required) for more information.
If this is not the case, or does not resolve the issue, continue to Step 3
3. Determine how long the longest request should take. Factor in transaction times. You
may need to increase the reply_timeout to resolve the issue.
If this does not resolve the issue, move on to Step 4 .
4. Determine if your current environment can handle the given load. If not, you may need to
upgrade or add more machines.
JBoss/JVM-related Issues
May present with errors like:
[error] service::jk_lb_worker.c (1473): All tomcat instances failed, no
more workers left

21

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

If Apache HT T P Server and JBoss Enterprise Application Platform are optimized and you still
receive "no more workers left" this typically indicates an issue on the JBoss/JVM side. A
number of JVM-related problems could lead to mod_jk not being able to get a connection to
JBoss in the configured timeouts, thus causing the worker to go into the error state and
producing this message.
Procedure 4 .5. JBoss/JVM Problems
1. Enable garbage collection logging.
a. For UNIX based systems, the options should be placed in run.conf, not run.sh.
T he run.conf in the server configuration directory (e.g.
<JBOSS_HOME>/server/<PROFILE>/run.conf) takes precedence over the
run.conf in the <JBOSS_HOME>/bin directory (except in JBoss EAP 5.0.0 due to
a regression fixed in version 5.0.1).
b. For Windows, the options need to be added to run.bat, as it does not read
run.conf.
c. Check boot.log to see the value of the user.dir environment variable (e.g.
<JBOSS_HOME>/bin), the default location for garbage collection logging when no
path is provided. If you are running multiple instances of JBoss against the same
directory like so:
./run.sh -c node1 -b 127.0.0.1 -Djboss.messaging.ServerPeerID=1
./run.sh -c node2 -b 127.0.0.1 -Djboss.messaging.ServerPeerID=2 Djboss.service.binding.set=ports-01

d. T hen for the gc.log files to be properly separated you will need to make sure
each <PROFILE> has a unique run.conf with the JVM_OPT S specific to that
<PROFILE>.
For example node1 will contain a <JBOSS_HOME>/server/node1/run.conf with
contents:
JAVA_OPTS="$JAVA_OPTS -verbose:gc -Xloggc:gc_node1.log XX:+PrintGCDetails -XX:+PrintGCDateStamps"

e. And <JBOSS_HOME>/server/node2/run.conf with contents:

JAVA_OPTS="$JAVA_OPTS -verbose:gc -Xloggc:gc_node2.log XX:+PrintGCDetails -XX:+PrintGCDateStamps"

Important
gc.log is recreated every time JBoss starts.
Be sure to back up gc.log if you are restarting the server. Alternatively
you may be able to add a timestamp to the file name depending on the OS
and/or shell. For example, with OpenJDK or Oracle/Sun JDK on Linux: Xloggc:gc.log.`date +%Y%m%d%H%M%S`.
f. On Windows, you can use

22

Chapter 4. Troubleshooting and optimizing mod_jk

for /f "tokens=2-4 delims=/ " %%a in ('date /t') do (set

mydate=%%c-%%a-%%b)
for /f "tokens=1-2 delims=/:" %%a in ("%TIME%") do (set
mytime=%%a%%b)
set "JAVA_OPTS=%JAVA_OPTS% Xloggc:C:/log/gv.log.%mydate%_%mytime%

2. For the time period when there are slowdowns, hangs, or errors, gather the following
data:
Garbage collection logs. Follow Procedure 4.5, JBoss/JVM Problems.
High CPU data coupled with thread dumps (depending upon platform):
T he links below can assist in gathering Java thread data. A Red Hat subscription is
required.
CPU utilization by Java threads on Linux/Solaris:
https://access.redhat.com/knowledge/node/46596.
CPU utilization by Java threads on Windows:
https://access.redhat.com/knowledge/node/46598.
For cases where the Java application is an application server, gather log files:
In JBoss:
<JBOSS_HOME>/server/<PROFILE>/log/server.log
<JBOSS_HOME>/server/<PROFILE>/log/boot.log
In T omcat:
catalina.out
3. Determine if the CPU utilization is caused by the JVM (Java application). Here, you want
to validate that a Java process is indeed using an unexpected amount of CPU.
T he Java thread data gathered in the first step should help identify this.
4. Assuming a Java process is identified as the cause of high CPU, the most common
cause is java Garbage collection. Determine if the high CPU is caused by Java garbage
collection by analyzing the garbage collection for long pause times and/or low throughput
overall at the time of the issue.
T o find the garbage collection logging related to the issue, it is necessary to determine
the number of seconds after JVM startup that the issue happens (that is the typical
format of garbage collection logging timestamps). T o determine the time elapsed, you can
use the first timestamp in the high CPU data gathered and the first timestamp in the
console log, boot.log (JBoss), server.log (JBoss), or catalina.out (T omcat.)
If you see long pause times and/or low throughput overall, refer to the following
Knowledge Base article (Red Hat subscription required)
https://access.redhat.com/knowledge/node/19932.
5. If Garbage collection is not responsible for the high CPU, use the thread dump
information gathered when validating CPU information to identify the threads.

One area that is not a direct consequence of an unoptimized mod_jk configuration but can still cause
issues with mod_jk is JVM and garbage collection related problems. When there are high pause times
and the JVM is not optimized for the app server, the pause times can cause mod_jk issues even when
mod_jk is tuned.

4.2. General Diagnostics

23

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

1. Verify the back end server is responsive by making a direct request to it.
2. Monitor high load using one of the following methods:
T widdle
a. Locate the appropriate T widdle script for your environment (twiddle.sh,
twiddle.bat or twiddle.jar) in the <JBOSS_HOME>/bin/ directory.
b. Run the following command:
<TWIDDLE> -u admin -p password get "jboss.web:name=ajp-127.0.0.18009,type=ThreadPool"

Use the script appropriate to your operating system and environment .

T widdle may need to be modified for each specific environment, but the above will
work in a default JBoss instance where no ports have been changed and JBoss is
starting on the localhost.
JMX Console
a. Navigate to http://localhost:8080/jm x-console.
b. Find the jboss.web section.
c. Click on nam e=ajp-localhost/127.0.0.1-8009,type=T hreadPool (or
whichever AJP ThreadPool matches your environment)
d. Investigate the currentThreadsBusy attribute. If this attribute is reaching the
maxThreads there will be a problem as JBoss Web is reaching the defined
ThreadPool capacity.

4.3. Getting Further Help

If none of the above information resolves your issue you can contact the Global Support Services staff
for assistance.
You can find the appropriate contact details at https://access.redhat.com/support/.
Please gather the following information prior to your call.
JBoss EAP boot.log.
Apache HT T P Server's httpd.conf and the httpd-m pm .conf file (if it exists).
mod_jk's workers.properties.
mod_jk's m od_jk.conf.
<JBOSS_HOME>/server/<PROFILE>/deploy/JBOSSWEB/server.xm l
<JBOSS_HOME>/server/<PROFILE>/deploy/JBOSSWEB/MET A-INF/jboss-service.xm l
T he output of running httpd -V on Apache HT T P Server (httpd -V > httpd.out, for example).
Note the capital "V". A lowercase "v" will not produced the desired output.
Version of Apache HT T P Server or the JBoss Enterprise Web Server.
/etc/sysconfig/httpd

24

Part II. JBoss HTTP Connector (mod_cluster)

Part II. JBoss HTTP Connector (mod_cluster)

25

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 5. Overview
T he JBoss HT T P Connector mod_cluster is a reduced-configuration, intelligent load-balancing solution
for JBoss Enterprise Application Platform, based on technology originally developed by the JBoss
mod_cluster community project.
T he JBoss HT T P connector load-balances HT T P requests to JBoss Enterprise Application Platform
and JBoss Enterprise Web Server worker nodes, using Apache HT T P Server as the proxy server.

5.1. Key features

Apache HT T P Server-based
T he JBoss HT T P Connector mod-cluster uses Apache HT T P Server as the proxy server.
Real-time load-balancing calculation
T he JBoss HT T P Connector mod_cluster creates a feedback network between the worker
nodes and the proxy server. T he mod_cluster service is deployed on each of the worker
nodes. T his service feeds real-time load information to the proxy server. T he proxy server then
makes intelligent decisions about where to allocate work, based on the current load on each
worker node. T his real-time adaptive load distribution results in increased optimization of
resources.
T he information that is reported by the worker nodes and the load-balancing policy used by the
proxy are both customizable.
Routing based on real-time application life-cycle
T he JBoss HT T P Connector mod_cluster service deployed on the worker nodes relays
application life-cycle events to the proxy server. T his allows the server to dynamically update its
routing table. When an application is undeployed on a node, the proxy server no longer routes
traffic for that application to that node.
Automatic Proxy Discovery
T he proxy server can be configured to announce its presence via UDP multicast. New worker
nodes discover the proxy server and add themselves to the load-balancing cluster
automatically. T his greatly reduces the configuration and maintenance needed. When UDP
multicast is not available or is undesirable, worker nodes are configured with a static list of
proxies.
Multiple Protocol Support
T he JBoss HT T P Connector mod_cluster can use HT T P, HT T PS, or Apache JServ Protocol
(AJP) for communication between the proxy and the worker nodes.

5.2. Components
Proxy Server
On the proxy server, the JBoss HT T P Connector, mod-cluster, consists of four Apache HT T P Server
modules.

26

Chapter 5. Overview

Shared Memory Manager module: m od_slotm em .so

T he Shared Memory Manager module, mod_slotmem, makes the real-time worker node
information available to multiple Apache HT T P Server server processes.
Cluster Manager module: m od_m anager.so
T he Cluster Manager module, mod_manager, receives and acknowledges messages from
nodes, including worker node registrations, worker node load data, and worker node application
life-cycle events.
Proxy Balancer module: m od_proxy_cluster.so
T he Proxy Balancer module, mod_proxy_cluster, handles the routing of requests to cluster
nodes. T he Proxy Balancer selects the appropriate node to forward the request to, based on
application location in the cluster, current state of each of the cluster nodes, and the Session ID
(if a request is part of an established session).
Proxy Advertisement module: m od_advertise.so
T he Proxy Advertisement module, mod_advertise.so, broadcasts the existence of the proxy
server via UDP multicast messages. T he server advertisement messages contain the IP
address and port number on which the proxy is listening for responses from nodes that wish to
join the load-balancing cluster.

Note
Refer to Section 6.1, Apache HT T P Server modules for detailed information about the available
modules including user-configurable parameters.
Worker Node Components
T he JBoss HT T P Connector client service, m od-cluster.sar, is deployed on each worker node.
Worker node service: m od-cluster.sar
T his service provides the proxy with real-time information on the worker node's state and
sends notification of application life-cycle events; as well as allowing the node to discover and
register itself with any proxies running on the same network.

5.3. Limitations
T he JBoss HT T P Connector mod_cluster uses shared memory to keep the nodes description, the
shared memory is created at the startup of httpd and the structure of each item is fixed. T herefore,
when defining proxy server and worker node properties, make sure to follow these character limits:
Maximum Alias length: 100 characters (Alias corresponds to the network name of the respective
virtual host; the name is defined in the Host element)
Maximum context length: 40 characters (for example, if myapp.war is deployed in /m yapp, then
/m yapp is the context)

27

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Maximum balancer name length: 40 characters (the balancer property in MBean)

Maximum JVMRoute string length: 80 character (JVMRoute in the <Engine> element)
Maximum domain name length: 20 characters (the domain property in MBean)
Maximum hostname length for a node: 64 characters (hostname address in the <Connector>
element)
Maximum port length for a node: 7 characters (8009 is 4 characters, the port property in the
<Connector> element)
Maximum scheme length for a node: 6 characters (possible values are http, https, ajp, the
protocol of the connector)
Maximum cookie name length: 30 characters (the header cookie name for session ID default value:
JSESSIONID from org.apache.catalina.Globals.SESSION_COOKIE_NAME)
Maximum path name length: 30 characters (the parameter name for the session ID default value:
JSESSIONID from org.apache.catalina.Globals.SESSION_PARAMET ER_NAME)
Maximum length of a session ID: 120 characters (session ID resembles the following:
BE81FAA969BF64 C8EC2B66004 57EAAAA.node01)

28

Chapter 6. Install proxy server components

Chapter 6. Install proxy server components

Read this chapter to install the JBoss HT T P Connector, mod_cluster, on a proxy server.

6.1. Apache HTTP Server modules

Read this section for expanded definitions of the Apache HT T P Server proxy server modules discussed
in Section 5.2, Components. You specify these modules as part of T ask: Install Proxy Server
Components.

6.1.1. mod_manager.so
T he Cluster Manager module, mod_manager, receives and acknowledges messages from nodes,
including worker node registrations, worker node load data, and worker node application life-cycle
events.
LoadModule manager_module modules/mod_manager.so

You can also define the following related directives in the <VirtualHost> element:
MemManagerFile
Defines the location for the files in which mod_manager stores configuration details.
mod_manager also uses this location to store generated keys for shared memory and lock files.
This must be an absolute path name.
It is recommended that this path be set explicitly and on a local drive, not an NFS share. T he
default value is platform/httpd specific.
Valid paths are:
HP-UX: HTTPD_HOME/cache/m od_cluster
Red Hat Enterprise Linux: /var/cache/m od_cluster
Maxcontext
T he maximum number of contexts JBoss mod_cluster will use. T he default value is 100.
Maxnode
T he maximum number of worker nodes JBoss mod_cluster will use. T he default value is 20.
Maxhost
T he maximum number of hosts (aliases) JBoss mod_cluster will use. T his is also the maximum
number of load balancers. T he default value is 10.
Maxsessionid
T he maximum number of active session identifiers stored. A session is considered inactive
when no information is received from that session within five minutes. T he default value is 0,
which disables this logic.
ManagerBalancerName
T he name of the load balancer to use when the worker node does not provide a load balancer

29

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

name. T he default value is m ycluster.

PersistSlots
When set to on, nodes, aliases and contexts are persisted in files. T he default value is off.
CheckNonce
When set to on, session identifiers are checked to ensure that they are unique, and have not
occurred before. T he default is on.

Warning
Setting this directive to off can leave your server vulnerable to replay attacks.

SetHandler
Defines a handler to display information about worker nodes in the cluster. T his is defined in
the Location element:
<Location $LOCATION>
SetHandler mod_cluster-manager
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>

When accessing the $LOCATION defined in the Location element in your browser, you will see
something like the following. (In this case, $LOCATION was also defined as m od_clusterhandler.)

Figure 6.1. mod_cluster Status

Transferred corresponds to the POST data sent to the worker node. Connected corresponds to the
number of requests that had been processed when this status page was requested. Sessions
corresponds to the number of active sessions. T his field is not present when Maxsessionid is 0.

30

Chapter 6. Install proxy server components

6.1.2. mod_proxy_cluster.so
T he Proxy Balancer module, mod_proxy_cluster, handles the routing of requests to cluster nodes.
T he Proxy Balancer selects the appropriate node to forward the request to, based on application
location in the cluster, current state of each of the cluster nodes, and the Session ID (if a request is part
of an established session).
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so

You can also define the following related directives in the <VirtualHost> element to change loadbalancing behavior.
mod_proxy_cluster directives
CreateBalancers
Defines how load balancers are created in the Apache HT T P Server virtual hosts. T he following
values are valid in CreateBalancers :
0
Create load balancers in all virtual hosts defined in Apache HT T P Server. Remember
to configure the load balancers in the ProxyPass directive.
1
Do not create balancers. When using this value, you must also define the load
balancer name in the ProxyPass or ProxyPassMatch .
2
Create only the main server. T his is the default value for CreateBalancers .

UseAlias
Defines whether to check that the defined Alias corresponds to the ServerNam e . T he
following values are valid for UseAlias :
0
Ignore Alias information from worker nodes. T his is the default value for UseAlias .
1
Verify that the defined alias corresponds to a worker node's server name.

LBstatusRecalT ime
Defines the interval in seconds between the proxy calculating the status of a worker node. T he
default interval is 5 seconds.
ProxyPassMatch; ProxyPass
ProxyPass maps remote servers into the local server namespace. If the local server has an

31

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

address http://local.com /, then the following ProxyPass directive would convert a

local request for http://local.com /requested/file1 into a proxy request for
http://worker.local.com /file1.
ProxyPass /requested/ http://worker.local.com/

ProxyPassMatch uses Regular Expressions to match local paths to which the proxied URL
should apply.
For either directive, ! indicates that a specified path is local, and a request for that path should
not be routed to a remote server. For example, the following directive specifies that .gif files
should be served locally.
ProxyPassMatch ^(/.*\.gif)$ !

6.1.3. mod_advertise.so
T he Proxy Advertisement module, mod_advertise.so, broadcasts the existence of the proxy server via
UDP multicast messages. T he server advertisement messages contain the IP address and port number
where the proxy is listening for responses from nodes that wish to join the load-balancing cluster.
T his module must be defined alongside mod_manager in the VirtualHost element. Its identifier in
the following code snippet is advertise_m odule.
LoadModule advertise_module modules/mod_advertise.so

mod_advertise also takes the following directives:

ServerAdvertise
Enables or disables the advertising mechanism. When set to On, the advertising mechanism is
used to tell worker nodes to send status information to this proxy. When set to Off, the
advertising mechanism is disabled.
You can also specify a hostname and port with the following syntax: ServerAdvertise On
http://hostnam e:port/. T his is only required when using a name-based virtual host, or
when a virtual host is not defined.
T he default value is Off but it is automatically enabled if any Advertise directive is specified
in defining a VirtualHost.
AdvertiseGroup
Defines the multicast address to advertise on. T he syntax is AdvertiseGroup
address:port, where address should correspond to AdvertiseGroupAddress , and
port should correspond to AdvertisePort in your worker nodes.
If your worker node is JBoss Enterprise Application Platform-based, and the -u switch is used
at startup, the default AdvertiseGroupAddress is the value passed via the -u switch.
T he default value is 224 .0.1.105:23364 . If port is not specified, the default port used is
23364 .

32

Chapter 6. Install proxy server components

AdvertiseFrequency
T he interval (in seconds) between multicast messages advertising the IP address and port.
T he default value is 10.
AdvertiseSecurityKey
Defines a string used to identify the JBoss HT T P Connector mod_cluster in JBoss Web. By
default this directive is not set and no information is sent.
AdvertiseManagerUrl
Defines the URL that the worker node should use to send information to the proxy server. By
default this directive is not set and no information is sent.
AdvertiseBindAddress
Defines the address and port over which to send multicast messages. T he syntax is
AdvertiseBindAddress address:port. T his allows an address to be specified on
machines with multiple IP addresses. T he default value is 0.0.0.0:23364 .

6.2. Install proxy server components

T ask: Install Proxy Server Components
Follow this task to install the JBoss HT T P Connector.
T he native components are specific to particular operating system and processor architectures. Refer to
the JBoss Enterprise Application Platform Installation Guide to download the correct native components
package for your server operating system and processor architecture.
Prerequisites
An installed Web Server distribution, such as JBoss Enterprise Web Server or HPWS installed
(designated by HT T PD_HOME in this documentation).
JBoss Enterprise Application Platform 5 Native components downloaded.

1. Extract Apache HT T P Server modules from Native Components download

Extract the four modules m od_advertise.so, m od_m anager.so, m od_proxy_cluster.so,
m od_slotm em .so from the appropriate Native Components package directory for your
processor architecture: either native/lib/httpd/m odules or
native/lib64 /httpd/m odules.
2. Copy Apache HT T P Server modules to HTTPD_HOME
Copy the JBoss HT T P Connector modules to the HTTPD_HOME/httpd/m odules directory of the
JBoss Enterprise Web Server.
3. Disable the mod_proxy_balancer module
Edit the HT T PD configuration file HTTPD_HOME/httpd/conf/httpd.conf and mark the
following line as a comment by adding a # character at the start:
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so

33

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

T his module is incompatible with the JBoss HT T P Connector.

4. Configure the server to load the JBoss HT T P Connector modules
a. Create HTTPD_HOME/httpd/conf/JBoss_HT T P.conf.
b. Add the following lines to HTTPD_HOME/httpd/conf/JBoss_HT T P.conf:
LoadModule
LoadModule
LoadModule
LoadModule

slotmem_module HTTPD_HOME/modules/mod_slotmem.so
manager_module HTTPD_HOME/modules/mod_manager.so
proxy_cluster_module HTTPD_HOME/modules/mod_proxy_cluster.so
advertise_module HTTPD_HOME/modules/mod_advertise.so

5. Restart the HT T PD service

Refer to HT T PD-specific documentation for detailed instructions.

34

Chapter 7. Configure basic proxy server

Chapter 7. Configure basic proxy server

Follow the instructions in this chapter to configure an HT T PD to use the JBoss HT T P Connector
(mod_cluster).

7.1. Basic proxy configuration overview

Configuration of the proxy server consists of one mandatory and one optional portion:
1. Configure a proxy server listener to receive worker node connection requests and worker node
feedback.
2. Optional: Disable server advertisement.
Server Advertisement
T he proxy server can advertise itself using UDP multicast. When UDP multicast is available on the
network between the proxy server and the worker nodes server advertisement allows you to add worker
nodes with no further configuration required on the proxy server, and minimal configuration on the
worker nodes.
If UDP multicast is not available or undesirable, configure the worker nodes with a static list of proxy
servers, as detailed in Section 9.1, Static proxy configuration. T here is no need in either case to
configure the proxy server with a list of worker nodes.

7.2. Configure a load-balancing proxy using the HTTP Connector

Read this section to configure a load balancing proxy that uses the JBoss HT T P Connector.
T ask: Configure a Proxy Server Listener
Follow this task to configure the Apache HT T P Server service to act as a load-balancing proxy using the
JBoss HT T P Connector.
Prerequisites
An installed Web Server distribution, such as JBoss Enterprise Web Server or HPWS installed
(designated by HT T PD_HOME in this documentation).
JBoss HT T P Connector modules. Refer to Chapter 6, Install proxy server components for details.

1. Create a listen directive for the proxy server

Edit the configuration file HTTPD_HOME/httpd/conf/JBoss_HT T P.conf and add the following:
Listen IP_ADDRESS:PORT_NUMBER

Where IP_ADDRESS is the IP address of a server network interface to communicate with the
worker nodes, and PORT_NUMBER is the port on that interface to listen on.

Note
T he port PORT_NUMBER must be open on the server firewall for incoming T CP connections.

35

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Example 7.1. Example Listen Directive

Listen 10.33.144.3:6666

2. Create Virtual Host

Add the following <VirtualHost> block to HTTPD_HOME/httpd/conf/JBoss_HT T P.conf:
<VirtualHost IP_ADDRESS:PORT_NUMBER>
<Location />
Order deny,allow
Deny from all
Allow from PARTIAL_IP_ADDRESS
</Location>
KeepAliveTimeout 60
MaxKeepAliveRequests 0
ManagerBalancerName mycluster
AdvertiseFrequency 5
</VirtualHost>

IP_ADDRESS and PORT_NUMBER match the values from the Listen directive.
PARTIAL_IP_ADDRESS is the first 1 to 3 bytes of an IP address, to restrict access to a specific
subnet - 10.33.144, for example.
3. Configure SELinux to allow proxy traffic
Enter the following commands as a root-equivalent user to modify the SELinux configuration to
allow the proxy traffic:
#semanage port -a -t http_port_t -p tcp 8079 #add port to the Apache port
list to enable the next command to work
#setsebool -P httpd_can_network_relay 1 #for mod_proxy to work

4. Optional: Disable Server Advertisement

T he presence of the AdvertiseFrequency directive, which is set to five seconds here, causes
the server to periodically send server advertisement messages via UDP multicast.
T hese server advertisement messages contain the IP_ADDRESS and PORT_NUMBER specified in
the VirtualHost definition. Worker nodes that are configured to respond to server advertisements
use this information to register themselves with the proxy server.
T o disable server advertisement, add the following directive to the VirtualHost definition:
ServerAdvertise Off

If server advertisements are disabled, or UDP multicast is not available on the network between
the proxy server and the worker nodes, you must configure worker nodes with a static list of proxy
servers. Refer to Section 9.1, Static proxy configuration for directions.
5. Restart the JBoss Enterprise Web Server Apache service
Refer to HT T PD-specific documentation for detailed instructions.

36

Chapter 8. Install node with basic configuration

Chapter 8. Install node with basic configuration

Read this chapter to install the JBoss HT T P Connector on a worker node, and implement basic
configuration for the node to begin immediate operation.

8.1. Worker node requirements

Supported Worker Node types
JBoss Enterprise Platform 5 JBoss Web component
JBoss Enterprise Web Server T omcat service

Note
JBoss Enterprise Platform worker nodes support all JBoss HT T P Connector functionality. JBoss
Enterprise Web Server T omcat worker nodes support a subset of JBoss HT T P Connector
functionality.
JBoss HT T P Connector Enterprise Web Server Node Limitations
Non-clustered mode only.
Only one load metric can be used at a time when calculating the load balance factor.

8.2. Install and configure a worker node

T his section contains a number of tasks. Follow the appropriate task to install and configure a worker
node on JBoss Enterprise Application Platform, or JBoss Enterprise Web Server.

Character Limitations on Worker Node

Make sure your configuration definition meets the following character limits:
Maximum JVMRoute string length: 80 character (JVMRoute in the <Engine> element)
Maximum hostname length for a node: 64 characters (hostname address in the <Connector>
element)
Maximum port length for a node: 7 characters (8009 is 4 characters, the port property in the
<Connector> element)
Maximum scheme length for a node: 6 characters (possible values are http, https, ajp, the
protocol of the connector)

T ask: Install and Configure a JBoss Enterprise Application Platform Worker Node
Follow this procedure to install JBoss HT T P Connector on a JBoss Enterprise Application Platform
instance and configure it for non-clustered operation.
Prerequisites
Install a supported JBoss Enterprise Application Platform.
Understand the Proxy Configuration parameters discussed in Appendix B, Reference: Java
properties

37

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

1. Deploy the worker node service

Copy m od-cluster.sar from the JBOSS_EAP_DIST/m od_cluster directory to jbossas/server/PROFILE/deploy.
2. Add a Listener to JBoss Web
Add the following Listener element beneath the other Listeners in JBOSS_EAP_DIST/jbossas/server/PROFILE/deploy/jbossweb.sar/server.xm l:
<Listener
className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLif
ecycleListener" delegateBeanName="ModClusterService"/>

3. Configure the service dependency

Add the following depends element beneath the other depends elements in
JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy/jbossweb.sar/MET A-INF/jbossbeans.xm l:
<depends>ModClusterService</depends>

4. Give the worker a unique identity

Edit JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy/jbossweb.sar/server.xm l
and add a jvm Route attribute and value to the Engine element, as shown:
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="worker01">

Use a unique jvm Route value for each node.

5. Optional: Configure firewall to receive multicast Proxy Server advertisements
A proxy server using the JBoss HT T P Connector can advertise itself via UDP multicast. T o enable
the worker node to dynamically discover proxy servers, open port 23364 for UDP connections on
the worker node's firewall.
Use the following command on Red Hat Enterprise Linux to achieve this:
/sbin/iptables -A INPUT -m state --state NEW -m udp -p udp --dport 23364 -j
ACCEPT
-m comment --comment "receive mod_cluster proxy server advertisements"
/sbin/iptables save

If you are not using Automatic Proxy Discovery (see Automatic Proxy Discovery), configure worker
nodes with a static list of proxies. Refer to Section 9.1, Static proxy configuration for directions. In
this case you can safely ignore the following warning message:
[warning] mod_advertise: ServerAdvertise Address or Port not defined,
Advertise disabled!!!

38

Chapter 8. Install node with basic configuration

Important
If your nodes are on different machines that run Red Hat Enterprise Linux, they may not
acknowledge each other automatically. JBoss Clustering relies on the UDP (User Datagram
Protocol) multicasting provided by jGroups. Red Hat Enterprise Linux blocks these packets
by default.
T o allow the packets, modify the iptables rules (as root). T he following commands apply to
an IP address that matches 192.168.1.x:
/sbin/iptables -I RH-Firewall-1-INPUT
ACCEPT
/sbin/iptables -I RH-Firewall-1-INPUT
/sbin/iptables -I RH-Firewall-1-INPUT
ACCEPT
/sbin/iptables -I RH-Firewall-1-INPUT
ACCEPT
/etc/init.d/iptables save

5 -p udp -d 224.0.1.0/24 -j
5 -p udp -d 224.0.0.0/4 -j ACCEPT
9 -p udp -s 192.168.1.0/24 -j
10 -p tcp -s 192.168.1.0/24 -j

T ask: Install and Configure a JBoss Enterprise Web Server Worker Node
Follow this procedure to install the JBoss HT T P Connector on a JBoss Enterprise Web Server node and
configure it for non-clustered operation.
Prerequisites
Install a supported JBoss Enterprise Web Server.
Understand the Proxy Configuration parameters discussed in Appendix B, Reference: Java
properties

1. Deploy worker node service

Copy all of the library files in the JBOSS_EAP_DIST/m od_cluster/JBossWeb-T om cat/lib
directory. Move these files to JBOSS_EWS_DIST/tom cat6/lib/
2. Add a Listener to T omcat
Add the following Listener element beneath the other Listener elements in
JBOSS_EWS_DIST/tomcat6/conf/server.xm l.
<Listener className="org.jboss.modcluster.ModClusterListener" advertise="true"
stickySession="true" stickySessionForce="false" stickySessionRemove="true"/>

3. Give this worker a unique identity

Edit JBOSS_EWS_DIST/tomcat6/conf/server.xm l and add a jvm Route attribute and value
to the <Engine> element, as shown:
<Engine name="Catalina" defaultHost="localhost" jvmRoute="worker01">

4. Optional: Configure firewall to receive Proxy Server advertisements

A proxy server using the JBoss HT T P Connector can advertise itself via UDP multicast. T o
receive these multicast messages, open port 23364 for UDP connections on the worker node's
firewall.

39

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

For Linux users:

/sbin/iptables -A INPUT -m state --state NEW -m udp -p udp --dport
23364 -j ACCEPT
-m comment -comment "receive mod_cluster proxy server advertisements"

If you are not using Automatic Proxy Discovery (see Automatic Proxy Discovery), configure worker
nodes with a static list of proxies. Refer to Section 9.1, Static proxy configuration for directions. In
this case you can safely ignore the following warning message:
[warning] mod_advertise: ServerAdvertise Address or Port not defined,
Advertise disabled!!!

40

Chapter 9. Advanced configuration

Chapter 9. Advanced configuration

Read this chapter to configure advanced features of the JBoss HT T P Connector.

9.1. Static proxy configuration

Server advertisement allows worker nodes to dynamically discover and register themselves with proxy
servers. If UDP broadcast is not available or server advertisement is disabled then worker nodes must
be configured with a static list of proxy server addresses and ports.

Character Limitations on Proxy Node

Make sure your configuration definition meets the following character limits:
Maximum Alias length: 100 character (for example, if myapp.war is deployed in /m yapp,
then/m yapp is the context)
Maximum balancer name length: 40 (thebalancer property in MBean)
Maximum domain name length: 20 (thedomain property in MBean)

T ask: Configure Application Platform Worker Node with Static Proxy List
Follow this task to configure a JBoss Enterprise Application Platform worker node to operate with a static
list of proxy servers.
Prerequisites
JBoss Enterprise Application Platform worker node configured. Refer to Chapter 8, Install node with
basic configuration for directions.

1. Disable dynamic proxy discovery

Edit the file JBOSS_EAP_DIST/jboss-as/server/PROFILE/m od-cluster.sar/MET AINF/m od-cluster-jboss-beans.xm l and set the advertise property to false:
<property name="advertise">false</property>

2. Choose, and implement, one of the following static proxy options:

A. Option 1: Create a static proxy server list
Edit JBOSS_EAP_DIST/jboss-as/server/PROFILE/m od-cluster.sar/MET A-INF/m odcluster-jboss-beans.xm l and add a comma separated list of proxies in the form of
IP_ADDRESS:PORT in the proxyList property.
Example 9.1. Example Static Proxy List
<property name="proxyList">10.33.144.3:6666,10.33.144.1:6666</property>

B. Option 2: Start the worker node with a static proxy list as a parameter
a. Edit JBOSS_EAP_DIST/server/PROFILE/m od-cluster.sar/MET A-INF/m odcluster-jboss-beans.xm l

41

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

b. Add the following line:

<property name="domain">${jboss.modcluster.domain:}</property>

c. Add a comma-separated list of proxies in the form of IP_ADDRESS:PORT as the

jboss.m odcluster.proxyList parameter when starting the node.
Example 9.2. Example Static Proxy List Parameter
-Djboss.modcluster.domain=10.33.144.3:6666,10.33.144.1:6666

T ask: Configure Web Server Worker Node with Static Proxy List
Follow this procedure to configure a JBoss Enterprise Web Server worker node to operate with a static
list of proxy servers.
Prerequisites
JBoss Enterprise Web Server worker node configured. Refer to Chapter 8, Install node with basic
configuration for directions.
Understand the Proxy Configuration parameters discussed in Appendix B, Reference: Java
properties

1. Disable dynamic proxy discovery

Edit JBOSS_EWS_DIST/tomcat6/conf/server.xm l. and set the advertise property of the
ModClusterListener to false:
2. Define a mod_cluster listener
Add a <Listener> element to server.xm l.
<Listener className="org.jboss.modcluster.ModClusterListener"
advertise="false" stickySession="true" stickySessionForce="false"
stickySessionRemove="true"/>

3. Create a static proxy server list

Add a comma separated list of proxies in the form of IP_ADDRESS:PORT as the proxyList
property of the ModClusterListener <Listener> element.
Example 9.3. Example Static Proxy List
<Listener className="org.jboss.modcluster.ModClusterListener"
advertise="false" stickySession="true" stickySessionForce="false"
stickySessionRemove="true" proxyList="10.33.144.3:6666,10.33.144.1:6666"/>

9.2. Clustered node operation

T he JBoss HT T P Connector can operate in either clustered or non-clustered mode.

42

Chapter 9. Advanced configuration

Note
Only JBoss Enterprise Application Platform nodes support clustered operation with the JBoss
HT T P Connector. JBoss Enterprise Web Server nodes support non-clustered operation only.
JBoss HT T P Connector non-clustered operation
In non-clustered mode each worker node communicates directly with the proxy.

JBoss HT T P Connector clustered operation

In clustered mode multiple worker nodes form a JBoss HA (High Availability) cluster domain. A
single worker node communicates with the proxy on behalf of the other nodes in the cluster
domain.

43

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 10. Java Properties

10.1. Configuration Properties
T he tables below enumerate the configuration properties available to an application server node. T he
location for these properties depends on how mod_cluster is configured.

10.1.1. Proxy Discovery Configuration

T he list of proxies from which an application expects to receive AJP connections is either defined
statically, via the addresses defined in the proxyList configuration property; or discovered dynamically
via the advertise mechanism.
Using a special mod_advertise module, proxies can advertise their existence by periodically
broadcasting a multicast message containing its address/port.
T his functionality is enabled via the advertise configuration property. If configured to listen, a server
can learn of the proxy's existence, then notify that proxy of its own existence, and update its
configuration accordingly. T his frees both the proxy and the server from having to define static,
environment-specific configuration values.

44

Chapter 10. Java Properties

T able 10.1. Proxy Discovery

Attribute

Default

Description

proxyList

None

Defines a comma-separated list

of httpd proxies with which this
node will initially communicate.
Value should be of the form:
address1:port1,address2
:port2
Using the default configuration,
this property can by manipulated
via the
jboss.modcluster.proxyLis
t system property.

excludedContexts

ROOT ,adminconsole,invoker,jbossws,jmxconsole,juddi,web-console

List of contexts to exclude from

httpd registration, of the form:
host1:context1,host2:con
text2,host3:context3
If no host is indicated, it is
assumed to be the default host
of the server (e.g. localhost).
"ROOT " indicates the root
context. Using the default
configuration, this property can
by manipulated via the
jboss.modcluster.excluded
Contexts system property.

autoEnableContexts

T rue

If false, the contexts are

registered disabled in httpd,
they need to be enabled via the
enable() MBean method or
via mod_cluster_manager.

stopContextTimeout

10

T he number of seconds to wait

for clean shutdown of a context,.
T his could be the completion of
all pending requests for a
distributable context or the
destruction/expiration of active
sessions for a non-distributable
context.

proxyURL

None

If defined, this value will be

prepended to the URL of MCMP
commands.

socketTimeout

20000

Number of milliseconds to wait

for a response from an httpd
proxy to MCMP commands
before timing out and flagging
the proxy as in error.

45

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

advertise

T his is true if proxyList is

undefined, false otherwise.

If enabled, httpd proxies will be

auto-discovered via multicast
announcements. T his can be
used either in concert or in
place of a static proxyList.

advertiseGroupAddress

224 .0.1.105

T he UDP address on which to

listen for httpd proxy multicast
advertisements.

advertisePort

23364

T he UDP port on which to listen

for httpd proxy multicast
advertisements.

advertiseSecurityKey

None

If specified, httpd proxy

advertisements checksums will
be verified using this value as a
salt.

10.1.2. Proxy Configuration

T he following configuration values are sent to proxies during server startup, when a proxy is detected
via the advertise mechanism, or during the resetting of a proxy's configuration during error recovery.

46

Chapter 10. Java Properties

T able 10.2. Proxy Configuration

Attribute

Default

Description

stickySession

true

Indicates whether subsequent

requests for a given session
should, if possible, be routed to
the same node.

stickySessionRemove

false

Indicates whether the httpd

proxy should remove session
stickiness in the event that the
balancer is unable to route a
request to the node to which it is
stuck. T his property is ignored if
stickySession is false.

stickySessionForce

true

Indicates whether the httpd

proxy should return an error in
the event that the balancer is
unable to route a request to the
node to which it is stuck. T his
property is ignored if
stickySession is false.

workerTimeout

-1

Number of seconds to wait for a

worker to become available to
handle a request. When all the
workers of a balancer are
unusable, mod_cluster will retry
after a specified period
(workerT imeout/100) to find a
usable worker.
A value of -1 indicates that the
httpd will not wait for a worker
to be available and will return an
error if none is available.

maxAttempts

Number of times an httpd proxy

will attempt to send a given
request to a worker before
giving up. T he minimum value is
1, meaning try only once.
Note that mod_proxy default
is also 1: no retry.

flushPackets

false

Enables/disables packet
flushing.

flushWait

-1

T ime to wait before flushing

packets. A value of -1 means
wait forever.

ping

10 seconds

T ime to wait for an answer to a

ping.

smax

Determined by httpd
configuration.

Soft maximum idle connection

count (that is the smax in worker

47

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

mod_proxy documentation). T he
maximum value depends on the
httpd thread configuration
(T hreadsPerChild or 1).
ttl

60 seconds

T ime to live (in seconds) for idle

connections above smax.

nodeTimeout

-1 (none)

T imeout (in seconds) for proxy

connections to a node. T hat is
the time mod_cluster will wait for
the back-end response before
returning an error.
T his corresponds to timeout in
the worker mod_proxy
documentation.
Note that mod_cluster always
uses a CPing/CPong before
forwarding a request and the
connectiontimeout value
used by mod_cluster is the ping
value.

balancer

m ycluster

T he balancer name.

domain

None

If specified, load will be balanced

among jvm Routes with the
same domain. T his is primarily
used in conjunction with
partitioned session replication
(e.g. buddy replication).

Note: When nodeT imeout is not defined the ProxyT imeout directive Proxy is used. If
ProxyT imeout is not defined the server timeout (T imeout) is used (default 300 seconds).
nodeT imeout, ProxyT imeout or T imeout is set at the socket level.

10.1.3. SSL Configuration

T he communication channel between application servers and httpd proxies uses HT T P by default. T his
channel can be secured using HT T PS by setting the ssl parameter to true.
Note: T his HT T P/HT T PS channel should not be confused with the processing of
HT T P/HT T PS client requests.

48

Chapter 10. Java Properties

T able 10.3. SSL Configuration

Attribute

Default

Description

ssl

false

Should connection to proxy use

a secure socket layer.

sslCiphers

T he default JSSE cipher suites

Overrides the cipher suites

used to init an SSL socket
ignoring any unsupported
ciphers.

sslProtocol

T LS

Overrides the default SSL

socket protocol.

sslCertificateEncodingAlg
orithm

T he default JSSE key manager

algorithm.

T he algorithm of the key

manager factory.

sslKeyStore

System .getProperty("user
.hom e") + "/.keystore"

T he location of the key store

containing client certificates.

sslKeyStorePass

changeit

T he password granting access

to the key store.

sslKeyStoreType

JKS

T he type of key store.

sslKeyStoreProvider

T he default JSSE security

provider.

T he key store provider.

sslTrustAlgorithm

T he default JSSE trust manager

algorithm.

T he algorithm of the trust

manager factory.

sslKeyAlias

T he alias of the key holding the

client certificates in the key
store.

sslCrlFile

Certificate revocation list.

sslTrustMaxCertLength

T he maximum length of a
certificate held in the trust store.

sslTrustStore

System .getProperty("jav
ax.net.ssl.trustStorePas
sword")

T he location of the file

containing the trust store.

sslTrustStorePassword

System .getProperty("jav
ax.net.ssl.trustStore")

T he password granting access

to the trust store.

sslTrustStoreType

System .getProperty("jav
ax.net.ssl.trustStoreT yp
e")

T he trust store type.

sslTrustStoreProvider

System .getProperty("jav
ax.net.ssl.trustStorePro
vider")

T he trust store provider.

10.1.4. HA Configuration
Additional configuration properties when mod_cluster is configured in clustered mode.

49

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

T able 10.4 . HA Configuration

Attribute

Default

Description

masterPerDomain

false

If the domain directive is used,

should HA partition use a
singleton master per domain.

10.1.5. Load Configuration

Additional configuration properties used when mod_cluster is configured in JBoss Web standalone or
T omcat.
T able 10.5. Load Configuration
Attribute

Default

Description

loadMetricClass

org.jboss.modcluster.load
.metric.impl.BusyConnecto
rsLoadMetric

Class name of an object

implementing
org.jboss.load.m etric.L
oadMetric.

loadMetricCapacity

T he capacity of the load metric

defined via the
loadMetricClass property.

loadHistory

T he number of historic load

values to consider in the load
balance factor computation.

loadDecayFactor

T he factor by which a historic

load values should degrade in
significance.

50

Chapter 11. Load Metrics

Chapter 11. Load Metrics

11.1. Server-Side Load Metrics
A major feature of mod_cluster is the ability to use server-side load metrics to determine how best to
balance requests.
T he Dynam icLoadBalanceFactorProvider bean computes the load balance factor of a node from
a defined set of load metrics.
<bean name="DynamicLoadBalanceFactorProvider" class="org.jboss.modcluster.load.imp
l.DynamicLoadBalanceFactorProvider" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service
=LoadBalanceFactorProvider",exposedInterface=org.jboss.modcluster.load.impl.Dynami
cLoadBalanceFactorProviderMBean.class)</annotation>
<constructor>
<parameter>
<set elementClass="org.jboss.modcluster.load.metric.LoadMetric">
<inject bean="BusyConnectorsLoadMetric"/>
<inject bean="HeapMemoryUsageLoadMetric"/>
</set>
</parameter>
</constructor>
<property name="history">9</property>
<property name="decayFactor">2</property>
</bean>

Load metrics can be configured with an associated weight and capacity:

1. T he weight (default is 1) indicates the significance of a metric with respect to the other metrics.
For example, a metric of weight 2 will have twice the impact on the overall load factor than a metric
of weight 1.
2. T he capacity of a metric serves 2 functions:
Each load metric contributes a value to the overall load factor of a node. T he load factors from each
metric are aggregated according to their weights.
In general, the load factor contribution of given metric is:
(load capacity) weight total weight

T he DynamicLoadBalanceFactorProvider applies a time decay function to the loads returned by each

metric. T he aggregate load, with respect to previous load values, can be expressed by the following
formula:
L = (L0 + L1D + L2D2 + L3D3 + ... + LHDH) (1 + D + D2 + D3 + ... DH)

... or more concisely as:

H
H
L = Li/Di *
i=0
i=0

Di

... where D = decayFactor and H = history.

51

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Setting history = 0 effectively disables the time decay function and only the current load for each
metric will be considered in the load balance factor computation.
T he mod_cluster proxy module expects the load factor to be an integer between 0 and 100, where 0
indicates max load and 100 indicates zero load. T herefore, the final load balance factor sent to the
proxy is:
100 - (L 100)

While you are free to write your own load metrics, the following LoadMetrics are available out of the
box:

11.2. Web Container metrics

1. ActiveSessionsLoadMetric
Requires an explicit capacity.
Uses SessionLoadMetricSource to query session managers
Analogous to method=S in mod_jk
For example:
<bean name="ActiveSessionsLoadMetric" class="org.jboss.modcluster.load.metric
.impl.ActiveSessionsLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=ActiveSessionsLoadMetric",exposedInterface=org.jboss.modcluster.load.me
tric.LoadMetricMBean.class)</annotation>
<constructor>
<parameter><inject bean="SessionLoadMetricSource"/></parameter>
</constructor>
<property name="capacity">1000</property>
</bean>
<bean name="SessionLoadMetricSource" class="org.jboss.modcluster.load.metric.
impl.SessionLoadMetricSource" mode="On Demand">
<constructor>
<parameter class="javax.management.MBeanServer"><inject bean="JMXKernel"
property="mbeanServer"/></parameter>
</constructor>
</bean>

2. BusyConnectorsLoadMetric
Returns the percentage of connector threads from the thread pool that are busy servicing
requests
Uses T hreadPoolLoadMetricSource to query connector thread pools
Analogous to method=B in mod_jk
For example:

52

Chapter 11. Load Metrics

<bean name="BusyConnectorsLoadMetric" class="org.jboss.modcluster.load.metric.

impl.BusyConnectorsLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=BusyConnectorsLoadMetric",exposedInterface=org.jboss.modcluster.load.me
tric.LoadMetricMBean.class)</annotation>
<constructor>
<parameter><inject bean="ThreadPoolLoadMetricSource"/></parameter>
</constructor>
</bean>
<bean name="ThreadPoolLoadMetricSource" class="org.jboss.modcluster.load.metr
ic.impl.ThreadPoolLoadMetricSource" mode="On Demand">
<constructor>
<parameter class="javax.management.MBeanServer"><inject bean="JMXKernel"
property="mbeanServer"/></parameter>
</constructor>
</bean>

3. ReceiveT rafficLoadMetric
Returns the incoming request traffic in KB/sec
Requires an explicit capacity
Uses RequestProcessorLoadMetricSource to query request processors
Analogous to method=T in mod_jk
For example:
<bean name="ReceiveTrafficLoadMetric" class="org.jboss.modcluster.load.metric
.impl.ReceiveTrafficLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=ReceiveTrafficLoadMetric",exposedInterface=org.jboss.modcluster.load.me
tric.LoadMetricMBean.class)</annotation>
<constructor>
<parameter class="org.jboss.modcluster.load.metric.impl.RequestProcessorL
oadMetricSource"><inject bean="RequestProcessorLoadMetricSource"/></parameter
>
</constructor>
<property name="capacity">1024</property>
</bean>
<bean name="RequestProcessorLoadMetricSource" class="org.jboss.modcluster.loa
d.metric.impl.RequestProcessorLoadMetricSource" mode="On Demand">
<constructor>
<parameter class="javax.management.MBeanServer"><inject bean="JMXKernel"
property="mbeanServer"/></parameter>
</constructor>
</bean>

4. SendT rafficLoadMetric
Returns the outgoing request traffic in KB/sec
Requires an explicit capacity
Uses RequestProcessorLoadMetricSource to query request processors
Analogous to method=T in mod_jk
For example:

53

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

<bean name="SendTrafficLoadMetric" class="org.jboss.modcluster.load.metric.im

pl.SendTrafficLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=SendTrafficLoadMetric",exposedInterface=org.jboss.modcluster.load.metri
c.LoadMetricMBean.class)</annotation>
<constructor>
<parameter class="org.jboss.modcluster.load.metric.impl.RequestProcessorL
oadMetricSource"><inject bean="RequestProcessorLoadMetricSource"/></parameter
>
</constructor>
<property name="capacity">512</property>
</bean>

5. RequestCountLoadMetric
Returns the number of requests/sec
Requires an explicit capacity
Uses RequestProcessorLoadMetricSource to query request processors
Analogous to method=R in mod_jk
For example:
<bean name="RequestCountLoadMetric" class="org.jboss.modcluster.load.metric.i
mpl.RequestCountLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=RequestCountLoadMetric",exposedInterface=org.jboss.modcluster.load.metr
ic.LoadMetricMBean.class)</annotation>
<constructor>
<parameter class="org.jboss.modcluster.load.metric.impl.RequestProcessorL
oadMetricSource"><inject bean="RequestProcessorLoadMetricSource"/></parameter
>
</constructor>
<property name="capacity">1000</property>
</bean>

11.3. System/JVM metrics

1. AverageSystemLoadMetric
Returns CPU load
Requires Java 1.6+.
Uses OperatingSystemLoadMetricSource to generically read attributes
For example:
<bean name="AverageSystemLoadMetric" class="org.jboss.modcluster.load.metric.
impl.AverageSystemLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=AverageSystemLoadMetric",exposedInterface=org.jboss.modcluster.load.met
ric.LoadMetricMBean.class)</annotation>
<constructor>
<parameter><inject bean="OperatingSystemLoadMetricSource"/></parameter>
</constructor>
</bean>
<bean name="OperatingSystemLoadMetricSource" class="org.jboss.modcluster.load
.metric.impl.OperatingSystemLoadMetricSource" mode="On Demand">
</bean>

54

Chapter 11. Load Metrics

2. SystemMemoryUsageLoadMetric
Returns system memory usage
Requires com.sun.management.OperatingSystemMXBean (available in Sun's JDK or
OpenJDK)
Uses OperatingSystemLoadMetricSource to generically read attributes
For example:
<bean name="SystemMemoryUsageLoadMetric" class="org.jboss.modcluster.load.met
ric.impl.SystemMemoryUsageLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=SystemMemoryUsageLoadMetric",exposedInterface=org.jboss.modcluster.load
.metric.LoadMetricMBean.class)</annotation>
<constructor>
<parameter><inject bean="OperatingSystemLoadMetricSource"/></parameter>
</constructor>
</bean>

3. HeapMemoryUsageLoadMetric
Returns the heap memory usage as a percentage of max heap size
For example:
<bean name="HeapMemoryUsageLoadMetric" class="org.jboss.modcluster.load.metri
c.impl.HeapMemoryUsageLoadMetric" mode="On Demand">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:se
rvice=HeapMemoryUsageLoadMetric",exposedInterface=org.jboss.modcluster.load.m
etric.LoadMetricMBean.class)</annotation>
</bean>

11.4. Other metrics

1. ConnectionPoolUsageLoadMetric
Returns the percentage of connections from a connection pool that are in use.
Uses ConnectionPoolLoadMetricSource to query JCA connection pools
For example:
<bean name="ConnectionPoolUsageMetric" class="org.jboss.modcluster.load.metric.imp
l.ConnectionPoolUsageLoadMetric" mode="On Demand"> <annotation>@org.jboss.aop.micr
ocontainer.aspects.jmx.JMX(name="jboss.web:service=ConnectionPoolUsageLoadMetric",e
xposedInterface=org.jboss.modcluster.load.metric.LoadMetricMBean.class)</annotation
>
<constructor>
<parameter><inject bean="ConnectionPoolLoadMetricSource"/></parameter>
</constructor>
</bean>
<bean name="ConnectionPoolLoadMetricSource" class="org.jboss.modcluster.load.metri
c.impl.ConnectionPoolLoadMetricSource" mode="On Demand">
<constructor>
<parameter class="javax.management.MBeanServer"><inject bean="JMXKernel" prope
rty="mbeanServer"/></parameter> </constructor>
</bean>

55

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 12. Load balancing demonstration

T he JBoss HT T P Connector includes a load balancing demonstration to show how different server-side
scenarios affect the client request routing performed by the load balancing proxy server. T he required
configuration is located in the JBOSS_EAP_DIST/m od_cluster/dem o directory.
T he application consists of two primary components:
/server/load-dem o.war
A WAR file to be deployed in JBoss Enterprise Application Platform or JBoss Enterprise Web
Server. T his WAR includes a number of servlets.
/client/lib/m od-cluster-dem o.jar
A web application that lets users launch a pool of threads, by sending requests through the
load balancer to the application's primary servlet. T he application displays information about
which servers are handling the requests. It can also send separate requests to the
application's load-generation servlets, allowing the user to see how certain load conditions
affect request load balancing.

T his application can be used to demonstrate how different worker-side scenarios impact the routing
decisions of the proxy server.

Important - Enterprise Web Server Limitation

If running the demonstration on JBoss Enterprise Web Server, the only metrics available will be
System, and JVM metrics. T he demonstration application is not designed to interact with any
other metrics in T omcat 6.

The demonstration application is not a load testing tool

T he demonstration application does not show the maximum load a cluster configuration can
handle.

12.1. Set up the demonstration

T he following procedure summarizes how to set up and start the demonstration. T hese steps will then
be explained in further detail. Once the demonstration is running, refer to Section 12.3, Interact with the
demonstration.
T ask: Start the Demo
Complete this task to set up the base requirements of the demonstration.
Prerequisites
Install and Configure the Worker Node. Refer to Section 8.2, Install and configure a worker node
Install and Configure the Proxy Server. Refer to Section 9.1, Static proxy configuration

56

Chapter 12. Load balancing demonstration

1. Start the Proxy Server

Navigate to HTTPD_DIST/sbin and start the proxy server.
[sbin]$ apachectl start

2. Start the Worker Node

In a terminal, execute the following command:
For JBoss Enterprise Web Server:
[home]$ ./JBOSS_EWS_DIST/tomcat6/bin/startup.sh

For JBoss Enterprise Application Platform:

[home]$ ./JBOSS_EAP_DIST/bin/run.sh

3. On JBoss Enterprise Web Server, specify the Catalina Service Name

T omcat 6 only: In $JBOSS_EWS_DIST/m od_cluster/src/dem o/resources/web.xm l, under
the <web-app> element, append a <context-param > directive, which specifies Catalina
as a service.
<context-param>
<param-name>service-name</param-name>
<param-value>Catalina</param-value>
</context-param>

4. Deploy Demo Web Archive to Worker Node

Copy load-dem o.war from JBOSS-EAP_DIST/m od_cluster/dem o/server into one of the
following directories:
For JBoss Enterprise Web Server:
JBOSS_EWS_DIST/tomcat6/webapps
For JBoss Enterprise Application Platform:
JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy
5. Start the Demonstration
Navigate to JBOSS_EAP_DIST/m od_cluster/dem o/client/, and start the demonstration.
[client]$ ./run-demo.sh

Result
T he demonstration starts, and the Load Balancing Demonstration window opens. Proceed to
T ask: Configure Client Control T ab Fields

57

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

12.2. Configure the demo client

You must configure the demonstration's Client Control parameters to ensure the client operates as
expected throughout the demonstration.
T ask: Configure Client Control T ab Fields
Complete this task to configure the Client Control tab of the Load Balancing Demonstration.
T erms
Proxy Hostname
Hostname of the load-balancing proxy server, or the IP address on which the proxy server is
listening for requests. T he default value for this field is localhost, or determined by the
m od_cluster.proxy.host system property, if set.
Edit the -Dm od_cluster.proxy.host=localhost value in run-dem o.sh to avoid resetting this value each time you use the demo.
Proxy Port
Port on which the load-balancing proxy server listens for requests. T he default value is 8000,
or determined by the m od_cluster.proxy.port property, if set.
Edit the -Dm od_cluster.proxy.port=8000 value in run-dem o.sh to avoid re-setting this
value each time you use the demo.
Context Path
T he part of the request URL that specifies the request is for load-dem o.war.

58

Chapter 12. Load balancing demonstration

Session Life
Number of seconds a client thread should use a session before invalidating or abandoning it.
T his should be a small value, or session stickiness can prevent changes in server load from
affecting the proxy server's routing decisions. When sticky sessions are enabled (strongly
recommended), the creation of new sessions allows the proxy to balance the workload.
Invalidate
When checked, specifies that a session is invalidated by the client thread when the thread
stops using a session. When unchecked, the session is abandoned, and exists on the worker
node until the session timeout expires.
Session T imeout
T he number of seconds a session can remain unused before the worker node can expire and
remove the session.
Deselecting Invalidate and setting a high value relative to session life causes a
significant number of unused sessions to accumulate on the server.
Num T hreads
Number of client threads to launch. Each thread repeatedly makes requests until the Stop
button is pressed, or a request receives a response other than HT T P 200.
Sleep T ime
Number of milliseconds that client threads should sleep between requests.
Startup T ime
Number of seconds over which the application should stagger client thread start-up. Staggering
the start time of sessions avoids the unrealistic situation where all sessions start and end
almost simultaneously. Staggering the start time allows the proxy to continually see new
sessions and decide how to route them.

Prerequisites
Complete T ask: Start the Demo before continuing with this task.

1. Click the Client Control tab.

2. Supply values for all fields on the Client Control tab, referring to the list of terms above.
3. Once you have specified the values, proceed to T ask: Interact with the Demonstration.

12.3. Interact with the demonstration

T erms
Active Sessions
A session is considered active if a client thread will ever send a request associated with the
session. When client threads stop using a session, they can either send a request to invalidate

59

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

it, or abandon it by no longer including its session cookie in requests.

Once a session has been abandoned, it is no longer reflected in the Session Balancing chart,
but will continue to exist on the worker node until it is removed based on session timeout
values.
T otal Clients
T he number of client threads created since the last time the Start button was clicked.
Live Clients
T he number of client threads currently running.
Failed Clients
T he number of clients threads that terminated abnormally, for example, a request that resulted
in something other than a HT T P 200 response.

T his section shows you how to configure and start using the demo.
T ask: Interact with the Demonstration
Complete this task to test the effects of changing load-balancing parameters.
Prerequisites
Complete T ask: Start the Demo.
Complete T ask: Configure Client Control T ab Fields.

1. Click on the Request Balancing tab to see how many requests are going to each of the
worker nodes.
2. Click on the Session Balancing tab to see how many active sessions are being hosted by
each of the worker nodes.
3. Stop some of the worker nodes, or undeploy load-dem o.war, and observe the effect that this
has on request and session balancing.
4. Restart some of the worker nodes, or re-deploy the load-dem o.war to some of the workers,
and observe the effect that this has on request and session balancing.
5. Experiment with adding artificial load to one or more worker nodes and observe the effects on load
and session balancing. (See Section 12.3.1, Generate artificial load for details.)

12.3.1. Generate artificial load

You can use the Load Balancing Demonstration to instruct your worker nodes to generate various types
of load, and then track how that load affects request and session balancing. Load generation is
controlled in the Server Load Control tab:
T arget Hostname, T arget Port
T he hostname and port number of the server on which to generate load. T here are two
strategies for setting these values:
1. Use the hostname and port of the proxy server. T he proxy will route the load to a worker

60

Chapter 12. Load balancing demonstration

node. However, the client does not maintain a session cookie for these requests, so
subsequent generated load will not necessarily be routed to the same worker.
2. If the worker nodes are running the HttpConnector and the AJP connector, you can
specify the IP address and port on which a worker's HttpConnector is listening. (T he
default is 8080.)
Load Creation Action
Specifies the type of load the worker node should generate.
Available Actions
Active Sessions
Generates server load by causing session creation on the target server.
Datasource Use
Generates server load by taking connections from the java:DefaultDS datasource
for a set time.
Connection Pool Use
Generates server load by blocking threads in the webserver connections pool for a set
time.
Heap Memory Pool Use
Generates server load by filling 50% of free heap memory for a set time.
CPU Use
Generates server CPU load by initiating a tight loop in a thread.
Server Receive T raffic
Generates server traffic receipt load by POST ing a large byte array to the server once
per second for a set time.
Server Send T raffic
Generates server traffic send load by making a request once per second, to which the
server responds with a large byte array.
Request Count
Generates server load by making numerous requests, increasing the request count on
the target server.

Params
Z ero or more parameters to pass to the specified load creation servlet, for example, Number of
Connections and Duration, as seen in the screenshot. T he parameters displayed, their name,
and their meaning depend on the selected Load Creation Action. T he label for each parameter
includes a tooltip that explains its use.

61

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

62

Part III. Internet Server API (ISAPI)

Part III. Internet Server API (ISAPI)

63

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 13. Overview

Read this chapter for a brief introduction about the Internet Server Application Programming Interface
(ISAPI).

13.1. What is Internet Server API

Internet Server Application Programming Interface (ISAPI) is a multi-tier application programming interface
for Microsoft Internet Information Services (IIS) web servers, and other compatible third-party web
servers.
T wo application types exist for ISAPI applications:
Extensions (full applications that run on IIS); and
Filters (applications that modify or enhance IIS functionality by constantly filtering for requests
relevant to their functionality).
ISAPI applications are implemented by compiling Extensions or Filters into Dynamic Link Library (DLL)
files. T hese DLLs must then be registered with the web server before they are available for use.

64

Chapter 14. Configuring the ISAPI connector on Windows

Chapter 14. Configuring the ISAPI connector on Windows

Read this chapter to learn how to configure the ISAPI connector to use JBoss Enterprise Application
Platform as a worker node for a Windows Server 2003 or 2008 master node.

14.1. Prerequisites and configuration assumptions

Complete the following prerequisites before continuing with the tasks that follow:
On the master node install one of the following technology combinations, and the appropriate Native
binary for its operating system and architecture.
Windows Server 2003 (32-bit) with Microsoft IIS 6
Windows Server 2003 (64-bit) with Microsoft IIS 6
Windows Server 2008 (32-bit) with Microsoft IIS 7.0
Windows Server 2008 (64-bit) with Microsoft IIS 7.0
On the worker nodes install JBoss Enterprise Application Platform 5.2 or later. T he Native
components are optional for worker nodes.
Refer to the Installation Guide for assistance with these installation prerequisites.

14.2. Configure server instance as a worker node

T ask: Configure Server Instance as a Worker Node
Complete this task to correctly configure your JBoss Enterprise Application Platform instance as a
worker node for use with Microsoft Internet Information Services (IIS).
Prerequisites
Section 14.1, Prerequisites and configuration assumptions

1. Create a server profile for each worker node

Make a copy of the server profile you want to configure as a worker node, and rename it worker-01 for example.
2. Give each instance a unique name
Edit the following line in the PROFILE\deploy\jbossweb.sar\server.xm l file of each new
worker instance:
<Engine name="jboss.web" defaultHost="localhost">

Add a unique jvm Route value, as shown. T his value is the identifier for this node in the
cluster.
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="worker-01">

3. Enable session handling

Uncomment the following line in the PROFILE\deployers\jbossweb.deployer\MET AINF\war-deployers-jboss-beans.xm l file of each worker node:
<property name="useJK">false</property>

65

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

T his property controls whether special session handling is used to coordinate with mod_jk and
other connector variants. Set this property to true in both worker nodes:
<property name="useJK">true</property>

4. Start worker nodes

Start each worker node in a separate command line interface. Ensure that each node is bound to
a different IP address with the --host switch and that the profile is specified with the -c switch.
JBOSS_EAP_DIST\bin\run.bat --host=127.0.0.1 -c worker-01

14.3. Microsoft IIS 6 initial clustering configuration

Microsoft IIS 6 contains basic ISAPI filters and ISAPI mapping as part of the default installation. Here we
create a filter to direct web requests to JBoss Enterprise Application Platform.
T ask: Define ISAPI Filter
Complete this task to define the ISAPI Filter on the Master server using the management console.
1. On the master server, open IIS Manager:
Start Run , then type inetm gr and hit Enter.
Start Control Panel Administrative T ools Internet Information Services (IIS)
Manager
T he IIS 6 Manager window opens.
2. In the tree view pane, expand Web Sites
3. Right click on Default Web Site, and then click Properties
T he Properties window opens.
4. Click the ISAPI Filters tab.
5. Click the Add button, and specify the following values in the Add/Edit Filter Properties
window:
Filter name:
Specify jboss (exactly as written).
Executable:
Specify NATIVE\sbin\isapi_redirect.dll .
6. Click OK to save the values, and close the Add/Edit Filter Properties dialog.

Note
T he ISAPI Filters tab now displays the jboss filter status and priority as Unknown
because IIS has not yet received requests for the resource. T he status and priority will
change to Loaded and High respectively once a request is executed.
T ask: Define ISAPI Virtual Directory
Complete this task to define the ISAPI virtual directory using the IIS management console.

66

Chapter 14. Configuring the ISAPI connector on Windows

1. Right click on Default Web Site, and then click New Add Virtual Directory .
T he Add Virtual Directory window opens.
2. Specify the following values in the Add Virtual Directory window:
Alias:
Specify jboss (exactly as written).
Physical path:
Specify NATIVE\sbin\ .
3. Click OK to save the values and close the Add Virtual Directory window.
4. In the tree view pane, expand Web Sites Default Web Site .
5. Right click on the jboss virtual directory, and then click Properties .
6. Click the Virtual Directory tab, and make the following changes:
Execute Permissions:
Select Scripts and Executables .
Read check box:
Select to activate Read access.
7. Click OK to save the values and close the jboss Properties window.
T ask: Define ISAPI Web Service Extension
Complete this task to define the ISAPI web service extension using the management console.
1. Click Web Service Extensions, and in the T asks group select Add a new Web service
extension.
T he New Web Service Extension window opens.
2. Add the following values to the New Web Service Extension window:
Extension name:
Specify jboss (exactly as written).
Required files:
Specify the path NATIVE\sbin\isapi_redirect.dll .
Set extension status to Allowed:
Select the check box.
3. Click OK to save the values and close the New Web Service Extension window.
4. Confirm the jboss Web Service Extension displays in the list.

14.4. Microsoft IIS 7 initial clustering configuration

Microsoft IIS 7 can be managed using the Management Console, or through the command prompt using
the APPCMD.EXE command tool.
T erms

67

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

ISAPI and CGI Restrictions

ISAPI and CGI restrictions are request handlers that allow dynamic content to execute on a
server. T hese restrictions are either CGI files (.exe) or ISAPI extensions (.dll). You can add
custom ISAPI or CGI restrictions if the IIS configuration system allows this. [ Configuring ISAPI
and CGI Restrictions in IIS 7 ] .

T ask: Define a JBoss Native ISAPI Restriction

Complete this task to define an ISAPI Restriction using the management console.
1. On the master server, open IIS Manager:
Start Run , then type inetm gr and hit Enter.
Start Control Panel Administrative T ools Internet Information Services (IIS)
Manager
T he IIS 7 Manager window opens.
2. In the tree view pane, select IIS 7 (referred to as Server Home).
T he IIS 7 Home Features View opens.
3. Double-click ISAPI and CGI Restrictions.
T he ISAPI and CGI Restrictions Features View opens.
4. In the Actions pane, click Add.
T he Add ISAPI or CGI Restriction window opens.
5. Specify the following values in the Add ISAPI or CGI Restriction window:
ISAPI or CGI Path:
Specify NATIVE\sbin\isapi_redirect.dll .
Description:
Specify jboss (exactly as written).
Allow extension path to execute
Select the check box.
6. Click OK to save the values, and close the Add ISAPI or CGI Restriction window.

Note
T he ISAPI and CGI Restrictions Features View now displays the jboss restriction
and path.
T ask: Define a JBoss Native Virtual Directory
Complete this task to define a virtual directory for the JBoss Native binary using the management
console.
1. Right click on Default Web Site, and then click Add Virtual Directory .
T he Add Virtual Directory window opens
2. Specify the following values in the Add Virtual Directory window:
Alias:

68

Chapter 14. Configuring the ISAPI connector on Windows

Specify jboss (exactly as written).

Physical path:
Specify NATIVE\sbin\ .
3. Click OK to save the values and close the Add Virtual Directory window.
T ask: Define a JBoss Native ISAPI Redirect Filter
Complete this task to define a JBoss Native ISAPI Redirect Filter using the management console.
1. In the tree view pane, expand Sites Default Web Site .
2. Double-click ISAPI Filters.
T he ISAPI Filters Features View opens.
3. In the Actions pane, click Add.
T he Add ISAPI Filter window opens.
4. Specify the following values in the Add ISAPI Filter window:
Filter name:
Specify jboss (exactly as written).
Executable:
Specify NATIVE\sbin\isapi_redirect.dll .
5. Click OK to save the values and close the Add ISAPI Filters window.
T ask: Enable the ISAPI-dll Handler
Complete this task to enable the ISAPI-dll handler using the management console.
1. In the tree view pane, select IIS 7 (referred to as Server Home).
T he IIS 7 Home Features View opens.
2. Double-click Handler Mappings.
T he Handler Mappings Features View opens.
3. In the Group by drop down box, select State .
T he Handler Mappings are displayed in Enabled and Disabled groups.
4. If ISAPI-dll is in the Disabled group, right mouse click and select Edit Feature Permissions .
5. Ensure the Read, Script, and Execute check boxes are selected.
6. Click OK to save the values and close the Edit Feature Perm issions window.

14.5. Configure a basic cluster with ISAPI

T ask: Configure ISAPI to serve a Basic Cluster
Complete this task to configure ISAPI to manage applications common to all servers on a single IP
address range, and route application requests to the correct server instance.
Use the configuration as an example when configuring your ISAPI cluster.

69

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Note
T his task does not provide instructions for load-balancing or server outage fail over. Refer to
Section 14.6, Configure a load-balancing cluster with ISAPI for configuration instructions.
Prerequisites
Complete the relevant Microsoft IIS clustering setup procedure. Refer to Section 14.3, Microsoft IIS 6
initial clustering configuration or Section 14.4, Microsoft IIS 7 initial clustering configuration for more
information.
T he following steps assume that the C:\connectors directory is used to store logs, properties
files, and NSAPI locks.

1. Create isapi_redirect.properties file

Create a new file named isapi_redirect.properties in the NATIVE\sbin\ directory.

Important
T he isapi_redirect.properties file must be in the same directory as the
isapi_redirect.dll file.
Append the following configuration block to isapi_redirect.properties:
# Configuration file for the ISAPI Redirector
# Extension uri definition
extension_uri=/jboss/isapi_redirect.dll
# Full path to the log file for the ISAPI Redirector
log_file=c:\connectors\isapi_redirect.log
# Log level (debug, info, warn, error or trace)
# Use debug only testing phase, for production switch to info
log_level=debug
# Full path to the workers.properties file
worker_file=c:\connectors\workers.properties
# Full path to the uriworkermap.properties file
worker_mount_file=c:\connectors\uriworkermap.properties
#Full path to the rewrite.properties file
rewrite_rule_file=c:\connectors\rewrite.properties

2. Optional: Create rewrite.properties file

T he rewrite.properties file allows you to specify simple URL rewrites specific to an
application. T his configuration file is optional, and can be excluded from the
isapi_redirect.properties file if URL rewrites are not required.
T he functionality offered is similar to Apache HT T P Server's mod_rewrite, but is less powerful.
You specify the rewrite path using name-value pairs. A simple example is where the app_01
application has an abstract directory name, containing images, and you want to remap that

70

Chapter 14. Configuring the ISAPI connector on Windows

directory to something more intuitive.

#Simple example, images are accessible under abc path
/app-01/abc/=/app-01/images/

3. Create uriworkermap.properties file

T he uriworkerm ap.properties file contains deployed application mapping configuration
information. Append the following lines to the file.
# images and css files for path /status are provided by worker01
/status=worker01
/images/*=worker01
/css/*=worker01
# Path /web-console is provided by worker02
# IIS (customized) error page is used for http errors with number greater or
equal to 400
# css files are provided by worker01
/web-console/*=worker02;use_server_errors=400
/web-console/css/*=worker01
# Example of exclusion from mapping, logo.gif will not be displayed
# !/web-console/images/logo.gif=*
# Requests to /app-01 or /app-01/something will be routed to worker01
/app-01|/*=worker01
# Requests to /app-02 or /app-02/something will be routed to worker02
/app-02|/*=worker02

4. Create workers.properties file

T he worker.properties file contains mapping definitions between worker labels and server
instances. Append the following lines to the file.
# An entry that lists all the workers defined
worker.list=worker01, worker02
# Entries that define the host and port associated with these workers
# First EAP server definition, port 8009 is standard port for AJP in EAP
worker.worker01.host=127.0.0.1
worker.worker01.port=8009
worker.worker01.type=ajp13
# Second EAP server definition
worker.worker02.host= 127.0.0.100
worker.worker02.port=8009
worker.worker02.type=ajp13

5. Restart IIS
Restart your IIS server to implement the changes. Execute the following commands for the IIS
version you are running:
IIS 6
C:\> net stop iisadmin /Y
C:\> net start w3svc

71

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

IIS 7
C:\> net stop was /Y
C:\> net start w3svc

6. Verify the Logs

Ensure you check the ISAPI logs once IIS has restarted. T he logs are saved to the file location
specified in the log_file property in isapi_redirect.properties. You should also check IIS
logs and the Event Viewer for other events of type Warning or Error.

14.6. Configure a load-balancing cluster with ISAPI

T ask: Configure ISAPI to serve a Load-Balancing Cluster
Complete this task to configure ISAPI to manage applications common to all servers, route requests to
JBoss Enterprise Application Platform instances, and redirect requests to live nodes when some nodes
are not online or experiencing connectivity issues.
Use the configuration as an example when configuring your ISAPI cluster.
Prerequisites
Complete the relevant Microsoft IIS clustering setup procedure. Refer to Section 14.3, Microsoft IIS 6
initial clustering configuration or Section 14.4, Microsoft IIS 7 initial clustering configuration for more
information.
T he following steps assume that the C:\connectors directory is used to store logs, properties
files, and NSAPI locks.

1. Create isapi_redirect.properties file

Create a new file named isapi_redirect.properties in the NATIVE\sbin\ directory.

Important
T he isapi_redirect.properties file must be in the same directory as the
isapi_redirect.dll file.
Append the following configuration block to the file:

72

Chapter 14. Configuring the ISAPI connector on Windows

# Configuration file for the ISAPI Redirector

# Extension uri definition
extension_uri=/jboss/isapi_redirect.dll
# Full path to the log file for the ISAPI Redirector
log_file=c:\connectors\isapi_redirect.log
# Log level (debug, info, warn, error or trace)
# Use debug only testing phase, for production switch to info
log_level=debug
# Full path to the workers.properties file
worker_file=c:\connectors\workers.properties
# Full path to the uriworkermap.properties file
worker_mount_file=c:\connectors\uriworkermap.properties
#OPTIONAL: Full path to the rewrite.properties file
rewrite_rule_file=c:\connectors\rewrite.properties

2. Optional: Create rewrite.properties file

T he rewrite.properties file allows you to specify simple URL rewrites specific to an
application. T his configuration file is optional, and can be excluded from the
isapi_redirect.properties file if URL rewrites are not required.
T he functionality offered is similar to Apache HT T P Server's mod_rewrite, but is less powerful.
You specify the rewrite path using name-value pairs. A simple example is where the app_01
application has an abstract directory name containing images, and you want to remap that
directory to something more intuitive.
#Simple example, images are accessible under abc path
/app-01/abc/=/app-01/images/

3. Create uriworkermap.properties file

T he uriworkerm ap.properties file contains deployed application mapping configuration
information. Append the following lines to the file.
# images, css files, path /status and /web-console will provided by nodes
defined in load-balancer
/css/*=router
/images/*=router
/status=router
/web-console|/*=router
# Example of exclusion from mapping, logo.gif will not be displayed
!/web-console/images/logo.gif=*
# Requests to /app-01 and /app-02 will be routed to nodes defined in loadbalancer
/app-01|/*=router
/app-02|/*=router
# mapping for management console, nodes in cluster can be enabled or disabled
here
/jkmanager|/*=status

4. Create workers.properties file

73

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

T he worker.properties file contains mapping definitions between worker labels and server
instances. Append the following lines to the file.
# The advanced router LB worker
worker.list=router,status
#
#
#
#
#
#
#

First EAP server definition, port 8009 is standard port for AJP in EAP
lbfactor defines how much the worker will be used.
The higher the number, the more requests are served
lbfactor is useful when one machine is more powerful
ping_mode=A all possible probes will be used to determine that
connections are still working

worker.worker01.port=8009
worker.worker01.host=127.0.0.1
worker.worker01.type=ajp13
worker.worker01.ping_mode=A
worker.worker01.socket_timeout=10
worker.worker01.lbfactor=3
# Second EAP server definition
worker.worker02.port=8009
worker.worker02.host= 127.0.0.100
worker.worker02.type=ajp13
worker.worker02.ping_mode=A
worker.worker02.socket_timeout=10
worker.worker02.lbfactor=1
# Define the LB worker
worker.router.type=lb
worker.router.balance_workers=worker01,worker02
# Define the status worker for jkmanager
worker.status.type=status

Note
For an explanation of workers.properties directives, refer to Appendix A, Reference:
workers.properties.
5. Restart IIS
Restart your IIS server to implement the changes. Execute the following commands for the IIS
version you are running:
IIS 6
C:\> net stop iisadmin /Y
C:\> net start w3svc

IIS 7
C:\> net stop was /Y
C:\> net start w3svc

74

Chapter 14. Configuring the ISAPI connector on Windows

6. Verify the Logs

Ensure you check the ISAPI logs once IIS has restarted. T he logs are saved to the file location
specified in the log_file property in isapi_redirect.properties. You should also check IIS
logs and the Event Viewer for other events of type Warning or Error.

75

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Part IV. Netscape Server API (NSAPI)

76

Chapter 15. What is Netscape Server API?

Chapter 15. What is Netscape Server API?

Read this chapter to gain a basic understanding of the Netscape Server API (NSAPI).
NSAPI is a programming interface that allows developers to extend the functionality of web server
software by creating applications (referred to as plug-ins) that run inside the server process itself.
T he goal of NSAPI, and its plug-ins, is to provide a method of creating different functional interfaces
between the web server and the back-end applications which run on it.
T he NSAPI plug-ins are designed to implement Server Application Functions (SAFs). SAFs consume a
HT T P request and take input from a server configuration database, and return a response to the client
based on the inputs. Each SAF is linked to a particular class, which directly relates to the requestresponse step it helps implement.
T he request-response steps (classes) are summarized in the following list:
1. Authorization translation;
2. Name translation;
3. Path checks;
4. Object type;
5. Request response;
6. Log transaction.
You are not required to provide a SAF for each request-response step: NSAPI allows you to substitute
your own custom functionality to the core request-response steps. You also have the choice of applying
the SAF globally, or constraining the SAF to a directory, file group, or individual file.

77

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 16. Configuring the NSAPI connector on Solaris

T he following tasks describe how to configure the NSAPI connector to use a JBoss Enterprise
Application Platform instance as a worker node for a Sun Java System Web Server (SJWS) master node.
Sun Java System Web Server has been renamed to the Oracle iPlanet Web Server. T he old name is
used throughout this guide for clarity.
In this section, all of the server instances are on the same machine. T o use different machines for each
instance, use the -b switch to bind your instance of JBoss Enterprise Application Platform to a public IP
address. Remember to edit the workers.properties file on the SJWS machine to reflect these
changes in IP address.

16.1. Prerequisites and configuration assumptions

Worker nodes are already installed with JBoss Enterprise Application Platform 5.2 or later. T he
Native components are not a requirement of the NSAPI connector. Refer to the Installation Guide for
assistance with this prerequisite.
T he master node is already installed with one of the following technology combinations, and the
appropriate Native binary for its operating system and architecture. Refer to the Installation Guide for
assistance with this installation prerequisite.
Solaris 10 x86 with Sun Java System Web Server 7.0 U8
Solaris 10 SPARC 64 with Sun Java System Web Server 7.0 U8

16.2. Configure server instance as a worker node

T ask: Configure a JBoss Enterprise Application Platform Worker Node
Follow this task to correctly configure a JBoss Enterprise Application Platform instance as a SJWS
worker node.
Prerequisites
Section 16.1, Prerequisites and configuration assumptions

1. Create a server profile for each worker node

Make a copy of the server profile that you wish to configure as a worker node. (T his procedure
uses the default server profile.)
[user@workstation jboss-ep-5.2]$ cd jboss-as/server
[user@workstation server]$ cp -r default/ default-01
[user@workstation server]$ cp -r default/ default-02

2. Give each instance a unique name

Edit the following line in the deploy/jbossweb.sar/server.xm l file of each new worker
instance:
<Engine name="jboss.web" defaultHost="localhost">

Add a unique jvm Route value, as shown. T his value is the identifier for this node in the
cluster.

78

Chapter 16. Configuring the NSAPI connector on Solaris

For the default-01 server profile:

<Engine name="jboss.web" defaultHost="localhost" jvmRoute="worker01">

For the default-02 server profile:

<Engine name="jboss.web" defaultHost="localhost" jvmRoute="worker02">

3. Enable session handling

Uncomment the following line in the deployers/jbossweb.deployer/MET A-INF/wardeployers-jboss-beans.xm l file of each worker node:
<property name="useJK">false</property>

T his property controls whether special session handling is used to coordinate with mod_jk and
other connector variants. Set this property to true in both worker nodes:
<property name="useJK">true</property>

4. Start your worker nodes

Start each worker node in a separate command line interface. Ensure that each node is bound to
a different IP address with the -b switch.
[user@workstation jboss-eap-5.2]$ ./jboss-as/bin/run.sh -b 127.0.0.1 -c
default-01
[user@workstation jboss-eap-5.2]$ ./jboss-as/bin/run.sh -b 127.0.0.100 -c
default-02

16.3. Initial clustering configuration

T ask: Configure Required Elements
Complete this task to configure the basic elements required for clustering using Sun Java Web Server
(SJWS) and NSAPI.
Prerequisites
T ask: Configure a JBoss Enterprise Application Platform Worker Node
Native zip archive extracted to the directory /tm p/connectors/. T he directory
/tm p/connectors/jboss-ep-5.2/native/ is referred to as NATIVE in this procedure.
T he directory /tm p/connectors is used as the storage location for logs, properties files, and
NSAPI locks.
SJWS is installed in one of the locations specified in the SJWS file path abbreviation in Section 1, File
Name Conventions.

1. Disable servlet mappings

Under Built In Servlet Mappings in the SJWS/PROFILE/config/default-web.xm l file, disable
the mappings for the following servlets, by commenting them out as shown:
default

79

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

invoker
jsp
<!-- ==================== Built In Servlet Mappings ===================== ->
<!-- The servlet mappings for the built in servlets defined above. -->
<!-- The mapping for the default servlet -->
<!--servlet-mapping>
<servlet-name>default</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping-->
<!-- The mapping for the invoker servlet -->
<!--servlet-mapping>
<servlet-name>invoker</servlet-name>
<url-pattern>/servlet/*</url-pattern>
</servlet-mapping-->
<!-- The mapping for the JSP servlet -->
<!--servlet-mapping>
<servlet-name>jsp</servlet-name>
<url-pattern>*.jsp</url-pattern>
</servlet-mapping-->

2. Load the required modules and properties

Append the following lines to the SJWS/PROFILE/config/m agnus.conf file:
Init fn="load-modules" funcs="jk_init,jk_service"
shlib="NATIVE/lib/nsapi_redirector.so" shlib_flags="(global|now)"
Init fn="jk_init" worker_file="/tmp/connectors/workers.properties"
log_level="debug" log_file="/tmp/connectors/nsapi.log"
shm_file="/tmp/connectors/jk_shm"

T hese lines define the location of the nsapi_redirector.so module used by the jk_init
and jk_service functions, and the location of the workers.properties file, which defines the
worker nodes and their attributes.

Note
T he lib directory in the NATIVE/lib/nsapi_redirector.so path applies only to 32bit machines. On 64-bit machines, this directory is called lib64 .

16.4. Configure a basic cluster with NSAPI

T ask: Configure a Basic Cluster with NSAPI
Complete this task to configure a basic cluster, where requests for particular paths are forwarded to
particular worker nodes. T he procedure specifies that worker02 serves the /nc path, while worker01
serves /status and all other paths defined in the first part of the obj.conf file.
Prerequisites

80

Chapter 16. Configuring the NSAPI connector on Solaris

T ask: Configure Required Elements

SJWS is installed in one of the locations specified in the SJWS file path abbreviation in Section 1, File
Name Conventions.

1. Define the paths to serve via NSAPI

Edit the SJWS/PROFILE/config/obj.conf file. Define paths that should be served via NSAPI at
the end of the default Object definition, as shown:
<Object name="default">
[...]
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
</Object>

from="/status" name="jknsapi"
from="/images(|/*)" name="jknsapi"
from="/css(|/*)" name="jknsapi"
from="/nc(|/*)" name="jknsapi"
from="/jmx-console(|/*)" name="jknsapi"

You can map the path of any application deployed on your JBoss Enterprise Platform instance in
this obj.conf file. In the example code, the /nc path is mapped to an application deployed under
the name nc.
2. Define the worker that serves each path
Edit the SJWS/PROFILE/config/obj.conf file and add the following jknsapi Object definition
after the default Object definition.
<Object name="jknsapi">
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="worker01" path="/status"
Service fn="jk_service" worker="worker02" path="/nc(/*)"
Service fn="jk_service" worker="worker01"
</Object>

T his jknsapi Object defines the worker nodes used to serve each path that was assigned to
nam e="jknsapi" in the default Object.
In the example code, the third Service definition does not specify a path value, so the worker
node defined (worker01) serves all of the paths assigned to jknsapi by default. In this case,
the first Service definition in the example code, which assigns the /status path to worker01, is
superfluous.
3. Define the workers and their attributes
Create a workers.properties file in the location you defined in Step 2.
Define the list of worker nodes and each worker node's properties in this file:

81

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

# An entry that lists all the workers defined

worker.list=worker01, worker02
# Entries that define the host and port associated with these workers
worker.worker01.host=127.0.0.1
worker.worker01.port=8009
worker.worker01.type=ajp13
worker.worker02.host=127.0.0.100
worker.worker02.port=8009
worker.worker02.type=ajp13

4. Restart the server

Once your Sun Java System Web Server instance is configured, restart it so that your changes
take effect.
For Sun Java System Web Server 6.1:
SJWS/PROFILE/stop
SJWS/PROFILE/start

For Sun Java System Web Server 7.0:

SJWS/PROFILE/bin/stopserv
SJWS/PROFILE/bin/startserv

16.5. Configure a load-balanced cluster with NSAPI

T ask: Configure a Load-balanced Cluster with NSAPI
Complete this task to configure a load-balanced cluster consisting of two worker nodes.
Prerequisites
T ask: Configure Required Elements
SJWS is installed in one of the locations specified in the SJWS file path abbreviation in Section 1, File
Name Conventions.

1. Define the paths to serve via NSAPI

Open SJWS/PROFILE/config/obj.conf and define paths that should be served through
NSAPI at the end of the default Object definition, as shown:
<Object name="default">
[...]
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
NameTrans fn="assign-name"
</Object>

from="/status" name="jknsapi"
from="/images(|/*)" name="jknsapi"
from="/css(|/*)" name="jknsapi"
from="/nc(|/*)" name="jknsapi"
from="/jmx-console(|/*)" name="jknsapi"
from="/jkmanager/*" name="jknsapi"

You can map the path of any application deployed on your JBoss Enterprise Platform instance in
this obj.conf file. In the example code, the /nc path is mapped to an application deployed under

82

Chapter 16. Configuring the NSAPI connector on Solaris

this obj.conf file. In the example code, the /nc path is mapped to an application deployed under
the name nc.
2. Define the worker that serves each path
Open SJWS/PROFILE/config/obj.conf and add the following jknsapi Object definition after
the default Object definition.
<Object name="jknsapi">
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="status" path="/jkmanager(/*)"
Service fn="jk_service" worker="router"
</Object>

T his jknsapi Object defines the worker nodes used to serve each path that was assigned to
nam e="jknsapi" in the default Object.
3. Define the workers and their attributes
Create SJWS/PROFILE/config/workers.properties.
Define the list of worker nodes and each worker node's properties in this file:

Note
For an explanation of workers.properties directives, refer to Appendix A, Reference:
workers.properties

# The advanced router LB worker

worker.list=router,status
#First EAP server definition, port 8009 is standard port for AJP in EAP
#
#lbfactor defines how much the worker will be used.
#The higher the number, the more requests are served
#lbfactor is useful when one machine is more powerful
#ping_mode=A all possible probes will be used to determine that
#connections are still working
worker.worker01.port=8009
worker.worker01.host=127.0.0.1
worker.worker01.type=ajp13
worker.worker01.ping_mode=A
worker.worker01.socket_timeout=10
worker.worker01.lbfactor=3
#Second EAP server definition
worker.worker02.port=8009
worker.worker02.host=127.0.0.100
worker.worker02.type=ajp13
worker.worker02.ping_mode=A
worker.worker02.socket_timeout=10
worker.worker02.lbfactor=1
# Define the LB worker
worker.router.type=lb
worker.router.balance_workers=worker01,worker02
# Define the status worker
worker.status.type=status

83

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

4. Restart the server

Once your Sun Java System Web Server instance is configured, restart it so that your changes
take effect.
For Sun Java System Web Server 6.1:
SJWS/PROFILE/stop
SJWS/PROFILE/start

For Sun Java System Web Server 7.0:

SJWS/PROFILE/bin/stopserv
SJWS/PROFILE/bin/startserv

84

Part V. Common load balancing tasks

Part V. Common load balancing tasks

85

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 17. HTTP session state replication

HT T P session state replication is a means of distributing clients' state across multiple servers. T he
following terms are important in understanding load balancing. Refer to the Clustering Guide part of the
Administration and Configuration Guide for details of associated JBoss Enterprise Application Platform
high availability options.
Software Load Balancer
A dedicated software-based service designed to distribute HT T P client session requests across
multiple computer servers (cluster). T he primary directive of a software load balancer is to maximize
resource utilization, reduce request response times, and prevent server overload. T he load balancer
forwards client session requests to a server cluster, based on server load and availability.
Client Session
A semi-permanent connection between the client (an application) and the server. T he load balancer
determines whether the client session is created with persistence, or whether a client session is
redistributed based on server load and availability.
Session Persistence
Session persistence is a feature where information about a client's session is stored by the server so
that if the client's connection is interrupted temporarily, the session can continue at the time the
connection error occurred. A persistent session is also commonly known as a sticky session .
Sticky Session
See Session Persistence.
Section 3.1, Configure worker nodes in mod_jk describes how to configure session state persistence
in the load balancer to ensure a client in a session is always routed to the same server node.
Session persistence on its own is not a best-practice solution because if a server fails, all session state
data is lost. For example, if a customer is about to make a purchase on a web site, and the server
hosting the shopping cart instance fails, session state data associated with the cart is lost permanently.
One way of preventing client session data loss is to replicate session data across the servers in the
cluster. If a server node fails or is shut down, the load balancer can fail over the next client request to
any server node and obtain the same session state.
Using a load balancer that supports session persistence, but not configuring web applications for
session replication, allows you to scale your implementation by avoiding the cost of session state
replication: each request for a session will always be handled by the same node.
Session state replication is more expensive than basic session persistence, but the reliability it provides
for session state data makes it important when creating a load balanced cluster.

17.1. Enabling session replication in your application

T o enable replication of your web application you must tag the application as distributable in the
web.xm l descriptor. Here's an example:

86

Chapter 17. HTTP session state replication

<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<distributable/>
</web-app>

You can further configure session replication using the replication-config element in the jbossweb.xm l file. However, the replication-config element only needs to be set if one or more of the
default values described below is unacceptable. All of the configuration elements are optional, and can
be omitted if the default value is acceptable.
Here is an example:
<!DOCTYPE jboss-web PUBLIC
"-//JBoss//DTD Web Application 5.0//EN"
"http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
<jboss-web>
<replication-config>
<cache-name>custom-session-cache</cache-name>
<replication-trigger>SET</replication-trigger>
<replication-granularity>ATTRIBUTE</replication-granularity>
<replication-field-batch-mode>true</replication-field-batch-mode>
<use-jk>false</use-jk>
<max-unreplicated-interval>30</max-unreplicated-interval>
<snapshot-mode>INSTANT</snapshot-mode>
<snapshot-interval>1000</snapshot-interval>
<session-notificationpolicy>com.example.CustomSessionNotificationPolicy</session-notification-policy>
</replication-config>
</jboss-web>

<replication-trigger>
element determines when the container should consider that session data must be replicated
across the cluster. T he rationale for this setting is that after a mutable object stored as a
session attribute is accessed from the session, in the absence of a setAttribute call, the
container has no clear way to know if the object (and hence the session state) has been
modified and needs to be replicated. T his element has 3 valid values:
SET _AND_GET is conservative but not optimal (performance-wise): it will always replicate
session data even if its content has only been accessed and not modified. T his setting made (a
little) sense in JBoss Enterprise Application Platform 4 since using it was a way to ensure that
every request triggered replication of the session's timestamp. Since setting
m ax_unreplicated_interval to 0 accomplishes the same thing at much lower cost, using
SET _AND_GET makes no sense with JBoss Enterprise Application Platform 5 or JBoss
Enterprise Web Platform 5.
SET _AND_NON_PRIMIT IVE_GET is conservative but will only replicate if an object of a nonprimitive type has been accessed (in effect, the object is not of a well-known immutable JDK

87

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

type such as Integer, Long, String, etc.) T his is the default value.
SET assumes that the developer will explicitly call setAttribute on the session if the data
needs to be replicated. T his setting prevents unnecessary replication and can have a major
beneficial impact on performance, but requires very good coding practices to ensure
setAttribute is always called whenever a mutable object stored in the session is modified.
In all cases, calling setAttribute marks the session as needing replication.

<cacheName>
Specifies the name of the JBoss Cache configuration that should be used for storing
distributable sessions and replicating them around the cluster. T his element lets web
applications that require different caching characteristics specify the use of separate, differently
configured, JBoss Cache instances. In JBoss Enterprise Application Platform 4 the cache to
use was a server-wide configuration that could not be changed per web application. T he default
value is standard-session-cache. See Section 17.3, Configure the JBoss Cache instance
used for session state replication for more details on JBoss Cache configuration for web-tier
clustering.
<replication-field-batch-mode>
Specifies whether all replication messages associated with a request will be batched into one
message. T his is applicable only if replication-granularity is FIELD. If
replication-field-batch-m ode is set to true, fine-grained changes made to objects
stored in the session attribute map will replicate only when the HT T P request is finished;
otherwise they replicate as they occur. Setting this to false is not advised because it
increases the number of replication requests and the chance of session state being out of
sync. Default is true.

FIELD Deprecated
T he FIELD granularity option is now deprecated as JBoss Cache, which provides this
feature, is to be subsituted by Infinispan (Infinispan does not support this granularity).

<useJK>
Specifies whether the container should assume that a JK-based software load balancer (for
example,. mod_jk, mod_proxy, mod_cluster) is being used for load balancing for this web
application. If set to true, the container will examine the session ID associated with every
request and replace the jvm Route portion of the session ID if it detects a failover.
You need only set this to false for web applications whose URL cannot be handled by the JK
load balancer.
<max-unreplicated-interval>
Specifies the maximum interval between requests, in seconds, after which a request will trigger
replication of the session's timestamp regardless of whether the request has otherwise made
the session dirty. Such replication ensures that other nodes in the cluster are aware of the
most recent value for the session's timestamp and will not incorrectly expire an unreplicated
session upon failover. It also results in correct values for

88

Chapter 17. HTTP session state replication

HttpSession.getLastAccessedT im e() calls following failover.

T he default value is null (in effect, unspecified). In this case the session manager will use the
presence or absence of a jvm Route configuration on its enclosing JBoss Web Engine (see
Section 3.2, Configuring JBoss to work with mod_jk) to determine whether JK is used.
A value of 0 means the timestamp will be replicated whenever the session is accessed. A value
of -1 means the timestamp will be replicated only if some other activity during the request (for
example,. modifying an attribute) has resulted in other replication work involving the session. A
positive value greater than the HttpSession.getMaxInactiveInterval() value will be
treated as probable misconfiguration and converted to 0; (in effect, replicate the metadata on
every request). Default value is 60.
<snapshot-mode>
Specifies when sessions are replicated to the other nodes. Possible values are INST ANT (the
default) and INT ERVAL.
T he typical value, INST ANT , replicates changes to the other nodes at the end of requests,
using the request processing thread to perform the replication. In this case, the snapshotinterval property is ignored.
With INT ERVAL mode, a background task is created that runs every snapshot-interval
milliseconds, checking for modified sessions and replicating them.
Note that this property has no effect if replication-granularity is set to FIELD. If it is
FIELD, INST ANT mode will be used.
<snapshot-interval>
Specifies how often (in milliseconds) the background task that replicates modified sessions
should be started for this web application. Only meaningful if snapshot-m ode is set to
INT ERVAL.
<session-notification-policy>
Specifies the fully qualified class name of the implementation of the
ClusteredSessionNotificationPolicy interface that should be used to govern whether
servlet specification notifications should be emitted to any registered HttpSessionListener,
HttpSessionAttributeListener and/or HttpSessionBindingListener.

Important
Event notifications that may be appropriate in non-clustered environment may not
necessarily be appropriate in a clustered environment; see
https://jira.jboss.org/jira/browse/JBAS-5778 for an example of why a notification may not
be desired. Configuring an appropriate ClusteredSessionNotificationPolicy
gives the application author fine-grained control over what notifications are issued.

89

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

17.2. HttpSession passivation and activation

Passivation
T he process of controlling memory usage by removing relatively unused sessions from memory while
storing them in persistent storage.
If a passivated session is requested by a client, it can be "activated" back into memory and removed
from the persistent store. JBoss Enterprise Application Platform 5 supports HttpSession passivation
from clustered web applications where the web.xm l file includes the distributable directive.
Passivation occurs at three points during the life cycle of a web application:
When the container requests the creation of a new session. If the number of currently active
sessions exceeds a configurable limit, an attempt is made to passivate sessions to make room in
memory.
Periodically (by default every ten seconds) as the JBoss Web background task thread runs.
When the web application is deployed and a backup copy of sessions active on other servers is
acquired by the newly deploying web application's session manager.
A session is passivated if one of the following conditions is true:
T he session has not been in use for longer than a configurable maximum idle time.
T he number of active sessions exceeds a configurable maximum and the session has not been in
use for longer than a configurable minimum idle time.
In both cases, sessions are passivated on a Least Recently Used (LRU) basis.

17.2.1. Configuring HttpSession passivation

Session passivation behavior is configured in the jboss-web.xm l deployment descriptor in your web
application's WEB-INF directory.
<!DOCTYPE jboss-web PUBLIC
"-//JBoss//DTD Web Application 5.0//EN"
"http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
<jboss-web>
<max-active-sessions>20</max-active-sessions>
<passivation-config>
<use-session-passivation>true</use-session-passivation>
<passivation-min-idle-time>60</passivation-min-idle-time>
<passivation-max-idle-time>600</passivation-max-idle-time>
</passivation-config>

</jboss-web>

max-active-sessions
Determines the maximum number of active sessions allowed. If the number of sessions managed by
the session manager exceeds this value and passivation is enabled, the excess will be passivated
based on the configured passivation-m in-idle-tim e. If after passivation is completed (or if
passivation is disabled), the number of active sessions still exceeds this limit, attempts to create new
sessions will be rejected. If set to -1 (the default), there is no limit.

90

Chapter 17. HTTP session state replication

T he total number of sessions in memory includes sessions replicated from other cluster nodes that
are not being accessed on this node. T ake this into account when setting m ax-active-sessions.
Whether or not buddy replication is enabled will also affect the number of sessions replicated from
other nodes.
Say, for example, that you have an eight node cluster, and each node handles requests from 100
users. With total replication, each node would store 800 sessions in memory. With buddy replication
enabled, and the default num Buddies setting (1), each node will store 200 sessions in memory.
use-session-passivation
Determines whether session passivation will be enabled for the web application. Default is false.
passivation-min-idle-time
Determines the minimum time (in seconds) that a session must have been inactive before the
container will consider passivating it in order to reduce the active session count to obey the value
defined by m ax-active-sessions. A value of -1 (the default) disables passivating sessions
before passivation-m ax-idle-tim e. Neither a value of -1 nor a high value are recommended if
m ax-active-sessions is set.
passivation-max-idle-time
Determines the maximum time (in seconds) that a session can be inactive before the container
should attempt to passivate it to save memory. Passivation of such sessions will take place
regardless of whether the active session count exceeds m ax-active-sessions. Should be less
than the session-tim eout setting in web.xm l . A value of -1 (the default) disables passivation
based on maximum inactivity.

17.3. Configure the JBoss Cache instance used for session state
replication
T he container for a distributable web application makes use of JBoss Cache to provide HT T P session
replication services around the cluster. It integrates with the CacheManager service to obtain a
reference to a JBoss Cache instance. For more information, refer to the Distributed Caching with JBoss
Cache and JBoss Cache Configuration and Deployment chapters in the Administration and Configuration
Guide
T he name of the JBoss Cache configuration to use is controlled by the cacheNam e element in the
application's jboss-web.xm l (see Section 17.1, Enabling session replication in your application). In
most cases this does not need to be set because the default value of standard-session-cache is
appropriate.
T he JBoss Cache configurations in the CacheManager service expose a number of options.
T he standard-session-cache configuration is already optimized for the web session replication
use case, and most of the settings should not be altered. Administrators may be interested in altering
the following settings:
cacheMode
T he default is REPL_ASYNC, which specifies that a session replication message sent to the cluster
does not wait for responses from other cluster nodes confirming that the message has been
received and processed. T he alternative mode, REPL_SYNC, offers a greater degree of confirmation
that session state has been received, but reduces performance significantly.
enabled property in the buddyReplicationConfig section
Set to true to enable buddy replication. Default is false.
numBuddies property in the buddyReplicationConfig section

91

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Set to a value greater than the default (1) to increase the number of backup nodes onto which
sessions are replicated. Only relevant if buddy replication is enabled.
buddyPoolName property in the buddyReplicationConfig section
A way to specify a preferred replication group when buddy replication is enabled. JBoss Cache tries
to pick a buddy who shares the same pool name (falling back to other buddies if not available). Only
relevant if buddy replication is enabled.
multiplexerStack
Name of the JGroups protocol stack the cache should use.
clusterName
Identifying name JGroups will use for this cache's channel. Only change this if you create a new
cache configuration, in which case this property should have a different value from all other cache
configurations.
If you wish to use a completely new JBoss Cache configuration rather than editing one of the existing
ones, refer to Deployment via the CacheManager Service section in the Administration and Configuration
Guide .

92

Chapter 18. High-Availability Web Sessions

Chapter 18. High-Availability Web Sessions

JBoss Enterprise Application Server allows you to make web sessions highly available by storing them
in a database table.

Session Replication Preferred

HT T P session replication with JBoss Cache is the preferred approach to securing web session
failover. It is strongly recommended to use this approach if possible (refer to Chapter 17, HTTP
session state replication).
T o provide high availability web sessions, you can configure JBoss Application Server to store the web
session state in a database table. If the server then becomes unavailable, the web session state is still
preserved in the database table and can be used by failover servers, while if using session replication,
the web session is available on the server and the respective failover nodes. T he high availability web
session setup can be useful in a WAN with several application server instance or in combination with
session replication.
T o make web sessions highly available, you need to do the following:
configure the server to use the session manager set on your web application (JBoss Application
Server by default ignores the web application session manager and switches to
JBossCacheManager automatically);
configure your web applications to use DataSourcePersistentManager as their session manager (the
manager handles the storing of web sessions to the defined database table);
create the web session table in the target database and deploy the datasource, which will provide
the connection between the session manager and the database table.
Configuring JBoss Enterprise Application Server
T o configure JBoss Enterprise Application Server to allow storing of sessions in a database, disable
overriding of the session manager set on your web application (overriden to JBossCacheManager; this
allows the web application to use its own session manager):
1. Open the JBOSS_HOME/server/PROFILE/deployers/jbossweb.deployer/MET AINF/war-deployers-jboss-beans.xm l file for editing.
2. Set the overrideDistributableManager property of the WarDeployer bean to false:
<bean name="WarDeployer"
class="org.jboss.web.tomcat.service.deployers.TomcatDeployer">
. . .
<!-- "False" disables overriding the session manager for distributable
webapps -->
<property name="overrideDistributableManager">false</property>
</bean>

Configuring Web Application

Configure your web application to use the database persistent session manager:
1. In the application's WEB-INF directory, create the context.xm l file, which will define what

93

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

session manager is to be used as well as the manager's attributes.

Important
Note that it is not recommended to add the manager definition to the jboss-web.xm l file,
although it is the standard web application deployment descriptor. T he goal of using the
context.xm l file instead is to avoid any unnecessary changes to the existing JBoss
Application Server code.
2. In the context.xm l file, add the Manager element and its attributes:
className
fully-qualified class name of the session manager implementation
dataSourceJndiName
datasource that allows the session manager to communicate with the database that
stores the web sessions

<Context cookies="true" crossContext="true">

<Manager
className="org.jboss.web.tomcat.service.session.persistent.DataSourcePersistent
Manager"
dataSourceJndiName="java:HttpSessionDS"/>
:</Context>

Note
T he className and dataSourceJndiName are compulsory attributes. You can also define
further Context and Manager attributes (refer to Section 18.1,
DataSourcePersistentManager Configuration Attributes.
Configuring Database and Datasource
Create the database session table, which will hold the web session data and then create the respective
datasource:
1. Create the web session ( httpsessions ) database table:
You can change the name of the table and of the columns; however, make sure to configure the
DataSourcePersistentManager attributes appropriately.
Individual columns must be able to store values of particular datatypes:
creationtime and lastaccess : java long values
maxinactive and version : java int value
metadata : serialized java objects (currently not used)
attributes : serialized java objects (stores the session attributes map; should be large enough
to store your largest sessions)
primary key : synthetic primary key (optional, make sure there is a UNIQUE INDEX on app + id).
T he following command creates the table with default settings in the most common databases
(MySQL, IBM DB2, Oracle Database):

94

Chapter 18. High-Availability Web Sessions

CREATE TABLE httpsessions (app VARCHAR(255) NOT NULL, id VARCHAR(255) NOT

NULL,
fullId VARCHAR(255) NOT NULL, creationtime BIGINT NOT NULL,
maxinactive BIGINT NOT NULL, version INT NOT NULL, lastaccess BIGINT NOT
NULL,
isnew CHAR(1) NOT NULL, valid CHAR(1) NOT NULL, metadata VARBINARY NULL,
attributes LONGVARBINARY NOT NULL,
CONSTRAINT app_id PRIMARY KEY (app, id))

2. Deploy an appropriate datasource to allow the DataSourcePersistentManager to communicate

with the database (refer to the chapter on Datasource Configuration in the Administration and
Configuration Guide. Make sure the datasource is set up as local-tx-datasource (xa-datasources
are not supported).
3. Add the dataSourceJndiName with the jndi-name of the created datasource to
DataSourcePersistentManager element in the context.xm l file.

18.1. DataSourcePersistentManager Configuration Attributes

T he DataSourcePersistentManager element must define the className and dataSourceJndiName
attributes. Apart from these, it can define other properties to specify manager's behavior and the way it
interacts with the database.
Compulsory Properties
className
fully-qualified class name of the org.apache.catalina.Manager implementation (that is,
org.jboss.web.tom cat.service.session.persistent.DataSourcePersistentMa
nager)
dataSourceJndiName
JNDI name of the data source, which defines the database connection to the httpsessions

Properties Defining the Database Connection Properties

connectionName
value of the username parameter to pass to the DataSource.getConnection method (if
null, the getConnection with no arguments is called)
connectionPassword
password to pass to DataSource.getConnection
sessionT able
name of the database session table in which sessions are stored (by default httpsessions)
sessionAppCol
name of the column with the web application name associated with the session (by default app)

95

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

sessionIdCol
name of the column with the core, immutable part of a session ID (by default id; this and the
sessionAppCol columns form the unique index for the table)
sessionFullIdCol
name of the column with the full session ID (including any mutable element added to the core
session ID, for example a jvmRoute; by default fullid)
sessionCreationT imeCol
name of the column with the time when the session was created (of the long datatype, by
default creationtim e)
sessionMaxInactiveCol
name of the column with the maximum number of milliseconds the session can remain
unaccessed before expiring (by default m axinactive)
sessionVersionCol
name of the column which stores the session's "version" (session version is incremented each
time the session is persisted; by default version)
sessionLastAccessedCol
name of the column with the timestamp of the last session access (take the long data type
value; by default lastaccess)
sessionNewCol
Name of the column with the flag indicating whether the session is new (session is considered
new if it was not yet joined by the client; by default isnew
sessionValidCol
name of the column with the flag indicating whether the session is valid (by default isvalid
sessionMetadataCol
name of the column which can store serialized metadata about the session (currently unused;
by default m etadata
sessionAttributeCol
name of the column with the serialized session attribute map (by default attributes)

Properties Defining the Manager's Behavior

cleanupInterval
minimum period of time in seconds that must lapse from the last cleaning of old "abandoned"
sessions from the database before the next cleaning (by default 14400 seconds, that is, 4
hours)

96

Chapter 18. High-Availability Web Sessions

A session is abandoned if the only server that was handling the session requests was shut
down before the session expired, no further requests for the session were received so that the
session did not fail over to another server. Such session do not expire on the normal session
expiration checks. T herefore a special process runs periodically to clean the session from the
database.
replicationT riggerString
activity executed during a request that makes the session database persistent (the activity with
the replication-trigger property SET )
maxUnreplicatedInterval
maximum interval between requests, in seconds, after which the session's timestamp is
persisted regardless of whether the request caused the session to become dirty in any other
way
useJK
flag determining whether the container assumes a JK-based software load balancer is used for
load balancing (if set to true, the container examines the session ID associated with every
request and replace the jvmRoute portion of the session ID if it detects a failover)
maxActiveAllowed
maximum number of active sessions
useSessionPassivation
flag for enabling/disabling session passivation (session is removed from memory but remains
always in the persistent store)
passivationMinIdleT ime
minimum time, in seconds, a session must be inactive before passivated
passivationMaxIdleT ime
maximum time, in seconds, a session can be inactive before passivated
processExpiresFrequency
frequency at which the background process thread calls the session manager to perform
background processes (for example, expire or passivate sessions; (by default, every 10
seconds)
T his configuration is defined as value N with the background cleanup process called 1 in N
callings to the session manager. Default is 1, that is, the cleanup process is performed every
time the manager is called by the background process, that is cleanup is performed every 10
seconds. For example, if set to 6, the manager performs the cleanup once a minute (1/6, that is
once in 60 seconds).
sessionNotificationPolicy
fully qualified class name of the implementation of the ClusteredSessionNotificationPolicy

97

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

interface that is used to govern whether servlet specification notifications is emitted to any
registered HttpSessionListener, HttpSessionAttributeListener or HttpSessionBindingListener.

98

Chapter 19. Using clustered Single Sign-on (SSO)

Chapter 19. Using clustered Single Sign-on (SSO)

JBoss supports clustered single sign-on (SSO), allowing a user to authenticate to one web application
and to be recognized on all web applications that are deployed on the same virtual host, regardless of
whether they are deployed on that same machine or on another node in the cluster.
Authentication replication is handled by JBoss Cache. Clustered single sign-on support is a JBossspecific extension of the non-clustered org.apache.catalina.authenticator.SingleSignOn
valve that is a standard part of T omcat and JBoss Web.

19.1. Configuration
T o enable clustered single sign-on, you must add the ClusteredSingleSignOn valve to the
appropriate Host elements of the
JBOSS_HOME/server/PROFILE/deploy/jbossweb.sar/server.xm l file. T he valve element is
already included in the standard file; you just need to uncomment it. T he valve configuration is shown
here:
Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /

T he element supports the following attributes:

className is a required attribute to set the Java class name of the valve implementation to use.
T his must be set to org.jboss.web.tom cat.service.sso.ClusteredSingleSign.
cacheConfig is the name of the cache configuration to use for the clustered SSO cache. Default is
clustered-sso.

Note
For more information about cache configuration, refer to The JBoss Enterprise Application
Platform CacheManager Service section in the Administration and Configuration Guide .
treeCacheName is deprecated; use cacheConfig. Specifies a JMX ObjectName of the JBoss
Cache MBean to use for the clustered SSO cache. If no cache can be located from the
CacheManager service using the value of cacheConfig, an attempt to locate an MBean registered
in JMX under this ObjectName will be made. Default value is
jboss.cache:service=T om catClusteringCache.
cookieDomain is used to set the host domain to be used for SSO cookies. See Section 19.4,
Configuring the cookie domain for more. Default is "/".
maxEmptyLife is the maximum number of seconds an SSO with no active sessions will be usable
by a request. T he clustered SSO valve tracks which cluster nodes are managing sessions related to
an SSO. When a node is shutdown, all local copies of a session are invalidated. If a further user
request is made within the time specified by maxEmptyLife, the request will fail over to another
cluster node, activating the backup copy of the session. If maxEmptyLife is set to 0, the SSO valve
terminates together with the local session copies. Default is 1800, (30 minutes).
processExpiresInterval is the minimum number of seconds between efforts by the valve to find
and invalidate SSOs that have exceeded their maxEmptyLife. Does not imply effort will be spent on
such cleanup every processExpiresInterval, just that it will not occur more frequently than that.
Default is 60.
requireReauthentication is a flag to determine whether each request needs to be reauthenticated
to the security Realm. If true, this valve uses cached security credentials (username and password)

99

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

to the security
. If true, this valve uses cached security credentials (username and password)
to reauthenticate to the JBoss Web security Realm for each request associated with an SSO
session. If false, the valve can itself authenticate requests based on the presence of a valid SSO
cookie, without rechecking with the Realm. Setting to true can allow web applications with different
security-dom ain configurations to share an SSO. Default is false.

19.2. SSO behavior

T he user will not be challenged as long as they access only unprotected resources in any of the web
applications on the virtual host.
Upon access to a protected resource in any web app, the user will be challenged to authenticate, using
the log in method defined for the web app.
Once authenticated, the roles associated with this user will be utilized for access control decisions
across all of the associated web applications, without challenging the user to authenticate themselves to
each application individually.
If the web application invalidates a session (by invoking the
javax.servlet.http.HttpSession.invalidate() method), the user's sessions in all web
applications will be invalidated.
A session timeout does not invalidate the SSO if other sessions are still valid.

19.3. Limitations
T here are a number of known limitations to this T omcat valve-based SSO implementation:
Only useful within a cluster of EAP instances; SSO does not propagate to other resources.
Requires use of container-managed authentication (via login-config element in web.xm l).
Requires cookies. SSO is maintained via a cookie and URL rewriting is not supported.
Unless requireReauthentication is set to true, all web applications configured for the same
SSO valve must share the same JBoss Web Realm and JBoss Security security-dom ain. T his
means:
In server.xm l you can nest the Realm element inside the Host element (or the surrounding
Engine element), but not inside a context.xm l packaged with one of the involved web
applications.
T he security-dom ain configured in jboss-web.xm l or jboss-app.xm l must be
consistent for all of the web applications.
Even if you set requireReauthentication to true and use a different security-dom ain
(or, less likely, a different Realm ) for different webapps, the varying security integrations must all
accept the same credentials (for example,. username and password).

19.4. Configuring the cookie domain

T he SSO valve supports a cookieDom ain configuration attribute. T his attribute allows configuration of
the SSO cookie's domain (the set of hosts to which the browser will present the cookie). By default the
domain is "/", meaning the browser will only present the cookie to the host that issued it. T he
cookieDom ain attribute allows the cookie to be scoped to a wider domain.
For example, suppose we have a case where two apps, with URLs http://app1.xyz.com and
http://app2.xyz.com , that wish to share an SSO context. T hese apps could be running on different

100

Chapter 19. Using clustered Single Sign-on (SSO)

servers in a cluster or the virtual host with which they are associated could have multiple aliases. T his
can be supported with the following configuration:
Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"
cookieDomain="xyz.com" /

101

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Chapter 20. Complete working example

Following are a set of example configuration files for a complete working example.
Proxy Server
A proxy server listening on localhost:
LoadModule
LoadModule
LoadModule
LoadModule

slotmem_module modules/mod_slotmem.so
manager_module modules/mod_manager.so
proxy_cluster_module modules/mod_proxy_cluster.so
advertise_module modules/mod_advertise.so

Listen 127.0.0.1:6666
<VirtualHost 127.0.0.1:6666>
<Directory />
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Directory>
KeepAliveTimeout 60
MaxKeepAliveRequests 0
ManagerBalancerName mycluster
ServerAdvertise On
AdvertiseFrequency 5
</VirtualHost>
<Location /mod_cluster-manager>
SetHandler mod_cluster-manager
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>

JBoss Web Client Listener

Following are the listener definitions for
JBOSS_EAP_DIST/server/PROFILE/deploy/jbossweb.sar/server.xm l.
<!-- Non-clustered mode -->
<Listener
className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycl
eListener" delegateBeanName="ModClusterService"/>
<!-- Clustered mode
Listener
className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycl
eListener" delegateBeanName="HAModClusterService"/-->

JBoss Web Client Service Dependencies

Following are the required dependencies for the WebServer bean in
JBOSS_EAP_DIST/server/PROFILE/deploy/jbossweb.sar/MET A-INF/jboss-beans.xm l. Add
them to the existing dependencies.

102

Chapter 20. Complete working example

<bean name="WebServer"
class="org.jboss.web.tomcat.service.deployers.TomcatService">
<!-- ... -->
<depends>ModClusterService</depends><!-- Non-clustered mode -->
<!--depends>HAModClusterService</depends--><!-- Clustered mode -->
<!-- ... -->
</bean>

Example iptables Firewall Rules

Following are a set of example firewall rules using iptables, for a cluster node on the 192.168.1.0/24
subnet.
/sbin/iptables -I INPUT 5 -p udp -d 224.0.1.0/24 -j ACCEPT -m comment --comment
"mod_cluster traffic"
/sbin/iptables -I INPUT 6 -p udp -d 224.0.0.0/4 -j ACCEPT -m comment --comment
"JBoss Cluster traffic"
/sbin/iptables -I INPUT 9 -p udp -s 192.168.1.0/24 -j ACCEPT -m comment --comment
"cluster subnet for inter-node communication"
/sbin/iptables -I INPUT 10 -p tcp -s 192.168.1.0/24 -j ACCEPT -m comment -comment "cluster subnet for inter-node communication"
/etc/init.d/iptables save

103

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Reference: workers.properties
Apache HT T P Server worker nodes are Servlet containers that are mapped to the mod_jk load
balancer. T he worker nodes are defined in HTTPD_DIST/conf/workers.properties. T his file
specifies where the different Servlet containers are located, and how calls should be load-balanced
across them.
T he workers.properties file contains two sections:
Global Properties
T his section contains directives that apply to all workers.
Worker Properties
T his section contains directives that apply to each individual worker.

Each node is defined using the Worker Properties naming convention. T he worker name can only
contain alphanumeric characters, limited to [a-z][A-Z ][0-9][_\-].
T he structure of a Worker Property is worker.worker_name.directive.
worker
T he constant prefix for all worker properties.
worker_name
T he arbitrary name given to the worker. For example: node1, node_01, Node_1.
directive
T he specific directive required.

T he main directives required to configure worker nodes are described below.

Note
For the full list of worker.properties configuration directives, refer directly to the Apache
T omcat Connector - Reference Guide
worker.properties Global Directives
worker.list
Specifies the list of worker names used by mod_jk. T he workers in this list are available to map
requests to.

104

Reference: workers.properties

Note
A single node configuration, which is not managed by a load balancer, must be set to
worker.list=[worker name].

workers.properties Mandatory Directives

type
Specifies the type of worker, which determines the directives applicable to the worker. T he
default value is ajp13, which is the preferred worker type to select for communication between
the web server and Apache HT T P Server.
Other values include ajp14, lb, status.
For detailed information about ajp13, refer to T he Apache T omcat Connector - AJP Protocol
Reference

workers.properties Connection Directives

host
T he hostname or IP address of the worker. T he worker node must support the ajp13 protocol
stack. T he default value is localhost.
You can specify the port directive as part of the host directive by appending the port number
after the hostname or IP address. For example: worker.node1.host=192.168.2.1:8009
or worker.node1.host=node1.exam ple.com :8009
port
T he port number of the remote server instance listening for defined protocol requests. T he
default value is 8009, which is the default listen port for AJP13 workers. If you are using AJP14
workers, this value must be set to 8011.
ping_mode
Specifies the conditions under which connections are probed for their current network health.
T he probe uses an empty AJP13 packet for the CPing, and expects a CPong in return, within a
specified timeout.
You specify the conditions by using a combination of the directive flags. T he flags are not
comma-separated. For example, a correct directive flag set is
worker.node1.ping_m ode=CI, which specifies that the connection will be pinged on
connecting to the server and at regular intervals afterward.
C (connect)
Specifies the connection is probed once after connecting to the server. You specify the
timeout using the connect_timeout directive, otherwise the value for ping_timeout
is used.

105

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

P (prepost)
Specifies the connection is probed before sending each request to the server. You
specify the timeout using the prepost_timeout directive, otherwise the value for
ping_timeout is used.
I (interval)
Specifies the connection is probed during regular internal maintenance cycles. You
specify the idle time between each interval using the connection_ping_interval
directive, otherwise the value for ping_timeout is used.
A (all)
T he most common setting, which specifies all directive flags are applied. For
information about the *_timeout advanced directives, refer directly to Apache T omcat
Connector - Reference Guide.

ping_timeout
Specifies the time to wait for CPong answers to a CPing connection probe (refer to ping_mode).
T he default value is 10000 (milliseconds).

worker.properties Load Balancing Directives

lbfactor
Specifies the load-balancing factor for an individual worker, and is only specified for a member
worker of a load balancer.
T his directive defines the relative amount of HT T P request load distributed to the worker
compared to other workers in the cluster.
A common example where this directive applies is where you want to differentiate servers with
greater processing power than others in the cluster. For example, if you require a worker to take
three times the load of other workers, specify worker.worker name.lbfactor=3
balance_workers
Specifies the worker nodes that the load balancer must manage. T he directive can be used
multiple times for the same load balancer, and consists of a comma-separated list of worker
names as specified in the workers.properties file.
sticky_session
Specifies whether requests for workers with SESSION IDs are routed back to the same worker.
T he default is 0 (false). When set to 1 (true), load balancer persistence is enabled.
For example, if you specify worker.loadbalancer.sticky_session=0, each request is
load balanced between each node in the cluster. In other words, different requests for the same
session will go to different servers based on server load.
If worker.loadbalancer.sticky_session=1, each session is persisted (locked) to one

106

Reference: workers.properties

server until the session is terminated, providing that server is available.

107

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Reference: Java properties

Read this appendix to learn about the JBoss HT T P Connector (mod_cluster) configuration properties
that apply to either a JBoss Enterprise Application Platform or JBoss Enterprise Application Platform
server node.

B.1. Proxy configuration

T he configuration values are sent to proxies under the following conditions:
During server startup;
When a proxy is detected through the advertise mechanism;
During error recovery, when a proxy's configuration is reset.
Proxy Configuration Attributes
stickySession
Specifies whether subsequent requests for a given session should be routed to the same
node, if possible. Default is true.
stickySessionRemove
Specifies whether the httpd proxy should remove session stickiness if the balancer is unable to
route a request to the node to which it is stuck. T his property is ignored if stickySession
is false. Default is false.
stickySessionForce
Specifies whether the httpd proxy should return an error if the balancer is unable to route a
request to the node to which it is stuck. T his property is ignored if stickySession is
false. Default is true.
workerT imeout
Specifies the number of seconds to wait for a worker to become available to handle a request.
When all the workers of a balancer are usable, mod_cluster will retry after a while
(workerT imeout/100) to find a usable worker.
A value of -1 indicates that the httpd will not wait for a worker to be available and will return an
error if no workers are available. Default is -1.
maxAttempts
Specifies the number of times the httpd proxy will attempt to send a given request to a worker
before aborting. T he minimum value is 1: try once before aborting. Default is 1.
flushPackets
Specifies whether packet flushing is enabled or disabled. Default is false.
flushWait
Specifies the time to wait before flushing packets. A value of -1 means wait forever. Default is 1.

108

Reference: Java properties

ping
T ime to wait (in seconds) for a pong answer to a ping. Default is 10.
smax
Specifies the soft maximum idle connection count. T he maximum value is determined by the
httpd thread configuration ( T hreadsPerChild or 1 ).
ttl
Specifies the time (in seconds) idle connections persist, above the sm ax threshold. Default is
60.
nodeT imeout
Specifies the time (in seconds) mod_cluster waits for the back-end server response before
returning an error.
mod_cluster always uses a CPing/CPong before forwarding a request. T he
connectiontim eout value used by mod_cluster is the ping value. Default is -1.
balancer
Specifies the name of the load-balancer. Default is m ycluster.
domain
Optional parameter, which specifies how load is balanced across jvmRoutes within the same
domain. dom ain is used in conjunction with partitioned session replication (for example,
buddy replication).

109

JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide

Revision history
Revision 5.2.0-103.4 00
Rebuild with publican 4.0.0

2013-10-30

Rdiger Landmann

Revision 5.2.0-103
T hu Jul 12 2013
Russell Dickenson
Incorporated changes for JBoss Enterprise Application Platform 5.2.0 GA. For information about
documentation changes to this guide, refer to Release Notes 5.2.0.
Revision 5.1.2-100
T hu Dec 8 2011
Jared Morgan
Incorporated changes for JBoss Enterprise Application Platform 5.1.2 GA. For information about
documentation changes to this guide, refer to Release Notes 5.1.2 .
Revision 5.1.1-100
Mon Jul 18 2011
Jared Morgan
Incorporated changes for JBoss Enterprise Application Platform 5.1.1 GA. For information about
documentation changes to this guide, refer to Release Notes 5.1.1 .

110