Docs

# 命令行接口

EMQX 提供了 ./bin/emqx_ctl 的管理命令行，用于用户对 EMQX 进行管理、配置、查询。

# status 命令

查询 EMQX 运行状态:

$ ./bin/emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

  
    Copied!
1
2
3

# mgmt 命令

mgmt 命令查询应用程序。

命令 描述
mgmt list 列出应用程序列表
mgmt insert <AppId> <Name> 添加允许访问 HTTP API 的应用程序
mgmt update <AppId> <status> 更新允许访问 HTTP API 的应用程序
mgmt lookup <AppId> 获取允许访问 HTTP API 的应用程序详情
mgmt delete <AppId> 删除允许访问 HTTP API 的应用程序

# mgmt list

列出应用程序列表:

$ ./bin/emqx_ctl mgmt list
app_id: 901abdba8eb8c, secret: MjgzMzQ5MjM1MzUzMTc4MjgyMjE3NzU4ODcwMDg0NjQ4OTG, name: hello, desc: , status: true, expired: undefined

  
    Copied!
1
2

# mgmt insert <AppId> <Name>

添加 HTTP API 的应用程序:

$ ./bin/emqx_ctl mgmt insert dbcb6e023370b world
AppSecret: MjgzMzQ5MjYyMTY3ODk4MjA5NzMwODExODMxMDM1NDk0NDA

  
    Copied!
1
2

# mgmt update <AppId> <status>

更新 HTTP API 的应用程序:

$ ./bin/emqx_ctl mgmt update dbcb6e023370b stop
update successfully.

  
    Copied!
1
2

# mgmt lookup <AppId>

获取 HTTP API 的应用程序详情:

$ ./bin/emqx_ctl mgmt lookup dbcb6e023370b
app_id: dbcb6e023370b
secret: MjgzMzQ5MjYyMTY3ODk4MjA5NzMwODExODMxMDM1NDk0NDA
name: world
desc: Application user
status: stop
expired: undefined

  
    Copied!
1
2
3
4
5
6
7

# mgmt delete <AppId>

删除 HTTP API 的应用程序:

$ ./bin/emqx_ctl mgmt delete dbcb6e023370b
ok

  
    Copied!
1
2

# broker 命令

broker 命令查询服务器基本信息，启动时间，统计数据与性能数据。

命令 描述
broker 查询 EMQX 描述、版本、启动时间
broker stats 查询连接 (Connection)、会话 (Session)、主题 (Topic)、订阅 (Subscription)、路由 (Route) 统计信息
broker metrics 查询 MQTT 报文 (Packet)、消息 (Message) 收发统计

查询 EMQX 基本信息，包括版本、启动时间等:

$ ./bin/emqx_ctl broker
sysdescr  : EMQX Broker
version   : 4.0.0
uptime    : 4 minutes, 52 seconds
datetime  : 2020-02-21 09:39:58

  
    Copied!
1
2
3
4
5

# broker stats

查询服务器客户端连接 (Connections)、主题 (Topics)、订阅 (Subscriptions)、路由 (Routes) 统计:

$ ./bin/emqx_ctl broker stats
channels.count                : 1
channels.max                  : 1
connections.count             : 1
connections.max               : 1
live_connections.count        : 1
live_connections.max          : 1
modules.count                 : 6
modules.max                   : 6
retained.count                : 0
retained.max                  : 5
routes.count                  : 1
routes.max                    : 1
sessions.count                : 1
sessions.max                  : 1
suboptions.count              : 1
suboptions.max                : 1
subscribers.count             : 1
subscribers.max               : 1
subscriptions.count           : 1
subscriptions.max             : 1
subscriptions.shared.count    : 0
subscriptions.shared.max      : 0
topics.count                  : 1
topics.max                    : 1

  
    Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# broker metrics

查询服务器流量 (Bytes)、MQTT 报文 (Packets)、消息 (Messages) 收发统计:

$ ./bin/emqx_ctl broker metrics
bytes.received                : 0
bytes.sent                    : 0
client.auth.anonymous         : 0
client.authenticate           : 0
client.check_acl              : 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.expired      : 0
messages.dropped.no_subscriber: 0
messages.forward              : 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.retained             : 3
messages.sent                 : 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.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.takeovered            : 0
session.terminated            : 0

  
    Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# cluster 命令

cluster 命令可以管理由多个 EMQX 节点（进程）组成的集群:

命令 描述
cluster join <Node> 加入集群
cluster leave 离开集群
cluster force-leave <Node> 从集群删除节点
cluster status 查询集群状态

示例:

为更好地展示 cluster 命令，我们可以先在单机上启动两个节点并组成集群，这称之为伪分布式启动模式。由于我们要在单机上启动两个 emqx 实例，为避免端口冲突，我们需要对其它节点的监听端口做出调整。

基本思路是复制一份 emqx 文件夹然后命名为 emqx2 ，将原先所有 emqx 节点监听的端口 port 加上一个偏移 offset 作为新的 emqx2 节点的监听端口。例如，将原先 emqx 的MQTT/TCP 监听端口由默认的 1883 改为了 2883 作为 emqx2 的 MQTT/TCP 监听端口。完成以上操作的自动化脚本可以参照 集群脚本 (opens new window)，具体配置请参见 配置说明 与 配置项。

启动 emqx1 :

$ cd emqx1 && ./bin/emqx start

  
    Copied!
1

启动 emqx2 :

$ cd emqx2 && ./bin/emqx start

  
    Copied!
1

使用 cluster join <Node> 将两个节点组成集群：

$ cd emqx2 && ./bin/emqx_ctl cluster join emqx1@127.0.0.1

Join the cluster successfully.
Cluster status: [{running_nodes,['emqx1@127.0.0.1','emqx2@127.0.0.1']}]

  
    Copied!
1
2
3
4

任意节点目录下查询集群状态:

$ ./bin/emqx_ctl cluster status
Cluster status: [{running_nodes,['emqx2@127.0.0.1','emqx1@127.0.0.1']}]

  
    Copied!
1
2

集群消息路由测试: MQTT 命令行工具使用由 EMQX 团队开发的 emqtt (opens new window) 客户端。

# emqx1 节点（1883 端口）订阅主题 x
$ ./bin/emqtt sub -t x -q 1 -p 1883
Client emqtt-a7de8fffbe2fbeb2fadb sent CONNECT
Client emqtt-a7de8fffbe2fbeb2fadb subscribed to x

# 向 emqx2 节点（2883 端口 ）发布消息
$ ./bin/emqtt pub -t x -q 1 -p 2883 --payload hello
Client emqtt-0898fa447676e17479a5 sent CONNECT
Client emqtt-0898fa447676e17479a5 sent PUBLISH (Q1, R0, D0, Topic=x, Payload=...(5 bytes))
Client emqtt-0898fa447676e17479a5 sent DISCONNECT

# emqx1 节点（1883 端口）收到消息
$ ./bin/emqtt sub -t x -q 1 -p 1883
hello

  
    Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14

emqx2 节点离开集群:

$ cd emqx2 && ./bin/emqx_ctl cluster leave

  
    Copied!
1

强制 emqx2 节点离开集群，需要在集群下的目标节点以外的节点上进行操作:

$ cd emqx1 && ./bin/emqx_ctl cluster force-leave emqx2@127.0.0.1

  
    Copied!
1

注意，EMQX 不支持一个已经在一个集群中的节点加入另外一个集群，因为这会导致两个集群数据不一致，但支持加入过集群的节点在离开该集群后加入另一个集群。

# acl 命令

从 v4.1 之后引入了 modules 的命令，我们使用以下命令重新加载 ACL：

$ ./bin/emqx_ctl modules reload emqx_mod_acl_internal
Module emqx_mod_acl_internal reloaded successfully.

  
    Copied!
1
2

在 v4.1 之前，则仍然使用：

$ ./bin/emqx_ctl acl reload
ok

  
    Copied!
1
2

# acl cache-clean

在 v4.3 之后，引入了的命令来清理 ACL 缓存:

命令 描述
acl cache-clean all 清除集群中所有的 ACL 缓存
acl cache-clean node <Node> 清除指定节点的 ACL 缓存
acl cache-clean <ClientId> 清除指定客户端的 ACL 缓存

# clients 命令

clients 命令查询连接的 MQTT 客户端。

命令 描述
clients list 列出所有客户端连接
clients show <ClientId> 查询指定 ClientId 的客户端
clients kick <ClientId> 踢除指定 ClientId 的客户端，连接与会话将一并终结。

# clients list

列出所有客户端连接:

$ ./bin/emqx_ctl clients list
Client (mosqsub/43832-airlee.lo, username=test1, peername=127.0.0.1:62135, clean_start=true, keepalive=60, session_expiry_interval=0, subscriptions=0, inflight=0, awaiting_rel=0, delivered_msgs=0, enqueued_msgs=0, dropped_msgs=0, connected=true, created_at=1582249657, connected_at=1582249657)
Client (mosqsub/44011-airlee.lo, username=test2, peername=127.0.0.1:64961, clean_start=true, keepalive=60, session_expiry_interval=0, subscriptions=0, inflight=0, awaiting_rel=0, delivered_msgs=0, enqueued_msgs=0, dropped_msgs=0, connected=true, created_at=1582249657, connected_at=1582249657, disconnected_at=1582249702)
    ...

  
    Copied!
1
2
3
4

返回 Client 对象的属性:

Name 描述
username 用户名
peername 客户端 IP 与端口
clean_start MQTT Clean Start
keepalive MQTT KeepAlive
session_expiry_interval 会话过期间隔
subscriptions 当前订阅数量
inflight 当前正在下发的 QoS 1 和 QoS 2 的消息总数
awaiting_rel 等待客户端发送 PUBREL 的 QoS2 消息数
delivered_msgs EMQX 向此客户端转发的消息数量 (包含重传)
enqueued_msgs 消息队列当前长度
dropped_msgs 消息队列达到最大长度后丢弃的消息数量
connected 是否在线
created_at 会话创建时间戳
connected_at 客户端连接时间戳
disconnected_at 客户端断开连接时间戳（仅当断开连接还保留会话时才会出现）

# clients show <ClientId>

查询指定 ClientId 的客户端:

$ ./bin/emqx_ctl clients show "mosqsub/43832-airlee.lo"
Client (mosqsub/43832-airlee.lo, username=test1, peername=127.0.0.1:62747, clean_start=false, keepalive=60, session_expiry_interval=7200, subscriptions=0, inflight=0, awaiting_rel=0, delivered_msgs=0, enqueued_msgs=0, dropped_msgs=0, connected=true, created_at=1576479557, connected_at=1576479557)

  
    Copied!
1
2

# clients kick <ClientId>

踢除指定 ClientId 的客户端:

$ ./bin/emqx_ctl clients kick "clientid"
ok

  
    Copied!
1
2

# routes 命令

routes 命令用于查询路由信息。

EMQX 中路由是指主题与节点的映射关系，用于在多个节点之间路由消息。

命令 描述
routes list 列出所有路由
routes show <Topic> 查询指定 Topic 的路由

# routes list

列出所有路由:

$ ./bin/emqx_ctl routes list
t2/# -> emqx2@127.0.0.1
t/+/x -> emqx2@127.0.0.1,emqx@127.0.0.1

  
    Copied!
1
2
3

# routes show <Topic>

查询指定 Topic d的路由:

$ ./bin/emqx_ctl routes show t/+/x
t/+/x -> emqx2@127.0.0.1,emqx@127.0.0.1

  
    Copied!
1
2

# subscriptions 命令

subscriptions 命令查询消息服务器的订阅 (Subscription) 表。

命令 描述
subscriptions list 列出所有订阅
subscriptions show <ClientId> 查询指定 ClientId 客户端的订阅
subscriptions add <ClientId> <Topic> <QoS> 手动添加静态订阅
subscriptions del <ClientId> <Topic> 手动删除静态订阅

# subscriptions list

列出所有订阅:

$ ./bin/emqx_ctl subscriptions list
mosqsub/91042-airlee.lo -> t/y:1
mosqsub/90475-airlee.lo -> t/+/x:2

  
    Copied!
1
2
3

# subscriptions show <ClientId>

查询某个 Client 的订阅:

$ ./bin/emqx_ctl subscriptions show 'mosqsub/90475-airlee.lo'
mosqsub/90475-airlee.lo -> t/+/x:2

  
    Copied!
1
2

# subscriptions add <ClientId> <Topic> <QoS>

手动添加订阅关系:

$ ./bin/emqx_ctl subscriptions add 'mosqsub/90475-airlee.lo' '/world' 1
ok

  
    Copied!
1
2

# subscriptions del <ClientId> <Topic>

手动删除订阅关系:

$ ./bin/emqx_ctl subscriptions del 'mosqsub/90475-airlee.lo' '/world'
ok

  
    Copied!
1
2

# plugins 命令

plugins 命令用于加载、卸载、查询插件应用。EMQX 通过插件扩展认证、定制功能，插件配置位于 etc/plugins/ 目录下。

命令 描述
plugins list 列出全部插件 (Plugin)
plugins load <Plugin> 加载插件 (Plugin)
plugins unload <Plugin> 卸载插件 (Plugin)
plugins reload <Plugin> 重载插件 (Plugin)

当配置文件发生更改，如果需要配置立即生效，你可以执行 emqx_ctl reload <Plugin\> 命令，即使插件在配置修改时并未处于运行状态，你也应当使用此命令而不是emqx_ctl load <Plugin>，因为 `emqx_ctl load <Plugin> 不会编译新的配置文件。

# plugins list

列出全部插件:

$ ./bin/emqx_ctl plugins list
...
Plugin(emqx_auth_http, description=EMQX Authentication/ACL with HTTP API, active=false)
Plugin(emqx_auth_jwt, description=EMQX Authentication with JWT, active=false)
Plugin(emqx_auth_ldap, description=EMQX Authentication/ACL with LDAP, active=false)
...

  
    Copied!
1
2
3
4
5
6

插件属性:

Name 描述
version 插件版本
description 插件描述
active 是否已加载

# plugins load <Plugin>

加载插件:

$ ./bin/emqx_ctl plugins load emqx_lua_hook
Plugin emqx_lua_hook loaded successfully.

  
    Copied!
1
2

# plugins unload <Plugin>

卸载插件:

$ ./bin/emqx_ctl plugins unload emqx_lua_hook
Plugin emqx_lua_hook unloaded successfully.

  
    Copied!
1
2

# plugins reload <Plugin>

重载插件:

$ ./bin/emqx_ctl plugins reload emqx_lua_hook
Plugin emqx_lua_hook reloaded successfully.

  
    Copied!
1
2

# modules 命令

自 v4.1 之后，引入了 modules 命令用于在运行时管理 EMQX 内置的模块。

命令 描述
modules list 列出全部内置模块 (Module)
modules start <Module> 启动内置模块 (Module)
modules stop <Module> 停止内置模块 (Module)

# modules list

列出全部内置模块:

$ ./bin/emqx_ctl modules list
Module(emqx_mod_delayed, description=EMQX Delayed Publish Module, active=false)
Module(emqx_mod_topic_metrics, description=EMQX Topic Metrics Module, active=false)
Module(emqx_mod_subscription, description=EMQX Subscription Module, active=false)
Module(emqx_mod_acl_internal, description=EMQX Internal ACL Module, active=true)
Module(emqx_mod_rewrite, description=EMQX Topic Rewrite Module, active=false)
Module(emqx_mod_presence, description=EMQX Presence Module, active=true)

  
    Copied!
1
2
3
4
5
6
7

# modules start

启动内置模块:

$ ./bin/emqx_ctl modules start emqx_mod_delayed
Module emqx_mod_delayed started successfully.

  
    Copied!
1
2

# modules stop

停止内置模块:

$ ./bin/emqx_ctl modules stop emqx_mod_delayed
Module emqx_mod_delayed stopped successfully.

  
    Copied!
1
2

# vm 命令

vm 命令用于查询 Erlang 虚拟机负载、内存、进程、IO 信息。

命令 描述
vm 等同于 vm all
vm all 查询 VM 全部信息
vm load 查询 VM 负载
vm memory 查询 VM 内存
vm process 查询 VM Erlang 进程数量
vm io 查询 VM io 最大文件句柄
vm ports 查询 VM 的端口

# vm all

查询 VM 全部信息，包括负载、内存、Erlang 进程数量等:

$ ./bin/emqx_ctl vm all
cpu/load1               : 4.22
cpu/load5               : 3.29
cpu/load15              : 3.16
memory/total            : 99995208
memory/processes        : 38998248
memory/processes_used   : 38938520
memory/system           : 60996960
memory/atom             : 1189073
memory/atom_used        : 1173808
memory/binary           : 100336
memory/code             : 25439961
memory/ets              : 7161128
process/limit           : 2097152
process/count           : 315
io/max_fds              : 10240
io/active_fds           : 0
ports/count             : 18
ports/limit             : 1048576

  
    Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# vm load

查询 VM 负载:

$ ./bin/emqx_ctl vm load
cpu/load1               : 2.21
cpu/load5               : 2.60
cpu/load15              : 2.36

  
    Copied!
1
2
3
4

# vm memory

查询 VM 内存:

$ ./bin/emqx_ctl vm memory
memory/total            : 23967736
memory/processes        : 3594216
memory/processes_used   : 3593112
memory/system           : 20373520
memory/atom             : 512601
memory/atom_used        : 491955
memory/binary           : 51432
memory/code             : 13401565
memory/ets              : 1082848

  
    Copied!
1
2
3
4
5
6
7
8
9
10

# vm process

查询 Erlang 进程数量及其限制:

$ ./bin/emqx_ctl vm process
process/limit           : 2097152
process/count           : 314

  
    Copied!
1
2
3

# vm io

查询文件描述符数量及其限制:

$ ./bin/emqx_ctl vm io
io/max_fds              : 10240
io/active_fds           : 0

  
    Copied!
1
2
3

# vm ports

查询端口占用数量及其限制:

$ ./bin/emqx_ctl vm ports
ports/count           : 18
ports/limit           : 1048576

  
    Copied!
1
2
3

# mnesia 命令

查询 mnesia 数据库系统状态。

# log 命令

log 命令用于设置日志等级。访问 Documentation of logger (opens new window) 以获取详细信息

命令 描述
log set-level <Level> 设置主日志等级和所有 Handlers 日志等级
log primary-level 查看主日志等级
log primary-lelvel <Level> 设置主日志等级
log handlers list 查看当前安装的所有 Handlers
log handlers start <HandlerId> 启动某个已停止的 Handler
log handlers stop <HandlerId> 停止某个 Handler
log handlers set-level <HandlerId> <Level> 设置指定 Handler 的日志等级

日志的等级由低到高分别为：debug | info | notice | warning | error | critical | alert | emergency，日志等级越低，系统输出的日志数量越多，消耗的系统资源越大。为提高系统运行性能，默认的主日志等级是 error。

# log set-level <Level>

设置主日志等级和所有 Handlers 日志等级:

$ ./bin/emqx_ctl log set-level debug
debug

  
    Copied!
1
2

# log primary-level

查看主日志等级:

$ ./bin/emqx_ctl log primary-level
debug

  
    Copied!
1
2

# log primary-level <Level>

设置主日志等级:

$ ./bin/emqx_ctl log primary-level info
info

  
    Copied!
1
2

# log handlers list

查看当前安装的所有 Handlers:

$ ./bin/emqx_ctl log handlers list
LogHandler(id=ssl_handler, level=debug, destination=console, status=started)
LogHandler(id=file, level=warning, destination=log/emqx.log, status=started)
LogHandler(id=default, level=warning, destination=console, status=started)

  
    Copied!
1
2
3
4

# log handlers start <HandlerId>

启动 log handler 'default':

$ ./bin/emqx_ctl log handlers start default
log handler default started

  
    Copied!
1
2

# log handlers stop <HandlerId>

停止 log handler 'default':

$ ./bin/emqx_ctl log handlers stop default
log handler default stopped

  
    Copied!
1
2

# log handlers set-level <HandlerId> <Level>

设置指定 Handler 的日志等级:

$ ./bin/emqx_ctl log handlers set-level emqx_logger_handler error
error

  
    Copied!
1
2

# trace 命令

trace 命令用于追踪某个 Client 或 Topic，打印日志信息到文件，详情请查看 日志与追踪。

命令 描述
trace list 列出所有开启的追踪
trace start client <ClientId> <File> [<Level>] 开启 Client 追踪，存储指定等级的日志到文件
trace stop client <ClientId> 关闭 Client 追踪
trace start topic <Topic> <File> [<Level>] 开启 Topic 追踪，存储指定等级的日志到文件
trace stop topic <Topic> 关闭 Topic 追踪

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

开启 Client 追踪:

$ ./bin/emqx_ctl log primary-level debug
debug

$ ./bin/emqx_ctl trace start client clientid log/clientid_trace.log
trace clientid clientid successfully

$ ./bin/emqx_ctl trace start client clientid2 log/clientid2_trace.log error
trace clientid clientid2 successfully

  
    Copied!
1
2
3
4
5
6
7
8

# trace stop client <ClientId>

关闭 Client 追踪:

$ ./bin/emqx_ctl trace stop client clientid
stop tracing clientid clientid successfully

  
    Copied!
1
2

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

开启 Topic 追踪:

$ ./bin/emqx_ctl log primary-level debug
debug

$ ./bin/emqx_ctl trace start topic topic log/topic_trace.log
trace topic topic successfully

$ ./bin/emqx_ctl trace start topic topic2 log/topic2_trace.log error
trace topic topic2 successfully

  
    Copied!
1
2
3
4
5
6
7
8

# trace stop topic <Topic>

关闭 Topic 追踪:

$ ./bin/emqx_ctl trace topic topic off
stop tracing topic topic successfully

  
    Copied!
1
2

# trace list

列出所有开启的追踪:

$ ./bin/emqx_ctl trace list
Trace (clientid=clientid2, level=error, destination="log/clientid2_trace.log")
Trace (topic=topic2, level=error, destination="log/topic2_trace.log")

  
    Copied!
1
2
3

# listeners

listeners 命令用于查询开启的 TCP 服务监听器。

命令 描述
listeners # List listeners
listeners stop <Identifier> # Stop a listener
listeners stop <Proto> <Port> # Stop a listener
listeners restart <Identifier> # Restart a listener

# listeners list

查询开启的 TCP 服务监听器:

$ ./bin/emqx_ctl listeners
mqtt:ssl:external
  listen_on       : 0.0.0.0:8883
  acceptors       : 16
  max_conns       : 102400
  current_conn    : 0
  shutdown_count  : []
mqtt:tcp:external
  listen_on       : 0.0.0.0:1883
  acceptors       : 8
  max_conns       : 1024000
  current_conn    : 0
  shutdown_count  : []
mqtt:tcp:internal
  listen_on       : 127.0.0.1:11883
  acceptors       : 4
  max_conns       : 1024000
  current_conn    : 0
  shutdown_count  : []
http:dashboard
  listen_on       : 0.0.0.0:18083
  acceptors       : 4
  max_conns       : 512
  current_conn    : 0
  shutdown_count  : []
http:management
  listen_on       : 0.0.0.0:8081
  acceptors       : 2
  max_conns       : 512
  current_conn    : 0
  shutdown_count  : []
mqtt:ws:external
  listen_on       : 0.0.0.0:8083
  acceptors       : 4
  max_conns       : 102400
  current_conn    : 0
  shutdown_count  : []
mqtt:wss:external
  listen_on       : 0.0.0.0:8084
  acceptors       : 4
  max_conns       : 16
  current_conn    : 0
  shutdown_count  : []

  
    Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

listener 参数说明:

Name 描述
acceptors TCP Acceptor 池
max_conns 最大允许连接数
current_conns 当前连接数
shutdown_count 连接关闭原因统计

# listeners stop

停止监听端口:

$ ./bin/emqx_ctl listeners stop mqtt:tcp:external
Stop mqtt:tcp:external listener on 0.0.0.0:1883 successfully.

  
    Copied!
1
2

# listeners restart

重启监听器:

$ ./bin/emqx_ctl listeners restart http:dashboard
Stop http:dashboard listener on 0.0.0.0:18083 successfully.
Start http:dashboard listener on 0.0.0.0:18083 successfully.


  
    Copied!
1
2
3
4

# recon 命令

EMQX 的 recon 命令基于 Erlang Recon 库实现，用于帮助 DevOps 人员诊断生产节点中的问题，普通用户无需关心。使用 recon 命令会耗费一定的性能，请谨慎使用。

命令 描述
recon memory recon_alloc:memory/2 (opens new window)
recon allocated recon_alloc:memory (allocated_types, current/max) (opens new window)
recon bin_leak recon:bin_leak (100) (opens new window)
recon node_stats recon:node_stats_print(10, 1000) (opens new window)
recon remote_load Mod recon:remote_load (Mod) (opens new window)
recon proc_count Attr N recon:proc_count(Attr, N) (opens new window)

访问 Documentation for recon (opens new window) 以获取详细信息。

# retainer 命令

命令 描述
retainer info 显示保留消息的数量
retainer topics 显示当前存储的保留消息的所有主题
retainer clean 清除所有保留的消息
retainer clean <Topic> 清除指定的主题下的保留的消息

# retainer info

显示保留消息的数量:

$ ./bin/emqx_ctl retainer info
retained/total: 3

  
    Copied!
1
2

# retainer topics

显示当前存储的保留消息的所有主题:

$ ./bin/emqx_ctl retainer topics
$SYS/brokers/emqx@127.0.0.1/version
$SYS/brokers/emqx@127.0.0.1/sysdescr
$SYS/brokers

  
    Copied!
1
2
3
4

# retainer clean

清除所有保留的消息:

$ ./bin/emqx_ctl retainer clean
Cleaned 3 retained messages

  
    Copied!
1
2

# retainer clean <Topic>

清除指定的主题下的保留的消息:

$ ./bin/emqx_ctl retainer clean topic
Cleaned 1 retained messages

  
    Copied!
1
2

# admins 命令

用于创建、删除管理员账号，重置管理员密码。

命令 描述
admins add <Username> <Password> <Tags> 创建 admin 账号
admins passwd <Username> <Password> 重置 admin 密码
admins del <Username> 删除 admin 账号

# admins add <Username> <Password> <Tags>

创建 admin 账户:

$ ./bin/emqx_ctl admins add root public test
ok

  
    Copied!
1
2

# admins passwd <Username> <Password>

重置 admin 账户密码:

$ ./bin/emqx_ctl admins passwd root private
ok

  
    Copied!
1
2

# admins del <Username>

删除 admin 账户:

$ ./bin/emqx_ctl admins del root
ok

  
    Copied!
1
2

# 规则引擎(rule engine) 命令

# rules 命令

命令 描述
rules list List all rules
rules show <RuleId> Show a rule
rules create <sql> <actions> [-d [<descr>]] Create a rule
rules delete <RuleId> Delete a rule

# rules create

创建一个新的规则。参数:

  • <sql>: 规则 SQL
  • <actions>: JSON 格式的动作列表
  • -d <descr>: 可选，规则描述信息

使用举例:

## 创建一个测试规则，简单打印所有发送到 't/a' 主题的消息内容
$ ./bin/emqx_ctl rules create \
    'select * from "t/a"' \
    '[{"name":"inspect", "params": {"a": 1}}]' \
    -d 'Rule for debug'

Rule rule:9a6a725d created

  
    Copied!
1
2
3
4
5
6
7

上例创建了一个 ID 为 rule:9a6a725d 的规则，动作列表里只有一个动作：动作名为 inspect，动作的参数是 {"a": 1}。

# rules list

列出当前所有的规则:

$ ./bin/emqx_ctl rules list

rule(id='rule:9a6a725d', for='['t/a']', rawsql='select * from "t/a"', actions=[{"metrics":...,"name":"inspect","params":...}], metrics=..., enabled='true', description='Rule for debug')

  
    Copied!
1
2
3

# rules show

查询规则:

## 查询 RuleID 为 'rule:9a6a725d' 的规则
$ ./bin/emqx_ctl rules show 'rule:9a6a725d'

rule(id='rule:9a6a725d', for='['t/a']', rawsql='select * from "t/a"', actions=[{"metrics":...,"name":"inspect","params":...}], metrics=..., enabled='true', description='Rule for debug')

  
    Copied!
1
2
3
4

# rules delete

删除规则:

## 删除 RuleID 为 'rule:9a6a725d' 的规则
$ ./bin/emqx_ctl rules delete 'rule:9a6a725d'

ok

  
    Copied!
1
2
3
4

# rule-actions 命令

命令 描述
rule-actions list List actions
rule-actions show <ActionId> Show a rule action

提示

动作可以由 EMQX 内置(称为系统内置动作)，或者由 EMQX 插件编写，但不能通过 CLI/API 添加或删除。

# rule-actions show

查询动作:

    ## 查询名为 'inspect' 的动作
$ ./bin/emqx_ctl rule-actions show 'inspect'

action(name='inspect', app='emqx_rule_engine', types=[], title ='Inspect (debug)', description='Inspect the details of action params for debug purpose')

  
    Copied!
1
2
3
4

# rule-actions list

列出符合条件的动作:

## 列出当前所有的动作
$ ./bin/emqx_ctl rule-actions list

action(name='data_to_rabbit', app='emqx_bridge_rabbit', types=[bridge_rabbit], title ='Data bridge to RabbitMQ', description='Store Data to Kafka')
action(name='data_to_timescaledb', app='emqx_backend_pgsql', types=[timescaledb], title ='Data to TimescaleDB', description='Store data to TimescaleDB')
...

  
    Copied!
1
2
3
4
5
6

# resources 命令

命令 描述
resources create <type> [-c [<config>]] [-d [<descr>]] Create a resource
resources list [-t <ResourceType>] List resources
resources show <ResourceId> Show a resource
resources delete <ResourceId> Delete a resource

# resources create

创建一个新的资源，参数:

  • type: 资源类型
  • -c config: JSON 格式的配置
  • -d descr: 可选，资源的描述
$ ./bin/emqx_ctl resources create 'web_hook' -c '{"url": "http://host-name/chats"}' -d 'forward msgs to host-name/chats'

Resource resource:a7a38187 created

  
    Copied!
1
2
3

# resources list

列出当前所有的资源:

$ ./bin/emqx_ctl resources list

resource(id='resource:a7a38187', type='web_hook', config=#{<<"url">> => <<"http://host-name/chats">>}, status=#{is_alive => false}, description='forward msgs to host-name/chats')

  
    Copied!
1
2
3

列出当前某个类型的资源:

$ ./bin/emqx_ctl resources list --type='web_hook'

resource(id='resource:a7a38187', type='web_hook', config=#{<<"url">> => <<"http://host-name/chats">>}, status=#{is_alive => false}, description='forward msgs to host-name/chats')

  
    Copied!
1
2
3

# resources show

查询资源:

$ ./bin/emqx_ctl resources show 'resource:a7a38187'

resource(id='resource:a7a38187', type='web_hook', config=#{<<"url">> => <<"http://host-name/chats">>}, status=#{is_alive => false}, description='forward msgs to host-name/chats')

  
    Copied!
1
2
3

# resources delete

删除资源:

$ ./bin/emqx_ctl resources delete 'resource:a7a38187'

ok

  
    Copied!
1
2
3

# resource-types 命令

命令 描述
resource-types list List all resource-types
resource-types show <Type> Show a resource-type

提示

资源类型可以由 EMQX 内置(称为系统内置资源类型)，或者由 EMQX 插件编写，但不能通过 CLI/API 添加或删除。

# resource-types list

列出当前所有的资源类型:

./bin/emqx_ctl resource-types list

resource_type(name='backend_mongo_rs', provider='emqx_backend_mongo', title ='MongoDB Replica Set Mode', description='MongoDB Replica Set Mode')
resource_type(name='backend_cassa', provider='emqx_backend_cassa', title ='Cassandra', description='Cassandra Database')
...

  
    Copied!
1
2
3
4
5

# resource-types show

查询资源类型:

$ ./bin/emqx_ctl resource-types show backend_mysql

resource_type(name='backend_mysql', provider='emqx_backend_mysql', title ='MySQL', description='MySQL Database')

  
    Copied!
1
2
3

# EMQX 内置数据库 Auth 与 ACL 命令

此命令只有在开启 emqx_auth_mnesia 插件后生效

# clientid 命令

命令 描述
clientid list List clientid auth rules
clientid add <ClientID> <Password> Add clientid auth rule
clientid update <ClientID> <Password> Update clientid auth rule
clientid del <ClientID> <Password> Delete clientid auth rule

# clientid list

列出所有的 clientid 验证规则

./bin/emqx_ctl clientid list
emqx

  
    Copied!
1
2

# clientid add <ClientID> <Password>

增加 clientid 验证规则

./bin/emqx_ctl clientid add emqx public
ok

  
    Copied!
1
2

# clientid update <ClientID> <Password>

更新 ClientID 验证的密码

./bin/emqx_ctl clientid update emqx new_password
ok

  
    Copied!
1
2

# clientid del <ClientID> <Password>

删除 clientid 验证规则码

./bin/emqx_ctl clientid del emqx new_password
ok

  
    Copied!
1
2

# user 命令

命令 描述
user list List username auth rules
user add <Username> <Password> Add username auth rule
user update <Username> <Password> Update username auth rule
user del <Username> <Password> Delete username auth rule

# user list

列出所有的 username 验证规则

./bin/emqx_ctl user list
emqx

  
    Copied!
1
2

# user add <Username> <Password>

增加 username 验证规则

./bin/emqx_ctl user add emqx public
ok

  
    Copied!
1
2

# user update <Username> <Password>

更新 ClientID 验证的密码

./bin/emqx_ctl user update emqx new_password
ok

  
    Copied!
1
2

# user del <Username> <Password>

删除 username 验证规则码

./bin/emqx_ctl user del emqx new_password
ok

  
    Copied!
1
2

# acl 命令

命令 描述
acl list clientid List clientid acls
acl list username List username acls
acl list _all List $all acls
acl show clientid <Clientid> Lookup clientid acl detail
acl show username <Username> Lookup username acl detail
acl aad clientid <Clientid> <Topic> <Action> <Access> Add clientid acl
acl add Username <Username> <Topic> <Action> <Access> Add username acl
acl add _all <Topic> <Action> <Access> Add $all acl
acl del clientid <Clientid> <Topic> Delete clientid acl
acl del username <Username> <Topic> Delete username acl
acl del _all \<Topic> Delete $all acl

# acl list

  • acl list clientid

    列出 clientid 的 ACL 规则

    ./bin/emqx_ctl acl list clientid
Acl(clientid = <<"emqx_clientid">> topic = <<"Topic/A">> action = pub access = allow)

      
    Copied!
    1
    2

  • acl list username

    列出 username 的 ACL 规则

    ./bin/emqx_ctl acl list username
Acl(username = <<"emqx_username">> topic = <<"Topic/B">> action = sub access = deny)

      
    Copied!
    1
    2

  • acl list _all

    列出 $all 的 ACL 规则

    ./bin/emqx_ctl acl list _all
Acl($all topic = <<"Topic/C">> action = pubsub access = allow)

      
    Copied!
    1
    2

# acl show

  • acl show clientid <Clientid>

    展示某一的 clientid ACL 规则

    ./bin/emqx_ctl acl show clientid emqx_clientid
Acl(clientid = <<"emqx_clientid">> topic = <<"Topic/A">> action = pub access = allow)

      
    Copied!
    1
    2

  • acl show username <Username>

    展示某一的 username ACL 规则

    ./bin/emqx_ctl acl show username emqx_username
Acl(username = <<"emqx_username">> topic = <<"Topic/B">> action = sub access = deny)

      
    Copied!
    1
    2

# acl add

  • acl aad clientid <Clientid> <Topic> <Action> <Access>

    增加一条 clientid 的 ACL 规则

    ./bin/emqx_ctl acl add clientid emqx_clientid Topic/A pub allow
ok

      
    Copied!
    1
    2

  • acl aad username <Username> <Topic> <Action> <Access>

    增加一条 username 的 ACL 规则

    ./bin/emqx_ctl acl add username emqx_username Topic/B sub deny
ok

      
    Copied!
    1
    2

  • acl aad _all <Topic> <Action> <Access>

    增加一条 $all 的 ACL 规则

    ./bin/emqx_ctl acl add _all Topic/C pubsub allow
ok

      
    Copied!
    1
    2

# acl del

  • acl del clientid <Clientid> <Topic>

    删除一条 clientid 的 ACL 规则

    ./bin/emqx_ctl acl del clientid emqx_clientid Topic/A
ok

      
    Copied!
    1
    2

  • acl del username <Username> <Topic>

    删除一条 username 的 ACL 规则

    ./bin/emqx_ctl acl del clientid emqx_username Topic/B
ok

      
    Copied!
    1
    2

  • acl del _all <Topic>

    删除一条 $all 的 ACL 规则

    ./bin/emqx_ctl acl del _all Topic/C
ok

      
    Copied!
    1
    2

# pem_cache 命令

pem_cache 命令用于清理所有 PEM 证书的缓存。例如，在替换了 SSL 监听器的证书 文件后，你可以使用该命令让新的证书文件生效，而不是重启 EMQX 的 SSL 监听器。

命令 描述
pem_cache clean 清理所有节点的 x509 的证书缓存
pem_cache clean node <Node> 清理指定节点的 x509 的证书缓存

注： 更新证书并不会影响当前已建立的 TLS 连接。

提示

该命令在 v4.3.13 版本中引入。在这之前都版本都不支持该命令

← 版本热升级 →

本页导航