ONJava.com    
 Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples


Using Tomcat Configuring Tomcat with IIS Web Server

by James Goodwill
12/18/2002

In this article, we are going to continue our Tomcat Connector discussions with a look at how to configure Tomcat and Microsoft's Internet Information Server (IIS) using the JK v1.2 Connectors.

Note: This article assumes that you have completed the steps from the previous article, "Configuring Tomcat and Apache With JK 1.2." If you have not already completed these steps, please go back to the article and complete steps 3-7.

Preparing Your Environment

To connect IIS to the Tomcat server, we are going to leverage a Microsoft technology called ISAPI. We don't need to know much about this technology; we simply need to make use of an existing Dynamic Link Library (DLL) that has already been built and is available here.

The file you are looking for is isapi_redirector.dll, which exists in the win32/ subdirectory.

Once you have this file, you then need to complete the following steps:

  1. Install IIS as described in its packaged documentation. This article assumes that you will be running IIS 5.x.

  2. Test the IIS installation, by starting IIS and opening your browser to http://localhost.

If everything went according to plan, you should now see images similar to the following.

Configuring Tomcat and IIS with the JK 1.2 Connector

Now that IIS is installed, it is time to begin the actual integration between IIS and Tomcat. This process can be broken down into two sections: configuring Tomcat, and configuring IIS. The result of our integration will make the Tomcat examples Web application available through IIS.

Configuring Tomcat

The complete Tomcat configuration was described a previous article, "Configuring Tomcat and Apache with JK 1.2."

Configuring IIS

Once Tomcat is configured, it is time to configure IIS. We do this by telling IIS that it should pass all requests to the examples context to Tomcat for processing. This is a relatively simple process and is broken down into the following four steps:

1. Creating a Tomcat Worker File

We begin the IIS configuration, just as we did with Apache, by creating a Tomcat worker definition. This worker definition is used to tell IIS how it is to talk to Tomcat. This is done by creating a Tomcat worker file that contains the definition for at least one Tomcat worker.

Note: We discussed the worker.properties file in the previous article, so I will only provide a source listing. If you did not read the previous article, this would be a good time to check it out.

worker.list=testWorker
worker.testWorker.port=8009
worker.testWorker.host=localhost
worker.testWorker.type=ajp13

If this file does not exist, create it, add the previous lines, and copy it to the <CATALINA_HOME>/conf directory of the Tomcat instance that you will be integrating with IIS.

Note: <CATALINA_HOME> represents the base directory of your Tomcat installation.

2. Creating a URI Worker Mapping File

After you have created the worker file, you need to tell IIS which requests will be serviced by the described worker. This is done by creating a file named uriworkermap.properties that contains a list of URI patterns mapped to Tomcat workers. The following listing contains the map for the examples context.

/examples/*=testWorker
/examples/*.jsp=testWorker
/examples/servlet/*=testWorker

Each of the URI mappings begins with the URI pattern of the request and the worker with which this pattern should be associated. Our mappings tell IIS that all static files, JSPs, and servlets in the examples context should be serviced by the testWorker. Once you have this file created, copy it to Tomcat's <CATALINA_HOME>/conf directory.

3. Modifying the Windows Registry

In this step, we are going to create the Windows Registry settings that will be used to point the ISAPI Redirector to our newly-created files.

Note: To add these new registry settings, you will need to use the Windows REGEDT32.EXE application, which is most likely in your C:\WINDOWS\SYSTEM32 directory.

Before you can add any of these settings, you must add the following registry key:

HKEY_LOCAL_MACHINE
   SOFTWARE
     Apache Software Foundation
         Jakarta Isapi Redirector
           1.0

Note: These keys must be entered exactly as they are listed above.

After you have the above keys, select the 1.0 key and add the following name/values pairs -- all of which are string values.

Name Data
extension_uri /tomcat/isapi_redirector.dll
worker_file <CATALINA_HOME>/conf/workers.properties
worker_mount_file <CATALINA_HOME>/conf/uriworkermap.properties
log_file <CATALINA_HOME>/logs/jk_iis.log
log_level debug

These string values are read by the ISAPI Redirector at startup, and are used to initialize IIS. The following table provides a description of each of these variables.

Name Data
extension_uri The extension_uri variable represents the IIS virtual director, which will be created in the next step, plus the name of the ISAPI redirector file.
worker_file The worker_file variable tells the ISAPI Redirector the location of the workers.properties file.
worker_mount_file The worker_mount_file variable tells the ISAPI Redirector the location of the uriworkermap.properties file.
log_file The log_file variable defines the name and location of the ISAPI Redirector's log file.
log_level The log_level variable defines the debug level used when writing to the log file. The possible values are debug, info, error, and emerg.

Once you have added the appropriate keys and variables, your registry should resemble the following figure.

4. Configuring the ISAPI Redirector

We are now at our final step. In this step, we are going to actually tell IIS when to use the ISAPI Redirector. To do this, we need to complete all of the following steps:

  1. Copy the isapi_redirector.dll file to your <CATALINA_HOME>/conf/ directory.

  2. Open up your Windows Control Panel.

  3. Open the Administrative Tools Application.

  4. Open the Internet Information Services Application. You should see an image similar to the following:

  5. Expand your local computer entry, until you see the default Web site

    .
  6. Right-click on the default Web site and select Virtual Directory from the New menu.

  7. Select the Next button and enter the value tomcat in the Alias text box.

  8. Browse to the directory containing your isapi_redirector.dll file, which in our case should be <CATALINA_HOME>/conf/ and select the Next button.

  9. Now make sure that you have the permissions set to read, run, and execute.

  10. Now continue through the Virtual Directory Wizard, until you reach the end and then select the Finish button.

  11. We now need to add the ISAPI Redirector to the default Web site, so right-click on the default Web site and select the menu item Properties.

  12. Select the ISAPI Filters tab and press the Add button.

  13. Enter a filter name and browse to the location of the isapi_redirector.dll file. The following image shows the values that I have used in my instance.

  14. Now press the OK button until you are back at the Internet Information Services dialog.

Testing Your New Configuration

At this point, everything should be properly configured and you can now test your changes. To do this, you must first start Tomcat and then restart the IIS server. When both servers are up and running, open your browser to one of the following two URLs and browse around testing your new integration:

Related Reading

Apache: The Definitive Guide
By Ben Laurie, Peter Laurie

Troubleshooting

If you have trouble, check the following items:

1. Double-check the settings in the registry file; they must be entered exactly as they are listed.

2. Make sure the tomcat virtual directory points to the location of the isapi_redirector.dll and the permissions are set to read, run, and execute.

3. Open the ISAPI filters dialog and make sure that the tomcat filter has a green arrow next to it. If it does not, then check the Executable entry on the Filter Properties dialog.

4. Make sure the values of your workers.properties and uriworkermap.properties files contain the previously listed values.

5. If you still cannot find the problem, then open the log file <CATALINA_HOME>/logs/jk_iis.log and see if you can diagnose the problem from the ISAPI Redirector's output.

Up Next

That about does it for the basic IIS/Tomcat configuration -- in the next Tomcat article, I will take another look at server.xml while we configure Tomcat to receive requests from Apache and the JK2 Connectors.

James Goodwill is the co-Founder of Virtuas Solutions, LLC, a Colorado-based software consultancy.


Read more Using Tomcat columns.

Return to the ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.