Apache Tomcat Connectors - リファレンスガイド

JkWorkersFile は、mod_jk がワーカー定義を見つける場所を指定します。詳細な説明については、ワーカーのドキュメントを参照してください。

JkWorkersFile     /etc/httpd/conf/workers.properties

JkLogFile は、mod_jk がログファイルを配置する場所を指定します。

JkLogFile     /var/log/httpd/mod_jk.log

Apache 2.x 用の JK 1.2.3 および Apache 1.3 用の JK 1.2.16 以降、これはパイプ付きログにも使用できます

JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"

JkLogLevel は、次の間のログレベルを設定します

• info ログには、標準の mod_jk アクティビティが含まれます (デフォルト)。
• warn ログには、致命的ではないエラーレポートが含まれます。
• error ログには、エラーレポートも含まれます。
• debug ログには、mod_jk アクティビティに関するすべての情報が含まれます
• trace ログには、mod_jk アクティビティに関するすべてのトレース情報が含まれます

JkLogLevel    info

通常の操作では、info をデフォルトとして選択する必要があります。

JkLogStampFormat は、mod_jk ログファイルに見られる日付/時刻形式を設定します。詳細については、上記を参照してください。

JkLogStampFormat "[%Y-%m-%d %H:%M:%S.%Q] "

Apache 標準モジュール mod_log_config を使用して mod_jk 情報をログに記録できます。モジュールは、Apache ノートテーブルにいくつかのノートを設定します。それらのほとんどは、ロードバランサーワーカーと組み合わせてのみ役立ちます。

LogFormat     "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \
               %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log
CustomLog     logs/access_log     mod_jk_log

アクセスログの代わりに、mod_jk のログファイルにリクエストプロトコルを記録することもできます。これは推奨されず、主に下位互換性のための機能です。ディレクティブ JkRequestLogFormat は、このプロトコルの形式を設定します。これは、仮想ホストごとに設定および有効化されます。仮想ホストのリクエストログを有効にするには、JkRequestLogFormat の設定を追加するだけです。フォーマット文字列の構文は Apache の LogFormat コマンドと似ており、利用可能なリクエストログのフォーマットオプションのリストを以下に示します。

JkRequestLogFormat     "%w %V %T"

ディレクティブ JkOptions を使用すると、以下のオプションを有効 (+) または無効 (-) にする多くの転送オプションを設定できます。先頭に符号がない場合、オプションは有効になります。

以下の 4 つのオプション +ForwardURIxxx は相互に排他的です。これらのうち正確に 1 つが必要です。負の符号の接頭辞は許可されていません。バージョン 1.2.24 以降のデフォルト値は "ForwardURIProxy" です。バージョン 1.2.23 では "ForwardURICompatUnparsed"、バージョン 1.2.22 までは "ForwardURICompat" でした。他の 2 つのオプションのいずれかをオンにすることで、デフォルトをオフにできます。変更する非常に正当な理由がない限り、デフォルト値のままにしておく必要があります。

すべてのオプションは、グローバルサーバーから仮想ホストに継承されます。有効化 (プラスオプション) および無効化 (マイナスオプション) をサポートするオプションは、次の方法で継承されます。
options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)

JkOptions ForwardURIProxy を使用すると、転送される URI は、Apache 内での処理後、Tomcat に転送する前に部分的に再エンコードされます。これは、mod_rewrite によるローカル URL 操作および URL エンコードされたセッション ID と互換性があります。

JkOptions     +ForwardURIProxy

JkOptions ForwardURICompatUnparsed を使用すると、転送される URI は解析されません。これは仕様に準拠しており、安全です。常に元のリクエスト URI を転送するため、mod_rewrite で URI を書き換えてから書き換えられた URI を転送することはできません。

JkOptions     +ForwardURICompatUnparsed

JkOptions ForwardURICompat を使用すると、転送される URI は Apache によってデコードされます。エンコードされた文字はデコードされ、".." などの明示的なパスコンポーネントはすでに解決されています。これは仕様への準拠が低く、プレフィックス JkMount を使用している場合は安全ではありません。このオプションを使用すると、転送前に mod_rewrite で URI を書き換えることができます。

JkOptions     +ForwardURICompat

JkOptions ForwardURIEscaped を使用すると、転送される URI は、ForwardURICompat で使用される URI のエンコードされた形式になります。 ".." などの明示的なパスコンポーネントはすでに解決されています。これは URL エンコードされたセッション ID と組み合わせて使用することはできませんが、転送前に mod_rewrite で URI を書き換えることができます。

JkOptions     +ForwardURIEscaped

JkOptions RejectUnsafeURI は、デコード後にパーセント記号 '%' またはバックスラッシュ '\' を含むすべての URL をブロックします。

ほとんどの Web アプリケーションでは、このような URL は使用されません。オプション RejectUnsafeURI を使用すると、いくつかのよく知られた URL エンコード攻撃をブロックできます。デフォルトでは、このオプションは設定されていません。

mod_rewrite を使用して、そのようなチェックを実現することもできます。これはより強力ですが、やや複雑です。

JkOptions     +RejectUnsafeURI

JkOptions CollapseSlashesAll は 1.2.44 で非推奨となり、使用されても無視されます。

JkOptions CollapseSlashesUnmount は 1.2.44 で非推奨となり、使用されても無視されます。

JkOptions CollapseSlashesNone は 1.2.44 で非推奨となり、使用されても無視されます。

JkOptions ForwardDirectories は、Apache の DirectoryIndex ディレクティブと組み合わせて使用されます。したがって、mod_dir は Apache で静的または動的 (DSO) に使用可能である必要があります。

DirectoryIndex が設定されている場合、Apache はディレクティブで指定された各ローカル URL に対してサブ リクエストを作成し、一致するローカル ファイルが存在するかどうかを判断します (これはファイルの stat を実行することによって行われます)。

ForwardDirectories が false (デフォルト) に設定されており、Apache が一致するファイルを見つけられない場合、Apache はディレクトリの内容を提供します (ディレクティブ Options がそのディレクトリに対して Indexes を指定している場合)、または 403 Forbidden 応答 (ディレクティブ Options がそのディレクトリに対して Indexes を指定していない場合)。

ForwardDirectories が true に設定されており、Apache が一致するファイルを見つけられない場合、リクエストは解決のために Tomcat に転送されます。これは、Apache がファイル システム上でインデックス ファイルを表示できない場合に、さまざまな理由で使用されます。Tomcat が別のマシンで実行されている、JSP ファイルがプリコンパイルされているなど。

ローカルで表示できるファイルは、Tomcat でのみ表示できるファイルよりも優先されることに注意してください (つまり、Apache がファイルを表示できる場合、それが提供されるファイルです)。これは、Tomcat が通常提供するファイルのタイプが複数ある場合に重要です (たとえば、Velocity ページと JSP ページ)。

JkOptions     +ForwardDirectories

JkOptions ForwardLocalAddress を設定すると、mod_jk に、リモート クライアント アドレスではなく、Apache HTTP サーバーのローカル アドレスを送信するように要求します。これは、構成された Apache サーバーからの接続のみを許可するために、Tomcat リモート アドレス バルブで使用できます。

JkOptions     +ForwardLocalAddress

JkOptions ForwardPhysicalAddress を設定すると、mod_jk に、クライアント アドレスとして物理ピア TCP IP アドレスを送信するように要求します。デフォルトでは、mod_jk は Web サーバーによって提供される論理アドレスを使用します。たとえば、モジュール mod_remoteip は、X-Forwarded-For ヘッダー内のプロキシによって転送されたクライアント IP に論理 IP アドレスを設定します。

JkOptions     +ForwardPhysicalAddress

JkOptions FlushPackets を使用すると、Tomcat から受信した各 AJP パケットチャンクの後に、mod_jk に Apache の接続バッファーをフラッシュするように要求します。このオプションは、通常必要な場合よりも頻繁に書き込みが実行されるため (つまり、各応答の最後)、Apache と Tomcat のパフォーマンスに大きな影響を与える可能性があります。

JkOptions     +FlushPackets

JkOptions FlushHeader を使用すると、mod_jk に、Tomcat から応答ヘッダーを受信した後、Apache の接続バッファーをフラッシュするように要求します。

JkOptions     +FlushHeader

JkOptions DisableReuse を使用すると、mod_jk に、使用直後に接続を閉じるように要求します。通常、mod_jk は永続的な接続を使用し、新しいリクエストを Tomcat に送信する必要がある場合、アイドル状態の接続をプールして再利用します。

このオプションを使用すると、Apache と Tomcat のパフォーマンスに大きな影響があります。修正不可能なネットワークの問題が発生した場合にのみ、最後の手段として使用してください。Apache と Tomcat の間のファイアウォールがアイドル状態の接続をサイレントに強制終了する場合は、ワーカー属性 socket_keepalive を OS の適切な TCP keepalive 値と組み合わせて使用してみてください。

JkOptions     +DisableReuse

JkOptions ForwardKeySize を使用すると、ajp13 を使用している場合、Servlet API 2.3 で必要な SSL キーサイズも転送するように mod_jk に要求します。サーブレットエンジンが Tomcat 3.2.x の場合は、このフラグを設定しないでください (デフォルトでオン)。

JkOptions     +ForwardKeySize

JkOptions ForwardSSLCertChain を使用すると、ajp13 を使用している場合、SSL 証明書チェーンを転送するように mod_jk に要求します (デフォルトではオフ)。 Mod_jk は SSL_CLIENT_CERT のみを AJP コネクタに渡します。これは、自己署名証明書またはルート CA 証明書によって直接署名された証明書では問題ありません。ただし、中間 CA 証明書によって署名された証明書が多数あり、これは重大な問題です。サーブレットは、クライアント証明書を独自に検証する可能性がありません。 AJP コネクタ経由で SSL_CLIENT_CERT_CHAIN を Tomcat に渡すことでバグが修正されます。
このディレクティブは、バージョン 1.2.22 以降でのみ存在します。

JkOptions     +ForwardSSLCertChain

ディレクティブ JkEnvVar を使用すると、Apache サーバーから Tomcat エンジンに環境変数を転送できます。ディレクティブの 2 番目のパラメーターとしてデフォルト値を追加できます。デフォルト値が明示的に指定されていない場合、変数はランタイム中に設定されている場合にのみ送信されます。
変数は、request.getAttribute(attributeName) を介して Tomcat 側でリクエスト属性として取得できます。 JkEnvVar を介して送信される変数は、request.getAttributeNames() にリストされないことに注意してください。
変数は、グローバルサーバーから仮想ホストに継承されます。

JkEnvVar     SSL_CLIENT_V_START     undefined

上記のように mod_jk.conf-local のカスタムまたはローカル バージョンを作成した場合は、ワーカーや URL プレフィックスなどの設定を変更できます。

JkMount ディレクティブは、特定の URL を Tomcat に割り当てます。一般に、JkMount ディレクティブの構造は次のとおりです。

JkMount [URL prefix] [Worker name]

# send all requests ending in .jsp to worker1
JkMount /*.jsp worker1
# send all requests ending /servlet to worker1
JkMount /*/servlet/ worker1
# send all requests jsp requests to files located in /otherworker will go worker2
JkMount /otherworker/*.jsp worker2

JkMount ディレクティブは、httpd.conf ファイルの最上位レベルまたは <VirtualHost> セクション内で使用できます。

JkUnMount ディレクティブは JkMount の反対として機能し、特定の URL へのアクセスをブロックします。目的は、マウントされたコンテキストから特定のコンテンツ タイプを除外できるようにすることです。次の例では、/servlet/* コンテキストをマウントしますが、そのコンテキストに属するすべての .gif ファイルは提供されません。

# send all requests ending with /servlet to worker1
JkMount /servlet/* worker1
# do not send requests ending with .gif to worker1
JkUnMount /servlet/*.gif worker1

JkUnMount は JkMount ディレクティブよりも優先されます。つまり、JK は最初にマウントを試み、次に JkUnMount によって定義された除外があるかどうかを確認します。 JkUnMount は、JkMount と JkUnMount のワーカー名が同じ場合にのみ、JkMount をオーバーライドします。

次の例では、.gif ファイルに対する JkMount が存在する場合でも、すべての .gif ファイルがブロックされます。

# do not send requests ending with .gif to worker1
JkUnMount /*.gif worker1
# The .gif files will not be mounted cause JkUnMount takes
# precedence over JkMount directive
JkMount /servlet/*.gif worker1

JK のバージョン 1.2.26 以降では、JkUnMount でワーカー名としてスター文字 '*' を使用することにより、JkUnMount を任意のワーカーに適用できます。 JkUnMount ワーカー名でのより複雑なパターンは許可されていません。

# Mapping the webapps myapp1 and myapp2:
/myapp1/*=worker1
/myapp2/*=worker2
# Exclude the all subdirectories static for all workers:
!/*/static/*=*
# Exclude some suffixes for all workers:
!*.html=*

JkAutoAlias ディレクティブは、webapp コンテキスト ディレクトリを Apache ドキュメント スペースに自動的に Alias します。これにより、Apache は静的コンテキストを提供し、Tomcat は動的コンテキストを提供できます。このディレクティブは、Tomcat の webapp ディレクトリ内の各アプリケーション ディレクトリに対して Apache Alias ディレクティブを配置する必要がないようにするために使用されます。セキュリティ上の理由から、JkMount を使用してすべてのリクエストをデフォルトで Tomcat に渡し、JkUnMount を使用して Apache によって提供される静的コンテンツを明示的に除外することを強くお勧めします。また、Apache によって提供されるコンテンツは、アプリケーションの web.xml で定義されているセキュリティ制約をバイパスすることにも注意してください。ディレクティブは、単一のパス要素を持つコンテキストとバージョン マーカーがない単純な場合にのみ機能します。それはサポートしていません

• ROOT コンテキスト (つまり、.../webapps/ROOT)
• マルチレベル コンテキスト (例: .../webapps/foo#bar)
• 並列デプロイメント (例: .../webapps/foo##v00.05.12)

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

次の例は、Tomcat による動的コンテキストと Apache による静的コンテキストの提供方法を示しています。 webapps ディレクトリは Apache からアクセスできる必要があります。

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

# Mount 'examples' directory. It's physical location
# is assumed to be in the /opt/tomcat/webapps/examples
# ajp13w is a worker defined in the workers.properties
JkMount /examples/* ajp13w

# Unmount desired static content from examples webapp.
# This content will be served by the Apache directly.
JkUnMount /*.gif ajp13w

httpd.conf 内の仮想ホストごとに 1 つの JkAutoAlias ディレクティブを持つことができることに注意してください。

JkWorkerProperty は、JK 1.2.7 バージョン以降で使用可能な新しいディレクティブです。これは、通常 workers.propeties ファイル内で設定されるディレクティブを設定するための便利な方法です。そのディレクティブのパラメーターは、workers.properties ファイルからの生の行です。

# Just like workers.properties but exact line is prefixed
# with JkWorkerProperty

# Minimal jk configuration
JkWorkerProperty worker.list=ajp13w
JkWorkerProperty worker.ajp13w.type=ajp13
JkWorkerProperty worker.ajp13w.host=localhost
JkWorkerProperty worker.ajp13w.port=8009   

JkMountFile は、JK 1.2.9 バージョン以降で使用可能な新しいディレクティブです。これは、ランタイム時のマウントポイントの動的な更新に使用されます。マウント ファイルが変更されると、JK はそのコンテンツをリロードします。

# Load mount points

JkMountFile conf/uriworkermap.properties

マウントポイントの URI が感嘆符 '!' で始まる場合、JkUnMount と同じ方法で除外を定義します。マウントポイントの URI がマイナス記号 '-' で始まる場合、マウントポイントは無効になります。無効なマウントは、マイナス記号を削除し、JkMountFile がリロードされるのを待つことによって再度有効にすることができます。除外は、先頭にマイナス記号を付けることで無効にすることができます。

# Sample uriworkermap.properties file

/examples/*=ajp13w
# Do not map .gif files
!/*.gif=ajp13w
# Make jsp examples initially disabled  
-/examples/jsp/*=ajp13w

実行時に、このファイルの内容を変更できます。たとえば、マイナス記号を削除すると、以前に無効にした URI マッピングが有効になります。新しくデプロイされたアプリケーションを反映する新しいエントリをランタイム時に任意の数だけ追加できます。 Apache はファイルをリロードし、60 秒間隔でマウントポイントを更新します。

動的なリロードによってエントリを削除する方法はありませんが、マッピングを無効または除外することができます。

mod_jk 固有のディレクティブに加えて、SetHandler と環境変数を使用して、どのリクエストがどのワーカーを介して転送されるかを制御することもできます。これにより、柔軟性が向上しますが、結果が理解しにくくなる可能性があります。フォワードを定義する両方の方法を組み合わせると、一般に mod_jk ディレクティブが優先されます。

SetHandler jakarta-servlet は、リクエストが mod_jk によって処理されるように強制します。たとえば、Location ブロックまたは Apache 2.2 以降では RewriteRule でも SetHandler を使用できます。

より複雑なルールに対して SetEnvIf または RewriteRule を使用してワーカーを制御するには、環境変数 JK_WORKER_NAME を選択したターゲット ワーカーの名前に設定できます。これにより、Cookie 値への依存関係など、より柔軟な方法で選択したワーカーを決定できます。この機能は、mod_jk のバージョン 1.2.19 で追加されました。さらに、ルール拡張をワーカー名に追加できます。拡張子は、uriworkermap.properties ファイルと同じ構文を使用して、セミコロン ";" でワーカー名から区切られます。ワーカー名でのルール拡張のサポートは、バージョン 1.2.33 で追加されました。

JK_WORKER_NAME 以外の変数を使用するには、ディレクティブ JkWorkerIndicator を介してこの変数の名前を設定できます。

環境変数 no-jk を設定することにより、mod_jk フォワードから除外を定義することもできます。

# Automatically map all encoded urls
<Location *;jsessionid=>
  SetHandler jakarta-servlet
  SetEnv JK_WORKER_NAME my_worker
</Location>

# Map all subdirs to workers via naming rule
# and exclude static content.
<Location /apps/>
  SetHandler jakarta-servlet
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk
</Location>

環境変数を使用すると、リクエスト URI、ヘッダー値、Cookie などのリクエスト プロパティに応じて、mod_jk のデフォルトの動作を上書きできます。これは、SetEnvIf または RewriteRule ディレクティブを使用して実行できます。

環境変数 JK_ROUTE を設定して、ロード バランサー ワーカーのメンバーを明示的に選択できます。値は、メンバーのルート属性と等しくなければなりません。その属性が使用されていない場合は、メンバー名と等しくなければなりません。これは、セッション ID とルートがリクエストで非標準的な方法でエンコードされている場合にのみ必要であることに注意してください。 Java サーブレットに準拠した ID エンコード方法を使用したスティッキー セッションは、デフォルトでサポートされています。これはバージョン 1.2.33 以降で使用可能です。

環境変数 JK_REPLY_TIMEOUT を設定して、応答タイムアウトを動的に定義できます。値はミリ秒単位で指定する必要があります。これはバージョン 1.2.27 以降で使用可能です。

環境変数 JK_STICKY_IGNORE を設定して、個々のリクエストのセッション スティッキー セッションを無効にできます。変数が空の文字列またはゼロ以外の数値に設定されている場合、セッション スティッキー セッションは無効になります。 0 に設定すると、ワーカー構成で定義された動作にリセットされます。これはバージョン 1.2.33 以降で使用可能です。

この機能は、Cookie ベースのセッション スティッキー セッションを使用する場合に、ロード バランシングを最適化するのに役立ちます。この場合、ブラウザーを開いている限り、セッションを開始したユーザーによるリクエストは、セッションを使用するアプリケーションの部分を離れた場合でも、同じ Tomcat インスタンスに送信されます。たとえば、ユーザーがログインフォームを要求した場合に、この環境変数を設定して、最初のセッション リクエストが非スティッキーで負荷分散されるようにすることができます。

環境変数 JK_STATELESS を使用すると、セッション ベースのバランシング方法 Session および Next のロード バランシングを改善できます。この場合、通常、セッション ID が付属していないリクエストはすべて新しいセッションとしてカウントされます。これは、たとえば静的コンテンツがセッション ID なしで取得される場合に問題になる可能性があります。リクエストに対して環境変数 JK_STATELESS を設定すると、セッション ID が付属していなくても、リクエストは新しいセッションとしてカウントされません。これはバージョン 1.2.33 以降で使用可能です。

環境変数 JK_IGNORE_CL を設定すると、リクエスト Content-Length ヘッダー (存在する場合) を強制的に無視できます。 mod_jk は、Web サーバーが本文全体が読み取られたことを示すまで、リクエスト本文をストリーミングします。 Content-Length ヘッダーはバックエンドに送信されません。これはバージョン 1.2.41 以降で使用可能です。

この機能を使用すると、リクエスト本文のサイズを変更するフィルターと mod_jk を互換性を持たせることができます。そのようなフィルターの 1 つは、gzip エンコードされた本文でリクエストの本文を解凍するために使用される mod_deflate です。この場合、mod_jk はデフォルトで、Web サーバーから間違った本文サイズを取得するため、切り捨てられた本文を転送します。 mod_jk に Content-Length ヘッダーを無視するように指示すると、Web サーバーから読み取ることができるすべてのリクエスト本文データがバックエンドにストリーミングされます。

実際に必要なリクエストに対してのみ、JK_IGNORE_CL 環境変数を設定する必要があります。残念ながら、mod_jk が必要性を自動的に検出する方法はありません。