插件

EMQX 发行包中,包含了大量的官方插件,提供了一些基础的、或各类扩展的功能。

它们依赖于 emqx插件介绍 - 图1 (opens new window) 的代码 API 或者 钩子 进行实现其特殊的功能。

然后通过打包编译工具 emqx-rel插件介绍 - 图2 (opens new window) 将其与 emqx插件介绍 - 图3 (opens new window) 核心项目一起编译并打包至一个可运行的软件包中。

提示

EMQX Enteprise 商业销售时不提供源代码,不支持客户自行开发、编译插件。

插件列表

目前 EMQX 发行包提供的插件包括:

插件配置文件说明
emqx_dashboard插件介绍 - 图4 (opens new window)etc/plugins/emqx_dashbord.confWeb 控制台插件 (默认加载)
emqx_management插件介绍 - 图5 (opens new window)etc/plugins/emqx_management.confHTTP API and CLI 管理插件
emqx_auth_mnesia插件介绍 - 图6 (opens new window)etc/plugins/emqx_auth_mnesia.confMnesia 认证 / 访问控制
emqx_auth_jwt插件介绍 - 图7 (opens new window)etc/plugins/emqx_auth_jwt.confJWT 认证 / 访问控制
emqx_auth_ldap插件介绍 - 图8 (opens new window)etc/plugins/emqx_auth_ldap.confLDAP 认证 / 访问控制
emqx_auth_http插件介绍 - 图9 (opens new window)etc/plugins/emqx_auth_http.confHTTP API 与 CLI 管理插件
emqx_auth_mongo插件介绍 - 图10 (opens new window)etc/plugins/emqx_auth_mongo.confMongoDB 认证 / 访问控制
emqx_auth_mysql插件介绍 - 图11 (opens new window)etc/plugins/emqx_auth_mysql.confMySQL 认证 / 访问控制
emqx_auth_pgsql插件介绍 - 图12 (opens new window)etc/plugins/emqx_auth_pgsql.confPostgreSQL 认证 / 访问控制
emqx_auth_redis插件介绍 - 图13 (opens new window)etc/plugins/emqx_auth_redis.confRedis 认证 / 访问控制
emqx_psk_file插件介绍 - 图14 (opens new window)etc/plugins/emqx_psk_file.confPSK 支持
emqx_web_hook插件介绍 - 图15 (opens new window)etc/plugins/emqx_web_hook.confWeb Hook 插件
emqx_lua_hook插件介绍 - 图16 (opens new window)etc/plugins/emqx_lua_hook.confLua Hook 插件
emqx_retainer插件介绍 - 图17 (opens new window)etc/plugins/emqx_retainer.confRetain 消息存储模块
emqx_rule_engine插件介绍 - 图18 (opens new window)etc/plugins/emqx_rule_engine.conf规则引擎
emqx_bridge_mqtt插件介绍 - 图19 (opens new window)etc/plugins/emqx_bridge_mqtt.confMQTT 消息桥接插件
emqx_coap插件介绍 - 图20 (opens new window)etc/plugins/emqx_coap.confCoAP 协议支持
emqx_lwm2m插件介绍 - 图21 (opens new window)etc/plugins/emqx_lwm2m.confLwM2M 协议支持
emqx_sn插件介绍 - 图22 (opens new window)etc/plugins/emqx_sn.confMQTT-SN 协议支持
emqx_stomp插件介绍 - 图23 (opens new window)etc/plugins/emqx_stomp.confStomp 协议支持
emqx_recon插件介绍 - 图24 (opens new window)etc/plugins/emqx_recon.confRecon 性能调试
emqx_plugin_template插件介绍 - 图25 (opens new window)etc/plugins/emqx_plugin_template.conf代码热加载插件

启停插件

目前启动插件有以下四种方式:

  1. 默认加载
  2. 命令行启停插件
  3. 使用 Dashboard 启停插件
  4. 调用管理 API 启停插件

开启默认加载

如需在 EMQX 启动时就默认启动某插件,则直接在 data/loaded_plugins 添加需要启动的插件名称。

例如,目前 EMQX 自动加载的插件有:

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

命令行启停插件

在 EMQX 运行过程中,可通过 CLI - Load/Unload Plugin 的方式查看、和启停某插件。

使用 Dashboard 启停插件

若开启了 Dashboard 的插件,可以直接通过访问 http://localhost:18083/plugins 中的插件管理页面启停插件。

使用管理 API 启停插件

在 EMQX 运行过程中,可通过 管理监控 API - Load Plugin 的方式查看、和启停某插件。

插件开发

创建插件项目

参考 emqx_plugin_template插件介绍 - 图26 (opens new window) 插件模版创建新的插件项目。

备注:在 <plugin name>_app.erl 文件中必须加上标签 -emqx_plugin(?MODULE). 以表明这是一个 EMQX 的插件。

创建 认证/访问控制 模块

接入认证示例代码 - emqx_auth_demo.erl

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

访问控制示例代码 - emqx_acl_demo.erl

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

挂载认证、访问控制钩子示例代码 - 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, []).

挂载钩子

在扩展插件中,可通过挂载 钩子 来处理客户端上下线、主题订阅、消息收发等事件。

钩子挂载示例代码 - 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.subscribe', {?MODULE, on_client_subscribe, [Env]}),
  9. emqx:hook('client.unsubscribe', {?MODULE, on_client_unsubscribe, [Env]}),
  10. emqx:hook('session.created', {?MODULE, on_session_created, [Env]}),
  11. emqx:hook('session.subscribed', {?MODULE, on_session_subscribed, [Env]}),
  12. emqx:hook('session.unsubscribed',{?MODULE, on_session_unsubscribed, [Env]}),
  13. emqx:hook('session.resumed', {?MODULE, on_session_resumed, [Env]}),
  14. emqx:hook('session.discarded', {?MODULE, on_session_discarded, [Env]}),
  15. emqx:hook('session.takeovered', {?MODULE, on_session_takeovered, [Env]}),
  16. emqx:hook('session.terminated', {?MODULE, on_session_terminated, [Env]}),
  17. emqx:hook('message.publish', {?MODULE, on_message_publish, [Env]}),
  18. emqx:hook('message.delivered', {?MODULE, on_message_delivered, [Env]}),
  19. emqx:hook('message.acked', {?MODULE, on_message_acked, [Env]}),
  20. emqx:hook('message.dropped', {?MODULE, on_message_dropped, [Env]}).

注册 CLI 命令

处理命令行命令示例代码 - emqx_cli_demo.erl

  1. -module(emqx_cli_demo).
  2. -export([cmd/1]).
  3. cmd(["arg1", "arg2"]) ->
  4. emqx_cli:print ("ok");
  5. cmd(_) ->
  6. emqx_cli:usage ([{"cmd arg1 arg2", "cmd demo"}]).

注册命令行示例代码 - emqx_plugin_template_app.erl

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

插件加载后,使用./bin/emqx_ctl 验证新增的命令行:

  1. ./bin/emqx_ctl cmd arg1 arg2

插件配置文件

插件自带配置文件放置在 etc/${plugin_name}.conf|config。 EMQX 支持两种插件配置格式:

  1. Erlang 原生配置文件格式 - ${plugin_name}.config
  1. [
  2. {plugin_name, [
  3. {key, value}
  4. ]}
  5. ].
  1. sysctl 的 k = v 通用格式 - ${plugin_name}.conf
  1. plugin_name.key = value

注:k = v 格式配置需要插件开发者创建 priv/plugin_name.schema 映射文件。

编译和发布插件

clone emqx-rel 项目:

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

rebar.config 添加依赖:

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

rebar.config 中 relx 段落添加:

  1. {relx,
  2. [...
  3. , ...
  4. , {release, {emqx, git_describe},
  5. [
  6. {plugin_name, load},
  7. ]
  8. }
  9. ]
  10. }