Version 5

    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 file eg C:\jk\conf\


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


    Step 5: Configuring workers


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


    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
    #Define a template worker to be used
    # Define Node1
    # modify the host as your host IP or DNS name.
    # Define Node2
    # modify the host as your host IP or DNS name.
    # Load-balancing worker
    # Status worker for managing load balancer

    Please review 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\ . The simplest URI map is:


    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:


    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


    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">

    The jvmRoute attribute must match a name specified in 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.




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


    The Apache Tomcat Connector - Documentation Index


    The Apache Tomcat Connector - 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: