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

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

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

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

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
      <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
      <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>

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

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

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

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  <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 サブシステムの属性」の項を参照してください。

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

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

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

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

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
      <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
      <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>

以下の例は、管理 CLI を使用してサーバーを設定する方法を示しています。管理コンソールを使用してサーバーを設定する場合は、Configuration → Subsystems → Web/HTTP - Undertow → HTTP → View と選択した後、HTTP Server タブを選択します。

既存のサーバーの更新

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

/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 サブシステムの属性」の項を参照してください。

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

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

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

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

以下の例は、管理 CLI を使用してサーブレットコンテナーを設定する方法を示しています。管理コンソールを使用してサーブレットコンテナーを設定する場合は、Configuration → Subsystems → Web/HTTP - Undertow → Servlet/JSP → View と選択します。

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

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

/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 サブシステムの属性」の項を参照してください。

Servlet extensions allow you to hook into the servlet deployment process and modify aspects of a servlet deployment. This can be useful in cases where you need to add additional authentication mechanisms to a deployment or use native Undertow handlers as part of a servlet deployment.

To create a custom servlet extension, it is necessary to implement the io.undertow.servlet.ServletExtension interface and then add the name of your implementation class to the META-INF/services/io.undertow.servlet.ServletExtension file in the deployment. You also need to include the compiled class file of the ServletExtension implementation. When Undertow deploys the servlet, it loads all the services from the deployments class loader and then invokes their handleDeployment methods.

An Undertow DeploymentInfo structure, which contains a complete and mutable description of the deployment, is passed to this method. You can modify this structure to change any aspect of the deployment.

The DeploymentInfo structure is the same structure that is used by the embedded API, so in effect a ServletExtension has the same amount of flexibility that you have when using Undertow in embedded mode.

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

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

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

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

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  <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(path="${jboss.home.dir}/welcome-content")

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

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

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

reload

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

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

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

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

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

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  <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>

以下の例は、管理 CLI を使用してフィルターを設定する方法を示しています。管理コンソールを使用してフィルターを設定する場合は、Configuration → Subsystems → Web/HTTP - Undertow → Filters → View と選択します。

既存のフィルターの更新

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

/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 サブシステムの属性」の項を参照してください。

/subsystem=undertow/configuration=filter/expression-filter=buf:add(expression="buffer-request(buffers=1)")

/subsystem=undertow/server=default-server/host=default-host/filter-ref=buf:add

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

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

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

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  ...
  <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <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 ファイルハンドラーの変更

default-web-module の変更

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

Web アプリケーションの HTTPS 設定に関する詳細は、『How to Configure Server Security』の「Configure One-way and Two-way SSL/TLS for Applications」を参照してください。

JBoss EAP 管理インターフェースと使用するための HTTPS 設定に関する詳細は、『How to Configure Server Security』の「How to Secure the Management Interfaces」を参照してください。

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

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

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

host-only をサーブレットコンテナーセッションクッキーに設定

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

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

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

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enable-http2,value=true)

HTTPS リスナーの情報や、Web アプリケーションで HTTPS を使用するよう Undertow を設定する方法については、『How to Configure Server Security』の「Configure One-way and Two-way SSL/TLS for Applications」を参照してください。

OpenSSL のインストール手順は、「JBoss Core Services からの OpenSSL のインストール」を参照してください。

JBoss EAP が OpenSSL を使用するよう設定する方法は複数あります。

JBoss EAP は自動的にシステム上の OpenSSL ライブラリーの検索を行い、それを使用します。JBoss EAP の起動中に org.wildfly.openssl.path プロパティーを使用すると、カスタム OpenSSL ライブラリーの場所を指定することもできます。JBoss Core Services によって提供される OpenSSL ライブラリーのバージョン 1.0.2 以上のみがサポートされます。HP-UX 上の JBoss EAP で OpenSSL を使用することはサポートされません。

OpenSSL が適切にロードされると、JBoss EAP の起動中に以下と似たメッセージが server.log に出力されます。

15:37:59,814 INFO [org.wildfly.openssl.SSL] (MSC service thread 1-7) WFOPENSSL0002 OpenSSL Version OpenSSL 1.0.2k-fips 23 Mar 2017

HTTP/2 は、HTTP/2 標準をサポートするブラウザーでのみ動作します。

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=enable-http2,value=true)

HTTP/2 が使用されていることを検証

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

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

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

/subsystem=undertow/configuration=filter/expression-filter=requestDumperExpression:add(expression="dump-request")

/subsystem=undertow/server=default-server/host=default-host/filter-ref=requestDumperExpression:add

dump-request

path(/test) -> dump-request

undertow サブシステムのパフォーマンスを最適化するための情報は、『Performance Tuning Guide』の「Undertow Subsystem Tuning」を参照してください。