配置说明(Configuration)

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

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

    +P

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

    +Q

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

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

    3. ## Cookie for distributed erlang
    4. -setcookie emqttdsecretcookie

    Note

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

    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.     {anonymous, []}
    23. ]},

    系统默认采用匿名认证(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. [{test1, "passwd1"}, {test2, "passwd2"}]

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

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

    ClientID认证

    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"]},
    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. ]},

    ‘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. ]},

    会话参数详细说明:

    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

    解除告警水位线

    队列满告警水位线

    queue_qos0

    是否缓存QoS0消息

    broker消息服务器参数

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

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

    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. ]},

    发布/订阅(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. ]}

    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参数说明:

    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
    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. {allow, all}.

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