Configuring the ISAPI redirector for Microsoft IIS

Requirements

The Tomcat redirector requires three entities:

  • isapi_redirect.dll - The IIS ISAPI redirector plugin, either obtain a pre-built DLL or build it yourself (see the build section).
  • workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers.properties can be found under the conf directory.
  • uriworkermap.properties - A file that maps URL-Path patterns to workers. A sample uriworkermap.properties can be found under the conf directory as well.

The installation includes the following parts:

  • Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS.
  • Adding more contexts to the configuration.

Note that in a 64 Bit environment - at least for IIS 7 - the used IIS Application Pool should have "Enable 32-bit Applications" set to "False". Otherwise the redirector will not be called and returns an http code 404. If you think, the 32bit version of isapi_redirect.dll would do the job instead, you will get an http code 500, because the library is not loadable into a 64 Bit IIS.

Registry settings

ISAPI redirector reads configuration from the registry, create a new registry key named:

"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"

Attributes described below as a "string value representing a boolean" can be set either using the numbers 0 (false) and 1 (true) as values, or off (false) and on (true) or any other string starting with the letters f (false), n (false), t (true) or y (true). The values are taken case insensitive. In this documentation we will stick to false and true.

Attribute Description
extension_uri

A string value pointing to the ISAPI extension /jakarta/isapi_redirect.dll

log_file

A value pointing to location where log file will be created. (for example c:\tomcat\logs\isapi.log)
If one of the log rotation settings (log_rotationtime or log_filesize) are specified then the actual log file name is based on this setting. If the log file name includes any '%' characters, then it is treated as a format string for strftime(3), e.g. c:\tomcat\logs\isapi-%Y-%m-%d-%H_%M_%S.log. Otherwise, the suffix .nnnnnnnnnn is automatically added and is the time in seconds. A full list of format string substitutions can be found in the Apache rotatelogs documentation

log_level

A string value for log level (can be debug, info, warn, error or trace).

This directive was added in version 1.2.31

log_rotationtime

The time between log file rotations in seconds. Setting this to 0 (the default) disables log rotation based on time.

This directive was added in version 1.2.31

log_filesize

The maximum log file size in megabytes, after which the log file will be rotated. Setting this to 0 (the default) disables log rotation based on file size.
The value can have an optional M suffix, i.e. both 5 and 5M will rotate the log file when it grows to 5MB.
If log_rotationtime is specified, then this setting is ignored.

worker_file

A string value which is the full path to workers.properties file (for example c:\tomcat\conf\workers.properties)

worker_mount_file

A string value which is the full path to uriworkermap.properties file (for example c:\tomcat\conf\uriworkermap.properties)

rewrite_rule_file

A string value which is the full path to rewrite.properties file (for example c:\tomcat\conf\rewrite.properties)

shm_size

A DWORD value size of the shared memory. Set this value to be the number of all defined workers * 400. (Set this value only if you have more then 64 workers)

This directive has been added in version 1.2.20

Starting with version 1.2.27 the size of the shared memory is determined automatically, even for large numbers of workers. This attribute is not needed any longer.

worker_mount_reload

A DWORD value specifying the time in seconds upon which the worker_mount_file will be reloaded.

This directive has been added in version 1.2.20

strip_session

A string value representing a boolean. If it is set to true, URL session suffixes of the form ";jsessionid=..." get stripped of URLs, if the are served locally by the web server.

The default value is false.

This directive has been added in version 1.2.21

auth_complete

A DWORD value representing "0" or "1". This is needed because of minor incompatibilities with IIS 5.1.

By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS. This might be needed for IIS 5.1 when handling requests using the PUT HTTP method.

This directive has been added in version 1.2.21

uri_select

A string value which influences, how URIs are decoded and re-encoded between IIS and Tomcat. You should leave this at it's default value, unless you have a very good reason to change it.

If the value is "parsed", the forwarded URI will be decoded and explicit path components like ".." will already be resolved. This is less spec compliant and is not safe if you are using prefix forwarding rules.

If the value is "unparsed", the forwarded URI will be the original request URI. It's spec compliant and also the safest option. Rewriting the URI and then forwarding the rewritten URI will not work.

If the value is "escaped", the forwarded URI will be the re-encoded form of the URI used by "parsed". Explicit path components like ".." will already be resolved. This will not work in combination with URL encoded session IDs.

If the value is "proxy", the forwarded URI will be a partially re-encoded form of the URI used by "parsed". Explicit path components like ".." will already be resolved. and problematic are re-encoded.

The default value since version 1.2.24 is "proxy". Before it was "parsed".

reject_unsafe

A string value representing a boolean. If it is set to true, URLs still containing percent signs '%' or backslashes '\' after decoding will be rejected.

Most web apps do not use such URLs. By enabling reject_unsafe you can block several well known URL encoding attacks.

The default value is false.

This directive has been added in version 1.2.24

collapse_slashes

This options is deprecated as of 1.2.44 and will be ignored if used.

Before version 1.2.41 collapsing was never done. Starting with version 1.2.41 collapsing before looking for unmount matches is the default to prevent easy bypassing of unmount rules. As of 1.2.44, collpasing is always performed before looking for mount or unmount rules.

This directive has been added in version 1.2.41

watchdog_interval

A DWORD value representing the watchdog thread interval in seconds. The workers are maintained periodically by a background thread running periodically every watchdog_interval seconds. Worker maintenance checks for idle connections, corrects load status and is able to detect backend health status.

The maintenance only happens, if since the last maintenance at least worker.maintain seconds have passed. So setting the watchdog_interval much smaller than worker.maintain is not useful.

The default value is 0 seconds, meaning the watchdog thread will not be created, and the maintenance is done in combination with normal requests instead.

This directive has been added in version 1.2.27

error_page

A string value representing the error page url redirection when backend returns non-200 response. This directive can be used to customise the error messages returned from backend server.

The url must point to a valid server url and can contain format string number (%d) that can be used to separate the pages by error number. The redirect url in that case is formatted by replacing %d from error_page to returned error number.

This directive has been added in version 1.2.27

enable_chunked_encoding

A string value representing a boolean. If it is set to true, chunked encoding is supported by the server.

The default value is false.

This directive has been added in version 1.2.27. Until version 1.2.30 it was considered experimental and only available when a special build containing chunking support was used. Starting with 1.2.30 it is no longer considered experimental.

flush_packets

A string value representing a boolean. If it is set to true, data is flushed immediately to the client as each AJP packet is received. Otherwise, IIS buffers the data and only writes to the client when the buffer is full or the response is complete.

The default value is false.

This directive has been added in version 1.2.42

Using a properties file for configuration

The ISAPI redirector can read it's configuration from a properties file instead of the registry. This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server. The redirector will check for the properties file during initialisation, and use it in preference to the registry if present.

Create a properties file in the same directory as the ISAPI redirector called isapi_redirect.properties i.e. with the same name as the ISAPI redirector DLL but with a .properties extension. A sample isapi_redirect.properties can be found under the conf directory.

The property names and values in the properties file are the same as for the registry settings described above. For example: 

# Configuration file for the Tomcat ISAPI Redirector

# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/jakarta/isapi_redirect.dll

# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\logs\isapi_redirect.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Full path to the workers.properties file
worker_file=c:\tomcat\conf\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=c:\tomcat\conf\uriworkermap.properties

Notes:

  • Back-slashes - '\' - are not escape characters.
  • Comment lines begin with '#'.

Starting with version 1.2.27 two environment variables are automatically added to the environment that can be used inside .properties files.

  • JKISAPI_PATH - Full path to the ISAPI Redirector.
  • JKISAPI_NAME - Name of the ISAPI Redirector dll without extension 

# Use the logs in the installation path of ISAPI Redirector
log_file=$(JKISAPI_PATH)\$(JKISAPI_NAME).log

Log file rotation

The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the rotatelogs program provided with Apache HTTP Server.

To configure log rotation, configure a log_file, and one of the log_rotationtime or log_filesize options. If both are specified, the log_rotationtime will take precedence, and log_filesize will be ignored.
For example, to configure daily rotation of the log file: 

# Configuration file for the Tomcat ISAPI Redirector
...

# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Rotate the log file every day
log_rotationtime=86400

...

Or to configure rotation of the log file when it reaches 5MB in size: 

# Configuration file for the Tomcat ISAPI Redirector
...

# Full path to the log file for the ISAPI Redirector
log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Rotate the log file at 5 MB
log_filesize=5M

...

The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure a log file name with strftime(3) format codes in it, then ensure it specifies the same granularity as the rotation time configured, e.g. %Y-%m-%d if rotating daily (log_rotationtime=86400).
See the rotatelogs documentation for more examples.

Using a simple rewrite rules

The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not as powerful as Apache HTTP Server's mod_rewrite, it allows a simple exchange of request URIs

The rule is in the form original-url-prefix=forward-url-prefix. For example: 

# Simple rewrite rules, making examples
# available under shorter URLs
/jsp/=/examples/jsp/
/servlets/=/examples/servlets/

You can also use regular expressions, if you prefix the rule with a tilde ~: 

# Complex rewrite rule, prefixing "/examples/"
# to the first path component of all requests
~/([^/]*)=/examples/$1

Note that uriworkermap.properties must use the URLs before rewriting.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.