設定リファレンス
読込先を確かめ、キーと単位を選びます。設定ごとの既定値、単位、入力範囲、変更したときの動作をまとめています。
説明を読みながらserver.yamlを作る → 設定ファイルジェネレータ
どこに書くか
| ファイル | 対象 | 反映 |
|---|---|---|
| conf/server.yaml | HTTP/TLS、セッション、管理、WebSocket、JTA、監視 | プロセス再起動 |
| conf/logging.yaml | コンテナログの出力先・レベル・ローテーション | プロセス再起動。最初のロガー取得前に設定を確定 |
| conf/users.yaml / cert-users.yaml | ユーザー・ロール / クライアント証明書DN | プロセス再起動 |
| conf/resources.yaml | サーバ共有DataSource / クエリログ | プロセス再起動 |
| WEB-INF/web.xml | 標準記述子、JSTLのcontext-param | webapp再配備 |
| WEB-INF/kohaku-web.xml | webapp個別のプール・authority・互換設定 | webapp再配備 |
YAMLの書き方
UTF-8・半角空白のインデントで書きます。入れ子と点区切りキーは同じ平坦キーへ変換されます。両方で同じキーを書いてはいけません。空値・null は既定値、"" は空文字として扱います。
# 入れ子
http:
port: 8080
# 点区切り(上の設定と同じファイルに重複して書かない)
http.port: 8080ファイル上限1 MiB、20,000行、1行8,192文字、入れ子32段、写像キー10,000、1列1,024要素です。server.yaml が無ければWARNして既定値で起動しますが、存在するファイルの読込失敗・構文破損・重複キーは起動失敗です。未知のサーバキーはWARNします。既知機能の数値・真偽値の打ち間違いを無害な既定値への復帰と期待しないでください。
時間の設定を読み解く
名前の末尾の Millis はミリ秒です。1000ミリ秒=1秒なので、30000は30秒、60000は1分、300000は5分です。Seconds は秒、Bytes はデータ量を表します。1 MiBは1,048,576バイトです。
readTimeout・keepAlive・requestTimeout・writeTimeoutの違い
例えば、ブラウザから画像をアップロードし、その結果を受け取り、続けて別のページを開く通信を考えます。以下はHTTP/1.1での待ち時間の説明です。
- 受信中のデータ待ち(readTimeout):送信の途中で次のデータが来なくなったとき、1回の読み取りで何秒待てるか。既定は30秒です。
- リクエスト全体の時間枠(requestTimeout):最初のデータが届いてから数える全体の期限。既定は60秒。少量ずつデータが届き続けていても、受信に使える時間枠は延びません。
- 応答の送信待ち(writeTimeout):結果を送り返す際、1回の書き込みが止まったときの期限。既定は30秒です。
- 次の要求を待つ時間(keepAliveTimeout):応答を返した接続を再利用するため、次の要求が来るまで保持する時間。既定は20秒で、期限を過ぎたら接続を閉じます。
例えば受信データが15秒ごとに届けば、1回のデータ待ちは30秒以内に収まっても、全体の時間枠60秒に達するとそれ以降の受信は許されません。アプリの処理時間やログイン状態の有効期限は別の仕組みです。
必要な待ち時間が分からない場合は「値を指定する」を選ばず、まず既定値を使えます。アップロード容量や利用者の回線速度、接続数を確認して調整してください。
エラーの番号・例外・起動失敗の読み方
HTTPステータスは、サーバがリクエストの結果を知らせる応答の番号です。例えば413なら「送った内容が大きすぎて、その要求を受け付けなかった」という意味です。ブラウザに表示される文言はアプリやブラウザによって変わるため、説明では番号に加えて実際の動作も記載しています。
WebSocketの終了理由の番号は、つながっていた通信を閉じる理由を相手に伝えるものです。1009は「メッセージが大きすぎる」、1008は「通信の規則に違反した」を表します。新しい接続を始める際のHTTP応答とは、使われる場面が違います。
例外は、アプリのプログラムへ処理の失敗を知らせる仕組みです。例外名はログやプログラムで原因を調べる手掛かりになります。利用者にどのエラー画面を返すかは、アプリのエラー処理にも左右されます。
起動を中止するは、設定が不正なためサーバを動かし始められないという意味です。該当する設定を修正してから、もう一度起動してください。
HTTP・リクエスト
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
http.enabled | true | 暗号化されていないHTTPでアクセスを受け付けるか。trueで有効、falseで無効。falseにする場合は、代わりにHTTPSのポートと証明書を設定する必要があります。 |
http.port | 8080 | HTTPの受付番号(ポート)。8080ならURLに「:8080」を付けてアクセスします。0〜65535で、0はOSに空き番号を選ばせます。HTTPSだけを使う場合も、この値の形式・範囲は検査されます。 |
http.host | 0.0.0.0 | アクセスを受け付けるサーバ側のアドレス。0.0.0.0は全IPv4アドレス、127.0.0.1は同じコンピュータからの接続だけを受け付けます。HTTPSにも共通で使用します。空文字は指定できません。 |
http.maxConnections | 1024 | 同時につなげておける通信回線の数。HTTPとHTTPSそれぞれにこの上限が適用されます。多くすると同時に受け付けられますが、メモリなどの使用量も増えます。1以上。 |
http.readTimeoutMillis | 30000 | 通信の続きを待つ時間。リクエストの受信中、1回の読み取りで次のデータが来るまで待てる時間です。既定の30000は30秒。短すぎると遅い回線の送信が途中で切れ、長すぎると止まった通信を長く保持します。待てる時間を過ぎると、そのリクエストの受信を打ち切って接続を閉じます。応答のHTTPステータスは408(受信の時間切れ)です。1以上・ミリ秒。 |
http.keepAliveTimeoutMillis | 20000 | 使い終わった接続で、次のリクエストが来るまで待つ時間。接続を再利用すると、画像などを続けて取得する際に接続し直す手間を減らせます。既定の20000は20秒。長くすると待機中の接続が増え、短くすると接続し直す機会が増えます。次のリクエストが来ないまま時間を過ぎると、待機中の接続を閉じます。その後のアクセスには新しい接続を使います。1以上・ミリ秒。 |
http.maxRequestBodyBytes | 2097152 | 1回のリクエストで送れる本文の最大サイズ。ファイルのアップロードやフォーム送信も対象です。既定2097152バイトは2 MiB。例えば既定の2 MiBを超える3 MiBのファイルを送ると、そのリクエストを受け付けず接続を閉じます。応答のHTTPステータスは413(送信内容が大きすぎる)です。必要なアップロード容量に合わせます。1以上・バイト。 |
http.requestTimeoutMillis | 60000 | 1つのリクエストの受信に使える全体の時間枠。最初の1バイトを受け取った時点から測り、その後のデータ待ちや未読本文の読み捨てに残り時間を適用します。少しずつ届いていても時間枠は延びません。既定60000は60秒。待てる時間を過ぎると、そのリクエストの受信を打ち切って接続を閉じます。応答のHTTPステータスは408(受信の時間切れ)です。1以上・ミリ秒。 |
http.writeTimeoutMillis | 30000 | 相手へ応答データを送る際、1回の書き込みに使える時間。相手がデータを受け取らず送信が止まったときに、接続を閉じるための期限です。既定30000は30秒。遅い回線への送信を許す時間と、止まった接続を保持する時間のバランスを取ります。1以上・ミリ秒。 |
http.maxKeepAliveRequests | 100 | 1本の接続を何回のリクエストまで使い回すか。既定100は100回。上限に達したリクエストの応答後に接続を閉じ、次のアクセスは新しい接続を使います。ログイン状態の有効期限は別の仕組みです。1以上。 |
http.upgradeIdleTimeoutMillis | 300000 | HTTPから別の通信方式へ切り替えた接続で、受信を待ち続けられる時間。切替はHTTP Upgradeと呼びます。既定300000は5分。WebSocketの利用者ごとの無通信時間はwebsocket.maxSessionIdleTimeoutMillisで別に設定します。1以上・ミリ秒。 |
http.upgradeDrainTimeoutMillis | 2000 | サーバ停止時に、HTTPから切り替えた接続をまとめて閉じるための時間枠。全接続の回収処理に使える合計時間で、接続1本ごとの待ち時間ではありません。既定2000は2秒。1〜600000ミリ秒(最大10分)。 |
http.maxParameterCount | 10000 | フォームやURLの「名前=値」の項目数の上限。大量の項目による処理・メモリ消費を抑えます。項目数が上限を超えていると、アプリがフォームやURLの値を読む処理が失敗します。getParameterなどのAPIがIllegalStateExceptionという例外(アプリへ失敗を伝える通知)で失敗を知らせます。アプリ側で対応する必要があります。1以上。 |
http.canonicalAuthority | 未設定 | アプリが生成するURLやログイン元の確認に使う公開先の名前。例: app.example.jp:443。host[:port]形式で、アプリ個別の宣言が優先されます。未設定なら接続先のローカル数値アドレスを使います。プロキシが送るHost/Forwardedを信頼する設定は兼ねません。 |
http.allowTrace | false | 受け取ったHTTPリクエストを返す、調査用のTRACEメソッドを許可するか。既定falseではTRACEを受け付けず、HTTPステータス405(この操作は許可されていない)を返します。TRACEを必要とする明確な用途がなければ既定値を使います。true/false。 |
http.poweredByHeader | true | 応答にサーバ製品情報のX-Powered-Byヘッダを付けるか。trueで送出、falseで抑止。アプリの内容とは別に返す付加情報です。 |
セッション・認証
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
session.cookie.httpOnly | true | ログイン状態などを識別するCookieを、ブラウザ上のJavaScriptから読めなくするか。trueならHttpOnly属性を付けます。アプリのweb.xmlやSessionCookieConfigがこの既定値を上書きできます。true/false。 |
session.cookie.sameSite | Lax | 別のサイトからのアクセス時に、ログイン状態などのCookieを送る条件。Strictは同一サイト中心、Laxは通常のリンク移動などにも対応、Noneは別サイトからの送信も許可します。NoneにはSecure付きCookieが必要で、平文HTTPではLaxとして扱います。Lax/Strict/None(大小不問)。 |
session.urlTracking.enabled | false | Cookieの代わりにURLへセッション識別子を付けて、利用者の状態を追跡できるようにするか。既定falseはURL追跡を禁止し、URL追跡を使うと宣言したアプリは読み込めず、そのアプリを公開できません。trueでは既定の追跡方法がCOOKIE+URLになります。true/false。 |
session.maxSessions | 8192 | アプリ1個ごとに、ログイン状態などを保持するセッションを何件まで作れるか。既定8192件。上限に達すると新しいセッションを作れず、呼び出したアプリへ例外で失敗を知らせます。アプリが対応しなければ通常はHTTP 500(サーバ側で処理できなかった)になります。既存のセッションは追い出しません。破棄の後片付け中も件数に含みます。1以上。 |
security.formLogin.originCheck | true | フォームログインの送信元が、想定するサイトか確認するか。trueならj_security_checkへのPOSTのOrigin、無ければRefererからホスト・ポートを確認します。送信元が一致しない場合や、両方のヘッダが無く送信元を確認できない場合は、ログインの要求を受け付けません。HTTPステータス403(アクセスを許可しない)を返します。これらはブラウザが送信元を示すHTTPヘッダです。true/false。 |
security.auth.maxConcurrentVerifications | 起動時のCPU数の半分(最低1) | パスワードが正しいか確認する計算を、サーバ全体で同時に何件まで行うか。未指定なら起動先で使えるCPU数の半分、最低1件を自動設定します。混雑して待ち時間内に枠が空かないと、BASIC/FORMログインは受け付けずHTTP 503(現在は混雑している)とRetry-After: 1(1秒後の再試行の案内)を返します。アプリからのlogin()は例外で失敗を知らせます。1以上。 |
realm.file | conf/users.yaml | ログインに使うユーザー・パスワード・ロールの設定ファイル。ロールは利用者に許可する役割です。kohaku.homeからの相対パスか絶対パスを指定します。パスを指定した場合、その場所にサーバが読み取れるファイルが必要です。未指定で既定ファイルが無ければ、ユーザー情報を読み込まず起動するため、このファイルを使うパスワード認証は利用できません。 |
security.auth.verificationWaitMillis | 1000 | パスワード確認の処理枠が埋まっているとき、空くのを何ミリ秒まで待つか。既定1000は1秒。0なら待たずに混雑として扱います。長くするとログインを待てますが、待っている間も接続の枠を使います。0〜60000ミリ秒(最大1分)。 |
realm.certFile | conf/cert-users.yaml | クライアント証明書の持ち主名(Subject DN)とユーザー名を結び付けるファイル。CLIENT-CERT認証に使います。パスを指定した場合、その場所にサーバが読み取れるファイルが必要です。未指定なら既定ファイルは任意です。 |
配備・作業領域
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
webapps.dir | webapps | 実行したいアプリを置くフォルダ。WARというアプリ配布ファイルや展開済みアプリをここから読み込みます。kohaku.homeからの相対パスか絶対パスを指定します。 |
work.dir | temp | アプリ配布ファイル(WAR)を展開する作業フォルダ。アプリ名と世代番号ごとに領域を分け、入れ替え前後を区別します。kohaku.homeからの相対パスか絶対パスを指定します。 |
hotdeploy.enabled | false | サーバを動かしたまま、アプリの追加・削除・WAR更新を定期的に検出して反映するか。trueで監視、falseで停止。監視の間隔はhotdeploy.intervalMillisで指定します。 |
hotdeploy.intervalMillis | 3000 | アプリの置き場に変更がないか見に行く間隔。既定3000は3秒。短いと変更の反映が早くなり、確認処理の回数も増えます。hotdeploy.enabledがtrueのときは1以上・ミリ秒。falseのときはサーバ側でこの値を検査しません。 |
TLS
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
https.port | 未設定(無効) | 暗号化通信(HTTPS)の受付番号。通常のHTTPとは別に使います。1〜65535で、0は指定できません。指定する場合はサーバ証明書・秘密鍵のhttps.keyStoreも必須です。 |
https.keyStore | 未設定 | サーバが自分の身元を示す証明書と、その証明に使う秘密鍵をまとめたJKS形式のファイル。サーバが読み取れる通常ファイルが必要です。相対パスはkohaku.home基準。https.portと併せて指定します。 |
https.keyStorePassword | 空文字 | 証明書・秘密鍵のファイルを開くためのパスワード。ファイル内の秘密鍵を取り出すパスワードも同じ値という前提です。生成YAMLには入力した値が含まれます。 |
https.clientAuth | NONE | 接続してくる利用者にも証明書を求めるか。NONEは求めず、WANTは求めるが無くても接続可、NEEDは必須です。提示された証明書は検証されます。NONE/WANT/NEED(大小不問)。true/required/optionalという表記は使えません。 |
https.trustStore | 未設定(keystoreを使用) | 利用者の証明書を検証する際に、信頼してよい証明書を収めたファイル。clientAuthをWANTまたはNEEDにした場合だけ指定できます。読み取れる通常ファイルが必要。未指定ならサーバのkeyStoreを使います。 |
https.trustStorePassword | keyStorePasswordを継承 | 利用者の証明書を検証するファイルを開くパスワード。未指定ならkeyStorePasswordを引き継ぎます。trustStoreを指定せず、この項目だけ書くと、サーバは設定不備として起動を中止します。使うファイルのtrustStoreも指定するか、この項目を未指定に戻します。 |
https.trustStoreType | JKSを継承 | 利用者の証明書を検証するファイルの形式名(例: JKS)。未指定ならサーバのkeyStoreの形式JKSを引き継ぎます。trustStoreを指定せず、この項目だけ書くと、サーバは設定不備として起動を中止します。使うファイルのtrustStoreも指定するか、この項目を未指定に戻します。 |
アクセスログ・診断・管理
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
server.stopTimeoutMillis | 45000 | サーバ停止時の後片付けで、サーバが管理する待ちに使える合計時間。既定45000は45秒。各処理は自分の待ち時間と、この合計時間の残りの短い方を使います。アプリ内の処理など全ての待ちを制限する設定ではないため、停止が必ず45秒以内に終わる保証はありません。期限を過ぎてもJVMを強制終了せず後片付けを続けます。1〜600000ミリ秒(最大10分)。 |
accesslog.enabled | false | 誰がいつどのURLへアクセスしたか、応答結果などをアクセスログへ記録するか。trueで有効、falseで無効。Common Log Formatという共通形式で記録します。 |
accesslog.file | logs/access.log | アクセス記録を保存するファイル。kohaku.homeからの相対パスか絶対パスを指定します。親フォルダは作成されます。accesslog.enabledで記録を有効にします。 |
accesslog.rotate.maxBytes | 0 | アクセスログがこのサイズになったら、古いファイルを退避して新しいファイルへ切り替えます。0以上・バイト。0はサイズによる切替を無効にします。1件の記録の書き込みで上限を超える場合はあります。 |
accesslog.rotate.every | 空文字 | アクセスログを一定時間ごとに新しいファイルへ切り替える間隔。1dは1日、12hは12時間、30mは30分。正整数+d/h/mで指定し、空文字は時間による切替を無効にします。ファイルを開いた時刻から数えます。 |
accesslog.rotate.keep | 10 | 切り替えた古いアクセスログを何世代残すか。既定10は過去10世代。古い記録を多く残すほど、保存に必要なディスク容量も増えます。1以上。 |
diagnostics.maxTotalBytes | 1073741824 | 障害調査用のファイルに使えるディスク容量の合計上限。0以上・バイト。既定1073741824は1 GiB。0は調査用ファイルを残さない設定です。 |
diagnostics.minFreeBytes | 268435456 | 調査用ファイルを保存するときに必要なディスクの空き容量。空き容量がこれより少ない場合は、新しい調査用ファイルを保存しません。ディスクを使い切らないための設定です。0以上・バイト。既定268435456は256 MiB。0は空き容量を理由に拒否しません。 |
diagnostics.bus.queueSize | 4096 | 診断の出来事を、受け手へ届けるまで一時的に待たせておける件数。配送待ちの列が満杯になると、新しい出来事は受け手へ届けず、その件数だけを数えます。大きくすると一時的な集中に対応できますが、メモリ使用量も増えます。1以上。 |
diagnostics.bus.ringSize | 256 | 最近起きた診断の出来事を、メモリに何件残すか。新しい出来事が入ると古いものを順に入れ替えます。後から直近の状況を確認するための件数です。1以上。 |
diagnostics.crashDetection.enabled | true | 前回のサーバが正常に終了しなかったことを、次の起動時に報告するか。起動・正常終了の印を使って判定します。true/false。 |
requestId.acceptIncoming | false | 外部から受け取った追跡番号を、アクセスの識別番号に引き継ぐか。trueなら妥当なtraceparentヘッダのtrace-idを使います。これらは複数のシステムで同じ処理を追うための番号です。falseまたは不正な値なら自分で採番します。 |
requestId.responseHeader | X-Request-Id | アクセスの識別番号を、応答のどのHTTPヘッダ名で返すか。既定X-Request-Idは、利用者の問い合わせとログを対応付ける手掛かりになります。妥当なHTTPヘッダ名を指定します。空文字なら応答に付けません。 |
concurrent.maxManagedThreads | 256 | アプリが管理用APIで作る処理用スレッドを、サーバ全体で何本まで保持するか。スレッドは処理を実行する単位です。開始前や撤去したアプリの生き残りも数えます。上限に達すると新しいスレッドを作れません。作成APIのnewThreadはnull(作成結果がないことを示す値)を返します。1以上。 |
concurrent.hungTaskScan.enabled | true | 管理対象の処理が長時間止まっていないか、定期的に調べるか。この状態をハングと呼びます。trueで検査を有効にします。true/false。 |
concurrent.hungTaskScan.intervalMillis | 60000 | 管理対象の処理が止まっていないか調べる間隔。既定60000は1分。短いと検査の機会が増えます。hungTaskScan.enabledがtrueのときは1以上・ミリ秒。falseのときはサーバ側でこの値を検査しません。 |
management.port | 未設定(無効) | 稼働状態の確認や監視に使う、管理用の受付番号。通常のアプリ用ポートと分けます。未指定なら管理用の待受は起動しません。0〜65535、0を指定するとOSが空いている番号を選びます。0以外でアプリ用ポートと同じ番号にすると、サーバは起動を中止します。同じ受付番号を両方で使えないため、別の番号を指定します。 |
management.host | 127.0.0.1 | 管理用の接続を受け付けるアドレス。既定127.0.0.1は同じコンピュータからだけ接続できます。空文字や空白だけの値は指定できません。management.port未指定なら警告して無視しますが、値が単一の文字列などであることは検査します。 |
management.maxConnections | 16 | 管理用ポートへ同時に接続できる数。アプリ用とは別の枠なので、アプリが混雑したときの監視用接続を確保できます。1以上。 |
トランザクション・非同期タスク
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
transaction.maxActive | 1024 | まとめて成功・取り消しを扱う処理(トランザクション)を、サーバ全体で同時に何件まで進めるか。上限に達すると、新しいトランザクションを開始できません。開始APIのbeginは、呼び出したアプリにSystemExceptionという例外で開始失敗を伝えます。1以上。 |
transaction.reapAfterMillis | 30000 | トランザクションの期限が切れてから、強制的な後片付けを始めるまでの追加猶予。処理本体の期限はdefaultTimeoutSecondsなどで別に決まります。0〜86400000ミリ秒(最大24時間)。0は定期的な強制回収を停止します。 |
transaction.stopTimeoutMillis | 30000 | サーバ停止時、まだ残っているトランザクションを中止する処理に使える時間枠。既定30000は30秒。短すぎると後片付けが終わる前に期限を迎え、長いと停止に時間がかかります。サーバ停止中はserver.stopTimeoutMillisの残り時間が先に尽きれば、この値より早く待ちを切り上げます。1以上・ミリ秒。 |
transaction.defaultTimeoutSeconds | 300 | 1件のトランザクションを進められる既定の時間。アプリがsetTransactionTimeoutで別の期限を指定していない場合に使います。既定300は5分。開始begin時にその処理の期限が決まります。1〜86400秒。単位はミリ秒ではなく秒です。 |
transaction.maxSynchronizations | 10000 | 1件のトランザクションに登録できる、完了前後に呼ぶ処理の数。これをSynchronizationコールバックと呼びます。登録が増え続けてメモリを消費しないように上限を設けます。1以上。 |
transaction.serverMaxSynchronizations | 100000 | 完了前後に呼ぶ処理(Synchronizationコールバック)の登録数を、サーバ全体で何件まで保持するか。1件ごとのmaxSynchronizationsに加え、全体でもメモリ消費を抑えます。1以上。 |
transaction.maxXaResources | 64 | 1件のトランザクションに登録できる、XA対応のDBなどの資源の数。XAは複数の資源をまとめて確定・取り消しするための仕組みです。XAResource登録数の上限。1以上。 |
transaction.maxRmBranches | 64 | 1件のトランザクションで、異なるDBなどの管理先ごとに作る処理の枝の上限。これをRM branchと呼びます。1以上で、登録できる資源数maxXaResources以下にします。 |
transaction.maxLocalParticipants | 64 | 1件のトランザクションに参加できる、XA非対応のDB接続などの数。複数を参加させると、途中の失敗で一部だけ確定する可能性があり、まとめて成功・取り消しする保証はありません。1以上。 |
async.maxTasks | 4096 | 利用者への応答処理から分けて動かす非同期処理(AsyncContext.start)を、サーバ全体で同時に何件まで実行するか。上限に達すると新しい非同期処理を開始できません。呼び出したアプリにIllegalStateExceptionという例外で開始失敗を伝えます。1以上。 |
async.maxTasksPerWebapp | 1024 | AsyncContext.startによる非同期処理を、アプリ1個ごとに同時に何件まで実行するか。1つのアプリがサーバ全体の処理枠を使い切るのを抑えるための、アプリ別の上限です。1以上。 |
async.maxIoCallbacks | 4096 | データが読める・書けるようになったことをアプリへ知らせる処理(ReadListener/WriteListener)を、サーバ全体で同時に何件まで保持するか。既定4096件。async.maxTasksとは別の枠です。上限に達すると新しいリスナーを登録できず、アプリへIllegalStateExceptionという例外で失敗を知らせます。1以上。 |
async.maxIoCallbacksPerWebapp | 1024 | ReadListener/WriteListenerによる通知処理を、アプリ1個ごとに同時に何件まで保持するか。既定1024件。登録から通知用スレッドの終了まで枠を使うため、長く生きる接続も上限に数えます。WebSocketサーバの独自スレッドはこの枠の対象外です。1以上。 |
WebSocket
| キー | 未指定時の値 | 意味・制約 |
|---|---|---|
websocket.enabled | true | ブラウザとサーバが接続を保ち、双方からメッセージを送れるWebSocketを使うか。チャットやリアルタイム通知などに使う通信方式です。trueで有効、falseで無効。 |
websocket.maxSessionIdleTimeoutMillis | 300000 | WebSocketの利用者ごとの接続で、送受信がない状態を何ミリ秒まで許すか。既定300000は5分、0は無期限。アプリはSession APIで上書きできます。0以上・ミリ秒。HTTP側のupgradeIdleTimeoutMillisとは別の期限です。 |
websocket.asyncSendTimeoutMillis | 20000 | WebSocketの非同期送信で、送信完了を待てる既定の時間。非同期は完了を待たずに次の処理へ進む方式です。既定20000は20秒、0は無期限。アプリがAPIで上書きできます。0以上・ミリ秒。 |
websocket.maxTextMessageBufferBytes | 8192 | WebSocketの文字メッセージを受け取る際、初期設定で使うバッファ(一時的な保存領域)のサイズ上限。文字数ではなくバイト数です。既定8192は8 KiB。1以上・バイト。 |
websocket.maxBinaryMessageBufferBytes | 8192 | WebSocketで画像などのバイナリデータを受け取る際、初期設定で使うバッファ(一時的な保存領域)のサイズ上限。既定8192は8 KiB。1以上・バイト。 |
websocket.sendTimeoutMillis | 20000 | WebSocketで接続後のデータを送り出す際、1回の書き込みに使える時間。相手が受け取らず送信が止まった接続を長く保持しないための期限です。Basic/Asyncの両送信方式に共通。既定20000は20秒。1以上・ミリ秒。 |
websocket.maxAsyncQueueDepth | 64 | WebSocketの非同期送信で、送信待ちにできるメッセージの件数。相手の受信が遅いと待ち行列が増えます。件数の上限を設け、待ち行列によるメモリ消費を抑えます。1以上。 |
websocket.maxAsyncQueueBytes | 1048576 | WebSocketの非同期送信で、送信待ちのデータを合計何バイトまで保持するか。件数のmaxAsyncQueueDepthと併せて、少数の大きなメッセージによるメモリ消費も抑えます。既定1048576は1 MiB。1以上・バイト。 |
websocket.sendLockTimeoutMillis | 20000 | 同じWebSocket接続へ別の処理が送信中のとき、自分の送信順番を待てる時間。送信内容が混ざらないよう順番を制御する仕組みを送信ロックと呼びます。既定20000は20秒。1以上・ミリ秒。 |
websocket.sessionCloseTimeoutMillis | 5000 | 自分からWebSocket接続を閉じる通知を送った後、相手から終了の返事が来るまで待つ時間。返事のない相手を待ち続けないための期限です。既定5000は5秒。1以上・ミリ秒。 |
websocket.maxFrameBytes | 65536 | WebSocketの1つの通信片(フレーム)に入れられるデータ量の上限。1つのメッセージを複数のフレームに分けて送ることがあります。上限を超えるデータが届くと、通信を続けずそのWebSocket接続を閉じます。相手へ通知する終了理由の番号は1009(メッセージが大きすぎる)です。1以上・バイト。 |
websocket.maxMessageBytes | 1048576 | 分割して届いたWebSocketメッセージを、メモリ上で1つに組み立てた後のサイズ上限。maxFrameBytesは通信片ごと、この項目はメッセージ全体に適用します。上限を超えると、そのWebSocket接続を閉じます。相手へ通知する終了理由の番号は1009(メッセージが大きすぎる)です。1以上・バイト。 |
websocket.maxStreamMessageBytes | 0 | WebSocketメッセージを一括保持せず、少しずつ読み取るストリーム方式でのサイズ上限。0は無制限で、明示した場合だけ大きさを制限します。0以上・バイト。 |
websocket.maxFragmentsPerMessage | 1024 | 1つのWebSocketメッセージを何個の通信片まで分割して送れるか。極端に細かく分けた送信による処理負荷を抑えます。上限を超えると、そのWebSocket接続を閉じます。相手へ通知する終了理由の番号は1009(メッセージが大きすぎる)です。1以上。 |
websocket.maxPingRatePerSecond | 20 | 相手が接続確認のために送るpingを、1秒に何回まで受け付けるか。接続確認が上限を超えて届くと、まず全てには返事をせず回数を抑えます。それでも多すぎる場合は、そのWebSocket接続を閉じます。終了理由の番号は1008(通信の規則違反)です。1〜1000000回/秒。 |
websocket.maxFrameRatePerSecond | 500 | WebSocketの通信片(フレーム)を、1秒に何個まで受け付けるか。小さなデータを大量に送る相手の処理負荷を抑えます。上限を超える頻度で届くと、そのWebSocket接続を閉じます。相手へ通知する終了理由の番号は1008(通信の規則違反)です。1〜1000000回/秒。 |
websocket.maxEmptyFrameRatePerSecond | 50 | データを持たないWebSocketの通信片(空フレーム)を、1秒に何個まで受け付けるか。意味のない通信が大量に届くのを抑えます。上限を超える頻度で届くと、そのWebSocket接続を閉じます。相手へ通知する終了理由の番号は1008(通信の規則違反)です。1〜1000000回/秒。 |
websocket.maxControlFrameRatePerSecond | 20 | 接続確認や終了通知など、WebSocketを制御する通信片を、1秒に何個まで受け付けるか。制御だけを大量に繰り返す通信を抑えます。上限を超える頻度で届くと、そのWebSocket接続を閉じます。相手へ通知する終了理由の番号は1008(通信の規則違反)です。1〜1000000回/秒。 |
websocket.maxRequestedExtensions | 32 | WebSocketの接続開始時に、追加の通信機能(拡張機能)をいくつまで要求できるか。要求の解析が重くなりすぎるのを抑えます。要求する拡張機能の数が上限を超えると、WebSocket接続を開始しません。接続開始のHTTP応答は400(要求の内容に問題がある)です。1以上。 |
websocket.maxConnections | 512 | 同時に保持できるWebSocket接続数。接続数が上限に達していると、新しいWebSocket接続を受け付けません。接続開始のHTTP応答は503(現在は受け付ける余裕がない)です。WebSocketに独立した枠ですが、接続はHTTPの接続枠も使います。1以上。 |
websocket.maxClosingConnections | 128 | こちらからWebSocketの終了通知を送り、相手の返事を待っている接続を同時に何本まで保持するか。この状態をCLOSINGと呼びます。この待機枠が満杯なら、相手の返事を待たずに接続を閉じます。1以上。 |
websocket.client.maxPendingConnections | 256 | アプリがWebSocketで外部サーバへつなぐ際、接続中の試みを同時に何件まで保持するか。WebSocketContainerというクライアント用の実体ごとの上限です。1以上。 |
websocket.clientDrainTimeoutMillis | 2000 | アプリ終了時、外部へのWebSocket接続をまとめて閉じるための時間枠。contextDestroyedでの回収フェーズ全体に適用し、接続1本ごとの待ち時間ではありません。既定2000は2秒。1〜600000ミリ秒(最大10分)。 |
その他の設定
logging.yamlの全キー、resources.yamlのDataSource設定、JSTL context-param はそれぞれの章にあります。設定キーの一覧は JSON形式 でも保存しています。