MQTT 設定

MQTT は、モノのインターネット（IoT）向けの標準的なメッセージングプロトコルです。非常に軽量なパブリッシュ／サブスクライブ型のメッセージングトランスポートとして設計されており、リモートデバイスを小さなコードフットプリントと最小限のネットワーク帯域幅で接続するのに最適です。

EMQX は 100% MQTT 5.0 および 3.x に準拠しています。本セクションでは、基本的な MQTT 設定項目について紹介します。基本的な MQTT 設定、サブスクリプション設定、セッション設定、強制シャットダウン設定、強制ガベージコレクション設定などのトピックを扱います。

基本的な MQTT 設定

本セクションでは、パケットサイズ、クライアントIDの長さ、トピックレベル数、QoS（サービス品質）、トピックエイリアス、保持設定など、MQTT プロトコルの動作を決定する設定項目を紹介します。

TIP

対応する設定項目は EMQX ダッシュボード（管理 -> MQTT 設定 -> 一般）でも確認できます。ダッシュボードで設定した内容は、設定ファイルの同じ設定項目を上書きします。
設定ファイルから MQTT を設定する場合は、emqx.conf ではなく base.hocon の使用を推奨します。
これは、emqx.conf に設定がある場合、ダッシュボードからの変更は一時的なものとなり、EMQX の再起動時に失われるためです。

設定例:

bash

mqtt {
  max_packet_size = 1MB
  max_clientid_len = 65535
  max_topic_levels = 128
  max_qos_allowed = 2
  max_topic_alias = 65535
  retain_available = true
}

各項目の説明は以下の通りです。

設定項目	ダッシュボード表示名	説明	デフォルト値	選択可能な値
`max_packet_size`	Max Packet Size	MQTT パケットは MQTT クライアントと EMQX 間でメッセージを送受信するために使用されます。許可される最大 MQTT パケットサイズを設定します。	`1MB`
`max_clientid_len`	Max Client ID Length	MQTT クライアントIDの最大長を設定します。過度に長いクライアントIDの使用を防止し、問題を回避します。	`65535`	`23` - `65535`
`max_topic_levels`	Max Topic Levels	MQTT トピックはメッセージの整理と分類に使用されます。トピックの最大レベル数を設定します。	`128`	`1` - `35`
`max_qos_allowed`	Max QoS	QoS（サービス品質）レベルはメッセージの信頼性と配信保証のレベルを決定します。 MQTT メッセージに許可される最大 QoS レベルを設定します。
`max_topic_alias`	Max Topic Alias	トピックエイリアスは、完全なトピック名の代わりに短いエイリアスを使うことで MQTT パケットのサイズを削減する方法です。 MQTT セッションで使用できるトピックエイリアスの最大数を設定します。	`65535`	`1` - `65535`
`retain_available`	Retain Available	保持メッセージは、トピックに最後にパブリッシュされたメッセージを保存し、新規サブスクライバーが最新のメッセージを受信できるようにします。 MQTT の保持メッセージ機能を有効にするかどうかを設定します。	`true`	`true`, `false`

サブスクリプション設定

EMQX におけるサブスクリプションは、クライアントが EMQX 上のトピックをサブスクライブするプロセスを指します。クライアントがトピックをサブスクライブすると、そのトピックにパブリッシュされたメッセージを受信したいことを示します。

本セクションでは、共有サブスクリプション、ワイルドカードサブスクリプション、排他サブスクリプションの設定方法を紹介します。

TIP

設定例:

bash

mqtt {
	wildcard_subscription = true
  exclusive_subscription = false
  shared_subscription = true
  shared_subscription_strategy  =  round_robin
}

各項目の説明は以下の通りです。

設定項目	ダッシュボード表示名	説明	デフォルト値	選択可能な値
`wildcard_subscription`	Wildcard Subscription Available	ワイルドカードサブスクリプションは、`+` や `#` といったワイルドカードを使い、複数のトピックを単一のサブスクリプションでサブスクライブ可能にします。ワイルドカードサブスクリプションを有効にするかどうかを設定します。	`true`	`true`, `false`
`exclusive_subscription`	Exclusive Subscription	排他サブスクリプションは、1つのトピックに対して同時に1つの MQTT クライアントのみがサブスクライブ可能にします。排他サブスクリプションを有効にするかどうかを設定します。	`true`	`true`, `false`
`shared_subscription`	Shared Subscription Available	共有サブスクリプションは、複数の MQTT クライアントがトピックのサブスクリプションを共有可能にします。共有サブスクリプションを有効にするかどうかを設定します。	`true`	`true`, `false`
`shared_subscription_strategy`		共有サブスクリプションでメッセージを複数の MQTT クライアントに配信する戦略を定義します。 `shared_subscription` が `true` の場合にのみ必要です。	`round_robin`	- `random`（ランダムにサブスクライバーへ配信） - `round_robin`（ラウンドロビン方式でサブスクライバーを選択） - `sticky`（最後に選択されたサブスクライバーに常に配信、切断時まで維持） - `hash`（`clientId` のハッシュでサブスクライバーを選択）

遅延パブリッシュ設定

遅延パブリッシュ機能は、クライアントがメッセージのパブリッシュを指定した時間だけ遅延させることを可能にします。この機能は、特定の時間にメッセージをパブリッシュしたい場合や、特定の条件が満たされたときにメッセージを送信したい場合に有用です。

本セクションでは、遅延パブリッシュの有効化方法と、許可される遅延メッセージの最大数の設定方法を紹介します。

設定例:

bash

delay {
  delayed_publish_enabled = true
  max_delayed_messages = 0
}

各項目の説明は以下の通りです。

delayed_publish_enabled は EMQX で遅延パブリッシュ機能を有効にするかどうかを設定します。デフォルト値：true、選択可能な値：true、false。
max_delayed_messages は許可される遅延メッセージの最大数を設定します。デフォルト値：0。

キープアライブ設定

キープアライブは 2 バイトの整数で、秒単位の時間間隔を表します。これは、MQTT クライアントと EMQX の接続がデータ送信がなくてもアクティブな状態を維持するための仕組みです。MQTT クライアントが EMQX に接続を確立する際、CONNECT パケットのヘッダーに非ゼロのキープアライブ値を設定することで、双方の間でキープアライブ機構を有効にできます。キープアライブの動作詳細については、MQTT キープアライブパラメータとは？を参照してください。

MQTT 5.0 プロトコルに従い、キープアライブが有効なクライアントに対して、サーバーはクライアントからキープアライブ時間の1.5倍以内に MQTT コントロールパケットを受信しない場合、ネットワーク接続を切断しなければなりません。
そのため、EMQX ではクライアントのキープアライブタイムアウト状態を定期的にチェックするための設定 keepalive_multiplier を導入しています。デフォルト値は 1.5 です。

bash

keepalive_multiplier = 1.5

タイムアウト計算式は以下の通りです。

Keep Alive \times keepalive_multiplier

動的キープアライブ調整

車載ネットワーク（T-Box）やモバイル IoT のようなシナリオでは、MQTT クライアントは「アクティブ状態」（頻繁な通信）と「スリープ状態」（低消費電力の待機）を切り替える必要があります。単一の固定キープアライブ値では両方のニーズを同時に満たせません。

短いキープアライブはアクティブ時の切断検知を高速化しますが、デバイスが駐車中や待機中は過剰なハートビート通信とバッテリー消費を招きます。
長いキープアライブはスリープ時の通信量を減らしますが、アクティブ時の切断検知が遅れます。

EMQX は、$SETOPTS/ システムトピック群を通じてクライアント単位の動的キープアライブ調整をサポートしています。クライアントはこれらのトピックにパブリッシュすることで自身のブローカー側キープアライブ許容値を更新でき、また特権を持つバックエンドサービスは複数クライアントを一括更新できます。MQTT 接続の切断や再交渉は不要です。調整はアクティブなセッションのメモリ上にのみ適用され、永続化されません。

単一クライアント更新：`$SETOPTS/mqtt/keepalive`

クライアントはこのトピックにパブリッシュして自身のブローカー側キープアライブタイムアウトを更新します。EMQX はパブリッシュ元のセッションからクライアントIDを自動的に取得します。

ペイロード: 秒数を表す非負整数の文字列。

text

有効範囲: 0～65535 秒。0 はそのセッションのキープアライブチェックを無効化します。65535 を超える値は 65535 にクランプされます。クライアントのゾーンに mqtt.server_keepalive が設定されている場合は、両者の最小値が有効値となります。

利用例: 車両が駐車状態に入る際、T-Box クライアントが $SETOPTS/mqtt/keepalive に 300 をパブリッシュします。EMQX はブローカー側のキープアライブ許容値を 300 秒に延長し（デフォルトの 1.5× 倍数を考慮すると実質的なアイドルタイムアウトは 450 秒）、リモートコマンド配信のために MQTT 接続を維持します。なお、これはブローカー側のタイムアウト調整のみで、クライアントの実際の PINGREQ 間隔は変わりません。ハートビート通信量を減らすには、クライアント側もキープアライブ間隔を延長する必要があります。

一括更新：`$SETOPTS/mqtt/keepalive-bulk`

バックエンドサービスはこのトピックにパブリッシュして、複数クライアントのキープアライブを一括更新できます。

ペイロード: JSON 配列。各要素は以下を含みます。

フィールド名	型	必須	説明
`clientid`	文字列	必須	対象 MQTT クライアントの識別子
`keepalive`	整数	必須	新しいキープアライブ間隔（秒、0～65535）

json

[
  { "clientid": "tbox-001", "keepalive": 300 },
  { "clientid": "tbox-002", "keepalive": 60 }
]

一括更新は非同期で処理され、クラスター対応です。EMQX は対象クライアントが存在するノードを特定し、ノード間 RPC で更新を適用します。内部で 10 件を超える一括リクエストがキューイングされると、それ以降のリクエストは破棄され、警告ログが記録されます。

アクセス制御

これら2つのトピックは細かい ACL をサポートするために分離されています。

認証済みクライアントに $SETOPTS/mqtt/keepalive へのパブリッシュを許可し、各デバイスが自身のキープアライブを調整可能にします。
$SETOPTS/mqtt/keepalive-bulk は信頼できるバックエンドサービスのみに制限します。

TIP

信頼できないクライアントに $SETOPTS/mqtt/keepalive へのパブリッシュ権限を与えないでください。キープアライブを 0 に設定すると、そのセッションのキープアライブチェックが完全に無効化され、過度に大きな値は切断されない接続を長時間維持し、ブローカーリソースを消費する恐れがあります。

これらのトピックにパブリッシュされたメッセージは、EMQX によってインターセプトされ消費され、ルーティングされることもサブスクライバーに配信されることもありません。

セッション設定

MQTT におけるセッションとは、クライアントとブローカー間の接続を指します。EMQX では、クライアントが接続を確立するとセッションが生成され、トピックのサブスクライブやメッセージの受信、EMQX へのメッセージパブリッシュが可能になります。

本セクションでは、セッションの設定方法を紹介します。

設定例:

bash

mqtt {
    max_subscriptions = infinity
    upgrade_qos = false
    max_inflight = 32
    retry_interval = 30s
    max_awaiting_rel = 100
    await_rel_timeout = 300s
    session_expiry_interval = 2h
    max_mqueue_len = 1000
    mqueue_priorities = disabled
    mqueue_default_priority = lowest
    mqueue_store_qos0 = true
    force_shutdown {
      max_mailbox_size = 1000
      max_heap_size = 32MB
    }
    force_gc {
      count  =  16000
      bytes  =  16MB
    }
  }

各項目の説明は以下の通りです。

設定項目	ダッシュボード表示名	説明	デフォルト値	選択可能な値
`max_subscriptions`	Max Subscriptions	クライアントが保持可能な最大サブスクリプション数を設定します。	`infinity`	`1` - `infinity`
`upgrade_qos`	Upgrade QoS	クライアントがパブリッシュ後にメッセージの QoS（サービス品質）レベルをアップグレードできるかどうかを設定します。	`false`（無効）	`true`, `false`
`max_inflight`	Max Inflight	QoS 1 および QoS 2 メッセージの未アック状態（送信済みだが未確認）の最大数を設定します。	`32`	`1` - `65535`
`retry_interval`	Retry Interval	QoS 1 または QoS 2 メッセージの再送間隔を設定します。	`30s` 単位: 秒	--
`max_awaiting_rel`	Max Awaiting PUBREL	各セッションで `PUBREL` 受信またはタイムアウトまで保留できる QoS 2 メッセージの最大数を設定します。この制限に達すると、新しい QoS 2 `PUBLISH` リクエストはエラーコード `147(0x93)` で拒否されます。 MQTT における `PUBREL` は QoS 2 メッセージフローの制御パケットです。	`100`	`1` - `infinity`
`await_rel_timeout`	Max Awaiting PUBREL TIMEOUT	QoS 2 メッセージの `PUBREL` 受信を待つ最大時間を設定します。この制限に達すると、EMQX はパケットIDを解放し、警告ログを生成します。注：EMQX は `PUBREL` の有無にかかわらず QoS 2 メッセージの転送を行います。	`300s` 単位: 秒	--
`session_expiry_interval`	Session Expiry Interval	セッションがアイドル状態で自動的に閉じられるまでの時間を設定します。注：MQTT 5.0 以外のクライアント向け。	`2h`
`max_mqueue_len`	Max Message Queue Length	永続化クライアントが切断された場合やインフライトウィンドウが満杯の際に許可される最大キュー長を設定します。	`1000`	`0` - `infinity`
`mqueue_priorities`	Topic Priorities	トピック優先度を設定します。ここでの設定は `mqueue_default_priority` の設定を上書きします。	`disabled` セッションは `mqueue_default_priority` の優先度を使用します。	`disabled` または `1` - `255`
`mqueue_default_priority`	Default Topic Priorities	デフォルトのトピック優先度を設定します。	`lowest`	`highest`， `lowest`
`mqueue_store_qos0`	Store QoS 0 Message	接続が切断されセッションが維持されている場合に、QoS 0 メッセージをメッセージキューに保存するかどうかを設定します。	`true`	`true`, `false`
`force_shutdown`	Enable Force Shutdown	強制シャットダウン機能を有効にするかどうかを設定します。メールボックスキュー長（`max_mailbox_size`）またはヒープサイズ（`max_heap_size`）が指定値に達すると、クライアント接続処理を強制終了します。	`true`	`true`, `false`
`force_shutdown.max_mailbox_size`	Max Mailbox Size	強制シャットダウンをトリガーするメールボックスキューの最大長を設定します。	`1000`	`1` - `infinity`
`force_shutdown.max_heap_size`	Max Heap Size	強制シャットダウンをトリガーするヒープサイズの最大値を設定します。	`32MB`	--
`force_gc`	--	指定されたメッセージ数（`count`）または受信バイト数（`bytes`）に達した場合に強制ガベージコレクションを有効にするかどうかを設定します。	`true`	`true`, `false`
`force_gc.count`	--	強制ガベージコレクションをトリガーする受信メッセージ数を設定します。	`16000`	`0` - `infinity`
`force_gc.bytes`	--	強制ガベージコレクションをトリガーする受信バイト数を設定します。	`16MB` 単位: `MB`	--

TIP

ダッシュボードで MQTT 設定を行うには、ダッシュボード左側のナビゲーションメニューから管理 -> MQTT 設定 をクリックしてください。ダッシュボードで設定した内容は設定ファイルの同じ設定項目を上書きします。
設定ファイルから MQTT を設定する場合は、emqx.conf ではなく base.hocon の使用を推奨します。
これは、emqx.conf に設定がある場合、ダッシュボードからの変更は一時的なものとなり、EMQX の再起動時に失われるためです。

TIP

EMQX はさらに多くの設定項目を提供しており、カスタマイズニーズに対応しています。詳細は EMQX Enterprise Configuration Manual for Enterprise を参照してください。

Kubernetes

EMQX Operator

EMQX クラスター管理

API リファレンス

パスワード認証

監視

アクセスコントロール

統合

管理

Prometheus との統合

OpenTelemetry との統合

エンドツーエンドトレース

プラグインカタログ

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

Volcengine RTC

シナリオ

GPT-Realtime

MQTT 設定 ​

基本的な MQTT 設定 ​

サブスクリプション設定 ​

遅延パブリッシュ設定 ​

キープアライブ設定 ​

動的キープアライブ調整 ​

単一クライアント更新：$SETOPTS/mqtt/keepalive ​

一括更新：$SETOPTS/mqtt/keepalive-bulk ​

アクセス制御 ​

セッション設定 ​

MQTT 設定

基本的な MQTT 設定

サブスクリプション設定

遅延パブリッシュ設定

キープアライブ設定

動的キープアライブ調整

単一クライアント更新：`$SETOPTS/mqtt/keepalive`

一括更新：`$SETOPTS/mqtt/keepalive-bulk`

アクセス制御

セッション設定