為 Microsoft IIS 設定 ISAPI 重導器

需求

Tomcat 重導器需要三個實體

  • isapi_redirect.dll - IIS ISAPI 重導器外掛程式，取得預先建置的 DLL 或自行建置 (請參閱建置區段)。
  • workers.properties - 描述工作執行緒 (Tomcat 程序) 使用的主機和埠的檔案。可在 conf 目錄下找到範例 workers.properties。
  • uriworkermap.properties - 將 URL 路徑模式對應到工作執行緒的檔案。也可在 conf 目錄下找到範例 uriworkermap.properties。

安裝包含以下部分

  • 使用預設 /examples 內容設定 ISAPI 重導器，並檢查您是否可以使用 IIS 提供 servlet。
  • 將更多內容新增到設定中。

請注意，在 64 位元環境中 - 至少適用於 IIS 7 - 所使用的 IIS 應用程式集區應將「啟用 32 位元應用程式」設定為「否」。否則，重導器不會被呼叫，並會傳回 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

日誌檔的最大大小 (以 MB 為單位)，超過此大小後，日誌檔將會輪替。將其設定為 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 值大小。將此值設定為所有已定義工作者 * 400 的數量。（僅當您有 超過 64 個工作者時，才設定此值）

此指令已新增至 1.2.20 版本

從 1.2.27 版本開始，共用記憶體的大小會自動決定，即使有大量的使用者。不再需要此屬性。

worker_mount_reload

指定 worker_mount_file 將重新載入的時間（以秒為單位）的 DWORD 值。

此指令已新增至 1.2.20 版本

strip_session

表示布林值的字串值。如果設定為 true，如果 URL 是由網路伺服器在本地端提供，則會移除 ";jsessionid=..." 形式的 URL 會話字尾。

預設值為 false。

此指令已新增至 1.2.21 版本

auth_complete

表示「0」或「1」的 DWORD 值。由於與 IIS 5.1 有些微的不相容性，因此需要此值。

預設值為 1，表示我們使用 SF_NOTIFY_AUTH_COMPLETE 事件。如果您將此值設定為 0，則我們使用 SF_NOTIFY_PREPROC_HEADERS。處理使用 PUT HTTP 方法的請求時，IIS 5.1 可能需要此值。

此指令已新增至 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 將會被拒絕。

大多數的網路應用程式都不會使用此類 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 值。工作執行緒會由每隔 watchdog_interval 秒定期執行的背景執行緒定期維護。工作執行緒維護會檢查閒置連線、修正負載狀態，並能夠偵測後端正常狀態。

維護僅在自上次維護以來至少經過 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。可以在 conf 目錄中找到範例 isapi_redirect.properties。

屬性檔中的屬性名稱和值與上述註冊設定相同。例如 

# 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。