Skip to content

Per-username Session Quota ​

このプラグインは、ユーザー名ごとのセッションクォータを強制します。

  • セッションカウンターはユーザー名ごとに管理され、クラスター全体で同期されます。
  • 設定されたクォータに達すると、認証は quota_exceeded エラーで拒否されます。
  • 既存の clientid での再接続は追加のクォータを消費しません。
  • ユーザー名ごとのクォータオーバーライドにより、カスタム制限、無制限セッション、または接続ブロックが可能です。

注意

client_attrs_init 設定で client_attrs.tns を設定し、ユーザー名をネームスペースとして使用できる場合は、ネームスペースベースの制限によってこの種のセッション制限を強制できます。 ネームスペース割り当てが異なるスキームに従う場合にのみ、このプラグインを使用してください。

設定 ​

フィールドデフォルトバリデーション説明
max_sessions_per_username100正の整数(>= 1)である必要があります。1未満または非数値は拒否されます。ユーザー名ごとのデフォルト最大同時セッション数。個別のユーザー名はオーバーライドAPIでこの値を上書き可能です。
snapshot_min_age_ms300000120000 から 900000 の範囲内である必要があります。範囲外の値はクランプされます。スナップショットの最小経過時間(ミリ秒)。これより古い場合に再構築がトリガーされます。大規模クラスターでの頻繁な再構築を防ぎます。
snapshot_request_timeout_ms5000正の整数に変換可能な文字列も受け入れます。リスト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 両方指定:400 BAD_REQUEST。フィルターはカーソルに固定されているため。
  • 両方なし:400 BAD_REQUEST

動作:

  • 結果は常にセッション数、次にユーザー名でソートされます。
  • ページネーションはカーソルベースです。最初のページでは cursor を省略します。
  • 各項目には username、リアルタイムの used、および limit(有効クォータ)が含まれます。
  • リアルタイムの used がスナップショットのカウントと異なる場合、snapshot_used が含まれ、キャッシュされた値と現在の値の両方を確認できます。

成功時レスポンス構造:

  • data: ユーザー名クォータエントリー
  • meta.limit: ページサイズ(ページネーション制限)
  • meta.count: このページのエントリー数
  • meta.total: スナップショット内の総エントリー数
  • meta.next_cursor: 次ページ用カーソル(存在する場合)
  • meta.snapshot: スナップショットメタデータ
    • node
    • generation(インクリメンタルなスナップショット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配列です:

json
[
  {"username": "user1", "quota": 1000},
  {"username": "vip", "quota": "nolimit"},
  {"username": "blocked", "quota": 0}
]

オーバーライドの意味:

quota の値意味
正の整数このユーザー名のカスタムセッション制限
"nolimit"無制限セッション(クォータ無効)
0接続禁止:新規接続をすべて拒否

オーバーライドはディスクに永続化され、クラスター全体にレプリケートされます。ユーザー名にオーバーライドがない場合は、グローバル設定の max_sessions_per_username が使用されます。

DELETE /quota/overrides ​

ユーザー名によるオーバーライドを削除します。ボディはユーザー名文字列のJSON配列です:

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.01.2.3emqx_username_quota-1.2.3.tar.gz (sha256)
6.3.11.2.3emqx_username_quota-1.2.3.tar.gz (sha256)
6.3.21.2.3emqx_username_quota-1.2.3.tar.gz (sha256)
6.3.31.2.3emqx_username_quota-1.2.3.tar.gz (sha256)