Plugins

    They rely on the code API of or hooks for their special functions.

    You can compile it with the 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.

    The official plug-ins provided by EMQ X include:

    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 .

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

    Start and stop plugin on command line

    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.

    Refer to the 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：

    1. -module(emqx_auth_demo).
    3. -export([ init/1
    4.         , check/2
    5.         , description/0
    6.         ]).
    8. init(Opts) -> {ok, Opts}.
    10. check(_ClientInfo = #{clientid := ClientId, username := Username, password := Password}, _State) ->
    11.     io:format("Auth Demo: clientId=~p, username=~p, password=~p~n", [ClientId, Username, Password]),
    12.     ok.
    14. description() -> "Auth Demo Module".

    Access control sample code - emqx_acl_demo.erl：

    2. -include_lib("emqx/include/emqx.hrl").
    4. %% ACL callbacks
    5. -export([ init/1
    6.         , check_acl/5
    7.         , reload_acl/1
    8.         , description/0
    9.         ]).
    11. init(Opts) ->
    14. check_acl({ClientInfo, PubSub, _NoMatchAction, Topic}, _State) ->
    15.     io:format("ACL Demo: ~p ~p ~p~n", [ClientInfo, PubSub, Topic]),
    16.     allow.
    18. reload_acl(_State) ->
    19.     ok.
    21. description() -> "ACL Demo Module".

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

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

    Hook load sample code - emqx_plugin_template.erl：

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

    Register CLI commands

    Processing command line sample code - emqx_cli_demo.erl：

    Register command line sample code - emqx_plugin_template_app.erl：

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

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

    1. ./bin/emqx_ctl cmd arg1 arg2

    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:
    1. [
    2.     {plugin_name, [
    3.     {key, value}
    4.     ]}
    5. ].
    1. Common format of k = v for sysctl-${plugin_name}.conf:
    1. plugin_name.key = value

    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

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

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

    Build a release

    1. $ export EMQX_EXTRA_PLUGINS=plugin_name
    2. $ make

    Run your code

    Start the node (interactive mode)

      Load the plugin with the command:

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

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