Microsoft IIS 用 ISAPI リダイレクターの構成

要件

Tomcat リダイレクターには 3 つのエンティティが必要です

  • isapi_redirect.dll - IIS ISAPI リダイレクタープラグイン。ビルド済みの DLL を入手するか、自分でビルドします (ビルドセクションを参照)。
  • workers.properties - ワーカー（Tomcat プロセス）が使用するホストやポートを記述したファイル。サンプルの workers.properties は、conf ディレクトリにあります。
  • uriworkermap.properties - URL パスパターンをワーカーにマップしたファイル。サンプルの uriworkermap.properties は、conf ディレクトリにあります。

インストールには次の部分が含まれます

  • デフォルトの /examples コンテキストで ISAPI リダイレクターを構成し、IIS でサーブレットを提供できることを確認します。
  • 構成にさらにコンテキストを追加します。

64 ビット環境では、少なくとも IIS 7 では、使用する IIS アプリケーションプールで「32 ビットアプリケーションを有効にする」が「False」に設定されている必要がある点に注意してください。それ以外の場合、リダイレクターが呼び出されず、HTTP コード 404 が返されます。isapi_redirect.dll の 32 ビットバージョンがその代わりになると考える場合、ライブラリが 64 ビット IIS に読み込めないため、HTTP コード 500 が返されます。

レジストリの設定

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を抽出するリクエストヘッダーの名前を表す文字列値です。

このディレクティブはバージョン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に設定されている場合、webサーバーでローカルに提供される場合は、";jsessionid=..."形式のURLセッションサフィックスが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はデコードされ、**..**」、「.**などの明示的なパスコンポーネントはすでに解決されています。これは仕様に準拠しておらず、「parsed」を使用すると、接頭辞転送ルールを使用している場合は安全ではありません。

値が「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値ワーカーは、バックグラウンドスレッドにより定期的に、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を使用します。サンプルとなる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ファイル内で使用できる環境変数が2つ自動的に環境に追加されました。

  • 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) フォーマットのコードを含むログファイル名を設定する場合は、ローテーション時刻として設定したものと同じ詳細を指定します。例: 毎日ローテーションする場合は ％Y-%m-%d（log_rotationtime=86400）。
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 を使用する必要があることに注意してください。