Six steps to JBoss (and Tomcat) with IIS 7

I've had a devil of a time getting IIS 7 talking to JBoss. It took 3 different sites and flash of insight to get all the settings working. I'm not a system administrator, and I'm not an IIS expert, so I may have missed a default somewhere or gone further than I needed to. Here's what I did, in hopes it helps you.

There are 6 things you have to do:

1. acquire and configure the Jakarta ISAPI filter which transfers IIS ISAPI calls to AJP calls to Tomcat (or the JBoss Tomcat web server),

2. install the ISAPI services on IIS,

3. tell IIS the particular DLL is authorized to run,

4. enable 32-bit application pools (if you're running IIS in 64-bit),

5. configure the jakarta filter on your specific site within IIS, and

6. verify that IIS can write to the log directory and file you specified for the jakarta ISAPI filter.

In sequence, then:

1. acquire and configure the Jakarta ISAPI filter.

Download isapi_redirect.dll from http://tomcat.apache.org/download-connectors.cgi and place it in a directory on your server; mine is in \inetpub\jakarta.

The Tomcat connector configuration documentation (http://tomcat.apache.org/connectors-doc/) is quite good, but for two points:

a. you don't need to make the registry entries cited. You can configure the connector with a properties file named isapi_redirect.properties in the same directory as the isapi_redirect.dll.

b. the specific IIS 7 setup requires some extra steps and verification is a bit different (but shares many similarities) with the documentation provided (which works pretty well through IIS 6).

My isapi_redirect.properties file is shown below:

# 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:\inetpub\logs\isapi.log

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

# Full path to the workers.properties file
worker_file=C:\inetpub\jakarta\worker_files\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=C:\inetpub\jakarta\worker_files\uriworkermap.properties

You'll need to create workermap and workers files, but the Tomcat documentation for that is pretty good. For a simple app, the uriworkermap.properties file might contain a single line:

/myappcontextroot|/*=myworker

...and your workers.properties file might consist only of:

worker.list=myworker

worker.myworker.type=ajp13

worker.myworker.host=localhost

worker.myworker.port=8009

You'll want to look at the reference material for other configuration options, most especially connection_pool_size, for starters.

2. install the ISAPI services on IIS

Add role services as shown below; ensure the ISAPI services are selected and installed. (click for a larger image)



3. tell IIS the particular DLL is authorized to run (click for a larger image)



4. enable 32-bit application pools (if you're running IIS in 64-bit on a CPU where there's no 64-bit build for isapi_connector.dll) (click for a larger image)



5. configure the jakarta filter on your specific site within IIS

There are several steps here; the first 2 seem to be requirements of the Tomcat connector specifically rather than of IIS:

a. create a virtual "jakarta" directory pointed at the .dll

right-click on the site and select "add virtual directory"; point to the directory containing your isapi_connector.dll, and name the directory "jakarta".

b. enable that directory for execute privileges within IIS (not on the file system)

select the virtual directory, select "features view", and open the "Handler Mapping" control. "Edit Feature Permissions..." as shown below, and verify that ISAPI-dll is in the "Enabled" list.

(click for a larger image)



c. add the dll to the filters list

...as shown:



6. verify that IIS can write to the log directory and file you specified for the jakarta ISAPI filter.

Unlike earlier releases, there's almost no way to know if the ISAPI filter has loaded and is running. If the connector isn't working, though, there are two possibilities:

1. IIS hasn't handed the request off to the ISAPI filter, and
2. IIS has handed off the request, but the filter isn't configured correctly and the requests aren't being delivered to JBoss or Tomcat.

You can distinguish between these cases by looking at the filter log: if IIS actually invokes the ISAPI filter, you'll get a log file; it there's no log file, then most likely, IIS hasn't invoked the filter.

If your filter is misconfigured, change the filter log level to "debug" and run a few requests; almost always, the filter logging has enabled me to find and fix the configuration issue.