By Gal Shachor <firstname.lastname@example.org>
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 plugin will let IIS send servlet and JSP requests to Tomcat (and this way, serve them to clients).
<tomcat_home> is the root directory of tomcat. Your Tomcat installation should have the following subdirectories:
In all the examples in this document <tomcat_home> will be c:\jakarta-tomcat.
A worker is defined to be a tomcat process that accepts work from the IIS server.
The IIS-Tomcat redirector was developed and tested on:
Note: Due to some feature additions, the IIS-Tomcat redirector from earlier Tomcat's can't be used with Tomcat 3.3. Only use the IIS-Tomcat redirector from Tomcat 3.3, or newer versions from the jakarta-tomcat-connectors Jakarta project.
The redirector uses ajp13 or ajp12 to send requests to the Tomcat containers. There is also an option to use Tomcat in process, more about the in-process mode can be found in the in process howto.
As of Tomcat 3.2, a pre-built version of the Tomcat redirector plugin, isapi_redirect.dll, is available under the win32/i386 directory where you downloaded the Tomcat binary distribution. For those using Netscape as your browser, try downloading a zip version of the file, if available. There can be problems using Netscape to download DLL files.
You can also build a copy locally from the source in Tomcat's source distribution.
The Tomcat redirector requires three entities:
uriworkermap.propertiesfile it generates is written to the
The installation includes the following parts:
The default installation of Tomcat 3.3 includes the
IISConfig module in the
server.xml file. This module is responsible for writting the
configuration files used for Tomcat redirector plugin installation and operation.
In Tomcat 3.3, configuration files are written on demand. You must start Tomcat 3.3 with the "jkconf" option specified. Tomcat 3.3 will initialize, write the configuration files, and then exit. This may be done, while an instance of Tomcat 3.3 is running. This differs from prior versions of Tomcat where the configuration files are written each time Tomcat is started.
The IISConfig module in Tomcat 3.3 writes two configuration files. The first
is the registry configuration file, which by default will be
conf/auto/iis_redirect.reg. The second is the worker map
configuration file, which by default will be
The IISConfig module in Tomcat 3.3.1 writes a third configuration file. This
file contains the same settings as the registry configuration file and
provides an alternate means of configuring the Tomcat redirector plugin
without relying on the registry. It defaults to writing
To use the "properties" file instead of registry settings, the "properties" file must have the same name as the redirector plugin DLL, except with a ".properties" extension. It must also be located in the same directory as the DLL. If both the "properties" file and registry settings exist, the "properties" file will be used.
The following steps show how to configure the Tomcat redirector plugin.
isapi_redirect.dll, and place it in a suitable location. A typical location is
TOMCAT_HOME\bin\native. If you are installing on WinNT or Win2k, make sure IIS runs with a user that can access this directory.
IISConfiggenerated "proprties" file,
isapi_redirect.properties, or a manually created one, to the directory where the redirector plugin DLL is found. Rename this file to have the same base name as the redirector plugin DLL should they happen to be different.
isapi_redirect.dll(for example c:\jakarta-tomcat\bin\native). While creating this new virtual directory, assign it with execute access.
isapi_redirect.dll, as a filter to your IIS/PWS web site. The name of the filter should reflect its task (for example, "Jakarta Redirector"). Its executable must be the redirector plugin DLL,
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters.This key contains a comma separated list of dlls ( full paths ). You need to add the full path to redirector plugin DLL, isapi_redirect.dll, to this key.
WINDOWS\SYSTEM\inetsrvdirectory and execute
PWS /stop. Then execute
PWSto start it again.
That's all, you should now start Tomcat and ask IIS to serve you the /examples context. Try http://localhost/examples/jsp/index.html for example and execute some of the JSP examples. If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem.
The examples context is useful for verifying your installation, but you will also need to add your own contexts. Adding a new context requires two operations:
Adding a context to the Tomcat redirector plugin is simple, all you need to do is to start Tomcat 3.3 with "jkconf" option specified again. After the worker map file is rewritten, restart IIS/PWS.
If you are using a manually modified URI to worker map file, edit the file to add a line that looks like:
Workers and their name are defined in workers.properties, by default workers.properties comes with 2 pre-configured workers named "ajp13" and "ajp12" so you can use it. As an example, if you want to add a context named "shop", the line that you should add to uriworkermap.properties will be:
After saving uriworkermap.properties restart IIS/PWS and it will serve the new context.
The following is an example isapi_redirect.properties file which contains the default settings for Tomcat 3.3.
extension_uri=/jakarta/isapi_redirect.dll log_file=E:\Jakarta\Tc33x\jakarta-tomcat\dist\tomcat\logs\iis_redirect.log log_level=emerg worker_file=E:\Jakarta\Tc33x\jakarta-tomcat\dist\tomcat\conf\jk\workers.properties worker_mount_file=E:\Jakarta\Tc33x\jakarta-tomcat\dist\tomcat\conf\auto\uriworkermap.properties
The Tomcat redirector plugin for Tomcat 3.3.1 supporta an additional setting with the following default.
The following table describes the use of each of these settings:
|extension_uri||The URI used by the redirector plugin's filter to redirect the request to the extension. This setting consists of the name of the virtual directory followed by the name of the DLL.||/jakarta/isapi_redirect.dll|
|log_file||The path of the log file for the redirector plugin DLL||must be specified|
|log_level||The quantity of log output desired. Valid values are debug, info, error, and emerg.||emerg|
|worker_file||The path to the workers definition file, typically named
||must be specified|
|worker_mount_file||The path to the URI to worker map file, typically named
||must be specified|
|This settings controls which of several forms of
the URI is passed to Tomcat. The following are the valid values:|
Setting this value properly is important so that request data, such as HttpServletRequest.getRequestURI(), are returned with the proper encoding. Tomcat 3.3 and later requires the
The Tomcat redirector was developed using Visual C++ Ver.6.0, so having this environment is a prerequisite if you want to perform a custom build.
The steps that you need to take are:
This will build both release and debug versions of the redirector plugin.
An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and build it using the build menu.
Unlike prior versions, Tomcat 3.3 writes config files which default to
sending all requests, including those for static pages, to Tomcat for processing.
This gives the best chance for the web application configuration specified in the
web.xml file to work successfully.
Also, unlike prior versions, the default worker map file does not try to add servlet or JSP operation to the IIS/PWS main virtual directory. To see how to control the manner in which Tomcat writes the worker map file see the reference information on the IISConfig module.
Sometimes it is better to have IIS serve the static pages (html, gif, jpeg etc.) even if these files are part of a context served by Tomcat. For example, consider the html and gif files in the examples context, there is no need to serve them from the Tomcat process, IIS will suffice.
Making IIS serve static files that are part of the Tomcat contexts requires the following:
Adding a Tomcat context to IIS requires the addition of a new IIS virtual directory that covers the Tomcat context. For example adding a /example IIS virtual directory that covers the c:\jakarta-tomcat\webapps\examples directory.
Configuring the redirector is somewhat harder, you will need to specify the exact URL-Path pattern(s) that you want Tomcat to handle (usually only JSP files and servlets). This requires a change to the uriworkermap.properties. For the examples context it requires to replace the following line:
with the following two lines:
As you can see the second configuration is more explicit, it actually instruct the redirector to redirect only requests to resources under /examples/servlet/ and resources under /examples/ whose name ends with .jsp. This is similar to what is automatically written to the uriworkermap.properties-auto file for each context.
You can even be more explicit and provide lines such as:
that instructs the redirector to redirect request whose URL-Path equals /example/servletname to the worker named ajp13.
Each servlet application (context) has a special directory named WEB-INF, this directory contains sensitive configurations data and Java classes and must be kept hidden from web users. Using the IIS management console it is possible to protect the WEB-INF directory from user access, this however requires the administrator to remember that. To avoid this need the redirector plugin automatically protects your WEB-INF directories by rejecting any request that contains WEB-INF in its URL-Path.
Sometimes you want to serve different contexts with different Tomcat processes (for example to spread the load among different machines). To achieve such goal you will need to define several workers and assign each context with its own worker.
Defining workers is done in workers.properties, this file includes two types of entries:
The above examples defined three workers, now we can use these workers to serve two different contexts each with its own worker. For example look at the following uriworkermap.properties fragment:
As you can see the examples context is served by ajp12 while the webapp1 context is served by ajp13, and the webapp2 context is served by the ajp13second worker.
It is easy to have the Tomcat redirector not work the first time you try to install it. If this happens to you, here are some steps to follow to try to correct the problem. These steps aren't guaranteed to cover all possible problems, but they should help find the typical mistakes. If you make any corrections during these steps, restart the IIS service as described above in the last step of the installation, then retry the step.
Note: These steps assume your worker_mount_file setting points
to an unmodified copy of the
Results may be misleading if worker_mount_file points to a modified
version of the file. It is also assumed that the "/examples"
context works correctly if you access Tomcat directly.
Please send feedback, bug report or any additional information to email@example.com