为 Microsoft IIS 配置 ISAPI 重定向器

要求

Tomcat 重定向器需要三个实体

  • isapi_redirect.dll - IIS ISAPI 重定向器插件，可获取预构建的 DLL 或自行构建（参见构建部分）。
  • workers.properties - 描述 worker（Tomcat 进程）使用的主机和端口的文件。示例 workers.properties 可以在 conf 目录下找到。
  • uriworkermap.properties - 将 URL 路径模式映射到 worker 的文件。示例 uriworkermap.properties 也可以在 conf 目录下找到。

安装包括以下部分

  • 配置带有默认 /examples 上下文的 ISAPI 重定向器，并检查您是否可以使用 IIS 提供 Servlet 服务。
  • 向配置中添加更多上下文。

请注意，在 64 位环境下，至少对于 IIS 7，所使用的 IIS 应用程序池应将“启用 32 位应用程序”设置为“False”。否则重定向器将不会被调用并返回 HTTP 404 错误。如果您认为 32 位版本的 isapi_redirect.dll 可以替代完成工作，您将得到 HTTP 500 错误，因为该库无法加载到 64 位 IIS 中。

注册表设置

ISAPI 重定向器从注册表读取配置，创建一个名为

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

下面描述为“表示布尔值的字符串值”的属性可以使用数字 0 (false) 和 1 (true) 作为值，或者 off (false) 和 on (true)，或者任何以字母 f (false)、n (false)、t (true) 或 y (true) 开头的其他字符串进行设置。这些值不区分大小写。在此文档中，我们将坚持使用 false 和 true。

属性描述
extension_uri

指向 ISAPI 扩展 /jakarta/isapi_redirect.dll 的字符串值

log_file

指向将创建日志文件的位置的值。（例如 c:\tomcat\logs\isapi.log）
如果指定了任一日志轮换设置（log_rotationtime 或 log_filesize），则实际的日志文件名将基于此设置。如果日志文件名包含任何 '%' 字符，则将其视为 strftime(3) 的格式字符串，例如 c:\tomcat\logs\isapi-%Y-%m-%d-%H_%M_%S.log。否则，会自动添加后缀 .nnnnnnnnnn，表示时间（秒）。完整的格式字符串替换列表可在 Apache rotatelogs 文档中找到。

log_level

日志级别的字符串值（可以是 debug、info、warn、error 或 trace）。

此指令在版本 1.2.31 中添加

log_rotationtime

日志文件轮换之间的时间间隔（秒）。设置为 0（默认值）会禁用基于时间的日志轮换。

此指令在版本 1.2.31 中添加

log_filesize

日志文件的最大大小（兆字节），达到该大小后日志文件将进行轮换。设置为 0（默认值）会禁用基于文件大小的日志轮换。
该值可以带可选的 M 后缀，即 5 和 5M 都将在日志文件增长到 5MB 时进行轮换。
如果指定了 log_rotationtime，则此设置将被忽略。

worker_file

workers.properties 文件的完整路径的字符串值（例如 c:\tomcat\conf\workers.properties）

worker_mount_file

uriworkermap.properties 文件的完整路径的字符串值（例如 c:\tomcat\conf\uriworkermap.properties）

rewrite_rule_file

rewrite.properties 文件的完整路径的字符串值（例如 c:\tomcat\conf\rewrite.properties）

request_id_header

一个字符串值，表示从中提取请求 ID 的请求头名称，该请求 ID 是每行日志的一部分。

此指令已在版本 1.2.49 中添加

shm_size

共享内存的 DWORD 值大小。将此值设置为所有已定义 worker 数量 * 400。（仅当您有超过 64 个 worker 时才设置此值）

此指令已在版本 1.2.20 中添加

从版本 1.2.27 开始，即使 worker 数量很大，共享内存的大小也会自动确定。此属性不再需要。

worker_mount_reload

一个 DWORD 值，指定重新加载 worker_mount_file 的时间（秒）。

此指令已在版本 1.2.20 中添加

strip_session

表示布尔值的字符串值。如果设置为 true，则如果 URL 的会话后缀形式为 ";jsessionid=..." 且由 Web 服务器本地提供服务，则该后缀会被从 URL 中移除。

默认值为 false。

此指令已在版本 1.2.21 中添加

auth_complete

表示“0”或“1”的 DWORD 值。这对于解决与 IIS 5.1 的轻微不兼容性是必需的。

默认值为 1，表示我们使用 SF_NOTIFY_AUTH_COMPLETE 事件。如果将其设置为 0，则我们使用 SF_NOTIFY_PREPROC_HEADERS。IIS 5.1 在处理使用 PUT HTTP 方法的请求时可能需要此设置。

此指令已在版本 1.2.21 中添加

uri_select

一个字符串值，它影响 IIS 和 Tomcat 之间 URI 的解码和重新编码方式。除非有充分理由，否则您应保留其默认值。

如果值为“parsed”，则转发的 URI 将被解码，并且显式路径组件（如“..”）将已解析。这不符合规范，并且如果您使用前缀转发规则，则不安全。

如果值为“unparsed”，则转发的 URI 将是原始请求 URI。它符合规范，也是最安全的选择。重写 URI 然后转发重写后的 URI 将不起作用。

如果值为“escaped”，则转发的 URI 将是“parsed”使用的 URI 的重新编码形式。显式路径组件（如“..”）将已解析。这与 URL 编码的会话 ID 结合使用将不起作用。

如果值为“proxy”，则转发的 URI 将是“parsed”使用的 URI 的部分重新编码形式。显式路径组件（如“..”）将已解析，并且有问题的内容会被重新编码。

自版本 1.2.24 起的默认值为“proxy”。之前是“parsed”。

reject_unsafe

表示布尔值的字符串值。如果设置为 true，则在解码后仍包含百分号 '%' 或反斜杠 '\' 的 URL 将被拒绝。

大多数 Web 应用程序不使用此类 URL。通过启用 reject_unsafe，您可以阻止几种众所周知的 URL 编码攻击。

默认值为 false。

此指令已在版本 1.2.24 中添加

collapse_slashes

此选项自 1.2.44 版本起已弃用，如果使用将忽略。

在 1.2.41 版本之前从未进行折叠。从 1.2.41 版本开始，在查找卸载匹配之前进行折叠是默认设置，以防止轻松绕过卸载规则。从 1.2.44 版本开始，在查找安装或卸载规则之前始终执行折叠。

此指令已在版本 1.2.41 中添加

watchdog_interval

一个 DWORD 值，表示看门狗线程间隔（秒）。Worker 由一个每 watchdog_interval 秒定期运行的后台线程进行维护。Worker 维护会检查空闲连接，纠正负载状态，并能够检测后端健康状态。

只有自上次维护以来至少过去了 worker.maintain 秒，才会进行维护。因此，将 watchdog_interval 设置得远小于 worker.maintain 是没有用的。

默认值为 0 秒，这意味着不会创建看门狗线程，维护将与正常请求结合进行。

此指令已在版本 1.2.27 中添加

error_page

当后端返回非 200 响应时，表示错误页面 URL 重定向的字符串值。此指令可用于自定义从后端服务器返回的错误消息。

URL 必须指向一个有效的服务器 URL，并且可以包含格式字符串数字 (%d)，用于按错误编号分离页面。在这种情况下，重定向 URL 的格式是通过将 error_page 中的 %d 替换为返回的错误编号来完成的。

此指令已在版本 1.2.27 中添加

enable_chunked_encoding

一个表示布尔值的字符串值。如果设置为 true，则服务器支持分块编码。

默认值为 false。

此指令已在版本 1.2.27 中添加。直到版本 1.2.30，它都被认为是实验性的，并且仅在使用了包含分块支持的特殊构建时才可用。从 1.2.30 开始，它不再被认为是实验性的。

flush_packets

一个表示布尔值的字符串值。如果设置为 true，则每当接收到 AJP 数据包时，数据都会立即刷新到客户端。否则，IIS 会缓冲数据，并且只有当缓冲区已满或响应完成时才写入客户端。

默认值为 false。

此指令已在版本 1.2.42 中添加

使用属性文件进行配置

ISAPI 重定向器可以从属性文件而非注册表读取其配置。这使得您可以在同一台服务器上使用多个具有独立配置的 ISAPI 重定向器。重定向器将在初始化期间检查属性文件，如果存在，则优先使用它而不是注册表。

在 ISAPI 重定向器所在的同一目录下创建一个名为 isapi_redirect.properties 的属性文件，即与 ISAPI 重定向器 DLL 同名但扩展名为 .properties。示例 isapi_redirect.properties 可以在 conf 目录下找到。

属性文件中的属性名称和值与上述注册表设置相同。例如

# 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

注释

  • 反斜杠 - '\' - 不是转义字符。
  • 注释行以 '#' 开头。

从 1.2.27 版本开始，会自动将两个环境变量添加到环境中，这些变量可以在 .properties 文件中使用。

  • JKISAPI_PATH - ISAPI 重定向器的完整路径。
  • JKISAPI_NAME - 不带扩展名的 ISAPI 重定向器 DLL 名称

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

日志文件轮换

版本 1.2.31 的 ISAPI 重定向器可以执行日志轮换，其配置和行为类似于 Apache HTTP Server 提供的 rotatelogs 程序。

要配置日志轮换，请配置 log_file 和 log_rotationtime 或 log_filesize 选项之一。如果两者都指定，则 log_rotationtime 将优先，log_filesize 将被忽略。
例如，要配置日志文件每日轮换

# 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

...

或者配置日志文件达到 5MB 时进行轮换

# 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

...

只要达到配置的限制，日志就会轮换，但前提是日志文件名会改变。如果您配置的日志文件名中包含 strftime(3) 格式代码，请确保它指定的粒度与配置的轮换时间相同，例如，如果每日轮换 (log_rotationtime=86400)，则使用 %Y-%m-%d。
更多示例请参阅 rotatelogs 文档。

使用简单的重写规则

版本 1.2.16 的 ISAPI 重定向器可以执行简单的 URL 重写。尽管不如 Apache HTTP Server 的 mod_rewrite 强大，但它允许请求 URI 的简单交换。

规则的形式是 original-url-prefix=forward-url-prefix。例如

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

您也可以使用正则表达式，如果规则以波浪号 ~ 为前缀。

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

请注意，uriworkermap.properties 必须使用重写前的 URL。