plugins
This commit is contained in:
Feng
parent
5558df8ba9
commit
b94776a42d
|
|
@ -5,43 +5,466 @@
|
||||||
Plugins
|
Plugins
|
||||||
=======
|
=======
|
||||||
|
|
||||||
------------------------------------
|
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.
|
||||||
emqttd_plugin_template
|
|
||||||
------------------------------------
|
|
||||||
|
|
||||||
-----------------------------------
|
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
|
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
|
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