docs.emqtt.com

docs/README

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

docs/source/guide.rst

@@ -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
-
-## Overview
-
-For emqttd is clustered, $SYS Topics of broker is started with:
-
-```
-$SYS/brokers/${node}
-```
+The emqttd broker periodically publishes internal status, MQTT statistics, metrics and client online/offline status to $SYS/# topics.
 
-${node} is erlang node of clustered brokers. For example:
+For emqttd broker is clustered, the $SYS topic path is started with::
 
-```
-$SYS/brokers/emqttd@host1/version
-$SYS/brokers/emqttd@host2/version
-```
+    $SYS/brokers/${node}/
 
-## Broker $SYS Topics
+'${node}' is the erlang node name of emqttd broker. For example::
 
-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/brokers/emqttd@127.0.0.1/version
 
-Start with: $SYS/brokers/${node}/clients/
+    $SYS/brokers/emqttd@host2/uptime
 
-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"}
+.. NOTE:: The broker only allows clients from localhost to subscribe $SYS topics by default. 
 
-Parameters of 'connected' Payload:
+Sys Interval of publishing broker $SYS messages, could be configured in etc/emqttd.config::
 
-```
-ipaddress: "127.0.0.1", 
-username: "test", 
-session: false, 
-protocol: 3, 
-connack: 0, 
-ts: 1432648482
-```
+    {broker, [
+        %% System interval of 
+        {sys_interval, 60},
 
-Parameters of 'disconnected' Payload:
 
-```
-reason: normal,
-ts: 1432648486
-```
+Broker Version, Uptime and Description
+---------------------------------------
 
-## Statistics $SYS Topics
++--------------------------------+-----------------------+
+| 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    |
++--------------------------------+-----------------------+
 
-Start with '$SYS/brokers/${node}/stats/'
+Online/Offline Status of MQTT Client
+------------------------------------
 
-### Client Stats
+The topic path is started with: $SYS/brokers/${node}/clients/
 
-Topic                                | Description
--------------------------------------|------------
-clients/count   | count of current connected clients
-clients/max     | max connected clients in the same time
++-------------------------+-------------------------------------------+------------------------------------+
+| 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}                          |                                    |
++-------------------------+-------------------------------------------+------------------------------------+
 
-### Session Stats
+Parameters of 'connected' Payload::
 
-Topic            | Description
------------------|------------
-sessions/count   | count of current sessions
-sessions/max     | max number of sessions
+    ipaddress: "127.0.0.1", 
+    username:  "test", 
+    session:   false, 
+    protocol:  3, 
+    connack:   0, 
+    ts:        1432648482
 
-### Subscriber Stats
+Parameters of 'disconnected' Payload::
 
-Topic             | Description
-------------------|------------
-subscriptions/count | count of current subscriptions
-subscriptions/max   | max number of subscriptions
+    reason: normal,
+    ts:     1432648486
 
-### 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
-
-Start with '$SYS/brokers/${node}/metrics/'
-
-### Bytes sent and received
-
-Topic                               | Description
-------------------------------------|------------
-bytes/received | MQTT Bytes Received since broker started
-bytes/sent     | MQTT Bytes Sent since the broker started
-
-### Packets 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
-
-### Messages 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
-
-## Alarm Topics
-
-Start with '$SYS/brokers/${node}/alarms/'
-
-Topic            | Description
------------------|-------------------
-${alarmId}/alert | New Alarm
-${alarmId}/clear | Clear Alarm
+Broker Statistics
+-----------------
 
-## Log
+Topic path started with: $SYS/brokers/${node}/stats/
+
+Clients
+.......
+
++---------------------+---------------------------------------------+
+| Topic               | Description                                 |
++---------------------+---------------------------------------------+
+| clients/count       | Count of current connected clients          |
++---------------------+---------------------------------------------+
+| clients/max         | Max number of cocurrent connected clients   |
++---------------------+---------------------------------------------+
+
+Sessions
+........
+
++---------------------+---------------------------------------------+
+| Topic               | Description                                 |
++---------------------+---------------------------------------------+
+| sessions/count      | Count of current sessions                   |
++---------------------+---------------------------------------------+
+| sessions/max        | Max number of sessions                      |
++---------------------+---------------------------------------------+
+
+Subscriptions
+.............
+
++---------------------+---------------------------------------------+
+| Topic               | Description                                 |
++---------------------+---------------------------------------------+
+| subscriptions/count | Count of current subscriptions              | 
++---------------------+---------------------------------------------+
+| subscriptions/max   | Max number of subscriptions                 |
++---------------------+---------------------------------------------+
+
+Topics
+......
+
++---------------------+---------------------------------------------+
+| Topic               | Description                                 |
++---------------------+---------------------------------------------+
+| topics/count        | Count of current topics                     |
++---------------------+---------------------------------------------+
+| topics/max          | Max number of topics                        |
++---------------------+---------------------------------------------+
+
+Broker Metrics
+--------------
 
-'$SYS/brokers/${node}/logs/${severity}'
+Topic path started with: $SYS/brokers/${node}/metrics/
+
+Bytes Sent/Received
+...................
+
++---------------------+---------------------------------------------+
+| 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     |
++------------------+--------------------+
 
-Severity   |  Description
------------|-------------------
-debug      | Debug Log
-info       | Info Log
-notice     | Notice Log
-warning    | Warning Log
-error      | Error Log
-critical   | Critical Log
 
-## Sysmon
+---------------------
+Trace Topic or Client
+---------------------
 
-Start with '$SYS/brokers/${node}/sysmon/'
+The emqttd broker supports to trace MQTT packets received/sent from/to a client, or trace MQTT messages published to a topic.
 
-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
+Trace a client::
 
-## Log
+    ./bin/emqttd_ctl trace client "clientid" "trace_clientid.log"
 
-'$SYS/brokers/${node}/log/${severity}'
+Trace a topic::
 
-Severity    | Description
-------------|-------------------
-debug       | Debug
-info        | Info Log
-notice      | Notice Log
-warning     | Warning Log
-error       | Error Log
-critical    | Critical Log
-alert       | Alert Log
+    ./bin/emqttd_ctl trace topic "topic" "trace_topic.log"
 
-## VM Load Topics
+Lookup Traces::
 
-Start with '$SYS/brokers/${node}/vm/'
+    ./bin/emqttd_ctl trace list
 
-Topic            | Description
------------------|-------------------
-memory/*         | TODO
-cpu/*            | TODO
-processes/*      | TODO
+Stop a Trace::
 
-## Sys Interval
+    ./bin/emqttd_ctl trace client "clientid" off
 
-sys_interval: 1 minute default
+    ./bin/emqttd_ctl trace topic "topic" off
 
----------------------
-Trace Topic or Client
----------------------
 
 .. _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
+