Per-username Session Quota
このプラグインは、ユーザー名ごとのセッションクォータを強制します。
- セッションカウンターはユーザー名ごとに管理され、クラスター全体で同期されます。
- 設定されたクォータに達すると、認証は
quota_exceededエラーで拒否されます。 - 既存の
clientidでの再接続は追加のクォータを消費しません。 - ユーザー名ごとのクォータオーバーライドにより、カスタム制限、無制限セッション、または接続ブロックが可能です。
注意
client_attrs_init 設定で client_attrs.tns を設定し、ユーザー名をネームスペースとして使用できる場合は、ネームスペースベースの制限によってこの種のセッション制限を強制できます。 ネームスペース割り当てが異なるスキームに従う場合にのみ、このプラグインを使用してください。
設定
| フィールド | デフォルト | バリデーション | 説明 |
|---|---|---|---|
max_sessions_per_username | 100 | 正の整数(>= 1)である必要があります。1未満または非数値は拒否されます。 | ユーザー名ごとのデフォルト最大同時セッション数。個別のユーザー名はオーバーライドAPIでこの値を上書き可能です。 |
snapshot_min_age_ms | 300000 | 120000 から 900000 の範囲内である必要があります。範囲外の値はクランプされます。 | スナップショットの最小経過時間(ミリ秒)。これより古い場合に再構築がトリガーされます。大規模クラスターでの頻繁な再構築を防ぎます。 |
snapshot_request_timeout_ms | 5000 | 正の整数に変換可能な文字列も受け入れます。 | リストAPIのスナップショットリクエスト処理のタイムアウト時間(ミリ秒)。 |
プラグイン設定は標準のプラグイン設定APIで更新します:
PUT /api/v5/plugins/<name-vsn>/config
ランタイムAPI
プラグインはプラグインAPIゲートウェイを通じてランタイムAPIを公開します。
ベースパス:/api/v5/plugin_api/emqx_username_quota
EMQX 6.3.2以降、これらのエンドポイントを呼び出すダッシュボードユーザーまたはAPIキーは、plugin_api または system スコープを持っている必要があります。呼び出し元のロールとネームスペース権限も要求されたHTTPメソッドを許可している必要があります。管理者相当の system スコープが不要な場合は、制限された plugin_api スコープを使用してください。
セッションクエリ
GET /quota/usernames: アクティブなセッションを持つ全ユーザー名の一覧を取得GET /quota/usernames/:username: 単一ユーザー名の詳細を取得GET /metrics: プラグインのメトリクスをPrometheusテキスト形式でエクスポートPOST /kick/:username: 指定ユーザー名の全セッションをキック
スナップショット管理
DELETE /quota/snapshot: スナップショットの強制再構築
クォータオーバーライド
POST /quota/overrides: ユーザー名ごとのクォータオーバーライド設定DELETE /quota/overrides: ユーザー名ごとのクォータオーバーライド削除GET /quota/overrides: 全オーバーライド一覧取得
GET /quota/usernames
このエンドポイントは、毎回ライブのセッションデータをスキャンする代わりに、事前に構築されたスナップショットの結果を返します。
スナップショットは、ユーザー名ごとのセッション数の時点コピーで、カウント順にソートされており、効率的なカーソルベースのページネーションが可能です。スナップショットは非同期でバックグラウンドにて構築されキャッシュされます。現在のスナップショットが snapshot_min_age_ms より古い場合にのみ新規構築がトリガーされます。
最初のリクエストでスナップショットがまだ存在しない場合、サーバーは進行中の構築完了を待ちます。待機時間はリクエストのタイムアウトから1秒差し引いた時間までです。構築が間に合えば通常の 200 レスポンスを返します。間に合わなければ 503 を返し、部分的なデータを含みます。
クエリパラメータ:
limit: 正の整数、最大100(デフォルト100)used_gte: カーソルがない場合必須。最小セッション数フィルター。指定した数以上のセッションを持つユーザー名のみ含まれます。正の整数(>= 1)である必要があります。cursor: 前回のリスト呼び出しで返された不透明なカーソル。指定しない場合は最初のページを返します。
パラメータルール:
used_gteのみ(cursorなし):OK(最初のページ)cursorのみ(used_gteなし):OK(used_gteはカーソルに埋め込まれている)used_gteとcursor両方指定:400BAD_REQUEST。フィルターはカーソルに固定されているため。- 両方なし:400
BAD_REQUEST
動作:
- 結果は常にセッション数、次にユーザー名でソートされます。
- ページネーションはカーソルベースです。最初のページでは
cursorを省略します。 - 各項目には
username、リアルタイムのused、およびlimit(有効クォータ)が含まれます。 - リアルタイムの
usedがスナップショットのカウントと異なる場合、snapshot_usedが含まれ、キャッシュされた値と現在の値の両方を確認できます。
成功時レスポンス構造:
data: ユーザー名クォータエントリーmeta.limit: ページサイズ(ページネーション制限)meta.count: このページのエントリー数meta.total: スナップショット内の総エントリー数meta.next_cursor: 次ページ用カーソル(存在する場合)meta.snapshot: スナップショットメタデータnodegeneration(インクリメンタルなスナップショットID)taken_at_ms(スナップショット取得時刻のミリ秒)
エラー応答:
400 BAD_REQUEST:used_gteがない、またはused_gteとcursorが同時に指定された場合400 INVALID_CURSOR: カーソルが存在しないノードを参照しているか不正な形式503 SERVICE_UNAVAILABLE: スナップショット再構築中- ボディに
snapshot_build_in_progress: true、data、metaを含む data: 進行中のスナップショットから部分的に読み取った最初のページ(ビルド開始直後の場合は空の場合あり)meta.count: 部分的なエントリー数、meta.partial: true- 制限付きバックオフで同じリクエストを再試行してください
- ボディに
DELETE /quota/snapshot
即時にスナップショットの再構築を強制します。非同期で再構築を開始した後に {"status": "ok"} を含む 200 を返します。スナップショットはバックグラウンドで再構築されます。
GET /quota/usernames/:username
単一ユーザー名の詳細を返します。レスポンスフィールドは username、used、limit、clientids です。
ユーザー名にアクティブなセッションがない場合は 404 NOT_FOUND を返します。
GET /metrics
プラグインのPrometheusテキスト形式メトリクスを返します。レプリカントノードではリクエストはスナップショット所有コアノードに転送されます。
現在エクスポートされているメトリクス:
emqx_username_count: アクティブスナップショット内のユーザー名総数
POST /kick/:username
指定ユーザー名の全セッションをキックします。キックしたセッション数を示す {"kicked": N} を返します。
ユーザー名にアクティブなセッションがない場合は 404 NOT_FOUND を返します。
POST /quota/overrides
ユーザー名ごとのクォータオーバーライドを設定します。ボディはJSON配列です:
[
{"username": "user1", "quota": 1000},
{"username": "vip", "quota": "nolimit"},
{"username": "blocked", "quota": 0}
]オーバーライドの意味:
quota の値 | 意味 |
|---|---|
| 正の整数 | このユーザー名のカスタムセッション制限 |
"nolimit" | 無制限セッション(クォータ無効) |
0 | 接続禁止:新規接続をすべて拒否 |
オーバーライドはディスクに永続化され、クラスター全体にレプリケートされます。ユーザー名にオーバーライドがない場合は、グローバル設定の max_sessions_per_username が使用されます。
DELETE /quota/overrides
ユーザー名によるオーバーライドを削除します。ボディはユーザー名文字列のJSON配列です:
["user1", "blocked"]GET /quota/overrides
全オーバーライド一覧を返します。レスポンスは {"data": [{"username": "...", "quota": ...}, ...]} です。
スナップショットベースのリスト取得の仕組み
このセクションでは、GET /quota/usernames や GET /metrics のようなリスト形式APIに対して、プラグインがどのようにスナップショットを構築し提供しているかを説明します。
スナップショット所有者ルーティング
スナップショットはコアノード上で構築されます。GET /quota/usernames と GET /metrics は、稼働中のコアノードのソートリストの最初のノードに選ばれたスナップショット所有コアノードにルーティングされます。
ブルー/グリーンスナップショット
2つのスナップショットバッファ(ブルーとグリーン)を維持します。一方が読み取りリクエストに応答している間に、もう一方で次のスナップショットを構築します。構築完了後に役割を入れ替えます。これにより、再構築中も古いスナップショットが利用可能なため、データの空白が発生しません。
バックグラウンドスナップショット構築
スナップショットの再構築は、サーバーのブロックを避けるためにイールドベースのスロットリングを用いたバックグラウンドプロセスで実行されます。リストAPIは構築中も応答性を維持します。
運用上の考慮事項と制限
このセクションでは、本プラグインを本番運用する際に考慮すべきランタイムの挙動や制限について説明します。
接続バースト時のクォータ超過
クォータ判定は認証時に行われ、セッションカウンターの確定はセッションライフサイクルフックで行われます。特にクラスター環境で高い同時接続バーストが発生すると、短時間の同期ウィンドウが生じ、あるユーザー名の同時セッション数が max_sessions_per_username を一時的に超過することがあります。
実務上の意味:
- 本プラグインはクラスター全体でのクォータ強制を提供し、バースト負荷下で最終的に整合します。
- 極端な接続集中時には、瞬間的な厳密なクォータ強制は保証されません。
プラグイン起動時のブートストラップ動作
プラグインを稼働中のクラスターにインストールした場合、既存のクライアントセッションはフック登録前に確立されているため、起動時にローカルの全チャネルを走査して各セッションを登録し、クォータ状態をブートストラップします。
コアノードへのDB書き込み負荷を避けるため(特にレプリカントノードに多数の既存接続がある場合)、ブートストラップループはスロットリングされます:
- セッションは100件ずつバッチ登録されます。
- 各バッチ後、最後に書き込まれたレコードがローカルテーブルにレプリケートされるのを待ちます。ポーリング間隔は10msです。
- 10秒以内にレプリケーションが完了しない場合、エラーがログに記録され、
errorレベルのログとともにブートストラップは中断されます。 タイムアウト前に登録されたセッションは保持され、残りは再接続時のフック登録で自然に処理されます。
リストAPIの 503 応答の取り扱い
サーバーがビジー状態またはスナップショットを構築中の場合、リストAPIは 503 を返します。
503 レスポンスのボディには、進行中のスナップショットテーブルから部分的に読み取った最初のページの data 配列が含まれます。これにより、呼び出し元は空のレスポンスではなく、即時にベストエフォートのデータを受け取れます。meta.partial: true フラグはデータが不完全であることを示します。ビルド開始直後の場合、部分ページは空の場合があります。
APIクライアントへの推奨:
dataを確認し、利用可能な部分結果を取得してください。- 制限付きバックオフで再試行してください。
ダウンロード
各EMQXリリースのtarball:
| EMQXバージョン | プラグインバージョン | パッケージ |
|---|---|---|
| 6.3.0 | 1.2.3 | emqx_username_quota-1.2.3.tar.gz (sha256) |
| 6.3.1 | 1.2.3 | emqx_username_quota-1.2.3.tar.gz (sha256) |
| 6.3.2 | 1.2.3 | emqx_username_quota-1.2.3.tar.gz (sha256) |
| 6.3.3 | 1.2.3 | emqx_username_quota-1.2.3.tar.gz (sha256) |