Tomcat 4.0.3+ on Windows 2000/XP

Table of Contents

1. Prerequisites
2. Automated Installer NEW!
3. Downloading and installing IIS_Config.zip
4. Editing workers.properties for your configuration
5. Editing and Loading the Registry file
6. Configuring IIS
7. Adding your own virtual directories
8. Advanced topics
9. Contact Information
10. Terms used in this document

Prerequisites

1. Windows 2000 or Windows XP. This installation may work on other OS's, but I wouldn't bet on it.
2. IIS 5.x should be installed and running on port 80. Test by going to http://localhost/.
3. J2SE (1.3x or greater) should be installed and the environmental variable JAVA_HOME should already be set to the J2SE base directory
4. J2EE (1.3x or greater) should be installed and the environmental variable J2EE_HOME should already be set to the J2EE base directory
5. Tomcat 4.0.3 should be installed and running on the default port 8080. Test by going to http://localhost:8080/. CATALINA_HOME environmental variable CATALINA_HOME should already be set to the Tomcat base directory
6. Tomcat 4.0.3 should be able to serve the example jsp files. All the test links use the examples files to test your connectivity. Test by going to http://localhost:8080/examples/jsp/dates/date.jsp.

Automated Installer

I've been working on a Automated Installer for setting up the IIS redirector, and I have a working BETA. To use the install app, you must already have all the prerequisites and Windows Installer 2.0 ( Windoes XP comes with it, but for Windows 2000 you must download the update ), and be willing to use a BETA product. There are no guarantees with this product, but for people with a basic configuration trying to set up Tomcat On IIS, this may be a quick solution.

If you understand that this product is not finished, but are willing to take the plunge, you may download it here. Otherwise, skip this section and continue below to get the manual installation procedure.

If you run into any bugs during installation, please send us an email. We will try and fix the bug and help you resolve any issues you may have.

Downloading and installing IIS_Config.zip

Download IIS_Config.zip . This file *should* contain the latest isapi_redirector.dll file for 4.0.3.

After downloading, extract IIS_Config.zip into your CATALINA directory. It's important that you extract the file into this directory, because it creates the necessary subdirectories and places the files in the corresponding locations.

Editing workers.properties for your configuration

1. In your CATALINA\conf\ntiis directory, open the workers.properties file.
2. Edit the value workers.tomcat_home and point it to your CATALINA directory (line 41)
3. Edit the value workers.java_home and point it to your J2SE directory (line 47)

Editing and Loading the Registry file

1. In your CATALINA\conf\ntiis directory, open the isapi.redirector.reg registry file in notepad.
2. Log_file should point to the CATALINA\\logs\\ iis_redirector.log (ie "C:\\Program Files\\Apache Tomcat 4.0\\logs\\iis_redirector.log" )
3. worker_file should point to CATALINA\\conf\\ntiis\\workers.properties (ie "C:\\Program Files\\Apache Tomcat 4.0\\conf\\ntiis\\workers.properties" )
4. worker_mount_file should point to the CATALINA\\conf\\ntiis\\uriworkermap.properties (ie "C:\\Program Files\\Apache Tomcat 4.0\\conf\\ntiis\\uriworkermap.properties" )
5. Save the file and load it. (by default, double-clicking loads the registry file). To view the values, go to HKLM->Software->Apache Software Foundation->Jakarta ISAPI Redirector->1.0

Configuring IIS

1. Open IIS Admin and your default web site.
2. Add a Virtual Directory called jakarta and point it to your CATALINA/bin directory and make it EXECUTABLE. TO add a Virtual Directory, Right-Click your web site, select New, select Virtual Directory. For the alias textbox, type "jakarta". For the directory textbox, put in your CATALINA_HOME directory (ie C:\Program Files\Apache Tomcat 4.0\bin ). For Access Permissions, check Read, Run Scripts and Execute. (write and browse are optional).
3. Add CATALINA\bin\isapi_redirector.dll as an ISAPI Filter. To do add an ISAPI Filter, right-click your web site, select properties. Select the ISAPI Filters Tab. Click Add. Give the Filter a Name, such as "Jakarta ISAPI Redirector". Browse to your CATALINA\bin directory and select isapi_redirector.dll. Save it. Close your properties window, and re-open it to the ISAPI Filters Tab. The Filter should have a green arrow. if not, restart your web services ( or reboot ) and check again. If it is still not green, then there is a configuration mistake. If it is green, then it should be running. to Test, go to http://localhost/examples/jsp/dates/date.jsp.

Adding your own virtual directories

A major misconception is that with Tomcat and the ISAPI filter you can now process JSP files through IIS. This is incorrect. All the filter does is redirect requests to Tomcat, meaning Tomcat still processes the JSP files. The reason I point this out is that you cannot add a directory to IIS and add JSP files to it, expecting the files to work. You have to add all your JSP files to virtual directories defined in Tomcat. To do this, you have to complete these 2 steps

1. Define your directory for Tomcat, so as you can access it via http://localhost:8080/my-directory
2. Define the directory to your ISAPI Redirector filter so you can access it http://localhost/my-directory

for example, if you want a folder called my-jsp to store, process and deliver JSP files, then you first have to define it in your Tomcat Server. To do so, you will need to become familiar with the server.xml file located at CATALINA\conf. ( for a complete discussion on manipulating your server configuration including adding virtual directories, go to /http://jakarta.apache.org/tomcat/tomcat-4.0-doc/config/index.html .Please be aware, this document is case sensitive and it must conform to XML document standards, most notably it must be well formed. An easy way to check for a well-formed document is to try and open it with Internet Explorer (5+). If the document loads, it is well-formed, otherwise the error message will try and tell you where your mistake is located.

To add a virtual directory to Tomcat, you need to modify your server.xml file located in CATALINA/conf. find the Server element. nested inside, look for a Service element. Nested inside the Service Element, look for an Engine element. Nested inside the Engine Element, look for a Host element. This is where we will add a Context element, which will define your virtual directory. A simple context element should look like this:

<Context path="/my-jsp" docBase="c:\JSP-Files" debug="0" privileged="true" />

where path is the name of the virtual directory and docBase points to the physical folder. After modifying server.xml, you will need to restart your Tomcat When this is working correctly you should be able to access the folder via Tomcat at http://localhost:8080/my-jsp.

To define the directory to your ISAPI redirector, you need to open the file uriworkermap.properties. You then need to add two lines.

/my-jsp=$(default.worker)
/my-jsp/*=$(default.worker)

After saving this file, you need to restart you IIS Service, to get the ISAPI redirector to reload. When this is working properly you should be able to access the folder via IIS at http://localhost/my-jsp

Advanced topics

Now that you can add your own virtual directories, here are some other things you can do.

If you wanted to you could add the virtual directories in Tomcat as Virtual Directories in IIS. The only reason you might want to do this is to allow WebDAV access to those directories from IIS. After you configure your Tomcat virtual directory, and after you have it working with the IIS redirector, just add a virtual directory in IIS that points to the directory you defined in Tomcat.

Another item that you may want to do is process all *.jsp's in your IIS folders by Tomcat. This requires a few steps.

• You must add a Context to your Tomcat. The path should be "" to be the default Context for for all apps without specified Contexts and the docBase should point to the web site files.
  
  <Context path="" docBase="c:\Inetpub\wwwroot" debug="0" privileged="true" /> )
  
• You must add a line to your uirworkermap.properties.
  
  /*.jsp=$(default.worker)
  

Contact Information and closing

We are always looking to improve this document, so feel free to drop us a line.

Terms used in this document

1. CATALINA or CATALINA_HOME - refers to an Environmental Variable that you should have already configured during the installation of Tomcat. IF you installed Tomcat into the default location, this should be "C:\Program Files\Apache Tomcat 4.0").
2. J2SE or JAVA_HOME - refers to an Environmental Variable that you should have already configured during the installation of Tomcat. IF you installed J2SE into the directory C:\jdk1.3.1, then this is where the environmental variable should point.
3. J2EE or J2EE_HOME - refers to an Environmental Variable that you should have already configured during the installation of Tomcat. IF you installed J2EE into the directory C:\j2sdkee1.3.1, then this is where the environmental variable should point.