# 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.

brokerShow version, description, uptime of the broker
broker pubsubShow status of the core pubsub process
broker statsShow statistics of client, session, topic, subscription and route of the broker
broker metricsShow 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 leaveLeave the cluster
cluster remove <Node>Remove a node from the cluster
cluster statusQuery cluster status and nodes

Suppose we create two emqttd nodes on localhost and cluster them:

FolderNodeMQTT Port
emqttd1emqttd1@127.0.0.11883
emqttd2emqttd2@127.0.0.12883

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 listList 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_sessClean Session Flag
usernameUsername of the client
peernamePeername of the TCP connection
connected_atThe 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)

# clients kick <ClientId>

Kick out a MQTT Client:

./bin/emqttd_ctl clients kick "clientid"

# 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 listList all Sessions
sessions list persistentQuery all persistent Sessions
sessions list transientQuery 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:

clean_sessclean sess flag. false: persistent, true: transient
max_inflightInflight window (Max number of messages delivering)
inflight_queueInflight Queue Size
message_queueMessage Queue Size
message_droppedNumber of Messages Dropped for queue is full
awaiting_relThe number of QoS2 messages received and waiting for PUBREL
awaiting_ackThe number of QoS1/2 messages delivered and waiting for PUBACK
awaiting_compThe number of QoS2 messages delivered and waiting for PUBCOMP
created_atTimestamp 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 listList 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 listList 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:

versionPlugin Version
descriptionPlugin Description
activeIf 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 listList all bridges
bridges optionsShow 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:

NameNodeMQTT Port
emqttd1emqttd1@127.0.0.11883
emqttd2emqttd2@127.0.0.12883

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 allQuery all
vm loadQuery VM Load
vm memoryQuery Memory Usage
vm processQuery Number of Erlang Processes
vm ioQuery Max Fds of VM

# vm load

Query load:

$ ./bin/emqttd_ctl vm load

cpu/load1               : 2.21
cpu/load5               : 2.60
cpu/load15              : 2.36

# 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 listList all the traces
trace client <ClientId> <LogFile>Trace a client
trace client <ClientId> offStop tracing the client
trace topic <Topic> <LogFile>Trace a topic
trace topic <Topic> offStop 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:

acceptorsTCP Acceptor Pool
max_clientsMax number of clients
current_clientsCount of current clients
shutdown_countStatistics 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

# admins add

Add admin account:

$ ./bin/emqttd_ctl admins add root public
ok

# admins passwd

Reset password:

$ ./bin/emqttd_ctl admins passwd root private
ok

# admins del

Delete admin account:

$ ./bin/emqttd_ctl admins del root
ok