配置说明 (Configuration)

    EMQ 配置变更历史

    为方便用户与插件开发者使用，EMQ 配置文件经过三次调整。

    1. EMQ 1.x 版本采用 Erlang 原生配置文件格式 etc/emqttd.config:

    Erlang 的原生配置格式多层级嵌套，对非 Erlang 开发者的用户很不友好。

    1. EMQ 2.0-beta.x 版本简化了原生 Erlang 配置文件，采用类似 rebar.config 或 relx.config 格式:
    2. {mqtt_max_clientid_len, 512}.
    4. %% Max Packet Size Allowed, 64K by default.
    5. {mqtt_max_packet_size, 65536}.
    7. %% Client Idle Timeout.
    8. {mqtt_client_idle_timeout, 30}. % Second

    简化后的 Erlang 原生配置格式方便用户配置，但插件开发者不得不依赖 gen_conf 库，而不是通过 appliaton:get_env 读取配置参数。

    1. EMQ 2.0-rc.2 正式版集成了 cuttlefish 库，采用了类似 sysctl 的 k = v 通用格式，并在系统启动时翻译成 Erlang 原生配置格式:
    1. ## Node name
    2. node.name = emqttd@127.0.0.1
    3. ...
    4. ## Max ClientId Length Allowed.
    5. mqtt.max_clientid_len = 1024
    6. ...

    EMQ 2.0 启动时配置文件处理流程:

    1. ----------------------                                          2.0/schema/*.schema      -------------------
    2. | etc/emq.conf       |                   -----------------              \|/              | data/app.config |
    3. |       +            | --> mergeconf --> | data/app.conf | -->  cuttlefish generate  --> |                 |
    4. | etc/plugins/*.conf |                   -----------------                               | data/vm.args    |
    5. ----------------------                                                                   -------------------

    EMQ 2.2 环境变量

    EMQ_NODE_NAME

    Erlang 节点名称，例如:

    EMQ_NODE_COOKIE

    Erlang 分布式节点通信 Cookie

    EMQ_MAX_PORTS

    Erlang 虚拟机最大允许打开文件 Socket 数

    EMQ_TCP_PORT

    MQTT/TCP 监听端口，默认: 1883

    EMQ_SSL_PORT

    MQTT/SSL 监听端口，默认: 8883

    EMQ_WS_PORT

    MQTT/WebSocket 监听端口，默认: 8083

    EMQ_WSS_PORT

    MQTT/WebSocket/SSL 监听端口，默认: 8084

    EMQ 集群设置

    1. ## Cluster name
    2. cluster.name = emqcl

    自动发现策略

    1. ## Cluster discovery strategy: manual | static | mcast | dns | etcd | k8s
    2. cluster.discovery = manual

    启用集群自愈

    1. ## Cluster Autoheal: on | off
    2. cluster.autoheal = on

    节点自动清除

    自动清除宕机节点:

    1. ## Clean down node of the cluster
    2. cluster.autoclean = 5m

    EMQ 集群自动发现

    EMQ R2.3 版本支持多种策略的节点自动发现与集群:

    manual 手动创建集群

    默认配置为手动创建集群，节点通过 ./bin/emqttd_ctl join <Node> 命令加入:

    1. cluster.discovery = manual

    基于 static 节点列表自动集群

    配置固定的节点列表，自动发现并创建集群:

    1. cluster.discovery = static
    3. ##--------------------------------------------------------------------
    4. ## Cluster with static node list
    6. cluster.static.seeds = emq1@127.0.0.1,ekka2@127.0.0.1

    基于 mcast 组播自动集群

    基于 UDP 组播自动发现并创建集群:

    1. cluster.discovery = mcast
    3. ##--------------------------------------------------------------------
    4. ## Cluster with multicast
    6. cluster.mcast.addr = 239.192.0.1
    8. cluster.mcast.ports = 4369,4370
    10. cluster.mcast.iface = 0.0.0.0
    12. cluster.mcast.ttl = 255
    14. cluster.mcast.loop = on

    基于 DNS A 记录自动发现并创建集群:

    1. cluster.discovery = dns
    3. ##--------------------------------------------------------------------
    4. ## Cluster with DNS
    6. cluster.dns.name = localhost
    8. cluster.dns.app  = ekka

    基于 etcd 自动集群

    基于 `etcd`_ 自动发现并创建集群:

    1. cluster.discovery = etcd
    3. ##--------------------------------------------------------------------
    4. ## Cluster with Etcd
    6. cluster.etcd.server = http://127.0.0.1:2379
    8. cluster.etcd.prefix = emqcl
    10. cluster.etcd.node_ttl = 1m

    基于 Kubernetes 自动集群

    下自动发现并创建集群:

    1. cluster.discovery = k8s
    3. ##--------------------------------------------------------------------
    4. ## Cluster with k8s
    6. cluster.k8s.apiserver = http://10.110.111.204:8080
    8. cluster.k8s.service_name = ekka
    10. ## Address Type: ip | dns
    11. cluster.k8s.address_type = ip
    13. ## The Erlang application name
    14. cluster.k8s.app_name = ekka

    EMQ 节点与 Cookie

    Erlang 节点名称、分布式节点间通信 Cookie:

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

    EMQ 节点连接方式

    EMQ 节点基于 Erlang/OTP 平台的 TCPv4, TCPv6 或 TLS 协议连接:

    1. ## Specify the erlang distributed protocol.
    2. ##
    3. ## Value: Enum
    4. ##  - inet_tcp: the default; handles TCP streams with IPv4 addressing.
    5. ##  - inet6_tcp: handles TCP with IPv6 addressing.
    6. ##  - inet_tls: using TLS for Erlang Distribution.
    7. ##
    8. ## vm.args: -proto_dist inet_tcp
    9. node.proto_dist = inet_tcp
    11. ## Specify SSL Options in the file if using SSL for Erlang Distribution.
    12. ##
    13. ## Value: File
    14. ##
    15. ## vm.args: -ssl_dist_optfile <File>

    Erlang 虚拟机参数

    1. ## SMP support: enable, auto, disable
    2. node.smp = auto
    4. ## Enable kernel poll
    5. node.kernel_poll = on
    7. ## async thread pool
    8. node.async_threads = 32
    10. ## Erlang Process Limit
    11. node.process_limit = 256000
    13. ## Sets the maximum number of simultaneously existing ports for this system
    14. node.max_ports = 65536
    16. ## Set the distribution buffer busy limit (dist_buf_busy_limit)
    17. node.dist_buffer_size = 32MB
    19. ## Max ETS Tables.
    20. ## Note that mnesia and SSL will create temporary ets tables.
    21. node.max_ets_tables = 256000
    23. ## Tweak GC to run more often
    24. node.fullsweep_after = 1000
    26. ## Crash dump
    27. node.crash_dump = log/crash.dump
    29. ## Distributed node ticktime
    30. node.dist_net_ticktime = 60
    32. ## Distributed node port range
    34. ## node.dist_listen_max = 6999

    Erlang 虚拟机主要参数说明:

    node.process_limit

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

    node.max_ports

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

    node.dist_listen_min

    Erlang 分布节点间通信使用 TCP 连接端口范围。注: 节点间如有防火墙，需要配置该端口段

    node.dist_listen_max

    Erlang 分布节点间通信使用 TCP 连接端口范围。注: 节点间如有防火墙，需要配置该端口段

    console 日志

    1. ## Console log. Enum: off, file, console, both
    2. log.console = console
    4. ## Console log level. Enum: debug, info, notice, warning, error, critical, alert, emergency
    5. log.console.level = error
    7. ## Console log file
    8. ## log.console.file = log/console.log

    error 日志

    1. ## Error log file
    2. log.error.file = log/error.log

    crash 日志

    1. ## Enable the crash log. Enum: on, off
    2. log.crash = on
    4. log.crash.file = log/crash.log

    syslog 日志

    1. ## Syslog. Enum: on, off
    2. log.syslog = on
    4. ##  syslog level. Enum: debug, info, notice, warning, error, critical, alert, emergency
    5. log.syslog.level = error

    MQTT 协议参数配置

    1. ## Max ClientId Length Allowed.
    2. mqtt.max_clientid_len = 1024

    MQTT 最大报文尺寸

    1. ## Max Packet Size Allowed, 64K by default.
    2. mqtt.max_packet_size = 64KB

    客户端连接闲置时间

    设置 MQTT 客户端最大允许闲置时间(Socket 连接建立，但未收到 CONNECT 报文):

    1. ## Client Idle Timeout (Second)
    2. mqtt.client.idle_timeout = 30

    启用客户端连接统计

    1. ## Enable client Stats: on | off
    2. mqtt.client.enable_stats = off

    强制 GC 设置

    1. ## Force GC: integer. Value 0 disabled the Force GC.
    2. mqtt.conn.force_gc_count = 100

    匿名认证与 ACL 文件

    是否开启匿名认证

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

    1. ## Allow Anonymous authentication
    2. mqtt.allow_anonymous = true

    默认访问控制(ACL)文件

    EMQ 支持基于 etc/acl.conf 文件或 MySQL、 PostgreSQL 等插件的访问控制规则。

    1. ## ACL nomatch
    2. mqtt.acl_nomatch = allow
    4. ## Default ACL File
    5. mqtt.acl_file = etc/acl.conf

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

    访问控制规则采用 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.conf 默认访问规则设置:

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

    注解

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

    EMQ 消息服务器接收到 MQTT 客户端发布(PUBLISH)或订阅(SUBSCRIBE)请求时，会逐条匹配 ACL 访问控制规则，直到匹配成功返回 allow 或 deny。

    MQTT 会话参数设置

    1. ## Upgrade QoS?
    2. mqtt.session.upgrade_qos = off
    4. ## Max number of QoS 1 and 2 messages that can be “inflight” at one time.
    5. ## 0 means no limit
    6. mqtt.session.max_inflight = 32
    8. ## Retry Interval for redelivering QoS1/2 messages.
    9. mqtt.session.retry_interval = 20s
    11. ## Max Packets that Awaiting PUBREL, 0 means no limit
    12. mqtt.session.max_awaiting_rel = 100
    14. ## Awaiting PUBREL Timeout
    15. mqtt.session.await_rel_timeout = 20s
    17. ## Enable Statistics: on | off
    18. mqtt.session.enable_stats = off
    20. ## Expired after 1 day:
    21. ## w - week
    22. ## d - day
    23. ## h - hour
    24. ## m - minute
    25. ## s - second
    26. mqtt.session.expiry_interval = 2h

    MQTT 消息队列参数设置

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

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

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

    队列参数设置:

    1. ## Type: simple | priority
    2. mqtt.mqueue.type = simple
    4. ## Topic Priority: 0~255, Default is 0
    5. ## mqtt.mqueue.priority = topic/1=10,topic/2=8
    7. ## Max queue length. Enqueued messages when persistent client disconnected,
    8. ## or inflight window is full. 0 means no limit.
    9. mqtt.mqueue.max_length = 0
    11. ## Low-water mark of queued messages
    12. mqtt.mqueue.low_watermark = 20%
    14. ## High-water mark of queued messages
    15. mqtt.mqueue.high_watermark = 60%
    17. ## Queue Qos0 messages?
    18. mqtt.mqueue.store_qos0 = true

    队列参数说明:

    Broker 参数设置

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

    1. ## System Interval of publishing broker $SYS Messages
    2. mqtt.broker.sys_interval = 60s

    发布订阅(PubSub)参数设置

    1. ## PubSub Pool Size. Default should be scheduler numbers.
    2. mqtt.pubsub.pool_size = 8
    4. mqtt.pubsub.by_clientid = true
    6. ## Subscribe Asynchronously
    7. mqtt.pubsub.async = true

    桥接(Bridge)参数设置

    1. ## Bridge Queue Size
    3. ## Ping Interval of bridge node. Unit: Second
    4. mqtt.bridge.ping_down_interval = 1s
    1. ## Dir of plugins' config
    2. mqtt.plugins.etc_dir = etc/plugins/
    4. ## File to store loaded plugin names.
    5. mqtt.plugins.loaded_file = data/loaded_plugins

    MQTT Listeners 参数说明

    EMQ 消息服务器支持 MQTT、MQTT/SSL、MQTT/WS 协议服务端，可通过 listener.tcp|ssl|ws|wss|.* 设置端口、最大允许连接数等参数。

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

    1883

    MQTT 协议端口

    8883

    MQTT/SSL 端口

    8083

    MQTT/WebSocket 端口

    8080

    HTTP 管理 API 端口

    8084

    Listener 参数说明:

    MQTT/TCP 监听器 - 1883

    EMQ 2.2 版本支持配置多个 MQTT 协议监听器，例如配置 external、internal 两个监听器:

    1. ##--------------------------------------------------------------------
    2. ## External TCP Listener
    4. ## External TCP Listener: 1883, 127.0.0.1:1883, ::1:1883
    5. listener.tcp.external = 0.0.0.0:1883
    7. ## Size of acceptor pool
    8. listener.tcp.external.acceptors = 16
    11. listener.tcp.external.max_clients = 102400
    13. #listener.tcp.external.mountpoint = external/
    15. ## Rate Limit. Format is 'burst,rate', Unit is KB/Sec
    16. #listener.tcp.external.rate_limit = 100,10
    18. #listener.tcp.external.access.1 = allow 192.168.0.0/24
    20. listener.tcp.external.access.2 = allow all
    22. ## Proxy Protocol V1/2
    23. ## listener.tcp.external.proxy_protocol = on
    24. ## listener.tcp.external.proxy_protocol_timeout = 3s
    26. ## TCP Socket Options
    27. listener.tcp.external.backlog = 1024
    29. #listener.tcp.external.recbuf = 4KB
    31. #listener.tcp.external.sndbuf = 4KB
    33. listener.tcp.external.buffer = 4KB
    35. listener.tcp.external.nodelay = true
    37. ##--------------------------------------------------------------------
    38. ## Internal TCP Listener
    40. ## Internal TCP Listener: 11883, 127.0.0.1:11883, ::1:11883
    41. listener.tcp.internal = 127.0.0.1:11883
    43. ## Size of acceptor pool
    44. listener.tcp.internal.acceptors = 16
    46. ## Maximum number of concurrent clients
    47. listener.tcp.internal.max_clients = 102400
    49. #listener.tcp.external.mountpoint = internal/
    51. ## Rate Limit. Format is 'burst,rate', Unit is KB/Sec
    52. ## listener.tcp.internal.rate_limit = 1000,100
    54. ## TCP Socket Options
    55. listener.tcp.internal.backlog = 512
    57. listener.tcp.internal.tune_buffer = on
    59. listener.tcp.internal.buffer = 1MB
    61. listener.tcp.internal.recbuf = 4KB
    63. listener.tcp.internal.sndbuf = 1MB
    65. listener.tcp.internal.nodelay = true

    MQTT/SSL 监听器 - 8883

    1. ##--------------------------------------------------------------------
    2. ## External SSL Listener
    3. listener.ssl.external = 8883
    5. ## Size of acceptor pool
    6. listener.ssl.external.acceptors = 16
    8. ## Maximum number of concurrent clients
    9. listener.ssl.external.max_clients = 1024
    11. ## listener.ssl.external.mountpoint = inbound/
    13. ## Rate Limit. Format is 'burst,rate', Unit is KB/Sec
    14. ## listener.ssl.external.rate_limit = 100,10
    16. ## Proxy Protocol V1/2
    17. ## listener.ssl.external.proxy_protocol = on
    18. ## listener.ssl.external.proxy_protocol_timeout = 3s
    20. listener.ssl.external.access.1 = allow all
    22. ## SSL Options
    23. listener.ssl.external.handshake_timeout = 15
    24. listener.ssl.external.keyfile = etc/certs/key.pem
    25. listener.ssl.external.certfile = etc/certs/cert.pem
    26. ## 开启双向认证
    27. ## listener.ssl.external.cacertfile = etc/certs/cacert.pem
    28. ## listener.ssl.external.verify = verify_peer
    29. ## listener.ssl.external.fail_if_no_peer_cert = true

    MQTT/WebSocket 监听器 - 8083

    1. ##--------------------------------------------------------------------
    2. ## External MQTT/WebSocket Listener
    4. listener.ws.external = 8083
    6. listener.ws.external.acceptors = 4
    8. listener.ws.external.max_clients = 64
    10. listener.ws.external.access.1 = allow all

    MQTT/WebSocket/SSL 监听器 - 8084

    1. ##--------------------------------------------------------------------
    2. ## External MQTT/WebSocket/SSL Listener
    4. listener.wss.external = 8084
    6. listener.wss.external.acceptors = 4
    8. listener.wss.external.max_clients = 64
    10. listener.wss.external.access.1 = allow all
    12. ## SSL Options
    13. listener.wss.external.handshake_timeout = 15s
    15. listener.wss.external.keyfile = {{ platform_etc_dir }}/certs/key.pem
    17. listener.wss.external.certfile = {{ platform_etc_dir }}/certs/cert.pem
    19. ## listener.wss.external.cacertfile = {{ platform_etc_dir }}/certs/cacert.pem
    21. ## listener.wss.external.verify = verify_peer
    23. ## listener.wss.external.fail_if_no_peer_cert = true

    HTTP API 监听器 - 8080

    1. ##--------------------------------------------------------------------
    2. ## HTTP Management API Listener
    4. listener.api.mgmt = 127.0.0.1:8080
    6. listener.api.mgmt.acceptors = 4
    8. listener.api.mgmt.max_clients = 64

    Erlang 虚拟机监控设置

    EMQ 2.2 插件配置文件，全部在 etc/plugins/ 目录:

    配置文件

    说明

    etc/plugins/emq_mod_presence

    客户端上下线状态消息发布

    etc/plugins/emq_mod_retainer

    Retain 消息存储插件

    etc/plugins/emq_mod_subscription

    客户端上线自动主题订阅

    etc/plugins/emq_auth_username.conf

    用户名、密码认证插件

    etc/plugins/emq_auth_clientid.conf

    ClientId 认证插件

    etc/plugins/emq_auth_http.conf

    HTTP 认证插件配置

    etc/plugins/emq_auth_mongo.conf

    MongoDB 认证插件配置

    etc/plugins/emq_auth_mysql.conf

    MySQL 认证插件配置

    etc/plugins/emq_auth_pgsql.conf

    Postgre 认证插件配置

    etc/plugins/emq_auth_redis.conf

    Redis 认证插件配置

    etc/plugins/emq_web_hook.conf

    Web Hook 插件配置

    etc/plugins/emq_lua_hook.conf

    Lua Hook 插件配置

    etc/plugins/emq_coap.conf

    CoAP 协议服务器配置

    etc/plugins/emq_dashboard.conf

    Dashboard 控制台插件配置

    etc/plugins/emq_plugin_template.conf

    示例插件模版

    etc/plugins/emq_recon.conf

    Recon 调试插件配置

    etc/plugins/emq_reloader.conf

    热加载插件配置

    etc/plugins/emq_sn.conf

    MQTT-SN 协议插件配置

    etc/plugins/emq_stomp.conf

    Stomp 协议插件配置