第17章 Web サーバーの設定 (Undertow)

17.1. Undertow サブシステムの概要

重要

JBoss EAP 7 では、JBoss EAP の過去のバージョンで使用された web サブシステムの代わりに undertow サブシステムが使用されます。

undertow サブシステムは、Web サーバーおよびサーブレットコンテナーの設定を可能にします。Java Servlet 3.1 仕様や WebSocket を実装し、HTTP Upgrade をサポートします。また、サーブレットデプロイメントでパフォーマンスの高い非ブロッキングハンドラーの使用をサポートします。undertow サブシステムは、mod_cluster をサポートする高パフォーマンスなリバースプロキシとして動作することも可能です。

undertow サブシステム内で設定する主なコンポーネントは 5 つあります。

注記

JBoss EAP には、これらの各コンポーネントの設定を更新する機能がありますが、デフォルト設定は妥当なパフォーマンスの設定を提供し、ほとんどのユースケースに適しています。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
      </host>
  </server>
  <servlet-container name="default">
      <jsp-config/>
      <websockets/>
  </servlet-container>
  <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
  </handlers>
  <filters>
      <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
      <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
  </filters>
</subsystem>
重要

また、undertow サブシステムは io サブシステムに依存して XNIO ワーカーやバッファープールを提供します。io サブシステムは個別に設定され、ほとんどの場合で最適なパフォーマンスを得られるデフォルト設定を提供します。

注記

JBoss EAP の過去のリリースに含まれていた web サブシステムと比較すると、JBoss EAP 7 の undertow サブシステムでは HTTP メソッドのデフォルト動作が異なります。

17.2. バッファーキャッシュの設定

バッファーキャッシュは静的リソースをキャッシュするために使用されます。JBoss EAP では複数のキャッシュを設定でき、デプロイメントによる参照が可能であるため、デプロイメントごとに異なるキャッシュサイズを使用することができます。バッファーは固定サイズで、リージョンで割り当てられます。使用領域の合計は、バッファーサイズ、リージョンごとのバッファー数、およびリージョンの最大数を掛けて算出できます。バッファーキャッシュのデフォルトサイズは 10MB です。

JBoss EAP はデフォルトで単一のキャッシュを提供します。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  ....
</subsystem>

既存のバッファーキャッシュの更新

既存のバッファーキャッシュを更新するには、以下を指定します。

/subsystem=undertow/buffer-cache=default/:write-attribute(name=buffer-size,value=2048)
reload

新規バッファーキャッシュの作成

新しいバッファーキャッシュを作成するには、以下を指定します。

/subsystem=undertow/buffer-cache=new-buffer:add

バッファーキャッシュの削除

バッファーキャッシュを削除するには、以下を指定します。

/subsystem=undertow/buffer-cache=new-buffer:remove
reload

バッファーキャッシュの設定に使用できる属性の完全リストは、Undertow サブシステムの属性の項を参照してください。

17.3. サーバーの設定

サーバーは Undertow のインスタンスを表し、複数の要素で構成されます。

  • host
  • http-listener
  • https-listener
  • ajp-listener

ホスト要素は仮想ホスト設定を提供し、3 つのリスナーはそのタイプの接続を Undertow インスタンスに提供します。

注記

複数のサーバーを設定でき、デプロイメントやサーバーを完全に分離できます。これは、マルチテナント環境などで便利です。

JBoss EAP はデフォルトでサーバーを提供します。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
      </host>
  </server>
  ...
</subsystem>

既存のサーバーの更新

既存のサーバーを更新するには、以下を設定します。

/subsystem=undertow/server=default-server:write-attribute(name=default-host,value=default-host)
reload

新規サーバーの作成

新規サーバーを作成するには、以下を指定します。

/subsystem=undertow/server=new-server:add
reload

サーバーの削除

サーバーを削除するには、以下を指定します。

/subsystem=undertow/server=new-server:remove
reload

サーバーの設定に使用できる属性の完全リストは、Undertow サブシステムの属性の項を参照してください。

17.4. サーブレットコンテナーの設定

サーブレットコンテナーは、すべてのサーブレット、 JSP、およびソケット関連の設定 (セッションに関連する設定を含む) を提供します。ほとんどのサーバーにはサーブレットコンテナーが 1 つだけ必要ですが、servlet-container 要素を追加すると複数のサーブレットコンテナーを設定することができます。サーブレットコンテナーが複数設定されていると、複数のデプロイメントを異なる仮想ホストの同じコンテキストパスにデプロイできるなど、一部の動作を有効にすることができます。

注記

サーブレットコンテナーによって提供される設定の多くは、デプロイされたアプリケーションが web.xml ファイルを使用して個別にオーバーライドできます。

JBoss EAP はデフォルトでサーブレットコンテナーを提供します。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
    ...
  </server>
  <servlet-container name="default">
      <jsp-config/>
      <websockets/>
  </servlet-container>
...
</subsystem>

既存のサーブレットコンテナーの更新

既存のサーブレットコンテナーを更新するには、以下を指定します。

/subsystem=undertow/servlet-container=default:write-attribute(name=ignore-flush,value=true)
reload

新規サーブレットコンテナーの作成

新規のサーブレットコンテナーを作成するには、以下を指定します。

/subsystem=undertow/servlet-container=new-servlet-container:add
reload

サーブレットコンテナーの削除

サーブレットコンテナーを削除するには、以下を指定します。

/subsystem=undertow/servlet-container=new-servlet-container:remove
reload

サーブレットコンテナーの設定に使用できる属性の完全リストは、Undertow サブシステムの属性の項を参照してください。

17.5. ハンドラーの設定

JBoss EAP では、2 つのタイプのハンドラーを設定できます。

  • ファイルハンドラー
  • リバースプロキシハンドラー

ファイルハンドラーは静的ファイルに対応します。各ファイルハンドラーは仮想ホストの場所にアタッチされている必要があります。リバースプロキシーハンドラーによって、JBoss EAP は高パフォーマンスなリバースプロキシーとして機能することができます。AJP、HTTP、および HTTP.2 バックエンドを処理でき、mod_cluster をサポートします。

JBoss EAP はデフォルトでファイルハンドラーを提供します。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
      ...
  </server>
  <servlet-container name="default">
      ...
  </servlet-container>
  <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
  </handlers>
  ...
</subsystem>

静的リソースに WebDAV を使用

過去のバージョンの JBoss EAP では、web サブシステムで WebDAV を使用して (WebdavServlet 経由) 静的リソースをホストし、追加の HTTP メソッドを有効にしてこれらのファイルへのアクセスや操作を実行できました。JBoss EAP 7 では、ファイルハンドラーを経由した静的ファイルの対応メカニズムは undertow サブシステムによって提供されますが、undertow サブシステムは WebDAV をサポートしません。JBoss EAP 7 で WebDAV を使用する場合は、カスタムの WebDav サーブレットを記述してください。

既存のファイルハンドラーの更新

既存のファイルハンドラーを更新するには、以下を指定します。

/subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=case-sensitive,value=true)
reload

新規ファイルハンドラーの作成

新規のファイルハンドラーを作成するには、以下を指定します。

/subsystem=undertow/configuration=handler/file=new-file-handler:add

ファイルハンドラーの削除

ファイルハンドラーを削除するには、以下を指定します。

/subsystem=undertow/configuration=handler/file=new-file-handler:remove
reload

ハンドラーの設定に使用できる属性の完全リストは、Undertow サブシステムの属性の項を参照してください。

17.6. フィルターの設定

フィルターはリクエストの一部の変更を可能にし、述語を使用してフィルターの実行時を制御できます。フィルターの一般的なユースケースには、ヘッダーの設定や GZIP 圧縮などがあります。

注記

フィルターの機能は、過去のバージョンの JBoss EAP で使用されたグローバルバルブと同等です。

以下のタイプのフィルターを定義できます。

  • custom-filter
  • error-page
  • expression-filter
  • gzip
  • mod-cluster
  • request-limit
  • response-header
  • rewrite

JBoss EAP はデフォルトで 2 つのフィルターを提供します。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
    ...
  </server>
  <servlet-container name="default">
    ...
  </servlet-container>
  <handlers>
      ...
  </handlers>
  <filters>
      <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
      <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
  </filters>
</subsystem>

既存のフィルターの更新

既存のフィルターを更新するには、以下を指定します。

/subsystem=undertow/configuration=filter/response-header=server-header:write-attribute(name=header-value,value="JBoss-EAP")
reload

新規のフィルターの作成

新規のフィルターを作成するには、以下を指定します。

/subsystem=undertow/configuration=filter/response-header=new-response-header:add(header-name=new-response-header,header-value="My Value")

フィルターの削除

フィルターを削除するには、以下を指定します。

/subsystem=undertow/configuration=filter/response-header=new-response-header:remove
reload

フィルターの設定に使用できる属性の完全リストは、Undertow サブシステムの属性の項を参照してください。

17.7. デフォルトの Welcome Web アプリケーションの設定

JBoss EAP には、デフォルトでポート 8080 のルートコンテキストで表示される Welcome アプリケーションが含まれます。

Undertow には、Welcome コンテンツに対応するデフォルトのサーバーが事前設定されています。

デフォルトの Undertow サブシステムの設定

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  ...
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
      </host>
  </server>
  ...
  <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
  </handlers>
  ...
</subsystem>

デフォルトのサーバー (default-server) にはデフォルトのホスト (default-host) が設定されています。デフォルトのホストは、welcome-content ファイルハンドラーで <location> 要素を使用して、サーバーのルートへのリクエストを処理するよう設定されています。welcome-content ハンドラーは path プロパティーに指定された場所でコンテンツを処理します。

このデフォルトの Welcome アプリケーションは、独自の Web アプリケーションで置き換えることができます。これは、以下の 2 つのいずれかの方法で設定できます。

Welcome コンテンツを無効にすることもできます。

welcome-content ファイルハンドラーの変更

新しいデプロイメントを参照する、既存の welcome-content ファイルハンドラーのパスを変更します。

/subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=path,value="/path/to/content")
注記

または、サーバーのルートにより使用される異なるファイルハンドラーを作成することもできます。

/subsystem=undertow/configuration=handler/file=NEW_FILE_HANDLER:add(path="/path/to/content")
/subsystem=undertow/server=default-server/host=default-host/location=\/:write-attribute(name=handler,value=NEW_FILE_HANDLER)

変更を反映するためにサーバーをリロードします。

reload

default-web-module の変更

デプロイされた Web アプリケーションをサーバーのルートにマップします。

/subsystem=undertow/server=default-server/host=default-host:write-attribute(name=default-web-module,value=hello.war)

変更を反映するためにサーバーをリロードします。

reload

デフォルトの Welcome Web アプリケーションの無効化

default-hostlocation エントリー (/) を削除して welcome アプリケーションを無効にします。

/subsystem=undertow/server=default-server/host=default-host/location=\/:remove

変更を反映するためにサーバーをリロードします。

reload

17.8. HTTPS の設定

両方の Web アプリケーションおよび管理インターフェースと使用するために HTTPS を設定する方法の詳細は、How to Configure Server Security Guide を参照してください。

17.9. HTTP セッションタイムアウトの設定

HTTP セッションタイムアウトは、HTTP セッションの無効を宣言するために必要な非アクティブな期間を定義します。たとえば、HTTP セッションを作成する JBoss EAP にデプロイされたアプリケーションにユーザーがアクセスしたとします。HTTP セッションタイムアウト後に同じユーザーが同じアプリケーションにアクセスしようとすると、元の HTTP セッションは無効化され、ユーザーは新しい HTTP セッションの作成を強制されます。これにより、永続化されなかったデータを損失したり、ユーザーを再認証する必要がある場合があります。

HTTP セッションタイムアウトは、アプリケーションの web.xml ファイルに設定されますが、デフォルトの HTTP セッションタイムアウトは JBoss EAP 内で指定できます。サーバーのタイムアウト値はデプロイされたすべてのアプリケーションに適用されますが、アプリケーションの web.xml はサーバーの値をオーバーライドします。

サーバーの値は、undertow サブシステムの servlet-container セクションにある default-session-timeout プロパティーに指定されます。default-session-timeout の値は分単位で指定され、デフォルトは 30 です。

デフォルトのセッションタイムアウトの設定

default-session-timeout を設定するには、以下を指定します。

/subsystem=undertow/servlet-container=default:write-attribute(name=default-session-timeout, value=60)
reload
重要

HTTP セッションタイムアウトを変更する場合は、影響を受けるすべての JBoss EAP インスタンスを再起動する必要があります。この操作が行われるまで元の HTTP セッションタイムアウト値が適用されます。

17.10. HTTP のみのセッション管理クッキーの設定

セッション管理クッキーは、HTTP API と非 HTTP API (JavaScript など) の両方によってアクセスされます。JBoss EAP は HttpOnly ヘッダーを Set-Cookie 応答ヘッダーの一部としてクライアント (通常はブラウザー) に送信します。サポートされるブラウザーでこのヘッダーを有効にすると、非 HTTP API を経由してセッション管理クッキーへアクセスしないようにブラウザーに通知します。セッション管理クッキーを HTTP API のみに制限すると、クロスサイトスクリプティングの攻撃よるセッションクッキーの窃盗のリスクを軽減することができます。この動作を有効にするには、http-only 属性を true に設定する必要があります。

重要

HttpOnly ヘッダーを使用しても、単にブラウザーに通知を行うだけで、クロスサイトスクリプティングによる攻撃を実際に防ぐわけではありません。この動作を反映するには、ブラウザーも HttpOnly をサポートしている必要があります。

重要

http-only 属性を使用すると制限がセッション管理クッキーのみに適用され、その他のブラウザークッキーには適用されません。

http-only 属性は undertow サブシステムの 2 カ所で設定されます。

  • セッションクッキー設定としてサーブレットコンテナーで設定
  • 単一のサインオンプロパティーとしてサーバーのホストセクションで設定

host-only プロパティーをサーブレットコンテナーセッションクッキーに設定するには、以下を指定します。

/subsystem=undertow/servlet-container=default/setting=session-cookie:add
/subsystem=undertow/servlet-container=default/setting=session-cookie:write-attribute(name=http-only,value=true)
reload

host-only をシングルサインオンに設定

host-only プロパティーをホストシングルサインオンに設定するには、以下を指定します。

/subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:add
/subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:write-attribute(name=http-only,value=true)
reload

17.11. HTTP/2 の設定

Undertow では、HTTP/2 標準を使用できます。この標準は、ヘッダーの圧縮と多くのストリームの多重化を同じ TCP 接続で行い、待ち時間を削減します。さらに、リクエストの前にサーバーがリソースをクライアントにプッシュできる機能も提供するため、ページのロードがより速くなります。新しい仕様に更新していないクライアントをサポートするため、Undertow は HTTP/2 以前の SPDY とも互換性を維持します。

重要

JBoss EAP 7.0 では HTTP/2 は技術プレビューとしてのみサポートされ、HTTP/2 標準をサポートするブラウザーでのみ動作します。

重要

HTTP/2 を使用するには、Java 8 を使用し、クラスパス上に ALPN を設定する必要があります。これは、HTTP/2 には Java 8 のデフォルトインストールに含まれていない ALPN をサポートする TLS スタックが必要であるためです。

17.11.1. Undertow が HTTP/2 を使用するよう設定

Undertow が HTTP/2 を使用するよう設定するには、以下を行う必要があります。

Undertow が HTTPS を使用するよう設定する

Web アプリケーションに HTTPS を使用するよう Undertow を設定するには、How to Configure Server Security Guide を参照してください。

注記

HTTP アップグレードを使用するプレーン HTTP の場合は HTTPS を使用せずに HTTP/2 を使用することは可能です。この場合、ALPN をインストールする必要はなく、Undertow で HTTP/2 を有効にします。

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=enable-http2,value=true)
ALPN JAR のダウンロード

最初に、Java のバージョンを確認します。ターミナルで以下のコマンドを実行し、インストールされている Java のバージョンを出力します。

java -version

このバージョンを基に このページ を参照し、このリスト からダウンロードする ALPN JAR の正しいバージョンを判断します。たとえば、実行している Java のバージョンが 1.8.0_51 である場合、使用する ALPN バージョンは 8.1.4.v20150727 で、alpn-boot-8.1.4.v20150727.jar をダウンロードします。

ALPN JAR の ブートクラスパスへの追加

正しいバージョンの ALPN JAR をダウンロードしたら、EAP_HOME/bin にコピーします。また、以下を bin/standalone.conf (管理対象ドメインで実行している場合は bin/domain.conf) に追加する必要もあります。$JBOSS_HOME$ALPN_VERSION は適切な値に置き換えてください。

JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:$JBOSS_HOME/bin/alpn-boot-$ALPN_VERSION.jar"
重要

クラスパスの変更を反映するには、JBoss EAP を再起動する必要があります。

HTTPS リスナーでの HTTP/2 の有効化

HTTP/2 を使用するよう Undertow の HTTPS リスナーを有効にするには、enable-http2 属性を true に設定します。

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enable-http2,value=true)
HTTP/2 が使用されていることを検証

Undertow が HTTP/2 を使用していることを検証するには、Undertow からのヘッダーを確認する必要があります。https を使用して JBoss EAP インスタンスに移動し (例: https://localhost:8443)、ブラウザーの開発者ツールを使用してヘッダーを確認します。 Google Chrome などの一部のブラウザーは、HTTP/2 の使用時には HTTP/2 擬似ヘッダーを表示します (:path, :authority:method、および :scheme)。 Firefox や Safari などの他のブラウザーは、HTTP/2.0 のようにヘッダーの状態またはバージョンを表示します。

17.12. RequestDumping ハンドラーの設定

RequestDumping ハンドラー (io.undertow.server.handlers.RequestDumpingHandler)、JBoss EAP 内で Undertow によって処理されるリクエストとその応答オブジェクトの詳細をログに記録します。

重要

このハンドラーはデバッグに便利ですが、機密情報がログに記録される可能性があります。この点に留意してこのハンドラーを有効にしてください。

注記

RequestDumping ハンドラーは、JBoss EAP の過去のバージョンで使用された RequestDumperValve の代わりに使用されます。

RequestDumping ハンドラーは、JBoss EAP のサーバーレベルまたは個別のアプリケーション内で設定できます。

17.12.1. サーバーでの RequestDumping ハンドラーの設定

RequestDumping ハンドラーは式フィルターとして設定する必要があります。RequestDumping ハンドラーを式フィルターとして設定するには、以下を行う必要があります。

RequestDumping ハンドラーで新しい式フィルターを作成する
/subsystem=undertow/configuration=filter/expression-filter=requestDumperExpression:add(expression="dump-request")
Undertow Web サーバーで式フィルターを有効にする
/subsystem=undertow/server=default-server/host=default-host/filter-ref=requestDumperExpression:add
重要

このように RequestDumping ハンドラーを式フィルターとして有効にすると、Undertow Web サーバーによって処理されるすべてのリクエストおよびそれらの応答がログに記録されます。

特定 URL に対して RequestDumping ハンドラーを設定する

すべてのリクエストをログに記録する他に、特定の URL のリクエストやそれらの応答のみをログに記録するために式フィルターを使用することもできます。これには、pathpath-prefix、または path-suffix などの述語を式に使用します。たとえば、/myApplication/test へのリクエストとそれらの応答をすべてログに記録するには、式フィルターの作成時に式 "dump-request" の代わりに "path(/myApplication/test) -> dump-request" を使用します。これにより、/myApplication/test に完全一致するパスを持つリクエストのみが RequestDumping ハンドラーに送られます。

17.12.2. アプリケーション内での RequestDumping ハンドラーの設定

サーバーで RequestDumping ハンドラーを設定する他に、個別のアプリケーション内で設定することもできます。これにより、ハンドラーの範囲がそのアプリケーションのみに制限されます。 RequestDumping ハンドラーは WEB-INF/undertow-handlers.conf で設定する必要があります。

指定のアプリケーションのすべてのリクエストとそれらの応答をログに記録するよう WEB-INF/undertow-handlers.confRequestDumping ハンドラーを設定するには、以下の式を WEB-INF/undertow-handlers.conf に追加します。

WEB-INF/undertow-handlers.conf の例

dump-request

指定のアプリケーション内での特定 URL のリクエストやそれらの応答のみをログに記録するには、pathpath-prefixpath-suffix などの述語を式に使用します。たとえば、アプリケーションの test へのリクエストとそれらの応答をすべてログに記録するには、path 述語が含まれる以下の式を使用できます。

WEB-INF/undertow-handlers.conf の例

path(/test) -> dump-request

注記

pathpath-prefixpath-suffix などの述語をアプリケーションの WEB-INF/undertow-handlers.conf に定義された式で使用する場合、使用する値はアプリケーションのコンテキストルートからの相対値になります。たとえば、アプリケーションのコンテキストルートは myApplication で、式 path(/test) -> dump-requestWEB-INF/undertow-handlers.conf に設定されている場合、 /myApplication/test へのリクエストとそれらの応答のみがログに記録されます。