Make your own free website on Tripod.com

 

 

 

Configuring Apache Tomcat 4.1 with Internet Information Server 5

 

 

 

 

Muhammad Murad Iqbal


 December 10, 2003


Draft Version

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1.         INTRODUCTION

This document explains how to set up IIS to cooperate with Tomcat. Normally IIS can not execute Servlets and Java Server Pages (JSPs), configuring IIS to use the Tomcat redirector plug-in will let IIS send servlet and JSP requests to Tomcat (and this way, serves them to clients).

2.         SOFTWARE REQUIRED

Following software is required to be installed on the target machine:

·        Tomcat 4.1.x web server should be installed and CATALINA_HOME system variable should be pointing to the directory of Tomcat’s installation. For example:

Variable name = CATALINA_HOME

Variable value = D:\java\Tomcat4.1

                        Visit the following URL to download Tomcat 4.1.29 in zip format

http://mirror.candidhosting.com/apache/jakarta/tomcat-4/v4.1.29/bin/jakarta-tomcat-4.1.29.zip

OR visit any of the following URLs for more information on Tomcat

http://jakarta.apache.org/site/binindex.cgi

http://jakarta.apache.org/tomcat/index.html

 

·        Java 2 SDK should be installed and JAVA_HOME system variable should be pointing to the directory of the SDK installation. For example:

Variable name = JAVA_HOME

Variable value = D:\java\j2sdk1.4.2

                        Visit the following URL to download J2 SDK version 1.4.2

 http://java.sun.com/j2se/1.4.2/download.html

 

·        Two files named ‘worker.properties’ and ‘uriworkermap.properties’ accompanied with this document are required to be placed under ‘conf’ directory located under Tomcat root i.e. CATALINA_HOME.

All configuration files can be found at the following URL:

http://tomcat-iis.tripod.com/configurationFiles

·        Another file named ‘isapi_redirect.dll’ accompanied with this document is required to be placed under CATALINA_HOME\bin\win32\i386. Note that the win32 and i386 folders may not be already there under CATALINA_HOME\bin directory. If this is the case, you will be required to take the effort of creating them. Therefore, the exact path of the .dll file on your machine may be something like:

D:\java\Tomcat4.1\bin\win32\i386\isapi_redirect.dll

·        An optional file named ‘tomcat_iis_connector.reg’ is accompanied with this document. You will have to use this file if in case you do not want to do the entries in the registry manually. However, it is recommended that you use this file as it will save time. You will have to open this file in an editor and do some parameter changes later on in the coming section.

It is assumed that Windows 2000 Server is installed on your machine. Normally IIS is installed with Windows 2000 Server, so you don’t have to worry about its installation. If you are using Windows 2000 Professional or an earlier version of Windows like 98/XP, insert your Windows CD in the CD-Drive, click on ‘Add/Remove Windows Components’ option under ‘Add/Remove Programs’ in the Windows Control Panel and check for ‘Internet Information Services’ or ‘IIS’ to install on your machine.

That’s all you need. You may now proceed to the next section.

 

3.         REGISTRY CONFIGURATION

There are some keys that are required to be added in the registry. It is recommended that you use the ‘tomcat_iis_connector.reg’ file to automate the process. You may alternatively enter the Keys, String and data manually in the registry by using the ‘Registry Editor’ tool.

If you are using the file to automate the insertion of registry entries, open the ‘tomcat_iis_connector.reg’ file an a text editor e.g. Notepad and change the data for ‘log_file’, ‘worker_file’ and ‘worker_mount_file’ by typing in appropriate path till your Tomcat web server installation directory.

For example, you may want to change

"worker_file"="D:\\java\Tomcat4.1\\conf\\worker.properties"

to

"worker_file"="D:\\JavaPkgs\\Tomcat4.1.2\\conf\\worker.properties"

If your Tomcat is installed under D:\JavaPkgs\Tomcat4.1.2

If you are doing it manually, click on Start and then Run. Type ‘regedit’ and then click OK to open the Registry Editor. You may now provide the entries in the ‘tomcat_iis_connector.reg’ to the Registry Editor by creating appropriate Keys, Strings and providing Data to those Strings accordingly.

 

4.         IIS CONFIGURATION

You are now required to configure IIS so that it can use the Jakarta ISAPI Redirector i.e. the ‘isapi_redirect.dll’ file. This is a two step process

i. Add a virtual directory named ‘jakarta’: Open the ‘Internet Information Services’ window by following this sequence - Start à Programs à Administrator Tools à Internet Services Manager. Right click on the website that you want to serve JSP, Servlets etc. and click on ‘New’ and then ‘Virtual Directory’. Click Next in the ‘Virtual Directory Creation Wizard’ and type ‘jakarta’ without quotes in the Alias section and click Next. Now click Browse or enter the full path to the directory where you placed the ‘isapi_redirect.dll’ file and click Next. Click on ‘execute’ to allow execute access. You may leave the other check boxes as it is and click Next and then Finish to complete the procedure.

You added a virtual directory named ‘jakarta’ that points to the directory where you have placed the ‘isapi_redirect.dll’ i.e. TOMCAT_HOME\bin\win32\i386.

ii. Add an ISAPI Filter: Right click on the website where you have just added the virtual directory and click on Properties, ISAPI Filters and then Add. You can give an appropriate name in the Filter Name column, I have given ‘jakarta’ without quotes. For the Executable column, Browse or enter the full path to the ‘isapi_redirect.dll’ file and click OK. Initially, the status may appear with a red arrow pointing down signifying that the filter was not loaded. You are therefore required to close the ‘Internet Information Services’ window and restart the IIS Admin Service and the World Wide Web Publishing Service. Alternatively, you may want to restart the PC if you don’t know how to restart the services.


That’s it. The status of the ISAPI Filter should be appearing in green color with the arrow pointing up. Your configuration is all set to be used for IIS to Tomcat redirection. You can now check the redirection is working by accessing the following URL:

http://localhost/examples/jsp/index.html

If this is not the case, refer to the Troubleshooting section to resolve the problem.

 

5.         TROUBLESHOOTING

WinNT/Win2K

  1. Make sure web site activity is being logged. For PWS 4.0 make sure "Save Web Site Activity Log" is checked in the Advanced Options of the Personal Web Manager.
  2. Start the World Wide Web Publishing Service and Tomcat.
  3. Check for the presence of the ISAPI redirector log file you specified in the log_file setting. If not found, check the following:
    1. Check the "executable" you set for the filter in the IIS Management Console and make sure the path is correct.
    2. Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" key. Case isn't important, but an incorrect letter will prevent the isapi_redirect.dll from finding its registry settings.
    3. Check the log_file setting for String name and data. Also insure the directory in which the log file will appear already exists.

If the above are set correctly, the ISAPI redirector should be able to create the log file.

  1. Check the jakarta filter you added and make sure its status shows a green upward-pointing arrow. If not, check the following:
    1. Check the worker_file setting for typos, name and data.
    2. Check the worker_mount_file setting typos, name and data.

If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong.

  1. Invoke the URL "http://localhost/examples/jsp/index.html" in your browser. Case is important in Tomcat 3.2. The characters following "localhost" in the URL must be lower case. If the page fails to appear, examine the last line in the IIS server log file in found in SYSTEM32/LogFiles/W3SVC1.
    1. The last line should contain something like: GET "/jakarta/isapi_redirect.dll HTTP1.1", which indicates the ISAPI redirector is recognizing that it should handle the request.
      1. If the number following GET "/..." is 404, check the following:
        1. Make sure you entered the URL correctly.
      2. If the number following GET "/..." is 500, check the following:
        1. Make sure the virtual directory created was called "jakarta".
        2. Make sure that the extension_uri setting is correct.
        3. Check the worker.properties file and make sure the port setting for worker.ajp13.port is the same as the port specified in the server.xml for the "Apache AJP13 support".
      3. If the number following GET "/..." is 200 or 403, make sure you have checked Execute Access for the jakarta virtual directory in the Advanced Options of the Personal Web Manager. If you created the "Filter DLLs" key in the registry, delete it. That registry key is only used on Win9x.

If the above settings are correct, the index.html page should appear in your browser. You should also be able to click the Execute links to execute the JSP examples.