EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ
お問い合わせ

NATS プロトコルゲートウェイ ​

EMQX 5.10.0 以降、EMQX は NATS プロトコル に基づく NATS プロトコルゲートウェイを導入しました。これにより、EMQX は NATS クライアントからの接続を受け入れ、MQTT とのメッセージ相互運用を実現できます。本ドキュメントでは、その機能概要と NATS ゲートウェイの有効化および設定手順について説明します。

機能概要 ​

NATS プロトコルゲートウェイは現在、以下の主要な機能をサポートしています。

プロトコルサポート ​

  • NATS プロトコルのメッセージタイプを完全サポート：
    • 接続およびセッション管理：INFO、CONNECT
    • メッセージのパブリッシュ／サブスクライブ：PUB、HPUB、SUB、UNSUB
    • メッセージ配信および応答：MSG、HMSG
    • ハートビートおよびステータス：PING、PONG、+OK、-ERR
  • Verbose モード対応：クライアントが CONNECT verbose=true で接続した場合に応答確認を有効化。
  • 豊富な認証方式をサポート：Token、NKey、JWT、ユーザー名／パスワード認証に対応。

MQTT との相互運用 ​

  • MQTT との双方向メッセージ相互運用：
    • NATS クライアントからパブリッシュされたメッセージを MQTT パブリッシュに変換。
    • MQTT メッセージを対応するトピックをサブスクライブしている NATS クライアントに転送。
  • NATS ワイルドカードサブスクリプションをサポートし、自動的に MQTT 互換のトピック形式に変換。
  • Queue Group の共有サブスクリプションをサポート：NATS の Queue Group サブスクリプションを MQTT の共有サブスクリプション形式に変換。
  • リクエスト／リプライモードをサポート：
    • NATS クライアントからのリクエストを MQTT リクエストに変換。
    • 対象トピックに MQTT サブスクライバーが存在しない場合は、EMQX が迅速にエラー応答を返却。

ネットワークおよび接続性 ​

  • 複数のトランスポートプロトコルに対応：TCP、TLS、WebSocket（WS）、および WebSocket over TLS（WSS）。

NATS と MQTT 間のクロスプロトコルメッセージング ​

NATS プロトコルはパブリッシュ／サブスクライブモデルと完全に互換性があり、NATS ゲートウェイを介して MQTT メッセージングと相互運用します。変換ルールは以下の通りです。

  • PUB および HPUB メッセージはパブリッシュ操作として扱われます：
    • トピックは PUB メッセージの subject フィールドから派生します。例：t.a は MQTT トピック t/a に変換されます。
    • メッセージのペイロードは PUB メッセージの本文から直接取得します。
    • クライアントが CONNECT verbose=1 で接続した場合、変換後の MQTT メッセージは QoS 1 を使用し、それ以外は QoS 0 となります。
  • SUB メッセージはサブスクリプション要求として扱われます：
    • トピックは SUB メッセージの subject フィールドから派生します。例：t.a は MQTT トピック t/a に変換されます。
    • QoS は同様のルールに従い、verbose=1 で QoS 1、それ以外で QoS 0。
    • ワイルドカードをサポートします。例：*.b.> は +/b/# に変換されます。
    • Queue Group をサポート。SUB メッセージの Queue Group 値は MQTT 共有サブスクリプションのグループ名に変換されます。
  • UNSUB メッセージはサブスクリプション解除要求として扱われ、サブスクリプション ID（sid）を使って解除対象を特定します。

TIP

NATS ゲートウェイはパブリッシュ／サブスクライブ操作に対する独自のアクセス制御を実装していません。トピック権限は統一された認可設定で管理してください。

NATS ゲートウェイの有効化 ​

EMQX 5.10.0 以降、NATS ゲートウェイは以下の3つの方法で有効化できます。

  • ダッシュボードから
  • REST API を使用して
  • base.hocon 設定ファイルを編集して

TIP

クラスター環境では、ダッシュボードまたは REST API で行った設定は自動的に全ノードに適用されます。特定ノードのみ設定を反映したい場合は、そのノードの base.hocon 設定ファイルを使用してください。

ダッシュボードからの有効化 ​

EMQX ダッシュボードから NATS ゲートウェイを素早く有効化する手順：

  1. 左メニューの 管理 -> ゲートウェイ に移動します。
  2. ゲートウェイ ページで NATS を探し、操作 列の 設定 ボタンをクリックして NATS 初期設定 ウィザードを開きます。
  3. ウィザードの手順に従います：
    • 基本設定 ではデフォルト値を受け入れ、次へ をクリック。
    • リスナー ではリスナーを設定するかスキップして 次へ をクリック。 （リスナーの詳細設定は リスナーの追加 を参照してください。）
    • 有効化 をクリックして NATS ゲートウェイを起動。

有効化が完了すると、ゲートウェイ ページにリダイレクトされ、NATS ゲートウェイの状態が 有効 と表示されます。

REST API からの有効化 ​

REST API を使用して NATS ゲートウェイを有効化する例：

bash
curl -X 'PUT' 'http://127.0.0.1:18083/api/v5/gateway/nats' \
  -u <your-application-key>:<your-security-key> \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "nats",
  "enable": true,
  "mountpoint": "nats/",
  "listeners": [
    {
      "type": "tcp",
      "name": "default",
      "bind": "4222",
      "max_conn_rate": 1000,
      "max_connections": 1024000
    }
  ]
}'

設定ファイルからの有効化 ​

base.hocon で NATS ゲートウェイを有効化する設定例：

properties
gateway.nats {

  mountpoint = "nats/"

  listeners.tcp.default {
    bind = 4222
    acceptors = 16
    max_connections = 1024000
    max_conn_rate = 1000
  }
}

NATS ゲートウェイは TCP、SSL、WS、WSS タイプのリスナーをサポートします。設定可能なパラメータの完全な一覧は、EMQX Enterprise 設定マニュアル のゲートウェイ設定 - リスナーの項目を参照してください。

NATS ゲートウェイのカスタマイズ ​

デフォルト設定に加え、EMQX は特定のビジネス要件に合わせて柔軟に設定できる各種オプションを提供しています。本セクションでは、ゲートウェイ ページで利用可能な設定項目を詳述します。

基本設定 ​

  1. ゲートウェイ ページで NATS を探し、操作 列の 設定 ボタンをクリックします。

  2. 設定 タブで、ゲートウェイの接続パラメータ、マウントポイントプレフィックス、クライアント識別情報の上書きを設定できます。

    • サーバー名：ゲートウェイの内部参照用の一意識別子。デフォルトは emq_nats_gateway。

    • マウントポイント：ゲートウェイを通過するすべてのトピックに自動的に付加される文字列プレフィックス。プロトコル間のトピック分離に役立ちます。例：nats/ を指定すると、クライアントが手動でプレフィックスを含めることなくクロスプロトコルルーティングが可能になります。

    • デフォルトハートビート間隔：サーバーがクライアントの生存確認のために送信する PING パケットの間隔（秒）。デフォルトは 60 秒。

    • ハートビートタイムアウト閾値：クライアントが応答しない場合に切断とみなす時間。

    • 最大ペイロードサイズ：単一の PUB または HPUB メッセージペイロードの最大サイズ（バイト）。デフォルトは 1048576 バイト。

    • アイドルタイムアウト：非アクティブなクライアント接続を切断するまでの秒数。デフォルトは 30 秒。

    • 統計収集の有効化：このゲートウェイの統計収集とレポートを有効にするかどうか。デフォルトは有効。

    • クライアント情報の上書き：CONNECT パケットから認証情報を抽出する方法を定義。

      TIP

      認証を有効にしている場合は、username と password の正しいフィールドマッピングを必ず設定し、適切な資格情報処理を行ってください。

      • ユーザー名：CONNECT パケットの user フィールドにマッピング。
      • パスワード：CONNECT パケットの pass フィールドにマッピング。
      • クライアント ID：${generated} で自動生成、または特定のロジックでカスタマイズ可能。

  3. 更新 をクリックして変更を適用します。

リスナーの追加 ​

リスナー タブで、既存リスナーの編集、削除、新規追加が可能です。

  1. リスナー タブで + リスナー追加 をクリック。

  2. リスナー追加 ダイアログで以下の項目を設定します。

    基本設定

    • 名前：リスナーを識別する一意の名前。
    • タイプ：リスナーの種類を選択。NATS では tcp、ssl、ws、wss がサポートされています。
    • バインド：リスナーが接続を受け付けるポート番号。

    リスナー設定

    • 最大接続数：同時接続の最大数。デフォルトは 1024000。
    • 最大接続レート（リスナー）：1秒あたりに受け入れる新規接続の最大数。デフォルトは 1000。
    • プロキシプロトコル：Proxy Protocol v1/v2 の有効化。デフォルトは false。
    • プロキシプロトコルタイムアウト：Proxy Protocol ヘッダー受信のタイムアウト。指定時間内にヘッダーが受信されない場合、接続を切断。デフォルトは 3 秒。

    ピア証明書検証設定（SSL および WSS リスナーのみ適用）

    相互 TLS はデフォルトで有効です。TLS 証明書、秘密鍵、CA 証明書を設定してください。アップロードまたは直接フォームに貼り付け可能です。詳細は SSL/TLS 接続の有効化 を参照。

    • TLS 証明書：TLS 証明書のファイルパスまたは内容。
    • TLS 秘密鍵：TLS 秘密鍵のファイルパスまたは内容。
    • CA 証明書：CA 証明書のファイルパスまたは内容。
    • ピア証明書検証の強制：クライアント証明書検証を必須にするか。デフォルトは true。

  3. 追加 をクリックしてリスナーを作成します。

認証の設定 ​

NATS ゲートウェイは以下の2種類の認証方式をサポートします。

  • ゲートウェイ認証（authentication）：EMQX ゲートウェイの認証機構で、通常はユーザー名／パスワード形式のバックエンドに使用。
  • 内部ゲートウェイ認証（internal_authn）：NATS ネイティブのユーザー名／パスワード以外の認証方式。

両方が有効な場合、EMQX は以下の順序で認証を評価します。

  1. internal_authn のメソッドを上から順に評価。
  2. 必要な資格情報が欠けている場合は次のメソッドへ。
  3. 資格情報があるが検証に失敗した場合は即座に接続拒否。
  4. すべての内部メソッドがスキップされ、authentication が設定されていればゲートウェイ認証にフォールバック。
  5. 内部メソッドもゲートウェイ認証も設定されていなければ、すべての NATS クライアントの接続を許可。

ゲートウェイ認証の設定 ​

他のゲートウェイ同様、NATS ゲートウェイは標準の EMQX 認証機構と連携可能です。以下の認証バックエンドをサポートします。

ゲートウェイ認証では、NATS の CONNECT パケットから以下のフィールドを抽出します。

  • クライアント ID：デフォルトで自動生成。
  • ユーザー名：user フィールドの値。
  • パスワード：pass フィールドの値。

MQTT プロトコルとは異なり、ゲートウェイ認証は単一の認証機構のみをサポートし、複数の認証機構リスト（チェーン）はサポートしません。

ダッシュボードからの設定例 ​

HTTP サーバーを用いたパスワード認証の設定例：

  1. NATS ゲートウェイ設定の 認証 タブに移動。
  2. + 認証作成 をクリックし、メカニズムに パスワードベース、データソースに HTTP サーバー を選択して 次へ。
  3. 設定パラメータを入力。詳細は HTTP パスワード認証 を参照。
  4. 作成 をクリックし、設定内容を確認後 更新 をクリック。
REST API からの設定例 ​

組み込みデータベース認証を REST API で設定する例：

bash
curl -X 'POST' \
  'http://127.0.0.1:18083/api/v5/gateway/nats/authentication' \
  -u <your-application-key>:<your-security-key> \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "built_in_database",
  "mechanism": "password_based",
  "password_hash_algorithm": {
    "name": "sha256",
    "salt_position": "suffix"
  },
  "user_id_type": "username"
}'
設定ファイルからの設定例 ​

組み込みデータベース認証を設定ファイルで設定する例：

properties
gateway.nats {

  authentication {
    backend = built_in_database
    mechanism = password_based
    password_hash_algorithm {
      name = sha256
      salt_position = suffix
    }
    user_id_type = username
  }
}

その他の認証タイプについては、EMQX 認証機構 のドキュメントを参照してください。

内部認証（internal_authn）の設定 ​

これは NATS ゲートウェイ固有の認証機能で、NATS サーバー標準の3つの認証方式をサポートします。

トークン認証 ​
  • NATS CONNECT パケットの auth_token フィールドを使用。
  • プレーンなトークンおよび bcrypt ハッシュ（$2a$、$2b$、$2y$）をサポート。
  • NATS リファレンス：Token authentication

ダッシュボード設定例：

nats-auth-token

設定ファイル例：

properties
gateway.nats {
  internal_authn = [
    {
      type = token
      token = "nats_token"
    }
  ]
}
NKey 認証 ​
  • NATS CONNECT パケットの nkey + sig チャレンジ／レスポンス方式を使用。
  • nkeys は有効な NATS ユーザーパブリックキー（U...）である必要があります。
  • NATS リファレンス：NKey authentication

ダッシュボード設定例：

nats-auth-nkey

設定ファイル例：

properties
gateway.nats {
  internal_authn = [
    {
      type = nkey
      nkeys = [
        "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  ]
}
JWT 認証（ACL サポート付き） ​
  • NATS CONNECT パケットの jwt + sig（およびオプションの nkey）を使用。
  • 信頼されたオペレーターリストと JWT プリロードリストの両方が必要。
  • リゾルバータイプは現在 memory のみサポート。つまり有効なアカウント JWT は設定で事前ロードされます。
  • NATS リファレンス：JWT authentication

ダッシュボード設定例：

nats-auth-jwt

設定ファイル例：

properties
gateway.nats {
  internal_authn = [
    {
      type = jwt
      trusted_operators = [
        "Oxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
      resolver {
        type = memory
        resolver_preload = [
          {
            pubkey = "Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            jwt = "<your-account-jwt>"
          }
        ]
      }
    }
  ]
}

JWT のユーザークレームは ACL ルールも保持可能です。EMQX は permissions と nats.pub / nats.sub クレームをサポートし、最終的な認可結果は JWT ACL と EMQX 認可ルールの積集合となります。

JWT ACL クレームの例：

json
{
  "sub": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "iss": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "nats": {
    "pub": {
      "allow": ["sensors.>"],
      "deny": ["sensors.secret.>"]
    },
    "sub": {
      "allow": ["alerts.>"],
      "deny": ["alerts.internal.>"]
    }
  }
}

ユーザーレベルインターフェースの設定 ​

さらに詳しく ​

NATS プロトコルゲートウェイとそのユースケースについて詳しくは、ブログ記事「EMQX NATS Gateway: MQTT-NATS 双方向相互運用の実現」をご覧ください。