Configuring IIS

+ + &project; + + + Mladen Turk + Configuring IIS + + + + +

+The Tomcat redirector requires three entities: + +

+isapi_redirect.dll - The IIS server 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. +

+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" +

+ +

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

+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 +

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

This directive was added in version 1.2.31

+ +

+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

+ +

+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. +

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

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

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

+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.

+ +

+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

+ +

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

+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +

This directive has been added in version 1.2.21

+ +

+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

+ +

+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".

+ +

+A string value representing a boolean. If it is set to true, +URLs 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. +

This directive has been added in version 1.2.24

+ +

+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

+ +

+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

+ +

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

+This option is considered experimental and its support +must be compile time enabled. Use isapi_redirect.dll +with chunked support enabled. + +

This directive has been added in version 1.2.27

+ + +

+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 Jakarta 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 +dynamically 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=$(ISAPI_PATH)\$(ISAPI_NAME).log +

+ +

+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 Jakarta 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 Jakarta 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. +

+ +

+The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not +as powerful as Apache Httpd'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 /jsp-examples +# and /servlets-examples available under shorter URLs +/jsp/=/jsp-examples/ +/servlets/=/servlets-examples/ + +

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

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

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

+ + +