HOWTO: Set Up IIS and the Jakarta isapi_redirect Connector

Introduction

The isapi_redirect.dll is a version of mod_jk compiled as an ISAPI Filter (not Application) for IIS. Although IIS4 should still work, IIS4 is no longer a supported web server configuration.

Step 1 - Download the Binary

Download the latest binary of isapi_redirect.dll from a tomcat connectors download mirror. At the time of this writing, the latest version is named isapi_redirect-1.2.28.dll. There are two versions of this DLL.  One is the standard version of the connector and the other is a version compiled to support IIS5+ chunked transfers.  I have only utilized the former dll, so this is the one this article will assume will be used.

isapi_redirect.dll should be placed somewhere on the hard disk on your server.  This article assumes the download location to be c:\tomcat\connector but you could put it anywhere you want.  Optionally, create a copy of isapi_redirect-1.2.28.dll and call it isapi_redirect.dll or simply rename the existing file.  Create two subdirectories, for example c:\tomcat\connector\conf and c:\tomcat\connector\logs.

Step 2 - Create Configuration Files

The binary isapi_redirect.dll available for download does not include any skeleton configuration files.  These will all need to be edited by hand in your favorite windows editor, (Cream is a nice choice).  There are three files that you will need to create, workers.properties, uriworkermap.properties, and isapi_redirect.properties.  The isapi_redirect.properties file resides within the same directory that you placed the dll in, (c:\tomcat\connector).  workers.properties and uriworkmap.properties are placed inside the "conf" subdirectory, (for example, c:\tomcat\connector\conf). 

  • isapi_redirect.properties defines generic configuration information for the DLL, specifically identifying items like the location of workers.properties and uriworkermap.properties, log file location or logging levels.  Optionally, instead of creating an isapi_redirect.properties file, you could create a registry file and import it into the Windows registry but the configuration file option seems to provide for more future flexibility, especially if you are virtual hosting IIS sites.
  • workers.properties defines the configuration data specific to a worker.  A worker can point to a local app server container instance, a remote container, or a set of load-balanced application servers.
  • uriworkermap.properties defines the name of the web application and the worker that it points to.  Optionally, uriworkermap.properties also provides configuration details for URL re-writing

 

Creating the isapi_redirect.properties file (or isapi_redirect.reg)

 

A generic isapi_redirect.properties file is included below, which you can use as a template for your own.

# Configuration file for the Jakarta ISAPI Redirector

# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/jakarta/isapi_redirect.dll

# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\connector\logs\isapi_redirect.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Full path to the workers.properties file
worker_file=c:\tomcat\connector\conf\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=c:\tomcat\connector\conf\uriworkermap.properties

Optionally, if you would rather go the registry route (for example, if the server you're working on is dedicated to this application and you don't need to worry about virtual hosting), create a registry import file named isapi_redirect.reg with the following values and then import this into your Windows Registry.

 REGEDIT4 
 [HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0] 
 "server_root"="C:\\tomcat\\connector\\"
 "extension_uri"="/jakarta/isapi_redirector.dll" 
 "worker_file"="C:\\tomcat\\connector\\conf\\workers.properties" 
 "log_file"="C:\\tomcat\\connector\\logs\mod_jk.log" "worker_mount_file"="C:\\tomcat\connector\conf\uriworkermap.properties" 
 "log_level"="INFO"

Creating the workers.properties file

 

A basic template for connecting IIS with a local tomcat instance (a 'local worker') is provided below.  Templates and configurations for remote workers will be provided in a future How-To.

 worker.list=local
 worker.local.port=8009
 worker.local.host=localhost
 worker.local.type=ajp13
 worker.local.lbfactor=1

 

Creating the uriworkermap.properties file

 

For the example in this article, we will use a generic name for the web application called "webapp".  The section below describes the syntax of resource-to-worker mappings for the "webapp" application.

/webapp/*=local

Step 3 - IIS Configuration Changes

 

Install the ISAPI Filter - All Versions of IIS

 

The isapi_redirect ISAPI filter is installed much like any other filter.  Simply bring up the properties for the web site, select the ISAPI Filters tab, then click the Add button.  Set Filter Name to something descriptive, like 'jakarta isapi_redirect' and set Executable to the physical location of the isapi_redirect.dll.  NOTE: I have had mixed results when installing the filter globally so I always now install it in each web site. NOTE 2: If you have more than one web site and want to keep everything separate, rename isapi_redirect.dll for each web site to something with a distinct name like website1_isapi_redirect.dll, website2_isapi_redirect.dll, etc., before installing the relevant isapi filter into your IIS site configuration.

 

Create the 'jakarta' virtual directory - All Versions of IIS

 

Create a virtual directory off the root of your web site and point it to the physical location of the isapi_redirect.dll.  Name the virtual directory 'jakarta'.  Permissions for this virtual directory must include Execute permissions.

 

Web Server Version Specific Changes

 

If you are using IIS5 or IIS6, you will also need to modify the allowable Web Service Extensions and enable support for isapi_redirect.dll. Open the IIS Manager, go to Web Service Extensions. Create a new extension, name it "jakarta connector" and input the path to the isapi_redirect.dll and then check the box to enable it.

If you are using IIS7, you pretty much do the same thing but you don't enable if from the Web Service Extension setting--you double click the ISAPI and CGI Restrictions setting and add it there.

Once these changes are made, restart IIS and you are done. You can verify that the ISAPI filter loaded by re-opening Internet Service Manger and checking your loaded ISAPI filters. If it is not loaded, re-check your registry settings (if you imported the registry settings) or re-check paths in your configuration files because there is a mistake there somewhere. 


Creative Commons Attribution-ShareAlike 3.0 Unported