Commands¶
The ‘./bin/emqttd_ctl’ command line could be used to query and administrate the EMQ broker.
Warning
Cannot work on Windows
status¶
Show running status of the broker:
$ ./bin/emqttd_ctl status
Node 'emqttd@127.0.0.1' is started
emqttd 2.0 is running
broker¶
Query basic information, statistics and metrics of the broker.
| broker | Show version, description, uptime of the broker |
| broker pubsub | Show status of the core pubsub process |
| broker stats | Show statistics of client, session, topic, subscription and route of the broker |
| broker metrics | Show metrics of MQTT bytes, packets, messages sent/received. |
Query version, description and uptime of the broker:
$ ./bin/emqttd_ctl broker
sysdescr : Erlang MQTT Broker
version : 0.15.0
uptime : 1 hours, 25 minutes, 24 seconds
datetime : 2016-01-16 13:17:32
broker stats¶
Query statistics of MQTT Client, Session, Topic, Subscription and Route:
$ ./bin/emqttd_ctl broker stats
clients/count : 1
clients/max : 1
queues/count : 0
queues/max : 0
retained/count : 2
retained/max : 2
routes/count : 2
routes/reverse : 2
sessions/count : 0
sessions/max : 0
subscriptions/count : 1
subscriptions/max : 1
topics/count : 54
topics/max : 54
broker metrics¶
Query metrics of Bytes, MQTT Packets and Messages(sent/received):
$ ./bin/emqttd_ctl broker metrics
bytes/received : 297
bytes/sent : 40
messages/dropped : 348
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 : 2
messages/sent : 0
packets/connack : 5
packets/connect : 5
packets/disconnect : 0
packets/pingreq : 0
packets/pingresp : 0
packets/puback/received : 0
packets/puback/sent : 0
packets/pubcomp/received: 0
packets/pubcomp/sent : 0
packets/publish/received: 0
packets/publish/sent : 0
packets/pubrec/received : 0
packets/pubrec/sent : 0
packets/pubrel/received : 0
packets/pubrel/sent : 0
packets/received : 9
packets/sent : 9
packets/suback : 4
packets/subscribe : 4
packets/unsuback : 0
packets/unsubscribe : 0
cluster¶
Cluster two or more emqttd brokers.
| cluster join <Node> | Join the cluster |
| cluster leave | Leave the cluster |
| cluster remove <Node> | Remove a node from the cluster |
| cluster status | Query cluster status and nodes |
Suppose we create two emqttd nodes on localhost and cluster them:
| Folder | Node | MQTT Port |
| emqttd1 | emqttd1@127.0.0.1 | 1883 |
| emqttd2 | emqttd2@127.0.0.1 | 2883 |
Start emqttd1 node:
cd emqttd1 && ./bin/emqttd start
Start emqttd2 node:
cd emqttd2 && ./bin/emqttd start
Under emqttd2 folder:
$ ./bin/emqttd_ctl cluster join emqttd1@127.0.0.1
Join the cluster successfully.
Cluster status: [{running_nodes,['emqttd1@127.0.0.1','emqttd2@127.0.0.1']}]
Query cluster status:
$ ./bin/emqttd_ctl cluster status
Cluster status: [{running_nodes,['emqttd2@127.0.0.1','emqttd1@127.0.0.1']}]
Message Route between nodes:
# Subscribe topic 'x' on emqttd1 node
mosquitto_sub -t x -q 1 -p 1883
# Publish to topic 'x' on emqttd2 node
mosquitto_pub -t x -q 1 -p 2883 -m hello
emqttd2 leaves the cluster:
cd emqttd2 && ./bin/emqttd_ctl cluster leave
Or remove emqttd2 from the cluster on emqttd1 node:
cd emqttd1 && ./bin/emqttd_ctl cluster remove emqttd2@127.0.0.1
clients¶
Query MQTT clients connected to the broker:
| clients list | List all MQTT clients |
| clients show <ClientId> | Show a MQTT Client |
| clients kick <ClientId> | Kick out a MQTT client |
clients lists¶
Query All MQTT clients connected to the broker:
$ ./bin/emqttd_ctl clients list
Client(mosqsub/43832-airlee.lo, clean_sess=true, username=test, peername=127.0.0.1:64896, connected_at=1452929113)
Client(mosqsub/44011-airlee.lo, clean_sess=true, username=test, peername=127.0.0.1:64961, connected_at=1452929275)
...
Properties of the Client:
| clean_sess | Clean Session Flag |
| username | Username of the client |
| peername | Peername of the TCP connection |
| connected_at | The timestamp when client connected to the broker |
clients show <ClientId>¶
Show a specific MQTT Client:
./bin/emqttd_ctl clients show "mosqsub/43832-airlee.lo"
Client(mosqsub/43832-airlee.lo, clean_sess=true, username=test, peername=127.0.0.1:64896, connected_at=1452929113)
sessions¶
Query all MQTT sessions. The broker will create a session for each MQTT client. Persistent Session if clean_session flag is true, transient session otherwise.
| sessions list | List all Sessions |
| sessions list persistent | Query all persistent Sessions |
| sessions list transient | Query all transient Sessions |
| sessions show <ClientId> | Show a session |
sessions list¶
Query all sessions:
$ ./bin/emqttd_ctl sessions list
Session(clientid, clean_sess=false, max_inflight=100, inflight_queue=0, message_queue=0, message_dropped=0, awaiting_rel=0, awaiting_ack=0, awaiting_comp=0, created_at=1452935508)
Session(mosqsub/44101-airlee.lo, clean_sess=true, max_inflight=100, inflight_queue=0, message_queue=0, message_dropped=0, awaiting_rel=0, awaiting_ack=0, awaiting_comp=0, created_at=1452935401)
Properties of Session:
TODO:??
| clean_sess | clean sess flag. false: persistent, true: transient |
| max_inflight | Inflight window (Max number of messages delivering) |
| inflight_queue | Inflight Queue Size |
| message_queue | Message Queue Size |
| message_dropped | Number of Messages Dropped for queue is full |
| awaiting_rel | The number of QoS2 messages received and waiting for PUBREL |
| awaiting_ack | The number of QoS1/2 messages delivered and waiting for PUBACK |
| awaiting_comp | The number of QoS2 messages delivered and waiting for PUBCOMP |
| created_at | Timestamp when the session is created |
sessions list persistent¶
Query all persistent sessions:
$ ./bin/emqttd_ctl sessions list persistent
Session(clientid, clean_sess=false, max_inflight=100, inflight_queue=0, message_queue=0, message_dropped=0, awaiting_rel=0, awaiting_ack=0, awaiting_comp=0, created_at=1452935508)
sessions list transient¶
Query all transient sessions:
$ ./bin/emqttd_ctl sessions list transient
Session(mosqsub/44101-airlee.lo, clean_sess=true, max_inflight=100, inflight_queue=0, message_queue=0, message_dropped=0, awaiting_rel=0, awaiting_ack=0, awaiting_comp=0, created_at=1452935401)
sessions show <ClientId>¶
Show a session:
$ ./bin/emqttd_ctl sessions show clientid
Session(clientid, clean_sess=false, max_inflight=100, inflight_queue=0, message_queue=0, message_dropped=0, awaiting_rel=0, awaiting_ack=0, awaiting_comp=0, created_at=1452935508)
routes¶
Show routing table of the broker.
routes list¶
List all routes:
$ ./bin/emqttd_ctl routes list
t2/# -> emqttd2@127.0.0.1
t/+/x -> emqttd2@127.0.0.1,emqttd@127.0.0.1
routes show <Topic>¶
Show a route:
$ ./bin/emqttd_ctl routes show t/+/x
t/+/x -> emqttd2@127.0.0.1,emqttd@127.0.0.1
topics¶
Query topic table of the broker.
topics list¶
Query all the topics:
$ ./bin/emqttd_ctl topics list
$SYS/brokers/emqttd@127.0.0.1/metrics/packets/subscribe: static
$SYS/brokers/emqttd@127.0.0.1/stats/subscriptions/max: static
$SYS/brokers/emqttd2@127.0.0.1/stats/subscriptions/count: static
...
topics show <Topic>¶
Show a topic:
$ ./bin/emqttd_ctl topics show '$SYS/brokers'
$SYS/brokers: static
subscriptions¶
Query the subscription table of the broker:
| subscriptions list | List all subscriptions |
| subscriptions show <ClientId> | Show a subscription |
subscriptions list¶
Query all subscriptions:
$ ./bin/emqttd_ctl subscriptions list
mosqsub/91042-airlee.lo -> t/y:1
mosqsub/90475-airlee.lo -> t/+/x:2
subscriptions list static¶
List all static subscriptions:
$ ./bin/emqttd_ctl subscriptions list static
clientid -> new_topic:1
subscriptions show <ClientId>¶
Show the subscriptions of a MQTT client:
$ ./bin/emqttd_ctl subscriptions show clientid
clientid: [{<<"x">>,1},{<<"topic2">>,1},{<<"topic3">>,1}]
plugins¶
List, load or unload plugins of emqttd broker.
| plugins list | List all plugins |
| plugins load <Plugin> | Load Plugin |
| plugins unload <Plugin> | Unload (Plugin) |
plugins list¶
List all plugins:
$ ./bin/emqttd_ctl plugins list
Plugin(emq_auth_clientid, version=2.0, description=Authentication with ClientId/Password, active=false)
Plugin(emq_auth_http, version=2.0, description=Authentication/ACL with HTTP API, active=false)
Plugin(emq_auth_ldap, version=2.0, description=Authentication/ACL with LDAP, active=false)
Plugin(emq_auth_mongo, version=2.0, description=Authentication/ACL with MongoDB, active=false)
Plugin(emq_auth_mysql, version=2.0, description=Authentication/ACL with MySQL, active=false)
Plugin(emq_auth_pgsql, version=2.0, description=Authentication/ACL with PostgreSQL, active=false)
Plugin(emq_auth_redis, version=2.0, description=Authentication/ACL with Redis, active=false)
Plugin(emq_auth_username, version=2.0, description=Authentication with Username/Password, active=false)
Plugin(emq_coap, version=0.2, description=CoAP Gateway, active=false)
Plugin(emq_dashboard, version=2.0, description=Dashboard, active=true)
Plugin(emq_mod_rewrite, version=2.0, description=EMQ Rewrite Module, active=false)
Plugin(emq_plugin_template, version=2.0, description=EMQ Plugin Template, active=false)
Plugin(emq_recon, version=2.0, description=Recon Plugin, active=false)
Plugin(emq_reloader, version=3.0, description=Reloader Plugin, active=false)
Plugin(emq_sn, version=0.2, description=MQTT-SN Gateway, active=false)
Plugin(emq_stomp, version=2.0, description=Stomp Protocol Plugin, active=false)
Properties of a plugin:
| version | Plugin Version |
| description | Plugin Description |
| active | If the plugin is Loaded |
Load <Plugin>¶
Load a Plugin:
$ ./bin/emqttd_ctl plugins load emq_recon
Start apps: [recon,emq_recon]
Plugin emq_recon loaded successfully.
Unload <Plugin>¶
Unload a Plugin:
$ ./bin/emqttd_ctl plugins unload emq_recon
Plugin emq_recon unloaded successfully.
bridges¶
Bridge two or more EMQ brokers:
--------- ---------
Publisher --> | node1 | --Bridge Forward--> | node2 | --> Subscriber
--------- ---------
commands for bridge:
| bridges list | List all bridges |
| bridges options | Show bridge options |
| bridges start <Node> <Topic> | Create a bridge |
| bridges start <Node> <Topic> <Options> | Create a bridge with options |
| bridges stop <Node> <Topic> | Delete a bridge |
Suppose we create a bridge between emqttd1 and emqttd2 on localhost:
| Name | Node | MQTT Port |
| emqttd1 | emqttd1@127.0.0.1 | 1883 |
| emqttd2 | emqttd2@127.0.0.1 | 2883 |
The bridge will forward all the the ‘sensor/#’ messages from emqttd1 to emqttd2:
$ ./bin/emqttd_ctl bridges start emqttd2@127.0.0.1 sensor/#
bridge is started.
$ ./bin/emqttd_ctl bridges list
bridge: emqttd1@127.0.0.1--sensor/#-->emqttd2@127.0.0.1
The the ‘emqttd1–sensor/#–>emqttd2’ bridge:
#emqttd2 node
mosquitto_sub -t sensor/# -p 2883 -d
#emqttd1 node
mosquitto_pub -t sensor/1/temperature -m "37.5" -d
bridges options¶
Show bridge options:
$ ./bin/emqttd_ctl bridges options
Options:
qos = 0 | 1 | 2
prefix = string
suffix = string
queue = integer
Example:
qos=2,prefix=abc/,suffix=/yxz,queue=1000
bridges stop <Node> <Topic>¶
Delete the emqttd1–sensor/#–>emqttd2 bridge:
$ ./bin/emqttd_ctl bridges stop emqttd2@127.0.0.1 sensor/#
bridge is stopped.
vm¶
Query the load, cpu, memory, processes and IO information of the Erlang VM.
| vm all | Query all |
| vm load | Query VM Load |
| vm memory | Query Memory Usage |
| vm process | Query Number of Erlang Processes |
| vm io | Query Max Fds of VM |
vm memory¶
Query memory:
$ ./bin/emqttd_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
vm process¶
Query number of erlang processes:
$ ./bin/emqttd_ctl vm process
process/limit : 8192
process/count : 221
vm io¶
Query max, active file descriptors of IO:
$ ./bin/emqttd_ctl vm io
io/max_fds : 2560
io/active_fds : 1
trace¶
Trace MQTT packets, messages(sent/received) by ClientId or Topic.
| trace list | List all the traces |
| trace client <ClientId> <LogFile> | Trace a client |
| trace client <ClientId> off | Stop tracing the client |
| trace topic <Topic> <LogFile> | Trace a topic |
| trace topic <Topic> off | Stop tracing the topic |
trace client <ClientId> <LogFile>¶
Start to trace a client:
$ ./bin/emqttd_ctl trace client clientid log/clientid_trace.log
trace client clientid successfully.
trace client <ClientId> off¶
Stop tracing the client:
$ ./bin/emqttd_ctl trace client clientid off
stop tracing client clientid successfully.
trace topic <Topic> <LogFile>¶
Start to trace a topic:
$ ./bin/emqttd_ctl trace topic topic log/topic_trace.log
trace topic topic successfully.
trace topic <Topic> off¶
Stop tracing the topic:
$ ./bin/emqttd_ctl trace topic topic off
stop tracing topic topic successfully.
trace list¶
List all traces:
$ ./bin/emqttd_ctl trace list
trace client clientid -> log/clientid_trace.log
trace topic topic -> log/topic_trace.log
listeners¶
Show all the TCP listeners:
$ ./bin/emqttd_ctl listeners
listener on mqtt:ws:8083
acceptors : 4
max_clients : 64
current_clients : 0
shutdown_count : []
listener on mqtt:ssl:8883
acceptors : 4
max_clients : 512
current_clients : 0
shutdown_count : []
listener on mqtt:tcp:1883
acceptors : 8
max_clients : 1024
current_clients : 0
shutdown_count : []
listener on dashboard:http:18083
acceptors : 2
max_clients : 512
current_clients : 0
shutdown_count : []
listener parameters:
| acceptors | TCP Acceptor Pool | |
| max_clients | Max number of clients | |
| current_clients | Count of current clients | |
| shutdown_count | Statistics of client shutdown reason | ||
mnesia¶
Show system_info of mnesia database.
admins¶
The ‘admins’ CLI is used to add/del admin account, which is registered by the dashboard plugin.
| admins add <Username> <Password> | Add admin account |
| admins passwd <Username> <Password> | Reset admin password |
| admins del <Username> | Delete admin account |