plugins
This commit is contained in:
Feng
parent
5558df8ba9
commit
b94776a42d
|
|
@ -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 - 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 - PostgreSQL Auth/ACL Plugin
|
||||
------------------------------------------------
|
||||
|
||||
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 - STOMP Protocol
|
||||
-----------------------------
|
||||
|
||||
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},
|
||||
|
||||
%%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_plugin_mysql:
|
||||
-------------------------------------------
|
||||
|
||||
------------------------------------------------
|
||||
emqttd_plugin_pgsql:
|
||||
------------------------------------------------
|
||||
|
||||
--------------------------------------------
|
||||
emqttd_plugin_redis:
|
||||
--------------------------------------------
|
||||
|
||||
-----------------------------
|
||||
emqttd_stomp:
|
||||
-----------------------------
|
||||
|
||||
--------------------------------
|
||||
emqttd_sockjs:
|
||||
--------------------------------
|
||||
|
||||
--------------------------------
|
||||
emqttd_recon: Recon Plugin
|
||||
--------------------------------
|
||||
|
||||
-------------------------
|
||||
Plugin Development Guide
|
||||
-------------------------
|
||||
|
||||
.. _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/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue