EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

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

コマンドラインインターフェース ​

このページでは、EMQXがサポートする起動および管理コマンドの種類を紹介し、ctl管理コマンドについて詳細に解説します。

起動コマンド ​

EMQXは基本的な起動および管理コマンドをサポートしており、emqx <command>コマンドで実行できます。

よく使われる起動および管理コマンドは以下の通りです。

コマンド説明
startEMQXをデーモンモードで起動し、実行時に対話型シェルを必要としません。
consoleEMQXをErlangまたはElixirの対話型シェルで起動します。開発環境でのデバッグに使用し、EMQXとの対話が必要です。
foregroundEMQXをフォアグラウンドモードで起動し、対話型シェルを使用しません。開発環境でバックグラウンド実行せずに起動する際に使用します。
stop実行中のEMQXノードを停止します。
ctlEMQXの管理および監視を行います。emqx ctl helpで詳細情報を取得できます。

以下は開発やデバッグ向けの高度なコマンドで、通常のユーザーは気にする必要はありません。

コマンド説明
remote_consoleリモートのEMQXノードの対話型シェルに接続します。
attach実行中のEMQXノードにアタッチして対話操作を行います。
ertspathEMQXのErlangライブラリのパスを取得します。
root_dirEMQXのルートディレクトリのパスを取得します。
pid実行中のEMQXノードのプロセスIDを取得します。
pingEMQXノードが稼働中か確認します。
check_configEMQXの設定ファイルが正しいか検証します。
console_clean対話型シェルコンソールの出力をクリアします。
escriptEMQXノード上でEscriptスクリプトを実行します。

ctlコマンド ​

EMQXのctlコマンドは、EMQXの管理および監視のための複数のサブコマンドを提供します。ctlコマンドはEMQXサービス起動後に実行する必要があります。

EMQXはemqx_ctlコマンドも提供しており、これはemqx ctlのエイリアスです。
ctlコマンドは指定したEMQXノードにリモート接続するために隠れたErlangノードを起動し、Erlangのリモートコールを実行し、その結果を表示します。したがって、ctlコマンドの過度な使用は避けることを推奨します。

以下はctlコマンドの全サブコマンドと簡単な説明の一覧です。機能紹介を目的としており、詳細なパラメーター情報はhelpコマンドで確認してください。

status ​

ブローカーが起動しているか簡単に確認するコマンドです。

bash
$ emqx ctl status
Node 'emqx@127.0.0.1' 5.8.7 is started

broker ​

ローカルブローカーの稼働状況、統計、メトリクスを確認するコマンドです。

bash
$ emqx ctl broker
sysdescr  : EMQX Enterprise
version   : 5.8.7
datetime  : 2025-08-06T10:01:23.857678490+02:00
uptime    : 52 seconds

broker stats ​

ローカルブローカーの統計情報（接続数、セッション数、サブスクリプション数、トピック数など）を表示します。

bash
$ emqx ctl broker stats
channels.count                : 0
channels.max                  : 0
cluster_sessions.count        : 0
cluster_sessions.max          : 0
connections.count             : 0
connections.max               : 0
delayed.count                 : 0
delayed.max                   : 0
durable_subscriptions.count   : 0
durable_subscriptions.max     : 0
live_connections.count        : 0
live_connections.max          : 0
retained.count                : 3
retained.max                  : 3
sessions.count                : 0
sessions.max                  : 0
suboptions.count              : 0
suboptions.max                : 0
subscribers.count             : 0
subscribers.max               : 0
subscriptions.count           : 0
subscriptions.max             : 0
subscriptions.shared.count    : 0
subscriptions.shared.max      : 0
topics.count                  : 0
topics.max                    : 0

broker metrics ​

認証、認可、メッセージ配信、パケット処理、過負荷保護などのローカルブローカーのメトリクスを表示します。

bash
$ emqx ctl broker metrics
authentication.failure        : 0
authentication.success        : 0
authentication.success.anonymo: 0
authorization.allow           : 0
authorization.cache_hit       : 0
authorization.cache_miss      : 0
authorization.deny            : 0
authorization.matched.allow   : 0
authorization.matched.deny    : 0
authorization.nomatch         : 0
authorization.superuser       : 0
bytes.received                : 0
bytes.sent                    : 0
client.auth.anonymous         : 0
client.authenticate           : 0
client.authorize              : 0
client.connack                : 0
client.connect                : 0
client.connected              : 0
client.disconnected           : 0
client.subscribe              : 0
client.unsubscribe            : 0
delivery.dropped              : 0
delivery.dropped.expired      : 0
delivery.dropped.no_local     : 0
delivery.dropped.qos0_msg     : 0
delivery.dropped.queue_full   : 0
delivery.dropped.too_large    : 0
messages.acked                : 0
messages.delayed              : 0
messages.delivered            : 0
messages.dropped              : 0
messages.dropped.await_pubrel_: 0
messages.dropped.no_subscriber: 0
messages.forward              : 0
messages.persisted            : 0
messages.publish              : 0
messages.qos0.received        : 0
messages.qos0.sent            : 0
messages.qos1.received        : 0
messages.qos1.sent            : 0
messages.qos2.received        : 0
messages.qos2.sent            : 0
messages.received             : 0
messages.sent                 : 0
messages.transformation_failed: 0
messages.transformation_succee: 0
messages.validation_failed    : 0
messages.validation_succeeded : 0
overload_protection.delay.ok  : 0
overload_protection.delay.time: 0
overload_protection.gc        : 0
overload_protection.hibernatio: 0
overload_protection.new_conn  : 0
packets.auth.received         : 0
packets.auth.sent             : 0
packets.connack.auth_error    : 0
packets.connack.error         : 0
packets.connack.sent          : 0
packets.connect.received      : 0
packets.disconnect.received   : 0
packets.disconnect.sent       : 0
packets.pingreq.received      : 0
packets.pingresp.sent         : 0
packets.puback.inuse          : 0
packets.puback.missed         : 0
packets.puback.received       : 0
packets.puback.sent           : 0
packets.pubcomp.inuse         : 0
packets.pubcomp.missed        : 0
packets.pubcomp.received      : 0
packets.pubcomp.sent          : 0
packets.publish.auth_error    : 0
packets.publish.dropped       : 0
packets.publish.error         : 0
packets.publish.inuse         : 0
packets.publish.received      : 0
packets.publish.sent          : 0
packets.pubrec.inuse          : 0
packets.pubrec.missed         : 0
packets.pubrec.received       : 0
packets.pubrec.sent           : 0
packets.pubrel.missed         : 0
packets.pubrel.received       : 0
packets.pubrel.sent           : 0
packets.received              : 0
packets.sent                  : 0
packets.suback.sent           : 0
packets.subscribe.auth_error  : 0
packets.subscribe.error       : 0
packets.subscribe.received    : 0
packets.unsuback.sent         : 0
packets.unsubscribe.error     : 0
packets.unsubscribe.received  : 0
session.created               : 0
session.discarded             : 0
session.resumed               : 0
session.takenover             : 0
session.terminated            : 0

cluster ​

ノードのクラスター状態を確認・管理するコマンドです。

EMQXのjoinコマンドは、指定したノードに対してクラスター参加の「リクエスト」を送るものであり、「招待」ではありません。つまり、emqx ctl cluster join <OneOfTheClusteredNodes>は、<OneOfTheClusteredNodes>のクラスターに参加するリクエストを送るコマンドです。

cluster join <Node> ​

指定したノードが属するEMQXクラスターにノードを参加させます。

指定ノードが稼働中でアクセス可能であることを確認してください。

bash
$ emqx ctl cluster join emqx2@127.0.0.1
Failed to join the cluster: {node_down,'emqx2@127.0.0.1'}

cluster leave ​

現在のEMQXクラスターからノードを離脱させます。

bash
$ emqx ctl cluster leave
Failed to leave the cluster: node_not_in_cluster

cluster force-leave <Node> ​

指定ノードを強制的にクラスターから削除します。

注意

この操作はクラスター状態の不整合を引き起こす可能性があるため、慎重に使用してください。

bash
$ emqx ctl cluster force-leave emqx2@127.0.0.1
Failed to remove the node from cluster: node_not_in_cluster

cluster status [--json] ​

EMQXクラスターの状態を表示します。

オプションの--jsonパラメーターを付けるとJSON形式で表示します。

bash
$ emqx ctl cluster status
Cluster status: #{running_nodes => ['emqx@127.0.0.1'],stopped_nodes => []}
bash
$ emqx ctl cluster status --json
{
  "stopped_nodes" : [

  ],
  "running_nodes" : [
    "emqx@127.0.0.1"
  ]
}

cluster discovery enable ​

自動クラスター検出を有効化し実行します（設定済みの場合）。

bash
$ emqx ctl cluster discovery enable
Automatic cluster discovery enabled.

clients ​

接続中のクライアントを確認・管理するコマンドです。

clients list ​

現在EMQXに接続中のすべてのクライアントを表示します。アクティブなクライアントや接続数の監視に利用できます。

TIP

多数のクライアントが接続している場合、listコマンドは時間がかかりリソースを多く消費する可能性があります。

bash
$ emqx ctl clients list
Client(emqx_c, username=undefined, peername=127.0.0.1:59441, clean_start=true, keepalive=60, session_expiry_interval=0, subscriptions=1, inflight=0, awaiting_rel=0, delivered_msgs=4530, enqueued_msgs=0, dropped_msgs=0, connected=true, created_at=1684736435155, connected_at=1684736435155)
Client(emqx_a, username=undefined, peername=127.0.0.1:59444, clean_start=true, keepalive=60, session_expiry_interval=0, subscriptions=1, inflight=0, awaiting_rel=0, delivered_msgs=4588, enqueued_msgs=0, dropped_msgs=0, connected=true, created_at=1684736441613, connected_at=1684736441613)

clients show <ClientId> ​

特定クライアントの詳細な接続情報を表示します。

bash
$ emqx ctl clients show emqx_c
Client(emqx_c, username=undefined, peername=127.0.0.1:59441, clean_start=true, keepalive=60, session_expiry_interval=0, subscriptions=1, inflight=0, awaiting_rel=0, delivered_msgs=4680, enqueued_msgs=0, dropped_msgs=0, connected=true, created_at=1684736435155, connected_at=1684736435155)

clients kick <ClientId> ​

指定したクライアントを強制切断します。

bash
$ emqx ctl clients kick emqx_c
ok

clients stats --file <path/to/file.csv> ​

クライアントごとの統計情報をCSVファイルに出力し、システム管理者がクライアントの活動状況や負荷の高いクライアントを把握できます。

bash
$ emqx ctl clients stats path/to/file.csv

引数:

  • 出力するCSVファイルのパス
  • --batchオプションは一度に処理するクライアント数を制御します。小さい値はリソース使用量を抑えますが処理時間が長くなります（デフォルトは1000）。
  • --sleepオプションはバッチ処理間の待機時間（ミリ秒）を制御します。値を大きくするとシステムへの影響を減らせますが処理時間が長くなります（デフォルトは10ms）。

出力フォーマット:

生成されるCSVファイルには以下のカラムが含まれます。

sql
timestamp, clientid, recv_oct, recv_cnt, send_oct, send_cnt, subscriptions_cnt, awaiting_rel_cnt, mqueue_len, mqueue_dropped

各フィールドの説明:

  • timestamp: データ収集時のUNIXタイムスタンプ（ミリ秒）
  • clientid: MQTTクライアントID
  • recv_oct: クライアントから受信した合計バイト数
  • recv_cnt: 受信したメッセージ数（またはメッセージ断片数）
  • send_oct: クライアントへ送信した合計バイト数
  • send_cnt: 送信したMQTTパケット数
  • subscriptions_cnt: クライアントが保持するサブスクリプション数
  • awaiting_rel_cnt: PUBREL待ちのQoS 2メッセージ数
  • mqueue_len: クライアントのメモリ上のセッションメッセージキューの長さ
  • mqueue_dropped: メモリ上のセッションメッセージキューから破棄されたメッセージ数

注意事項:

  • 本コマンドは可観測性向上を目的としており、リアルタイムのテレメトリーではありません。
  • パフォーマンス低下を避けるため、ETSスキャンを周期的にスリープ（例：1000件ごとに10ms）して制御しています。
  • 生成されたCSVはオフライン分析や可視化、自動処理に利用可能です。

session-top ​

EMQX 6.3.0以降、session-topコマンドでMQTTペイロードバイト数が多い、またはメッセージキューが長いセッションを特定できます。このコマンドはsession-topをサポートするクラスターノードからキャッシュされたセッション統計を読み取り、実行ノード上にトップセッションをCSVファイルとして書き出します。

セッションスキャン開始 ​

以下のコマンドでスキャンを開始します。

bash
emqx ctl session-top --out <File> [--count <K>] [--sort <SortBy>] [--batch <Size>] [--sleep <Ms>]

例：MQTTペイロードバイト数が多い上位20セッションをエクスポート

bash
emqx ctl session-top --out /tmp/session-top.csv --count 20 --sort total_payload_bytes
オプション説明デフォルト
--out <File>出力CSVファイルのパス。必須。既存ファイルは不可。なし
--count <K>エクスポートする最大セッション数。1〜1000の範囲。10
--sort <SortBy>セッションのランキング基準。total_payload_bytesまたはmqueue_length。total_payload_bytes
--batch <Size>ローカルスキャンで一度に処理するキャッシュセッション数。正の整数。1000
--sleep <Ms>ローカルスキャンバッチ間の遅延時間（ミリ秒）。非負整数。1

スキャンは非同期で実行されます。進捗や完了状況はemqx ctl session-top statusで確認可能です。

ローリングアップグレード中はsession-top非対応のノードはスキャン対象外となります。

1ノードから同時に1つのスキャンのみ開始可能で、各参加ノードも同時に1つのローカルスキャンのみ受け入れます。EMQXは影響を抑えるためバッチ処理で各ノードをスキャンします。

CSVファイルのカラムは以下の通りです。

text
clientid,node,mqueue_length,total_payload_bytes,inflight_count
  • clientid: MQTTクライアントID
  • node: セッションを所有するEMQXノード
  • mqueue_length: セッションメッセージキュー内のメッセージ数
  • total_payload_bytes: メモリ上のセッションメッセージキューおよびinflightウィンドウが保持するMQTTペイロードバイト数。トピック、ヘッダー、MQTTプロパティ、Erlang内部レコードのオーバーヘッドは含まれません。Durableセッションはバッファ状態がメモリ構造にないため0を報告します。
  • inflight_count: セッションのinflightウィンドウ内のメッセージ数

これらの値はキャッシュされたセッション統計から読み取られ、スキャン中に変動する可能性があります。

リモートノードが既にスキャン中、起動失敗、エラー報告した場合、Bad repliesにノードが表示され、CSVには完了したノードの結果のみ含まれます。

リモートノードがスキャンを受け入れたが結果を返さない場合、タスクはrunning状態のままでCSVは書き込まれません。タスク状態を確認し必要に応じてキャンセルしてください。

メモリ上のセッションの保持ペイロードバイト数が閾値を超えた場合にスロットル警告をログに記録したい場合は、sysmon.session.total_payload_bytes_high_watermarkを0より大きい値に設定してください。デフォルトの0は警告を無効化します。警告は診断用であり、バッファペイロードバイト数の制限やメッセージ配信、メッセージキューの削除、inflight処理、セッションテイクオーバーの挙動には影響しません。設定詳細はEMQX Enterprise設定マニュアルを参照してください。

スキャン状況の確認 ​

スキャンを開始したノードで以下のコマンドを実行し、実行中または最新の完了スキャンの状況を表示します。

bash
emqx ctl session-top status

最新の完了状況は次のスキャン開始まで保持されます。

状況は開始ノードにローカルなため、他ノードで実行するとスキャン中でもidleが返ることがあります。

セッションスキャンのキャンセル ​

スキャンを開始したノードで以下のコマンドを実行し、実行中のスキャンをキャンセルします。

bash
emqx ctl session-top cancel

キャンセルはクラスタ全体にベストエフォートで伝播されます。ノードがキャンセル要求を受ける前にローカルスキャンを完了する場合があります。

他ノードでcancelを実行しても、別ノードで開始したスキャンはキャンセルされず、session-topスキャンが実行されていない旨が報告されます。

topics ​

現在のシステムでサブスクライブされているすべてのトピックを表示・管理するコマンドです。

topics list ​

すべてのトピックを一覧表示します。トピック数や分布の監視に利用できます。

注意

クラスター内に大量のトピックサブスクリプションがある場合、listコマンドは時間がかかりリソースを多く消費する可能性があります。

bash
$ emqx ctl topics list
t/1 -> emqx@127.0.0.1

topics show <Topic> ​

特定トピックの詳細情報を表示します。

bash
$ emqx ctl topics show t/1
t/1 -> emqx@127.0.0.1

subscriptions ​

クライアントのサブスクリプションを表示、追加、削除するコマンドです。

subscriptions list ​

すべてのサブスクリプションを一覧表示します。

bash
$ emqx ctl subscriptions list
emqx_a -> topic:t/1 qos:0 nl:0 rh:0 rap:0
emqx_c -> topic:t/1 qos:0 nl:0 rh:0 rap:0

subscriptions show <ClientId> ​

特定クライアントのサブスクリプションを表示します。

bash
$ emqx ctl subscriptions show emqx_a
emqx_a -> topic:t/1 qos:0 nl:0 rh:0 rap:0

subscriptions add <ClientId> <Topic> <QoS> ​

手動でサブスクリプションを追加します。

bash
$ emqx ctl subscriptions add emqx_a t/1 1
ok

subscriptions del <ClientId> <Topic> ​

手動でサブスクリプションを削除します。

bash
$ emqx ctl subscriptions del emqx_a t/1
ok

TIP

システム内に大量のサブスクリプションがある場合、listコマンドは時間がかかりリソースを多く消費する可能性があります。

plugins ​

プラグインのインストール状況を表示・管理するコマンドです。

plugins list ​

インストール済みのプラグインを一覧表示します。

bash
emqx ctl plugins list
[]

plugins describe <Name-Vsn> ​

インストール済みプラグインの詳細情報を表示します。

bash
emqx ctl plugins describe emqx_auth_mnesia-3.0.1

plugins allow <Name-Vsn> ​

ダッシュボードから指定プラグインのインストールを許可します。

bash
emqx ctl plugins allow emqx_auth_mnesia-3.0.1
{
  "result" : "ok",
  "name_vsn" : "emqx_auth_mnesia-3.0.1",
  "action" : "do_allow_installation"
}

plugins disallow <Name-Vsn> ​

ダッシュボードから指定プラグインのインストールを禁止します。

bash
emqx ctl plugins disallow emqx_auth_mnesia-3.0.1
{
  "result" : "ok",
  "name_vsn" : "emqx_auth_mnesia-3.0.1",
  "action" : "do_disallow_installation"
}

plugins install <Name-Vsn> [--cluster] ​

プラグインインストールディレクトリにあるプラグインパッケージをインストールします。--clusterオプションを付けると、すべての稼働中ノードに配布・インストールします。

bash
emqx ctl plugins install emqx_auth_mnesia-3.0.1
emqx ctl plugins install emqx_auth_mnesia-3.0.1 --cluster

plugins uninstall <Name-Vsn> ​

指定プラグインをアンインストールします。

bash
emqx ctl plugins uninstall emqx_auth_mnesia-3.0.1

plugins start <Name-Vsn> ​

指定プラグインを起動します。

bash
emqx ctl plugins start emqx_auth_mnesia-3.0.1

plugins stop <Name-Vsn> ​

指定プラグインを停止します。

bash
emqx ctl plugins stop emqx_auth_mnesia-3.0.1

plugins restart <Name-Vsn> ​

指定プラグインを再起動します。

bash
emqx ctl plugins restart emqx_auth_mnesia-3.0.1

plugins disable <Name-Vsn> ​

プラグインの自動起動を無効化します。

bash
emqx ctl plugins disable emqx_auth_mnesia-3.0.1

plugins enable <Name-Vsn> [Position] ​

プラグインの自動起動を有効化し、起動順序の位置を指定します。

bash
emqx ctl plugins enable emqx_auth_mnesia-3.0.1 front

front、rear、before Other-Vsnのいずれかで相対位置を指定可能です。位置指定がない場合は既存のプラグイン順序は維持され、新規プラグインは末尾に追加されます。

vm ​

Erlang仮想マシンの統計データを確認するコマンドです。

vm all ​

CPU負荷、メモリ使用量などErlang VMの全情報を表示します。

bash
$ emqx ctl vm all
cpu/load1               : 13.16
cpu/load5               : 11.95
cpu/load15              : 9.75
memory/total            : 127648904
memory/processes        : 30427456
memory/processes_used   : 30426744
memory/system           : 97221448
memory/atom             : 2277809
memory/atom_used        : 2259843
memory/binary           : 668072
memory/code             : 48748792
memory/ets              : 10725432
process/limit           : 2097152
process/count           : 626
io/max_fds              : 8192
io/active_fds           : 0
ports/count             : 27
ports/limit             : 1048576

vm load ​

Erlang VMのCPU負荷平均（1分、5分、15分）を表示します。

bash
$ emqx ctl vm load
cpu/load1               : 0.96
cpu/load5               : 1.03
cpu/load15              : 1.05

vm memory ​

Erlang VMのメモリ使用量（合計、プロセスメモリ、アトムメモリ、バイナリメモリ、ETSメモリ）を表示します。

bash
$ emqx ctl vm memory
memory/total            : 218672189
memory/processes        : 70762184
memory/processes_used   : 70760616
memory/system           : 147910005
memory/atom             : 3080769
memory/atom_used        : 3061022
memory/binary           : 1652808
memory/code             : 67620307
memory/ets              : 17414480

vm process ​

Erlang VMのプロセス情報（プロセス数、プロセス上限）を表示します。

bash
$ emqx ctl vm process
process/limit           : 2097152
process/count           : 870

vm io ​

Erlang VMのI/O情報（最大ファイルディスクリプタ数、アクティブファイルディスクリプタ数）を表示します。

bash
$ emqx ctl vm io
io/max_fds              : 1048576
io/active_fds           : 0

vm ports ​

Erlang VMのポート情報（ポート数、ポート上限）を表示します。

bash
$ emqx ctl vm ports
ports/count             : 12
ports/limit             : 1048576

mnesia ​

組み込みデータベース（Mnesia）の稼働状況およびメトリクスを表示します。

bash
$ emqx ctl mnesia
===> System info in version "4.20.4.1", debug level = none <===
opt_disc. Directory "/Users/emqx/Downloads/emqx-503/data/mnesia/emqx@127.0.0.1" is used.
use fallback at restart = false
running db nodes   = ['emqx@127.0.0.1']
stopped db nodes   = []
master node tables = []
backend types      = null_copies    - mria_mnesia_null_storage
                     rocksdb_copies - mnesia_rocksdb
remote             = []
ram_copies         = [bpapi,emqx_channel_registry,
                      emqx_ee_schema_registry_serde_tab,
                      emqx_exclusive_subscription,
                      emqx_gateway_coap_channel_registry,emqx_retainer_index,
                      emqx_retainer_index_meta,emqx_retainer_message,
                      emqx_route,emqx_routing_node,emqx_shared_subscription,
                      emqx_trie,mria_schema]
disc_copies        = [cluster_rpc_commit,cluster_rpc_mfa,emqx_acl,
                      emqx_activated_alarm,emqx_admin,emqx_admin_jwt,emqx_app,
                      emqx_authn_mnesia,emqx_banned,emqx_dashboard_monitor,
                      emqx_deactivated_alarm,emqx_delayed,
                      emqx_enhanced_authn_scram_mnesia,emqx_psk,
                      emqx_telemetry,emqx_trace,schema]
disc_only_copies   = []
[{'emqx@127.0.0.1',disc_copies}] = [schema,emqx_psk,emqx_delayed,emqx_app,
                                    emqx_admin_jwt,emqx_dashboard_monitor,
                                    emqx_admin,cluster_rpc_mfa,
                                    cluster_rpc_commit,emqx_acl,
                                    emqx_enhanced_authn_scram_mnesia,
                                    emqx_authn_mnesia,emqx_banned,
                                    emqx_activated_alarm,
                                    emqx_deactivated_alarm,emqx_telemetry,
                                    emqx_trace]
[{'emqx@127.0.0.1',ram_copies}] = [mria_schema,emqx_trie,
                                   emqx_shared_subscription,emqx_routing_node,
                                   emqx_route,emqx_exclusive_subscription,
                                   bpapi,emqx_channel_registry,
                                   emqx_retainer_index_meta,
                                   emqx_retainer_message,emqx_retainer_index,
                                   emqx_ee_schema_registry_serde_tab,
                                   emqx_gateway_coap_channel_registry]
414 transactions committed, 32 aborted, 6 restarted, 250 logged to disc
0 held locks, 0 in queue; 0 local transactions, 0 remote
0 transactions waits for other nodes: []

log ​

ログレベルや設定済みログ出力を管理するコマンドです。

log set-level <Level> ​

全体のログレベルを設定します。

bash
$ emqx ctl log set-level debug
debug

log primary-level ​

現在のプライマリログレベルを表示します。primary-levelはEMQXのデフォルトログレベルで、特定のログ出力に独立したレベルが設定されていない限り全体に適用されます。

bash
$ emqx ctl log primary-level
debug

log primary-level <Level> ​

プライマリログレベルを設定します。

bash
$ emqx ctl log primary-level info
info

log outputs list ​

設定済みのログ出力を表示します。outputsにはコンソール出力console、デフォルトのファイル出力file、および設定された名前付きファイル出力が含まれます。各ログ出力は独自のログレベル、出力先、状態を持ちます。

bash
$ emqx ctl log outputs list
LogOutput(name=console, level=debug, destination=console, status=enabled)
LogOutput(name=file, level=debug, destination=/var/log/emqx/emqx.log, status=enabled)

log outputs enable <name> ​

特定のログ出力を有効化します。<name>はconsole、file、または設定済みの名前付きファイル出力です。

bash
$ emqx ctl log outputs enable console
log output console enabled

log outputs disable <name> ​

特定のログ出力を無効化します。<name>はconsole、file、または設定済みの名前付きファイル出力です。

bash
$ emqx ctl log outputs disable console
log output console disabled

log outputs set-level <name> <Level> ​

特定のログ出力のログレベルを設定します。<name>はconsole、file、または設定済みの名前付きファイル出力です。

bash
$ emqx ctl log outputs set-level console debug
log output console level set to debug

trace ​

特定のクライアントやトピックなどのイベントをトレース（ログ記録）するコマンドです。

trace list ​

ローカルノードで開始中のトレースを一覧表示します。

bash
$ emqx ctl trace list
Trace(ip_address=127.0.0.1, level=debug, destination="trace.log")

trace start client <ClientId> <File> [<Level>] ​

特定クライアントのトレースを開始します。

bash
$ emqx ctl trace start client emqx_c trace.log debug
trace emqx_c CLI-emqx_c successfully

trace stop client <ClientId> ​

特定クライアントのトレースを停止します。

bash
$ emqx ctl trace stop client emqx_c
stop tracing clientid emqx_c successfully

trace start topic <Topic> <File> [<Level>] ​

特定トピックのトレースを開始します。

bash
$ emqx ctl trace start topic t/1 trace.log info
trace t/1 CLI-t/1 successfully

trace stop topic <Topic> ​

特定トピックのトレースを停止します。

bash
$ emqx ctl trace stop topic t/1
stop tracing topic t/1 successfully

trace start ip_address <IP> <File> [<Level>] ​

特定クライアントIPアドレスのトレースを開始します。

bash
$ emqx ctl trace start ip_address 127.0.0.1 trace.log debug
trace 127.0.0.1 CLI-127.0.0.1 successfully

trace stop ip_address <IP> ​

特定クライアントIPアドレスのトレースを停止します。

bash
$ emqx ctl trace stop ip_address 127.0.0.1
stop tracing ip_address 127.0.0.1 successfully

TIP

コマンドラインから開始する場合、トレースログファイルは絶対パスを使うことを推奨します。
例：emqx ctl trace start client foobar /abs/path/to/trace.log debug

TIP

トレースはダッシュボードUIからも管理可能です。詳細はログトレースを参照してください。

traces ​

traceコマンドに似ていますが、クラスタ全ノードでトレーサーを開始・停止します。

traces list ​

クラスタで開始中のトレースを一覧表示します。

bash
$ emqx ctl traces list
Trace(mytraces_ip: ip_address=127.0.0.1, waiting, LogSize:#{'emqx@127.0.0.1' => 0})

traces start <Name> client <ClientId> [<Duration>] ​

クラスタ内のクライアントのトレースを開始します。

bash
$ emqx ctl traces start mytraces client emqx_c 1200
cluster_trace clientid emqx_c mytraces successfully

traces start <Name> topic <Topic> [<Duration>] ​

クラスタ内のトピックのトレースを開始します。

bash
$ emqx ctl traces start mytraces_ip topic t/1 1200
cluster_trace topic t/1 mytraces_ip successfully

traces start <Name> ip_address <IPAddr> [<Duration>] ​

クラスタ内のクライアントIPのトレースを開始します。

bash
$ emqx ctl traces start mytraces_ip ip_address 127.0.0.1 1200
cluster_trace ip_address 127.0.0.1 mytraces_ip successfully

traces stop <Name> ​

クラスタ内のトレースを停止します。

bash
$ emqx ctl traces stop mytraces_ip
Stop cluster_trace mytraces_ip successfully

traces delete <Name> ​

クラスタ内のトレースを削除します。

bash
$ emqx ctl traces delete mytraces_ip
Del cluster_trace mytraces_ip successfully

listeners ​

リスナーを管理するコマンドです。

listeners ​

ローカルノードのMQTTリスナー情報を一覧表示します。EMQX 6.3.0以降は解決済みアドレスとそのソースも含まれます。

bash
emqx ctl listeners

IPアドレスを明示的に設定したリスナーの例:

text
ssl:default
  listen_on             : 0.0.0.0:8883
  acceptors             : 16
  proxy_protocol        : false
  enable                : true
  running               : true
  resolved_address      : 0.0.0.0
  resolved_address_from : bind
  current_conn          : 0
  max_conns             : 5000000
tcp:default
  listen_on             : 0.0.0.0:1883
  acceptors             : 16
  proxy_protocol        : false
  enable                : true
  running               : true
  resolved_address      : 0.0.0.0
  resolved_address_from : bind
  current_conn          : 12
  max_conns             : 5000000
  shutdown_count        : [{takenover,2},{discarded,1}]
ws:default
  listen_on             : 0.0.0.0:8083
  acceptors             : 16
  proxy_protocol        : false
  enable                : true
  running               : true
  resolved_address      : 0.0.0.0
  resolved_address_from : bind
  current_conn          : 0
  max_conns             : 5000000
wss:default
  listen_on             : 0.0.0.0:8084
  acceptors             : 16
  proxy_protocol        : false
  enable                : true
  running               : true
  resolved_address      : 0.0.0.0
  resolved_address_from : bind
  current_conn          : 0
  max_conns             : 5000000

リスナーアドレス情報 ​

以下のフィールドは設定されたバインドとローカルノードで選択されたアドレスを区別します。

フィールド説明
listen_onポートを含む設定されたバインド。ポートのみのバインドは例：:1883のように表示されます。
resolved_addressポートを含まない解決済みIPアドレス。空欄はポートのみバインドが全ネットワークインターフェースを指すことを意味します。
resolved_address_from以下で説明するアドレスのソース。
runningリスナーが稼働中かどうか。停止中でも解決済みアドレスは表示されますが、接続受付中とは限りません。

resolved_address_fromに入る値:

値意味
bindリスナーのbindで明示的にIPアドレスが指定されている。
0.0.0.0node.default_listener_addressまたはセキュリティプロファイルが全ネットワークインターフェースを選択。
127.0.0.1node.default_listener_addressまたはセキュリティプロファイルがループバックを選択。
nodenameローカルErlangノード名のホスト部分から取得。
IPアドレスまたはホスト名node.default_listener_addressの値から取得。

例：bind = 1883かつnode.default_listener_address = "all"の場合、listen_onは:1883、resolved_addressは空、resolved_address_fromは0.0.0.0。明示的にbind = "0.0.0.0:1883"の場合、解決済みアドレスは0.0.0.0、ソースはbind。

本コマンドはクラスター全体のアドレスを集約しません。リスナーアドレス情報の他の確認方法はリスナーアドレス情報の表示を参照してください。

一般的なシャットダウン理由 ​

TCPリスナーでは、EMQXはshutdown_countフィールドを報告し、理由別に切断されたクライアント数を記録します。TCPリスナーからの切断理由の特定に役立ちます。

bash
shutdown_count  : [{takenover,2},{discarded,1}]

上記例では：

  • 2件は同一clientidでclean_start = falseの新しいセッションによるテイクオーバー切断
  • 1件は同一clientidでclean_start = trueの新しいセッションによる破棄切断

以下はよくあるシャットダウン理由一覧です。

理由説明
bannedACL違反、レート制限、IP制限によりクライアントがブラックリスト入り。
closedサーバまたはクライアントによる接続クローズ。
discarded同一clientidかつclean_start = trueの新クライアント接続により既存セッション破棄。
takenover同一clientidかつclean_start = falseの新クライアント接続により既存セッションテイクオーバー。
einval無効な引数やソケットエラー。通常はすでに閉じたソケットへの書き込み競合による。
frame_too_largeMQTTパケットが最大フレームサイズを超過。
idle_timeoutTCP/SSL接続確立後、許容時間内にCONNECTパケット受信なし。
invalid_proto_nameCONNECTパケットのプロトコル名が無効または"MQTT"でない。
invalid_topic不正なトピック使用（不正文字含む、ブローカーにより禁止など）。
keepalive_timeoutキープアライブ間隔内にパケット送信なし。
malformed_packetMQTTパケットが破損またはMQTT仕様に準拠しない。
not_authorizedACLにより認可されていない操作をクライアントが試行。
ssl_closedSSL/TLS接続がピアによりクローズ。
ssl_errorSSL/TLSハンドシェイクまたはデータ送受信中のエラー。
ssl_upgrade_timeoutSSL/TLSハンドシェイクが許容時間内に完了しなかった。
unexpected_packet現在の接続状態で予期しないパケット受信。
zero_remaining_lenパケットの残り長さフィールドがゼロ（多くの場合無効）。
bad_username_or_password認証失敗（ユーザー名またはパスワード誤り）。
client_identifier_not_validログイン時に提供されたclientidが無効または他クライアントにロックされている。
protocol_error一般的なMQTTプロトコル違反。
tcp_closedクライアントまたはネットワーク障害によるTCP接続クローズ。
timeout一般的なタイムアウト（認証中など）。

listeners stop <Identifier> ​

リスナーを停止します。識別子は{type}:{name}形式（例：tcp:default）。一時的な効果で、EMQX再起動後に元に戻ります。

bash
$ emqx ctl listeners stop tcp:default
Stop tcp:default listener successfully.

TIP

リスナー停止は接続中のすべてのクライアントを切断します。

listeners start <Identifier> ​

リスナーを起動します（一時的な効果）。

bash
$ emqx ctl listeners start tcp:default
Started tcp:default listener successfully.

listeners restart <Identifier> ​

リスナーを再起動します。

bash
$ emqx ctl listeners restart tcp:default
Restarted tcp:default listener successfully.

TIP

リスナー再起動は接続中のすべてのクライアントを切断します。

listeners enable <Identifier> <true/false> ​

リスナーを有効または無効にします。設定に永続化され、恒久的に有効となります。

bash
$ emqx ctl listeners enable tcp:default true
Enabled tcp:default listener successfully.
bash
$ emqx ctl listeners enable tcp:default false
Disabled tcp:default listener successfully.

authz cache-clean ​

認可（ACL）キャッシュを強制的に削除したい場合に便利なコマンドです。

authz cache-clean all ​

すべてのノードの認可キャッシュをクリアします。

bash
$ emqx ctl authz cache-clean all
Authorization cache drain started on all nodes OK

authz cache-clean node <Node> ​

指定ノードの認可キャッシュをクリアします。

bash
$ emqx ctl authz cache-clean node emqx@127.0.0.1
Authorization cache drain started on node emqx@127.0.0.1 OK

authz cache-clean <ClientId> ​

指定クライアントの認可キャッシュをクリアします。

bash
$ emqx ctl authz cache-clean mqttx_9502dc8a
Drain mqttx_9502dc8a authz cache OK

pem_cache ​

更新されたpem（x509鍵・証明書）ファイルをEMQXに強制リロードさせるコマンドです。

pem_cache clean all ​

すべてのノードのx509証明書キャッシュをクリアします。

bash
$ emqx ctl pem_cache clean all
PEM cache clean OK

pem_cache clean node <Node> ​

指定ノードのx509証明書キャッシュをクリアします。

bash
$ emqx ctl pem_cache clean emqx@127.0.0.1
emqx@127.0.0.1 PEM cache clean OK

olp ​

OLPは過負荷保護（overload protection）の略です。
olpコマンドは過負荷状態の確認や過負荷保護の有効・無効を操作します。

詳細はoverload_protection設定ドキュメントを参照してください。

TIP

olpはデフォルトで有効化されておらず、CLIから有効化しても設定ファイルには永続化されません。

olp status ​

システムが過負荷の場合は過負荷保護の状態を返し、そうでなければ「not overloaded」と報告します。

bash
$ emqx ctl olp status
'emqx@172.17.0.3' is not overloaded

olp enable ​

過負荷保護を有効化します。

bash
$ emqx ctl olp enable
Enable overload protection 'emqx@127.0.0.1' : {ok,<0.5703.0>}

olp disable ​

過負荷保護を無効化します。

bash
$ emqx ctl olp disable
Disable overload protetion 'emqx@127.0.0.1' : ok

data ​

ノードのデータをtarアーカイブファイルへエクスポート/インポートするコマンドです。

data export ​

bash
data export \
  [--root-keys key1,key2,key3] \
  [--table-sets set1,set2,set3] \
  [--dir out_dir]

EMQXノードのデータをtarアーカイブファイルにエクスポートします。バックアップやノード間データ転送に便利です。

含まれるデータ:

  • クラスター設定
  • EMQXデータディレクトリの追加ファイル（SSL証明書など）
  • 組み込みデータベース

--root-keysと--table-setsオプションでエクスポート対象を指定可能。指定しない場合は全データをエクスポートします。

bash
emqx ctl data export --root-keys listeners,connectors,actions,rule_engine --dir /tmp
Exporting data to "/tmp/emqx-export-2025-08-06-12-00-19.334.tar.gz"...
Exporting cluster configuration...
Exporting additional files from EMQX data_dir: "data"...
Exporting built-in database...
Exporting emqx_banned_rules database table...
Exporting emqx_banned database table...
Exporting emqx_psk database table...
Exporting emqx_authn_mnesia database table...
Exporting emqx_authn_scram_mnesia database table...
Exporting emqx_acl database table...
Exporting emqx_app database table...
Exporting emqx_mt_config database table...
Exporting emqx_admin database table...
Exporting emqx_retainer_message database table...
Data has been successfully exported to /tmp/emqx-export-2025-08-06-12-00-19.334.tar.gz.

data import <File> ​

指定したtarアーカイブファイルからデータをインポートします。バックアップからの復元や新ノードへのデータ転送に使用します。

emqx ctl data import /tmp/emqx-export-2025-08-06-12-00-19.334.tar.gz
Importing data from "/tmp/emqx-export-2025-08-06-12-00-19.334.tar.gz"...
Importing cluster configuration for namespace global...
Importing built-in database...
Importing emqx_retainer_message database table...
Starting reindexing retained messages
Reindexed 3 messages
Reindexing retained messages finished
Importing emqx_admin database table...
Importing emqx_mt_config database table...
Importing emqx_app database table...
Importing emqx_acl database table...
Importing emqx_authn_scram_mnesia database table...
Importing emqx_authn_mnesia database table...
Importing emqx_psk database table...
Importing emqx_banned database table...
Importing emqx_banned_rules database table...
Data has been imported successfully.

ds ​

Durable Storageを操作するコマンドです。

ds info ​

組み込みDurable Storageの状態概要を表示します。

bash
emqx ctl ds info
THIS SITE:
EFC84E67230295E2

SITES:
.------------------.----------------.--------.
: Site             : Node           : Status :
:------------------:----------------:--------:
: EFC84E67230295E2 : emqx@127.0.0.1 :     up :
 ------------------ ---------------- --------

SHARDS:
.----------.----------.-------------.
: DB/Shard : Replicas : Transitions :
:----------:----------:-------------:
 ---------- ---------- -------------

ds set-replicas <storage> <site1> <site2> ... ​

Durable Storageのレプリカセットを変更します。

ds join <storage> <site> ​

ストレージのレプリカセットにサイトを追加します。

ds leave <storage> <site> ​

ストレージのレプリカセットからサイトを削除します。

ds forget <site> ​

既知のサイトリストからサイトを削除します。

exclusive ​

現在のシステムのすべての排他トピックを表示または排他トピックを削除するコマンドです。

exclusive list ​

すべての排他トピックを一覧表示します。

bash
$ emqx ctl exclusive list
t/1 -> client1

exclusive delete <Topic> ​

排他トピックを削除します。

bash
$ emqx ctl exclusive delete t/1
ok

retainer ​

retainerコマンドは保持メッセージの確認・管理に使用します。emqx ctl retainer reindexコマンドで保持メッセージのインデックス作成・更新も可能です。

retainer info ​

保持メッセージ数を表示します。

bash
$ emqx ctl retainer info
Number of retained messages: 3

retainer topics ​

保持メッセージがあるすべてのトピックを表示します。

bash
$ emqx ctl retainer topics
$SYS/brokers
$SYS/brokers/emqx@127.0.0.1/sysdescr
$SYS/brokers/emqx@127.0.0.1/version

retainer clean ​

すべての保持メッセージをクリアします。

bash
emqx ctl retainer clean

retainer clean <Topic> ​

特定トピックフィルターに基づき保持メッセージをクリアします。

bash
emqx ctl retainer clean t/1

retainer reindex status ​

インデックス作成処理の状態を表示します。

bash
$ emqx ctl retainer reindex status
Reindexing is not running

retainer reindex start [force] ​

設定に基づき保持メッセージトピックの新しいインデックスを生成します。<force>にtrueを渡すと、既存のインデックス作成処理を無視して強制開始します。

bash
$ emqx ctl retainer reindex start true
Starting reindexing
Reindexed 0 messages
Reindexing finished

observer ​

Erlang仮想マシンの状態を監視するコマンドで、Linuxのtopコマンドのようなリアルタイムビューを提供します。サブコマンドは以下の通りです。

observer status ​

現在のコンソールでobserverを起動し、EMQXノードの状態や活動を監視・デバッグします。

bash
$ emqx ctl observer status

observer bin_leak ​

すべてのプロセスにガベージコレクションを強制実行し、最大のバイナリデータを解放した上位100プロセスを表示します。メモリリークの可能性を調査するのに役立ちます。

bash
$ emqx ctl observer bin_leak
{<0.2140.0>,-48,
 [{current_function,{logger_std_h,file_ctrl_loop,1}},
  {initial_call,{erlang,apply,2}}]}
{<0.2093.0>,-29,
 [{current_function,{application_master,main_loop,2}},
  {initial_call,{proc_lib,init_p,5}}]}
{<0.2116.0>,-23,
 [user_drv,
  {current_function,{user_drv,server_loop,6}},
  {initial_call,{user_drv,server,2}}]}
...

observer load Mod ​

指定したモジュールをEMQXクラスタ内のすべてのノードにロードします。クラスタ全体でモジュールの利用を保証したい場合に使用します。

bash
$ emqx ctl observer load Mod
Loaded 'Mod' module on []: ok

conf ​

EMQXクラスター設定の確認・変更に使用するコマンドです。

conf reload --replace|--merge ​

ローカルノードのetc/emqx.confをリロードします。既存設定に新設定を上書きするのがデフォルトです。--replaceを付けると既存設定を新設定で置き換えます。

conf show_keys ​

現在使用中のすべての設定キーを表示します。

conf show [<key>] ​

指定キー以下の設定（デフォルト値含む）を表示します。キー未指定時は全キーを表示します。

conf load --replace|--merge <path> ​

HOCON形式の設定ファイルを読み込みます。既存設定に新設定を上書きするのがデフォルトです。--replaceで置換します。現在のノードがクラスタ全体に設定変更を同期するトランザクションを開始します。

注意：ローリングアップグレード中はランタイム設定変更を行わないでください。

conf cluster_sync ​

クラスタ内ノード間の設定同期に問題がある場合のトラブルシューティング用コマンドです。

TIP

EMQX 5.0.xではcluster_callという名前でした。5.1でも古いコマンドは利用可能ですが、ヘルプには表示されません。

EMQX HTTP APIは多くの設定変更に利用可能です。API呼び出し（例：ダッシュボード操作）時、受け取ったノードはまずローカルのdata/configs/cluster.hoconに変更を書き込み、その後データベースに記録し、非同期で他ノードに転送します。

何らかの理由でピアノードに適用できない場合、本コマンドで同期状況を調査・修正できます。

EMQXはクラスタ範囲内の設定変更に対しID（tnx_id）を生成し、クラスタ内で厳密に増加します。ダッシュボード等での変更はすべてデータベースに記録されます。

TIP

skipやfast_forwardコマンドはクラスタ内ノード間で設定不整合を引き起こす可能性があります。

conf cluster_sync status ​

全ノードのクラスタ設定同期状況の概要を表示します。

bash
$ emqx ctl conf cluster_sync status
-----------------------------------------------
All configuration synchronized(tnx_id=0) successfully
-----------------------------------------------

conf cluster_sync inspect <tnx_id> ​

指定したtnx_idの設定変更トランザクションの詳細を調査します。

例：2番目の変更（tnx_id=2）でTLSリスナー有効化操作を表示

bash
$ emqx ctl conf cluster_sync inspect 2
{atomic,#{created_at => {{2022,6,21},{21,57,50}},
          initiator => 'emqx@127.0.0.1',
          mfa =>
              {emqx,update_config,
                    [[listeners,ssl,default],
                     {action,stop,#{<<"enabled">> => false}},
                     #{override_to => cluster,rawconf_with_defaults => true}]},
          tnx_id => 2}}

conf cluster_sync skip [node] ​

指定ノードの（失敗中の）コミットをインクリメントします。

注意

クラスタノード間で設定不整合を引き起こす可能性があります。

conf cluster_sync fast_forward [node] <tnx_id> ​

指定ノードの設定変更を指定tnx_idまで高速進行させます。

注意

クラスタノード間で設定不整合を引き起こす可能性があります。

conf cluster_sync fix ​

最も包括的な設定を持つノード（通常は設定リーダーで最高tnx_id）から他ノードへ同期します。

eviction status ​

現在のノードのエビクション（追い出し）状態を取得します。

bash
$ emqx ctl eviction
Eviction status: disabled

rebalance ​

クラスター内の負荷分散を目的に、高負荷ノードから低負荷ノードへ接続やセッションを移行するコマンドです。

rebalance start --evacuation ​

現在ノードの退避を開始し、オプションで指定サーバーへのリダイレクトを行います。

rebalance start --evacuation \
  [--wait-health-check Secs] \
  [--redirect-to "Host1:Port1 Host2:Port2 .."] \
  [--conn-evict-rate CountPerSec] \
  [--migrate-to "node1@host1 node2@host2 .."] \
  [--wait-takeover Secs] \
  [--sess-evict-rate CountPerSec]

rebalance start ​

現在ノードをコーディネーターとして指定ノードでリバランスを開始します。

rebalance start \
  [--nodes "node1@host1 node2@host2 .."] \
  [--wait-health-check Secs] \
  [--conn-evict-rate ConnPerSec] \
  [--abs-conn-threshold Count] \
  [--rel-conn-threshold Fraction] \
  [--wait-takeover Secs] \
  [--sess-evict-rate CountPerSec] \
  [--abs-sess-threshold Count] \
  [--rel-sess-threshold Fraction]

rebalance node-status ​

現在ノードのリバランス状態を取得します。

rebalance node-status "node1@host1" ​

リモートノードのリバランス状態を取得します。

rebalance status ​

クラスタ全体のリバランス/退避処理の状態を取得します。

rebalance stop ​

現在ノードの退避を停止します。

gateway ​

ゲートウェイの読み込み・稼働状況を確認・管理するコマンドです。

gateway list ​

すべてのゲートウェイ情報を一覧表示します。

bash
$ emqx ctl gateway list
Gateway(name=coap, status=running, clients=0, started_at=2023-05-22T14:23:50.353+08:00)
Gateway(name=lwm2m, status=unloaded)
Gateway(name=mqttsn, status=unloaded)
Gateway(name=stomp, status=unloaded)

gateway lookup <Name> ​

特定ゲートウェイの詳細情報を照会します。

bash
$ emqx ctl gateway lookup coap
name: coap
status: running
created_at: 2023-05-22T14:23:50.352+08:00
started_at: 2023-05-22T14:23:50.353+08:00
config: #{connection_required => false,enable => true,enable_stats => true,
          heartbeat => 30000,idle_timeout => 30000,
          listeners =>
              #{udp =>
                    #{default =>
                          #{access_rules => [],bind => 5683,enable => true,
                            enable_authn => true,max_conn_rate => 1000,
                            max_connections => 1024000,
                            udp_options =>
                                #{active_n => 100,reuseaddr => true}}}},
          mountpoint => <<>>,notify_type => qos,publish_qos => coap,
          subscribe_qos => coap}

gateway load <Name> <JsonConf> ​

ゲートウェイをロードし、パラメーターを設定します。

bash
emqx ctl gateway load coap '{"type":"coap", ...}'

gateway unload <Name> ​

ゲートウェイをアンロードします。

bash
$ emqx ctl gateway unload coap
ok

gateway stop <Name> ​

ゲートウェイを停止します。

bash
$ emqx ctl gateway stop coap
ok

gateway start <Name> ​

ゲートウェイを起動します。

bash
$ emqx ctl gateway start coap
ok

gateway-registry ​

emqx ctl gateway-registry

システムに登録されているゲートウェイ一覧を表示します。

デフォルトで5つのゲートウェイが登録されています：

  • coap
  • lwm2m
  • mqttsn
  • stomp

EMQXはプラグイン可能に設計されており、追加のゲートウェイをプラグインとしてインストールし、ランタイムでEMQXに登録可能です。
登録後は管理APIやCLI（gatewayコマンド）で管理できます。

gateway-clients ​

ゲートウェイクライアントを確認するコマンドです。

gateway-clients list <Name> ​

ゲートウェイのすべてのクライアントを一覧表示します。

gateway-clients lookup <Name> <ClientId> ​

指定クライアントの情報を照会します。

gateway-clients kick <Name> <ClientId> ​

ゲートウェイから特定クライアントを強制切断します。

gateway-metrics <Name> ​

ゲートウェイのすべてのメトリクスを一覧表示します。

license ​

license info ​

ライセンス情報を表示します。

bash
$ emqx ctl license info
customer        : Developer
email           : contact@emqx.io
deployment      : Development
max_sessions    : 10000000
start_at        : 2025-03-02
expiry_at       : 2029-03-01
type            : community
customer_type   : 11
expiry          : false

license update License ​

ライセンス情報を更新します。

bash
emqx ctl license update <YOUR_LICENSE_STRING>

YOUR_LICENSE_STRINGは実際のライセンス文字列に置き換えてください。

license update default ​

デフォルトのCommunityライセンスに戻します。

bash
emqx ctl license update default

license history ​

セッションのハイウォーターマーク履歴を表示します。EMQX Enterpriseは日次ピークセッション数を記録し、課金監査のため少なくとも24ヶ月分の履歴を保持します。

bash
emqx ctl license history [N] [--period daily|monthly] [--json]
  • N: 省略可能な正の整数。返す行数の上限（デフォルトは月次で24）
  • --period daily|monthly: 集計粒度。dailyはカレンダー日ごと、monthlyは日次ピークを月次最大に折りたたむ（デフォルトはmonthly）
  • --json: プレーンテキストではなくJSON形式で出力

例：プレーンテキスト出力

bash
$ emqx ctl license history
period=2026-04 high_watermark=25000 observed_at=2026-04-18T13:53:05.000Z
period=2026-03 high_watermark=23500 observed_at=2026-03-31T22:10:42.000Z

例：JSON出力

bash
$ emqx ctl license history --json
json
{
  "period": "monthly",
  "count": 2,
  "data": [
    { "period": "2026-04", "high_watermark": 25000, "observed_at": "2026-04-18T13:53:05.000Z" },
    { "period": "2026-03", "high_watermark": 23500, "observed_at": "2026-03-31T22:10:42.000Z" }
  ]
}

まだデータが記録されていない場合、プレーンテキスト出力は以下を表示します。

No session high-watermark history recorded.

mt ​

mtコマンドはEMQX Enterpriseのマルチテナンシー保守操作を提供します。

mt purge_ns <Namespace> ​

EMQX Enterprise 6.1.4以降、このコマンドは指定したネームスペースを削除し、同期的にクリーンアップ処理を実行します。クリーンアップはネームスペース設定と組み込みデータベースのネームスペーススコープデータ（パスワード認証ユーザー、SCRAMユーザー、認可ルールなど）を削除します。ネームスペースが存在しなくてもコマンドは実行されます。

ネームスペース状態が変わっていなければ操作は冪等です。クリーンアップが完了しなかった場合、同名のネームスペースが再作成されていなければ再実行可能です。

中断されたネームスペース削除で残ったデータを除去する最後の手段として使用してください。通常のネームスペース削除はダッシュボードまたはDELETE /mt/ns/<namespace> REST APIを使用してください。

重要

存在するネームスペースに対してこのコマンドを実行するとネームスペースとそのデータが永久に削除されます。
同名のネームスペースが再作成された後に再実行しないでください。

例：tenant-aネームスペースを削除

bash
emqx ctl mt purge_ns tenant-a

すべてのクリーンアップステップが成功した場合、出力JSONに"result": "ok"が含まれます。

json
{"namespace":"tenant-a","result":"ok"}

クリーンアップのいずれかが失敗した場合、出力JSONに"error": "cleanup_incomplete"が含まれます。

json
{"error":"cleanup_incomplete","hint":"some cleanup steps failed; check logs and re-run the command to retry","namespace":"tenant-a"}

EMQXログを確認し失敗原因を解決してから再実行してください。

admins ​

管理ユーザーを管理するコマンドです。

admins add <Username> <Password> <Description> ​

ダッシュボードユーザーを追加します。

bash
$ emqx ctl admins add emqx_u EMQemq@1172
ok

admins passwd <Username> <Password> ​

特定ダッシュボードユーザーのパスワードをリセットします。

bash
$ emqx ctl admins passwd emqx_u EMQemq@11721
ok

admins del <Username> ​

特定ダッシュボードユーザーを削除します。

bash
$ emqx ctl admins del emqx_u
ok

api_keys ​

REST APIキーをコマンドラインから管理するコマンドです。ダッシュボードにログインせずAPIアクセスを初期化できます。

api_keys list ​

すべてのAPIキーを一覧表示します。

bash
$ emqx ctl api_keys list
[
  {
    "role" : "administrator",
    "name" : "my-key",
    "expired_at" : "infinity",
    "expired" : false,
    "enable" : true,
    "desc" : "",
    "api_key" : "admin"
  }
]

api_keys show --name <Name> ​

特定APIキーの詳細を表示します。

bash
$ emqx ctl api_keys show --name my-key

api_keys add ​

新しいAPIキーを作成します。生成されたapi_keyとapi_secretが出力されます。api_secretは作成時のみ表示されます。

bash
$ emqx ctl api_keys add --name my-key --role viewer --valid-days 30 --desc "My API key"
{
  "role" : "viewer",
  "name" : "my-key",
  "expired_at" : 1777201070,
  "expired" : false,
  "enable" : true,
  "desc" : "My API key",
  "api_secret" : "tEWX9APine9B9Bkk...",
  "api_key" : "CPKcoFpIkIlbaqhL"
}

オプション:

オプション説明
--name <Name>必須。APIキーを識別する名前。
--api-secret <Secret>任意。秘密鍵を指定。省略時は自動生成。
--valid-days <infinity|days>任意。有効期間。infinityは期限なし（デフォルト）、または日数指定。
--role <Role>任意。administrator（デフォルト）、viewer、publisherのいずれか。詳細はRoles and Permissions参照。
--desc <Desc>任意。APIキーの説明。

api_keys enable --name <Name> ​

無効化済みAPIキーを有効化します。

bash
$ emqx ctl api_keys enable --name my-key

api_keys disable --name <Name> ​

APIキーを削除せず無効化します。

bash
$ emqx ctl api_keys disable --name my-key

api_keys del --name <Name> ​

APIキーを削除します。

bash
$ emqx ctl api_keys del --name my-key
{
  "result" : "ok",
  "name" : "my-key"
}

rules ​

ルールエンジンで作成されたルールを一覧表示するコマンドです。

rules list ​

ルールID、名前などの情報を含むすべてのルールを一覧表示します。

bash
$ emqx ctl rules list
Rule{id=my-rule, name=, enabled=true, descr=this is my rule}

rules show <RuleID> ​

特定ルールの詳細情報を表示します。

bash
$ emqx ctl rules show my-rule
Id:
  my-rule
Name:

Description:
  this is my rule
Enabled:
  true
SQL:
  SELECT
    *
  FROM
    "f/#"
Created at:
  2023-05-22T14:14:27.567+08:00
Updated at:
  2023-05-22T14:14:27.567+08:00
Actions:
  - Name:  republish
    Type:  function
    Args:  #{payload => <<>>,qos => 0,retain => false,topic => <<"t/1">>,
             user_properties => <<"${user_properties}">>}

CLIは検査用であり、ルールおよびアクションの管理はダッシュボードで行います。