Tomcat - server.xml

このリソースを登録するJNDI名を記述します。
実際に登録されるJNDI名は、java:comp/env + name となります。
例えば、UserDataBase という名前の環境変数を利用する場合には
プログラム内にはlookup("java:comp/env/UserDataBase")と記述します。

scope

リソースマネージャから得たこのリソースの接続を共有するかどうかを指定します。
Shareable(デフォルト) または Unshareable を記述します。

type

このリソースのクラス名を完全限定名で指定します。

ResourceParams

リソースに渡すパラメータを記述します。
Resource要素とペアで使用して下さい。

Engine

親要素 : Service
サーブレットエンジンコンテナの情報を記述します。
エンジンコンテナは、一つもしくはそれ以上のコネクタからのリクエストを受け取り
レスポンスを返します。

className

使用するエンジンクラスを指定します。
このクラスは org.apache.catalina.Engine インターフェイスを実装している必要があります。
省略すると、org.apache.catalina.core.StandardEngine がデフォルトで使用されます。

defaultHost

デフォルトのホスト名を記述します。
これは、このエンジンの子に存在するHost要素のname属性に対応させる必要があります。

jvmRoute

ロード・バランシング(負荷分散)機能を利用するときに使います。
この機能はJK/JK2インターフェイスを使ってApacheと連携を取っている状況下で働きます。
詳細は不明ですが、おそらく異なるEngineに異なるjvmRoute属性を記述すれば良いはずです。
jvmRoute属性文字列は識別子となり、セッションIDのサフィックス等にも使われます。

name

このエンジンに付ける名前を記述します。

debug

この項目は org.apache.catalina.core.StandardEngine のエンジンクラスを使用時に有効です。
Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

子要素 : Host / Logger / Realm / DefaultContext
一つ以上のHost要素が必須となります。

Logger

親要素 : Engine / Host / Valve / Context
ログ出力に関する情報を記述する要素です。

className

使用するログ出力クラスを指定します。
このクラスは org.apache.catalina.Logger インターフェイスを実装している必要があります。
org.apache.catalina.logger.FileLogger 等のクラスが提供されています。

verbosity

ログ出力レベルを選択します。
デフォルトは1です。値を大きくすると、より詳細なメッセージがログ出力されます。

File Logger

以下、org.apache.catalina.logger.FileLogger を使用した場合に使用できる属性を説明します。

directory

ログを出力するディレクトリを記述します。
相対パスで記述すると、その基準パスは $CATALINA_HOME になります。
デフォルトは $CATALINA_HOME/logs です。

prefix

出力ファイル名のプレフィックス(先頭に付く文字列)を記述します。
デフォルトでは catalina. になります。

suffix

出力ファイル名のサフィックス(最後に付く文字列)を記述します。
デフォルトでは .log になります。

timestamp

true にすると、全てのログ出力に日付情報を付加します。デフォルトは false です。

Host

親要素 : Engine
バーチャルホストを定義します。

appBase

このバーチャルホストの基準ディレクトリを指定します。

autoDeploy

このホストのWebアプリケーションがオートデプロイされるかどうかを指定します。
デフォルトは true です。

className

使用するホストのクラスを指定します。
このクラスは org.apache.catalina.Host インターフェイスを実装している必要があります。
省略すると、org.apache.catalina.core.StandardHost がデフォルトで使用されます。

name

このバーチャルホストが利用されるネットワーク名を指定します。
ネットワーク名とはDNSサーバに登録されているものを指定するか localhost と記述する必要があります。

StandardHost

以下、org.apache.catalina.core.StandardHost を使用した場合に使用できる属性を説明します。

debug

Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

deployXML

オートデプロイ時にXMLファイルの読み込みを行うかどうかを指定します。
デフォルトはtrueです。falseにすると
appBase ディレクトリ以外にあるwarファイルの手動インストールも不可能になります。

つまり、appBase ディレクトリ(とそのサブディレクトリ)以外にあるファイルが
一切使えないようになるので、セキュリティの面で安全性が高まります。

errorReportValveClass

このホストでエラーが発生した場合、それを画面に出力する為のクラスを指定します。
このクラスは org.apache.catalina.Valve インターフェイスを実装している必要があります。
デフォルトでは org.apache.catalina.valves.ErrorReportValve が使用されます。

liveDeploy

Tomcat起動中にデプロイ作業を行うかどうかを指定します。
true(デフォルト)にすると、Tomcat起動中 appBase ディレクトリにWARファイルを配置すると
自動的にデプロイされます。

unpackWARs

appBase ディレクトリ上に配置したWARファイルを
このディレクトリ上に展開(解凍)するかどうかを指定します。
false にすると、配置されたWARファイルはそのままの形で実行されます。

workDir

このホストが一時的に利用するディレクトリを指定します。
コンテキスト毎に指定する場合は、Context要素のworkDir属性を記述すれば
この値は上書きされます。
省略すると、$CATALINA_HOME/work がデフォルトで使用されます。

子要素 : Logger / Realm / Valve / Context

オートデプロイ

Catalinaを起動した際、autoDeploy属性がtrueならばオートデプロイ機能が働きます。
以下の3項目がその処理内容です。
これらはホスト毎のappBase属性を基準として行なわれます。

XMLファイルの読み込み
deployXML属性がtrue(デフォルト)の場合に以下の処理が働きます。

appBase 上にある全てのXMLファイルが読み込まれます。
このファイルにはContext要素(とその子要素)を記述できます。
こうやって conf/server.xml から分離して別ファイルに記述することで
各コンテキストを一時的に利用可能／不可能にする事が簡単に行えるようになります。
WARファイルの読み込みと展開
appBase 上にある全てのWARファイルを
そのファイル名から拡張子.warを取り除いた名前のコンテキストとして認識します。
さらに、unpackWARs属性がtrueの場合は同名のディレクトリを作成してWARファイルを展開します。
ただし、既に同名のディレクトリが存在する場合には展開はされません。
サブディレクトリの自動コンテキスト設定
appBase上にある全てのサブディレクトリ(WARファイルを解凍したものを除く)は、
それに関するContext要素が自動的に作成されます。
ただし、これらのサブディレクトリ内に WEB-INF/web.xml ファイルが存在しているものに限ります。
これらのコンテキストには DefaultContext の属性が適用されます。
コンテキストパスは /dir_name という形式になりますが、
唯一例外として ROOT という名前のディレクトリはこのホストのルートコンテキストとして設定されます。

Context

親要素 : Host
Webアプリケーション単位のコンテキスト設定を記述します。
オートデプロイを利用することにより、この要素は別ファイルに分けることが出来ます。
コンテキスト(アプリケーション)毎に設定ファイルを用意することができるので便利です。

className

使用するコンテキストクラスを指定します。
このクラスは org.apache.catalina.Context インターフェイスを実装している必要があります。
省略すると、org.apache.catalina.core.StandardContext がデフォルトで使用されます。

cookies

アプリケーションがセッションを識別するのに
クッキーを使用するかどうかを指定します。デフォルトでは true です。
false にすると、URLにセッションIDを埋め込む形でしかセッションを利用できなくなります。
これは携帯サイトなどクッキーを利用できないブラウザでは必要な手段となります。

crossContext

このコンテキストを他のコンテキストから参照できるかどうかを指定します。
true にすると、他のコンテキストから ServletContext.getContext(String) メソッドを
呼び出すことによって ServletContext オブジェクトを取得することが出来ます。

docBase

このコンテキストのルートディレクトリを指定します。
WARファイルを指定することも出来ます。

override

true にすると、各属性は DefaultContext要素の属性を(もしあれば)上書きします。
false(デフォルト)では、DefaultContext要素の属性が(もしあれば)そのまま使われます。

privileged

このWebアプリケーションに特権を与えるかどうかを指定します。
true にすると、コンテナ・サーブレットを使うことが可能になります。
コンテナ・サーブレットとは、org.apache.catalina.ContainerServletインターフェイスを
実装したサーブレットの事を指します。

path

このコンテキストに対応するURIを記述します。

reloadable

true にすると、Catalina は /WEB-INF/classes/ と /WEB-INF/lib/ に存在するファイルの内容を
随時チェックし、変更があった場合にはそれをリロードします。
この機能はサーブレットのデバッグ時には大変便利ですが、その為にかなりのオーバーヘッドを要します。
実運用段階では、この項目は必ず false にすることを推奨します。

wrapperClass

使用するラッパークラスを指定します。
このクラスは org.apache.catalina.Wrapper インターフェイスを実装している必要があります。
省略すると、org.apache.catalina.core.StandardWrapper がデフォルトで使用されます。

StandardContext

以下、org.apache.catalina.core.StandardContext を使用した場合に使用できる属性を説明します。

debug

Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

swallowOutput

true にすると、標準出力およびエラー出力(System.out,err)への出力が全て
Logger に渡されます。デフォルトは false です。

useNaming

true(デフォルト)にすると、CatalinaはJNDIのInitialContextを利用可能にします。

workDir

このコンテキストが一時的に利用するディレクトリを指定します。
省略すると、$CATALINA_HOME/work がデフォルトで使用されます。

子要素 : Loader / Logger / Manager / Realm / Resources / Parameter / Environment / Resource / ResourceParams / ResourceLink

Parameter

このコンテキストで利用できるパラメータを宣言します。
これは web.xml 内の context-param要素で宣言するのと同一の効果があります。
アプリケーション内でパラメータを取得するには、ServletContext.getInitParameter()を使用します。

description

このパラメータに関する情報を記述します。
これはサーバに全く関与しない、あくまでこのファイルを読む他の人間に対する記述です。

name

このパラメータの名前を記述します。

override

これと同じ名前のパラメータが web.xml 内で見つかったとき、
その値を上書きするかどうかを指定します。デフォルトは true です。

value

このパラメータの値を記述します。

ResourceLink

グローバルリソースをアクセスする為の記述をします。

global

グローバルリソース名

name

リソースをアクセスする際のJNDI名。これは java:comp/env/ からの相対名になります。

type

リソースのタイプ(クラス)名

DefaultContext

親要素 : Engine / Host

Manager

親要素 : Context
HTTPセッションを生成、確保する為のセッションマネージャの設定をします。

className

使用するコンテキストクラスを指定します。
このクラスは org.apache.catalina.Manager インターフェイスを実装している必要があります。
省略すると、org.apache.catalina.session.StandardManager がデフォルトで使用されます。

distributable

アプリケーションが使用するセッションオブジェクトが
全て直列化可能なことを示すときにtrueにします。
デフォルトはfalseです。
trueのとき、直列化不可能(Serializable)なオブジェクトを
セッションに格納しようとすると IllegalArgumentException が発生します。

StandardManager

以下、org.apache.catalina.session.StandardManager を使用した場合に使用できる属性を説明します。

algorithm

セッション識別子を計算するアルゴリズムを指定します。
この値は java.security.MessageDigest クラスでサポートされている必要があります。
デフォルトは MD5 です。

checkInterval

セッションの有効期限をチェックする間隔を秒単位で指定します。
デフォルトは60秒です。
この為、例えばセッションタイムアウト値を3分に設定していても
実際にセッションが切断されるのは3〜4分の間になります。

debug

Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

entropy

セッション識別子生成時に用いられる乱数生成メソッドに渡す文字列を指定します。
デフォルトでもある程度有用なセッション識別子は生成されますが、
セキュリティが重要な環境下で使用する場合には
ここで明示的に何らかの文字列を指定する方がより強固な(他人に利用されにくい)識別子が生成されます。

maxActiveSessions

マネージャによって生成されるアクティブ・セッションの最大数を制限します。
-1(デフォルト)にすると、セッションは無制限に生成されます。

pathname

アプリケーション再起動時に保存されるセッション状態を記述したファイルがあります。
デフォルトでは workDir/SESSIONS.ser ですが、ここではそのファイル名およびパスを指定する事が出来ます。

randomClass

使用する乱数生成クラスを指定します。
このクラスは java.util.Random インターフェイスを実装している必要があります。
省略すると、java.security.SecureRancom がデフォルトで使用されます。

PersistentManager

以下、org.apache.catalina.session.PersistentManager を使用した場合に使用できる属性を説明します。
このマネージャを利用すると、セッションのスワップ管理を制御することができます。
※ このマネージャはまだテスト段階です

概要を説明します。
基本的に作成されたセッションはメモリ内に保持されますが、
数が多くなってくるとメモリ使用量も圧迫されます。

そこで、一定期間使われていないセッションをストア(ファイルやDBレコード)に保管して
メモリから破棄する処理を行います。これをスワップアウトといいます。
また、オブジェクトの破棄は行わずストアへの保管だけを行うことをバックアップといいます。

ストアに保管する際にはJavaのオブジェクトを直列化するので
セッションに利用するオブジェクトはSerializableインターフェイスを実装する必要があります。
具体的には、

session.setAttribute(name, value);

としたときに、valueオブジェクトがSerializableインターフェイスを実装していないと
例外が発生します。

このマネージャを利用すると、以下の処理が checkInterval 秒ごとに行われます。

一定時間使われていないセッションを破棄します。
このときのタイムアウト値はweb.xmlのsession-timeout要素で指定されます。

maxIdleSwap秒以上使われていないセッションをスワップアウトします。

maxActiveSessions個を超えたセッションのうち、
minIdleSwap秒以上使われていないものをスワップアウトします。

maxIdleBackup秒以上使われていないセッションをバックアップします。

以下、PersistentManager要素に指定できる属性を列挙します。

algorithm

checkInterval

debug

Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

entropy

randomClass

saveOnRestart

これをtrue(デフォルト)にすると、全ての有効なセッションは
Catalinaサーバ終了時にスワップアウトされ保管されます。
保管された全てのセッションは、次回のサーバスタート時にメモリにロードされます。
つまり、サーバを再起動してもセッションは無効になりません。
これはアプリケーションの停止／開始や再起動時にも同じように働きます。

maxActiveSessions

メモリ内に保持できるセッションの最大数を制限します。
-1(デフォルト)にすると、セッションは無制限に生成されます。
この値を超えるセッションを生成しようとするとIllegalStateExceptionが発生します。
このときに独自の画面を表示させたいなら、web.xmlのerror-page要素を記述して下さい。

minIdleSwap

セッションは最大数maxActiveSessionsを超えると
超えた分のセッションがスワップアウトされますが、
少なくともこの秒数を超える期間使われない限りはスワップアウトの対象になりません。
スワップアウトされたセッションに再度接続要求が来ると、
Catalinaはセッションをスワップインして利用することになります。

maxIdleSwap

セッションが最後に使われてからスワップアウトされるまでの時間を秒単位で指定します。
minIdleSwapがこの値より大きい場合、この値はminIdleSwapで上書きされます。
-1にすると全てのセッションはスワップアウトされません。

maxIdleBackup

セッションが最後に使われてからバックアップされるまでの時間を秒単位で指定します。
バックアップはスワップアウトと似ていますが、こちらはメモリからセッションを削除しません。
-1にすると、セッションはバックアップされません。

処理内容は似ていますが、使用目的はスワップアウトとは異なるはずです。
スワップアウトはメモリ使用量を抑える目的で使われるのに対し、
バックアップはセッションを記憶領域に保管してログのような目的で使われるのだと思います。

スワップアウトされたセッションはストアと呼ばれる場所に保管されます。
ストアの指定は、Manager要素の子要素Storeに必ず指定しなければなりません。

File Based Store

ファイルベースのストアを使う場合は、以下の属性をStore要素に付加します。

className

org.apache.catalina.session.FileStore を記述します。

checkInterval

ストアに保管されたセッションが切断されたかどうかのチェックを行う間隔を
秒単位で指定します(デフォルトは60秒)。

debug

Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

directory

セッションを保管するディレクトリを指定します。
相対パスで記述した場合、その基準ディレクトリはworkディレクトリになります。

JDBC Based Store

JDBC経由でデータベースをストアとして使う場合は、以下の属性をStore要素に付加します。

className

org.apache.catalina.session.JDBCStore を記述します。

checkInterval

ストアに保管されたセッションが切断されたかどうかのチェックを行う間隔を
秒単位で指定します(デフォルトは60秒)。

debug

Logger に渡すデバッグレベルを指定します。
デフォルトは0です。値を大きくすると、より詳細なメッセージがログ出力されます。

driverName

使用するJDBCドライバのクラス名を記述します。

connectionURL

データベースにJDBC接続するためのURLを記述します。

sessionTable

ストアに利用するデータベースのテーブル名を記述します。

sessionIdCol

「セッションID」を書き出すデータベースのカラム名を記述します。
DBのカラムは可変文字列型にします。例： VARCHAR(100) NOT NULL PRIMARY KEY

sessionAppCol

「セッションアプリケーション名」を書き出すデータベースのカラム名を記述します。
これは「エンジン名/ホスト名/アプリケーション名」の形式になります。
DBのカラムは可変文字列型にします。例： VARCHAR(255)

sessionDataCol

「セッションデータ」を書き出すデータベースのカラム名を記述します。
DBのカラムはBLOB型にします。例：MEDIUMBLOB

sessionLastAccessedCol

「最終アクセス日付」を書き出すデータベースのカラム名を記述します。
DBのカラムは数値型(64bit)にします。例： BIGINT NOT NULL

sessionMaxInactiveCol

「セッションタイムアウト値(秒)」を書き出すデータベースのカラム名を記述します。
「現在日付 > 最終アクセス日付 + タイムアウト値」になった時点で
このセッションは切断(DBからも削除)されます。
DBのカラムは数値型(32bit)にします。例： INT NOT NULL

sessionValidCol

「セッション有効フラグ」を書き出すデータベースのカラム名を記述します。
DBのカラムは固定文字列型(1文字)にします。例： CHAR(1) NOT NULL

ストアに利用するDBテーブルは、予め作成しておく必要があります。
例を以下に挙げます。MySQLでの動作を確認しました。

create table tomcat_sessions (
  session_id     varchar(100) not null primary key,
  valid_session  char(1) not null,
  max_inactive   int not null,
  last_access    bigint not null,
  app_name       varchar(255),
  session_data   mediumblob,
  KEY kapp_name(app_name)
);

ストアからセッションを削除したい場合、全ての値を-1、saveOnRestartをfalseに設定して
サーバ(又はアプリケーション)を再起動して下さい。

Realm

親要素 : Engine / Host / Context
データベースに関する情報を記述する要素です。

className

使用するクラスを指定します。
このクラスは org.apache.catalina.Realm インターフェイスを実装している必要があります。

提供されているクラス群

org.apache.catalina.realm.JDBCRealm

org.apache.catalina.realm.DataSourceRealm

org.apache.catalina.realm.JNDIRealm

org.apache.catalina.realm.MemoryRealm

Resources

様々なリソース情報を定義する要素です。

Valve

様々なコンポーネントを定義する要素です。

親要素 : Engine / Host / Context

Access Log Valve

アクセスログのコンポーネントに関する記述です。

className

使用するクラスを指定します。
org.apache.catalina.valves.AccessLogValve を使用して下さい。

directory

ログを出力するディレクトリを指定します。
デフォルトでは CATALINA_HOME/logs になっています。

pattern

ログ出力フォーマットを定義します。
common / combined と記述すると、標準で用意されているフォーマットが用いられます。
独自のフォーマットを利用したい場合は、以下に記述するフォーマット文字列を組み合わせて記述します。

%a -
リモートIPアドレス

%A -
ローカルIPアドレス

%b -
サーブレットが出力したバイト数(HTTPヘッダを除く)

%B -
不明

%h -
リモートホスト名。
ただし、resolveHosts が false の場合にはIPアドレスを返す(%aと同じ)

%H -
リクエストを要求したプロトコル(HTTP/1.1等)

%l -
常に - を返す(利用法は不明)

%m -
リクエストメソッド(GET,POST等)

%p -
このリクエストを受け取ったローカルのポート番号

%q -
クエリー文字列

%r -
リクエストメソッド + リクエストURI

%s -
レスポンスが返したステータスコード

%S -
ユーザのセッションID

%t -
現在時刻

%u -
リモートユーザ名

%U -
リクエストURI

%v -
ローカルサーバ名

Remote Address Filter

IPアドレスによるフィルタリングを掛けるコンポーネントです。

className

使用するクラスを指定します。
org.apache.catalina.valves.RemoteAddrValve を記述して下さい。

allow

許可するIPアドレスを記述します。複数指定する場合はカンマで区切って下さい。
「192.168.1.*」などのワイルドカード形式が利用できます。
この属性を記述した場合、指定したIPアドレスからのアクセスのみが許可されますが
記述しない場合はdenyで指定した以外の全てのIPアドレスからのアクセスが許可されます。

deny

拒否するIPアドレスを記述します。複数指定する場合はカンマで区切って下さい。
ワイルドカード形式が利用できます。

allow と deny の両方に当てはまるIPアドレスは「拒否」されます。
やや複雑なので解説します。

allowとdeny両方を指定した場合

allowで指定してあり、かつdenyで指定していないアドレスのみが許可されます。

allowのみ指定した場合

allowで指定したアドレスのみが許可されます。

denyのみ指定した場合

denyで指定した以外の全てのアドレスが許可されます。

両方とも指定しなかった場合

全てのアドレスが許可されます。
…フィルタリングを掛けないのと一緒です(笑)。