plugins

docs/source/plugins.rst

@@ -5,43 +5,466 @@
 Plugins
 =======
 
-------------------------------------
-emqttd_plugin_template
-------------------------------------
+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.
 
------------------------------------
+The plugins that emqtt project released:
+
++---------------------------+---------------------------+
+| Plugin                    | Description               |
++===========================+===========================+
+| `emqttd_plugin_template`_ | Plugin Template           |
++---------------------------+---------------------------+
+| `emqttd_dashboard`_       | Web Dashboard             |
++---------------------------+---------------------------+
+| `emqttd_plugin_mysql`_    | MySQL Auth/ACL Plugin     |
++---------------------------+---------------------------+
+| `emqttd_plugin_pgsql`_    | PostgreSQL Auth/ACL Plugin|
++---------------------------+---------------------------+
+| `emqttd_plugin_redis`_    | Redis Auth/ACL Plugin     |
++---------------------------+---------------------------+
+| `emqttd_stomp`_           | Stomp Protocol Plugin     |
++---------------------------+---------------------------+
+| `emqttd_sockjs`_          | Stomp over SockJS Plugin  |
++---------------------------+---------------------------+
+| `emqttd_recon`_           | Recon Plugin              |
++---------------------------+---------------------------+
+
+----------------------------------------
+emqttd_plugin_template - Plugin Template
+----------------------------------------
+
+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: 
+
++------------------------+---------------------------+
+| File                   | Description               |
++========================+===========================+
+| etc/plugin.config      | Plugin config file        |
++------------------------+---------------------------+
+| ebin/                  | Erlang program files      |
++------------------------+---------------------------+
+
+Load, unload Plugin
+-------------------
+
+Use 'bin/emqttd_ctl plugins' CLI to load, unload a plugin::
+
+    ./bin/emqttd_ctl plugins load <PluginName>
+
+    ./bin/emqttd_ctl plugins unload <PluginName>
+
+    ./bin/emqttd_ctl plugins list
+
+----------------------------------
 emqttd_dashboard: Dashboard Plugin
------------------------------------
+----------------------------------
+
+The Web Dashboard of emqttd broker. Address: http://localhost:18083, Default User: admin, Password: public
+
+.. image:: _static/images/dashboard.png
 
 Configure Dashboard
---------------------
+-------------------
+
+plugins/emqttd_dashboard/etc/plugin.config::
+
+    [
+      {emqttd_dashboard, [
+        {default_admin, [
+          {login, "admin"},
+          {password, "public"}
+        ]},
+        {listener,
+          {emqttd_dashboard, 18083, [
+            {acceptors, 4},
+            {max_clients, 512}]}
+        }
+      ]}
+    ].
 
 -------------------------------------------
-emqttd_plugin_mysql: 
+emqttd_plugin_mysql - MySQL Auth/ACL Plugin
 -------------------------------------------
 
+MQTT Authentication, ACL with MySQL database.
+
+MQTT User Table
+---------------
+
+.. code:: sql
+
+    CREATE TABLE `mqtt_user` (
+      `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
+      `username` varchar(100) DEFAULT NULL,
+      `password` varchar(100) DEFAULT NULL,
+      `salt` varchar(20) DEFAULT NULL,
+      `created` datetime DEFAULT NULL,
+      PRIMARY KEY (`id`),
+      UNIQUE KEY `mqtt_username` (`username`)
+    ) ENGINE=MyISAM DEFAULT CHARSET=utf8;
+
+MQTT ACL Table
+--------------
+
+.. code:: sql
+
+    CREATE TABLE `mqtt_acl` (
+      `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
+      `allow` int(1) DEFAULT NULL COMMENT '0: deny, 1: allow',
+      `ipaddr` varchar(60) DEFAULT NULL COMMENT 'IpAddress',
+      `username` varchar(100) DEFAULT NULL COMMENT 'Username',
+      `clientid` varchar(100) DEFAULT NULL COMMENT 'ClientId',
+      `access` int(2) NOT NULL COMMENT '1: subscribe, 2: publish, 3: pubsub',
+      `topic` varchar(100) NOT NULL DEFAULT '' COMMENT 'Topic Filter',
+      PRIMARY KEY (`id`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+
+
+emqttd_plugin_mysql/etc/plugin.config
+-------------------------------------
+
+Configure MySQL host, username, password and database::
+
+    [
+
+    {emqttd_plugin_mysql, [
+
+        {mysql_pool, [
+            %% ecpool options
+            {pool_size, 4},
+            {auto_reconnect, 3},
+
+            %% mysql options
+            {host,     "localhost"},
+            {port,     3306},
+            {user,     ""},
+            {password, ""},
+            {database, "mqtt"},
+            {encoding, utf8}
+        ]},
+
+        %% select password only
+        {authquery, "select password from mqtt_user where username = '%u' limit 1"},
+
+        %% hash algorithm: md5, sha, sha256, pbkdf2?
+        {password_hash, sha256},
+
+        %% select password with salt
+        %% {authquery, "select password, salt from mqtt_user where username = '%u'"},
+
+        %% sha256 with salt prefix
+        %% {password_hash, {salt, sha256}},
+
+        %% sha256 with salt suffix
+        %% {password_hash, {sha256, salt}},
+
+        %% comment this query, the acl will be disabled
+        {aclquery, "select * from mqtt_acl where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'"},
+
+        %% If no rules matched, return...
+        {acl_nomatch, allow}
+    ]}
+    ].
+
+Load emqttd_plugin_mysql plugin
+-------------------------------
+
+.. code::
+
+    ./bin/emqttd_ctl plugins load emqttd_plugin_mysql
+
 ------------------------------------------------
-emqttd_plugin_pgsql: 
+emqttd_plugin_pgsql - PostgreSQL Auth/ACL Plugin
 ------------------------------------------------
 
---------------------------------------------
-emqttd_plugin_redis: 
---------------------------------------------
+MQTT Authentication, ACL with PostgreSQL Database.
+
+MQTT User Table
+---------------
+
+.. code:: sql
+
+    CREATE TABLE mqtt_user (
+      id SERIAL primary key,
+      username character varying(100),
+      password character varying(100),
+      salt character varying(40)
+    );
+
+MQTT ACL Table
+--------------
+
+.. code:: sql
+
+    CREATE TABLE mqtt_acl (
+      id SERIAL primary key,
+      allow integer,
+      ipaddr character varying(60),
+      username character varying(100),
+      clientid character varying(100),
+      access  integer,
+      topic character varying(100)
+    );
+
+    INSERT INTO mqtt_acl (id, allow, ipaddr, username, clientid, access, topic)
+    VALUES
+        (1,1,NULL,'$all',NULL,2,'#'),
+        (2,0,NULL,'$all',NULL,1,'$SYS/#'),
+        (3,0,NULL,'$all',NULL,1,'eq #'),
+        (5,1,'127.0.0.1',NULL,NULL,2,'$SYS/#'),
+        (6,1,'127.0.0.1',NULL,NULL,2,'#'),
+        (7,1,NULL,'dashboard',NULL,1,'$SYS/#');
+
+Configure emqttd_plugin_pgsql/etc/plugin.config
+-----------------------------------------------
+
+Configure host, username, password and database of PostgreSQL::
+
+    [
+
+      {emqttd_plugin_pgsql, [
+
+        {pgsql_pool, [
+          %% ecpool options
+          {pool_size, 4},
+          {auto_reconnect, 3},
+
+          %% pgsql options
+          {host, "localhost"},
+          {port, 5432},
+          {username, "feng"},
+          {password, ""},
+          {database, "mqtt"},
+          {encoding,  utf8}
+        ]},
+
+        %% select password only
+        {authquery, "select password from mqtt_user where username = '%u' limit 1"},
+
+        %% hash algorithm: md5, sha, sha256, pbkdf2?
+        {password_hash, sha256},
+
+        %% select password with salt
+        %% {authquery, "select password, salt from mqtt_user where username = '%u'"},
+
+        %% sha256 with salt prefix
+        %% {password_hash, {salt, sha256}},
+
+        %% sha256 with salt suffix
+        %% {password_hash, {sha256, salt}},
+
+        %% Comment this query, the acl will be disabled. Notice: don't edit this query!
+        {aclquery, "select allow, ipaddr, username, clientid, access, topic from mqtt_acl
+                     where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'"},
+
+        %% If no rules matched, return...
+        {acl_nomatch, allow}
+      ]}
+    ].
+
+Load emqttd_plugin_pgsql Plugin
+-------------------------------
+
+.. code:: shell
+
+    ./bin/emqttd_ctl plugins load emqttd_plugin_pgsql
+
+-------------------------------------------
+emqttd_plugin_redis - Redis Auth/ACL Plugin
+-------------------------------------------
+
+MQTT Authentication, ACL with Redis.
+
+Configure emqttd_plugin_redis/etc/plugin.config
+-----------------------------------------------
+
+.. code:: erlang
+
+    [
+      {emqttd_plugin_redis, [
+
+        {eredis_pool, [
+          %% ecpool options
+          {pool_size, 8},
+          {auto_reconnect, 2},
+
+          %% eredis options
+          {host, "127.0.0.1"},
+          {port, 6379},
+          {database, 0},
+          {password, ""}
+        ]},
+
+        %% HMGET mqtt_user:%u password
+        {authcmd, ["HGET", "mqtt_user:%u", "password"]},
+
+        %% Password hash algorithm: plain, md5, sha, sha256, pbkdf2?
+        {password_hash, sha256},
+
+        %% SMEMBERS mqtt_acl:%u
+        {aclcmd, ["SMEMBERS", "mqtt_acl:%u"]},
+
+        %% If no rules matched, return...
+        {acl_nomatch, deny},
+
+        %% Store subscriptions to redis when SUBSCRIBE packets received.
+        {subcmd, ["HMSET", "mqtt_subs:%u"]},
+
+        %% Load Subscriptions form Redis when client connected.
+        {loadsub, ["HGETALL", "mqtt_subs:%u"]},
+
+        %% Remove subscriptions from redis when UNSUBSCRIBE packets received.
+        {unsubcmd, ["HDEL", "mqtt_subs:%u"]}
+
+      ]}
+    ].
+
+Load emqttd_plugin_redis Plugin
+-------------------------------
+
+.. code:: console
+
+    ./bin/emqttd_ctl plugins load emqttd_plugin_redis
 
 -----------------------------
-emqttd_stomp: 
+emqttd_stomp - STOMP Protocol
 -----------------------------
 
---------------------------------
-emqttd_sockjs: 
---------------------------------
+Support STOMP 1.0/1.1/1.2 clients to connect to emqttd broker and communicate with MQTT Clients.
+
+Configure emqttd_stomp/etc/plugin.config
+----------------------------------------
+
+.. NOTE:: TCP Port for STOMP Protocol: 61613
+
+.. code:: erlang
+
+    [
+      {emqttd_stomp, [
+
+        {default_user, [
+            {login,    "guest"},
+            {passcode, "guest"}
+        ]},
+
+        {allow_anonymous, true},
 
---------------------------------
-emqttd_recon: Recon Plugin
---------------------------------
+        %%TODO: unused...
+        {frame, [
+          {max_headers,       10},
+          {max_header_length, 1024},
+          {max_body_length,   8192}
+        ]},
 
+        {listeners, [
+          {emqttd_stomp, 61613, [
+            {acceptors,   4},
+            {max_clients, 512}
+          ]}
+        ]}
+
+      ]}
+    ].
+
+Load emqttd_stomp Plugin
+------------------------
+
+.. code::
+
+    ./bin/emqttd_ctl plugins load emqttd_stomp
+
+
+-----------------------------------
+emqttd_sockjs - Stomp/SockJS Plugin
+-----------------------------------
+
+emqttd_sockjs plugin enables web browser to connect to emqttd broker and communicate with MQTT clients.
+
+.. NOTE:: Default TCP Port: 61616
+
+Configure emqttd_sockjs
+-----------------------
+
+.. code:: erlang
+
+    [
+      {emqttd_sockjs, [
+
+        {sockjs, []},
+
+        {cowboy_listener, {stomp_sockjs, 61616, 4}},
+
+      ]}
+    ].
+
+Load emqttd_sockjs Plugin
 -------------------------
+
+.. NOTE:: emqttd_stomp Plugin required.
+
+.. code:: console
+
+    ./bin/emqttd_ctl plugins load emqttd_stomp
+
+    ./bin/emqttd_ctl plugins load emqttd_sockjs
+
+SockJS Demo Page
+----------------
+
+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.
+
+Load emqttd_recon Plugin
+------------------------
+
+.. code:: console
+
+    ./bin/emqttd_ctl plugins load emqttd_recon
+
+Recon CLI
+---------
+
+.. code:: console
+
+    ./bin/emqttd_ctl recon
+
+    recon memory                 #recon_alloc:memory/2
+    recon allocated              #recon_alloc:memory(allocated_types, current|max)
+    recon bin_leak               #recon:bin_leak(100)
+    recon node_stats             #recon:node_stats(10, 1000)
+    recon remote_load Mod        #recon:remote_load(Mod)
+
+
+------------------------
 Plugin Development Guide
+------------------------
+
+Create a Plugin Project
+-----------------------
+
+Register Auth/ACL Modules
 -------------------------
 
+Register Handlers for Hooks
+---------------------------
+
+Register CLI Modules
+--------------------
+
+
+.. _emqttd_dashboard:       https://github.com/emqtt/emqttd_dashboard
+.. _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
+.. _emqttd_stomp:           https://github.com/emqtt/emqttd_stomp
+.. _emqttd_sockjs:          https://github.com/emqtt/emqttd_sockjs
+.. _emqttd_recon:           https://github.com/emqtt/emqttd_recon
+.. _emqttd_plugin_template: https://github.com/emqtt/emqttd_plugin_template
+.. _recon:                  http://ferd.github.io/recon/