Apache Tomcat Logo

This is a walkthrough to help you use ISAPI Filters to run Tomcat on a Windows Server Machine that uses IIS7. If you're interested in setting up Tomcat under Apache, see this other lab.usgin.org walkthrough.

A couple of other webpages that I used to learn how to do this are located here and here.

1. Prerequisites 
   1. IIS must be installed with ISAPI Extensions and ISAPI Filters enabled. You can double check this in Windows Server 2008 by right-clicking the "Computer" entry in the Start Menu and selecting "Manage". Examine the "Roles" that are installed, and make sure that these services are installed under the "Web Server (IIS)" role.
   2. Tomcat must be installed and running properly. You should be able to get to the default Tomcat page by pointing a web browser at http://localhost:8080. 
2. Setup Tomcat
   1. Download the appropriate Tomcat Connector .dll file from http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/. Note that these .dlls are specific to your server's processor architecture. Navigate the folders to choose the most recent version of the appropriate .dll.
   2. Rename the .dll to isapi_redirect.dll and place it in {your Tomcat root directory}/isapi.
   3. Create a file called workers.properties and place it in {your Tomcat root directory}/conf. Paste the following into that file:

      # An entry that lists all the workers defined
      worker.list=worker1
      # Entries that define the host and port associated with these workers
      worker.worker1.host=localhost
      worker.worker1.port=8009
      worker.worker1.type=ajp13

   4. Create a file called uriworkermap.properties and place it in {your Tomcat root directory}/conf. This file determines what traffic should be handled by the ISAPI redirection. What you'll want to do here is make an entry for each webapp that you have running under Tomcat that you want to be exposed through IIS. Basically, you tell it that if the URI requested matches a certain condition, send the traffic to a "worker" defined in the workers.properties file you already created. For example, let's say you have Geoserver running under Tomcat, and it can be accessed via

      http://localhost:8080/geoserver

      You should write a line to uriworkermap.properties that reads

      /geoserver*=worker1

      Similarly, if GeoNetwork is running at

      http://localhost:8080/geonetwork

      then you'll want another line in this file that reads

      /geonetwork*=worker1

      Note that we only defined one "worker" in our workers.properties file, and this worker makes the connection from Tomcat to the ISAPI .dll we downloaded. That worker can be reused for as many webapps as you wish to expose. It's also worth mentioning that changes to uriworkermap.properties are effective immediately once you're finished setting things up, without having to reboot Tomcat.
   5. In that same directory, create a file called isapi_redirect.properties. This file tells the isapi_redirect.dll where to look for its neccessary configuration files that you just created. Adjust the following template file with the appropriate paths for your installation of Tomcat:

      # 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=/tomcat/isapi_redirect.dll
       
      # Full path to the log file for the ISAPI Redirector
      log_file={your Tomcat root directory}\isapi\logs\isapi_redirect.log
       
      # Log level (debug, info, warn, error or trace)
      log_level=info
       
      # Full path to the workers.properties file
      worker_file={your Tomcat root directory}\conf\workers.properties
       
      # Full path to the uriworkermap.properties file
      worker_mount_file={your Tomcat root directory}\conf\uriworkermap.properties

   6. Finally, you'll want to make sure that the AJP connector is enabled in the {your Tomcat root directory}\conf\server.xml  file. Look for a line that looks like this:

      <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

      If this line is commented out, uncomment it. If it does not exist, add it.
3. Setup IIS
   1. In the IIS Manager, select the main server node and find the ISAPI and CGI Restrictions feature. Open it and add a new restriction with the following information:

      ISAPI or CGI path = {your Tomcat root directory}\isapi\isapi_redirect.dll
      Description = Tomcat
      Select "Allow extension path to execute"

   2. Now right-click your website's node and add a new virtual directory with the following properties:

      Alias = tomcat
      Physical path = {your Tomcat root directory}\isapi 

   3. Next, you'll select the ISAPI Filters feature under your web site's node. Create a new filter with this information:

      Filter name = tomcat
      Executable = {your Tomcat root directory}\isapi\isapi_redirect.dll

   4. Last but not least, make sure that the ISAPI handler is enabled. Within your web site, click the Handler Mappings feature. If ISAPI-dll is in the disabled group, right-click it and select Edit Feature Permissions. Make sure that Read, Script and Execute are all selected.