UsingMod_jk1.2WithJBossAndIIS7

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

element and add an attribute jvmRoute:
<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

element with a name of UseJK, and set its value to "true":
               <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: