配置说明(Configuration)

emqttd消息服务器通过etc/目录下配置文件进行设置，主要配置文件包括:

配置文件

说明

etc/vm.args

Erlang 虚拟机的参数设置

etc/emqttd.config

emqttd消息服务器参数设置

etc/acl.config

ACL(访问控制规则)设置

etc/clients.config

基于ClientId认证设置

etc/rewrite.config

Rewrite扩展模块规则配置

etc/ssl/*

SSL证书设置

etc/vm.args

etc/vm.args文件设置Erlang虚拟机参数:

  1. ##-------------------------------------------------------------------------
  2. ## Name of the node
  3. ##-------------------------------------------------------------------------
  4. -name emqttd@127.0.0.1
  6. ## Cookie for distributed erlang
  7. -setcookie emqttdsecretcookie
  9. ##-------------------------------------------------------------------------
  10. ## Flags
  11. ##-------------------------------------------------------------------------
  13. ## Heartbeat management; auto-restarts VM if it dies or becomes unresponsive
  14. ## (Disabled by default..use with caution!)
  15. ##-heart
  16. -smp true
  18. ## Enable kernel poll and a few async threads
  19. +K true
  21. ## 12 threads/core.
  22. +A 48
  24. ## max process numbers
  25. +P 8192
  27. ## Sets the maximum number of simultaneously existing ports for this system
  28. +Q 8192
  30. ## max atom number
  31. ## +t
  33. ## Set the distribution buffer busy limit (dist_buf_busy_limit) in kilobytes.
  34. ## Valid range is 1-2097151. Default is 1024.
  35. ## +zdbbl 8192
  37. ## CPU Schedulers
  38. ## +sbt db
  40. ##-------------------------------------------------------------------------
  41. ## Env
  42. ##-------------------------------------------------------------------------
  44. ## Increase number of concurrent ports/sockets, deprecated in R17
  45. -env ERL_MAX_PORTS 8192
  47. -env ERTS_MAX_PORTS 8192
  49. -env ERL_MAX_ETS_TABLES 1024
  51. ## Tweak GC to run more often
  52. -env ERL_FULLSWEEP_AFTER 1000

etc/vm.args中两个最重要的参数:

+P

Erlang虚拟机允许的最大进程数，一个MQTT连接会消耗2个Erlang进程，所以参数值 > 最大连接数 * 2

+Q

Erlang虚拟机允许的最大Port数量，一个MQTT连接消耗1个Port，所以参数值 > 最大连接数

etc/vm.args设置Erlang节点名、节点间通信Cookie:

  1. -name emqttd@127.0.0.1
  3. ## Cookie for distributed erlang
  4. -setcookie emqttdsecretcookie

Note

Erlang/OTP平台应用多由分布的Erlang节点(进程)组成，每个Erlang节点(进程)需指配一个节点名，用于节点间通信互访。 所有互相通信的Erlang节点(进程)间通过一个共用的Cookie进行安全认证。

etc/emqttd.config

etc/emqttd.config是消息服务器的核心配置文件。Erlang程序由多个应用(application)组成，每个应用(application)有自身的环境参数，

启动时候通过etc/emqttd.config文件加载。

etc/emqttd.config文件采用的是Erlang数据格式，kernel, sasl, emqttd是Erlang应用(application)名称，’[]’内是应用的环境参数列表。

  1. [{kernel, [
  2.     {start_timer, true},
  3.     {start_pg2, true}
  4.  ]},
  5.  {sasl, [
  6.     {sasl_error_logger, {file, "log/emqttd_sasl.log"}}
  7.  ]},
  9.  ...
  11.  {emqttd, [
  12.     ...
  13.  ]}
  14. ].

emqttd.config格式简要说明:

  1. [ ] : 列表，逗号分隔元素

  2. { } : 元组，配置元组一般两个元素{Env, Value}

  3. % : 注释

日志级别设置

emqttd消息服务器日志由lager应用(application)提供，日志相关设置在lager应用段落:

  1. {lager, [
  2.   ...
  3. ]},

产品环境下默认只开启error日志，日志输出到logs/emqttd_error.log文件。’handlers’段落启用其他级别日志:

  1. {handlers, [
  2.     {lager_console_backend, info},
  4.     {lager_file_backend, [
  5.         {formatter_config, [time, " ", pid, " [",severity,"] ", message, "\n"]},
  6.         {file, "log/emqttd_info.log"},
  7.         {level, info},
  8.         {size, 104857600},
  9.         {date, "$D0"},
  10.         {count, 30}
  11.     ]},
  13.     {lager_file_backend, [
  14.         {formatter_config, [time, " ", pid, " [",severity,"] ", message, "\n"]},
  15.         {file, "log/emqttd_error.log"},
  16.         {level, error},
  17.         {size, 104857600},
  18.         {date, "$D0"},
  19.         {count, 30}
  20.     ]}
  21. ]}

Warning

过多日志打印严重影响服务器性能，产品环境下建议开启error级别日志。

消息服务器参数配置

emqttd消息服务器参数设置在emqttd应用段落，包括用户认证与访问控制设置，MQTT协议、会话、队列设置，扩展模块设置，TCP服务监听器设置:

  1. {emqttd, [
  2.    %% 用户认证与访问控制设置
  3.    {access, [
  4.        ...
  5.    ]},
  6.    %% MQTT连接、协议、会话、队列设置
  7.    {mqtt, [
  8.        ...
  9.    ]},
  10.    %% 消息服务器设置
  11.    {broker, [
  12.        ...
  13.    ]},
  14.    %% 扩展模块设置
  15.    {modules, [
  16.        ...
  17.    ]},
  18.    %% 插件目录设置
  19.    {plugins, [
  20.        ...
  21.    ]},
  23.    %% TCP监听器设置
  24.    {listeners, [
  25.        ...
  26.    ]},
  28.    %% Erlang虚拟机监控设置
  29.    {sysmon, [
  30.    ]}
  31. ]}

access用户认证设置

emqttd消息服务器认证由一系列认证模块(module)或插件(plugin)提供，系统默认支持用户名、ClientID、LDAP、匿名(anonymouse)认证模块:

  1. %% Authetication. Anonymous Default
  2. {auth, [
  3.     %% Authentication with username, password
  4.     %% Add users: ./bin/emqttd_ctl users add Username Password
  5.     %% {username, [{"test", "public"}]},
  7.     %% Authentication with clientid
  8.     % {clientid, [{password, no}, {file, "etc/clients.config"}]},
  10.     %% Authentication with LDAP
  11.     % {ldap, [
  12.     %    {servers, ["localhost"]},
  13.     %    {port, 389},
  14.     %    {timeout, 30},
  15.     %    {user_dn, "uid=$u,ou=People,dc=example,dc=com"},
  16.     %    {ssl, fasle},
  17.     %    {sslopts, [
  18.     %        {"certfile", "ssl.crt"},
  19.     %        {"keyfile", "ssl.key"}]}
  20.     % ]},
  22.     %% Allow all
  23.     {anonymous, []}
  24. ]},

系统默认采用匿名认证(anonymous)，通过删除注释可开启其他认证方式。同时开启的多个认证模块组成认证链:

  1.            ----------------           ----------------           ------------
  2. Client --> | Username认证 | -ignore-> | ClientID认证 | -ignore-> | 匿名认证 |
  3.            ----------------           ----------------           ------------
  4.                   |                         |                         |
  5.                  \|/                       \|/                       \|/
  6.             allow | deny              allow | deny              allow | deny

Note

emqttd消息服务器还提供了MySQL、PostgreSQL、Redis、MongoDB认证插件， 认证插件加载后认证模块失效。

用户名密码认证

  1. {username, [{test1, "passwd1"}, {test2, "passwd2"}]},

两种方式添加用户:

  1. 直接在[]中明文配置默认用户:

    1. [{test1, "passwd1"}, {test2, "passwd2"}]

  2. 通过’./bin/emqttd_ctl’管理命令行添加用户:

    1. $ ./bin/emqttd_ctl users add <Username> <Password>

ClientID认证

  1. {clientid, [{password, no}, {file, "etc/clients.config"}]},

etc/clients.config文件中添加ClientID:

  1. testclientid0
  2. testclientid1 127.0.0.1
  3. testclientid2 192.168.0.1/24

LDAP认证

  1. {ldap, [
  2.    {servers, ["localhost"]},
  3.    {port, 389},
  4.    {timeout, 30},
  5.    {user_dn, "uid=$u,ou=People,dc=example,dc=com"},
  6.    {ssl, fasle},
  7.    {sslopts, [
  8.        {certfile, "ssl.crt"},
  9.        {keyfile, "ssl.key"}]}
  10. ]},

匿名认证

默认开启。允许任意客户端登录:

  1. {anonymous, []}

access用户访问控制(ACL)

emqttd消息服务器支持基于etc/acl.config文件或MySQL、PostgreSQL插件的访问控制规则。

默认开启基于etc/acl.config文件的访问控制:

  1. %% ACL config
  2. {acl, [
  3.     %% Internal ACL module
  4.     {internal,  [{file, "etc/acl.config"}, {nomatch, allow}]}
  5. ]}

etc/acl.config访问控制规则定义:

  1. 允许|拒绝  用户|IP地址|ClientID  发布|订阅  主题列表

etc/acl.config默认访问规则设置:

  1. {allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.
  3. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.
  5. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.
  7. {allow, all}.

Note

默认规则只允许本机用户订阅’$SYS/#’与’#’

emqttd消息服务器接收到MQTT客户端发布(PUBLISH)或订阅(SUBSCRIBE)请求时，会逐条匹配ACL访问控制规则，

直到匹配成功返回allow或deny。

MQTT报文(Packet)尺寸与ClientID长度限制

packet 段落设置最大报文尺寸、最大客户端ID长度:

  1. {packet, [
  3.     %% ClientID长度, 默认1024
  4.     {max_clientid_len, 1024},
  6.     %% 最大报文长度，默认64K
  7.     {max_packet_size,  65536}
  8. ]},

MQTT客户端(Client)连接闲置时间

‘client’段落设置客户端最大允许闲置时间(Socket连接建立，但未发送CONNECT报文):

  1. {client, [
  2.     %% 单位: 秒
  3.     {idle_timeout, 10}
  4. ]},

MQTT会话(Session)参数设置

‘session’段落设置MQTT会话参数:

  1. {session, [
  2.     %% Max number of QoS 1 and 2 messages that can be “in flight” at one time.
  3.     %% 0 means no limit
  4.     {max_inflight, 100},
  6.     %% Retry interval for redelivering QoS1/2 messages.
  7.     {unack_retry_interval, 20},
  9.     %% Awaiting PUBREL Timeout
  10.     {await_rel_timeout, 20},
  12.     %% Max Packets that Awaiting PUBREL, 0 means no limit
  13.     {max_awaiting_rel, 0},
  15.     %% Statistics Collection Interval(seconds)
  16.     {collect_interval, 20},
  18.     %% Expired after 2 day (unit: minute)
  19.     {expired_after, 2880}
  21. ]},

会话参数详细说明:

max_inflight

飞行窗口。最大允许同时下发的Qos1/2报文数，0表示没有限制。 窗口值越大，吞吐越高；窗口值越小，消息顺序越严格

unack_retry_interval

下发QoS1/2消息未收到PUBACK响应的重试间隔

await_rel_timeout

收到QoS2消息，等待PUBREL报文超时时间

max_awaiting_rel

最大等待PUBREL的QoS2报文数

collect_interval

采集会话统计数据间隔，默认0表示关闭统计

expired_after

持久会话到期时间，从客户端断开算起，单位：分钟

MQTT会话消息队列(MQueue)设置

emqttd消息服务器会话通过队列缓存Qos1/Qos2消息:

  1. 持久会话(Session)的离线消息

  2. 飞行窗口满而延迟下发的消息

队列参数设置:

  1. {queue, [
  2.     %% simple | priority
  3.     {type, simple},
  5.     %% Topic Priority: 0~255, Default is 0
  6.     %% {priority, [{"topic/1", 10}, {"topic/2", 8}]},
  8.     %% Max queue length. Enqueued messages when persistent client disconnected,
  9.     %% or inflight window is full.
  10.     {max_length, infinity},
  12.     %% Low-water mark of queued messages
  13.     {low_watermark, 0.2},
  15.     %% High-water mark of queued messages
  16.     {high_watermark, 0.6},
  18.     %% Queue Qos0 messages?
  19.     {queue_qos0, true}
  20. ]}

队列参数说明:

type

队列类型。simple: 简单队列，priority: 优先级队列

priority

主题(Topic)队列优先级设置

max_length

队列长度, infinity表示不限制

low_watermark

解除告警水位线

high_watermark

队列满告警水位线

queue_qos0

是否缓存QoS0消息

broker消息服务器参数

‘broker’段落设置消息服务器内部模块参数。

sys_interval设置系统发布$SYS消息周期:

  1. {sys_interval, 60},

broker retained消息设置

retained设置MQTT retain消息处理参数:

  1. {retained, [
  2.     %% retain消息过期时间，单位: 秒
  3.     {expired_after, 0},
  5.     %% 最大retain消息数量
  6.     {max_message_num, 100000},
  8.     %% retain消息payload最大尺寸
  9.     {max_playload_size, 65536}
  10. ]},

expired_after

Retained消息过期时间，0表示永不过期

max_message_num

最大存储的Retained消息数量

max_packet_size

Retained消息payload最大允许尺寸

broker pubsub路由设置

发布/订阅(Pub/Sub)路由模块参数:

  1. {pubsub, [
  2.     %% PubSub Erlang进程池
  3.     {pool_size, 8},
  5.     %% 订阅存储类型，true: 存储, false: 不存储
  6.     {subscription, true},
  8.     %% 路由老化时间
  9.     {route_aging, 5}
  10. ]},

broker bridge桥接参数

桥接参数设置:

  1. {bridge, [
  2.     %% 最大缓存桥接消息数
  3.     {max_queue_len, 10000},
  5.     %% 桥接节点宕机检测周期，单位: 秒
  6.     {ping_down_interval, 1}
  7. ]}

modules扩展模块设置

emqtt消息服务器支持简单的扩展模块，用于定制服务器功能。默认支持presence、subscription、rewrite模块。

‘presence’扩展模块会向$SYS主题(Topic)发布客户端上下线消息:

  1. {presence, [{qos, 0}]},

‘subscription’扩展模块支持客户端上线时，自动订阅或恢复订阅某些主题(Topic):

  1. %% Subscribe topics automatically when client connected
  2. {subscription, [
  3.     %% Subscription from stored table
  4.     stored,
  6.     %% $u will be replaced with username
  7.     {"$Q/username/$u", 1},
  9.     %% $c will be replaced with clientid
  10.     {"$Q/client/$c", 1}
  11. ]}

‘rewrite’扩展模块支持重写主题(Topic)路径, 重写规则定义在etc/rewrite.config文件:

  1. %% Rewrite rules
  2. %% {rewrite, [{file, "etc/rewrite.config"}]}

关于扩展模块详细介绍，请参考<用户指南>文档。

plugins插件目录设置

  1. {plugins, [
  2.     %% Plugin App Library Dir
  3.     {plugins_dir, "./plugins"},
  5.     %% File to store loaded plugin names.
  6.     {loaded_file, "./data/loaded_plugins"}
  7. ]},

listeners监听器设置

emqttd消息服务器开启的MQTT协议、HTTP协议服务端，可通过listener设置TCP服务端口、最大允许连接数等参数。

emqttd消息服务器默认开启的TCP服务端口包括:

1883

MQTT协议端口

8883

MQTT(SSL)端口

8083

MQTT(WebSocket), HTTP API端口

  1. {listeners, [
  3.     {mqtt, 1883, [
  4.         %% Size of acceptor pool
  5.         {acceptors, 16},
  7.         %% Maximum number of concurrent clients
  8.         {max_clients, 8192},
  10.         %% Socket Access Control
  11.         {access, [{allow, all}]},
  13.         %% Connection Options
  14.         {connopts, [
  15.             %% Rate Limit. Format is 'burst, rate', Unit is KB/Sec
  16.             %% {rate_limit, "100,10"} %% 100K burst, 10K rate
  17.         ]},
  19.         %% Socket Options
  20.         {sockopts, [
  21.             %Set buffer if hight thoughtput
  22.             %{recbuf, 4096},
  23.             %{sndbuf, 4096},
  24.             %{buffer, 4096},
  25.             %{nodelay, true},
  26.             {backlog, 1024}
  27.         ]}
  28.     ]},
  30.     {mqtts, 8883, [
  31.         %% Size of acceptor pool
  32.         {acceptors, 4},
  34.         %% Maximum number of concurrent clients
  35.         {max_clients, 512},
  37.         %% Socket Access Control
  38.         {access, [{allow, all}]},
  40.         %% SSL certificate and key files
  41.         {ssl, [{certfile, "etc/ssl/ssl.crt"},
  42.                {keyfile,  "etc/ssl/ssl.key"}]},
  44.         %% Socket Options
  45.         {sockopts, [
  46.             {backlog, 1024}
  47.             %{buffer, 4096},
  48.         ]}
  49.     ]},
  50.     %% WebSocket over HTTPS Listener
  51.     %% {https, 8083, [
  52.     %%  %% Size of acceptor pool
  53.     %%  {acceptors, 4},
  54.     %%  %% Maximum number of concurrent clients
  55.     %%  {max_clients, 512},
  56.     %%  %% Socket Access Control
  57.     %%  {access, [{allow, all}]},
  58.     %%  %% SSL certificate and key files
  59.     %%  {ssl, [{certfile, "etc/ssl/ssl.crt"},
  60.     %%         {keyfile,  "etc/ssl/ssl.key"}]},
  61.     %%  %% Socket Options
  62.     %%  {sockopts, [
  63.     %%      %{buffer, 4096},
  64.     %%      {backlog, 1024}
  65.     %%  ]}
  66.     %%]},
  68.     %% HTTP and WebSocket Listener
  69.     {http, 8083, [
  70.         %% Size of acceptor pool
  71.         {acceptors, 4},
  72.         %% Maximum number of concurrent clients
  73.         {max_clients, 64},
  74.         %% Socket Access Control
  75.         {access, [{allow, all}]},
  76.         %% Socket Options
  77.         {sockopts, [
  78.             {backlog, 1024}
  79.             %{buffer, 4096},
  80.         ]}
  81.     ]}
  82. ]},

listener参数说明:

acceptors

TCP Acceptor池

max_clients

最大允许TCP连接数

access

允许访问的IP地址段设置，例如: [{allow, “192.168.1.0/24”}]

connopts

连接限速配置，例如限速10KB/秒: {rate_limit, “100,10”}

sockopts

Socket参数设置

etc/acl.config

emqttd消息服务器默认访问控制规则配置在etc/acl.config文件。

访问控制规则采用Erlang元组格式，访问控制模块逐条匹配规则:

  1.           ---------              ---------              ---------
  2. Client -> | Rule1 | --nomatch--> | Rule2 | --nomatch--> | Rule3 | --> Default
  3.           ---------              ---------              ---------
  4.               |                      |                      |
  5.             match                  match                  match
  6.              \|/                    \|/                    \|/
  7.         allow | deny           allow | deny           allow | deny

etc/acl.config文件默认规则设置:

  1. %% 允许'dashboard'用户订阅 '$SYS/#'
  2. {allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.
  4. %% 允许本机用户发布订阅全部主题
  5. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.
  7. %% 拒绝用户订阅'$SYS#'与'#'主题
  8. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.
  10. %% 上述规则无匹配，允许
  11. {allow, all}.

etc/rewrite.config

Rewrite扩展模块的规则配置文件，示例配置:

  1. {topic, "x/#", [
  2.     {rewrite, "^x/y/(.+)$", "z/y/$1"},
  3.     {rewrite, "^x/(.+)$", "y/$1"}
  4. ]}.
  6. {topic, "y/+/z/#", [
  7.     {rewrite, "^y/(.+)/z/(.+)$", "y/z/$2"}
  8. ]}.