diff --git a/docs/source/commands.rst b/docs/source/commands.rst index 6f01c348b..91a29be72 100644 --- a/docs/source/commands.rst +++ b/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 | 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 | Show a subscription | +--------------------------------------------+--------------------------------------+ diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index d7db15156..071518602 100644 --- a/docs/source/plugins.rst +++ b/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