EMQ is a MQTT broker written in Erlang. The broker is opensource and licensed under Apache 2.
EMQ broker has plugin support to extend features of the broker. Such that, EMQ broker has a web dashboard to handle administrative task which is actually a EMQ plugin developed out of EMQ broker. So if you want to add such custom feature to broker you can develop plugin for that by yourself. The tutorial will follow the steps which is need to develop a EMQ plugin.
EMQ broker's internal program flow can be intercepted in two ways. One is by module directly and another is by hook.
Such as, Authentication & Authorization can be handled by registering module.
And client connect, disconnect, publish, subscribe, acknowledged, delivered etc by hooks.
First of all create an Erlang project using rebar3.
// Our plugin name is emq_custom_plugin
// It will be used across the the tutorial
rebar3 new app emq_custom_plugin
Then in root folder add two more files erlang.mk
& Makefile
.
Checkout this for erlang.mk file content
And Makefile content will be,
Create a folder named etc
and add a file emq_custom_plugin.config
having content,
[
{emq_custom_plugin, [
{"version", "1.0"}
]}
].
Ok, We are ready to go.
Now to intercept Authentication [auth
] & Authorization [acl
] we have to register module having few function which structure is predefined by EMQ.
// Init function
init(Opts)->
{ok, Opts}.
// Authentication function
check(#mqtt_client{client_id = ClientId, username = Username}, Password, _Opts) ->
ok.
// Authorization
check_acl({Client, PubSub, Topic}, Opts) ->
allow.
// Reloading authorization
reload_acl(_Opts) ->
ok.
// To provide module description
description() ->
"EMQ Custom Plugin".
These functions must be public.
Assume our module name is emq_custom_plugin.erl
having these functions.
And
-behaviour(emqttd_auth_mod).
-include_lib("emqttd/include/emqttd.hrl").
-include_lib("emqttd/include/emqttd_cli.hrl").
these are at top.
Now to register it we have to add below lines in emq_custom_plugin_app.erl
in start
function,
ok = emqttd_access_control:register_mod(auth, emq_custom_plugin, []),
ok = emqttd_access_control:register_mod(acl, emq_custom_plugin, [])
in stop
function,
ok = emqttd_access_control:unregister_mod(auth, emq_auth_demo),
ok = emqttd_access_control:unregister_mod(acl, emq_acl_demo),
Now you will get callback for auth
and acl
in emq_custom_plugin
module in respective functions.
Lets play with hooks,
Assume we have another module named mod_hook_handler.erl
then it should have this definitions depending on your requirements,
And in emq_custom_plugin.erl
in start
function add,
mod_hook_handler:load(application:get_all_env())
in stop
function,
emq_plugin_template:unload().
Well your plugin is ready. Now we will deploy it to broker. For that,
Clone https://github.com/emqtt/emq-relx
in your system and enter into the emq-relx
folder. Then in plugin section of relx.config
add,
{emq_custom_plugin, load}
In Makefile
concat emq_custom_plugin
with DEPS
and add,
dep_emq_custom_plugin = git git_url branch_name
Finally execute, make clean && make && make rel
.
If everything goes ok then start the broker.
Move to _rel/emqttd/bin
and
execute emqttd_ctl plugins load emq_custom_plugin
Your plugin is now running in the system.
To stop it execute emqttd_ctl plugins unload emq_custom_plugin
.
You can also start and stop plugin from web dashboard.
References,