4.5. Web サーバー設定の変更

4.5.1. Undertow による Web サブシステムの置換

JBoss EAP 7 の web サーバーは、JBoss Web から Undertow に変更になりました。そのため、web サブシステム設定を新しい JBoss EAP 7 undertow サブシステム設定に移行する必要があります。

  • サーバー設定ファイルの urn:jboss:domain:web:2.2 サブシステム設定ネームスペースは urn:jboss:domain:undertow:10.0 ネームスペースに置き換えられました。
  • EAP_HOME/modules/system/layers/base/ にあった org.jboss.as.web 拡張モジュールは、org.wildfly.extension.undertow 拡張モジュールに置き換えられました。

管理 CLI migrate 操作を使うと、 web サブシステムをサーバー設定ファイル内の undertow に移行することができます。ただし、この操作では JBoss Web サブシステムのすべての設定が移行できるわけではないことに注意してください。"migration-warning" エントリーが表示される場合は、追加の管理 CLI コマンドを実行して設定を Undertow に移行する必要があります。管理 CLI migrate 操作についての詳細情報は、管理 CLI の移行操作 を参照してください。

以下の例は、JBoss EAP 6.4 のデフォルトの web サブシステム設定を示しています。 

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <virtual-server name="default-host" enable-welcome-root="true">
        <alias name="localhost"/>
        <alias name="example.com"/>
    </virtual-server>
</subsystem>

以下の例は、JBoss EAP 7.3 undertow サブシステムのデフォルト設定を示しています。 

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <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"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    ...
</subsystem>

4.5.2. JBoss Web リライト条件の移行

管理 CLI の migrate 操作はリライト条件を自動的に移行できません。"migration-warnings" として報告され、手作業で移行する必要があります。Undertow の述語属性およびハンドラーを使用すると (Undertow Predicates Attributes and Handlers を参照)、JBoss EAP 7 で同等の設定を作成できます。

以下の例は、rewrite 設定を含む JBoss EAP 6 の web サブシステム設定を示しています。 

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default" native="false">
    <virtual-server name="default" enable-welcome-root="true">
        <alias name="localhost"/>
        <rewrite name="test" pattern="(.*)/toberewritten/(.*)" substitution="$1/rewritten/$2" flags="NC"/>
        <rewrite name="test2" pattern="(.*)" substitution="-" flags="F">
            <condition name="get" test="%{REQUEST_METHOD}" pattern="GET"/>
            <condition name="andCond" test="%{REQUEST_URI}" pattern=".*index.html" flags="NC"/>
        </rewrite>
    </virtual-server>
</subsystem>

管理 CLI の移行操作 にある手順にしたがってサーバーと管理 CLI を開始し、以下のコマンドを使用して web サブシステム設定ファイルを移行します。 

/subsystem=web:migrate

上記の設定で migrate 操作を実行すると、以下の "migration-warnings" がレポートされます。 

/subsystem=web:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYWEB0002: Could not migrate resource {
    \"pattern\" => \"(.*)\",
    \"substitution\" => \"-\",
    \"flags\" => \"F\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_METHOD}\",
    \"pattern\" => \"GET\",
    \"flags\" => undefined,
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"get\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_URI}\",
    \"pattern\" => \".*index.html\",
    \"flags\" => \"NC\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"andCond\")
    ]
}"
    ]}
}

サーバー設定ファイルを確認すると、undertow サブシステムが以下の設定になっています。

注記

リライト設定は削除されています。 

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
     <buffer-cache name="default"/>
     <server name="default-server">
         <http-listener name="http" socket-binding="http"/>
         <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
         <host name="default-host" alias="localhost, example.com">
             <location name="/" handler="welcome-content"/>
         </host>
     </server>
     <servlet-container name="default">
         <jsp-config/>
     </servlet-container>
     <handlers>
         <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
     </handlers>
 </subsystem>

管理 CLI を使用してフィルターを作成し、undertow サブシステムのリライト設定を置き換えます。各コマンドで "{"outcome" ⇒ "success"}" が表示されるはずです。 

# Create the filters
/subsystem=undertow/configuration=filter/expression-filter="test1":add(expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')")
/subsystem=undertow/configuration=filter/expression-filter="test2":add(expression="method('GET') and path('.*index.html') -> response-code(403)")

# Add the filters to the default server
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test1":add
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test2":add

更新されたサーバー設定ファイルを確認します。JBoss Web サブシステムは完全に移行され、undertow サブシステムに設定されます。 

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="http" socket-binding="http"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost, example.com">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="test1"/>
            <filter-ref name="test2"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <expression-filter name="test1" expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')"/>
        <expression-filter name="test2" expression="method('GET') and path('.*index.html') -> response-code(403)"/>
    </filters>
</subsystem>

管理 CLI を使用してフィルターとハンドラーを設定する方法については、JBoss EAP 7 設定ガイド のWeb サーバーの設定を参照してください。

4.5.3. JBoss Web システムプロパティーの移行

以前のリリースの JBoss EAP では、システムプロパティーを使用して JBoss Web のデフォルトの動作を変更することが可能でした。Undertow で同じ動作を設定する方法は、JBoss Web システムプロパティー移行のリファレンス を参照してください。

4.5.4. アクセスログヘッダーパターンの更新

JBoss EAP 6.4 から JBoss EAP 7 に移行するときに、アクセスログに予期される "Referer" および "User-agent" 値が書き込まれないことに気付くかもしれません。これは、JBoss EAP 6.4 に含まれていた JBoss Web は access-log で %{headername}i パターンを使用して受信ヘッダーをログに記録したためです。

例: JBoss EAP 6.4 でのアクセスログ形式

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{Referer}i&quot; &quot;%{User-agent}i&quot;"/>

JBoss EAP 7 では Undertow が使用されるようになったため、受信ヘッダーのパターンは %{i,headername} に変更になりました。

例: JBoss EAP 7 でのアクセス形式ヘッダー

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{i,Referer}&quot; &quot;%{i,User-Agent}&quot;"/>

4.5.5. グローバルバルブの移行

以前のリリースの JBoss EAP ではバルブがサポートされました。バルブとは、リクエストの変更や追加処理を実行するために、サーブレットフィルターの前にアプリケーションのリクエスト処理パイプラインへ挿入されるカスタムクラスのことです。

  • グローバルバルブは、デプロイされたすべてのアプリケーションのリクエスト処理パイプラインへ挿入され、サーバー設定ファイルで設定されます。
  • オーセンティケーターバルブはリクエストのクレデンシャルを認証します。
  • カスタムアプリケーションバルブは、org.apache.catalina.valves.ValveBase クラスを拡張して作成され、jboss-web.xml 記述子ファイルの <valve> 要素で設定されます。これらのバルブは手作業で移行する必要があります。

この項では、グローバルバルブの移行方法について説明します。カスタムおよびオーセンティケーターバルブの移行については、本ガイドの カスタムアプリケーションバルブの移行 を参照してください。

JBoss EAP 7 で JBoss Web の代わりに導入された Undertow はグローバルバルブをサポートしませんが、Undertow ハンドラーを使用すると同様の機能を実現できます。Undertow には共通の機能を提供する複数のビルトインハンドラーが含まれています。また、カスタムハンドラーを作成する機能も含まれ、カスタムバルブの機能を置き換えるために使用することができます。

アプリケーションがバルブを使用する場合、JBoss EAP 7 へ移行するときに適切な Undertow ハンドラーコードに置き換え、同様の機能を実現する必要があります。

ハンドラーの設定方法に関する詳細は、JBoss EAP 7設定ガイド のハンドラーの設定を参照してください。

フィルターの設定方法に関する詳細は、JBoss EAP 7設定ガイド のフィルターの設定を参照してください。

JBoss Web バルブの移行

以下の表では、JBoss EAP の前リリースで JBoss Web が提供していたバルブとそれに対応する Undertow ビルトインハンドラーを示しています。JBoss Web バルブは、org.apache.catalina.valves パッケージにあります。

表4.2 バルブとハンドラーのマッピング

バルブハンドラー

AccessLogValve

io.undertow.server.handlers.accesslog.AccessLogHandler

CrawlerSessionManagerValve

io.undertow.servlet.handlers.CrawlerSessionManagerHandler

ExtendedAccessLogValve

io.undertow.server.handlers.accesslog.AccessLogHandler

JDBCAccessLogValve

手順については JDBCAccessLogValve の手動移行の手順 を参照してください。

RemoteAddrValve

io.undertow.server.handlers.IPAddressAccessControlHandler

RemoteHostValve

io.undertow.server.handlers.AccessControlListHandler

RemoteIpValve

io.undertow.server.handlers.ProxyPeerAddressHandler

RequestDumperValve

io.undertow.server.handlers.RequestDumpingHandler

RewriteValve

これらのバルブを手作業で移行する手順は、JBoss Web リライト条件の移行 を参照してください。

StuckThreadDetectionValve

io.undertow.server.handlers.StuckThreadDetectionHandler

管理 CLI の migrate 操作を使用すると、以下の基準を満たすグローバルバルブを自動的に移行できます。

  • 前述の表にリストされている、手動処理の必要がないバルブに限定されます。
  • サーバー設定ファイルの web サブシステムに定義されている必要があります。

管理 CLI migrate 操作についての詳細情報は、管理 CLI の移行操作 を参照してください。

JDBCAccessLogValve の手動移行の手順

org.apache.catalina.valves.JDBCAccessLogValve バルブはルールの例外で、io.undertow.server.handlers.JDBCLogHandler へ自動的に移行することができません。以下の手順に従って、次のバルブ例を移行します。 

<valve name="jdbc" module="org.jboss.as.web" class-name="org.apache.catalina.valves.JDBCAccessLogValve">
    <param param-name="driverName" param-value="com.mysql.jdbc.Driver" />
    <param param-name="connectionName" param-value="root" />
    <param param-name="connectionPassword" param-value="password" />
    <param param-name="connectionURL" param-value="jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull" />
    <param param-name="format" param-value="combined" />
</valve>
  1. ログエントリーを保存するデータベースのドライバーモジュールを作成します。

  2. データベースのデータソースを設定し、ドライバーを datasources サブシステムの利用可能なドライバーのリストに追加します。 

    <datasources>
    <datasource jndi-name="java:jboss/datasources/accessLogDS" pool-name="accessLogDS" enabled="true" use-java-context="true">
        <connection-url>jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull</connection-url>
        <driver>mysql</driver>
        <security>
           <user-name>root</user-name>
           <password>Password1!</password>
        </security>
    </datasource>
    ...
    <drivers>
        <driver name="mysql" module="com.mysql">
            <driver-class>com.mysql.jdbc.Driver</driver-class>
        </driver>
    ...
    </drivers>
</datasources>

  3. 式 jdbc-access-log(datasource=DATASOURCE_JNDI_NAME) を使用して、undertow サブシステムの expression-filter を設定します。 

    <filters>
    <expression-filter name="jdbc-access" expression="jdbc-access-log(datasource='java:jboss/datasources/accessLogDS')" />
    ...
</filters>

4.5.7. HTTP メソッド呼び出しの挙動変更

JBoss Web が web サーバーとして含まれていた JBoss EAP 6.4 では、デフォルトで HTTP TRACE メソッド呼び出しが許可されていました。

JBoss EAP 7 で JBoss Web の代わりに web サーバーとして導入された Undertow は、デフォルトでは HTTP TRACE メソッド呼び出しを許可しません。この設定は、undertow サブシステムで http-listener 要素の disallowed-methods 属性を使用して設定されます。この設定を確認するには、以下の read-resource コマンドの出力を確認します。disallowed-methods 属性の値が ["TRACE"] であることに注目してください。 

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "allow-unescaped-characters-in-url" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => ["TRACE"],
         ...
    }
}

JBoss EAP 7 およびそれ以降のバージョンで HTTP TRACE メソッド呼び出しを有効にするには、以下のコマンドを実行して disallowed-methods 属性リストから "TRACE" エントリーを削除する必要があります。 

/subsystem=undertow/server=default-server/http-listener=default:list-remove(name=disallowed-methods,value="TRACE")

read-resource コマンドを再度実行すると、TRACE メソッド呼び出しが許可されないメソッドのリストから削除されたことが確認できます。 

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "allow-unescaped-characters-in-url" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => [],
         ...
    }
}

HTTP メソッドのデフォルト動作に関する詳細は、JBoss EAP設定ガイド のHTTP メソッドのデフォルトの動作を参照してください。

4.5.8. デフォルトの Web モジュール動作の変更

JBoss EAP 7.0 では、mod_cluster の web アプリケーションのルートコンテキストはデフォルトで無効になっていました。

JBoss EAP 7.1 よりこれが変更にななりました。そのため、ルートコンテキストが無効になっていることを想定している場合は予期せぬ結果が生じる可能性があります。たとえば、リクエストが誤って不都合なノードにルーティングされたり、公開してはならないプライベートアプリケーションにパブリックプロキシーを介してアクセスされる可能性があります。Undertow の場所も明示的に除外しない限り、mod_cluster ロードバランサーに自動的に登録されるようになりました。

以下の管理 CLI コマンドを使用して、modcluster サブシステム設定から ROOT を除外します。 

/subsystem=modcluster/mod-cluster-config=configuration:write-attribute(name=excluded-contexts,value=ROOT)

以下の管理 CLI コマンドを使用して、デフォルトのウェルカム web アプリケーションを無効にします。 

/subsystem=undertow/server=default-server/host=default-host/location=\/:remove
/subsystem=undertow/configuration=handler/file=welcome-content:remove
reload

デフォルトのウェルカム Web アプリケーションを設定する方法の詳細は、JBoss EAP開発ガイド のデフォルトの Welcome Web アプリケーションの設定を参照してください。

4.5.9. Undertow サブシステムのデフォルト設定の変更

JBoss EAP 7.2 よりも前のリリースでは、undertow サブシステムのデフォルト設定に 2 つの応答ヘッダーフィルターが含まれ、これらのフィルターは default-host によって各 HTTP 応答に追加されていました。

  • JBoss-EAP/7 に設定されていた Server
  • Undertow/1 に設定されていた X-Powered-By

使用中のサーバーに関する情報を無意識に公開しないようにするため、これらの応答ヘッダーフィルターはデフォルトの JBoss EAP 7.2 設定から削除されました。

以下の例は、JBoss EAP 7.1 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"/>
        <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"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </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 7.3 undertow サブシステムの新しいデフォルト設定を示しています。 

<subsystem xmlns="urn:jboss:domain:undertow:10.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <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"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>