yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/README Normal file
View File

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

395
docs/source/guide.rst
View File

@ -9,7 +9,7 @@ User Guide
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.
@ -41,7 +41,7 @@ Enable an authentication module in etc/emqttd.config::
{anonymous, []}
]},
.. NOTE:: "%%" comments the line.
.. NOTE:: "%" comments the line.
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, []}
MySQL Plugin
------------
MySQL
-----
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
PostgreSQL Plugin
-----------------
PostgreSQL
----------
Authenticate against PostgreSQL database. Create a mqtt_user table::
@ -196,7 +196,7 @@ Load the plugin::
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::
@ -243,7 +243,7 @@ Access Control Module of emqttd broker will match the rules one by one::
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::
@ -355,7 +355,7 @@ Configure 'aclquery' and 'acl_nomatch' in emqttd_plugin_pgsql/etc/plugin.config:
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::
@ -474,7 +474,7 @@ Parameters of the HTTP API:
| message | Payload |
+---------+----------------+
.. NOTE:: The API use HTTP Basic Authentication.
.. NOTE:: The API uses HTTP Basic Authentication.
-------------------
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
-----------
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}/
```
$SYS/brokers/${node}
```
'${node}' is the erlang node name of emqttd broker. For example::
${node} is erlang node of clustered brokers. For example:
$SYS/brokers/emqttd@127.0.0.1/version
```
$SYS/brokers/emqttd@host1/version
$SYS/brokers/emqttd@host2/version
```
$SYS/brokers/emqttd@host2/uptime
## Broker $SYS Topics
.. NOTE:: The broker only allows clients from localhost to subscribe $SYS topics by default.
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
 
## Client $SYS Topics
Sys Interval of publishing broker $SYS messages, could be configured in etc/emqttd.config::
Start with: $SYS/brokers/${node}/clients/
{broker, [
%% System interval of
{sys_interval, 60},
Topic | Payload(json) | Description
----------------------|---------------------|---------------
${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:
Broker Version, Uptime and Description
---------------------------------------
+--------------------------------+-----------------------+
| 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 |
+--------------------------------+-----------------------+
Online/Offline Status of MQTT Client
------------------------------------
The topic path is started with: $SYS/brokers/${node}/clients/
+-------------------------+-------------------------------------------+------------------------------------+
| Topic | Payload(JSON) | Description |
+=========================+===========================================+====================================+
| ${clientid}/connected | {ipaddress: "127.0.0.1", username: "test",| Publish when a client connected |
| | session: false, version: 3, connack: 0, | |
| | ts: 1432648482} | |
+-------------------------+-------------------------------------------+------------------------------------+
| ${clientid}/disconnected| {reason: "keepalive_timeout", | Publish when a client disconnected |
| | ts: 1432749431} | |
+-------------------------+-------------------------------------------+------------------------------------+
Parameters of 'connected' Payload::
```
ipaddress: "127.0.0.1",
username: "test",
session: false,
protocol: 3,
connack: 0,
ts: 1432648482
```
Parameters of 'disconnected' Payload:
Parameters of 'disconnected' Payload::
```
reason: normal,
ts: 1432648486
```
## Statistics $SYS Topics
Broker Statistics
-----------------
Start with '$SYS/brokers/${node}/stats/'
Topic path started with: $SYS/brokers/${node}/stats/
### Client Stats
Clients
.......
Topic | Description
-------------------------------------|------------
clients/count | count of current connected clients
clients/max | max connected clients in the same time
+---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| clients/count | Count of current connected clients |
+---------------------+---------------------------------------------+
| clients/max | Max number of cocurrent connected clients |
+---------------------+---------------------------------------------+
### Session Stats
Sessions
........
Topic | Description
-----------------|------------
sessions/count | count of current sessions
sessions/max | max number of sessions
+---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| sessions/count | Count of current sessions |
+---------------------+---------------------------------------------+
| sessions/max | Max number of sessions |
+---------------------+---------------------------------------------+
### Subscriber Stats
Subscriptions
.............
Topic | Description
------------------|------------
subscriptions/count | count of current subscriptions
subscriptions/max | max number of subscriptions
+---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| subscriptions/count | Count of current subscriptions |
+---------------------+---------------------------------------------+
| subscriptions/max | Max number of subscriptions |
+---------------------+---------------------------------------------+
### Topic Stats
Topics
......
Topic | Description
------------------|------------
topics/count | count of current topics
topics/max | max number of topics
+---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| topics/count | Count of current topics |
+---------------------+---------------------------------------------+
| topics/max | Max number of topics |
+---------------------+---------------------------------------------+
### Queue Stats
Broker Metrics
--------------
Topic | Description
------------------|------------
queues/count | count of current queues
queues/max | max number of queues
Topic path started with: $SYS/brokers/${node}/metrics/
Bytes Sent/Received
...................
## Metrics $SYS Topics
+---------------------+---------------------------------------------+
| Topic | Description |
+---------------------+---------------------------------------------+
| bytes/received | MQTT Bytes Received since broker started |
+---------------------+---------------------------------------------+
| bytes/sent | MQTT Bytes Sent since the broker started |
+---------------------+---------------------------------------------+
Start with '$SYS/brokers/${node}/metrics/'
Packets Sent/Received
.....................
### Bytes sent and 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 |
+--------------------------+---------------------------------------------+
Topic | Description
------------------------------------|------------
bytes/received | MQTT Bytes Received since broker started
bytes/sent | MQTT Bytes Sent since the broker started
Messages Sent/Received
......................
### Packets sent and received
+--------------------------+---------------------------------------------+
| Topic | Description |
+--------------------------+---------------------------------------------+
| messages/received | Messages Received |
+--------------------------+---------------------------------------------+
| messages/sent | Messages Sent |
+--------------------------+---------------------------------------------+
| messages/retained | Messages Retained |
+--------------------------+---------------------------------------------+
| messages/stored | TODO: Messages Stored |
+--------------------------+---------------------------------------------+
| messages/dropped | Messages Dropped |
+--------------------------+---------------------------------------------+
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
Broker Alarms
-------------
### Messages sent and received
The topic path started with: $SYS/brokers/${node}/alarms/
Topic | Description
---------------------------------------|-------------------
messages/received | Messages Received
messages/sent | Messages Sent
messages/retained | Messages Retained
messages/stored | TODO: Messages Stored
messages/dropped | Messages Dropped
+------------------+------------------+
| Topic | Description |
+------------------+------------------+
| ${alarmId}/alert | New Alarm |
+------------------+------------------+
| ${alarmId}/clear | Clear Alarm |
+------------------+------------------+
## Alarm Topics
Broker Sysmon
-------------
Start with '$SYS/brokers/${node}/alarms/'
Topic path: '$SYS/brokers/${node}/sysmon/'
Topic | Description
-----------------|-------------------
${alarmId}/alert | New Alarm
${alarmId}/clear | Clear Alarm
+------------------+--------------------+
| 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 |
+------------------+--------------------+
## Log
'$SYS/brokers/${node}/logs/${severity}'
Severity | Description
-----------|-------------------
debug | Debug Log
info | Info Log
notice | Notice Log
warning | Warning Log
error | Error Log
critical | Critical Log
## Sysmon
Start with '$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
## Log
'$SYS/brokers/${node}/log/${severity}'
Severity | Description
------------|-------------------
debug | Debug
info | Info Log
notice | Notice Log
warning | Warning Log
error | Error Log
critical | Critical Log
alert | Alert Log
## VM Load Topics
Start with '$SYS/brokers/${node}/vm/'
Topic | Description
-----------------|-------------------
memory/* | TODO
cpu/* | TODO
processes/* | TODO
## Sys Interval
sys_interval: 1 minute default
---------------------
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_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql
.. _emqttd_plugin_redis: https://github.com/emqtt/emqttd_plugin_redis