配置项

说明

cluster.proto_dist

说明

分布式 Erlang 集群协议类型。可选值为:

• inet_tcp: 使用 IPv4
• inet6_tcp 使用 IPv6
• inet_tls: 使用 TLS，需要与 node.ssl_dist_optfile 配置一起使用。

cluster.discovery

说明

集群节点发现方式。可选值为:

• manual: 手动加入集群
• static: 配置静态节点。配置几个固定的节点，新节点通过连接固定节点中的某一个来加入集群。
• mcast: 使用 UDP 多播的方式发现节点。
• dns: 使用 DNS A 记录的方式发现节点。
• etcd: 使用 etcd 发现节点。
• k8s: 使用 Kubernetes 发现节点。

cluster.autoheal

说明

启用或关闭集群网络分区自动恢复机制。

cluster.autoclean

说明

指定多久之后从集群中删除离线节点。

cluster.static.seeds

说明

当使用 static 方式集群时，指定固定的节点列表，多个节点间使用逗号 , 分隔。

cluster.mcast.addr

说明

当使用 mcast 方式集群时，指定多播地址。

cluster.mcast.ports

说明

当使用 mcast 方式集群时，指定多播端口。如有多个端口使用逗号 , 分隔。

cluster.mcast.iface

说明

当使用 mcast 方式集群时，指定节点发现服务需要绑定到本地哪个 IP 地址。

cluster.mcast.ttl

说明

当使用 mcast 方式集群时，指定多播的 Time-To-Live 值。

cluster.mcast.loop

说明

当使用 mcast 方式集群时，设置多播的报文是否投递到本地回环地址。

cluster.dns.name

说明

当使用 dns 方式集群时，指定 DNS A 记录的名字。emqx 会通过访问这个 DNS A 记录来获取 IP 地址列表，然后拼接 cluster.dns.app 里指定的 APP 名得到集群中所有节点的列表。

示例

设置 cluster.dns.app = emqx，并且配置了一个 DNS: mycluster.com，其指向 3 个 IP 地址:

则得到集群节点列表如下：

emqx@192.168.0.100
emqx@192.168.0.101
emqx@192.168.0.102

cluster.dns.app

说明

当使用 dns 方式集群时，用来与从 cluster.dns.name 获取的 IP 列表拼接得到节点名列表。

cluster.etcd.server

说明

当使用 etcd 方式集群时，指定 etcd 服务的地址。如有多个服务使用逗号 , 分隔。

cluster.etcd.prefix

说明

当使用 etcd 方式集群时，指定 etcd 路径的前缀。每个节点在 etcd 中都会创建一个路径:

v2/keys/<prefix>/<cluster.name>/<node.name>

cluster.etcd.node_ttl

说明

当使用 etcd 方式集群时，指定 etcd 中节点路径的过期时间。

cluster.etcd.ssl.keyfile

说明

当使用 SSL 连接 etcd 时，指定客户端的私有 Key 文件。

cluster.etcd.ssl.certfile

说明

当使用 SSL 连接 etcd 时，指定 SSL 客户端的证书文件。

cluster.etcd.ssl.cacertfile

说明

当使用 SSL 连接 etcd 时，指定 SSL 的 CA 证书文件。

cluster.k8s.apiserver

说明

当使用 k8s 方式集群时，指定 Kubernetes API Server。如有多个 Server 使用逗号 , 分隔。

cluster.k8s.service_name

说明

当使用 k8s 方式集群时，指定 Kubernetes 中 EMQX 的服务名。

cluster.k8s.address_type

说明

当使用 k8s 方式集群时，address_type 用来从 Kubernetes 接口的应答里获取什么形式的 Host 列表。

示例

指定 cluster.k8s.address_type 为 ip，则将从 Kubernetes 接口中获取 emqx 服务的 IP 地址列表:

172.16.122.31
172.16.122.32
172.16.122.33

然后与 cluster.k8s.app_name 配置指定的 app name 拼接，得到 emqx 节点列表:

emqx@172.16.122.31
emqx@172.16.122.32
emqx@172.16.122.33

cluster.k8s.app_name

说明

当使用 k8s 方式集群时，app_name 用来跟获取的 Host 列表拼接，得到节点列表。

cluster.k8s.suffix

说明

当使用 k8s 方式并且 cluster.k8s.address_type 指定为 dns 类型时，可设置 emqx 节点名的后缀。与 cluster.k8s.namespace 一起使用用以拼接得到节点名列表。

cluster.k8s.namespace

说明

当使用 k8s 方式并且 cluster.k8s.address_type 指定为 dns 类型时，可设置 emqx 节点名的命名空间。与 cluster.k8s.suffix 一起使用用以拼接得到节点名列表。

示例

设置 cluster.k8s.address_type 为 dns，则将从 Kubernetes 接口中获取 emqx 服务的 dns 列表:

172-16-122-31
172-16-122-32
172-16-122-33

然后拼接上 cluster.k8s.app_name = emqx，cluster.k8s.suffix = pod.cluster.local，cluster.k8s.namespace = default 得到 dns 形式的 emqx 节点名列表:

emqx@172-16-122-31.default.pod.cluster.local
emqx@172-16-122-32.default.pod.cluster.local
emqx@172-16-122-33.default.pod.cluster.local

Node

node.name

说明

节点名。格式为 <name>@<host>。其中 <host> 可以是 IP 地址，也可以是 FQDN。详见 。

node.cookie

说明

分布式 Erlang 集群使用的 cookie 值。

node.data_dir

说明

节点的 data 目录，用于存放 Mnesia 数据文件等。

node.heartbeat

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 -heart 参数。

启用或关闭 Erlang 运行时检测机制，并在运行时终止时自动重启。需小心使用，以免手动关闭 emqx 时被监控进程重新启动。

node.async_threads

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 +A 参数。

设置 Erlang 运行时异步线程池中的线程数量。详情请参见 http://erlang.org/doc/man/erl.html (opens new window)。

node.process_limit

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 +P 参数。

设置 Erlang 允许的最大进程数，这将影响 emqx 节点能处理的连接数。详情请参见 。

node.max_ports

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 +Q 参数。

设置 Erlang 允许的最大 Ports 数量。详情请参见 http://erlang.org/doc/man/erl.html (opens new window)。

node.dist_buffer_size

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 +zdbbl 参数。

设置 Erlang 分布式通信使用的最大缓存大小。详情请参见 。

node.max_ets_tables

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 +e 参数。

设置 Erlang 运行时允许的最大 ETS 表数量。详情请参见 http://erlang.org/doc/man/erl.html (opens new window)。

node.global_gc_interval

说明

系统调优参数，设置 Erlang 运行多久强制进行一次全局垃圾回收。

node.fullsweep_after

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 -env ERL_FULLSWEEP_AFTER 参数。

设置 Erlang 运行时多少次 generational GC 之后才进行一次 fullsweep GC。详情请参见 。

node.crash_dump

说明

设置 Erlang crash_dump 文件的存储路径和文件名。

node.ssl_dist_optfile

说明

此配置将覆盖 vm.args 文件里的 -ssl_dist_optfile 参数。

如使用 SSL 方式建立 emqx 集群，需指定 SSL 分布式协议的配置文件。需要与 cluster.proto_dist = inet_tls 一起使用。

node.dist_net_ticktime

说明

系统调优参数，此配置将覆盖 vm.args 文件里的 -kernel net_ticktime 参数。

当一个节点持续无响应多久之后，认为其已经宕机并断开连接。详情请参见 http://www.erlang.org/doc/man/kernel_app.html#net_ticktime (opens new window)。

### node.dist_use_interface

说明

节点间通讯网卡，默认使用 0.0.0.0 指定监听所有的网卡，或在指定需要监听网卡的 IP。

node.dist_listen_min

说明

与 node.dist_listen_max 一起设定一个 TCP 端口段，此端口段用于分配给分布式 Erlang，作为分布式通道的监听端口。注意如果在节点之间设置了防火墙，需要将此端口段放进防火墙的端口白名单里。

node.dist_listen_max

说明

与 node.dist_listen_min 一起设定一个 TCP 端口段，此端口段用于分配给分布式 Erlang，作为分布式通道的监听端口。注意如果在节点之间设置了防火墙，需要将此端口段放进防火墙的端口白名单里。

RPC

rpc.mode

说明

RPC 模式。可选同步或异步模式。

rpc.async_batch_size

说明

异步模式下最大的批量发送消息数。注意此配置在同步模式下不起作用。

rpc.port_discovery

说明

manual: 手动指定服务器客户端的端口号 tcp_server_port and tcp_client_port. stateless: discover ports in a stateless manner. If node name is emqx<N>@127.0.0.1, where the <N> is an integer, then the listening port will be 5370 + <N>

Default is manual when started from docker (environment variable override from docker-entrypoint) otherwise stateless.

rpc.tcp_server_ip

说明

设置 RPC 本地服务使用的监听网卡。默认使用 0.0.0.0 指定监听所有的网卡，或在指定需要监听网卡的 IP。

rpc.tcp_server_port

说明

设置 RPC 本地服务使用的监听 port。 注意，该配置仅在 rpc.port_discovery 设置成 manual 时有效

rpc.tcp_client_num

说明

设置由本节点发起，通往每个远程节点的 RPC 通信通道数量。设置为 1 可保证消息顺序。保持默认值（CPU 核心数的一半）可提高 RPC 的吞吐能力。

rpc.connect_timeout

说明

建立 RPC 连接超时时间。建立连接时若远程节点无响应，多久之后放弃尝试。

rpc.send_timeout

说明

发送超时时间。发送消息多久之后放弃。

rpc.authentication_timeout

说明

RPC 认证超时时间。尝试认证若远程节点无响应，多久之后放弃。

rpc.call_receive_timeout

说明

RPC 同步模式的超时时间。RPC 同步调用若收不到回复，用多久之后放弃。

rpc.socket_keepalive_idle

说明

在最近一次数据包发送多久之后，发送 keepalive 探测报文。

rpc.socket_keepalive_interval

说明

发送 keepalive 探测报文的间隔。

rpc.socket_keepalive_count

说明

连续多少次 keepalive 探测报文都收不到回复的情况下，认为 RPC 连接已丢失。

rpc.socket_sndbuf

说明

TCP 调优参数。TCP 发送缓冲区大小。

rpc.socket_recbuf

说明

TCP 调优参数。TCP 接收缓冲区大小。

rpc.socket_buffer

说明

TCP 调优参数。用户态的 Socket 缓冲区大小。

Log

log.to

说明

将日志输出到什么地方。可选值为:

• off: 完全关闭日志功能

• file: 仅将日志输出到文件

• console: 仅将日志输出到标准输出(emqx 控制台)

• both: 同时将日志输出到文件和标准输出(emqx 控制台)

log.level

说明

全局的日志级别。这包括 primary log level 以及所有的 log handlers。详情请参见 日志级别和 log handlers。

log.dir

说明

日志文件目录。

log.file

说明

日志文件的前缀。例如，若使用默认值 (log.file = emqx.log)，日志文件名将为 emqx.log.1，emqx.log.2，…。

log.chars_limit

说明

设置单个日志消息的最大长度。如超过此长度，日志消息将被截断。-1 表示无限制。

log.max_depth

Description

控制 Eralng 数据结构的打印深度，和 Erlang 进程消息队列查看的深度。 或配置成 ‘unlimited’ (不带引号) 不限深度打印。

log.rotation.size

说明

设置单个日志文件大小。如超过此大小，则进行日志文件滚动，创建新的日志文件。

log.rotation.count

说明

设置日志文件总个数。如超过此文件个数，则下一次日志文件滚动将会覆盖第一个文件。

log.<level>.file

说明

针对某日志级别设置单独的日志文件。

示例

将 info 及 info 以上的日志单独输出到 info.log.N 文件中：

log.info.file = info.log

将 error 及 error 以上的日志单独输出到 error.log.N 文件中

log.error.file = error.log

log.max_depth

说明

控制对大的数据结构打印日志时的最大深度。超过深度的部分将被 ‘…’ 代替。

log.single_line

说明

设置成 true 时，单行打印日志。 如果设置成 false, 如 crash 日志中的堆栈信息等将打印多行

log.formatter

说明

选择打印日志的格式

log.formatter.text.date.format

注意: 这个配置在 EMQX 开源版 4.3.15, 4.4.4 和 EMQX 企业版 4.3.10, 4.4.4 及之后可以使用。

说明

指定 text logger 的时间戳格式。可以是 rfc3339 或者 FORMAT 字符串。

其中 FORMAT 里支持的控制符如下:

举例:

authacl

allow_anonymous

说明

是否允许匿名用户登录系统。

注：生产环境建议关闭此选项。

acl_nomatch

说明

ACL 未命中时，允许或者拒绝 发布/订阅 操作。

acl_file

说明

默认 ACL 文件的路径。

enable_acl_cache

说明

是否启用 ACL 缓存。

acl_cache_max_size

说明

ACL 规则最大缓存条数。

acl_cache_ttl

说明

ACL 规则最大缓存时间。

acl_deny_action

说明

ACL 检查失败后，执行的操作。

• ignore：不做任何操作。
• disconnect：断开连接。

alias_enrichment_module

说明

Tip

这是一个非常特殊的高级选项，除非 EMQ 推荐，否则不应该使用。

在 “4.4.11 “中引入。

指定一个定义了 enrich_with_aliases/2 函数的模块。 这个函数会被用来添加客户端的 ID 和证书通用名（CN）的别名等信息。

special_auth_module

说明

Tip

这是一个特殊的高级选项，除非 EMQ 推荐，否则不应该使用。

在 “4.4.11 “中引入。

指定一个实现了 check_authn/2 函数的模块。 这个 该函数将被用于 client.authenticate 钩子，作为一种实现自定义认证逻辑的方式。

acl_order

Description

配置多个 ACL 后端时，可以使用该配置来指定检查的顺序。 默认值 none 表示未定义任何顺序。使用逗号分隔多个后端名称（或别名）。 例如 jwt,http 表示先检查 jwt，再检查 http。 支持的名称有：internal（或 file）、http、jwt、ldap、mnesia、mongo（或 mongodb）、mysql、pgsql（或 postgres）、redis。 指定顺序的后端总是排在未指定顺序的前面，例如如果使用了 mnesia，jwt 和 http，但是在配置中仅指定了 jwt,http，那么 mnesia 会排在最后。 如果使用了第三方插件，则必需使用具体的回调模块名称，例如 my_auth_plugin_module。

Tip

无法识别的名字会被忽略。

auth_order

Description

置多个认证后端时，可以使用该配置来指定检查的顺序。 默认值 none 表示未定义任何顺序。使用逗号分隔多个后端名称（或别名）。 配置使用与 acl_order 类似，只是认证没有 internal 这个后端。

Tip

无法识别的名字会被忽略。

flapping_detect_policy

说明

指定 Flapping 检查策略。

格式：<threshold>,<duration>,<banned>。

例如，30, 1m, 5m，它表示如果客户端在 1 分钟内断开连接 30 次，那么在后续 5 分钟内禁止登录。

mqtt

mqtt.max_packet_size

说明

允许的 MQTT 报文最大长度。

mqtt.max_clientid_len

说明

允许的 Client ID 串的最大长度。

mqtt.max_topic_levels

说明

允许客户端订阅主题的最大层级。0 表示不限制。

Warning

Topic层级过多可能导致订阅时的性能问题。

mqtt.max_qos_allowed

说明

允许客户端发布的最大 QoS 等级。

mqtt.max_topic_alias

说明

允许最大的主题别名数。0 表示不支持主题别名。

mqtt.retain_available

说明

是否支持 Retain 消息。

mqtt.wildcard_subscription

说明

是否支持订阅通配主题。

mqtt.shared_subscription

说明

是否支持共享订阅。

mqtt.ignore_loop_deliver

说明

是否忽略自己发送的消息。如果忽略，则表明 EMQX 不会向消息的发送端投递此消息。

mqtt.strict_mode

说明

是否开启严格检查模式。严格检查模式会更细致的检查 MQTT 报文的正确性。

zoneexternal

zone.external.idle_timeout

说明

TCP 连接建立后的发呆时间，如果这段时间内未收到任何报文，则会关闭该连接。

zone.external.enable_acl

说明

是否开启 ACL 检查。

zone.external.enable_ban

说明

是否开启黑名单。

zone.external.enable_stats

说明

是否开启客户端状态统计。

zone.external.acl_deny_action

说明

ACL 检查失败后，执行的操作。

• ignore：不做任何操作。
• disconnect：断开连接。

zone.external.force_gc_policy

说明

当收到一定数量的消息，或字节，就强制执行一次垃圾回收。

格式：<Number>|<Bytes>。

例如，16000|16MB 表示当收到 16000 条消息，或 16MB 的字节流入就强制执行一次垃圾回收。

zone.external.force_shutdown_policy

说明

当进程消息队列长度，或占用的内存字节到达某值，就强制关闭该进程。

这里的 消息队列 指的是 Erlang 进程的 消息邮箱，并非 QoS 1 和 QoS 2 的 mqueue。

格式：<Number>|<Bytes>。

例如，32000|32MB 表示当进程堆积了 32000 条消息，或进程占用内存达到 32MB 则关闭该进程。

zone.external.max_packet_size

说明

允许的 MQTT 报文最大长度。

zone.external.max_clientid_len

说明

允许的 Client ID 串的最大长度。

zone.external.max_topic_levels

说明

允许客户端订阅主题的最大层级。0 表示不限制。

Warning

Topic层级过多可能导致订阅时的性能问题。

zone.external.max_qos_allowed

说明

允许客户端发布的最大 QoS 等级。

zone.external.max_topic_alias

说明

允许最大的主题别名数。0 表示不支持主题别名。

zone.external.retain_available

说明

是否支持 Retain 消息。

zone.external.wildcard_subscription

说明

是否支持订阅通配主题。

zone.external.shared_subscription

说明

是否支持共享订阅。

zone.external.server_keepalive

说明

服务端指定的 Keepalive 时间。用于 MQTT v5.0 协议的 CONNACK 报文。

zone.external.keepalive_backoff

说明

Keepalive 退避指数。EMQX 如果在 Keepalive * backoff * 2 的时间内未收到客户端的任何数据报文，则认为客户端已心跳超时。

zone.external.max_subscriptions

说明

单个客户端允许订阅的最大主题数。0 表示不限制。

zone.external.upgrade_qos

说明

允许 EMQX 在投递消息时，强制升级消息的 QoS 等级为订阅的 QoS 等级。

zone.external.max_inflight

说明

飞行窗口大小。飞行窗口用于存储未被应答的 QoS 1 和 QoS 2 消息。

zone.external.retry_interval

说明

消息重发间隔。EMQX 在每个间隔检查是否需要进行消息重发。

zone.external.max_awaiting_rel

说明

QoS 2 消息的最大接收窗口，配置 EMQX 能够同时处理多少从客户端发来的 QoS 2 消息。0 表示不限制。

zone.external.await_rel_timeout

说明

QoS 2 消息处理超时时间，在超时后若还未收到 QoS 的 PUBREL 报文，则将消息从接收窗口中丢弃。

zone.external.session_expiry_interval

说明

会话默认超时时间，主要用于 MQTT v3.1 和 v3.1.1 协议。在 MQTT v5.0 中，该值通常会携带在客户端的连接报文中。

zone.external.max_mqueue_len

说明

消息队列最大长度。当飞行窗口满，或客户端离线后，消息会被存储至该队列中。0 表示不限制。

zone.external.mqueue_priorities

说明

队列消息优先级配置：

• none：表示无优先级区分。
• <Spec>：表示为一个消息优先表，它配置了某主题下消息的优先级。例如：
  • topic/1=10：表示主题 topic/1 的消息优先级为 10。
  • topic/1=10,topic/2=8：表示配置了两个主题的优先级，其分别为 10 和 8。
  • 其中，优先级数值越高，优先等级越高。

当消息队列长度有限时，会优先丢弃低优先级的消息。

zone.external.mqueue_default_priority

说明

消息默认的优先等级。

zone.external.mqueue_store_qos0

说明

消息队列是否存储 QoS 0 消息。

zone.external.enable_flapping_detect

说明

是否开启 Flapping 检查。

zone.external.mountpoint

说明

主题挂载点。配置后，所有订阅和发布的主题在 EMQX 都会为其增加一个前缀。

其中可用的占位符有：

• %c：表示客户端的 Client ID。
• %u：表示客户端的 Username。

例如，配置挂载点为 user/%c/。那么 Client ID 为 tom 的客户端在发布主题 open 消息时，实际在 EMQX 中路由的主题是 user/tom/open。

zone.external.use_username_as_clientid

说明

是否用客户端的 Username 作为其 Client ID。

zone.external.ignore_loop_deliver

说明

是否忽略自己发送的消息。如果忽略，则表明 EMQX 不会向消息的发送端投递此消息。

zone.external.strict_mode

说明

是否开启严格检查模式。严格检查模式会更细致的检查 MQTT 报文的正确性。

zoneinternal

zone.internal.allow_anonymous

说明

是否允许匿名用户登录系统。

zone.internal.enable_stats

说明

是否开启客户端状态统计。

zone.internal.enable_acl

说明

是否开启 ACL 检查。

zone.internal.acl_deny_action

说明

ACL 检查失败后，执行的操作。

• ignore：不做任何操作。
• disconnect：断开连接。

zone.internal.force_gc_policy

说明

当收到一定数量的消息，或字节，就强制执行一次垃圾回收。

格式：<Number>|<Bytes>。

例如，16000|16MB 表示当收到 16000 条消息，或 16MB 的字节流入就强制执行一次垃圾回收。

zone.internal.wildcard_subscription

说明

是否支持订阅通配主题。

zone.internal.shared_subscription

说明

是否支持共享订阅。

zone.internal.max_subscriptions

说明

单个客户端允许订阅的最大主题数。0 表示不限制。

zone.internal.max_inflight

说明

飞行窗口大小。飞行窗口用于存储未被应答的 QoS 1 和 QoS 2 消息。

zone.internal.max_awaiting_rel

说明

QoS 2 消息的最大接收窗口，配置 EMQX 能够同时处理多少从客户端发来的 QoS 2 消息。0 表示不限制。

zone.internal.max_mqueue_len

说明

消息队列最大长度。当飞行窗口满，或客户端离线后，消息会被存储至该队列中。0 表示不限制。

zone.internal.mqueue_store_qos0

说明

消息队列是否存储 QoS 0 消息。

zone.internal.enable_flapping_detect

说明

是否开启 Flapping 检查。

zone.internal.force_shutdown_policy

说明

当进程消息队列长度，或占用的内存字节到达某值，就强制关闭该进程。

这里的 消息队列 指的是 Erlang 进程的 消息邮箱，并非 QoS 1 和 QoS 2 的 mqueue。

格式：<Number>|<Bytes>。

例如，32000|32MB 表示当进程堆积了 32000 条消息，或进程占用内存达到 32MB 则关闭该进程。

zone.internal.mountpoint

说明

主题挂载点。配置后，所有订阅和发布的主题在 EMQX 都会为其增加一个前缀。

其中可用的占位符有：

• %c：表示客户端的 Client ID。
• %u：表示客户端的 Username。

例如，配置挂载点为 user/%c/。那么 Client ID 为 tom 的客户端在发布主题 open 消息时，实际在 EMQX 中路由的主题是 user/tom/open。

zone.internal.ignore_loop_deliver

说明

是否忽略自己发送的消息。如果忽略，则表明 EMQX 不会向消息的发送端投递此消息。

zone.internal.strict_mode

说明

是否开启严格检查模式。严格检查模式会更细致的检查 MQTT 报文的正确性。

zone.internal.bypass_auth_plugins

说明

是否允许该 Zone 下的客户端绕过认证插件的认证步骤。

tcpexternal

listener.tcp.external

说明

配置名称为 external 的 MQTT/TCP 监听器的监听地址。

示例

1883：表监听 IPv4 的 0.0.0.0:1883。 127.0.0.1:1883：表监听地址为 127.0.0.1 网卡上的 1883 端口。 ::1:1883：表监听 IPv6 地址为 ::1 网卡上的 1883 端口。

listener.tcp.external.acceptors

说明

监听器的接收池大小。

listener.tcp.external.max_connections

说明

监听器允许的最大并发连接数量。

listener.tcp.external.max_conn_rate

说明

监听器允许的最大接入速率。单位：个/秒

listener.tcp.external.active_n

说明

监听器持续接收 TCP 报文的次数。

listener.tcp.external.zone

说明

监听器所属的配置域 (Zone)。

listener.tcp.external.rate_limit

说明

监听器的速率限制。格式为 <limit>,<duration>。

示例

100KB,10s：表 限制 10 秒内的流入字节数不超过 100 KB。

listener.tcp.external.access.1

说明

监听器的 ACL 规则列表。它用于设置连接层的白/黑名单。

示例

allow all：表允许所有的 TCP 连接接入。 allow 192.168.0.0/24：表允许网络地址为 192.168.0.0/24 的 TCP 连接接入。

同时，该配置可配置多条规则：

listener.tcp.external.access.1 = deny 192.168.0.1
listener.tcp.external.access.2 = allow all

它表示，除 192.168.0.1 外的 TCP 连接都允许接入。

listener.tcp.external.proxy_protocol

说明

监听器是否开启 Proxy Protocol 的支持。

如果 EMQX 集群部署在 HAProxy 或 Nginx 后，且需要拿到客户端真实的源 IP 地址与端口，则需打开此配置。

Proxy Protcol 参考: https://www.haproxy.com/blog/haproxy/proxy-protocol (opens new window)。

listener.tcp.external.proxy_protocol_timeout

说明

设置 Proxy Protocol 解析的超时时间。如果该时间内没收到 Proxy Protocol 的报文，EMQX 会关闭其连接。

listener.tcp.external.peer_cert_as_username

说明

使用客户端证书来覆盖 Username 字段的值。其可选值为：

• cn：客户端证书的 Common Name 字段值
• dn：客户端证书的 Subject Name 字段值
• crt：DER 格式编码的客户端证书二进制
• pem：基于 DER 格式上的 base64 编码后的字符串
• md5：DER 格式证书的 MD5 哈希值

注意：在 TCP 的监听器下，该配置仅在负载均衡服务器终结 SSL 的部署情况下可以用；且负载均衡服务器需要配置 Proxy Protocol 将证书域的内容给发送至 EMQX。例如 HAProxy 的配置可参考

listener.tcp.external.peer_cert_as_clientid

说明

使用客户端证书来覆盖 ClientID 字段的值。其可选值的含义同上。

listener.tcp.external.backlog

说明

TCP 连接队列的最大长度。它表明了系统中允许的正在三次握手的 TCP 连接队列最大个数。

listener.tcp.external.send_timeout

说明

TCP 报文发送超时时间。

listener.tcp.external.send_timeout_close

说明

TCP 报文发送超时后，是否关闭该连接。

listener.tcp.external.recbuf

说明

TCP 接收缓存区大小（操作系统内核级参数）

参见：http://erlang.org/doc/man/inet.html

listener.tcp.external.sndbuf

说明

TCP 发送缓存区大小（操作系统内核级参数）。

参见：。

listener.tcp.external.buffer

说明

TCP 缓冲区大小 (用户级)。

该值建议大于等于 sndbuff 和 recbuff 的最大值，以避免一些性能问题。在不配置的情况下，它默认等于 sndbuff 和 recbuff 的最大值。

参见：http://erlang.org/doc/man/inet.html (opens new window)。

listener.tcp.external.tune_buffer

说明

如果打开此配置，请设置该值等于 sndbuff 与 recbuff 的最大值。

listener.tcp.external.nodelay

说明

即 TCP_NODELAY 参数。开启该选项即允许小的 TCP 数据报文将会立即发送。

listener.tcp.external.reuseaddr

说明

即 SO_REUSEADDR 参数。开启该选项即允许本地重用端口，无需等待 TIME_WAIT 状态结束。

tcpinternal

listener.tcp.internal

说明

配置名称为 internal 的 MQTT/TCP 监听器的监听地址。

示例

11883：表监听 IPv4 的 0.0.0.0:11883。 127.0.0.1:11883：表监听地址为 127.0.0.1 网卡上的 11883 端口。 ::1:11883：表监听 IPv6 地址为 ::1 网卡上的 端口。

listener.tcp.internal.acceptors

说明

监听器的接收池大小。

listener.tcp.internal.max_connections

说明

监听器允许的最大并发连接数量。

listener.tcp.internal.max_conn_rate

说明

监听器允许的最大接入速率。单位：个/秒

listener.tcp.internal.active_n

说明

监听器持续接收 TCP 报文的次数。

listener.tcp.internal.zone

说明

监听器所属的配置域 (Zone)。

listener.tcp.internal.rate_limit

说明

监听器的速率限制。格式为 <limit>,<duration>。

示例

100KB,10s：表 限制 10 秒内的流入字节数不超过 100 KB。

listener.tcp.internal.backlog

说明

TCP 连接队列的最大长度。它表明了系统中允许的正在三次握手的 TCP 连接队列最大个数。

listener.tcp.internal.send_timeout

说明

TCP 报文发送超时时间。

listener.tcp.internal.send_timeout_close

说明

TCP 报文发送超时后，是否关闭该连接。

listener.tcp.internal.recbuf

说明

TCP 接收缓存区大小（操作系统内核级参数）

listener.tcp.internal.sndbuf

说明

TCP 发送缓存区大小（操作系统内核级参数）

listener.tcp.internal.buffer

说明

TCP 缓冲区大小 (用户级)。

listener.tcp.internal.tune_buffer

说明

listener.tcp.internal.nodelay

说明

即 TCP_NODELAY 参数。开启该选项即允许小的 TCP 数据报文将会立即发送。

listener.tcp.internal.reuseaddr

说明

即 SO_REUSEADDR 参数。开启该选项即允许本地重用端口，无需等待 TIME_WAIT 状态结束。

tlsexternal

listener.ssl.external

说明

配置名称为 external 的 SSL 监听器。

listener.ssl.external.acceptors

说明

监听器的接收池大小。

listener.ssl.external.max_connections

说明

监听器允许的最大并发连接数量。

listener.ssl.external.max_conn_rate

说明

监听器允许的最大接入速率。单位：个/秒。

listener.ssl.external.active_n

说明

监听器持续接收 TCP 报文的次数。

listener.ssl.external.zone

说明

监听器所属的配置组 (Zone)。

listener.ssl.external.access.1

说明

监听器的 ACL 规则列表。它用于设置连接层的白/黑名单。

例如:

allow all：表允许所有的 TCP 连接接入。 allow 192.168.0.0/24：表允许网络地址为 192.168.0.0/24 的 TCP 连接接入。

同时，该配置可配置多条规则:

listener.ssl.external.access.1 = deny 192.168.0.1
listener.ssl.external.access.2 = allow all

listener.ssl.external.rate_limit

说明

监听器的速率限制。格式为 <limit>,<duration>。

listener.ssl.external.proxy_protocol

说明

监听器是否开启 Proxy Protocol 的支持。

如果 EMQX 集群部署在 HAProxy 或 Nginx 后，且需要拿到客户端真实的源 IP 地址与端口，则需打开此配置。

Proxy Protcol 参考: 。

listener.ssl.external.proxy_protocol_timeout

说明

设置 Proxy Protocol 解析的超时时间。如果该时间内没收到 Proxy Protocol 的报文，EMQX 会关闭其连接。

listener.ssl.external.tls_versions

说明

指定服务端支持的 SSL 的版本列表。详情请参见 http://erlang.org/doc/man/ssl.html (opens new window)。

listener.ssl.external.handshake_timeout

说明

指定 SSL 握手过程的超时时间。

listener.ssl.external.depth

说明

证书链中非自签发的中间证书的最大数量。如果该值为 0 则表示，对端证书必须是根 CA 直接授信的。

listener.ssl.external.key_password

说明

证书密钥文件的密码。如果你的证书密钥设置了密码，则需要配置该选项。

listener.ssl.external.keyfile

说明

指定 SSL 的私钥文件 (PEM)。

listener.ssl.external.certfile

说明

指定 SSL 的证书文件 (PEM)。

listener.ssl.external.cacertfile

说明

指定 SSL 的 CA 证书文件 (PEM)。该文件应包含发布服务器证书的所有中间CA证书以及根证书。 该文件还应包含所有受信CA的证书用以用于验证客户端的证书。

listener.ssl.external.enable_ocsp_stapling

说明

在 e4.4.11 中引入。

是否为监听器启用OCSP Stapling 功能。 如果设置为 true，则需要定义OCSP响应者的URL。 这个响应将被缓存，并作为 TLS 握手的一部分发送给连接的客户端。 注意：仅支持 TLS 1.2 和 TLS 1.3。

listener.ssl.external.ocsp_responder_url

说明

在 e4.4.11 中引入。

启用 OCSP Stapling 时，用于检查服务器证书的 OCSP 应答服务 URL。 应答的内容会被缓存，并定期刷新。

listener.ssl.external.ocsp_issuer_pem

说明

在 e4.4.11 中引入。

该文件用于存放 OCSP Responder 的 PEM 格式编码的证书。 该证书用于校验 OCSP Responder 返回的内容。

listener.ssl.external.ocsp_refresh_interval

说明

在 e4.4.11 中引入。

刷新 OCSP Stapling 的间隔。 如果响应在刷新期间未能被获取，先前缓存的 响应仍将被使用，直到从 OCSP Responder 那里成功地获取一个较新的响应。 该配置不能小于 1 分钟。

说明

在 e4.4.11 中引入。

从 OCSP Responder 处获取 OCSP Stapling 响应的最长时间。

listener.ssl.external.enable_crl_check

说明

在 e4.4.11 中引入。

是否为该监听器启用 CRL 验证和缓存。

注意：当缓存没有命中时，EMQX 会尝试在运行时从客户端证书中携带的 URL 来下载最新的 CRL。如果下载失败，EMQX 会拒绝该客户端的连接。

listener.ssl.external.crl_cache_urls

说明

在 e4.4.11 中引入。

以逗号分隔的URL列表，用于获取和缓存 CRL 列表的服务器。 必须在路径中包括CRL文件的路径（例如： http://my.crl.server/intermediate.crl.pem, http://my.other.crl.server/another.crl.pem）。

crl_cache_http_timeout

说明

在 e4.4.11 中引入。

获取 CRL 列表时 HTTP 请求的超时。适用于所有监听器。

crl_cache_refresh_interval

说明

在 e4.4.11 中引入。

从服务器刷新 CRL 的周期。 适用于所有 URL 和监听器。 不能短于1分钟。

listener.ssl.external.dhfile

说明

若使用 Ephemeral Diffie-Helman 算法，指定算法使用的 key 文件。

listener.ssl.external.verify

说明

指定握手过程中是否校验客户端。

listener.ssl.external.fail_if_no_peer_cert

说明

SSL 握手过程中若客户端没有证书，是否让握手失败。

listener.ssl.external.ciphers

说明

指定服务端支持的密码套件。

listener.ssl.external.psk_ciphers

说明

若使用 PSK 算法，指定服务端支持的 PSK Cipher 列表。注意 ‘listener.ssl.external.ciphers’ 和 ‘listener.ssl.external.psk_ciphers’ 只能配置一个。

listener.ssl.external.secure_renegotiate

说明

指定在客户端不遵循 RFC 5746 的情况下，是否拒绝 renegotiation 请求。

listener.ssl.external.reuse_sessions

说明

指定是否支持 SSL session 重用。详情见 。

listener.ssl.external.honor_cipher_order

说明

指定是否使用服务端的偏好设置选择 Ciphers。

listener.ssl.external.peer_cert_as_username

说明

使用客户端证书来覆盖 Username 字段的值。其可选值为：

• cn：客户端证书的 Common Name 字段值
• dn：客户端证书的 Subject Name 字段值
• crt：DER 格式编码的客户端证书二进制
• pem：基于 DER 格式上的 base64 编码后的字符串
• md5：DER 格式证书的 MD5 哈希值

注意 listener.ssl.external.verify 应当设置为 verify_peer。

listener.ssl.external.peer_cert_as_clientid

说明

使用客户端证书来覆盖 ClientID 字段的值。其可选值的含义同上。

注意 listener.ssl.external.verify 应当设置为 verify_peer。

listener.ssl.external.backlog

说明

TCP 连接队列的最大长度。它表明了系统中允许的正在三次握手的 TCP 连接队列最大个数。

listener.ssl.external.send_timeout

说明

TCP 报文发送超时时间。

listener.ssl.external.send_timeout_close

说明

TCP 报文发送超时后，是否关闭该连接。

listener.ssl.external.recbuf

说明

TCP 接收缓存区大小（操作系统内核级参数）。

参见：http://erlang.org/doc/man/inet.html (opens new window)。

listener.ssl.external.sndbuf

说明

TCP 发送缓存区大小（操作系统内核级参数）。

参见：。

listener.ssl.external.buffer

说明

TCP 缓冲区大小 (用户级)。

该值建议大于等于 sndbuff 和 recbuff 的最大值，以避免一些性能问题。在不配置的情况下，它默认等于 sndbuff 和 recbuff 的最大值。

参见：http://erlang.org/doc/man/inet.html (opens new window)。

listener.ssl.external.tune_buffer

说明

如果打开此配置，请设置该值等于 sndbuff 与 recbuff 的最大值。

listener.ssl.external.nodelay

说明

即 TCP_NODELAY 参数。开启该选项即表示禁用 Nagle 算法，小包将被立即发送。

listener.ssl.external.reuseaddr

说明

即 SO_REUSEADDR 参数。开启该选项即允许本地重用端口，无需等待 TIME_WAIT 状态结束。

wsexternal

listener.ws.external

说明

配置名称为 external 的 MQTT/WS 监听器的监听地址。

示例

8083：表监听 IPv4 的 0.0.0.0:8083。 127.0.0.1:8083：表监听地址为 127.0.0.1 网卡上的 8083 端口。 ::1:8083：表监听 IPv6 地址为 ::1 网卡上的 8083 端口。

listener.ws.external.mqtt_path

说明

WebSocket 的 MQTT 协议路径。因此 EMQX 的 WebSocket 的地址是： ws://{ip}:{port}/mqtt。

listener.ws.external.acceptors

说明

监听器的接收池大小。

listener.ws.external.max_connections

说明

监听器允许的最大并发连接数量。

listener.ws.external.max_conn_rate

说明

监听器允许的最大接入速率。单位：个/秒

listener.ws.external.active_n

说明

监听器持续接收 TCP 报文的次数。

listener.ws.external.rate_limit

说明

监听器的速率限制。格式为 <limit>,<duration>。

示例

100KB,10s：表 限制 10 秒内的流入字节数不超过 100 KB。

listener.ws.external.zone

说明

监听器所属的配置域 (Zone)。

listener.ws.external.access.1

说明

监听器的 ACL 规则列表。它用于设置连接层的白/黑名单。

listener.ws.external.fail_if_no_subprotocol

说明

如果设置为 true，则服务器将在客户端没有携带 Sec-WebSocket-Protocol 字段时返回错误。微信小程序需关闭该验证。

listener.ws.external.supported_protocols

说明

指定支持的子协议，子协议之间以逗号分隔。

listener.ws.external.proxy_address_header

说明

如果 EMQX 集群部署在 HAProxy 或 Nginx 后，则可打开该配置获取客户端真实的 IP 地址。

listener.ws.external.proxy_port_header

说明

如果 EMQX 集群部署在 HAProxy 或 Nginx 后，则可打开该配置获取客户端真实的端口。

listener.ws.external.proxy_protocol

说明

监听器是否开启 Proxy Protocol 的支持。

如果 EMQX 集群部署在 HAProxy 或 Nginx 后，且需要拿到客户端真实的源 IP 地址与端口，则需打开此配置。

Proxy Protcol 参考: https://www.haproxy.com/blog/haproxy/proxy-protocol (opens new window)。

listener.ws.external.proxy_protocol_timeout

说明

设置 Proxy Protocol 解析的超时时间。如果该时间内没收到 Proxy Protocol 的报文，EMQX 会关闭其连接。

listener.ws.external.backlog

说明

TCP 连接队列的最大长度。它表明了系统中允许的正在三次握手的 TCP 连接队列最大个数。

listener.ws.external.send_timeout

说明

TCP 报文发送超时时间。

listener.ws.external.send_timeout_close

说明

TCP 报文发送超时后，是否关闭该连接。

listener.ws.external.recbuf

说明

TCP 接收缓存区大小（操作系统内核级参数）

listener.ws.external.sndbuf

说明

TCP 发送缓存区大小（操作系统内核级参数）

listener.ws.external.buffer

说明

TCP 缓冲区大小 (用户级)。

listener.ws.external.tune_buffer

说明

如果打开此配置，请设置该值等于 sndbuff 与 recbuff 的最大值。

listener.ws.external.nodelay

说明

即 TCP_NODELAY 参数。开启该选项即允许小的 TCP 数据报文将会立即发送。

listener.ws.external.compress

说明

是否压缩 WebSocket 消息。压缩的实现依赖 。

defalte_opts 下的配置项，都属于压缩相关的参数配置，如无必要请不需要修改它。

listener.ws.external.deflate_opts.level

说明

压缩等级。

listener.ws.external.deflate_opts.mem_level

说明

压缩参数。内存使用限制等级，配置可开辟多少内存来参与压缩过程。

1：最少的内存，但会降低压缩率。 9：最多的内存，会提高计算速度和压缩率。

不配置，则默认为 8。

listener.ws.external.deflate_opts.strategy

说明

压缩策略，用于调优压缩率：

• default：针对普通数据。
• filtered：由过滤器或预测器产生的数据，适用于分布随机性强的内容。
• huffman_only：强制使用 Huffman 算法。优于 filtered。
• rle：将匹配距离限制为 1 (Run-Lenght Encoding)，比 huffman_only 要快，但主要用于 PNG 图片。

这些策略仅影响压缩率，不会对正确性带来任何影响。

listener.ws.external.deflate_opts.server_context_takeover

说明

是否允许服务端的压缩上下文在帧之间传递。

listener.ws.external.deflate_opts.client_context_takeover

说明

是否允许客户端的压缩上下文在帧之间传递。

listener.ws.external.deflate_opts.server_max_window_bits

说明

服务端最大窗口值。设置一个较大的值会有更好的压缩率，但会额外的消耗内存。

listener.ws.external.deflate_opts.client_max_window_bits

说明

客户端最大窗口值。设置一个较大的值会有更好的压缩率，但会额外的消耗内存。

listener.ws.external.idle_timeout

说明

TCP 连接建立后的发呆时间，如果这段时间内未收到任何报文，则会关闭该连接。

listener.ws.external.max_frame_size

说明

允许的单个 MQTT 报文长度的最大值。

listener.wss.external

说明

配置名称为 external 的 WSS (MQTT/WebSocket/SSL) 监听器。

listener.wss.external.mqtt_path

说明

WebSocket 的 URL Path。

listener.wss.external.acceptors

说明

监听器的接收池大小。

listener.wss.external.max_connections

说明

监听器允许的最大并发连接数量。

listener.wss.external.max_conn_rate

说明

监听器允许的最大接入速率。单位：个/秒。

listener.wss.external.active_n

说明

监听器持续接收 TCP 报文的次数。

listener.wss.external.rate_limit

说明

监听器的速率限制。格式为 <limit>,<duration>。

listener.wss.external.zone

说明

监听器所属的配置组 (Zone)。

listener.wss.external.access.1

说明

监听器的 ACL 规则列表。它用于设置连接层的白/黑名单。

例如:

allow all：表允许所有的 TCP 连接接入。 allow 192.168.0.0/24：表允许网络地址为 192.168.0.0/24 的 TCP 连接接入。

同时，该配置可配置多条规则:

listener.wss.external.access.1 = deny 192.168.0.1
listener.wss.external.access.2 = allow all

listener.wss.external.fail_if_no_subprotocol

说明

如果设置为 true，则服务器将在客户端没有携带 Sec-WebSocket-Protocol 字段时返回错误。微信小程序需关闭该验证。

listener.wss.external.supported_protocols

说明

指定支持的子协议，子协议之间以逗号分隔。

listener.wss.external.proxy_address_header

说明

如果 EMQX 集群部署在 HAProxy 或 Nginx，则可打开该配置获取客户端真实的 IP 地址。

listener.wss.external.proxy_protocol

说明

监听器是否开启 Proxy Protocol 的支持。

如果 EMQX 集群部署在 HAProxy 或 Nginx 后，且需要拿到客户端真实的源 IP 地址与端口，则需打开此配置。

Proxy Protcol 参考：。

listener.wss.external.proxy_protocol_timeout

说明

设置 Proxy Protocol 解析的超时时间。如果该时间内没收到 Proxy Protocol 的报文，EMQX 会关闭其连接。

listener.wss.external.tls_versions

说明

指定服务端支持的 SSL 的版本列表。详情请参见 http://erlang.org/doc/man/ssl.html (opens new window)。

listener.wss.external.keyfile

说明

指定 SSL 的私钥文件 (PEM)。

listener.wss.external.certfile

说明

指定 SSL 的证书文件 (PEM)。

listener.wss.external.cacertfile

说明

指定 SSL 的 CA 证书文件 (PEM)。该文件应包含发布服务器证书的所有中间CA证书以及根证书。 该文件还应包含所有受信CA的证书用以用于验证客户端的证书。

listener.wss.external.depth

说明

证书链中非自签发的中间证书的最大数量。如果该值为 0 则表示，对端证书必须是根 CA 直接授信的。

listener.wss.external.key_password

说明

证书密钥文件的密码。如果你的证书密钥设置了密码，则需要配置该选项。

listener.wss.external.dhfile

说明

若使用 Ephemeral Diffie-Helman 算法，指定算法使用的 key 文件。

listener.wss.external.verify

说明

指定握手过程中是否校验客户端。

listener.wss.external.fail_if_no_peer_cert

说明

SSL 握手过程中若客户端没有证书，是否让握手失败。

listener.wss.external.ciphers

说明

指定服务器支持的密码套件。

listener.wss.external.psk_ciphers

说明

若使用 PSK 算法，指定服务端支持的 PSK Cipher 列表。注意 ‘listener.wss.external.ciphers’ 和 ‘listener.wss.external.psk_ciphers’ 只能配置一个。

listener.wss.external.secure_renegotiate

说明

指定在客户端不遵循 RFC 5746 的情况下，是否拒绝 renegotiation 请求。

listener.wss.external.reuse_sessions

说明

指定是否支持 SSL session 重用。详情见 。

listener.wss.external.honor_cipher_order

说明

指定是否使用服务端的偏好设置选择 Ciphers。

listener.wss.external.peer_cert_as_username

说明

使用客户端证书来覆盖 Username 字段的值。其可选值为：

• cn：客户端证书的 Common Name 字段值
• dn：客户端证书的 Subject Name 字段值
• crt：DER 格式编码的客户端证书二进制
• pem：基于 DER 格式上的 base64 编码后的字符串
• md5：DER 格式证书的 MD5 哈希值

注意 listener.wss.external.verify 应当设置为 verify_peer。

listener.wss.external.peer_cert_as_clientid

说明

使用客户端证书来覆盖 ClientID 字段的值。其可选值的含义同上。

注意 listener.wss.external.verify 应当设置为 verify_peer。

listener.wss.external.backlog

说明

TCP 连接队列的最大长度。它表明了系统中允许的正在三次握手的 TCP 连接队列最大个数。

listener.wss.external.send_timeout

说明

TCP 报文发送超时时间。

listener.wss.external.send_timeout_close

说明

TCP 报文发送超时后，是否关闭该连接。

listener.wss.external.recbuf

说明

TCP 接收缓存区大小（操作系统内核级参数）

参见：http://erlang.org/doc/man/inet.html

listener.wss.external.sndbuf

说明

TCP 发送缓存区大小（操作系统内核级参数）

参见：

listener.wss.external.buffer

说明

TCP 缓冲区大小 (用户级)。

该值建议大于等于 sndbuff 和 recbuff 的最大值，以避免一些性能问题。在不配置的情况下，它默认等于 sndbuff 和 recbuff 的最大值

参见：http://erlang.org/doc/man/inet.html

listener.wss.external.tune_buffer

说明

如果打开此配置，请设置该值等于 sndbuff 与 recbuff 的最大值。

listener.wss.external.nodelay

说明

即 TCP_NODELAY 参数。开启该选项即允许小的 TCP 数据报文将会立即发送。

listener.wss.external.compress

说明

该选项若设置为 true，Websocket 消息将会被压缩。

listener.wss.external.deflate_opts.level

说明

压缩等级。

listener.wss.external.deflate_opts.mem_level

说明

压缩参数。内存使用限制等级，配置可开辟多少内存来参与压缩过程。

1：最少的内存，但会降低压缩率。 9：最多的内存，会提高计算速度和压缩率。

不配置，则默认为 8。

listener.wss.external.deflate_opts.strategy

说明

压缩策略，用于调优压缩率：

• default：针对普通数据。
• filtered：由过滤器或预测器产生的数据，适用于分布随机性强的内容。
• huffman_only：强制使用 Huffman 算法。优于 filtered。
• rle：将匹配距离限制为 1 (Run-Lenght Encoding)，比 huffman_only 要快，但主要用于 PNG 图片。

这些策略仅影响压缩率，不会对正确性带来任何影响。

listener.wss.external.deflate_opts.server_context_takeover

说明

是否允许服务端的压缩上下文在帧之间传递。

listener.wss.external.deflate_opts.client_context_takeover

说明

是否允许客户端的压缩上下文在帧之间传递。

listener.wss.external.deflate_opts.server_max_window_bits

说明

服务端最大窗口值。设置一个较大的值会有更好的压缩率，但会额外的消耗内存。

listener.wss.external.deflate_opts.client_max_window_bits

说明

客户端最大窗口值。设置一个较大的值会有更好的压缩率，但会额外的消耗内存。

listener.wss.external.idle_timeout

说明

TCP 连接建立后的发呆时间，如果这段时间内未收到任何报文，则会关闭该连接。

listener.wss.external.max_frame_size

说明

允许的单个 MQTT 报文长度的最大值。

plugins

plugins.etc_dir

说明

插件的配置目录。

plugins.loaded_file

说明

插件启动列表的配置文件路径。

plugins.expand_plugins_dir

说明

外部插件存放目录。

broker

broker.sys_interval

说明

设置系统主题 ($SYS) 消息的发布间隔。

broker.sys_heartbeat

说明

设置系统心跳消息的发布间隔。系统心跳消息包括下面两个主题：

• “$SYS/brokers/<node>/uptime”
• “$SYS/brokers/<node>/datetime”

broker.enable_session_registry

说明

启用或关闭全局会话注册。

broker.session_locking_strategy

说明

设置会话集群锁的类型。会话的集群锁用来防止同一个客户端在多个不同节点上创建多个会话，常见于客户端频繁切换节点登录的情况。

broker.shared_subscription_strategy

说明

设置共享订阅的分发策略。可选值为:

• hash_clientid: 按照发布者 ClientID 的哈希值
• hash_topic: 按照源消息主题的哈希值
• local: 优先选择和发布者在同一各节点的共享订阅者来派发消息，否则进行随机派发
• random: 在所有订阅者中随机选择
• round_robin: 按照一个固定的顺序选择下一个订阅者
• sticky: 首次分发时随机选择一个订阅者，后续消息一直发往这一个订阅者直到该订阅者离线或该发布者重连。

broker.sample_group.shared_subscription_strategy

说明

重载共享订阅组名为 sample_group 的派发策略。不配置则以 broker.shared_subscription_strategy 为准。

其中 sample_group 可以配置为任何组名称。

其可选策略与 broker.shared_subscription_strategy 一致。

broker.shared_dispatch_ack_enabled

说明

开启或关闭共享订阅对于 qos1/qos2 消息的 ACK 检查功能。开启后，如果投递到某个订阅者但收不到ACK，将尝试投递给订阅组里的下一个订阅者。

broker.route_batch_clean

说明

开启或关闭批量清理路由信息。批量清理路由可用在短时间内大量客户端掉线的情况，以提高清理效率。

broker.perf.route_lock_type = key

Description

选择在数据库中为通配符订阅更新路由信息时锁的粒度。

• key (默认值) 为每个前缀拿一次数据库锁。
• tab 表锁
• global 全局锁

对于较大集群，(如7个node或以上），尤其是node之间网络延迟大的，推荐是用tab 和 global。 注意：是需要重启整个集群来使得更新生效。

broker.perf.trie_compaction

Description

设置为 true 时，对通配符订阅表进行压缩。 压缩可优化写操作，降低高并发量的订阅请求响应时间，内存使用量也只有非压缩时的一半。 非压缩优化读操作，适用于发布主题层数较多的场景。

注意: 将该配置从 fase 改成 true 时，集群中的节点可依次重启来使配置生效。 从 true 改为 false 时，需要将集群中所有的节点重启，否则会发生有些消息 无法被路由的情况。

monitor

sysmon.long_gc

说明

启用垃圾回收时间监控并在回收时间超过设定值时触发告警，0 表示禁用此监控。

sysmon.long_schedule

说明

启用进程调度时间监控并在调度时间超过设定值时触发告警，0 表示禁用此监控。

sysmon.large_heap

说明

启用堆栈大小监控并在进程执行垃圾回收后堆栈大小仍大于设定值时触发告警，0 表示禁用此监控。

sysmon.busy_port

说明

指定是否启用进程间消息通道拥塞监控。

sysmon.busy_dist_port

说明

指定是否启用集群 RPC 通道拥塞监控。

os_mon.cpu_check_interval

说明

CPU 占用率检查周期。

os_mon.cpu_high_watermark

说明

CPU 占用率超过 os_mon.cpu_high_watermark 时将触发告警。

os_mon.cpu_low_watermark

说明

CPU 占用率回落到 os_mon.cpu_low_watermark 以下时将清除告警。

os_mon.mem_check_interval

说明

内存占用率检查周期。

os_mon.sysmem_high_watermark

说明

EMQX 为所有进程分配的内存占系统内存的百分比超过 os_mon.sysmem_high_watermark 时将触发告警。

os_mon.procmem_high_watermark

说明

EMQX 为单个进程分配的内存占系统内存的百分比超过 os_mon.procmem_high_watermark 时将触发告警。

vm_mon.check_interval

说明

进程数量检查周期。

vm_mon.process_high_watermark

说明

当前进程数量占进程最大数量的百分比超过 vm_mon.process_high_watermark 时将触发告警。进程最大数量由 node.process_limit 配置项决定。

vm_mon.process_low_watermark

说明

当前进程数量占进程最大数量的百分比回落到 vm_mon.process_low_watermark 以下时将触发告警。进程最大数量由 node.process_limit 配置项决定。

插件 emqx-auth-http

auth.http.auth_req.url

说明

指定认证请求的目标 URL。

auth.http.auth_req.method

说明

指定认证请求的请求方法。

auth.http.auth_req.headers.<Any>

示例

auth.http.auth_req.headers.content-type = application/x-www-form-urlencoded
auth.http.auth_req.headers.accept = */*

说明

指定 HTTP 请求头部中的数据。<Key> 指定 HTTP 请求头部中的字段名，此配置项的值为相应的字段值。<Key> 可以是标准的 HTTP 请求头部字段，也可以自定义的字段，可以配置多个不同的请求头部字段。

auth.http.auth_req.params

说明

指定认证请求中携带的数据。使用 GET 方法时 auth.http.auth_req.params 的值将被转换为以 & 分隔的 k=v 键值对以查询字符串参数的形式发送。使用 POST 方法时 auth.http.auth_req.params 的值将被转换为以 & 分隔的 k=v 键值对以 Request Body 的形式发送。所有的占位符都会被运行时数据所替换，可用的占位符如下：

auth.http.super_req.url

说明

指定超级用户认证请求的目标 URL。

auth.http.super_req.method

说明

指定超级用户认证请求的请求方法。

auth.http.super_req.headers.<Any>

示例

auth.http.super_req.headers.content-type = application/x-www-form-urlencoded
auth.http.super_req.headers.accept = */*

说明

指定 HTTP 请求头部中的数据。<Key> 指定 HTTP 请求头部中的字段名，此配置项的值为相应的字段值。<Key> 可以是标准的 HTTP 请求头部字段，也可以自定义的字段，可以配置多个不同的请求头部字段。

auth.http.super_req.params

说明

指定超级用户认证请求中携带的数据。使用 GET 方法时 auth.http.super_req.params 的值将被转换为以 & 分隔的 k=v 键值对以查询字符串参数的形式发送。使用 POST 方法时 auth.http.super_req.params 的值将被转换为以 & 分隔的 k=v 键值对以 Request Body 的形式发送。所有的占位符都会被运行时数据所替换，可用的占位符同 auth.http.auth_req.params。

auth.http.acl_req

说明

指定 ACL 验证请求的目标 URL。

auth.http.acl_req.method

说明

指定 ACL 验证请求的请求方法。

auth.http.acl_req.headers.<Any>

示例

auth.http.acl_req.headers.content-type = application/x-www-form-urlencoded
auth.http.acl_req.headers.accept = */*

说明

指定 HTTP 请求头部中的数据。<Key> 指定 HTTP 请求头部中的字段名，此配置项的值为相应的字段值。<Key> 可以是标准的 HTTP 请求头部字段，也可以自定义的字段，可以配置多个不同的请求头部字段。

auth.http.acl_req.params

说明

指定 ACL 验证请求中携带的数据。使用 GET 方法时 auth.http.acl_req.params 的值将被转换为以 & 分隔的 k=v 键值对以查询字符串参数的形式发送。使用 POST 方法时 auth.http.acl_req.params 的值将被转换为以 & 分隔的 k=v 键值对以 Request Body 的形式发送。所有的占位符都会被运行时数据所替换，可用的占位符如下：

auth.http.timeout

说明

HTTP 请求超时时间。任何等价于 0s 的设定值都表示永不超时。

auth.http.connect_timeout

说明

HTTP 请求的连接超时时间。任何等价于 0s 的设定值都表示永不超时。

auth.http.ssl.cacertfile

说明

CA 证书文件路径。

auth.http.ssl.certfile

说明

客户端证书文件路径。

auth.http.ssl.keyfile

说明

客户端私钥文件路径。

插件 emqx_auth_jwt

auth.jwt.secret

说明

设置 HMAC Secret。

auth.jwt.from

说明

从什么地方获取 JWT。可选值为:

• username: MQTT CONNECT 报文的 username 字段作为 JWT。
• password: MQTT CONNECT 报文的 password 字段作为 JWT。

auth.jwt.pubkey

说明

若使用 RSA 或者 ECDSA 加密算法，须指定私钥文件。

auth.jwt.verify_claims

说明

启用或关闭 Claims 校验功能。

auth.jwt.verify_claims.<claims>

说明

启用 Claims 校验功能时，可设置 JWT 中字段的可选值。

例如，若期望 JWT 中的 Claim 字段 sub 的值为 “abc”，则可以配置如下规则:

auth.jwt.verify_claims.sub = abc

期望值支持两个通配符:

• %u: username
• %c: clientid

例如，若期望 JWT 中的 Claim 字段 sub 的值与 MQTT CONNECT 报文中 username 字段相同，则可以配置如下规则:

auth.jwt.verify_claims.sub = %u

插件 emqx_auth_ldap

auth.ldap.servers

说明

LDAP 服务地址。

auth.ldap.port

说明

LDAP 服务端口。

auth.ldap.pool

说明

连接池大小。

auth.ldap.bind_dn

说明

登入 LDAP 服务的 DN。

auth.ldap.bind_password

说明

登入 LDAP 服务的密码。

auth.ldap.timeout

说明

查询操作的超时时间。

auth.ldap.device_dn

说明

客户端隶属的 DN。

auth.ldap.match_objectclass

说明

客户端对象的名称。

auth.ldap.username.attributetype

说明

Username 属性的数据类型。

auth.ldap.password.attributetype

说明

Password 属性的数据类型。

auth.ldap.ssl

说明

是否开启 SSL。

auth.ldap.ssl.certfile

说明

SSL 服务端证书路径。

auth.ldap.ssl.keyfile

说明

SSL 服务端秘钥文件路径。

auth.ldap.ssl.cacertfile

说明

CA 证书文件路径。

auth.ldap.ssl.verify

说明

SSL 认证方式：

• verify_none：单向认证。
• verify_peer：双向认证。

auth.ldap.ssl.fail_if_no_peer_cert

说明

如果客户端未提供 SSL 证书，则断开连接。

插件 emqx_auth_mongo

auth.mongo.type

说明

设置 MongoDB 的拓扑类型:

• single: 单节点

• unknown: 未知

• sharded: 分片模式

• rs: 副本模式 (replicated set)

auth.mongo.rs_set_name

说明

设置 MongoDB 服务的地址。如有多个使用逗号 , 分隔。

auth.mongo.pool

说明

auth.mongo.login

说明

设置 MongoDB 的用户名。

auth.mongo.password

说明

设置 MongoDB 的密码。

auth.mongo.auth_source

说明

设置 MongoDB 的认证源数据库名。

auth.mongo.database

说明

设置 MongoDB 的数据库名。

auth.mongo.query_timeout

说明

设置访问 MongoDB 超时时间。

auth.mongo.ssl

说明

设置是否使用 SSL 访问 MongoDB。

auth.mongo.ssl_opts.keyfile

说明

若使用 SSL 访问 MongoDB，设置 SSL 客户端的私钥文件。

auth.mongo.ssl_opts.certfile

说明

若使用 SSL 访问 MongoDB，设置 SSL 客户端的证书文件。

auth.mongo.ssl_opts.cacertfile

说明

若使用 SSL 访问 MongoDB，设置 SSL 的 CA 证书文件。

auth.mongo.w_mode

说明

设置 MongoDB 的写入模式。

auth.mongo.r_mode

说明

设置 MongoDB 的读取模式。

auth.mongo.auth_query.collection

说明

认证过程用的 Collection 名字。

auth.mongo.auth_query.password_field

说明

认证过程用的主要字段。如需在密码之后加 salt，可以配置为:

auth.mongo.auth_query.password_hash

说明

设置密码字段用的哈希算法。如需在 sha256 密码之后加 salt，可以设置为:

auth.mongo.auth_query.password_hash = sha256,salt

如需在 sha256 密码之前加 salt，可以设置为:

auth.mongo.auth_query.password_hash = salt,sha256

如需在 bcrypt 密码之前加 salt，可以设置为:

auth.mongo.auth_query.password_hash = salt,bcrypt

auth.mongo.auth_query.selector

说明

认证过程执行的 MongoDB 语句。命令可支持通配符:

• %u: username
• %c: clientid
• %C: 客户端 TLS 证书里的 Common Name
• %d: 客户端 TLS 证书里的 Subject

auth.mongo.auth_query.super_query

说明

认证中是否使用 SuperUser。

auth.mongo.super_query.collection

说明

若使用 SuperUser，指定 SuperUser 的 MongoDB Collection。

auth.mongo.super_query.selector

说明

若使用 SuperUser，指定查询 SuperUser 使用的 MongoDB 语句。

auth.mongo.acl_query

说明

是否开启 ACL 功能。

auth.mongo.acl_query.collection

说明

若使用 ACL 功能，指定查询 ACL 规则的 MongoDB Collection。

auth.mongo.acl_query.selector

说明

若使用 ACL 功能，指定查询 ACL 规则使用的 MongoDB 语句。可支持多个 ACL 语句，多个语句之间使用 or 连接。

例如，配置如下两条访问规则：

auth.mongo.acl_query.selector.1 = username=%u
auth.mongo.acl_query.selector.2 = username=$all

并且客户端的 username=’ilyas’，则在查询 acl 规则的时候，会执行如下 MongoDB 语句：

db.mqtt_acl.find({$or: [{username: "ilyas"},  {username: "$all"}]});

auth.mongo.topology.pool_size

说明

MongoDB 拓扑参数，设置线程池大小。

auth.mongo.topology.max_overflow

说明

MongoDB 拓扑参数，当线程池中所有 workers 都处于忙碌状态时，允许创建多少额外的 worker 线程。

auth.mongo.topology.overflow_ttl

说明

MongoDB 拓扑参数，当有 worker 空闲时。多久之后释放额外的 worker 线程。单位: 毫秒。

auth.mongo.topology.overflow_check_period

说明

MongoDB 拓扑参数，多长时间检查一次有无空闲线程，以释放额外的 worker。

auth.mongo.topology.local_threshold_ms

说明

MongoDB 拓扑参数，选择用来处理用户请求的 Secondary 节点的策略。记到所有节点的 RTT 中的最小值为 LowestRTT，那么只有那些 RTT < LowestRTT + local_threshold_ms 的 Secondary 节点会被选择。

auth.mongo.topology.connect_timeout_ms

说明

MongoDB 拓扑参数，MongoDB 连接超时时间，单位: 毫秒。

auth.mongo.topology.socket_timeout_ms

说明

MongoDB 拓扑参数，MongoDB 消息发送超时时间，单位: 毫秒。

说明

MongoDB 拓扑参数，选择 MongoDB Server 的超时时间，单位: 毫秒。

auth.mongo.topology.wait_queue_timeout_ms

说明

MongoDB 拓扑参数，从线程池中选取 worker 的等待超时时间，单位: 毫秒。

auth.mongo.topology.heartbeat_frequency_ms

说明

MongoDB 拓扑参数，拓扑扫描之间的间隔时间，单位: 毫秒。

auth.mongo.topology.min_heartbeat_frequency_ms

说明

MongoDB 拓扑参数，heartbeat_frequency_ms 允许的最小值，单位: 毫秒。

插件 emqx_auth_mysql

auth.mysql.server

说明

MySQL 服务器地址。

auth.mysql.pool

说明

数据库连接线程池大小。

auth.mysql.username

说明

MySQL 用户名。

auth.mysql.password

说明

MySQL 密码。

auth.mysql.database

说明

MySQL 数据库名称。

auth.mysql.query_timeout

说明

MySQL 数据查询超时时间。查询超时将等同于未找到用户数据处理。

auth.mysql.auth_query

说明

认证时使用的 MySQL 选取语句，选取出来的数据将与经过由 auth.mysql.password_hash 指定的加密方式加密的密码进行比较，比较后内容一致的客户端将被允许登录。加盐后存储的密码需要同时选取盐对应的字段，例如 select password, salt from mqtt_user where username = '%u' limit 1。password 与 salt 字段名不可以修改，表名与 WHERE 子句中的字段名可以视情况变化。WHERE 子句支持以下占位符：

auth.mysql.password_hash

说明

存储在数据库的密码所使用的加密方式。支持以下加密方式：

• plain，支持前后加盐，例如 salt,plain
• md5，支持前后加盐
• sha，支持前后加盐
• sha256，支持前后加盐
• sha512，支持前后加盐
• pbkdf2，格式为 pbkdf2,<Hashfun>,<Iterations>,<Dklen>。其中，<Hashfun> 为使用的哈希函数，支持 md4，md5，ripemd160，sha，sha224，sha256，sha384，sha512，<Iterations> 为迭代次数，<Dklen> 为导出密钥长度。示例：pbkdf2,sha256,1000,20
• bcrypt，仅支持前向加盐，例如 salt,bcrypt

auth.mysql.super_query

说明

超级用户认证时使用的 SQL 选取语句，此语句中所有表名与字段名都可视情况修改，当且仅当选取得到字段的值为 1 时，该用户为超级用户。WHERE 子句中支持的占位符与 auth.mysql.auth_query 相同。

auth.mysql.acl_query

说明

ACL 校验时使用的 SQL 选取语句，此语句中所有表名与字段名都可视情况修改。WHERE 子句中支持的占位符如下：

插件 emqx_auth_pgsql

auth.pgsql.server

说明

PostgreSQL 服务器地址。

auth.pgsql.pool

说明

数据库连接线程池大小。

auth.pgsql.username

说明

PostgreSQL 用户名。

auth.pgsql.password

说明

PostgreSQL 密码。

auth.pgsql.database

说明

PostgreSQL 数据库名称。

auth.pgsql.encoding

说明

PostgreSQL 数据库字符编码格式。

auth.pgsql.ssl

说明

是否启用 TLS 连接。

auth.pgsql.ssl_opts.keyfile

说明

客户端私钥文件路径。

auth.pgsql.ssl_opts.certfile

说明

客户端证书文件路径。

auth.pgsql.ssl_opts.cacertfile

说明

客户端 CA 证书文件路径。

auth.pgsql.auth_query

说明

认证时使用的 SQL 选取语句，同 auth.mysql.auth_query。

auth.pgsql.password_hash

说明

存储在数据库的密码所使用的加密方式，同 auth.mysql.password_hash。

auth.pgsql.super_query

说明

超级用户认证时使用的 SQL 选取语句，同 auth.mysql.super_query。

auth.pgsql.acl_query

说明

ACL 校验时使用的 SQL 选取语句，同 auth.mysql.acl_query。

auth.redis.type

说明

Redis 服务集群类型：

• single：单节点服务。
• sentinel：哨兵模式。
• cluster：集群模式。

auth.redis.server

说明

Redis 服务地址，如果有多个则以逗号分隔。例如，192.168.0.1:6379, 192.168.0.2:6379。

auth.redis.sentinel

说明

Redis sentinel 模式下的集区名称。如果非 sentinel 模式，则不需要配置。

auth.redis.pool

说明

连接池大小。

auth.redis.database

说明

要连接的 Redis 数据库序号。

auth.redis.password

说明

Redis 用户密码。

auth.redis.query_timeout

说明

Redis 查询超时时间。

auth.redis.auth_cmd

说明

认证查询命令，可用站位符有：

• %u：客户端用户名。
• %c：客户端标识。
• %C：客户端 SSL 证书的 cn。
• %d：客户端 SSL 证书的 dn。

auth.redis.password_hash