17.4. サーバーの設定
サーバーは Undertow のインスタンスを表し、複数の要素で設定されます。
- host
- http-listener
- https-listener
- ajp-listener
ホスト要素は仮想ホスト設定を提供し、3 つのリスナーはそのタイプの接続を Undertow インスタンスに提供します。
サーバーのデフォルトの動作では、サーバーの起動中にリクエストをキューに置きます。デフォルトの動作を変更するには、ホストで queue-requests-on-start
属性を使用します。この属性がデフォルトの true
に設定されている場合、サーバーの起動時に到達するリクエストはサーバーの準備が整うまで保留されます。この属性が false
に設定された場合、サーバーが完全に起動する前に到達したリクエストは、デフォルトの応答コードで拒否されます。
属性の値に関わらず、サーバーが完全に起動するまでリクエストの処理は開始されません。
管理コンソールを使用して queue-requests-on-start
属性を設定するには、Configuration
複数のサーバーを設定できるため、デプロイメントやサーバーを完全に分離できます。これは、マルチテナント環境などで便利です。
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 を使用してサーバーを設定する方法を示しています。管理コンソールを使用してサーバーを設定する場合は、Configuration
既存のサーバーの更新
既存のサーバーを更新するには、以下を設定します。
/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 属性を更新した後は、サーバーをリロードする必要があります。
パターン | 説明 |
---|---|
%A | リモート IP アドレス |
%A | ローカル IP アドレス |
%b |
送信済みバイト数 (HTTP ヘッダーまたは |
%B | 送信済みバイト数 (HTTP ヘッダーを除く) |
%h | リモートホスト名 |
%H | 要求プロトコル |
%l |
|
%m | 要求メソッド |
%p | ローカルポート |
%q |
クエリー文字列 ( |
%r | 要求の最初の行 |
%s | 応答の HTTP ステータスコード |
%t | Common Log Format 形式の日時 |
%u | 認証されたリモートユーザー |
%U | 要求された URL パス |
%v | ローカルサーバー名 |
%D | 要求を処理するのにかかった時間 (ミリ秒単位) |
%T | 要求を処理するのにかかった時間 (秒単位) |
%I | 現在の要求スレッド名 (後でスタックトレースと比較できます) |
common |
|
combined |
|
cookie、受信ヘッダーおよび応答ヘッダー、またはセッションから情報を書き込むこともできます。これは、Apache 構文に基づきます。
-
%{i,xxx}
(受信ヘッダーの場合) -
%{o,xxx}
(送信応答ヘッダーの場合) -
%{c,xxx}
(特定のクッキーの場合) -
%{r,xxx}
(xxx
はServletRequest
の属性) -
%{s,xxx}
(xxx
はHttpSession
の属性)
このログには、追加の設定オプションも利用できます。詳細は、付録の 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
デフォルトでは、コンソールアクセスログレコードには以下のデータが含まれます。
ログデータフィールド名 | 説明 |
---|---|
eventSource | リクエストのイベントのソース |
hostname | 要求を処理した JBoss EAP ホスト |
bytesSent | JBoss EAP サーバーがリクエストへの応答として送信したバイト数 |
DateTime | 要求が JBoss EAP サーバーによって処理された日時 JBoss EAP サーバーがリクエストを処理した日時 |
remoteHost | 要求の発信先のマシンの IP アドレス |
remoteuser | リモート要求に関連付けられたユーザー名 |
requestLine | 送信された要求 |
responseCode | JBoss EAP サーバーによって返された HTTP 応答コード |
デフォルトプロパティーはログ出力に常に含まれます。attributes
属性を使用して、デフォルトのログデータのラベルを変更できます。場合によっては、データ設定を変更することも可能です。attributes
属性を使用して、さらにログデータを出力に追加することもできます。
ログデータフィールド名 | 説明 | 形式 |
---|---|---|
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}}