upgrade

docs/source/commands.rst

@@ -127,7 +127,7 @@ Cluster two or more emqttd brokers.
 | cluster status        | Query cluster status and nodes |
 +-----------------------+--------------------------------+
 
-Suppose we create two emqttd nodes and cluster them on localhost:
+Suppose we create two emqttd nodes on localhost and cluster them:
 
 +-----------+---------------------+-------------+
 | Folder    | Node                | MQTT Port   |
@@ -181,7 +181,7 @@ clients
 Query MQTT clients connected to the broker:
 
 +-------------------------+----------------------------------+
-| clients list            | Show all MQTT clients            |
+| clients list            | List all MQTT clients            |
 +-------------------------+----------------------------------+
 | clients show <ClientId> | Show a MQTT Client               |
 +-------------------------+----------------------------------+
@@ -235,7 +235,7 @@ 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            | Query all Sessions            |
+| sessions list            | List all Sessions             |
 +--------------------------+-------------------------------+
 | sessions list persistent | Query all persistent Sessions |
 +--------------------------+-------------------------------+
@@ -340,7 +340,7 @@ subscriptions
 Query the subscription table of the broker:
 
 +--------------------------------------------+--------------------------------------+
-| subscriptions list                         | Query all subscriptions              |
+| subscriptions list                         | List all subscriptions               |
 +--------------------------------------------+--------------------------------------+
 | subscriptions show <ClientId>              | Show a subscription                  |
 +--------------------------------------------+--------------------------------------+

docs/source/plugins.rst

@@ -1,9 +1,9 @@
 
 .. _plugins:
 
-=======
-Plugins
-=======
+============
+Plugin Guide
+============
 
 The emqttd broker could be extended by plugins. Users could develop plugins to customize authentication, ACL and functions of the broker, or integrate the broker with other systems.
 
@@ -12,7 +12,7 @@ The plugins that emqtt project released:
 +---------------------------+---------------------------+
 | Plugin                    | Description               |
 +===========================+===========================+
-| `emqttd_plugin_template`_ | Plugin Template           |
+| `emqttd_plugin_template`_ | Template Plugin           |
 +---------------------------+---------------------------+
 | `emqttd_dashboard`_       | Web Dashboard             |
 +---------------------------+---------------------------+
@@ -22,20 +22,20 @@ The plugins that emqtt project released:
 +---------------------------+---------------------------+
 | `emqttd_plugin_redis`_    | Redis Auth/ACL Plugin     |
 +---------------------------+---------------------------+
-| `emqttd_stomp`_           | Stomp Protocol Plugin     |
+| `emqttd_stomp`_           | STOMP Protocol Plugin     |
 +---------------------------+---------------------------+
-| `emqttd_sockjs`_          | Stomp over SockJS Plugin  |
+| `emqttd_sockjs`_          | STOMP over SockJS Plugin  |
 +---------------------------+---------------------------+
 | `emqttd_recon`_           | Recon Plugin              |
 +---------------------------+---------------------------+
 
 ----------------------------------------
-emqttd_plugin_template - Plugin Template
+emqttd_plugin_template - Template Plugin
 ----------------------------------------
 
 A plugin is just a normal Erlang application under the 'emqttd/plugins' folder. Each plugin has e configuration file: 'etc/plugin.config'.
 
-plugins/emqttd_plugin_template is a demo plugin: 
+plugins/emqttd_plugin_template is a demo plugin. The folder structure:
 
 +------------------------+---------------------------+
 | File                   | Description               |
@@ -56,18 +56,26 @@ Use 'bin/emqttd_ctl plugins' CLI to load, unload a plugin::
 
     ./bin/emqttd_ctl plugins list
 
-----------------------------------
-emqttd_dashboard: Dashboard Plugin
-----------------------------------
+-----------------------------------
+emqttd_dashboard - Dashboard Plugin
+-----------------------------------
 
-The Web Dashboard of emqttd broker. Address: http://localhost:18083, Default User: admin, Password: public
+The Web Dashboard for emqttd broker. The plugin will be loaded automatically when the broker started successfully.
+
++------------------+---------------------------+
+| Address          | http://localhost:18083    |
++------------------+---------------------------+
+| Default User     | admin                     |
++------------------+---------------------------+
+| Default Password | public                    |
++------------------+---------------------------+
 
 .. image:: _static/images/dashboard.png
 
 Configure Dashboard
 -------------------
 
-plugins/emqttd_dashboard/etc/plugin.config::
+emqttd_dashboard/etc/plugin.config::
 
     [
       {emqttd_dashboard, [
@@ -121,8 +129,8 @@ MQTT ACL Table
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
 
 
-emqttd_plugin_mysql/etc/plugin.config
--------------------------------------
+Configure emqttd_plugin_mysql/etc/plugin.config
+-----------------------------------------------
 
 Configure MySQL host, username, password and database::
 
@@ -336,7 +344,7 @@ Support STOMP 1.0/1.1/1.2 clients to connect to emqttd broker and communicate wi
 Configure emqttd_stomp/etc/plugin.config
 ----------------------------------------
 
-.. NOTE:: TCP Port for STOMP Protocol: 61613
+.. NOTE:: Default Port for STOMP Protocol: 61613
 
 .. code:: erlang
 
@@ -376,7 +384,7 @@ Load emqttd_stomp Plugin
 
 
 -----------------------------------
-emqttd_sockjs - Stomp/SockJS Plugin
+emqttd_sockjs - STOMP/SockJS Plugin
 -----------------------------------
 
 emqttd_sockjs plugin enables web browser to connect to emqttd broker and communicate with MQTT clients.
@@ -418,7 +426,7 @@ http://localhost:61616/index.html
 emqttd_recon - Recon Plugin
 ---------------------------
 
-The plugin will load `recon`_ library on a running emqttd broker. Recon libray helps to debug and optimize an Erlang application.
+The plugin loads `recon`_ library on a running emqttd broker. Recon libray helps to debug and optimize an Erlang application.
 
 Load emqttd_recon Plugin
 ------------------------
@@ -448,15 +456,154 @@ Plugin Development Guide
 Create a Plugin Project
 -----------------------
 
+Clone emqttd source from github.com::
+
+    git clone https://github.com/emqtt/emqttd.git
+
+Create a plugin project under 'plugins' folder::
+
+    cd plugins && mkdir emqttd_my_plugin
+
+    cd emqttd_my_plugin && rebar create-app appid=emqttd_my_plugin
+
+Template Plugin: https://github.com/emqtt/emqttd_plugin_template
+
 Register Auth/ACL Modules
 -------------------------
 
+emqttd_auth_demo.erl - demo authentication module:
+
+.. code:: erlang
+
+    -module(emqttd_auth_demo).
+
+    -behaviour(emqttd_auth_mod).
+
+    -include("../../../include/emqttd.hrl").
+
+    -export([init/1, check/3, description/0]).
+
+    init(Opts) -> {ok, Opts}.
+
+    check(#mqtt_client{client_id = ClientId, username = Username}, Password, _Opts) ->
+        io:format("Auth Demo: clientId=~p, username=~p, password=~p~n",
+                  [ClientId, Username, Password]),
+        ok.
+
+    description() -> "Demo Auth Module".
+
+emqttd_acl_demo.erl - demo ACL module:
+
+.. code:: erlang
+
+    -module(emqttd_acl_demo).
+
+    -include("../../../include/emqttd.hrl").
+
+    %% ACL callbacks
+    -export([init/1, check_acl/2, reload_acl/1, description/0]).
+
+    init(Opts) ->
+        {ok, Opts}.
+
+    check_acl({Client, PubSub, Topic}, Opts) ->
+        io:format("ACL Demo: ~p ~p ~p~n", [Client, PubSub, Topic]),
+        allow.
+
+    reload_acl(_Opts) ->
+        ok.
+
+    description() -> "ACL Module Demo".
+
+emqttd_plugin_template_app.erl - Register the auth/ACL modules:
+
+.. code:: erlang
+
+    ok = emqttd_access_control:register_mod(auth, emqttd_auth_demo, []),
+    ok = emqttd_access_control:register_mod(acl, emqttd_acl_demo, []),
+
+
 Register Handlers for Hooks
 ---------------------------
 
+The plugin could register handlers for hooks. The hooks will be called by the broker when a client connected/disconnected, a topic subscribed/unsubscribed or a message published/delivered.
+
+emqttd_plugin_template.erl for example::
+
+    %% Called when the plugin application start
+    load(Env) ->
+
+        emqttd_broker:hook('client.connected', {?MODULE, on_client_connected},
+                           {?MODULE, on_client_connected, [Env]}),
+
+        emqttd_broker:hook('client.disconnected', {?MODULE, on_client_disconnected},
+                           {?MODULE, on_client_disconnected, [Env]}),
+
+        emqttd_broker:hook('client.subscribe', {?MODULE, on_client_subscribe},
+                           {?MODULE, on_client_subscribe, [Env]}),
+
+        emqttd_broker:hook('client.subscribe.after', {?MODULE, on_client_subscribe_after},
+                           {?MODULE, on_client_subscribe_after, [Env]}),
+
+        emqttd_broker:hook('client.unsubscribe', {?MODULE, on_client_unsubscribe},
+                           {?MODULE, on_client_unsubscribe, [Env]}),
+
+        emqttd_broker:hook('message.publish', {?MODULE, on_message_publish},
+                           {?MODULE, on_message_publish, [Env]}),
+
+        emqttd_broker:hook('message.acked', {?MODULE, on_message_acked},
+                           {?MODULE, on_message_acked, [Env]}).
+
+Hook List:
+
++------------------------+-------------+---------------------------------------+
+| Name                   | Type        | Description                           |
++------------------------+-------------+---------------------------------------+
+| client.connected       | foreach     | Run when a client connected to the    |
+|                        |             | broker successfully                   |
++------------------------+-------------+---------------------------------------+
+| client.subscribe       | foldl       | Run before a client subscribes topics |
++------------------------+-------------+---------------------------------------+
+| client.subscribe.after | foreach     | Run after a client subscribed topics  |
++------------------------+-------------+---------------------------------------+
+| client.unsubscribe     | foldl       | Run when a client unsubscribes topics |
++------------------------+-------------+---------------------------------------+
+| message.publish        | foldl       | Run when a message is published       |
++------------------------+-------------+---------------------------------------+
+| message.acked          | foreach     | Run when a message is delivered       |
++------------------------+-------------+---------------------------------------+
+| client.disconnected    | foreach     | Run when a client is disconnnected    |
++----------------------- +-------------+---------------------------------------+
+
 Register CLI Modules
 --------------------
 
+emqttd_cli_demo.erl:
+
+.. code:: erlang
+
+    -module(emqttd_cli_demo).
+
+    -include("../../../include/emqttd_cli.hrl").
+
+    -export([cmd/1]).
+
+    cmd(["arg1", "arg2"]) ->
+        ?PRINT_MSG("ok");
+
+    cmd(_) ->
+        ?USAGE([{"cmd arg1 arg2", "cmd demo"}]).
+
+emqttd_plugin_template_app.erl - register the CLI module to emqttd broker:
+
+.. code:: erlang
+
+    emqttd_ctl:register_cmd(cmd, {emqttd_cli_demo, cmd}, []).
+
+There will be a new CLI after the plugin loaded::
+
+    ./bin/emqttd_ctl cmd arg1 arg2
+
 
 .. _emqttd_dashboard:       https://github.com/emqtt/emqttd_dashboard
 .. _emqttd_plugin_mysql:    https://github.com/emqtt/emqttd_plugin_mysql