docs.emqtt.com

This commit is contained in:
Feng 2016-02-28 15:49:17 +08:00
parent 3866dbaffb
commit f3607230d4
2 changed files with 221 additions and 207 deletions

7
docs/README Normal file
View File

@ -0,0 +1,7 @@
http://docs.emqtt.com/
or
http://emqttd-docs.rtfd.org

View File

@ -9,7 +9,7 @@ User Guide
Authentication Authentication
-------------- --------------
The emqttd broker supports to authenticate MQTT client with ClientID, Username/Password, IpAddress and even HTTP Cookies. The emqttd broker supports to authenticate MQTT clients with ClientID, Username/Password, IpAddress and even HTTP Cookies.
The authentication is provided by a list of extended modules, or MySQL, PostgreSQL and Redis Plugins. The authentication is provided by a list of extended modules, or MySQL, PostgreSQL and Redis Plugins.
@ -41,7 +41,7 @@ Enable an authentication module in etc/emqttd.config::
{anonymous, []} {anonymous, []}
]}, ]},
.. NOTE:: "%%" comments the line. .. NOTE:: "%" comments the line.
If we enable several modules in the same time, the authentication process:: If we enable several modules in the same time, the authentication process::
@ -119,8 +119,8 @@ Allow any client to connect to the broker::
{anonymous, []} {anonymous, []}
MySQL Plugin MySQL
------------ -----
Authenticate against MySQL database. Support we create a mqtt_user table:: Authenticate against MySQL database. Support we create a mqtt_user table::
@ -158,8 +158,8 @@ Load the plugin::
./bin/emqttd_ctl plugins load emqttd_plugin_mysql ./bin/emqttd_ctl plugins load emqttd_plugin_mysql
PostgreSQL Plugin PostgreSQL
----------------- ----------
Authenticate against PostgreSQL database. Create a mqtt_user table:: Authenticate against PostgreSQL database. Create a mqtt_user table::
@ -196,7 +196,7 @@ Load the plugin::
Redis Redis
----- -----
Authenticate against Redis. Support we store mqtt user in an redis HASH, the key is "mqtt_user:<Username>". Authenticate against Redis. MQTT users could be stored in redis HASH, the key is "mqtt_user:<Username>".
Configure 'authcmd' and 'password_hash' in emqttd_plugin_redis/etc/plugin.config:: Configure 'authcmd' and 'password_hash' in emqttd_plugin_redis/etc/plugin.config::
@ -243,7 +243,7 @@ Access Control Module of emqttd broker will match the rules one by one::
Internal Internal
-------- --------
ACL of emqttd broker is implemented by an 'internal' module by default. The default ACL of emqttd broker is implemented by an 'internal' module.
Enable the 'internal' ACL module in etc/emqttd.config:: Enable the 'internal' ACL module in etc/emqttd.config::
@ -355,7 +355,7 @@ Configure 'aclquery' and 'acl_nomatch' in emqttd_plugin_pgsql/etc/plugin.config:
Redis Redis
----- -----
ACL against Redis. We store ACL rules for each MQTT client in Redis List by defualt. The key is "mqtt_acl:<Username>", the value is a list of "publish <Topic>", "subscribe <Topic>" or "pubsub <Topic>". ACL against Redis. We store ACL rules for each MQTT client in a Redis List by defualt. The key is "mqtt_acl:<Username>", the value is a list of "publish <Topic>", "subscribe <Topic>" or "pubsub <Topic>".
Configure 'aclcmd' and 'acl_nomatch' in emqttd_plugin_redis/etc/plugin.config:: Configure 'aclcmd' and 'acl_nomatch' in emqttd_plugin_redis/etc/plugin.config::
@ -474,7 +474,7 @@ Parameters of the HTTP API:
| message | Payload | | message | Payload |
+---------+----------------+ +---------+----------------+
.. NOTE:: The API use HTTP Basic Authentication. .. NOTE:: The API uses HTTP Basic Authentication.
------------------- -------------------
MQTT Over WebSocket MQTT Over WebSocket
@ -509,245 +509,252 @@ Listener of WebSocket and HTTP Publish API is configured in etc/emqttd.config::
]} ]}
]} ]}
## Overview
emqttd could trace packets received/sent from/to specific client, or trace publish/subscribe to specific topic.
emqttd use lager:trace_file api and write trace log to file.
## Trace Commands
### Trace client
```
./bin/emqttd_ctl trace client "ClientId" "trace_clientid.log"
```
### Trace topic
```
./bin/emqttd_ctl trace topic "Topic" "trace_topic.log"
```
### Stop Trace
```
./bin/emqttd_ctl trace client "ClientId" off
./bin/emqttd_ctl trace topic "Topic" off
```
### Lookup Traces
```
./bin/emqttd_ctl trace list
```
----------- -----------
$SYS Topics $SYS Topics
----------- -----------
NOTICE: This is the design of 0.9.0 release The emqttd broker periodically publishes internal status, MQTT statistics, metrics and client online/offline status to $SYS/# topics.
## Overview For emqttd broker is clustered, the $SYS topic path is started with::
For emqttd is clustered, $SYS Topics of broker is started with: $SYS/brokers/${node}/
``` '${node}' is the erlang node name of emqttd broker. For example::
$SYS/brokers/${node}
```
${node} is erlang node of clustered brokers. For example: $SYS/brokers/emqttd@127.0.0.1/version
``` $SYS/brokers/emqttd@host2/uptime
$SYS/brokers/emqttd@host1/version
$SYS/brokers/emqttd@host2/version
```
## Broker $SYS Topics .. NOTE:: The broker only allows clients from localhost to subscribe $SYS topics by default.
Topic | Description Sys Interval of publishing broker $SYS messages, could be configured in etc/emqttd.config::
-------------------------------|------------
$SYS/brokers | Broker nodes
$SYS/brokers/${node}/version | Broker Version
$SYS/brokers/${node}/uptime | Broker Uptime
$SYS/brokers/${node}/datetime | Broker DateTime
$SYS/brokers/${node}/sysdescr | Broker Description
 
## Client $SYS Topics
Start with: $SYS/brokers/${node}/clients/ {broker, [
%% System interval of
Topic | Payload(json) | Description {sys_interval, 60},
----------------------|---------------------|---------------
${clientid}/connected | {ipaddress: "127.0.0.1", username: "test", session: false, version: 3, connack: 0, ts: 1432648482} | Publish when client connected
${clientid}/disconnected | {reason: "normal" | "keepalive_timeout" | "conn_closed"}
Parameters of 'connected' Payload:
```
ipaddress: "127.0.0.1",
username: "test",
session: false,
protocol: 3,
connack: 0,
ts: 1432648482
```
Parameters of 'disconnected' Payload:
```
reason: normal,
ts: 1432648486
```
## Statistics $SYS Topics
Start with '$SYS/brokers/${node}/stats/'
### Client Stats
Topic | Description
-------------------------------------|------------
clients/count | count of current connected clients
clients/max | max connected clients in the same time
### Session Stats
Topic | Description
-----------------|------------
sessions/count | count of current sessions
sessions/max | max number of sessions
### Subscriber Stats
Topic | Description
------------------|------------
subscriptions/count | count of current subscriptions
subscriptions/max | max number of subscriptions
### Topic Stats
Topic | Description
------------------|------------
topics/count | count of current topics
topics/max | max number of topics
### Queue Stats
Topic | Description
------------------|------------
queues/count | count of current queues
queues/max | max number of queues
## Metrics $SYS Topics Broker Version, Uptime and Description
---------------------------------------
Start with '$SYS/brokers/${node}/metrics/' +--------------------------------+-----------------------+
| Topic | Description |
+================================+=======================+
| $SYS/brokers | Broker nodes |
+--------------------------------+-----------------------+
| $SYS/brokers/${node}/version | Broker Version |
+--------------------------------+-----------------------+
| $SYS/brokers/${node}/uptime | Broker Uptime |
+--------------------------------+-----------------------+
| $SYS/brokers/${node}/datetime | Broker DateTime |
+--------------------------------+-----------------------+
| $SYS/brokers/${node}/sysdescr | Broker Description |
+--------------------------------+-----------------------+
### Bytes sent and received Online/Offline Status of MQTT Client
------------------------------------
Topic | Description The topic path is started with: $SYS/brokers/${node}/clients/
------------------------------------|------------
bytes/received | MQTT Bytes Received since broker started
bytes/sent | MQTT Bytes Sent since the broker started
### Packets sent and received +-------------------------+-------------------------------------------+------------------------------------+
| Topic | Payload(JSON) | Description |
Topic | Description +=========================+===========================================+====================================+
-------------------------|------------ | ${clientid}/connected | {ipaddress: "127.0.0.1", username: "test",| Publish when a client connected |
packets/received | MQTT Packets received | | session: false, version: 3, connack: 0, | |
packets/sent | MQTT Packets sent | | ts: 1432648482} | |
packets/connect | MQTT CONNECT Packet received +-------------------------+-------------------------------------------+------------------------------------+
packets/connack | MQTT CONNACK Packet sent | ${clientid}/disconnected| {reason: "keepalive_timeout", | Publish when a client disconnected |
packets/publish/received | MQTT PUBLISH packets received | | ts: 1432749431} | |
packets/publish/sent | MQTT PUBLISH packets sent +-------------------------+-------------------------------------------+------------------------------------+
packets/subscribe | MQTT SUBSCRIBE Packets received
packets/suback | MQTT SUBACK packets sent
packets/unsubscribe | MQTT UNSUBSCRIBE Packets received
packets/unsuback | MQTT UNSUBACK Packets sent
packets/pingreq | MQTT PINGREQ packets received
packets/pingresp | MQTT PINGRESP Packets sent
packets/disconnect | MQTT DISCONNECT Packets received
### Messages sent and received Parameters of 'connected' Payload::
Topic | Description ipaddress: "127.0.0.1",
---------------------------------------|------------------- username: "test",
messages/received | Messages Received session: false,
messages/sent | Messages Sent protocol: 3,
messages/retained | Messages Retained connack: 0,
messages/stored | TODO: Messages Stored ts: 1432648482
messages/dropped | Messages Dropped
## Alarm Topics Parameters of 'disconnected' Payload::
Start with '$SYS/brokers/${node}/alarms/' reason: normal,
ts: 1432648486
Topic | Description Broker Statistics
-----------------|------------------- -----------------
${alarmId}/alert | New Alarm
${alarmId}/clear | Clear Alarm
## Log Topic path started with: $SYS/brokers/${node}/stats/
'$SYS/brokers/${node}/logs/${severity}' Clients
.......
Severity | Description +---------------------+---------------------------------------------+
-----------|------------------- | Topic | Description |
debug | Debug Log +---------------------+---------------------------------------------+
info | Info Log | clients/count | Count of current connected clients |
notice | Notice Log +---------------------+---------------------------------------------+
warning | Warning Log | clients/max | Max number of cocurrent connected clients |
error | Error Log +---------------------+---------------------------------------------+
critical | Critical Log
## Sysmon Sessions
........
Start with '$SYS/brokers/${node}/sysmon/' +---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| sessions/count | Count of current sessions |
+---------------------+---------------------------------------------+
| sessions/max | Max number of sessions |
+---------------------+---------------------------------------------+
Topic | Description Subscriptions
-----------------|------------------- .............
long_gc | Long GC Warning
long_schedule | Long Schedule
large_heap | Large Heap Warning
busy_port | Busy Port Warning
busy_dist_port | Busy Dist Port
## Log +---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| subscriptions/count | Count of current subscriptions |
+---------------------+---------------------------------------------+
| subscriptions/max | Max number of subscriptions |
+---------------------+---------------------------------------------+
'$SYS/brokers/${node}/log/${severity}' Topics
......
Severity | Description +---------------------+---------------------------------------------+
------------|------------------- | Topic | Description |
debug | Debug +---------------------+---------------------------------------------+
info | Info Log | topics/count | Count of current topics |
notice | Notice Log +---------------------+---------------------------------------------+
warning | Warning Log | topics/max | Max number of topics |
error | Error Log +---------------------+---------------------------------------------+
critical | Critical Log
alert | Alert Log
## VM Load Topics Broker Metrics
--------------
Start with '$SYS/brokers/${node}/vm/' Topic path started with: $SYS/brokers/${node}/metrics/
Topic | Description Bytes Sent/Received
-----------------|------------------- ...................
memory/* | TODO
cpu/* | TODO
processes/* | TODO
## Sys Interval +---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| bytes/received | MQTT Bytes Received since broker started |
+---------------------+---------------------------------------------+
| bytes/sent | MQTT Bytes Sent since the broker started |
+---------------------+---------------------------------------------+
Packets Sent/Received
.....................
+--------------------------+---------------------------------------------+
| Topic | Description |
+--------------------------+---------------------------------------------+
| packets/received | MQTT Packets received |
+--------------------------+---------------------------------------------+
| packets/sent | MQTT Packets sent |
+--------------------------+---------------------------------------------+
| packets/connect | MQTT CONNECT Packet received |
+--------------------------+---------------------------------------------+
| packets/connack | MQTT CONNACK Packet sent |
+--------------------------+---------------------------------------------+
| packets/publish/received | MQTT PUBLISH packets received |
+--------------------------+---------------------------------------------+
| packets/publish/sent | MQTT PUBLISH packets sent |
+--------------------------+---------------------------------------------+
| packets/subscribe | MQTT SUBSCRIBE Packets received |
+--------------------------+---------------------------------------------+
| packets/suback | MQTT SUBACK packets sent |
+--------------------------+---------------------------------------------+
| packets/unsubscribe | MQTT UNSUBSCRIBE Packets received |
+--------------------------+---------------------------------------------+
| packets/unsuback | MQTT UNSUBACK Packets sent |
+--------------------------+---------------------------------------------+
| packets/pingreq | MQTT PINGREQ packets received |
+--------------------------+---------------------------------------------+
| packets/pingresp | MQTT PINGRESP Packets sent |
+--------------------------+---------------------------------------------+
| packets/disconnect | MQTT DISCONNECT Packets received |
+--------------------------+---------------------------------------------+
Messages Sent/Received
......................
+--------------------------+---------------------------------------------+
| Topic | Description |
+--------------------------+---------------------------------------------+
| messages/received | Messages Received |
+--------------------------+---------------------------------------------+
| messages/sent | Messages Sent |
+--------------------------+---------------------------------------------+
| messages/retained | Messages Retained |
+--------------------------+---------------------------------------------+
| messages/stored | TODO: Messages Stored |
+--------------------------+---------------------------------------------+
| messages/dropped | Messages Dropped |
+--------------------------+---------------------------------------------+
Broker Alarms
-------------
The topic path started with: $SYS/brokers/${node}/alarms/
+------------------+------------------+
| Topic | Description |
+------------------+------------------+
| ${alarmId}/alert | New Alarm |
+------------------+------------------+
| ${alarmId}/clear | Clear Alarm |
+------------------+------------------+
Broker Sysmon
-------------
Topic path: '$SYS/brokers/${node}/sysmon/'
+------------------+--------------------+
| Topic | Description |
+------------------+--------------------+
| long_gc | Long GC Warning |
+------------------+--------------------+
| long_schedule | Long Schedule |
+------------------+--------------------+
| large_heap | Large Heap Warning |
+------------------+--------------------+
| busy_port | Busy Port Warning |
+------------------+--------------------+
| busy_dist_port | Busy Dist Port |
+------------------+--------------------+
sys_interval: 1 minute default
--------------------- ---------------------
Trace Topic or Client Trace Topic or Client
--------------------- ---------------------
The emqttd broker supports to trace MQTT packets received/sent from/to a client, or trace MQTT messages published to a topic.
Trace a client::
./bin/emqttd_ctl trace client "clientid" "trace_clientid.log"
Trace a topic::
./bin/emqttd_ctl trace topic "topic" "trace_topic.log"
Lookup Traces::
./bin/emqttd_ctl trace list
Stop a Trace::
./bin/emqttd_ctl trace client "clientid" off
./bin/emqttd_ctl trace topic "topic" off
.. _emqttd_plugin_mysql: https://github.com/emqtt/emqttd_plugin_mysql .. _emqttd_plugin_mysql: https://github.com/emqtt/emqttd_plugin_mysql
.. _emqttd_plugin_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql .. _emqttd_plugin_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql
.. _emqttd_plugin_redis: https://github.com/emqtt/emqttd_plugin_redis .. _emqttd_plugin_redis: https://github.com/emqtt/emqttd_plugin_redis