Using mod_jk 1.2.x with JBoss and IIS7

Quick Overview

1. Download jk 1.2.x isapi redirector

2. Install IIS

3. Configure IIS

4. Create registry entry for isapi redirector

5. Configure the jk workers

6. Configure the IIS URIs served by jk (the applications served by JBoss)

7. Configure JBossWeb(Tomcat) (Give each JBoss node a jvmRoute for session stickness)

8. Restart JBoss

9. Restart IIS

10. Test it

More Details

This wiki outlines the various steps required to install a basic load-balanced or non load-balanced solution based on JBoss 4.2.x and jk 1.2 running as an extension within IIS 7.0.

NOTE: Installers were available for some previous releases of JK. Current releases just publish the dll of the redirector. VB script files are mentioned in a couple of forums, but are difficult to track down. The author has made IIS7 work properly with the manual procedure outlined below.

Step 1: Download jk 1.2.x isapi redirector

Create a directory to hold the redirector and associated files (JK_HOME). Create subdirectories bin, log and conf.

Download the latest dll available from Tomcats's 'Download Tomcat connector section' page . Always download the latest stable release if possible.

Rename the dll to isapi_redirect.dll and drop it in JK_HOME/bin directory.

NOTE: Don't use releases prior to mod_jk 1.2.26. Earlier releases appear to have problems with IIS7.

Step 2: Install IIS 7.0

Select 'Turn Windows features on or off' from Control Panel->Programs and Features.

Enable ISAPI Extensions and ISAPI Filters in World Wide Web Services->Application Development Features.

Step 3: Configure IIS 7.0

Start Administrative Tools->IIS Manager

On the server node open the "ISAPI and CGI Restrictions" and add the isapi_redirect.dll allowing the extension path to execute.

On the default web site add a new virtual directory. Enter its alias as "jakarta" and the physical directory path where the isapi_redirect.dll resides (JK_HOME\bin).

On the default web site open the "ISAPI Filters" and add the isapi_redirect.dll naming the filter "jkfilter".

On the node of the "jakarta" virtual directory, open the "Handler Mappings" and enable the "ISAP-dll" handler by editing the "ISAPI-dll" handler permissions to enable "Read", "Script" and "Execute".

Step 4: Create registry entry for isapi redirector

The redirector dll needs this registry entry to find its configuration files. It must be created manually with the Registry Editor

Control Panel->Administrative Tools->System Configuration->Tools->Registry Editor

Create a registry key HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0

Add String value named extension_uri with value /jakarta/isapi_redirect.dll

Add String value named log_file with a value of the full file path to a log file eg C:\jk\log\isapi.log

Add String value named log_level with value debug, info, error or emerg

Add String value named worker_file with a value of the full file path to the workers.properties file eg C:\jk\conf\workers.properties

Add String value named worker_mount_file with a value of the full file path to the uriworkermap.properties file eg C:\jk\conf\uriworkermap.properties

Step 5: Configuring workers

JK workers are configured in the JK_HOME\conf\workers.properties file. A simple non load balanced config looks like this:

worker.list=node1

worker.node1.port=8009
worker.node1.host=localhost
worker.node1.type=ajp13
worker.node1.ping_mode=A
worker.node1.socket_timeout=10

A load balanced configuration looks like this:

# Define list of workers that will be used
# for mapping requests
# Note worker list does not include the nodes
worker.list=loadbalancer,status

#Define a template worker to be used
worker.template.port=8009
worker.template.type=ajp13
worker.template.ping_mode=A
worker.template.socket_timeout=10

# Define Node1
# modify the host as your host IP or DNS name.
worker.node1.reference=worker.template
worker.node1.host=node1.mydomain.com
worker.node1.type=ajp13

# Define Node2
# modify the host as your host IP or DNS name.
worker.node2.reference=worker.template
worker.node2.host= node2.mydomain.com
worker.node2.type=ajp13

# Load-balancing worker
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2

# Status worker for managing load balancer
worker.status.type=status

Please review http://tomcat.apache.org/connectors-doc/reference/workers.html for the directive descriptions.

The load balancer defaults to sticky_session=True. It is extremely important to consult the Tomcat and JBoss clustering documentation before turning sticky_session off.

Step 6: Create the URI to worker map file

The URIs handled by each worker are defined in JK_HOME\conf\uriworkermap.properties . The simplest URI map is:

/*=node1

This directs all requests to the worker named node1, which must be in the worker.list . Requests may be selectively directed with a map such as:

/jmx-console=loadbalancer
/jmx-console/*=loadbalancer
/web-console=loadbalancer
/web-console/*=loadbalancer

This directs requests for jmx-console and web-console to the loadbalancer worker, but all others are handled by IIS.

Step 7: Configure JBossWeb(Tomcat)

If running load balanced we also need to name each node according to the names specified in workers.properties.

Edit JBOSS_HOME/server/CONFIGURATION/deploy/jboss-web.deployer/server.xml

Locate the

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

The jvmRoute attribute must match a name specified in workers.properties under worker.loadbalancer.balance_workers, not worker.list

In the server.xml file, make sure that the AJP 1.3 Connector is uncommented, e.g.:

    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" address="${jboss.bind.address}" protocol="AJP/1.3"
         emptySessionPath="true" enableLookups="false" redirectPort="8443" maxThreads="400" connectionTimeout="600000"/>

If you are only accepting requests via IIS/IsapiRedirector, you can comment out the regular HTTP Connector; Tomcat then won't listen on port 8080.

Finally, we need to tell JBossWeb(Tomcat) to add the jvmRoute value to its session cookies so that isapi redirector can route incoming requests.

Edit JBOSS_HOME/server/CONFIGURATION/deploy/jboss-web.deployer/META-INF/jboss-service.xml

Locate the

               <attribute name="UseJK">true</attribute>

Step 8: Restart JBoss AS.

Step 9: Restart IIS

Step 10: Access the JBoss AS jmx-console through IIS by browsing to http://localhost/jmx-console and you should see the JBoss JMX console page.

Resources

JBoss Clustering Guide: Additional details about HTTP Session replication, workers.properties and other goodies.

The Apache Tomcat Connector - Documentation Index

The Apache Tomcat Connector - workers.properties configuration

The Apache Tomcat Connector - Configuring Apache

The Apache Tomcat Connector - Configuring IIS

Tomcat - Workers HowTo

Tomcat user-mail archive

mod_jk FAQ

An Optimal base Apache, Tomcat, mod_jk 1.2 configuration

Using mod_jk 1.2 with a Firewall

Referenced by: