コンポーネント

この文書は、Jakarta Projectが記述した JK2ドキュメントを翻訳したものです。

Apache Software Foundation | Jakarta Project | Apache Tomcat

はじめに

それぞれのコンポーネントのインスタンスは名前を持っています。それは設定のために実行時に利用されます。それぞれのコンポーネントはいくつかの設定可能なプロパティを持っています。以下に示すルールに従います。

名前は、':'で区切られるタイプとローカルパートから構成されます。 ( 例: channel.unixsocket:/tmp/jk.socket )
タイプは'.'とアスキー文字から成ります。それはJMXの'domain'と対応づけられます。
ローカルパートはアスキー文字と .:/; から成ります。
プロパティはドットを含まない単純な名前です。
単純な形式の置換は、あらかじめ定義された$(property)の値が使われます。もしプロパティが':'を含んでいたら、オブジェクトから値を得ることになります。そうでなければグローバル・マップから値を取り出します。

共通のプロパティ

すべてのコンポーネントで共通のプロパティ

プロパティ名	デフォルト	説明
disabled	0 (false)	コンポーネントの"disabled(無効)"状態, 1=true 0=false
debug	0 (false)	コンポーネントのデバッグレベル, 0=無効, 1..10 有効数値が高いほど詳細なデバッグ情報を生成します。
version	0	コンポーネント構成の'世代(Generation)'. 実行環境で再構成をする際に重要です。設定ファイルを編集したり、shmemプロパティを設定した場合、修正したコンポーネントのバージョンも同時に更新しなければなりません。設定レイヤーは変更を検出し、セッターメソッドを呼び出します。

workerEnv

このコンポーネントはjk2のコア部分に相当します。このコンポーネントは他のすべてのコンポーネント用のデフォルトloggerを持ちます。中央コントローラであるため、このコンポーネントはグローバルプロパティを制御し、他のすべてのオブジェクトへのアクセスを提供します。

プロパティ名	デフォルト	説明
logger	logger	jk2コンポーネントによって使用されるデフォルトの logger, 設定ファイルで変更が可能です。通常は、そのデフォルト値は"logger" で、サーバ/プラットフォームのデフォルトloggerの別名となっています。
timing	0	jk2が要求を得るタイミングでしょう (APRで必要?)

config

設定ファイル名のような、システムの設定の詳細を保持するconfigコンポーネントはグローバルな定義を生成します。

プロパティ名	デフォルト	説明
file	${serverRoot}/conf/workers2.properties	workers2.properties ファイルの場所
debug	0	設定コンポーネントのデバッグレベルを設定します。
debugEnv	0	隠蔽されているenvコンポーネントのデバッグレベルを設定します。

uriMap

shm

共有メモリ　ディスクリプタ

プロパティ名	デフォルト	説明
file	デフォルト値なし	共有メモリとして使われ、mmapで対応づけられるファイル名
size	デフォルト値なし	ファイルのサイズ

uri

uriは、ワーカへのリクエストの一致に使われ、プロパティと関連しているパターンを保存します。

もし uri名がスラッシュを持たないなら、それは仮想ホスト指示子と考えられます。uri名は仮想ホスト名と（または）関連するポートを持つことができます。それらの名前の書式は hostname または hostname:port となります。hostnameは仮想サーバ名で、ポートは仮想サーバのポート番号を意味します。ポート番号はデフォルトサーバポートでない場合のみ指定します。

デフォルトサーバが [uri:*] と名づけられている場合は特別です。これは仮想ホストが設定内に見つからない場合に使われます。ホスト名を含んでいないすべてのuri指示子は、グローバルマッピングを持つデフォルトサーバに属します。

ワイルド文字スキーマid [uri:*:port] の追加。ある特別な（デフォルトでない）ポート番号の仮想ホストとマッチさせたい時に利用します。たとえば[uri:*:443]のようにです。これは、名前が何であれ、ポート番号443であるすべての仮想ホストについて、対応づけされます。

ホスト名が解決される手順 :

正確なホスト名。オプションとしてデフォルトと異なるポート番号
ホスト名とポート番号が一致するエリアス
*:port。ポートがデフォルト以外の値だったら、デフォルト
デフォルトサーバ

プロパティ名	デフォルト	説明
group	lb:0 (デフォルト・ロードバランサ)	tomcatグループまたはワーカの名前。この名前はuriに一致するリクエストを処理します。これは以前は'worker'というプロパティ名でした。
context		このuriコンポーネント(webappスタイル)のためのコンテキストパス
servlet		このマッピングのためのサーブレットパス
alias		サーバ名のエリアス。これは[uri:myHost:myPort](すなわち / を含まない)のようなホスト uri に対してのみ設定できます。

内部プロセスコンテナとして利用されるJVMを意味します。

プロパティ名	デフォルト	説明
JVM	(Autoguess)	このvmで使用するJVM
OPT		このvmへパスされるオプション。これは複数指定ができるプロパティです。
classpath		このvmへ、-Djava.class.path オプションをパスします。これは複数の値を指定できるプロパティです。

channels

channelはRPC通信のために２つの通信サイドを接続する転送プロトコルを意味します。もっとも共通に使われていて、標準となっているものにTCPソケットがあります。他に重要なchannelとしては、UNIXソケットとJNIがあります。

channel.un

AF_UNIX ソケット。UNIX 系プラットフォームのみ有効です。これらのソケットは"通常"のソケットよりも高速ですが、動作するマシンは制限されています。

プロパティ名	デフォルト	説明
file	ソケット名	ソケットファイル名(Tomcat ChannelUnによって作成されます)

channel.socket

リモートエンジンへの通信路 Magic: ローカルパートの名前はエンジン名で、 uriとの対応を決めるときに使用されます。例えば、channel.socket.local_9009 は自動的にlocal_9009という名前のエンジンを決めます。そして、もし他に設定が無ければ、ajp13が通信に利用されます。 Magic: もし設定においてchannelが１つも定義されていない場合は、 port=8009, engine=DEFAULT, worker=ajp13 という設定で、名前が'channel.socket.DEFAULT'というデフォルトchannelが構築されます。

プロパティ名	デフォルト	説明
port	8009	Tomcatが利用するポート番号
host	localhost	リモートホスト
keepalive	0	?
lbfactor	1	ロードバランシングの要素。現時点では、worker上で設定されるでしょう。しかし、将来的には、channelレベルのlbを使って指定できるようになるでしょう。
group	lb:0	このchannelと関連があるworkerが追加されるロードバランスされたグループ。複数の値が指定可能。
tomcatId	?	?

channel.apr

APRライブラリを使ったリモートエンジンへの通信路 Magic: ローカルパートの名前はエンジン名で、 uriとの対応を決めるときに使用されます。例えば、channel.apr.local_9009 は自動的にlocal_9009という名前のエンジンを決めます。そして、もし他に設定が無ければ、ajp13が通信に利用されます。 Magic: もし設定においてchannelが１つも定義されていない場合は、 port=8009, engine=DEFAULT, worker=ajp13 という設定で、名前が'channel.apr.DEFAULT'というデフォルトchannelが構築されます。

プロパティ名	デフォルト	説明
port	8009	Tomcatが利用するポート番号
host	localhost	リモートホスト
keepalive	0 (無効)	1が設定されたら、TCPコネクションでのkeep-aliveパケットが有効になります。
timeout	0 (無限)	ソケット通信での送信受信のタイムアウト
ndelay	0	1が設定されたら、小さいパケットをまとめて送るNagleアルゴリズムを無効にします。
lbfactor	1	ロードバランシングの要素。現時点では、worker上で設定されるでしょう。しかし、将来的には、channelレベルのlbを使って指定できるようになるでしょう。
group	lb:0	このchannelと関連があるworkerが追加されるロードバランスされたグループ。複数の値が指定可能。

channel.jni

jni channel。tomcatがinprocessで開始された時に使われます。

workers

現時点では、worker.jni、ajp13、status、lb の 4 つのタイプのワーカがサポートされています。

worker.jni

内部プロセスにおいて利用されるワーカは、起動するためのTomcatクラスの詳細と、渡すためのパラメータを持ちます。

onStartup と onShutdown という２つのあらかじめ定義されたjni ワーカがあります。それらの２つのワーカはコネクターの起動時と停止時に実行されます。２つともTomcatを起動、停止可能にするために設定が存在していなければなりません。

プロパティ名	デフォルト	説明
class	org/apache/jk/apr/TomcatStarter	tomcatを開始するためのmainメソッドを持つクラス
ARG		meinメソッドへパスされる引数
stdout	NULL	Javaプロセスからの標準出力をリダイレクトするファイル名
stderr	NULL	Javaプロセスからの標準出力(訳注：標準エラー出力ではないだろうか)をリダイレクトするファイル名

ajp13

デフォルトワーカ

プロパティ名	デフォルト	説明
secretkey	NULL	Magic: 秘密鍵は関連するworkerに自動的に設定されます。
tomcatId
route
group
level
channel
max_connections	0 (無制限 unlimited)	現在使用されているエンドポイントの最大値。指定した数に達したら、ロードバランサは他のworkerへ試行する機会を得ます。これは、複数のサーバがありlb_factorをより細かく調整したいような状況ではとても有効です。

status

JK2をモニタするための有用な情報をページへ出力するワーカ

利用するためには、このワーカに割り当てるuriコンポーネントを追加します。

ロードバランスをするワーカ

プロパティ名	デフォルト	説明
worker
noWorkerMsg
noWorkerCode	503
hwBalanceErr
timeout	0 (無効)	たとえばTomcatが過度な負担の原因となる新しい接続を拒絶することによって、すべてのワーカがエラー状態になる場合は、timeoutを設定してみましょう。これはlbに対して、クライアントに即時でエラーを返す代わりに、いくつかのワーカが有効になるまで待たせることを強制する働きがあります。これはハイピークロード(high peek load)のような状況ではとても有効です。timeoutはアプリケーション呼び出し時間の最大値を指定すべきです。ただし、1秒未満は指定してはいけません。
attempts	3	試行回数。lbが各ワーカに、あきらめずに試してみる回数
recovery	60 (seconds)	ワーカがエラー状態になっているように見える時に、再試行の前に待機する時間

loggers

jk2をベースとしてコネクタはどれでも、少なくともデフォルトloggerをもっています。それは "logger"エリアスを利用して到達できます。利用されるloggerはプラットフォームとサーバの組み合わせによって、さらに特定できます。(appropiate → appropriate) Apache2はどのプラットフォームの下でもデフォルトとしてlogger.apache2を持っています。IISはlogger.win32を使用する唯一のプラットフォームです。そしてapache 1 はどのプラットフォームでもデフォルトとしてlogger.fileを使用します。設定ファイルでデフォルトを変更できます。たとえば、IISにおいてlogger.fileを使ってファイルの末尾にログを追加することもできます。

すべてのloggerで共通のプロパティ:

プロパティ名	デフォルト	説明
level	INFO	ログレベル。サポートされている値: EMERG, ERROR, INFO, DEBUG

logger.file

プロパティ名	デフォルト	説明
file	${serverRoot}/logs/jk2.log	ログファイル. XXX rollingを実装することにより、実行時にこれを変更できるかもしれません。

logger.win32

デフォルトでIISサーバで利用されるloggerです。ネイティブ・アプリケーション・イベント・ログの末尾にログを追加します。

logger.apache2

Apache2サーバで利用されるloggerです。通常は error.log の末尾にログを追加します。

[訳注: これは小山博史が翻訳しました。日本語訳に対するコメントがあれば、こちらに送って下さい。]