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.
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
Once you have this file, you then need to complete the following steps:
Install IIS as described in its packaged documentation. This article assumes that you will be running IIS 5.x.
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.
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.
The complete Tomcat configuration was described a previous article, "Configuring Tomcat and Apache with JK 1.2."
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
REGEDT32.EXE application, which is most likely in your
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.
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.
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:
Copy the isapi_redirector.dll file to your <CATALINA_HOME>/conf/ directory.
Open up your Windows Control Panel.
Open the Administrative Tools Application.
Open the Internet Information Services Application. You should see an image similar to the following:
Expand your local computer entry, until you see the default Web site.
Right-click on the default Web site and select Virtual Directory from the New menu.
Select the Next button and enter the value tomcat in the Alias text box.
Browse to the directory containing your isapi_redirector.dll file, which in our case should be <CATALINA_HOME>/conf/ and select the Next button.
Now make sure that you have the permissions set to read, run, and execute.
Now continue through the Virtual Directory Wizard, until you reach the end and then select the Finish button.
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.
Select the ISAPI Filters tab and press the Add button.
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.
Now press the OK button until you are back at the Internet Information Services dialog.
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:
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.
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.