17.4. サーバーの設定

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

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

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

サーバーのデフォルトの動作では、サーバーの起動中にリクエストをキューに置きます。デフォルトの動作を変更するには、ホストで queue-requests-on-start 属性を使用します。この属性がデフォルトの true に設定されている場合、サーバーの起動時に到達するリクエストはサーバーの準備が整うまで保留されます。この属性が false に設定された場合、サーバーが完全に起動する前に到達したリクエストは、デフォルトの応答コードで拒否されます。

属性の値に関わらず、サーバーが完全に起動するまでリクエストの処理は開始されません。

管理コンソールを使用して queue-requests-on-start 属性を設定するには、ConfigurationSubsystemsWeb (Undertow)Server と選択した後、サーバーを選択して 表示 をクリックし、Hosts タブを選択します。管理対象ドメイでは、設定するプロファイルを指定する必要があります。

注記

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

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

デフォルトの 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>

以下の例は、管理 CLI を使用してサーバーを設定する方法を示しています。管理コンソールを使用してサーバーを設定する場合は、ConfigurationSubsystemsWeb (Undertow)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 サブシステムの属性 の項を参照してください。

17.4.1. アクセスロギング

定義する各ホストにアクセスロギングを設定できます。

利用できるアクセスロギングオプションは、標準のアクセスロギングとコンソールアクセスロギングの 2 つです。

アクセスロギングに必要な追加の処理はシステムパフォーマンスに影響を与える可能性があることに注意してください。

17.4.1.1. 標準のアクセスロギング

標準のアクセスログは、ログエントリーをログファイルに書き込みます。

デフォルトでは、ログファイルは standalone/log/access_log.log ディレクトリーに保存されます。

標準のアクセスログを有効にするには、アクセスログデータを取得するホストに access-log 設定を追加します。以下の CLI コマンドは、デフォルトの JBoss EAP サーバーのデフォルトのホストの設定を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=access-log:add
注記

標準のアクセスログを有効にしたら、サーバーをリロードする必要があります。

デフォルトでは、アクセスログレコードには以下のデータが含まれます。

  • リモートホスト名
  • リモート論理ユーザー名 (常に -)
  • 認証されたリモートユーザー
  • Common Log Format 形式のリクエストの日時
  • 要求の最初の行
  • 応答の HTTP ステータスコード
  • HTTP ヘッダーを除く、送信済みバイト数。

この一連のデータは共通のパターンとして定義されます。組み合わせた別のパターンも使用できます。一般的なパターンでログ記録されているデータのほかに、組み合わせたパターンには、受信ヘッダーからの閲覧元およびユーザーエージェントが含まれます。

ログに記録されるデータは、pattern 属性を使用して変更できます。以下の CLI コマンドは、組み合わせたパターンを使用ための pattern 属性の更新を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=access-log:write-attribute(name=pattern,value="combined"
注記

pattern 属性を更新した後は、サーバーをリロードする必要があります。

表17.1 利用可能なパターン

パターン説明

%A

リモート IP アドレス

%A

ローカル IP アドレス

%b

送信済みバイト数 (HTTP ヘッダーまたは - を除く (バイトが送信されなかった場合))

%B

送信済みバイト数 (HTTP ヘッダーを除く)

%h

リモートホスト名

%H

要求プロトコル

%l

identd からのリモート論理ユーザー名 (常に - を返します。これは、Apache アクセスログの互換性のために含まれています)

%m

要求メソッド

%p

ローカルポート

%q

クエリー文字列 (? 文字を除く)

%r

要求の最初の行

%s

応答の HTTP ステータスコード

%t

Common Log Format 形式の日時

%u

認証されたリモートユーザー

%U

要求された URL パス

%v

ローカルサーバー名

%D

要求を処理するのにかかった時間 (ミリ秒単位)

%T

要求を処理するのにかかった時間 (秒単位)

%I

現在の要求スレッド名 (後でスタックトレースと比較できます)

common

%h %l %u %t "%r" %s %b

combined

%h %l %u %t "%r" %s %b "%{i,Referer}" "%{i,User-Agent}"

cookie、受信ヘッダーおよび応答ヘッダー、またはセッションから情報を書き込むこともできます。これは、Apache 構文に基づきます。

  • %{i,xxx} (受信ヘッダーの場合)
  • %{o,xxx} (送信応答ヘッダーの場合)
  • %{c,xxx} (特定のクッキーの場合)
  • %{r,xxx} (xxxServletRequest の属性)
  • %{s,xxx} (xxxHttpSession の属性)

このログには、追加の設定オプションも利用できます。詳細は、付録の access-log 属性を参照してください。

17.4.1.2. コンソールアクセスロギング

コンソールのアクセスログは、JSON データとして構造化された標準出力 (stdout) にデータを書き込みます。

各アクセスログレコードは、1 行のデータです。ログ集約システムにより、このデータを取得して処理できます。

コンソールアクセスロギングを設定するには、アクセスログデータをキャプチャーしたいホストに console-access-log 設定を追加します。以下の CLI コマンドは、デフォルトの JBoss EAP サーバーのデフォルトのホストの設定を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:add

デフォルトでは、コンソールアクセスログレコードには以下のデータが含まれます。

表17.2 デフォルトのコンソールアクセスログデータ

ログデータフィールド名説明

eventSource

リクエストのイベントのソース

hostname

要求を処理した JBoss EAP ホスト

bytesSent

JBoss EAP サーバーがリクエストへの応答として送信したバイト数

DateTime

要求が JBoss EAP サーバーによって処理された日時 JBoss EAP サーバーがリクエストを処理した日時

remoteHost

要求の発信先のマシンの IP アドレス

remoteuser

リモート要求に関連付けられたユーザー名

requestLine

送信された要求

responseCode

JBoss EAP サーバーによって返された HTTP 応答コード

デフォルトプロパティーはログ出力に常に含まれます。attributes 属性を使用して、デフォルトのログデータのラベルを変更できます。場合によっては、データ設定を変更することも可能です。attributes 属性を使用して、さらにログデータを出力に追加することもできます。

表17.3 利用可能なコンソールアクセスログデータ

ログデータフィールド名説明形式

authentication-type

要求に関連付けられたユーザーの認証に使用される認証タイプデフォルトラベル: authenticationType。このキーオプションを使用して、このプロパティーのラベルを変更します。

authentication-type{} authentication-type={key="authType"}

bytes-sent

リクエストに対して返されるバイト数。HTTP ヘッダーを除く。デフォルトラベル: bytesSent。このキーオプションを使用して、このプロパティーのラベルを変更します。

bytes-sent={} bytes-sent={key="sent-bytes"}

date-time

要求が受信および処理された日時。デフォルトラベル: dateTime。このキーオプションを使用して、このプロパティーのラベルを変更します。date-format を使用して、日付レコードのフォーマットに使用するパターンを定義します。このパターンは Java SimpleDateFormatter パターンである必要があります。date-format オプションが定義されている場合は、time-zone オプションを使用して日付や時間データのフォーマットに使用するタイムゾーンを指定します。この値は有効な java.util.TimeZone である必要があります。

date-time={key="<keyname>", date-format="<date-time format>"} date-time={key="@timestamp", date-format="yyyy-MM-dd'T'HH:mm:sSSS"}

host-and-port

リクエストによってクエリーされたホストおよびポート。デフォルトラベル: hostAndPort。このキーオプションを使用して、このプロパティーのラベルを変更します。

host-and-port{} host-and-port={key="port-host"}

local-ip

ローカル接続の IP アドレス。このキーオプションを使用して、このプロパティーのラベルを変更します。デフォルトラベル: locallp。このキーオプションを使用して、このプロパティーのラベルを変更します。

local-ip{} local-ip{key="localIP"}

local-port

ローカル接続のポート。デフォルトラベル: localPort。このキーオプションを使用して、このプロパティーのラベルを変更します。

local-port{} local-port{key="LocalPort"}

local-server-name

要求を処理したローカルサーバー名。デフォルトラベル: localServerName。このキーオプションを使用して、このプロパティーのラベルを変更します。

local-server-name {} local-server-name {key=LocalServerName}

path-parameter

リクエストに含まれる 1 つ以上のパスまたは URI パラメーター。name プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合は、出力の各 path パラメーター名の前に接頭辞が追加されます。

path-parameter{names={store,section}} path-parameter{names={store,section}, key-prefix="my-"}

predicate

述語コンテキストの名前。name プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合は、出力の各 path パラメーター名の前に接頭辞が追加されます。

predicate{names={store,section}} predicate{names={store,section}, key-prefix="my-"}

query-parameter

リクエストに含まれる 1 つ以上のパラメーターまたはクエリーパラメーター。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合は、出力の各 path パラメーター名の前に接頭辞が追加されます。

query-parameter{names={store,section}} query-parameter{names={store,section}, key-prefix="my-"}

query-string

リクエストのクエリー文字列。デフォルトラベル: localPort。このキーオプションを起用して、このプロパティーのラベルを変更します。include-question-mark プロパティーを使用して、クエリー文字列に疑問符を含めるかどうかを指定します。デフォルトでは、疑問符は含まれていません。

query-string{} query-string{key="QueryString", include-question-mark="true"}

relative-path

要求の相対パス。デフォルトラベル: relativePath。このキーオプションを使用して、このプロパティーのラベルを変更します。

relative-path{} relative-path{key="RelativePath"}

remote-host

リモートホスト名デフォルトラベル: remotehost。このキーオプションを使用して、このプロパティーのラベルを変更します。

remote-host{} remote-host{key="RemoteHost"}

remote-ip

リモート IP アドレス。デフォルトラベル: remoteIp。このキーオプションを使用して、このプロパティーのラベルを変更します。この難読化プロパティーを使用して、出力ログレコードの IP アドレスを難読化します。デフォルト値は false です。

remote-ip{} remote-ip{key="RemoteIP", obfuscated="true"}

remote-user

認証されたリモートユーザーデフォルトラベル: remoteuser。このキーオプションを使用して、このプロパティーのラベルを変更します。

remote-user{} remote-user{key="RemoteUser"}

request-header

要求ヘッダーの名前。構造化されたデータのキーはヘッダーの名前です。その値は名前付きヘッダーの値になります。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合には、出力の要求ヘッダー名の前に接頭辞が追加されます。

request-header{names={store,section}} request-header{names={store,section}, key-prefix="my-"}

request-line

リクエストの行。デフォルトラベル: requestLine。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-line{} request-line{key="Request-Line"}

request-method

要求メソッドデフォルトラベル: requestMethod。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-method{} request-method{key="RequestMethod"}

request-path

リクエストの相対パス。デフォルトラベル: requestPath。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-path{} request-path{key="RequestPath"}

request-protocol

要求のプロトコル。デフォルトラベル: requestProtocol。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-protocol{} request-protocol{key="RequestProtocol"}

request-scheme

要求の URI スキーム。デフォルトラベル: requestScheme。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-scheme{} request-scheme{key="RequestScheme"}

request-url

元の要求 URI。クライアントで指定した場合、ホスト名、プロトコルなどが含まれます。デフォルトラベル: requestUrl。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-url{} request-url{key="RequestURL"}

resolved-path

解決したパス。デフォルトラベル: resolvedPath。このキーオプションを使用して、このプロパティーのラベルを変更します。

resolved-path{} resolved-path{key="ResolvedPath"}

response-code

応答コード。デフォルトラベル: responseCode。このキーオプションを使用して、このプロパティーのラベルを変更します。

response-code{} response-code{key="ResponseCode"}

response-header

応答ヘッダーの名前。構造化されたデータのキーはヘッダーの名前です。その値は名前付きヘッダーの値になります。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合には、出力の要求ヘッダー名の前に接頭辞が追加されます。

response-header{names={store,section}} response-header{names={store,section}, key-prefix="my-"}

response-reason-phrase

応答コードのテキスト理由。デフォルトラベル: responseReasonPhrase。このキーオプションを使用してこのプロパティーのラベルを変更します。

response-reason-phrase{} response-reason-phrase{key="ResponseReasonPhrase"}

response-time

リクエストの処理に使われる時間。デフォルトラベル: responseTime。このキーオプションを使用して、このプロパティーのラベルを変更します。デフォルトの時間単位はミリ秒 (MILLISECONDS) です。利用可能な時間の単位は以下のとおりです。* NANOSECONDS * MICROSECONDS * MILLISECONDS * SECONDS

response-time{} response-time{key="ResponseTime", time-unit=SECONDS}

secure-exchange

交換がセキュアであったかどうかを示します。デフォルトラベル: secureExchange。このキーオプションを使用して、このプロパティーのラベルを変更します。

secure-exchange{} secure-exchange{key="SecureExchange"}

ssl-cipher

要求の SSL 暗号。デフォルトラベル: sslCipher。このオプションを使用して、このプロパティーのラベルを変更します。

ssl-cipher{} ssl-cipher{key="SSLCipher"}

ssl-client-cert

要求の SSL クライアント証明書。デフォルトラベル: sslclientcert。このキーオプションを使用して、このプロパティーのラベルを変更します。

ssl-client-cert{} ssl-client-cert{key="SSLClientCert"}

ssl-session-id

要求の SSL セッション ID。デフォルトラベル: sslSessionId。このキーオプションを使用して、このプロパティーのラベルを変更します。

ssl-session-id{} stored-response

要求に対する、保存した応答。デフォルトラベル: storedResponse。このキーオプションを使用して、このプロパティーのラベルを変更します。

stored-response{} stored-response{key="StoredResponse"}

thread-name

現在のスレッドのスレッド名。デフォルトラベル: threadName。このキーオプションを使用して、このプロパティーのラベルを変更します。

thread-name{} thread-name{key="ThreadName"}

transport-protocol

metadata 属性を使用して、アクセスログレコードに追加する追加の任意のデータを設定できます。metadata 属性の値は、アクセスログレコードに追加するデータを定義する key:value ペアのセットです。ペアのこの値は管理モデルの式になります。管理モデル式は、サーバーの起動またはリロード時に解決されます。キーと値のペアはコンマで区切られます。

以下の CLI コマンドは、追加のログデータ、ログデータのカスタマイズ、追加のメタデータなど、複雑なコンソールログ設定の例を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:add(metadata={"@version"="1", "qualifiedHostName"=${jboss.qualified.host.name:unknown}}, attributes={bytes-sent={}, date-time={key="@timestamp", date-format="yyyy-MM-dd'T'HH:mm:ssSSS"}, remote-host={}, request-line={}, response-header={key-prefix="responseHeader", names=["Content-Type"]}, response-code={}, remote-user={}})

結果として生成されるアクセスログレコードは以下の追加の JSON データに類似しています (注意: 以下の出力例は、読みやすさを考慮してフォーマットされています。実際の記録では、すべてのデータが単一の行として出力されます)。

{
    "eventSource":"web-access",
    "hostName":"default-host",
    "@version":"1",
    "qualifiedHostName":"localhost.localdomain",
    "bytesSent":1504,
    "@timestamp":"2019-05-02T11:57:37123",
    "remoteHost":"127.0.0.1",
    "remoteUser":null,
    "requestLine":"GET / HTTP/2.0",
    "responseCode":200,
    "responseHeaderContent-Type":"text/html"
}

以下のコマンドは、コンソールアクセスログを有効にした後にのログデータへの更新を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:write-attribute(name=attributes,value={bytes-sent={}, date-time={key="@timestamp", date-format="yyyy-MM-dd'T'HH:mm:ssSSS"}, remote-host={}, request-line={}, response-header={key-prefix="responseHeader", names=["Content-Type"]}, response-code={}, remote-user={}})

以下のコマンドは、コンソールアクセスログを有効にした後にカスタムメタデータへの更新を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:write-attribute(name=metadata,value={"@version"="1", "qualifiedHostName"=${jboss.qualified.host.name:unknown}}