Apache Tomcat 設定リファレンス

Host コンテナ

Host 要素は仮想ホスト (virtual host) を表す。 これは何らかのサーバを表すネットワーク上の名前 (例えば "www.mycompany.com") と Catalina が走っている特定のサーバの組み合わせである。 効率のため，この名前は，君が属しているインターネット・ドメインを管理する Domain Name Service (DNS) サーバに登録されなければならない - 詳しい情報 については君のネットワーク管理者に問い合わせよ。

多くの場合，システム管理者はネットワーク上の複数の名前 (例えば www.mycompany.com と company.com) を同じ一つの仮想ホストとアプリケーションと組み合わせることを望む。 これは下記で議論する Host Name Aliases 機能を使って達成できる。

１個以上の Host 要素が Engine 要素の内側に入れ子にされる。 Host 要素の内側で，君は複数の Context 要素を入れ子にできる。 Context 要素はその仮想ホストの web アプリケーションを表す。 各 Engine に対し，正確に１個の Host が， Engine の defaultHost 属性と一致する名前でなければならない。

以下の記述では変数名 $CATALINA_HOME を使って，君が Tomcat 6 をインストールしたディレクトリを表す。 これは大多数の相対パスの解決に使われる基準ディレクトリである。 しかし，もしも君が CATALINA_BASE ディレクトリをセットして Tomcat 6 を複数インスタンス用に設定したならば， $CATALINA_HOME が参照されているところにそれぞれ $CATALINA_BASE を使わなければならない。

共通属性

Host のすべての実装は次の属性をサポートする: Attribute Description appBase この仮想ホストに対する Application Base ディレクトリ。 これは，この仮想ホストにデプロイされる web アプリケーションが置かれるディレクトリのパス名である。 君はこのディレクトリとして絶対パス名を指定してもよいし， $CATALINA_BASE ディレクトリからの相対パス名を指定してもよい。 自動的にデプロイされる web アプリケーションの自動的な認識とデプロイメントについて詳しくは Automatic Application Deployment を見よ。 autoDeploy これは，Tomcat が走っている最中に appBase ディレクトリに新しく置かれた web アプリケーションが，自動的にデプロイされるかどうかのフラグである。 フラグのデフォルト値は true である。 詳しくは Automatic Application Deployment を見よ。 backgroundProcessorDelay この値は，この host およびその子コンテナ (すべての context を含む) での backgroundProcess メソッドの呼出しと呼出しの間の遅延 (秒) を表す。 子コンテナの遅延値が非負ならば (子コンテナが自分自身の処理スレッドを使うことを意味するから)， 子コンテナ [のメソッド] を呼び出すことはしない。 この値を正にすると [その host 用の処理] スレッドが１本，生成される。 指定された秒数だけ待ってから，このスレッドは host およびその子コンテナすべての backgroundProcess メソッドを [どれか１個] 呼び出す。 host は background 処理を使ってライブ web アプリケーション・デプロイメント関連のタスクを実行する。 指定しなければ，この属性のデフォルト値は -1 である。 これは host が自分の親である engine の background 処理スレッドに頼ることを意味する。 className 使用する実装の Java クラス名。 このクラスは org.apache.catalina.Host インタフェースを実装しなければならない。 指定しなければ，標準値 (下記で定義) が使われる。 deployOnStartup これは，この host からの web アプリケーションが host の configurator によって 自動的にデプロイされるかどうかのフラグである。 フラグのデフォルト値は true である。 詳しくは Automatic Application Deployment を見よ。 name この仮想ホストのネットワーク上の (君の Domain Name Service サーバに登録されたとおりの) 名前。 Engine の内側に入れ子にされた Host の１個は，その Engine の defaultHost の設定と一致する名前でなければならない。 同一の仮想ホストにネットワーク上の名前を複数割り当てる方法については Host Name Aliases を見よ。

標準実装

Host の標準実装は org.apache.catalina.core.StandardHost である。 (上記の共通属性に加えて) 次の付加的な属性をサポートする: Attribute Description deployXML アプリケーション内部に組み込まれた context.xml ファイル (/META-INF/context.xml) のパースをディスエーブルするには false にセットせよ。 セキュリティを意識した環境ならば，これを false にセットして， アプリケーションがコンテナの設定と相互作用することを防ぐべきである。 このとき，管理者は contxt 設定ファイルを別に用意して $CATALINA_HOME/conf/[enginename]/[hostname]/ に置く責任がある。 フラグのデフォルト値は true である。 errorReportValveClass この Host が使うエラー報告 valve の Java クラス名。 この valve の責任はエラー報告 (error report) の出力である。 このプロパティをセットすることで，Tomcat が生成するエラー・ページの見映えをカスタマイズできる。 このクラスは org.apache.catalina.Valve インタフェースを実装しなければならない。 指定しなければ org.apache.catalina.valves.ErrorReportValve がデフォルトで使われる。 unpackWARs WAR (web application archive) ファイルの形式で appBase ディレクトリに置かれた web アプリケーションを対応するディスク・ディレクトリ構造へ unpack させるには true にセットせよ。 false ならば WAR ファイルから直接 web アプリケーションが走る。 詳しくは Automatic Application Deployment を見よ。 workDir この Host のアプリケーションが使う scratch ディレクトリのパス名。 各アプリケーションは一時的な読み書き用にそれ自身の下位ディレクトリを持つ。 Context の workDir を設定すると，そちらが Host の workDir 設定よりも優先される。 web アプリケーション内のサーブレットからは，このディレクトリは Servlet Specification の記述どおり　 javax.servlet.context.tempdir という context 属性 (java.io.File 型) によって可視である。 指定しなければ，$CATALINA_HOME/work 下の適当なディレクトリが用意される。

君はこの Host 要素の内側に１個以上の Context 要素を入れ子にできる。 それぞれがこの仮想ホストの別々の web アプリケーションを表す。

君は次のユーティリティ・コンポーネントをたかだか１個だけ Host 要素の内側に入れ子にできる:

• Realm - １個の realm のユーザ (とそのロール) のデータベースが， この Host の内側のすべての Context で共有されるように設定する。 ただし，下位レベルの Realm 設定が，これよりも優先される。

Logging

host の log category は org.apache.catalina.core.ContainerBase.[enginename].[hostname] である。 ブラケットは，実際に名前の一部であり，省略してはならない。

アクセス・ログ

君が web サーバを走らせる時，通常生成される出力ファイルの一つがアクセス・ログ である。 これはサーバが処理したリクエストごとに，ある標準的な書式で，１行の情報を生成する。 Catalina にはオプションとして Valve 実装がある。 これは [多くの] web サーバが作成する標準的な書式で，あるいは任意のカスタム書式で， アクセス・ログを作成することができる。 君は，下記のように Valve 要素を入れ子にすることによって， Engine， Host または Context が処理する全リクエストに対し，アクセス・ログを作成するように Catalina に要求できる。 <Host name="localhost" ...> ... <Valve className="org.apache.catalina.valves.AccessLogValve" prefix="localhost_access_log." suffix=".txt" pattern="common"/> ... </Host> サポートされている設定属性について詳しくは Access Log Valve を見よ。

Automatic Application Deployment

もしも君が標準的な Host 実装を使っているならば，Catalina が最初にスタートした時， 次のアクションが自動的に起こる。 ただし，deployOnStartup プロパティが true にセットされているならばである (デフォルト値はそうなっている): $CATALINA_HOME/conf/[engine_name]/[host_name] ディレクトリのどの XML ファイル も，１個の Context 要素 (と随伴するその下位要素) を１個の web アプリケーションのために持っていると仮定される。 この <Context> 要素の docBase 属性は典型的には web アプリケーション・ディレクトリの絶対パス名か， または (展開されない) WAR (web application archive) ファイルの絶対パス名である。 path 属性が Context のドキュメンテーションで定義されたように自動的にセットされる。 appBase (application base) ディレクトリ内のどの WAR ファイルも， もしも対応する同じ名前のディレクトリ (".war" 拡張子を除く) がなければ自動的に展開される。 ただし，unpackWARs プロパティが false にセットされていなければである。 もしも君が更新した WAR ファイルを再デプロイするならば， 更新した WAR ファイルが再展開されるように， Tomcat を再スタートするとき，展開されたディレクトリを忘れずに削除すること (自動デプロイヤがイネーブルならば，更新された WAR ファイルは，以前に展開されたディレクトリが 除去された途端に自動的に展開されることに注意せよ)。 application base directory 内のどの下位ディレクトリも， 自動生成された Context 要素を受け取る。 たとえそのディレクトリが conf/server.xml ファイルで言及されていなくてもである。 この生成された Context エントリは，この Host 要素で入れ子にされた DefaultContext 要素がセットするプロパティにしたがって設定される。 このデプロイされた Context の context path はスラッシュ文字 ("/") にディレクトリ名を続けたものになる。 ただし，ディレクトリ名が ROOT の場合は，context path は空文字列 ("") になる。 スタートアップ時に起こる自動デプロイメントに加えて， 君は，新しい XML 設定ファイル，WAR ファイル，または下位ディレクトリが appBase (または XML 設定ファイルの場合は $CATALINA_HOME/conf/[engine_name]/[host_name]) ディレクトリに，Tomcat が走っているあいだにドロップされたとき， 上述の規則にしたがって自動的にデプロイされることを要求してよい。 自動デプロイヤはまた web アプリケーションを次の変更に対し追従する: WEB-INF/web.xml の更新は web アプリケーションの再ロードを引き起こす。 WAR の更新は，(展開されたディレクトリを除去せずに) デプロイ解除を引き起こし， 直後にその web アプリケーションのデプロイメントが続く。 XML 設定ファイルの更新は，(展開されたディレクトリを除去せずに) デプロイ解除を引き起こし， 直後にその web アプリケーションのデプロイメントが続く。 自動デプロイメントを使うときは，XML Context ファイルが定義する docBase を，appBase ディレクトリの外側にすべきである。 そうしなければ，web アプリケーションをデプロイするときに難儀したり， アプリケーションが２度デプロイされるかもしれない。 最後に，もしも君が context を陽に定義するならば，おそらく自動アプリケーション・デプロイメントは切ったほうがよい。 そうしなければ，君の contxt は毎回２度デプロイされることになるから， アプリケーションに問題を引き起こすかもしれない。

Host Name Aliases

多くのサーバ環境では，ネットワーク管理者は 同じサーバの IP アドレスへリゾルブされる 複数のネットワーク名を (Domain Name Service (DNS) サーバに) 設定している。 通常，このようなネットワーク名は conf/server.xml の 別々の Host 要素として設定される。 そして，それぞれがそれ自身の web アプリケーションの集合を持つ。 しかし，状況によっては，複数のネットワーク名が，同じアプリケーションの集合を走らせている 同じ仮想ホストへリゾルブされるほうが望ましいことがある。 このよくある例は会社の web サイトである。 ユーザが www.mycompany.com と company.com のどちらを利用しても 正確に同じコンテンツとアプリケーションにアクセスできることが望ましい。 これは Host 要素に入れ子で Alias 要素を１個以上使えば達成される。 例えば: <Host name="www.mycompany.com" ...> ... <Alias>mycompany.com</Alias> ... </Host> この戦略を有効にするには，関係するすべてのネットワーク名を DNS サーバに登録して， 名前がこの Catalina のインスタンスを走らせている同じ計算機へリゾルブされるようにする必要がある。

ライフサイクル・リスナ

もしも君が，この Host が何時 start または stop したのかを知る必要がある Java オブジェクトを実装したときは，この要素の内側に Listener を入れ子にすることで， それを宣言できる。 君が指定するクラス名は org.apache.catalina.LifecycleListener インタフェースを実装していなければならない。 そのクラスは対応するライフサイクル・イベントが生じたことを [メソッドの呼出しによって」知らされる。 このようなリスナの設定はこうなる: <Host name="localhost" ...> ... <Listener className="com.mycompany.mypackage.MyListener" ... > ... </Host> Listener はどれだけでも多く付加的なプロパティを持つことができる。 それらのプロパティを，この [XML の] 要素から設定してよい。 [要素の] 属性名は，標準的なプロパティ・メソッド命名パターンを使って，対応する JavaBean のプロパティ名と照合される。 [foo という名前の属性の値は setFoo メソッドでセットされる，などです]

リクエスト・フィルタ

君は，取り囲む Engine, Host または Context 要素あてに 到来した各リクエストについて，IP アドレスまたはホスト名をチェックするように Catalina に要求できる。 リモート・アドレスまたは名前が "accept" および/または "deny" フィルタの設定リストに対してチェックされる。 各フィルタは Jakarta Regexp 正規表現ライブラリ がサポートする正規表現構文を使って定義される。 accept されない場所から来たリクエストは HTTP "Forbidden" エラー [コード 403] で拒絶される。 フィルタ宣言の例: <Host name="localhost" ...> ... <Valve className="org.apache.catalina.valves.RemoteHostValve" allow="*.mycompany.com,www.yourcompany.com"/> <Valve className="org.apache.catalina.valves.RemoteAddrValve" deny="192.168.1.*"/> ... </Host> サポートされている設定オプションについて詳しくは Remote Address Filter と Remote Host Filter を見よ。

Single Sign On

多くの環境では，とりわけポータル環境では，特定の仮想ホストにデプロイされた web アプリケーションの集合上でユーザはたった１回だけ自分自身の認証を求められることが望ましい。 これは仮想ホストの Host 要素の内側でこのようにエレメントを入れ子にすれば達成できる: <Host name="localhost" ...> ... <Valve className="org.apache.catalina.authenticator.SingleSignOn" debug="0"/> ... </Host> Single Sign On 機能は次の規則にしたがって動作する: この仮想ホストのすべての web アプリケーションは同じ Realm を共有しなければならない。 事実上，これが意味することは，この Host 要素 (またはそれを取り囲む Engine 要素) の内側に Realm 要素を入れ子にすることはよいが， 関係する web アプリケーションの一つに対する Context 要素の 内側に [Realm 要素を] 入れ子にはできないということである。 ユーザががこの仮想ホストの web アプリケーションのプロテクトされていないリソースだけをアクセス する限りは，認証は求められない。 ユーザがこの仮想ホストのどの web アプリケーションであれ プロテクトされたリソースをアクセスした途端， そのときアクセスされている web アプリケーションで定義された login メソッドを使った認証が求められる。 いったん認証されると，関連するすべての web アプリケーション にわたって，このユーザのロールがアクセス制御のために利用される。 個々のアプリケーションはユーザに認証を求めない。 ユーザが一つの web アプリケーションから (例えば，form ベースのログインを使ったときは， 対応するセッションを無効にすることによって) ログアウトした途端， すべての web アプリケーションでユーザのセッションが無効化される。 どのアプリケーションであれプロテクトされたリソースへユーザが引き続きアクセスしようとすると， 再び認証が求められる。 Single Sign On 機能は，HTTP クッキーを使って， 各リクエストを保存されたユーザ識別とひもづけるトークンを伝達する。 したがって，クッキーをサポートするクライアント環境でだけ利用できる。

User Web Applications

多くの web サーバは，チルド文字 ("~") とユーザ名で始まるリクエスト URI を自動的に サーバ上のそのユーザのホーム・ディレクトリ内のあるディレクトリ (普通は public_html) へマップできる。 (妥当なユーザを識別するために /etc/passwd を使う Unix システムでは) 君は同じことを，特別な Listener 要素をこのように使うことにより，Catalina で達成できる: <Host name="localhost" ...> ... <Listener className="org.apache.catalina.startup.UserConfig" directoryName="public_html" userClass="org.apache.catalina.startup.PasswdUserDatabase"/> ... </Host> /etc/passwd が使われないサーバでは， 君は Catalina に，ある指定した基準ディレクトリ (この例では c:\Homes) にあるすべてのディレクトリを，この指示の目的では "user home" と見なすように要求できる。 <Host name="localhost" ...> ... <Listener className="org.apache.catalina.startup.UserConfig" directoryName="public_html" homeBase="c:\Homes" userClass="org.apache.catalina.startup.HomesUserDatabase"/> ... </Host> craigmcc という名前のユーザに対して ユーザ・ホーム・ディレクトリをセットアップした場合， そのコンテンツはクライアント・ブラウザからは次のような URL へリクエストをすれば見ることができる: http://www.mycompany.com:8080/~craigmcc この機能を首尾良く使うには次の事項を考慮する必要がある: 各ユーザ web アプリケーションは，君がこの Host 用に設定した DefaultContext 要素による特性でデプロイされる。 この listener インスタンスを複数個含めることは合法的である。 ただし，これが有用なのは，君が複数の "homeBase" ディレクトリを設定したい場合だけである。 Catalina を実行するオペレーティング・システムのユーザ名は， 各ユーザの web アプリケーション・ディレクトリとそのコンテンツすべてに対して read アクセスを持っていなければならない。