server.xml設定文書について
|
Tomcatの設定ファイルは、XMLで記述されたサーバの設定のためのserver.xmlと、ウェブ・アプリケーション毎に設定するweb.xmlその他が存在する。web.xmlファイルはserver.xmlが置かれているディレクトリにも存在するが、これはデフォルトとして存在するもので、これと相違する個所を各アプリケーションでオーバーライドすればよい。
web.xmlは、サーブレット仕様書にDTD(文書型定義)がきちんと定められているので、比較的理解しやすい。web.xmlのDTDは、本サイトのServlet仕様書の翻訳版の第13章に示されているので、参照されたい。しかしながら、server.xmlについてはMinimalistic User’s Guideが存在する(日本語化されたものもインターネット上に存在する)だけで、非常に分かり難い。ここでは、多少系統的に説明を試みたい。
server.xmlの階層構造を以下に示す。ひとつのボックスが要素である。’?’はひとつまたはそれ以上存在することを意味する。要素を示すボックスの上半分がタグ名、下半分がその属性である。
以下各要素について説明する。
Server要素はひとつのTomcatサーバを定義するものである。これにはContextManagerやLogger要素が含まれる。
ContextManager要素は、それに属する5種類の要素を、それぞれひとつ以上包含でき、それらの設定や構成を指定する。この要素のオプショナルな属性は、このサーバに属するすべてのコンテキスト(ウェブ・アプリケーション)から参照される。まず、これらの属性を説明する。
home: webapps/、conf/、logs/などの相対パスおよびすべての<Context>のベースであり、この属性はTOMCAT_HOME以外のディレクトリにこのhomeディレクトリが存在するとき(startupコマンドの”-f/path/to/server.xml”オプションを使って、別のserver.xmlファイルを使って)に使用する。従って、TOMCAT_HOMEが、デフォルトのhomeディレクトリである。このhomeディレクトリからのパスに含まれるものは、
- webapps/: これが存在する場合はすべてのwarアーカイブ・ファイルはここに展開され、これのすべてのサブディレクトリはコンテキスト(複数)として追加される。
- conf/: このディレクトリには特定のweb.xml、ユーザ認証のためのtomcat-users.xmlなどその他の設定ファイルを含めることができる。
- logs/: メインのTOMCAT_HOME/logs/の代わりにこのディレクトリにすべてのログが蓄積される。
- work/: これらのコンテキストのためのワーク用ディレクトリである。
workDir: 作業用ディレクトリの名前.
randomClass: セッションIDを生成するためのjava.util.Randomのサブクラスを指定する。デフォルトはjava.security.SecureRandomである。java.util.Randomを指定したほうが高速になるが、セキュリティ度は下がる。
showDebugInfo: Tomcatのデフォルトの応答にスタック・トレースやその他のデバッグ用情報を付すかどうかをここで指定する。デバッグ情報としては、以下のものがある。
- 例外が発生したときのスタック・トレース
- 400またはそれ以上のステータス応答を生じさせたときの要求URI
デフォルトは”true”である。必要がなければこれを”false”にする。デバッグ情報はサーバーの内部の情報の一部を外部にさらけだすことになるので、セキュリティが心配な人もこれを”false”にする。
debug: デバッグ情報のログの詳細度を指定する。これは0から99までの範囲の値であり、99が一番詳細となるが、セキュリティが心配なら0とする。デフォルト値は0である。
ContextManager要素の属性のデフォルトは次のようである。
<ContextManager debug="0" workDir="work" showDebugInfo="true">
Logger要素はロガーのオブジェクトを指定する。ロガーは名前”name”および”path”で識別される。ロガー出力の詳細度は”verbosityLevel”で指定する。ロガーには現在、Servlet用、JSPファイル用、Tomcatランタイム用が存在する。サーブレットのプログラマが出力するのは、ServletContext.log()メソッド呼び出しである。標準のログ用ストリームの名称はtc_log、servlet_log、およびJASPER_LOGである。
name: ログの名前。
path: 外ログファイルへのTOMCAT_HOMEからの相対パス。このpath属性を指定しないとstderrまたはstdoutへの出力となる。
vervosityLevel: どのタイプのメッセージをログに出力するかを指定する(verbosityはくどさとか、おしゃべりの程度とかいう意味)。レベルは上からFATAL(致命的)、ERROR(エラー)、WARNING(警告)、INFORMATIONAL(情報)、DEBUG(デバッグ)の5段階があり、例えばWARNINGを指定するとWARNINGとそれ以上のレベルの情報が出力される。
timestampおよびtimestampFormat: 各ログにはタイムスタンプが付されるが、その形式を指定する。標準はデフォルトのYYYY-MM-dd hh:mm:ssである。
- timestamp=”no” これはタイムスタンプを付さない
- timestamp=”epoch” timestampFormat="hh:mm:ss" エポックからのミリ秒を付す
特定のフォーマットを指定したいときは、java.text.SimpleDateFormatに準拠して例えばtimestampFormat="hh:mm:ss"のように指定する。
custom: yesを指定すると通常の形式の出力となるが、non-customを指定するとXMLタグで囲んだ書式で出力される。
次のような設定を考えてみよう:
<Logger name="tc_log" verbosityLevel="WARNING" timestamp="no"/>
<Logger name="servlet_log" path="logs/servlet.log" verbosityLevel="WARNING" timestamp="no"/>
<Logger name="jasper_log" verbosityLevel="WARNING" timestamp="no"/>
この場合、Tomcatからのログ(tc_log)はコンソール出力となる。サーブレットからのログはTOMCAT_HOME/logs/servlet.logとなる。JasperのJSPコンパイラ出力はコンソール出力となる。
通常<xmlmapper:debug level="0" />として、これの立ち上がり時のデバッグレベルを指定する。
クライアントとの接続を指定する。スタンドアロンのモードではTomcatは直接クライアントとTCP接続する。その他のモードでは、Tomcatとクライアント間にはウェブ・サーバが介在する。まずこの要素にはclassNameがあり、これで実装するコネクタを指定する。現在はorg.apache.tomcat.service.PoolTcpConnectorが使われている。つぎにサブ要素としてParameterが存在し、ここで名前と値(name/value)の形式で必要なパラメタを設定していく。以下にそれらのパラメタを紹介する。
handler: これはハンドラのクラスを指定する。通常は"org.apache.tomcat.service.http.HttpConnectionHandler"が使われる。ウェブ・サーバのアドオンとしてTomcatが機能する場合は、Apache AJP12 Connectorを使用する。またこのコネクタは、Tomcatをバッチ・ファイルからシャット・ダウンさせる場合にも必要である。Tomcatのv.3.2.1では、AJP13よりこのコネクタのほうが良いとされている。以下はその例である。
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler" />
<Parameter name="port" value="8007" />
</Connector>
port: 使用するTCPポートの番号である。通常は80や8080を使う。
max_threads: スレッド・プールにおく最大スレッド数である。
max_spare_threads: 未使用のスレッドの数がこの値を超えると、スレッド・プール・マネージャが未使用スレッドの削除を開始する。
min_spare_threads: いつでもこれ以上のスレッドが待機しなければならない数。スレッド・プール・マネージャは未使用スレッドの削除に際して、この数の待機スレッドをのこす。
socketFactory: SSL(セキュアなソケット層)などを使う場合にこれで指定する。
backlog: 用途不明
以下に一般的なConnector要素の設定を示す。
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.http.HttpConnectionHandler" />
<Parameter name="port" value="8080" />
</Connector>
もしSSLを使う場合は、以下のようになろう。
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
<Parameter name="port" value="8443"/>
<Parameter name="socketFactory"
value="org.apache.tomcat.net.SSLSocketFactory" />
</Connector>
ただしこの場合には、Java™ Secure Socket Extension (JSSE)を使ったサーバ認証も設定しなければならない。JSSEの設定法は次のとおり:
1. CLASSPATHにJSSEのJARを追加する。
2. java_home/jre/lib/security/java.securityを編集して、security.provider.2=com.sun.net.ssl.internal.ssl.Providerと追加する。
3. keytoolを次のようにスタートさせる。
keytool -genkey -alias tomcat -keyalg RSA
NetscapeとIISとともに動作可能にするためにはRSAが必須である。changeitをパスワードにするか、keypas属性を追加するかする。認証のサインの必要は無い。user_home/.keystoreのデフォルト設定を変更したいときは、keystoreとkeypassパラメタを設定する。
コンテキストはウェブ・アプリケーションの環境だといえる。webapps/下にアプリケーションを置くのが標準だが、その場合は特にこの要素を追加する必要は無かろう。デフォルトの設定は次のようである:
<Context crossContext=”false” debug=”0” reloadable=”true” trusted=”false” />
以下その属性を記す。
crossContext: ServletContext.getContext()メソッドで他のコンテキストもアクセス可能とする。”true”はもっぱら管理目的に使うべきであろう。通常は”false”にする。
debug: これはすでに説明済み。
docBase: TOMCAT_BASEからのこのコンテキストへのパス。
path: このコンテキストのホームページのURLパス。このコンテキスト内のサーブレットやJSPはこれをホーム・ディレクトリとする。指定はフルパス表記でも、ContextManagerのホームからの相対であっても良い。
reloadable: コードに変更があったときにTomcatが自動的にそれを再ロードするか、あるいは変更を反映させるためにはTomcatをリブートさせねばならないかを指定する。通常は”true”にして、ソフトウエアの変更があってもリブートの必要が無いようにする。しかし、変更があったかの検出のためのオーバーヘッドが存在するし、新規のサーブレットは新規のクラス・ローダ・オブジェクトにロードされ、このクラス・ロードに伴ってキャスト・エラーを引き起こす場合もあるので、それが問題となる場合は”false”とする。
trusted: FacedeManagerを使ってTomcatの内部オブジェクトへのアクセスを可能にする。その場合は”true”を指定するとともにパスワードの設定が必要になる。また、tomcat.policyを編集する必要もある。セキュリティ・マネージャがオンとなっているときは、webappsディレクトリ内の読み出しとworkディレクトリの読み書きの許可を得ることになる。
特別にadminというコンテキストが用意されているが、これはウェブ・アプリケーションやTomcat内部へのアクセスを可能ならしめるためのデフォルトとしてtomcat.coreを用いている。デフォルトでは、トラストではなくて、Tomcat内部へのアクセスはできない。この場合、全てのサーブレットからアクセス可能な情報だけがadminサーブレットから見えることになる。
<Context docBase="webapps/admin" path="/admin" reloadable="false" />
<Context docBase="webapps/ROOT" path="/docs" reloadable="false" />
<Context docBase="webapps/examples" path="/examples" reloadable="false" />
<Context debug="99" docBase="webapps/radar"
path="/radar" reloadable="false" />
コンテキストに関わるインターセプタは、アプリケーションのロード等にかかわるもので、className属性で各々を指定する。
autoSetupInterceptor: <ContextInterceptor className="org.apache.tomcat.context.AutoSetup" />
webappsディレクトリにあるWARアーカイブファイルを探し出し、これを展開する。またこのアーカイブにあるアプリケーションに対応するコンテキストのオブジェクトを生成する。つまりwebapps/webapp_name.warというアーカイブ・ファイルがあったとしたら、そのコンテンツを/webapp_name/というパスにマッピングするコンテキストを生成する。従って、webapps内のWARになっているアプリケーションの場合は、特にContext要素を指定する必要は無い。
AutoSetupはorg.apache.tomcat.core.Context型の新しいインスタンスを生成する。新しいインスタンスの生成は、Tomcatがserver.xml内でContext要素に出くわしたときもなされる。Autosetupは/wabapp_name/をパスとし、<ContextManager home property>/webapps/webapp_name/>をdocBaseとする。しかるのち、新しいContextのオブジェクトをContextManagerに追加する。つまりWARを使っていなくて、次のようにContext要素が設定されているのと等価なふるまいをする。
<Context path="/webapp_name/" docBase="/webapps/webapp_name/">
このような自動的な設定を望まず、明示的な設定だけを使いたいときは、server.xmlにあるこの行をコメント・アウトする。
その他のインターセプターは、設定されているままにしておけばよい。
<ContextInterceptor
className="org.apache.tomcat.context.DefaultCMSetter" />
<ContextInterceptor
className="org.apache.tomcat.context.LoaderInterceptor" />
<ContextInterceptor
className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
<ContextInterceptor
className="org.apache.tomcat.context.LogEvents">
<ContextInterceptor
className="org.apache.tomcat.context.PolicyInterceptor" />
<ContextInterceptor
className="org.apache.tomcat.context.WebXmlReader" />
<ContextInterceptor
className="org.apache.tomcat.context.WorkDirInterceptor" />
この要素は、仮想ホストの設定を指定する。どの仮想ホストがどのコンテキストを受け持つかを指定する。例えば:
<Host name="127.0.0.1" >
<Context path=""
docBase="webapps/examples" />
<Context path="/examples"
docBase="webapps/ROOT" />
</Host>
と指定したとしたら、http://127.0.0.1/でアクセスでき、そのドキュメントのベースがTOMCAT_BASE/webapps/examplesであるコンテキストと、http://127.0.0.1/examples/でアクセスできるTOMCAT_BASE/webapps/ROOTがdocBaseのコンテキストをこの仮想ホストが受け持っていることになる。(実はこれは標準の設定をあべこべにしたもので、良いサンプルとは云えない)
要求インターセプターは、クライアントからの要求オブジェクトをサーブレットに渡す前に必要に応じ前処理する。
AccessInterceptor(アクセス・インターセプター): この要求は認証ロールを必要とするかどうかをチェックする。
<RequestInterceptor
className="org.apache.tomcat.request.AccessInterceptor" debug="0"
/>
InvokerInterceptor:
これはもともと習慣的にhttp://domain/servlet/myservletの形式でサーブレットをアクセスしていたので、互換性のためプレフィックスとして/servlet/が設定されている。必要に応じこのprefix属性を変更すればよい。Plefix属性はスラッシュで囲まれていることに注意する。このプレフィックスは全てのコンテキストに適用される。TomcatはこのプレフィックスをURIから外してマッピングを行う。
<RequestInterceptor
className="org.apache.tomcat.request.InvokerInterceptor"
debug="0"
prefix="/servlet/"
/>
JDBCRealmInterceptor(JDBCレルム・インターセプター):
JDBCレルムは、クライアントが有効なユーザであるかを認識するため、TOMCAT_HOME/conf/tomcat-users.xmlにあるデータを使わないで、換わりにデータベースを使うときの認証のメカニズムである。以下の事例はJDBC-ODBCブリッジを使っていることや、スレッド安全でないことから、良い事例とは云えない。
<RequestInterceptor
className="org.apache.tomcat.request.JDBCRealm"
debug="99"
driverName="sun.jdbc.odbc.JdbcOdbcDriver"
connectionURL="jdbc:odbc:TOMCAT"
userTable="users"
userNameCol="user_name"
userCredCol="user_pass"
userRoleTable="user_roles"
roleNameCol="role_name"
connectionName="scott"
connectionPassword="tiger"
/>
connectionNameやconnectionPasswordはオプショナルだが、使用したほうが良い。
OracleのJDBCドライバーを使ったJDBCRealmの場合は次のようになる。
driverName="oracle.jdbc.driver.OracleDriver"
connectionURL="jdbc:oracle:thin:@ntserver:1521:ORCL"
connectionName="scott"
connectionPassword="tiger"
MySqlのJDBCドライバを使ったJDBCRealmの場合は次のようになる。
driverName="org.gjt.mm.mysql.Driver"
connectionURL="jdbc:mysql://localhost/authority?user=test&password=test"
Session Interceptor(セッション・インターセプター):
CookieからセッションIDを抽出し、URLのjsessionidに書き換える。例えば、http://localhost:8080/servletなるURLは、http://localhost:8080/servlet;jsessionid=20938402398402398402394といった具合に追加される。もしクッキーを使いたくない場合は、noCookie属性をtrueにする。この場合は、応答にセッションIDを含めるためにencodeURLメソッドを使用する。標準の設定は以下のとおりである。
<RequestInterceptor
className="org.apache.tomcat.request.SessionInterceptor"
noCookies="false"
/>
SimpleMapper1 Interceptor:
要求に対応するコンテナを探す。標準の設定は以下のとおり。
<RequestInterceptor
className="org.apache.tomcat.request.SimpleMapper1"
debug="1"
/>
SimpleRealm Interceptor:
シンプル・レルムというのは、TOMCAT_HOME/conf/tomcat-users.xml のファイルをユーザ認証のメカニズムに使用するものである。このインターセプターはデフォルトではコメントアウトされている
<RequestInterceptor
className="org.apache.tomcat.request.SimpleRealm"
debug="0"
/>
Standard Session Interceptor:
これは標準のセッション・インターセプターである。
<RequestInterceptor
className="org.apache.tomcat.session.StandardSessionInterceptor"
/>
Static Interceptor:
スタティックなファイルやドキュメントのデフォルトのハンドラーである。Suppress属性はwelcomeファイルが存在しないときにそのディレクトリのリストを出力するのを抑制する。この設定はこのTomcatのインスタンス内で実行する全てのウェブ・アプリケーションに提要される。
<RequestInterceptor
className="org.apache.tomcat.request.StaticInterceptor"
debug="0"
suppress="false"
/>