The Apache Tomcat Connectors - リファレンスガイド (1.2.50) - Microsoft IIS 用 ISAPI リダイレクターの構成

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サーバーによってローカルで提供される場合、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は拒否されます。ほとんどの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) フォーマットコードを含むログファイル名を構成する場合は、設定されたローテーション時間と同じ粒度を指定していることを確認してください。例えば、日次ローテーションの場合 (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を使用する必要があることに注意してください。