# Command line interface

EMQ X Broker provides the management command line of ./bin/emqx_ctl for users to manage, configure and query EMQ X Broker.

# status command

Query the running status of EMQ X Broker:

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

# mgmt command

The mgmt command can query the application.

CommandDescription
mgmt listList application
mgmt insert <AppId> <Name>Add an application that can access to the HTTP API
mgmt update <AppId> <status>Update applications that can access to the HTTP API
mgmt lookup <AppId>Get application details that can access to the HTTP API
mgmt delete <AppId>Remove applications that can access to the HTTP API

# mgmt list

List application

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

# mgmt insert

Add the HTTP API application:

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

# mgmt update

Update the HTTP API application:

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

# mgmt lookup

Get application details of the HTTP API:

$ ./bin/emqx_ctl mgmt lookup dbcb6e023370b
app_id: dbcb6e023370b
secret: MjgzMzQ5MjYyMTY3ODk4MjA5NzMwODExODMxMDM1NDk0NDA
name: world
desc: Application user
status: stop
expired: undefined
1
2
3
4
5
6
7

# mgmt delete

Remove the HTTP API application:

$ ./bin/emqx_ctl mgmt delete dbcb6e023370b
ok
1
2

# broker command

The broker command queries basic server information, startup time, statistics data and performance data.

CommandDescription
brokerQuery EMQ X Broker description, version, start time
broker statsStatistics of Connection, Session, Topic, Subscription, Route
broker metricsQuery MQTT Packet and Message Statistics

Query basic information of EMQ X Broker, including version, startup time, etc .:

$ ./bin/emqx_ctl broker
sysdescr  : EMQ X Broker
version   : 4.0.0
uptime    : 4 minutes, 52 seconds
datetime  : 2020-02-21 09:39:58
1
2
3
4
5

# broker stats

Query statistics of connections, topics, subscriptions, routes between server and client :

$ ./bin/emqx_ctl broker stats
actions.count                 : 5
actions.max                   : 5
channels.count                : 0
channels.max                  : 0
connections.count             : 0
connections.max               : 0
resources.count               : 0
resources.max                 : 0
retained.count                : 3
retained.max                  : 3
routes.count                  : 0
routes.max                    : 0
rules.count                   : 0
rules.max                     : 0
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
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

# broker metrics

Query server traffic (Bytes), MQTT Packets, messages sending and receiving statistics:

$ ./bin/emqx_ctl broker metrics
actions.success               : 0
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
rules.matched                 : 0
session.created               : 0
session.discarded             : 0
session.resumed               : 0
session.takeovered            : 0
session.terminated            : 0
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
80
81

# cluster command

The cluster command is used to manage a cluster of multiple EMQ X Broker nodes (processes):

CommandDescription
cluster join <Node>Join the cluster
cluster leaveLeave the cluster
cluster force-leave <Node>Remove nodes from the cluster
cluster statusQuery cluster status

Example:

To demonstrate the cluster command in a better way, we first start two nodes on the local machine and create a cluster. To avoid port conflicts, we have adjusted the listening port of the emqx2 node. For example, the MQTT/TCP listening port was changed from the default 1883 to 2883. Please refer to Configuration Instructions and Configuration Items for details.

Start emqx1 :

$ cd emqx1 && ./bin/emqx start
1

Start emqx2 :

$ cd emqx2 && ./bin/emqx start
1

Use cluster join <Node> to combine two nodes into one cluster:

$ 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']}]
1
2
3
4

Query the cluster status in any node directory:

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

Cluster message routing test: The MQTT command line tool uses the emqtt (opens new window) client developed by the EMQ X team.

# emqx1 node (port 1883) subscribed topic x
$ ./bin/emqtt sub -t x -q 1 -p 1883
Client emqtt-a7de8fffbe2fbeb2fadb sent CONNECT
Client emqtt-a7de8fffbe2fbeb2fadb subscribed to x

# Published message to emqx2 node (port 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

# received a message by emqx1 node (port 1883) 
$ ./bin/emqtt sub -t x -q 1 -p 1883
hello
1
2
3
4
5
6
7
8
9
10
11
12
13
14

emqx2 nodes leave the cluster:

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

emqx2 node is forced to leave the cluster, and you need to perform operations on nodes other than the target node under the cluster:

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

It is Noted that EMQ X Broker does not support joining a node that is already in a cluster to another cluster. That is because this will cause the data of the two clusters to be inconsistent. However, it supports nodes that have joined the cluster to join another cluster after leaving the cluster.

# acl command

Since v4.1 the command modules has been introduced and we reload the ACLs using the following command:

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

Prior to v4.1, still use:

$ ./bin/emqx_ctl acl reload
ok
1
2

# clients command

The clients command can query the connected MQTT clients.

CommandDescription
clients listList all client connections
clients show <ClientId>Query the client with the specified ClientId
clients kick <ClientId>Kick out the client with the specified ClientId, and the connection and session will be terminated together.

# clients list

List all client connections:

$ ./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)
    ...
1
2
3
4

Return the properties of the Client object:

NameDescription
usernameUsername
peernameClient IP and port
clean_startMQTT Clean Start
keepaliveMQTT KeepAlive
session_expiry_intervalSession expiration interval
subscriptionsCurrent subscriptions
inflightTotal number of QoS 1 and QoS 2 messages currently being issued
awaiting_relNumber of QoS2 messages waiting for the client to send PUBREL
delivered_msgsNumber of messages forwarded by EMQ X Broker to this client (including retransmissions)
enqueued_msgsCurrent length of message queue
dropped_msgsNumber of messages dropped after the message queue reached the maximum length
connectedWhether online
created_atSession creation timestamp
connected_atClient connection timestamp
disconnected_atClient disconnection timestamp (appears only if the disconnection also retains the session)

# clients show

Query the client with the specified 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)
1
2

# clients kick

Kick out the client with the specified ClientId:

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

# routes command

The routes command is used to query routing information.

In EMQ X Broker, route refers to the mapping of topics to nodes, which is used to route messages between multiple nodes.

CommandDescription
routes listList all routes
routes show <Topic>Query the route of the specified topic

# routes list

List all routes:

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

# routes show

Query the route with the specified topic:

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

# subscriptions command

The subscriptions command queries the subscription table of the message server.

CommandDescription
subscriptions listList all subscriptions
subscriptions show <ClientId>Query the subscription of the specified ClientId client
subscriptions add <ClientId> <Topic> <QoS>Add static subscriptions manually
subscriptions del <ClientId> <Topic>Delete static subscriptions manually

# subscriptions list

List all subscriptions:

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

# subscriptions show

Query certain client's subscription:

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

# subscriptions add

Add subscription relationship manually:

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

# subscriptions del

Delete subscription relationship manually:

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

# plugins command

The plugins command is used to load, unload, and query plugin applications. EMQ X Broker extends authentication and customization through plugins. The plugin configuration is located in the directory of etc/plugins/ .

CommandDescription
plugins listList all plugins
plugins load <Plugin>Load plugins
plugins unload <Plugin>Unload plugins
plugins reload <Plugin>Reload plugins

When the configuration file changesand it needs to take effect immediately, you can execute the emqx_ctl reload <Plugin \> command, even if the plugin is not running when the configuration is modified. You should use this command instead of emqx_ctl load <Plugin\> . Because emqx_ctl load <Plugin \> does not compile the new configuration file.

# plugins list

List all plugins:

$ ./bin/emqx_ctl plugins list
Plugin (emqx_auth_clientid, version=v4.0.0, description=EMQ X Authentication with ClientId/Password, active=false)
Plugin (emqx_auth_http, version=v4.0.0, description=EMQ X Authentication/ACL with HTTP API, active=false)
Plugin (emqx_auth_jwt, version=v4.0.0, description=EMQ X Authentication with JWT, active=false)
Plugin (emqx_auth_ldap, version=v4.0.0, description=EMQ X Authentication/ACL with LDAP, active=false)
Plugin (emqx_auth_mongo, version=v4.0.0, description=EMQ X Authentication/ACL with MongoDB, active=false)
Plugin (emqx_auth_mysql, version=v4.0.0, description=EMQ X Authentication/ACL with MySQL, active=false)
Plugin (emqx_auth_pgsql, version=v4.0.0, description=EMQ X Authentication/ACL with PostgreSQL, active=false)
Plugin (emqx_auth_redis, version=v4.0.0, description=EMQ X Authentication/ACL with Redis, active=false)
Plugin (emqx_auth_username, version=v4.0.0, description=EMQ X Authentication with Username and Password, active=false)
Plugin (emqx_bridge_mqtt, version=v4.0.0, description=EMQ X Bridge to MQTT Broker, active=false)
Plugin (emqx_coap, version=v4.0.0, description=EMQ X CoAP Gateway, active=false)
Plugin (emqx_dashboard, version=v4.0.0, description=EMQ X Web Dashboard, active=true)
Plugin (emqx_delayed_publish, version=v4.0.0, description=EMQ X Delayed Publish, active=false)
Plugin (emqx_lua_hook, version=v4.0.0, description=EMQ X Lua Hooks, active=false)
Plugin (emqx_lwm2m, version=v4.0.0, description=EMQ X LwM2M Gateway, active=false)
Plugin (emqx_management, version=v4.0.0, description=EMQ X Management API and CLI, active=true)
Plugin (emqx_plugin_template, version=v4.0.0, description=EMQ X Plugin Template, active=false)
Plugin (emqx_psk_file, version=v4.0.0, description=EMQX PSK Plugin from File, active=false)
Plugin (emqx_recon, version=v4.0.0, description=EMQ X Recon Plugin, active=true)
Plugin (emqx_reloader, version=v4.0.0, description=EMQ X Reloader Plugin, active=false)
Plugin (emqx_retainer, version=v4.0.0, description=EMQ X Retainer, active=true)
Plugin (emqx_rule_engine, version=v4.0.0, description=EMQ X Rule Engine, active=true)
Plugin (emqx_sn, version=v4.0.0, description=EMQ X MQTT SN Plugin, active=false)
Plugin (emqx_statsd, version=v4.0.0, description=Statsd for EMQ X, active=false)
Plugin (emqx_stomp, version=v4.0.0, description=EMQ X Stomp Protocol Plugin, active=false)
Plugin (emqx_web_hook, version=v4.0.0, description=EMQ X Webhook Plugin, active=false)
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

Plugin properties:

NameDescription
versionPlugin version
descriptionPlugin description
activeWhether loaded

# plugins load

Load plugin:

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

# plugins unload

Unload plugin:

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

# plugins reload

Reload plugin:

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

# modules command

Since v4.1 we have introduced the modules command to manage EMQ X's built-in modules at runtime.

CommandDescription
modules listList all modules
modules load <Module>Load a module
modules unload <Module>Unload a module
modules reload <Module>Reload a module

# modules list

Lists all built-in modules, including those that have not been started:

$ ./bin/emqx_ctl modules list
Module(emqx_mod_delayed, description=EMQ X Delayed Publish Module, active=false)
Module(emqx_mod_topic_metrics, description=EMQ X Topic Metrics Module, active=false)
Module(emqx_mod_subscription, description=EMQ X Subscription Module, active=false)
Module(emqx_mod_acl_internal, description=EMQ X Internal ACL Module, active=true)
Module(emqx_mod_rewrite, description=EMQ X Topic Rewrite Module, active=false)
Module(emqx_mod_presence, description=EMQ X Presence Module, active=true)
1
2
3
4
5
6
7

# modules load

Load a module:

$ ./bin/emqx_ctl modules load emqx_mod_delayed
Module emqx_mod_delayed loaded successfully.
1
2

# modules unload

Unload a module:

$ ./bin/emqx_ctl modules unload emqx_mod_delayed
Module emqx_mod_delayed unloaded successfully.
1
2

# modules reload

Reload a module:

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

# vm command

The vm command is used to query information of Erlang virtual machine load, memory, process, and IO.

CommandDescription
vmEquivalent to vm all
vm allQuery all VM information
vm loadQuery VM load
vm memoryQuery VM memory
vm processQuery the number of VM Erlang processes
vm ioQuery maximum file handle of VM io
vm portsQuery the port of a VM

# vm all

Query all VM information, including load, memory, number of Erlang processes, etc .:

$ ./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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# vm load

Query VM load:

$ ./bin/emqx_ctl vm load
cpu/load1               : 2.21
cpu/load5               : 2.60
cpu/load15              : 2.36
1
2
3
4

# vm memory

Query VM memory:

$ ./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
1
2
3
4
5
6
7
8
9
10

# vm process

Query the number of Erlang processes and their limits:

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

# vm io

Query the number of file descriptors and their limits:

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

# vm ports

Query the number of occupied ports and their limits:

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

# mnesia command

Query the mnesia database system status.

# log command

The log command is used to set the log level. Visit Documentation of logger (opens new window) for more information in detail.

CommandDescription
log set-level <Level>Set the primary log level and all Handlers log levels
log primary-levelCheck the primary log level
log primary-lelvel <Level>Set the primary log level
log handlers listView all Hanlders currently installed
log handlers set-level <HandlerId> <Level>Set the log level with the specified Hanlder

The levels of the logs from low to high are: debug | info | notice | warning | error | critical | alert | emergency. The lower the log level, the more logs the system outputs, and the more system resources it consumes. To improve system performance, the default primary log level is error.

# log set-level

Set the primary log level and all Handlers log levels

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

# log primary-level

View the primary log level:

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

# log primary-level

Set the primary log level:

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

# log handlers list

View all Hanlders currently installed:

$ ./bin/emqx_ctl log handlers list
LogHandler (id=emqx_logger_handler, level=debug, destination=unknown)
LogHandler (id=file, level=debug, destination=log/emqx.log)
LogHandler (id=default, level=debug, destination=console)
1
2
3
4

# log handlers set-level

Set the log level with the specified Hanlder:

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

# trace command

The trace command is used to trace a client or topic, and print log information to a file. For details, see Log and Trace.

CommandDescription
trace listList all started traces
trace start client <ClientId> <File> [<Level>]Start client trace and store logs of specified level to a file
trace stop client <ClientId>Stop Client trace
trace start topic <Topic> <File> [<Level>]Start Topic trace and store logs of specified level to a file
trace stop topic <Topic>Stop Topic trace

# trace start client[]

Start client trace:

$ ./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
1
2
3
4
5
6
7
8

# trace stop client

Stop client trace:

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

# trace start topic[]

Start Topic trace:

$ ./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
1
2
3
4
5
6
7
8

# trace stop topic

Stop Topic trace:

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

# trace list

List all started traces:

$ ./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")
1
2
3

# listeners

The listeners command is used to query the active TCP service listeners.

CommandDescription
listenersQuery active TCP Service Listeners
listeners stop <Proto> <Port>Stop listener port, support mqtt: ssl,mqtt: tcp, http: dashboard,http: management, mqtt: ws,mqtt: wss protocol

# listeners list

Query the active TCP service listeners

$ ./bin/emqx_ctl listeners
listener on mqtt:ssl:8883
    acceptors       : 16
    max_conns       : 102400
    current_conn    : 0
    shutdown_count  : []
listener on mqtt:tcp:0.0.0.0:1883
    acceptors       : 8
    max_conns       : 1024000
    current_conn    : 0
    shutdown_count  : []
listener on mqtt:tcp:127.0.0.1:11883
    acceptors       : 4
    max_conns       : 1024000
    current_conn    : 2
    shutdown_count  : []
listener on http:dashboard:18083
    acceptors       : 2
    max_conns       : 512
    current_conn    : 0
    shutdown_count  : []
listener on http:management:8081
    acceptors       : 2
    max_conns       : 512
    current_conn    : 0
    shutdown_count  : []
listener on mqtt:ws:8083
    acceptors       : 2
    max_conns       : 102400
    current_conn    : 0
    shutdown_count  : []
listener on mqtt:wss:8084
    acceptors       : 2
    max_conns       : 16
    current_conn    : 0
    shutdown_count  : []
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

listener parameter description:

NameDescription
acceptorsTCP Acceptor pool
max_connsMaximum allowed connections
current_connsCurrent connections
shutdown_countStatistics of connection shutdown reasons

# listeners stop

Stop listener port:

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

# recon command

The recon command of EMQ X Broker is based on the Erlang Recon library, which is used to help DevOps staff to diagnose problems in the production node, and ordinary users do not need to care. The recon command will consume some performance, so, please use it with caution.

CommandDescription
recon memoryrecon_alloc:memory/2 (opens new window)
recon allocatedrecon_alloc:memory (allocated_types, current/max) (opens new window)
recon bin_leakrecon:bin_leak (100) (opens new window)
recon node_statsrecon:node_stats_print(10, 1000) (opens new window)
recon remote_load Modrecon:remote_load (Mod) (opens new window)
recon proc_count Attr Nrecon:proc_count(Attr, N) (opens new window)

Visit Documentation for recon (opens new window) for more information.

# retainer command

CommandDescription
retainer infoShow the number of retained messages
retainer topicsDisplay all topics of currently stored retained messages
retainer cleanClean all retained messages
retainer clean <Topic>Clean retained messages with the specified topic

# retainer info

Show the number of retained messages:

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

# retainer topics

Show all topics of currently stored retained messages:

$ ./bin/emqx_ctl retainer topics
$SYS/brokers/emqx@127.0.0.1/version
$SYS/brokers/emqx@127.0.0.1/sysdescr
$SYS/brokers
1
2
3
4

# retainer clean

Clear all retained messages:

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

# retainer clean

Clear the retained messages with the specified topic:

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

# admins command

It is used to create and delete administrator's accounts and reset the administrator's password.

CommandDescription
admins add <Username> <Password> <Tags>Create admin account
admins passwd <Username> <Password>Reset admin password
admins del <Username>Delete admin account

# admins add

Create admin account:

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

# admins passwd

Reset admin password:

$ ./bin/emqx_ctl admins passwd root private
ok
1
2

# admins del

Delete admin account:

$ ./bin/emqx_ctl admins del root
ok
1
2

# Rule engine command

# rules command

CommandDescription
rules listList 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

Create a new rule with the following parameter:

  • <sql>: rule SQL
  • <actions>: Action list in JSON format
  • -d <descr>: Optional, rule description

Example

## Create a test rule to simply print the content of all messages sent to the 't / a' topic
$ ./bin/emqx_ctl rules create \
    'select * from "t/a"' \
    '[{"name":"inspect", "params": {"a": 1}}]' \
    -d 'Rule for debug'
    
Rule rule:9a6a725d created
1
2
3
4
5
6
7

The above example creates a rule with the ID rule:9a6a725d. There is only one action in the action list with the name inspect, and the action parameters are {" a ": 1}.

# rules list

List all current rules:

$ ./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')
1
2
3

# rules show

Query rules:

## Query rule with 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')
1
2
3
4

# rules delete

Delete rule:

## Delete rule with RuleID 'rule:9a6a725d'
$ ./bin/emqx_ctl rules delete 'rule:9a6a725d'
    
ok
1
2
3
4

# rule-actions command

CommandDescription
rule-actions listList actions
rule-actions show <ActionId>Show a rule action

TIP

Actions can be built-in by EMQ X Broker (called system built-in actions) or be written by EMQ X Broker plugins, but cannot be added or removed through the CLI/API.

# rule-actions show

Query action:

## Query action named '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')
1
2
3
4

# rule-actions list

List eligible actions:

## List all current actions
$ ./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')
...
1
2
3
4
5
6

# resources command

CommandDescription
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

Create a new resource with the following parameters:

  • type: resource type

  • -c config: Configuration in JSON format

  • -d descr: Optional, description of the resource

    $ ./bin/emqx_ctl resources create 'web_hook' -c '{"url": "http://host-name/chats"}' -d 'forward msgs to host-name/chats'

    Resource resource:a7a38187 created

# resources list

List all current resources:

$ ./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')
1
2
3

List resources of a certain type:

$ ./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')
1
2
3

# resources show

Query resource:

$ ./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')
1
2
3

# resources delete

Delete resource:

$ ./bin/emqx_ctl resources delete 'resource:a7a38187'
    
ok
1
2
3

# resource-types command

CommandDescription
resource-types listList all resource-types
resource-types show <Type>Show a resource-type

TIP

Resource type can be built-in by EMQ X Broker (called system built-in resource type) or be written by EMQ X Broker plugins, but cannot be added or removed through the CLI/API

# resource-types list

List all current resource types:

./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')
...
1
2
3
4
5

# resource-types show

Query resource type:

$ ./bin/emqx_ctl resource-types show backend_mysql
    
resource_type(name='backend_mysql', provider='emqx_backend_mysql', title ='MySQL', description='MySQL Database')
1
2
3

# Rule status and statistical indicators

image

  • Hits: number of rule hits (match succeed for rule SQL),
  • Hit Speed: Speed of rule hits (times/second)
  • Maximum hit speed: Peak value of hit speed (times/second)
  • 5 minute average speed: Average hit speed in 5 minutes (times/second)

# Action status and statistical indicators

image

  • Success: Number of successful actions
  • Failure: Number of failed actions

# Resource status and alerts

image

  • Available: Resources available
  • Unavailable: resources unavailable (e.g. database connection shutdown)