# Plugins

The EMQ X Broker distribution contains a large number of official plug-ins, which provide some basic or various extended functions.

They rely on the code API of emqx (opens new window) or hooks for their special functions.

You can compile it with the emqx (opens new window) core project and package it into a working package.

WARNING

EMQ X Enterprise edition customers are not provided with the source code. EMQ provides no supports for customer developed plugins in their development, test or integration work.

# List of plugins

The official plug-ins provided by EMQ X include:

PluginConfiguration fileDescription
emqx_dashboard (opens new window)etc/plugins/emqx_dashbord.confWeb dashboard Plugin (Default)
emqx_management (opens new window)etc/plugins/emqx_management.confHTTP API and CLI Management Plugin
emqx_auth_mnesia (opens new window)etc/plugins/emqx_auth_mnesia.confMnesia Auth/access control
emqx_auth_jwt (opens new window)etc/plugins/emqx_auth_jwt.confJWT Auth/access control
emqx_auth_ldap (opens new window)etc/plugins/emqx_auth_ldap.confLDAP Auth/access control
emqx_auth_http (opens new window)etc/plugins/emqx_auth_http.confHTTP Auth/access control
emqx_auth_mongo (opens new window)etc/plugins/emqx_auth_mongo.confMongoDB Auth/access control
emqx_auth_mysql (opens new window)etc/plugins/emqx_auth_mysql.confMySQL Auth/access control
emqx_auth_pgsql (opens new window)etc/plugins/emqx_auth_pgsql.confPostgreSQL Auth/access control
emqx_auth_redis (opens new window)etc/plugins/emqx_auth_redis.confRedis Auth/access control
emqx_psk_file (opens new window)etc/plugins/emqx_psk_file.confPSK support
emqx_web_hook (opens new window)etc/plugins/emqx_web_hook.confWeb Hook Plugin
emqx_lua_hook (opens new window)etc/plugins/emqx_lua_hook.confLua Hook Plugin
emqx_retainer (opens new window)etc/plugins/emqx_retainer.confRetain Message storage module
emqx_rule_engine (opens new window)etc/plugins/emqx_rule_engine.confRule engine
emqx_bridge_mqtt (opens new window)etc/plugins/emqx_bridge_mqtt.confMQTT Message Bridge Plugin
emqx_coap (opens new window)etc/plugins/emqx_coap.confCoAP protocol support
emqx_lwm2m (opens new window)etc/plugins/emqx_lwm2m.confLwM2M protocol support
emqx_sn (opens new window)etc/plugins/emqx_sn.confMQTT-SN protocol support
emqx_stomp (opens new window)etc/plugins/emqx_stomp.confStomp protocol support
emqx_recon (opens new window)etc/plugins/emqx_recon.confRecon performance debugging
emqx_plugin_template (opens new window)etc/plugins/emqx_plugin_template.confplugin develop template

# Start and stop plugin

There are four ways to load plugins:

  1. Default loading
  2. Start and stop plugin on command line
  3. Start and stop plugin on Dashboard
  4. Start and stop plugin by calling management API

Default loading

If a plugin needs to start with the broker, add this plugin in data/loaded_plugins.

For example, the plugins that are loaded by default are:

{emqx_management, true}.
{emqx_recon, true}.
{emqx_retainer, true}.
{emqx_dashboard, true}.
{emqx_rule_engine, true}.
{emqx_bridge_mqtt, false}.
1
2
3
4
5
6

Start and stop plugin on command line

When the EMQ X is running, plugins can be checked, loaded/unloaded by CLI - Load/Unload Plugin:

Start and stop plugin on Dashboard

If Dashboard plugin is started (by default), the plugins can be start or stopped by visiting the managing page that can be found under http://localhost:18083/plugins.

Start and stop plugins using management API

When EMQ X Broker is running, you can view, start and stop a plugin through Managing and Monitoring API - Load Plugin.

# Plugin development

# Create plugin project

Refer to the emqx_plugin_template (opens new window) plugin template to create a new plugin project.

Tip

The tag of-emqx_plugin (? MODULE)should be added to <plugin name>_app.erl file to indicate that this is an EMQ X Broker plugin.

# Create Authentication / Access Control Module

Authentication/Access sample code - emqx_auth_demo.erl

-module(emqx_auth_demo).

-export([ init/1
        , check/2
        , description/0
        ]).

init(Opts) -> {ok, Opts}.

check(_ClientInfo = #{clientid := ClientId, username := Username, password := Password}, _State) ->
    io:format("Auth Demo: clientId=~p, username=~p, password=~p~n", [ClientId, Username, Password]),
    ok.

description() -> "Auth Demo Module".
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Access control sample code - emqx_acl_demo.erl

-module(emqx_acl_demo).

-include_lib("emqx/include/emqx.hrl").

%% ACL callbacks
-export([ init/1
        , check_acl/5
        , reload_acl/1
        , description/0
        ]).

init(Opts) ->
    {ok, Opts}.

check_acl({ClientInfo, PubSub, _NoMatchAction, Topic}, _State) ->
    io:format("ACL Demo: ~p ~p ~p~n", [ClientInfo, PubSub, Topic]),
    allow.

reload_acl(_State) ->
    ok.

description() -> "ACL Demo Module".
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Example code for mounting authentication and access control hooks - emqx_plugin_template_app.erl

ok = emqx:hook('client.authenticate', fun emqx_auth_demo:check/2, []),
ok = emqx:hook('client.check_acl', fun emqx_acl_demo:check_acl/5, []).
1
2

# Load hook

During the plugin extension, you can load hooks to handle events such as client online and offline, topic subscription, and message sending and receiving.

Hook load sample code - emqx_plugin_template.erl

load(Env) ->
    emqx:hook('client.connect',      {?MODULE, on_client_connect, [Env]}),
    emqx:hook('client.connack',      {?MODULE, on_client_connack, [Env]}),
    emqx:hook('client.connected',    {?MODULE, on_client_connected, [Env]}),
    emqx:hook('client.disconnected', {?MODULE, on_client_disconnected, [Env]}),
    emqx:hook('client.authenticate', {?MODULE, on_client_authenticate, [Env]}),
    emqx:hook('client.check_acl',    {?MODULE, on_client_check_acl, [Env]}),
    emqx:hook('client.subscribe',    {?MODULE, on_client_subscribe, [Env]}),
    emqx:hook('client.unsubscribe',  {?MODULE, on_client_unsubscribe, [Env]}),
    emqx:hook('session.created',     {?MODULE, on_session_created, [Env]}),
    emqx:hook('session.subscribed',  {?MODULE, on_session_subscribed, [Env]}),
    emqx:hook('session.unsubscribed',{?MODULE, on_session_unsubscribed, [Env]}),
    emqx:hook('session.resumed',     {?MODULE, on_session_resumed, [Env]}),
    emqx:hook('session.discarded',   {?MODULE, on_session_discarded, [Env]}),
    emqx:hook('session.takeovered',  {?MODULE, on_session_takeovered, [Env]}),
    emqx:hook('session.terminated',  {?MODULE, on_session_terminated, [Env]}),
    emqx:hook('message.publish',     {?MODULE, on_message_publish, [Env]}),
    emqx:hook('message.delivered',   {?MODULE, on_message_delivered, [Env]}),
    emqx:hook('message.acked',       {?MODULE, on_message_acked, [Env]}),
    emqx:hook('message.dropped',     {?MODULE, on_message_dropped, [Env]}).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Register CLI commands

Processing command line sample code - emqx_cli_demo.erl

-module(emqx_cli_demo).

-export([cmd/1]).

cmd(["arg1", "arg2"]) ->
    emqx_cli:print ("ok");

cmd(_) ->
    emqx_cli:usage ([{"cmd arg1 arg2", "cmd demo"}]).
1
2
3
4
5
6
7
8
9

Register command line sample code - emqx_plugin_template_app.erl

ok = emqx_ctl:register_command(cmd, {emqx_cli_demo, cmd}, []),
1

After the plugin is loaded, use ./bin/emqx_ctl to verify the new command line:

./bin/emqx_ctl cmd arg1 arg2
1

# Plugin configuration file

Plug-in configuration files are placed in etc/${plugin_name}.conf|config. EMQ X Broker supports two plugin configuration formats:

  1. Erlang native configuration file format-${plugin_name}.config:
[
    {plugin_name, [
    {key, value}
    ]}
].
1
2
3
4
5
  1. Common format of k = v for sysctl-${plugin_name}.conf:
plugin_name.key = value
1

Tip

k = v format configuration requires the plugin developer to create priv/plugin_name.schema mapping file.

# Compile and publish the plugin

# clone emqx project

git clone https://github.com/emqx/emqx.git
1

Add plugin_name as a dependency by describing it in lib-extra/plugins:

{erlang_plugins,
   [ {plugin_name, {git, "url_of_plugin", {tag, "tag_of_plugin"}}}
   , ....
   ....
   ]
}
1
2
3
4
5
6

# Build a release

$ export EMQX_EXTRA_PLUGINS=plugin_name
$ make
1
2

# Run your code

Start the node (interactive mode)

./_build/emqx/rel/emqx/bin/emqx console
1

Load the plugin with the command:

./_build/emqx/rel/emqx/bin/emqx_ctl plugins load plugin_name
1

Tip

To have the plugin enabled/loaded by default, you can include it in data/loaded_plugins.tmpl.