ホストコンテナ

目次

はじめに

Host 要素は、Tomcat が実行されている特定のサーバーと、サーバーのネットワーク名（例: "www.mycompany.com"）の関連付けである仮想ホストを表します。クライアントがネットワーク名を使用してTomcatサーバーに接続できるようにするには、この名前が所属するインターネットドメインを管理するドメインネームサービス (DNS) サーバーに登録されている必要があります。詳細については、ネットワーク管理者にお問い合わせください。

多くの場合、システム管理者は、同じ仮想ホストおよびアプリケーションに複数のネットワーク名（例: www.mycompany.com および company.com）を関連付けたいと考えます。これは、後述するホスト名エイリアス機能を使用することで実現できます。

1つ以上のHost要素が、Engine要素内にネストされます。Host要素内には、この仮想ホストに関連付けられたウェブアプリケーション用のContext要素をネストできます。各Engineに関連付けられたHostのうち、正確に1つは、そのEngineのdefaultHost属性と一致する名前を持つ必要があります。

クライアントは通常、接続したいサーバーを識別するためにホスト名を使用します。このホスト名はHTTPリクエストヘッダーにも含まれます。TomcatはHTTPヘッダーからホスト名を抽出し、一致する名前を持つHostを探します。一致が見つからない場合、リクエストはデフォルトホストにルーティングされます。デフォルトホストの名前はDNS名と一致する必要はありません（一致しても構いません）。DNS名がHost要素の名前と一致しないリクエストはすべてデフォルトホストにルーティングされるためです。

以下の説明では、ほとんどの相対パスの解決基準となるベースディレクトリを指すために変数名 $CATALINA_BASE を使用しています。CATALINA_BASE ディレクトリを設定してTomcatを複数インスタンスで構成していない場合、$CATALINA_BASE はTomcatをインストールしたディレクトリである $CATALINA_HOME の値に設定されます。

属性

共通属性

Host のすべての実装は、次の属性をサポートしています。

属性説明
appBase

この仮想ホストのアプリケーションベースディレクトリです。これは、この仮想ホストにデプロイされるウェブアプリケーションを含む可能性のあるディレクトリのパス名です。絶対パス名または$CATALINA_BASEディレクトリに対する相対パス名を指定できます。ウェブアプリケーションの自動認識とデプロイメントの詳細については、アプリケーションの自動デプロイを参照してください。指定しない場合、デフォルトのwebappsが使用されます。

xmlBase

この仮想ホストのXMLベースディレクトリです。これは、この仮想ホストにデプロイされるコンテキストXML記述子を含む可能性のあるディレクトリのパス名です。このディレクトリの絶対パス名、または$CATALINA_BASEディレクトリに対する相対パス名を指定できます。ウェブアプリケーションの自動認識とデプロイメントの詳細については、アプリケーションの自動デプロイを参照してください。指定しない場合、デフォルトのconf/<engine_name>/<host_name>が使用されます。

createDirs

trueに設定すると、Tomcat は起動フェーズ中にappBaseおよびxmlBase属性で定義されたディレクトリを作成しようとします。デフォルト値はtrueです。trueに設定され、ディレクトリの作成に失敗した場合、エラーメッセージが出力されますが、起動シーケンスは停止しません。

autoDeploy

このフラグ値は、Tomcat の実行中に新規または更新されたウェブアプリケーションが定期的にチェックされるかどうかを示します。trueの場合、Tomcat はappBaseおよびxmlBaseディレクトリを定期的にチェックし、見つかった新しいウェブアプリケーションまたはコンテキストXML記述子をデプロイします。更新されたウェブアプリケーションまたはコンテキストXML記述子は、ウェブアプリケーションのリロードをトリガーします。デフォルトはtrueです。アプリケーションの自動デプロイで詳細を参照してください。

backgroundProcessorDelay

この値は、このホストとその子コンテナ（すべてのコンテキストを含む）で backgroundProcess メソッドが呼び出される間の遅延（秒単位）を表します。子コンテナの遅延値が負でない場合（つまり、それらが独自の処理スレッドを使用している場合）、それらは呼び出されません。これを正の値に設定すると、スレッドが生成されます。指定された時間待機した後、スレッドはこのホストとそのすべての子コンテナで backgroundProcess メソッドを呼び出します。ホストは、ライブウェブアプリケーションのデプロイ関連タスクを実行するためにバックグラウンド処理を使用します。指定しない場合、この属性のデフォルト値は -1 であり、ホストが親エンジンのバックグラウンド処理設定に依存することを意味します。

className

使用する実装のJavaクラス名。このクラスはorg.apache.catalina.Hostインターフェースを実装する必要があります。指定しない場合、標準値（下記参照）が使用されます。

deployIgnore

autoDeploy と deployOnStartup が設定されている場合に無視するパスを定義する正規表現。これにより、例えば、設定をバージョン管理システムに保持し、appBase 内にある.svn、.git、またはその他の設定管理システムのフォルダをデプロイしないようにすることができます。

この正規表現はappBaseに対する相対パスです。また、アンカーされており、ファイル/ディレクトリ名全体に対してマッチが行われます。したがって、fooはfooという名前のファイルまたはディレクトリのみにマッチし、foo.war、foobar、またはmyfooappにはマッチしません。「foo」を含むものすべてにマッチさせるには、.*foo.*を使用できます。

アプリケーションの自動デプロイで詳細を参照してください。

deployOnStartup

このフラグ値は、Tomcat 起動時にこのホストのウェブアプリケーションが自動的にデプロイされるかどうかを示します。デフォルトはtrueです。アプリケーションの自動デプロイで詳細を参照してください。

failCtxIfServletStartFails

子コンテキストのロードオンスタートアップが0以上のサーブレットが起動に失敗した場合、その子コンテキストの起動を失敗させるには、trueに設定します。

各子コンテキストはこの属性をオーバーライドできます。

指定しない場合、デフォルト値のfalseが使用されます。

legacyAppBase

この仮想ホストのレガシーアプリケーションベースディレクトリです。これは、デプロイ前にJakarta EEに変換されるJava EEウェブアプリケーションを含む可能性のあるディレクトリのパス名です。このディレクトリに配置されたWARファイルまたはディレクトリとしてパッケージ化されたJava EEアプリケーションは、Apache Tomcat Migration Tool for Jakarta EEを使用してJakarta EEに変換されます。変換はデフォルト設定を使用して実行されます。結果のWARまたはディレクトリは、この仮想ホスト用に構成されたappBaseに配置されます。

アプリケーションの移行にデフォルト設定が適切でない場合、完全な移行オプションを手動で実行することでアクセスできます。この目的のために、$CATALINA_HOME/binディレクトリにmigrate.[sh|bat]スクリプトが提供されています。

絶対パス名、または$CATALINA_BASEディレクトリに対する相対パス名を指定できます。指定しない場合、デフォルトのwebapps-javaeeが使用されます。

name

通常、ドメインネームサービス (DNS) サーバーに登録されている、この仮想ホストのネットワーク名です。ホスト名を指定する際に使用される大文字・小文字に関わらず、Tomcat は内部的に小文字に変換します。Engine内にネストされたHostのうち、1つは必ずそのEngineのdefaultHost設定と一致する名前を持つ必要があります。同じ仮想ホストに複数のネットワーク名を割り当てる方法については、ホスト名エイリアスを参照してください。この名前にはワイルドカードを含めることはできません。これはAliasでのみ有効です。

startStopThreads

このHostが子Context要素を並行して起動するために使用するスレッド数。自動デプロイメントが使用されている場合、同じスレッドプールが新しいContextsのデプロイにも使用されます。スレッドプールはServerレベルで共有されるため、複数のHostがこの設定を指定した場合、最大値のみが適用され、特殊な値1を除いてすべてに使用されます。指定しない場合、デフォルト値の1が使用されます。1スレッドが使用される場合、ExecutorServiceを使用する代わりに現在のスレッドが使用されます。

undeployOldVersions

このフラグは、Tomcat が自動デプロイプロセスの一部として、並行デプロイを使用してデプロイされた古い未使用のウェブアプリケーションをチェックし、見つかった場合は削除するかどうかを決定します。このフラグは、autoDeployがtrueの場合にのみ適用されます。指定しない場合、デフォルト値のfalseが使用されます。

標準実装

Host の標準実装は org.apache.catalina.core.StandardHost です。これは、次の追加属性（上記の共通属性に加えて）をサポートしています。

属性説明
copyXML

アプリケーション内に埋め込まれたコンテキストXML記述子（/META-INF/context.xmlに配置）を、アプリケーションがデプロイされる際にxmlBaseにコピーしたい場合は、trueに設定します。それ以降の起動では、アプリケーション内に埋め込まれた記述子よりも、コピーされたコンテキストXML記述子が優先的に使用されます。たとえアプリケーション内に埋め込まれた記述子の方が新しい場合でも同様です。デフォルトはfalseです。なお、deployXMLがfalseの場合、この属性は効果がありません。

deployXML

アプリケーション内に埋め込まれたコンテキストXML記述子（/META-INF/context.xmlに配置）の解析を無効にしたい場合は、falseに設定します。セキュリティを重視する環境では、アプリケーションがコンテナの構成とやり取りするのを防ぐために、これをfalseに設定する必要があります。その場合、管理者は外部のコンテキスト構成ファイルを提供し、xmlBase属性で定義された場所に配置する責任があります。このフラグがfalseで、記述子が/META-INF/context.xmlにあり、xmlBaseに記述子がない場合、記述子に安全なデプロイメントに必要な構成（RemoteAddrValveなど）が含まれていて無視すべきでない場合、コンテキストの起動は失敗します。デフォルトはtrueです。

errorReportValveClass

このホストによって使用されるエラーレポートバルブの Java クラス名。このバルブの責任は、エラーレポートを出力することです。このプロパティを設定することで、Tomcat によって生成されるエラーページの表示をカスタマイズできます。このクラスは org.apache.catalina.Valve インターフェースを実装する必要があります。指定されていない場合、デフォルトで org.apache.catalina.valves.ErrorReportValve の値が使用されます。空文字列に設定すると、エラーレポートは無効になります。

unpackWARs

appBaseディレクトリにウェブアプリケーションアーカイブ（WAR）ファイルとして配置されたウェブアプリケーションを、対応するディスクディレクトリ構造に展開したい場合はtrueに設定し、WARファイルから直接ウェブアプリケーションを実行したい場合はfalseに設定します。デフォルトはtrueです。アプリケーションの自動デプロイで詳細を参照してください。

注: Tomcat が WAR ファイルを展開すると、展開されたディレクトリ構造にファイル (/META-INF/war-tracking) が追加され、Tomcat が実行されていない間に WAR ファイルの変更を検出するために使用されます。このような変更があると、Tomcat の次回の起動時に展開されたディレクトリが削除され、更新された WAR ファイルがデプロイされます。

注: このオプションをfalseに設定して実行すると、パフォーマンスが低下します。大幅なパフォーマンス低下を避けるためには、サーブレット3.0+のプラグイン機能のためのクラススキャンが不要になるようにウェブアプリケーションを構成する必要があります。ユーザーは、ExtractingRoot Resourcesの実装も検討することをお勧めします。

workDir

このホストのアプリケーションが使用するスクラッチディレクトリへのパス名。各アプリケーションは、一時的な読み書きのために独自のサブディレクトリを持ちます。Context の workDir を設定すると、Host の workDir 設定は上書きされます。このディレクトリは、サーブレット仕様に記述されているように、jakarta.servlet.context.tempdir という名前のサーブレットコンテキスト属性（java.io.File 型）によってウェブアプリケーション内のサーブレットに表示されます。指定しない場合、$CATALINA_BASE/work の下の適切なディレクトリが提供されます。

ネストされたコンポーネント

このHost要素内に、この仮想ホストに関連付けられた異なるウェブアプリケーションを表す、1つ以上のContext要素をネストできます。

以下のユーティリティコンポーネントのインスタンスを、対応する要素をHost要素内にネストすることで、最大1つまでネストできます。

  • Realm - このホスト内にネストされたすべてのContexts（下位レベルのRealm設定によって上書きされない限り）で、ユーザーのデータベースとそれに関連付けられたロールを共有できるようにするレルムを設定します。

特別な機能

ロギング

ホストはorg.apache.catalina.core.ContainerBase.[engine_name].[host_name]ログカテゴリに関連付けられています。角括弧は名前の一部であり、省略しないでください。

アクセスログ

ウェブサーバーを実行すると、通常、出力ファイルの一つとしてアクセスログが生成され、標準形式でサーバーによって処理された各リクエストごとに1行の情報が生成されます。Catalinaには、ウェブサーバーによって作成されるのと同じ標準形式、または任意の数のカスタム形式でアクセスログを作成できるオプションのValve実装が含まれています。

Engine、Host、またはContext要素によって処理されるすべてのリクエストに対して、次のようにValve要素をネストすることで、Catalinaにアクセスログを作成するように要求できます。

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.valves.AccessLogValve"
         prefix="localhost_access_log" suffix=".txt"
         pattern="common"/>
  ...
</Host>

サポートされている構成属性の詳細については、アクセスロギングバルブを参照してください。

アプリケーションの自動デプロイ

標準の Host 実装をデフォルト設定で使用している場合、appBase 内のアプリケーションまたはconfigBase 内のコンテキストファイルは、Tomcat 起動時に自動的にデプロイされ（deployOnStartup プロパティはデフォルトで true）、Tomcat 実行中に変更が検出されると、適切にリロードまたは再デプロイされます（autoDeploy 属性もデフォルトで true です）。

deployOnStartup と autoDeploy は全く同じコードの実行をトリガーするため、動作は非常に似ています。しかし、一つ重要な違いがあります。Tomcat が起動するとき、どのファイルが同じで、どのファイルが変更され、どのファイルが新しいかという知識がありません。そのため、すべてのファイルを新しいものとして扱います。Tomcat が実行している間は、変更されていないファイル、変更されたファイル、新しいファイルを区別できます。これにより、Tomcat が実行中にファイルが変更された場合と、Tomcat が停止中にファイルが変更された場合とで、動作にいくつかの違いが生じます。

自動デプロイメントを使用する場合、HostのappBaseおよび/またはconfigBaseに存在する関連ファイル（ウェブアプリケーションはcontext.xmlファイル、WAR、およびディレクトリを持つ場合があります）は、予期される命名規則に準拠している必要があります。簡単に言えば、これは同じウェブアプリケーションのファイルが同じベース名を共有する必要があることを意味します。

自動デプロイプロセスは、次の検索順序を使用して、新規および/または変更されたウェブアプリケーションを識別します。

  1. ホストのconfigBaseに配置されたcontext.xmlファイルを持つウェブアプリケーション。
  2. ホストのappBaseに配置されたWARファイルを持つウェブアプリケーションで、context.xmlファイルのスキャン中にまだ識別されていないもの。
  3. ホストのappBaseに配置されたディレクトリを持つウェブアプリケーションで、context.xmlおよび/またはWARファイルのスキャン中にまだ識別されていないもの。

autoDeployがtrueの場合、自動デプロイプロセスは、デプロイされたウェブアプリケーションの変更を監視します。何が変更されたかによって、ウェブアプリケーションは再デプロイまたはリロードされます。再デプロイには新しいウェブアプリケーションの作成が含まれ、標準のセッションマネージャーを使用している場合、ユーザーセッションは保持されません。リロードは既存のウェブアプリケーションを使用しますが、web.xmlを再解析し、クラスを再ロードします。標準のセッションマネージャーを使用している場合、ユーザーセッションは永続化されます。

ユーザーは、context.xmlファイルにWatchedResources要素を追加することで、自動デプロイプロセスがリロードのために監視するファイル（つまり、これらのファイルのいずれかが変更されるとウェブアプリケーションのリロードをトリガーする）に追加できます。詳細については、Contextのドキュメントを参照してください。

自動デプロイメントを使用する場合、XML Context ファイルによって定義された docBase は、appBase ディレクトリの外にあるべきです。そうでない場合、ウェブアプリケーションのデプロイに問題が生じたり、アプリケーションが二重にデプロイされたりする可能性があります。deployIgnore 属性を使用すると、この状況を回避できます。

server.xmlでコンテキストを明示的に定義している場合、おそらく自動アプリケーションデプロイをオフにするか、deployIgnoreを慎重に指定する必要があります。そうしないと、ウェブアプリケーションがそれぞれ二重にデプロイされ、アプリケーションに問題を引き起こす可能性があります。

設定、新規ファイル、変更ファイル、削除ファイルの組み合わせは多数あります。別のページでは、これらのシナリオの多くにおける自動デプロイメントプロセスの期待される動作について説明しています。

ホスト名エイリアス

多くのサーバー環境では、ネットワーク管理者は複数のネットワーク名（ドメインネームサービス (DNS) サーバー内）を設定しており、それらが同じサーバーのIPアドレスに解決されます。通常、このような各ネットワーク名は、conf/server.xml内で別個のHost要素として構成され、それぞれ独自のウェブアプリケーションセットを持っています。

しかし、場合によっては、2つ以上のネットワーク名が同じ仮想ホストに解決され、同じアプリケーションセットを実行することが望ましいことがあります。このシナリオの一般的なユースケースは、企業ウェブサイトであり、ユーザーがwww.mycompany.comまたはcompany.comのいずれかを使用して、全く同じコンテンツとアプリケーションにアクセスできることが望ましい場合です。

これは、Host要素内に1つ以上のAlias要素をネストすることで実現されます。例えば、

<Host name="www.mycompany.com" ...>
  ...
  <Alias>mycompany.com</Alias>
  ...
</Host>

この戦略を効果的に機能させるには、関連するすべてのネットワーク名が、このCatalinaインスタンスを実行している同じコンピューターに解決されるようにDNSサーバーに登録されている必要があります。

エイリアスは、Hostのname属性とは異なり、ワイルドカード形式 (*.domainname) も使用できます。

ライフサイクルリスナー

このHostが起動または停止したときに通知を受け取る必要があるJavaオブジェクトを実装している場合、この要素内にListener要素をネストしてそれを宣言できます。指定するクラス名はorg.apache.catalina.LifecycleListenerインターフェースを実装する必要があり、対応するライフサイクルイベントの発生について通知されます。このようなリスナーの構成は次のようになります。

<Host name="localhost" ...>
  ...
  <Listener className="com.mycompany.mypackage.MyListener" ... >
  ...
</Host>

Listenerは、この要素から設定できる追加プロパティを任意の数だけ持つことができる点に注意してください。属性名は、標準のプロパティメソッド命名パターンを使用して、対応するJavaBeanプロパティ名に一致させられます。

リクエストフィルタ

Catalinaに、周囲のEngine、Host、またはContext要素に向けられたすべての受信リクエストについて、IPアドレスまたはホスト名をチェックするように要求できます。リモートアドレスまたは名前は、java.util.regex正規表現構文を使用して定義された「accept」および/または「deny」フィルターと照合されます。許可されていない場所からのリクエストは、HTTP「Forbidden」エラーで拒否されます。フィルター宣言の例:

<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\.\d+"/>
  ...
</Host>

サポートされている構成オプションの詳細については、リモートアドレスフィルターとリモートホストフィルターを参照してください。

シングルサインオン

多くの環境、特にポータル環境では、特定の仮想ホストにデプロイされた一連のウェブアプリケーションに対して、ユーザーが一度だけ認証されるようにすることが望ましいです。これは、この仮想ホストのHost要素内に次のような要素をネストすることで実現できます。

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
  ...
</Host>

シングルサインオン機能は、以下のルールに従って動作します。

  • この仮想ホスト用に設定されたすべてのウェブアプリケーションは、同じRealmを共有する必要があります。実際には、Realm要素をこのHost要素（または囲むEngine要素）内にネストすることはできますが、関連するウェブアプリケーションのContext要素内にはネストできません。
  • この仮想ホスト上のいずれかのウェブアプリケーションでユーザーが保護されていないリソースにのみアクセスする限り、認証を要求されることはありません。
  • ユーザーがこの仮想ホストに関連付けられた任意のウェブアプリケーション内の保護されたリソースにアクセスするとすぐに、現在アクセスしているウェブアプリケーションに対して定義されたログイン方法を使用して、ユーザーは自身の認証を求められます。
  • 一度認証されると、このユーザーに関連付けられたロールは、関連するすべてのウェブアプリケーションにわたるアクセス制御の決定に利用され、ユーザーは各アプリケーションに個別に認証されることなくアクセスできます。
  • ユーザーがいずれかのウェブアプリケーションからログアウトすると（例えば、フォームベースのログインが使用されている場合に対応するセッションを無効にすることで）、すべてのウェブアプリケーションでのユーザーセッションが無効になります。その後、任意のアプリケーションの保護されたリソースにアクセスしようとすると、ユーザーは再度自分自身を認証する必要があります。
  • シングルサインオン機能は、各リクエストを保存されたユーザーIDと関連付けるトークンを送信するためにHTTPクッキーを利用するため、クッキーをサポートするクライアント環境でのみ利用できます。

ユーザーウェブアプリケーション

多くのウェブサーバーは、チルダ文字 ("~") とユーザー名で始まるリクエストURIを、そのユーザーのサーバー上のホームディレクトリ（通常はpublic_htmlという名前）内のディレクトリに自動的にマッピングできます。Catalinaでも、次のような特別なListener要素を使用することで同じことを実現できます（有効なユーザーを識別するために/etc/passwdファイルを使用するUnixシステムの場合）。

<Host name="localhost" ...>
  ...
  <Listener className="org.apache.catalina.startup.UserConfig"
            directoryName="public_html"
            userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
  ...
</Host>

/etc/passwdが使用されていないサーバーでは、指定されたベースディレクトリ（この例ではc:\Homesなど）で見つかったすべてのディレクトリを、このディレクティブの目的のための「ユーザーホーム」ディレクトリとみなすようにCatalinaに要求できます。

<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

この機能の利用を成功させるには、以下の考慮事項を認識する必要があります。

  • 各ユーザーウェブアプリケーションは、グローバルおよびホストレベルのデフォルトコンテキスト設定によって確立された特性でデプロイされます。
  • このListener要素のインスタンスを複数含めることは合法です。ただし、これは複数の「homeBase」ディレクトリを設定したい場合にのみ役立ちます。
  • Catalinaが実行されるオペレーティングシステムユーザー名は、各ユーザーのウェブアプリケーションディレクトリとそのすべての内容に対して読み取りアクセス権を持っている必要があります。

カスタム context.xml および web.xml

$CATALINA_BASEのconf/context.xmlおよびconf/web.xmlファイルで見つかるデフォルト値を、各仮想ホストで上書きできます。Tomcat はxmlBaseで指定されたディレクトリにcontext.xml.defaultおよびweb.xml.defaultという名前のファイルを探し、それらのファイルをデフォルトのファイルにマージします。