# 配置项

# Cluster

# cluster.name

Type	Default
string	`emqxcl`

# 说明

集群名称。

# cluster.proto_dist

Type	Optional Value	Default
enum	`inet_tcp`, `inet6_tcp`, `inet_tls`	`inet_tcp`

# 说明

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

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

# cluster.discovery

Type	Optional Value	Default
enum	`manual`, `static`, `mcast`, `dns`, `etcd`, `k8s`	`manual`

# 说明

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

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

# cluster.autoheal

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# cluster.autoclean

Type	Default
duration	`5m`

# 说明

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

# cluster.static.seeds

Type	Default	Example
string	-	`emqx1@192.168.0.100,emqx2@192.168.0.101`

# 说明

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

# cluster.mcast.addr

Type	Default
ipaddr	`239.192.0.1`

# 说明

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

# cluster.mcast.ports

Type	Default
string	`4369`

# 说明

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

# cluster.mcast.iface

Type	Default
ipaddr	`0.0.0.0`

# 说明

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

# cluster.mcast.ttl

Type	Default
integer	`255`

# 说明

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

# cluster.mcast.loop

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# cluster.dns.name

Type	Default	Example
string	-	`mycluster.com`

# 说明

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

# 示例

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

192.168.0.100
192.168.0.101
192.168.0.102

1
2
3

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

emqx@192.168.0.100
emqx@192.168.0.101
emqx@192.168.0.102

1
2
3

# cluster.dns.app

Type	Default	Example
string	-	`emqx`

# 说明

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

# cluster.etcd.server

Type	Default	Example
string	-	`http://127.0.0.1:2379`

# 说明

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

# cluster.etcd.prefix

Type	Default	Example
string	-	`emqxcl`

# 说明

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

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

# cluster.etcd.node_ttl

Type	Default	Example
duration	-	`1m`

# 说明

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

# cluster.etcd.ssl.keyfile

Type	Default	Example
string	-	`etc/certs/client-key.pem`

# 说明

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

# cluster.etcd.ssl.certfile

Type	Default	Example
string	-	`etc/certs/client.pem`

# 说明

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

# cluster.etcd.ssl.cacertfile

Type	Default	Example
string	-	`etc/certs/ca.pem`

# 说明

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

# cluster.k8s.apiserver

Type	Default	Example
string	-	`http://10.110.111.204:8080`

# 说明

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

# cluster.k8s.service_name

Type	Default	Example
string	-	`emqx`

# 说明

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

# cluster.k8s.address_type

Type	Optional Value	Default
enum	`ip`, `dns`, `hostname`	`ip`

# 说明

当使用 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

1
2
3

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

emqx@172.16.122.31
emqx@172.16.122.32
emqx@172.16.122.33

1
2
3

# cluster.k8s.app_name

Type	Default	Example
string	-	`emqx`

# 说明

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

# cluster.k8s.suffix

Type	Default	Example
string	-	`pod.cluster.local`

# 说明

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

# cluster.k8s.namespace

Type	Default	Example
string	-	`default`

# 说明

当使用 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

1
2
3

然后拼接上 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

1
2
3

# Node

# node.name

Type	Default
string	`emqx@127.0.0.1`

# 说明

节点名。格式为 <name>@<host>。其中 <host> 可以是 IP 地址，也可以是 FQDN。详见 http://erlang.org/doc/reference_manual/distributed.html (opens new window)。

Type	Default
string	`emqxsecretcookie`

# 说明

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

# node.data_dir

Type	Default
folder	`./data`

# 说明

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

# node.heartbeat

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

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

# node.async_threads

Type	Optional Value	Default
integer	`0` - `1024`	`4`

# 说明

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

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

# node.process_limit

Type	Optional Value	Default
integer	`1024` - `134217727`	`2097152`

# 说明

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

设置 Erlang 允许的最大进程数，这将影响 emqx 节点能处理的连接数。详情请参见 http://erlang.org/doc/man/erl.html (opens new window)。

# node.max_ports

Type	Optional Value	Default
integer	`1024` - `134217727`	`1048576`

# 说明

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

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

# node.dist_buffer_size

Type	Optional Value	Default
bytesize	`1KB` - `2GB`	`8MB`

# 说明

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

设置 Erlang 分布式通信使用的最大缓存大小。详情请参见 http://erlang.org/doc/man/erl.html (opens new window)。

# node.max_ets_tables

Type	Default
integer	`262144`

# 说明

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

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

# node.global_gc_interval

Type	Default
duration	`15m`

# 说明

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

# node.fullsweep_after

Type	Optional Value	Default
integer	`0` - `65535`	`1000`

# 说明

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

设置 Erlang 运行时多少次 generational GC 之后才进行一次 fullsweep GC。详情请参见 http://erlang.org/doc/man/erlang.html#spawn_opt-4 (opens new window)。

# node.crash_dump

Type	Default
string	`log/crash.dump`

# 说明

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

# node.ssl_dist_optfile

Type	Default
string	`etc/ssl_dist.conf`

# 说明

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

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

# node.dist_net_ticktime

Type	Default
integer	`120`

# 说明

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

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

### node.dist_use_interface

Type	Default
ipaddr	`0.0.0.0`

# 说明

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

# node.dist_listen_min

Type	Optional Value	Default
integer	`1024` - `65535`	`6369`

# 说明

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

# node.dist_listen_max

Type	Optional Value	Default
integer	`1024` - `65535`	`6369`

# 说明

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

# RPC

# rpc.mode

Type	Optional Value	Default
enum	`sync`, `async`	`async`

# 说明

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

# rpc.async_batch_size

Type	Default
integer	`256`

# 说明

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

# rpc.port_discovery

Type	Optional Value Default
enum	`manual`, `stateless`

# 说明

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

Type	Optional Value	Default
ipaddr	`[0-255].[0-255].[0-255].[0-255]`	`0.0.0.0`

# 说明

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

# rpc.tcp_server_port

Type	Optional Value	Default
integer	`1024` - `65535`	`5369`

# 说明

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

# rpc.tcp_client_num

Type	Optional Value	Default
integer	`1` - `256`	`CPU 核心数` / `2`

# 说明

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

# rpc.connect_timeout

Type	Default
duration	`5s`

# 说明

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

# rpc.send_timeout

Type	Default
duration	`5s`

# 说明

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

# rpc.authentication_timeout

Type	Default
duration	`5s`

# 说明

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

# rpc.call_receive_timeout

Type	Default
duration	`15s`

# 说明

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

# rpc.socket_keepalive_idle

Type	Default
duration	`900s`

# 说明

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

# rpc.socket_keepalive_interval

Type	Default
duration	`75s`

# 说明

发送 keepalive 探测报文的间隔。

# rpc.socket_keepalive_count

Type	Default
integer	`9`

# 说明

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

# rpc.socket_sndbuf

Type	Default
bytesize	`1MB`

# 说明

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

# rpc.socket_recbuf

Type	Default
bytesize	`1MB`

# 说明

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

# rpc.socket_buffer

Type	Default
bytesize	`1MB`

# 说明

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

# Log

# log.to

Type	Optional Value	Default
enum	`off`, `file`, `console`, `both`	`file`

# 说明

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

off: 完全关闭日志功能
file: 仅将日志输出到文件
console: 仅将日志输出到标准输出(emqx 控制台)
both: 同时将日志输出到文件和标准输出(emqx 控制台)

# log.level

Type	Optional Value	Default
enum	`debug`, `info`, `notice`, `warning` `error`, `critical`, `alert`, `emergency`	`warning`

# 说明

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

# log.dir

Type	Default
dir	`./log`

# 说明

日志文件目录。

# log.file

Type	Default
string	`emqx.log`

# 说明

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

# log.chars_limit

Type	Default
integer	`-1`

# 说明

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

# log.max_depth

Type	Default
union(integer, 'unlimited')	`20`

# Description

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

# log.rotation.size

Type	Default
bytesize	`10MB`

# 说明

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

# log.rotation.count

Type	Default
integer	`5`

# 说明

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

# log.<level>.file

Type	Default
string	-

# 说明

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

# 示例

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

log.info.file = info.log

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

log.error.file = error.log

# log.max_depth

Type	Default
integer	`20`

# 说明

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

# log.single_line

Type	Default
boolean	`true`

# 说明

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

# log.formatter

Type	Optional Value	Default
enum	`text`, `json`	`text`

# 说明

选择打印日志的格式

# log.formatter.text.date.format

Type	Optional Value	Default
enum	`rfc3339`	`FORMAT`

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

# 说明

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

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

控制符	说明	格式示例
%Y	年	2022
%m	月 (01..12)	11
%d	日	01
%H	时 (00..23)	06
%M	分 (00..59)	43
%S	秒 (00..60)	31
%N	纳秒 (000000000..999999999)	019085000
%6N	微秒 (00000..999999)	019085
%3N	毫秒 (000..999)	019
%z	+HHMM 数字时区	-0400
%:z	+HH:MM 数字时区	-04:00
%::z	+HH:MM:SS 数字时区	-04:00:00

举例:

## 2022-06-02T14:23:09.230000 +08:00
log.formatter.text.date.format = %Y-%m-%dT%H:%M:%S.%6N %:z

## 如下配置可以让时间戳跟 4.2.x 版本的一样 (2022-06-02 14:24:36.124):
log.formatter.text.date.format = %Y-%m-%d %H:%M:%S.%3N

1
2
3
4
5

# authacl

# allow_anonymous

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

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

# acl_nomatch

Type	Optional Value	Default
enum	`allow`, `deny`	`allow`

# 说明

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

# acl_file

Type	Default
string	`etc/acl.conf`

# 说明

默认 ACL 文件的路径。

# enable_acl_cache

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

是否启用 ACL 缓存。

# acl_cache_max_size

Type	Default
integer	`32`

# 说明

ACL 规则最大缓存条数。

# acl_cache_ttl

Type	Default
duration	`1m`

# 说明

ACL 规则最大缓存时间。

# acl_deny_action

Type	Optional Value	Default
enum	`ignore`, `disconnect`	`ignore`

# 说明

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

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

# alias_enrichment_module

Type	Default
string	-

# 说明

Tip

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

在 "4.4.11 "中引入。

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

# special_auth_module

Type	Default
string	-

# 说明

Tip

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

在 "4.4.11 "中引入。

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

# acl_order

Type	Default
string	`none`

# 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

Type	Default
string	`none`

# Description

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

Tip

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

# flapping_detect_policy

Type	Default
string	`30, 1m, 5m`

# 说明

指定 Flapping 检查策略。

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

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

# mqtt

# mqtt.max_packet_size

Type	Default
bytesize	`1MB`

# 说明

允许的 MQTT 报文最大长度。

# mqtt.max_clientid_len

Type	Default
integer	`65535`

# 说明

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

# mqtt.max_topic_levels

Type	Default
integer	`128`

# 说明

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

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

# mqtt.max_qos_allowed

Type	Optional Value	Default
enum	`0`, `1`, `2`	`2`

# 说明

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

# mqtt.max_topic_alias

Type	Default
integer	`65535`

# 说明

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

# mqtt.retain_available

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

是否支持 Retain 消息。

# mqtt.wildcard_subscription

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

是否支持订阅通配主题。

# mqtt.shared_subscription

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

是否支持共享订阅。

# mqtt.ignore_loop_deliver

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# mqtt.strict_mode

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# mqtt.response_information

Type	Default
string	-

# 说明

配置服务端 CONNACK 报文中返回的 Response-Information 属性（MQTT 5.0)，详见：CONNACK: Response Information (opens new window)

# mqtt.message_expiry_interval

Type	Default
duration	infinity

# 说明

设置消息的过期时间。

对于 MQTT 5.0 客户端，此配置仅当消息中未设置 Message-Expiry-Interval 属性时生效；否则，将使用 Message-Expiry-Interval 属性的值。
对于低于 5.0 版本的 MQTT，此配置将始终生效。

注意：将 message_expiry_interval 设置为大于 session_expiry_interval 的值是没有意义的，因为当会话过期时，所有消息都将被清除。

# zoneexternal

# zone.external.idle_timeout

Type	Default
duration	`15s`

# 说明

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

# zone.external.enable_acl

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

是否开启 ACL 检查。

# zone.external.enable_ban

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

是否开启黑名单。

# zone.external.enable_stats

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# zone.external.acl_deny_action

Type	Optional Value	Default
enum	`ignore`, `disconnect`	`ignore`

# 说明

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

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

# zone.external.force_gc_policy

Type	Default
string	`16000\|16MB`

# 说明

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

格式：<Number>|<Bytes>。

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

# zone.external.force_shutdown_policy

Type	Default
string	-

# 说明

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

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

格式：<Number>|<Bytes>。

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

# zone.external.max_packet_size

Type	Default
bytesize	-

# 说明

允许的 MQTT 报文最大长度。

# zone.external.max_clientid_len

Type	Default
integer	-

# 说明

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

# zone.external.max_topic_levels

Type	Default
integer	-

# 说明

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

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

# zone.external.max_qos_allowed

Type	Optional Value	Default
enum	`0`, `1`, `2`	-

# 说明

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

# zone.external.max_topic_alias

Type	Default
integer	-

# 说明

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

# zone.external.retain_available

Type	Optional Value	Default
enum	`true`, `false`	-

# 说明

是否支持 Retain 消息。

# zone.external.wildcard_subscription

Type	Optional Value	Default
enum	`true`, `false`	-

# 说明

是否支持订阅通配主题。

# zone.external.shared_subscription

Type	Optional Value	Default
enum	`true`, `false`	-

# 说明

是否支持共享订阅。

# zone.external.server_keepalive

Type	Default
integer	-

# 说明

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

# zone.external.keepalive_backoff

Type	Optional Value	Default
float	> `0.5`	`0.75`

# 说明

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

# zone.external.max_subscriptions

Type	Default
integer	`0`

# 说明

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

# zone.external.upgrade_qos

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

# zone.external.max_inflight

Type	Default
integer	`32`

# 说明

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

# zone.external.retry_interval

Type	Default
duration	`30s`

# 说明

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

# zone.external.max_awaiting_rel

Type	Default
integer	`100`

# 说明

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

# zone.external.await_rel_timeout

Type	Default
duration	`300s`

# 说明

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

# zone.external.session_expiry_interval

Type	Default
duration	`2h`

# 说明

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

# zone.external.max_mqueue_len

Type	Default
integer	`1000`

# 说明

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

# zone.external.mqueue_priorities

Type	Optional Value	Default
string	`none`, `<Spec>`	`none`

# 说明

队列消息优先级配置：

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

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

# zone.external.mqueue_default_priority

Type	Optional Value	Default
enum	`highest`, `lowest`	`highest`

# 说明

消息默认的优先等级。

# zone.external.mqueue_store_qos0

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# zone.external.enable_flapping_detect

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

是否开启 Flapping 检查。

# zone.external.mountpoint

Type	Default
string	-

# 说明

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

其中可用的占位符有：

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

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

# zone.external.use_username_as_clientid

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# zone.external.ignore_loop_deliver

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# zone.external.strict_mode

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# zoneinternal

# zone.internal.allow_anonymous

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# zone.internal.enable_stats

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# zone.internal.enable_acl

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

是否开启 ACL 检查。

# zone.internal.acl_deny_action

Type	Optional Value	Default
enum	`ignore`, `disconnect`	`ignore`

# 说明

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

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

# zone.internal.force_gc_policy

Type	Default
string	-

# 说明

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

格式：<Number>|<Bytes>。

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

# zone.internal.wildcard_subscription

Type	Optional Value	Default
enum	`true`, `false`	-

# 说明

是否支持订阅通配主题。

# zone.internal.shared_subscription

Type	Optional Value	Default
enum	`true`, `false`	-

# 说明

是否支持共享订阅。

# zone.internal.max_subscriptions

Type	Default
integer	`0`

# 说明

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

# zone.internal.max_inflight

Type	Default
integer	`128`

# 说明

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

# zone.internal.max_awaiting_rel

Type	Default
integer	`1000`

# 说明

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

# zone.internal.max_mqueue_len

Type	Default
integer	`10000`

# 说明

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

# zone.internal.mqueue_store_qos0

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# zone.internal.enable_flapping_detect

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

是否开启 Flapping 检查。

# zone.internal.force_shutdown_policy

Type	Default
string	-

# 说明

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

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

格式：<Number>|<Bytes>。

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

# zone.internal.mountpoint

Type	Default
string	-

# 说明

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

其中可用的占位符有：

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

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

# zone.internal.ignore_loop_deliver

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# zone.internal.strict_mode

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# zone.internal.bypass_auth_plugins

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# tcpexternal

# listener.tcp.external

Type	Default
string	`0.0.0.0:1883`

# 说明

配置名称为 external 的 MQTT/TCP 监听器的监听地址，同时支持 IPv4 和 IPv6。

# 示例

如需配置 IPv4 地址，可参考如下格式：

0.0.0.0:1883：监听连接至 1883 端口的所有 IP 的活动。
127.0.0.1:1883：监听连接至 1883 端口、且 IP 地址为 127.0.0.1 网卡的活动。

如需配置 IPv6 地址，可参考如下格式：

::1:1883：监听连接至 1883 端口、且地址为 ::1 网卡上的活动。

# listener.tcp.external.acceptors

Type	Default
integer	`8`

# 说明

监听器的接收池大小。

# listener.tcp.external.max_connections

Type	Default
integer	`1024000`

# 说明

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

# listener.tcp.external.max_conn_rate

Type	Default
integer	`1000`

# 说明

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

# listener.tcp.external.active_n

Type	Default
integer	`100`

# 说明

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

# listener.tcp.external.zone

Type	Default
string	`external`

# 说明

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

# listener.tcp.external.rate_limit

Type	Default
string	-

# 说明

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

# 示例

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

# listener.tcp.external.access.1

Type	Default
string	`allow all`

# 说明

监听器的 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

1
2

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

# listener.tcp.external.proxy_protocol

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

监听器是否开启 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

Type	Default
duration	-

# 说明

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

# listener.tcp.external.peer_cert_as_username

Type	Optional Value	Default
enum	`cn`, `dn`, `crt`, `pem`, `md5`	`cn`

# 说明

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

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

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

# listener.tcp.external.peer_cert_as_clientid

Type	Optional Value	Default
enum	`cn`, `dn`, `crt`, `pem`, `md5`	`cn`

# 说明

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

# listener.tcp.external.backlog

Type	Default
integer	`1024`

# 说明

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

# listener.tcp.external.send_timeout

Type	Default
duration	`15s`

# 说明

TCP 报文发送超时时间。

# listener.tcp.external.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.tcp.external.recbuf

Type	Default
bytesize	-

# 说明

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

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

# listener.tcp.external.sndbuf

Type	Default
bytesize	-

# 说明

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

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

# listener.tcp.external.buffer

Type	Default
bytesize	-

# 说明

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

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

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

# listener.tcp.external.tune_buffer

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

# listener.tcp.external.nodelay

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# listener.tcp.external.reuseaddr

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# tcpinternal

# listener.tcp.internal

Type	Default
string	`127.0.0.1:11883`

# 说明

配置名称为 internal 的 MQTT/TCP 监听器的监听地址，同时支持 IPv4 和 IPv6。

# 示例

如需配置 IPv4 地址，可参考如下格式：

0.0.0.0:11883：监听连接至 11883 端口的所有 IP 的活动。
127.0.0.1:11883：监听连接至 11883 端口、且 IP 地址为 127.0.0.1 网卡的活动。

如需配置 IPv6 地址，可参考如下格式：

::1:11883：监听连接至 11883 端口、且地址为 ::1 网卡上的活动。

# listener.tcp.internal.acceptors

Type	Default
integer	`4`

# 说明

监听器的接收池大小。

# listener.tcp.internal.max_connections

Type	Default
integer	`1024000`

# 说明

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

# listener.tcp.internal.max_conn_rate

Type	Default
integer	`1000`

# 说明

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

# listener.tcp.internal.active_n

Type	Default
integer	`1000`

# 说明

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

# listener.tcp.internal.zone

Type	Default
string	`internal`

# 说明

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

# listener.tcp.internal.rate_limit

Type	Default
string	-

# 说明

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

# 示例

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

# listener.tcp.internal.backlog

Type	Default
integer	`512`

# 说明

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

# listener.tcp.internal.send_timeout

Type	Default
duration	`5s`

# 说明

TCP 报文发送超时时间。

# listener.tcp.internal.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.tcp.internal.recbuf

Type	Default
bytesize	`64KB`

# 说明

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

# listener.tcp.internal.sndbuf

Type	Default
bytesize	`64KB`

# 说明

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

# listener.tcp.internal.buffer

Type	Default
bytesize	-

# 说明

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

# listener.tcp.internal.tune_buffer

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

# listener.tcp.internal.nodelay

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# listener.tcp.internal.reuseaddr

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# tlsexternal

# listener.ssl.external

Type	Default
string	`0.0.0.0:8883`

# 说明

配置名称为 external 的 SSL 监听器，同时支持 IPv4 和 IPv6。

# 示例

如需配置 IPv4 地址，可参考如下格式：

0.0.0.0:8883：监听连接至 8883 端口的所有 IP 的活动。
127.0.0.1:8883：监听连接至 8883 端口、且 IP 地址为 127.0.0.1 网卡的活动。

如需配置 IPv6 地址，可参考如下格式：

::1:8883：监听连接至 8883 端口、且地址为 ::1 网卡上的活动。

# listener.ssl.external.acceptors

Type	Default
integer	`16`

# 说明

监听器的接收池大小。

# listener.ssl.external.max_connections

Type	Default
integer	`102400`

# 说明

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

# listener.ssl.external.max_conn_rate

Type	Default
integer	`500`

# 说明

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

# listener.ssl.external.active_n

Type	Default
integer	`100`

# 说明

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

# listener.ssl.external.zone

Type	Default
string	`external`

# 说明

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

# listener.ssl.external.access.1

Type	Default
string	`allow all`

# 说明

监听器的 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

1
2

# listener.ssl.external.rate_limit

Type	Default
string	-

# 说明

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

# listener.ssl.external.proxy_protocol

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

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

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

# listener.ssl.external.proxy_protocol_timeout

Type	Default
duration	-

# 说明

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

# listener.ssl.external.tls_versions

Type	Default
string	`tlsv1.3,tlsv1.2,tlsv1.1,tlsv1`

# 说明

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

# listener.ssl.external.handshake_timeout

Type	Default
duration	`15s`

# 说明

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

# listener.ssl.external.depth

Type	Default
number	`10`

# 说明

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

# listener.ssl.external.key_password

Type	Default
string	-

# 说明

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

# listener.ssl.external.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

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

# listener.ssl.external.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

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

# listener.ssl.external.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

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

# listener.ssl.external.enable_ocsp_stapling

Type	Default
boolean	`false`

# 说明

在 e4.4.11 中引入。

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

# listener.ssl.external.ocsp_responder_url

Type	Default
string	-

# 说明

在 e4.4.11 中引入。

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

# listener.ssl.external.ocsp_issuer_pem

Type	Default
string	-

# 说明

在 e4.4.11 中引入。

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

# listener.ssl.external.ocsp_refresh_interval

Type	Default
duration	5m

# 说明

在 e4.4.11 中引入。

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

# listener.ssl.external.ocsp_refresh_http_timeout

Type	Default
duration	15s

# 说明

在 e4.4.11 中引入。

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

# listener.ssl.external.enable_crl_check

Type	Default
boolean	`false`

# 说明

在 e4.4.11 中引入。

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

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

# listener.ssl.external.crl_cache_urls

Type	Default
string	-

# 说明

在 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

Type	Default
duration	15s

# 说明

在 e4.4.11 中引入。

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

# crl_cache_refresh_interval

Type	Default
duration	15m

# 说明

在 e4.4.11 中引入。

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

# listener.ssl.external.dhfile

Type	Default
string	`etc/certs/dh-params.pem`

# 说明

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

# listener.ssl.external.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	`verify_peer`

# 说明

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

# listener.ssl.external.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# listener.ssl.external.ciphers

Type Default

string ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-AES256-SHA384,ECDHE-RSA-AES256-SHA384,ECDHE-ECDSA-DES-CBC3-SHA,ECDH-ECDSA-AES256-GCM-SHA384,ECDH-RSA-AES256-GCM-SHA384,ECDH-ECDSA-AES256-SHA384,ECDH-RSA-AES256-SHA384,DHE-DSS-AES256-GCM-SHA384,DHE-DSS-AES256-SHA256,AES256-GCM-SHA384,AES256-SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES128-SHA256,ECDHE-RSA-AES128-SHA256,ECDH-ECDSA-AES128-GCM-SHA256,ECDH-RSA-AES128-GCM-SHA256,ECDH-ECDSA-AES128-SHA256,ECDH-RSA-AES128-SHA256,DHE-DSS-AES128-GCM-SHA256,DHE-DSS-AES128-SHA256,AES128-GCM-SHA256,AES128-SHA256,ECDHE-ECDSA-AES256-SHA,ECDHE-RSA-AES256-SHA,DHE-DSS-AES256-SHA,ECDH-ECDSA-AES256-SHA,ECDH-RSA-AES256-SHA,AES256-SHA,ECDHE-ECDSA-AES128-SHA,ECDHE-RSA-AES128-SHA,DHE-DSS-AES128-SHA,ECDH-ECDSA-AES128-SHA,ECDH-RSA-AES128-SHA,AES128-SHA

# 说明

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

# listener.ssl.external.psk_ciphers

Type	Default
string	`PSK-AES128-CBC-SHA,PSK-AES256-CBC-SHA,PSK-3DES-EDE-CBC-SHA,PSK-RC4-SHA`

# 说明

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

# listener.ssl.external.secure_renegotiate

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

# listener.ssl.external.reuse_sessions

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

指定是否支持 SSL session 重用。详情见 http://erlang.org/doc/man/ssl.html (opens new window)。

# listener.ssl.external.honor_cipher_order

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.ssl.external.peer_cert_as_username

Type	Optional Value	Default
enum	`cn`, `dn`, `crt`, `pem`, `md5`	`cn`

# 说明

使用客户端证书来覆盖 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

Type	Optional Value	Default
enum	`cn`, `dn`, `crt`, `pem`, `md5`	`cn`

# 说明

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

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

# listener.ssl.external.backlog

Type	Default
integer	`1024`

# 说明

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

# listener.ssl.external.send_timeout

Type	Default
duration	`15s`

# 说明

TCP 报文发送超时时间。

# listener.ssl.external.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.ssl.external.recbuf

Type	Default
bytesize	-

# 说明

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

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

# listener.ssl.external.sndbuf

Type	Default
bytesize	-

# 说明

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

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

# listener.ssl.external.buffer

Type	Default
bytesize	-

# 说明

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

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

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

# listener.ssl.external.tune_buffer

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

# listener.ssl.external.nodelay

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# listener.ssl.external.reuseaddr

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# wsexternal

# listener.ws.external

Type	Default
string	`8083`

# 说明

配置名称为 external 的 MQTT/WS 监听器的监听地址，同时支持 IPv4 和 IPv6。

# 示例

如需配置 IPv4 地址，可参考如下格式：

0.0.0.0:8083：监听连接至 8083 端口的所有 IP 的活动。
127.0.0.1:8083：监听连接至 8083 端口、且 IP 地址为 127.0.0.1 网卡的活动。

如需配置 IPv6 地址，可参考如下格式：

::1:8083：监听连接至 8083 端口、且地址为 ::1 网卡上的活动。

# listener.ws.external.mqtt_path

Type	Default
string	`/mqtt`

# 说明

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

# listener.ws.external.acceptors

Type	Default
integer	`4`

# 说明

监听器的接收池大小。

# listener.ws.external.max_connections

Type	Default
integer	`102400`

# 说明

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

# listener.ws.external.max_conn_rate

Type	Default
integer	`1000`

# 说明

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

# listener.ws.external.active_n

Type	Default
integer	`100`

# 说明

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

# listener.ws.external.rate_limit

Type	Default
string	`100KB,10s`

# 说明

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

# 示例

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

# listener.ws.external.zone

Type	Default
string	`external`

# 说明

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

# listener.ws.external.access.1

Type	Default
string	`allow all`

# 说明

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

# listener.ws.external.fail_if_no_subprotocol

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# listener.ws.external.supported_protocols

Type	Default
string	`mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5`

# 说明

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

# listener.ws.external.proxy_address_header

Type	Optional Value	Default
string	`X-Forwarded-For`	-

# 说明

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

# listener.ws.external.proxy_port_header

Type	Optional Value	Default
string	`X-Forwarded-Port`	-

# 说明

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

# listener.ws.external.proxy_protocol

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

监听器是否开启 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

Type	Default
duration	-

# 说明

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

# listener.ws.external.backlog

Type	Default
integer	`1024`

# 说明

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

# listener.ws.external.send_timeout

Type	Default
duration	`15s`

# 说明

TCP 报文发送超时时间。

# listener.ws.external.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.ws.external.recbuf

Type	Default
bytesize	-

# 说明

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

# listener.ws.external.sndbuf

Type	Default
bytesize	-

# 说明

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

# listener.ws.external.buffer

Type	Default
bytesize	-

# 说明

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

# listener.ws.external.tune_buffer

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

# listener.ws.external.nodelay

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# listener.ws.external.compress

Type	Optional Value	Default
enum	`true`, `false`	-

# 说明

是否压缩 WebSocket 消息。压缩的实现依赖 zlib (opens new window)。

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

# listener.ws.external.deflate_opts.level

Type	Optional Value	Default
enum	`none`, `default`, `best_compression`, `best_speed`	-

# 说明

压缩等级。

# listener.ws.external.deflate_opts.mem_level

Type	Optional Value	Default
integer	1 - 9	-

# 说明

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

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

不配置，则默认为 8。

# listener.ws.external.deflate_opts.strategy

Type	Optional Value	Default
enum	`default`, `filtered`, `huffman_only`, `rle`	-

# 说明

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

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

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

# listener.ws.external.deflate_opts.server_context_takeover

Type	Optional Value	Default
enum	`takeover`, `no_takeover`	-

# 说明

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

# listener.ws.external.deflate_opts.client_context_takeover

Type	Optional Value	Default
enum	`takeover`, `no_takeover`	-

# 说明

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

# listener.ws.external.deflate_opts.server_max_window_bits

Type	Optional Value	Default
integer	8 - 15	-

# 说明

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

# listener.ws.external.deflate_opts.client_max_window_bits

Type	Optional Value	Default
integer	`8` - `15`	-

# 说明

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

# listener.ws.external.idle_timeout

Type	Default
duration	-

# 说明

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

# listener.ws.external.max_frame_size

Type	Default
integer	-

# 说明

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

# wssexternal

# listener.wss.external

Type	Default
string	`0.0.0.0:8084`

# 说明

配置名称为 external 的 WSS (MQTT/WebSocket/SSL) 监听器，同时支持 IPv4 和 IPv6。

# 示例

如需配置 IPv4 地址，可参考如下格式：

0.0.0.0:8084：监听连接至 8084 端口的所有 IP 的活动。
127.0.0.1:8084：监听连接至 8084 端口、且 IP 地址为 127.0.0.1 网卡的活动。

如需配置 IPv6 地址，可参考如下格式：

::1:8084：监听连接至 8084 端口、且地址为 ::1 网卡上的活动。

# listener.wss.external.mqtt_path

Type	Default
string	`/mqtt`

# 说明

WebSocket 的 URL Path。

# listener.wss.external.acceptors

Type	Default
integer	`4`

# 说明

监听器的接收池大小。

# listener.wss.external.max_connections

Type	Default
integer	`16`

# 说明

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

# listener.wss.external.max_conn_rate

Type	Default
integer	`1000`

# 说明

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

# listener.wss.external.active_n

Type	Default
integer	`100`

# 说明

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

# listener.wss.external.rate_limit

Type	Default
string	-

# 说明

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

# listener.wss.external.zone

Type	Default
string	`external`

# 说明

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

# listener.wss.external.access.1

Type	Default
string	`allow all`

# 说明

监听器的 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

1
2

# listener.wss.external.fail_if_no_subprotocol

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# listener.wss.external.supported_protocols

Type	Default
string	`mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5`

# 说明

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

# listener.wss.external.proxy_address_header

Type	Default
string	`X-Forwarded-For`

# 说明

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

# listener.wss.external.proxy_protocol

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

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

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

# listener.wss.external.proxy_protocol_timeout

Type	Default
duration	-

# 说明

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

# listener.wss.external.tls_versions

Type	Default
string	`tlsv1.3,tlsv1.2,tlsv1.1,tlsv1`

# 说明

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

# listener.wss.external.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

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

# listener.wss.external.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

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

# listener.wss.external.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

# listener.wss.external.depth

Type	Default
number	`10`

# 说明

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

# listener.wss.external.key_password

Type	Default
string	-

# 说明

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

# listener.wss.external.dhfile

Type	Default
string	`etc/certs/dh-params.pem`

# 说明

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

# listener.wss.external.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	`verify_peer`

# 说明

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

# listener.wss.external.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# listener.wss.external.ciphers

Type Default

# 说明

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

# listener.wss.external.psk_ciphers

Type	Default
string	`PSK-AES128-CBC-SHA,PSK-AES256-CBC-SHA,PSK-3DES-EDE-CBC-SHA,PSK-RC4-SHA`

# 说明

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

# listener.wss.external.secure_renegotiate

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

# listener.wss.external.reuse_sessions

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

指定是否支持 SSL session 重用。详情见 http://erlang.org/doc/man/ssl.html (opens new window)。

# listener.wss.external.honor_cipher_order

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.wss.external.peer_cert_as_username

Type	Optional Value	Default
enum	`cn`, `dn`, `crt`, `pem`, `md5`	`cn`

# 说明

使用客户端证书来覆盖 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

Type	Optional Value	Default
enum	`cn`, `dn`, `crt`, `pem`, `md5`	`cn`

# 说明

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

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

# listener.wss.external.backlog

Type	Default
integer	`1024`

# 说明

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

# listener.wss.external.send_timeout

Type	Default
duration	`15s`

# 说明

TCP 报文发送超时时间。

# listener.wss.external.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# listener.wss.external.recbuf

Type	Default
bytesize	-

# 说明

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

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

# listener.wss.external.sndbuf

Type	Default
bytesize	-

# 说明

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

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

# listener.wss.external.buffer

Type	Default
bytesize	-

# 说明

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

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

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

# listener.wss.external.tune_buffer

Type	Optional Value	Default
enum	`on`, `off`	-

# 说明

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

# listener.wss.external.nodelay

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# listener.wss.external.compress

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# listener.wss.external.deflate_opts.level

Type	Optional Value	Default
enum	`none`, `default`, `best_compression`, `best_speed`	`default`

# 说明

压缩等级。

# listener.wss.external.deflate_opts.mem_level

Type	Optional Value	Default
integer	1 - 9	-

# 说明

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

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

不配置，则默认为 8。

# listener.wss.external.deflate_opts.strategy

Type	Optional Value	Default
enum	`default`, `filtered`, `huffman_only`, `rle`	-

# 说明

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

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

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

# listener.wss.external.deflate_opts.server_context_takeover

Type	Optional Value	Default
enum	`takeover`, `no_takeover`	-

# 说明

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

# listener.wss.external.deflate_opts.client_context_takeover

Type	Optional Value	Default
enum	`takeover`, `no_takeover`	-

# 说明

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

# listener.wss.external.deflate_opts.server_max_window_bits

Type	Optional Value	Default
integer	8 - 15	-

# 说明

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

# listener.wss.external.deflate_opts.client_max_window_bits

Type	Optional Value	Default
integer	`8` - `15`	-

# 说明

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

# listener.wss.external.idle_timeout

Type	Default
duration	-

# 说明

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

# listener.wss.external.max_frame_size

Type	Default
integer	-

# 说明

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

# plugins

# plugins.etc_dir

Type	Default
string	`etc/plugins`

# 说明

插件的配置目录。

# plugins.loaded_file

Type	Default
string	`etc/loaded_plugins`

# 说明

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

# plugins.expand_plugins_dir

Type	Default
string	`plugins/`

# 说明

外部插件存放目录。

# broker

# broker.sys_interval

Type	Default
duration	`1m`

# 说明

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

# broker.sys_heartbeat

Type	Default
duration	`30s`

# 说明

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

"$SYS/brokers/<node>/uptime"
"$SYS/brokers/<node>/datetime"

# broker.enable_session_registry

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# broker.session_locking_strategy

Type	Optional Value	Default
enum	`local`, `leader`, `quorum`, `all`	`quorum`

# 说明

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

# broker.shared_subscription_strategy

Type	Optional Value	Default
enum	`hash_clientid`, `hash_topic`, `local`, `random`, `round_robin`, `sticky`,	`random`

# 说明

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

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

# broker.sample_group.shared_subscription_strategy

Type	Optional Value	Default
enum	`hash_clientid`, `hash_topic`, `local`, `random`, `round_robin`, `sticky`,	-

# 说明

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

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

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

# broker.shared_dispatch_ack_enabled

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# broker.route_batch_clean

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

# broker.perf.route_lock_type = key

Type	Optional Value	Default
enum	`key`, `tab`, `global`	`key`

# Description

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

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

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

# broker.perf.trie_compaction

Type	Optional Value	Default
enum	`true`, `false`	`false`

# Description

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

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

# monitor

# sysmon.long_gc

Type	Default
duration	`0ms`

# 说明

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

# sysmon.long_schedule

Type	Default
duration	`240ms`

# 说明

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

# sysmon.large_heap

Type	Default
bytesize	`8MB`

# 说明

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

# sysmon.busy_port

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# sysmon.busy_dist_port

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

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

# os_mon.cpu_check_interval

Type	Default
duration	`60s`

# 说明

CPU 占用率检查周期。

# os_mon.cpu_high_watermark

Type	Default
percent	`80%`

# 说明

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

# os_mon.cpu_low_watermark

Type	Default
percent	`60%`

# 说明

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

# os_mon.mem_check_interval

Type	Default
duration	`60s`

# 说明

内存占用率检查周期。

# os_mon.sysmem_high_watermark

Type	Default
percent	`70%`

# 说明

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

# os_mon.procmem_high_watermark

Type	Default
percent	`5%`

# 说明

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

# vm_mon.check_interval

Type	Default
duration	`30s`

# 说明

进程数量检查周期。

# vm_mon.process_high_watermark

Type	Default
percent	`80%`

# 说明

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

# vm_mon.process_low_watermark

Type	Default
percent	`60%`

# 说明

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

# 插件 `emqx-auth-http`

# auth.http.auth_req.url

Type	Default
string	`http://127.0.0.1:80/mqtt/auth`

# 说明

指定认证请求的目标 URL。

# auth.http.auth_req.method

Type	Optional Value	Default
enum	`get`, `post`	`post`

# 说明

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

# auth.http.auth_req.headers.<Any>

# 示例

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

1
2

# 说明

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

# auth.http.auth_req.params

Type	Format	Default
string	以 `,` 分隔的 `k=v` 键值对，`v` 可以是固定内容，也可以是占位符	`clientid=%c,username=%u,password=%P`

# 说明

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

占位符	替换内容
`%u`	用户名
`%c`	MQTT Client ID
`%a`	客户端的网络 IP 地址
`%r`	客户端使用的协议，可以是：`mqtt`, `mqtt-sn`, `coap`, `lwm2m` 以及 `stomp`
`%P`	密码
`%p`	客户端连接的服务端端口
`%c`	客户端证书中的 Common Name
`%d`	客户端证书中的 Subject

# auth.http.super_req.url

Type	Default
string	`http://127.0.0.1:80/mqtt/superuser`

# 说明

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

# auth.http.super_req.method

Type	Optional Value	Default
enum	`get`, `post`	`post`

# 说明

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

# auth.http.super_req.headers.<Any>

# 示例

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

1
2

# 说明

# auth.http.super_req.params

Type	Format	Default
string	以 `,` 分隔的 `k=v` 键值对，`v` 可以是固定内容，也可以是占位符	`clientid=%c,username=%u`

# 说明

指定超级用户认证请求中携带的数据。使用 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

Type	Default
string	`http://127.0.0.1:8991/mqtt/acl`

# 说明

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

# auth.http.acl_req.method

Type	Optional Value	Default
enum	`get`, `post`	`post`

# 说明

指定 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 = */*

1
2

# 说明

# auth.http.acl_req.params

Type	Format	Default
string	以 `,` 分隔的 `k=v` 键值对，`v` 可以是固定内容，也可以是占位符	`access=%A,username=%u,clientid=%c,ipaddr=%a,topic=%t,mountpoint=%m`

# 说明

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

占位符	替换内容
`%A`	需要验证的权限，1 表示订阅，2 表示发布
`%u`	MQTT Client ID
`%c`	客户端标识符
`%a`	客户端的网络 IP 地址
`%r`	客户端使用的协议，可以是：`mqtt`, `mqtt-sn`, `coap`, `lwm2m` 以及 `stomp`
`%m`	挂载点
`%t`	主题

# auth.http.timeout

Type	Default
duration	`5s`

# 说明

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

# auth.http.connect_timeout

Type	Default
duration	`5s`

# 说明

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

# auth.http.ssl.cacertfile

Type	Default
string	`etc/certs/ca.pem`

# 说明

CA 证书文件路径。

# auth.http.ssl.certfile

Type	Default
string	`etc/certs/client-cert.pem`

# 说明

客户端证书文件路径。

# auth.http.ssl.keyfile

Type	Default
string	`etc/certs/client.key.pem`

# 说明

客户端私钥文件路径。

# 插件 `emqx_auth_jwt`

# auth.jwt.secret

Type	Default
string	`emqxsecret`

# 说明

设置 HMAC Secret。

# auth.jwt.from

Type	Optional Value	Default
enum	`username`, `password`	`password`

# 说明

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

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

# auth.jwt.pubkey

Type	Default
string	`etc/certs/jwt_public_key.pem`

# 说明

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

# auth.jwt.verify_claims

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

启用或关闭 Claims 校验功能。

# auth.jwt.verify_claims.<claims>

Type	Default
string	-

# 说明

启用 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

Type	Default
string	`127.0.0.1`

# 说明

LDAP 服务地址。

# auth.ldap.port

Type	Default
integer	`389`

# 说明

LDAP 服务端口。

# auth.ldap.pool

Type	Optional Value	Default
integer	> `0`	`8`

# 说明

连接池大小。

# auth.ldap.bind_dn

Type	Default
string	`cn=root,dc=emqx,dc=io`

# 说明

登入 LDAP 服务的 DN。

# auth.ldap.bind_password

Type	Default
string	`public`

# 说明

登入 LDAP 服务的密码。

# auth.ldap.timeout

Type	Default
duration	`30s`

# 说明

查询操作的超时时间。

# auth.ldap.device_dn

Type	Default
string	`ou=device,dc=emqx,dc=io`

# 说明

客户端隶属的 DN。

# auth.ldap.match_objectclass

Type	Default
string	`mqttUser`

# 说明

客户端对象的名称。

# auth.ldap.username.attributetype

Type	Default
string	`uid`

# 说明

Username 属性的数据类型。

# auth.ldap.password.attributetype

Type	Default
string	`userPassword`

# 说明

Password 属性的数据类型。

# auth.ldap.ssl

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

是否开启 SSL。

# auth.ldap.ssl.certfile

Type	Default
string	-

# 说明

SSL 服务端证书路径。

# auth.ldap.ssl.keyfile

Type	Default
string	-

# 说明

SSL 服务端秘钥文件路径。

# auth.ldap.ssl.cacertfile

Type	Default
string	-

# 说明

CA 证书文件路径。

# auth.ldap.ssl.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	-

# 说明

SSL 认证方式：

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

# auth.ldap.ssl.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# 插件 `emqx_auth_mongo`

# auth.mongo.type

Type	Optional Value	Default
enum	`single`, `unknown`, `sharded`, `rs`	`single`

# 说明

设置 MongoDB 的拓扑类型:

single: 单节点
unknown: 未知
sharded: 分片模式
rs: 副本模式 (replicated set)

# auth.mongo.rs_set_name

Type	Default
string	`127.0.0.1:27017`

# 说明

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

# auth.mongo.pool

Type	Default
integer	`8`

# 说明

设置 MongoDB 连接池的进程数。

Type	Default
string	-

# 说明

设置 MongoDB 的用户名。

# auth.mongo.password

Type	Default
string	-

# 说明

设置 MongoDB 的密码。

# auth.mongo.auth_source

Type	Default
string	`mqtt`

# 说明

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

# auth.mongo.database

Type	Default
string	`mqtt`

# 说明

设置 MongoDB 的数据库名。

# auth.mongo.query_timeout

Type	Default
duration	`5s`

# 说明

设置访问 MongoDB 超时时间。

# auth.mongo.ssl

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

设置是否使用 SSL 访问 MongoDB。

# auth.mongo.ssl_opts.keyfile

Type	Default
string	-

# 说明

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

# auth.mongo.ssl_opts.certfile

Type	Default
string	-

# 说明

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

# auth.mongo.ssl_opts.cacertfile

Type	Default
string	-

# 说明

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

# auth.mongo.w_mode

Type	Optional Value	Default
enum	`unsafe`, `safe`, `undef`	`undef`

# 说明

设置 MongoDB 的写入模式。

# auth.mongo.r_mode

Type	Optional Value	Default
enum	`master`, `slave_ok`, `undef`	`undef`

# 说明

设置 MongoDB 的读取模式。

# auth.mongo.auth_query.collection

Type	Default
string	`mqtt_user`

# 说明

认证过程用的 Collection 名字。

# auth.mongo.auth_query.password_field

Type	Default
string	`password`

# 说明

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

auth.mongo.auth_query.password_field = password,salt

# auth.mongo.auth_query.password_hash

Type	Optional Value	Default
enum	`plain`, `md5`, `sha`, `sha256`, `bcrypt`	`sha256`

# 说明

设置密码字段用的哈希算法。如需在 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

Type	Default
string	`username=%u`

# 说明

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

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

# auth.mongo.auth_query.super_query

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

认证中是否使用 SuperUser。

# auth.mongo.super_query.collection

Type	Default
string	`mqtt_user`

# 说明

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

# auth.mongo.super_query.selector

Type	Default
string	`username=%u, clientid=%c`

# 说明

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

# auth.mongo.acl_query

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

是否开启 ACL 功能。

# auth.mongo.acl_query.collection

Type	Default
string	`mqtt_acl`

# 说明

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

# auth.mongo.acl_query.selector

Type	Default
string	`username=%u`

# 说明

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

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

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

1
2

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

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

# auth.mongo.topology.pool_size

Type	Default
integer	`1`

# 说明

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

# auth.mongo.topology.max_overflow

Type	Default
integer	`0`

# 说明

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

# auth.mongo.topology.overflow_ttl

Type	Default
integer	`1000`

# 说明

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

# auth.mongo.topology.overflow_check_period

Type	Default
integer	`1000`

# 说明

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

# auth.mongo.topology.local_threshold_ms

Type	Default
integer	`1000`

# 说明

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

# auth.mongo.topology.connect_timeout_ms

Type	Default
integer	`20000`

# 说明

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

# auth.mongo.topology.socket_timeout_ms

Type	Default
integer	`100`

# 说明

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

# auth.mongo.topology.server_selection_timeout_ms

Type	Default
integer	`30000`

# 说明

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

# auth.mongo.topology.wait_queue_timeout_ms

Type	Default
integer	`1000`

# 说明

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

# auth.mongo.topology.heartbeat_frequency_ms

Type	Default
integer	`10000`

# 说明

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

# auth.mongo.topology.min_heartbeat_frequency_ms

Type	Default
integer	`1000`

# 说明

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

# 插件 `emqx_auth_mysql`

# auth.mysql.server

Type	Default
ip	`127.0.0.1:3306`

# 说明

MySQL 服务器地址。

# auth.mysql.pool

Type	Default
integer	`8`

# 说明

数据库连接线程池大小。

# auth.mysql.username

Type	Default
string	-

# 说明

MySQL 用户名。

# auth.mysql.password

Type	Default
string	-

# 说明

MySQL 密码。

# auth.mysql.database

Type	Default
string	`mqtt`

# 说明

MySQL 数据库名称。

# auth.mysql.query_timeout

Type	Default
duration	`5s`

# 说明

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

# auth.mysql.auth_query

Type	Default
string	`select password from mqtt_user where username = '%u' limit 1`

# 说明

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

占位符	说明
`%u`	将被替换为 MQTT 客户端在 CONNECT 报文中指定的用户名
`%c`	将被替换为 MQTT 客户端在 CONNECT 报文中指定的客户端标识符
`%C`	将被替换为 TLS 连接时客户端证书中的 Common Name
`%d`	将被替换为 TLS 连接时客户端证书中的 Subject

# auth.mysql.password_hash

Type	Default
string	`sh256`

# 说明

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

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

Type	Default
string	`select is_superuser from mqtt_user where username = '%u' limit 1`

# 说明

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

# auth.mysql.acl_query

Type	Default
string	`select allow, ipaddr, username, clientid, access, topic from mqtt_acl where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'`

# 说明

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

占位符	说明
`%a`	将被替换为客户端 IP 地址
`%u`	将被替换为 MQTT 客户端在 CONNECT 报文中指定的用户名
`%c`	将被替换为 MQTT 客户端在 CONNECT 报文中指定的客户端标识符

# 插件 `emqx_auth_pgsql`

# auth.pgsql.server

Type	Default
ip	`127.0.0.1:5432`

# 说明

PostgreSQL 服务器地址。

# auth.pgsql.pool

Type	Default
integer	`8`

# 说明

数据库连接线程池大小。

# auth.pgsql.username

Type	Default
string	`root`

# 说明

PostgreSQL 用户名。

# auth.pgsql.password

Type	Default
string	-

# 说明

PostgreSQL 密码。

# auth.pgsql.database

Type	Default
string	`mqtt`

# 说明

PostgreSQL 数据库名称。

# auth.pgsql.encoding

Type	Default
string	`utf8`

# 说明

PostgreSQL 数据库字符编码格式。

# auth.pgsql.ssl

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

是否启用 TLS 连接。

# auth.pgsql.ssl_opts.keyfile

Type	Default
string	-

# 说明

客户端私钥文件路径。

# auth.pgsql.ssl_opts.certfile

Type	Default
string	-

# 说明

客户端证书文件路径。

# auth.pgsql.ssl_opts.cacertfile

Type	Default
string	-

# 说明

客户端 CA 证书文件路径。

# auth.pgsql.auth_query

Type	Default
string	`select password from mqtt_user where username = '%u' limit 1`

# 说明

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

# auth.pgsql.password_hash

Type	Default
string	`sh256`

# 说明

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

# auth.pgsql.super_query

Type	Default
string	`select is_superuser from mqtt_user where username = '%u' limit 1`

# 说明

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

# auth.pgsql.acl_query

Type	Default
string	`select allow, ipaddr, username, clientid, access, topic from mqtt_acl where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'`

# 说明

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

# 插件 `emqx_auth_redis`

# auth.redis.type

Type	Optional Value	Default
enum	`single`, `sentinel`, `cluster`	`single`

# 说明

Redis 服务集群类型：

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

# auth.redis.server

Type	Default
string	`127.0.0.1:6379`

# 说明

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

# auth.redis.sentinel

Type	Default
string	-

# 说明

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

# auth.redis.pool

Type	Optional Value	Default
integer	> `0`	`8`

# 说明

连接池大小。

# auth.redis.database

Type	Default
integer	`0`

# 说明

要连接的 Redis 数据库序号。

# auth.redis.password

Type	Default
string	-

# 说明

Redis 用户密码。

# auth.redis.query_timeout

Type	Default
duration	`5s`

# 说明

Redis 查询超时时间。

# auth.redis.auth_cmd

Type	Default
string	`HMGET mqtt_user:%u password`

# 说明

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

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

# auth.redis.password_hash

Type	Optional Value	Default
enum	`plain`, `md5`, `sha`, `sha256`, `bcrypt`	`plain`

# 说明

Redis 存储的 password 字段的编码格式。

# auth.redis.super_cmd

Type	Default
string	`HGET mqtt_user:%u is_superuser`

# 说明

超级用户查询命令，可用的占位符有：

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

# auth.redis.acl_cmd

Type	Default
string	`HGETALL mqtt_acl:%u`

# 说明

ACL 查询命令。可用的占位符有：

%u：客户端用户名。
%c：客户端标识。

# 插件 `emqx_bridge_mqtt`

# bridge.mqtt.aws.address

Type	Default
string	`127.0.0.1:1883`

# 说明

桥接地址，支持两种格式，例如：

emqx@192.168.0.100：EMQX 节点名称，它表示将该节点的消息桥接到另外一个 EMQX 节点。
192.168.0.100:1883：IP 地址和端口，它表示将该节点的消息通过一个 MQTT 连接桥接到另外一个 MQTT 服务器。

# bridge.mqtt.aws.proto_ver

Type	Optional Value	Default
enum	`mqttv3`, `mqttv4`, `mqttv5`	`mqttv4`

# 说明

MQTT 桥接的客户端协议版本。

# bridge.mqtt.aws.start_type

Type	Optional Value	Default
eunm	`manual`, `auto`	`manual`

# 说明

启动类型：

auto：跟随插件自动启动。
manual：手动启动桥接。

# bridge.mqtt.aws.bridge_mode

Type	Optional Value	Default
boolean	`true`, `false`	`true`

# 说明

是否开启桥接模式，仅 MQTT 桥接支持。开启后 emqx_bridge_mqtt 启动的 MQTT 客户端在发送连接报文时会携带一个标志位，标识这是一个桥接客户端。

注：RabbitMQ 目前不支持该标志。

# bridge.mqtt.aws.clientid

Type	Default
string	`bridge_aws`

# 说明

MQTT 桥接的客户端标识。

# bridge.mqtt.aws.clean_start

Type	Optional Value	Default
boolean	`true`, `false`	`true`

# 说明

MQTT 桥接的 clean_start 标志。它表示客户端是否以 清楚会话 的方式连接到远程 MQTT Broker。

# bridge.mqtt.aws.username

Type	Default
string	`user`

# 说明

MQTT 桥接客户端的用户名。

# bridge.mqtt.aws.password

Type	Default
string	`passwd`

# 说明

MQTT 桥接客户端的密码。

# bridge.mqtt.aws.forwards

Type	Default
string	`topic1/#,topic2/#`

# 说明

桥接转发规则。例如：

topic1/#, topic2/#：emqx_bridge_mqtt 会将 EMQX 中所以与 topic1/#，topic2/# 匹配的主题消息进行转发。

# bridge.mqtt.aws.forward_mountpoint

Type	Default
string	`bridge/aws/${node}/`

# 说明

转发主题的前缀。将消息转发到目标系统时，支持给该主题添加一个统一的前缀。

# bridge.mqtt.aws.subscription.1.topic

Type	Default
string	-

# 说明

订阅对端系统的主题。

# bridge.mqtt.aws.subscription.1.qos

Type	Optional Value	Default
enum	`0`, `1`, `2`	`1`

# 说明

订阅对端系统主题的 QoS。

# bridge.mqtt.aws.receive_mountpoint

Type	Default
string	`receive/aws/`

# 说明

接收消息的主题前缀。emqx_bridge_mqtt 支持给来着对端的消息添加一个统一的主题前缀。

# bridge.mqtt.aws.ssl

Type	Optional Value	Default
boolean	`true`, `false`	`true`

# 说明

MQTT 桥接客户端是否开启 SSL。

# bridge.mqtt.aws.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

MQTT 桥接客户端的 CA 证书文件路径。

# bridge.mqtt.aws.certfile

Type	Default
string	`etc/certs/client-cert.pem`

# 说明

MQTT 桥接客户端的 SSL 证书文件路径。

# bridge.mqtt.aws.keyfile

Type	Default
string	`etc/certs/client-key.pem`

# 说明

MQTT 桥接客户端的 SSL 秘钥文件路径。

# bridge.mqtt.aws.ciphers

Type	Default
string	`ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384`

# 说明

SSL 握手支持的加密套件。

# bridge.mqtt.aws.psk_ciphers

Type	Default
string	`PSK-AES128-CBC-SHA,PSK-AES256-CBC-SHA,PSK-3DES-EDE-CBC-SHA,PSK-RC4-SHA`

# 说明

SSL PSK 握手支持的加密套件。

# bridge.mqtt.aws.keepalive

Type	Default
duration	`60s`

# 说明

MQTT 桥接客户端的心跳间隔。

# bridge.mqtt.aws.tls_versions

Type	Default
string	`tlsv1.3,tlsv1.2,tlsv1.1,tlsv1`

# 说明

MQTT 桥接客户端的 SSL 版本。

# bridge.mqtt.aws.reconnect_interval

Type	Default
duration	`30s`

# 说明

重连间隔。

# bridge.mqtt.aws.retry_interval

Type	Default
duration	`20s`

# 说明

QoS 1/2 消息重发间隔。

# bridge.mqtt.aws.batch_size

Type	Default
integer	`32`

# 说明

EMQX 桥接的批处理大小。emqx_bridge_mqtt 的 EMQX 桥接模式支持批量发送消息以提搞吞吐。

# bridge.mqtt.aws.max_inflight_size

Type	Default
integer	`32`

# 说明

飞行窗口大小。

# bridge.mqtt.aws.queue.replayq_dir

Type	Default
string	`etc/emqx_aws_bridge/`

# 说明

设置消息队列文件路径。不配置则仅使用内存存储。

# bridge.mqtt.aws.queue.replayq_seg_bytes

Type	Default
bytesize	`10MB`

# 说明

消息队列存储在磁盘的单个文件大小。

# bridge.mqtt.aws.queue.max_total_size

Type	Default
bytesize	`5GB`

# 说明

消息队列允许存储的最大值。

# 插件 `emqx_coap`

# coap.port

Type	Default
integer	`5683`

# 说明

指定 CoAP 插件的 UDP 绑定端口。

# coap.enable_stats

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

启用或关闭 CoAP 的统计功能。

# coap.dtls.port

Type	Default
integer	`5684`

# 说明

指定 CoAP 插件的 DTLS 绑定端口。

# coap.dtls.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	`verify_peer`

# 说明

使用 DTLS 时，指定 DTLS 握手过程中是否校验客户端。

# coap.dtls.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

使用 DTLS 时，指定 DTLS 的私钥文件。

# coap.dtls.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

使用 DTLS 时，指定 DTLS 的证书文件。

# coap.dtls.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

使用 DTLS 时，指定 DTLS 的 CA 证书文件。

# coap.dtls.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# coap.dtls.ciphers

Type Default

# 说明

使用 DTLS 时，指定 DTLS 服务端支持的 Cipher 列表。

# 插件 `emqx_dashboard`

# dashboard.default_user.login`&`dashboard.default_user.password

Type	Default
string	-

# 说明

Dashboard 默认用户的认证数据。dashboard.default_user.login 与 dashboard.default_user.password 必须同时存在。

# dashboard.listener.http

Type	Default
integer	`18083`
string	`0.0.0.0:18083`

# 说明

HTTP 监听器的监听端口。
使用 ip:port 监听指定网卡端口。默认 0.0.0.0:18083 会监听所有网卡的 18083 端口。

# dashboard.listener.http.acceptors

Type	Default
integer	`4`

# 说明

此监听器将创建的监听进程数量。

# dashboard.listener.http.max_clients

Type	Default
integer	`512`

# 说明

此监听器允许同时建立的最大连接数量限制。

# dashboard.listener.http.inet6

Type	Optional Value	Default
enum	`ture`, `false`	`false`

# 说明

是否设置套接字允许 IPv6 连接。

# dashboard.listener.http.ipv6_v6only

Type	Optional Value	Default
enum	`ture`, `false`	`false`

# 说明

是否限制套接字仅使用 IPv6，禁止任何 IPv4 连接。仅适用于 IPv6 套接字，即仅在 dashboard.listener.http.inet6 被设置为 true 时此配置项的值有实际意义。需要注意的是，在某些操作系统上，例如 Windows，此配置项唯一允许的值为 true。

# dashboard.listener.https

Type	Default
integer	`18084`

# 说明

HTTPS 监听器的监听端口，默认此监听器被禁用。

# dashboard.listener.https.acceptors

Type	Default
integer	`2`

# 说明

同 dashboard.listener.http.acceptors。

# dashboard.listener.https.max_clients

Type	Default
integer	`512`

# 说明

同 dashboard.listener.http.max_clients。

# dashboard.listener.https.inet6

Type	Optional Value	Default
enum	`ture`, `false`	`false`

# 说明

同 dashboard.listener.http.inet6。

# dashboard.listener.https.ipv6_v6only

Type	Optional Value	Default
enum	`ture`, `false`	`false`

# 说明

同 dashboard.listener.http.ipv6_v6only。

# dashboard.listener.https.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

服务端私钥文件路径。

# dashboard.listener.https.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

服务端证书文件路径。

# dashboard.listener.https.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

# dashboard.listener.https.dhfile

Type	Default
string	`etc/certs/dh-params.pem`

# 说明

如果协商使用 Diffie Hellman 密钥交换的密码套件，则可以通过此配置项指定包含 PEM 编码的 Diffie Hellman 参数的文件路径。如果未指定，则使用默认参数。

# dashboard.listener.https.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	`verify_peer`

# 说明

verify_none 表示关闭对端证书验证，服务端不会向客户端发出证书请求。verify_peer 表示开启对端证书验证，服务端会向客户端发出证书请求。当此配置项被设置为 verify_peer 时，通常需要配合 dashboard.listener.https.fail_if_no_peer_cert 一起使用，以指定是否强制客户端提供证书。

# dashboard.listener.https.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`ture`, `false`	`true`

# 说明

必须配合 dashboard.listener.https.verify 一起使用。如果设置为 true，则服务端向客户端请求证书时如果客户端不提供证书将导致握手失败。如果设置为 false，则客户端即使不提供证书也能握手成功。

# dashboard.listener.https.tls_versions

Type	Default
string	`tlsv1.3,tlsv1.2,tlsv1.1,tlsv1`

# 说明

指定服务端支持的 TLS 协议版本，版本之间由 , 分隔，支持的 TLS 协议版本有： tlsv1.3, tlsv1.2, tlsv1.1, tlsv1, sslv3。

# dashboard.listener.https.ciphers

Type Default

# 说明

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

# dashboard.listener.https.secure_renegotiate

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

指定是否启动安全重协商机制。

# dashboard.listener.https.reuse_sessions

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

指定是否启用会话复用机制。

# dashboard.listener.https.honor_cipher_order

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

如果设置为 on，则使用服务器的首选项进行密码选择。如果设置为 off，则使用客户端的首选项。

# 插件 `emqx_lwm2m`

# lwm2m.port

Type	Default
integer	`5683`

# 说明

指定 LwM2M 使用的 UDP 端口。

# lwm2m.lifetime_min

Type	Default
duration	`1s`

# 说明

指定允许的 LwM2M lifetime 最小值，单位: 秒。

# lwm2m.lifetime_max

Type	Default
duration	`86400s`

# 说明

指定允许的 LwM2M lifetime 最大值，单位: 秒。

# lwm2m.qmode_time_window

Type	Default
integer	`22`

# 说明

指定 LwM2M Q 模式使用的窗口大小，单位: 秒。

这个窗口期之内可以下发执行给 Q 模式的设备，过了窗口期则缓存下行数据。

# lwm2m.lb

Type	Optional Value	Default
enum	`coaproxy`, `undefined`	`undefined`

# 说明

设置是否使用 coaproxy。设置为 undefined 则不使用 coaproxy。

# lwm2m.auto_observe

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

在设备注册后是否自动下发 observe 命令。

# lwm2m.mountpoint

Type	Default
string	`lwm2m/%e/`

# 说明

设置 LwM2M 主题的挂载点。支持以下通配符:

'%e': Endpoint Name
'%a': IP Address

# lwm2m.topics.command

Type	Default
string	`dn/#`

# 说明

设备注册完成后，需要订阅的下行命令主题。

# lwm2m.topics.response

Type	Default
string	`up/resp`

# 说明

设备的上行回复需要发布到哪个主题。

# lwm2m.topics.notify

Type	Default
string	`up/notify`

# 说明

设备的上行报告消息 (notify) 需要发布到哪个主题。

# lwm2m.topics.register

Type	Default
string	`up/resp`

# 说明

设备的上行注册消息 (register) 需要发布到哪个主题。

# lwm2m.topics.update

Type	Default
string	`up/resp`

# lwm2m.update_msg_publish_condition

Type	Optional Value	Default
enum	`contains_object_list`, `always`	`contains_object_list`

# Description

发布 UPDATE 事件的条件。可以为下列两种之一：

contains_object_list: 仅当 UPDATE 消息包含 object list 时发布
always: 总是发布

# 说明

设备的上行更新消息 (update) 需要发布到哪个主题。

# lwm2m.opts.buffer

Type	Default
bytesize	`1024KB`

# 说明

UDP 调优参数，指定 UDP 用户态缓存大小。

# lwm2m.opts.recbuf

Type	Default
bytesize	`1024KB`

# 说明

UDP 调优参数，指定 UDP 接收缓存大小。

# lwm2m.opts.sndbuf

Type	Default
bytesize	`1024KB`

# 说明

UDP 调优参数，指定 UDP 发送缓存大小。

# lwm2m.opts.read_packets

Type	Default
integer	`20`

# 说明

UDP 调优参数，指定每次从 UDP socket 读取多少个报文。

# lwm2m.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

指定 UDP DTLS 使用的证书文件。

# lwm2m.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

指定 UDP DTLS 使用的私钥文件。

# lwm2m.xml_dir

Type	Default
dir	`etc/lwm2m_xml`

# 说明

指定 LwM2M Object 定义文件存放的目录。

# 插件 `emqx_management`

# management.max_row_limit

Type	Default
integer	`10000`

# 说明

分页查询时返回的最大记录数量。

# management.default_application.id

Type	Default
string	`admin`

# 说明

默认应用的 AppId。

# management.default_application.secret

Type	Default
string	`public`

# 说明

默认应用的 AppSecret。

# management.listener.http

Type	Default
integer	`8081`
string	`0.0.0.0:8081`

# 说明

HTTP 监听器的监听端口。
使用 ip:port 监听指定网卡端口。默认 0.0.0.0:8081 会监听所有网卡的 8081 端口。

# management.listener.http.acceptors

Type	Default
integer	`2`

# 说明

此监听器将创建的监听进程数量。

# management.listener.http.max_clients

Type	Default
integer	`512`

# 说明

此监听器允许同时建立的最大连接数量限制。

# management.listener.http.backlog

Type	Default
integer	`512`

# 说明

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

# management.listener.http.send_timeout

Type	Default
duration	`15s`

# 说明

HTTP 报文发送超时时间。

# management.listener.http.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# management.listener.http.inet6

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

是否设置套接字允许 IPv6 连接。

# management.listener.http.ipv6_v6only

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

是否限制套接字仅使用 IPv6，禁止任何 IPv4 连接。仅适用于 IPv6 套接字，即仅在 management.listener.http.inet6 被设置为 true 时此配置项的值有实际意义。需要注意的是，在某些操作系统上，例如 Windows，此配置项唯一允许的值为 true。

# management.listener.https

Type	Default	Example
integer	-	`8081`
string	-	`0.0.0.0:8081`

# 说明

HTTPS 监听器的监听端口。
使用 ip:port 监听指定网卡端口。默认 0.0.0.0:8081 会监听所有网卡的 8081 端口。

# management.listener.https.acceptors

Type	Default
integer	`2`

# 说明

此监听器将创建的监听进程数量。

# management.listener.https.max_clients

Type	Default
integer	`512`

# 说明

此监听器允许同时建立的最大连接数量限制。

# management.listener.https.backlog

Type	Default
integer	`512`

# 说明

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

# management.listener.https.send_timeout

Type	Default
duration	`15s`

# 说明

HTTPS 报文发送超时时间。

# management.listener.https.send_timeout_close

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

# management.listener.https.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

服务端私钥文件路径。

# management.listener.https.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

服务端证书文件路径。

# management.listener.https.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

# management.listener.https.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	`verify_peer`

# 说明

verify_none 表示关闭对端证书验证，服务端不会向客户端发出证书请求。verify_peer 表示开启对端证书验证，服务端会向客户端发出证书请求。当此配置项被设置为 verify_peer 时，通常需要配合 management.listener.https.fail_if_no_peer_cert 一起使用，以指定是否强制客户端提供证书。

# management.listener.https.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`ture`, `false`	`true`

# 说明

必须配合 management.listener.https.verify 一起使用。如果设置为 true，则服务端向客户端请求证书时如果客户端不提供证书将导致握手失败。如果设置为 false，则客户端即使不提供证书也能握手成功。

# management.listener.https.inet6

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

是否设置套接字允许 IPv6 连接。

# management.listener.https.ipv6_v6only

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

是否限制套接字仅使用 IPv6，禁止任何 IPv4 连接。仅适用于 IPv6 套接字，即仅在 management.listener.https.inet6 被设置为 true 时此配置项的值有实际意义。需要注意的是，在某些操作系统上，例如 Windows，此配置项唯一允许的值为 true。

# 插件`emqx_retainer`

# retainer.storage_type

Type	Optional Value	Default
enum	`ram`, `disc`, `disc_only`	`ram`

# 说明

保留消息的存储类型，以下选项可用：

ram

保留消息仅存储在内存中。

disc

保留消息同时存储在内存和磁盘中。

disc_only

保留消息仅存储在磁盘中。

# retainer.max_retained_messages

Type	Default
integer	`0`

# 说明

保留消息的存储数量限制。一旦存储数量达到限制，可以替换已存在的保留消息，但不能为新的主题存储保留消息。0 表示没有限制。

# retainer.max_payload_size

Type	Default
bytesize	`1MB`

# 说明

允许存储的保留消息的 Payload 最大长度限制。如果 Payload 超出最大限制，该保留消息可以被正常处理，但不会存储在服务端。

# retainer.expiry_interval

Type	Default
duration	`0`

# 说明

保留消息的过期间隔，仅对协议版本低于 MQTT v5.0 的客户端生效，MQTT v5.0 客户端的保留消息过期间隔将以 Message Expiry Interval 的值为准。0 表示永不过期。

# 插件`emqx_rule_engine`

# rule-engine.ignore_sys_message

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

忽略系统消息 ($SYS)。启用此选项规则引擎将不会处理系统消息。

# rule-engine.events.<event-name>

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

设置是否发布事件消息。可指定事件消息的 QoS，例如:

rule-engine.events.client_connected = on, qos1

1
2

若启用此选项，规则引擎会将系统消息使用 $events/<event-name> 主题发布出来。可支持的 <event-name> 有:

client_connected: 客户端登录完成
client_disconnected: 客户端下线
session_subscribed: 客户端订阅
session_unsubscribed: 客户端取消订阅
message_delivered: 消息已投递
message_acked: 消息已确认
message_dropped: 消息被丢弃

如果禁用此选项，事件消息将不会发布，但事件规则仍然可以使用。例如，即使 rule_engine.events.client_connected = off，以下规则仍然可以使用:

SELECT * FROM "$events/client_connected"

# 插件 `emqx_sn`

# mqtt.sn.port

Type	Default
string	`1884`

# 说明

emqx_sn 监听的 UDP 端口。

# mqtt.sn.advertise_duration

Type	Default
duration	`15s`

# 说明

ADVERTISE 消息广播间隔，单位：秒。

# mqtt.sn.gateway_id

Type	Default
integer	`1`

# 说明

ADVERTISE 中的 MQTT-SN 网关 ID。

# mqtt.sn.enable_stats

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

# mqtt.sn.enable_qos3

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

是否处理 QoS 为 -1 的消息。

# mqtt.sn.idle_timeout

Type	Default
duration	`30s`

# 说明

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

# mqtt.sn.predefined.topic.0

Type	Default
string	`reserved`

# 说明

预定义的 Topic 与 TopicId 映射。Id 为 0 的主题是保留项，固定为 reserved。例如，预定义主题 foo/bar 的 Id 为 1：

mqtt.sn.predefined.topic.1 = foo/bar

# mqtt.sn.username

Type	Default
string	`mqtt_sn_user`

# 说明

emqx_sn 连接至 EMQX 的用户名。

# mqtt.sn.password

Type	Default
string	`abc`

# 说明

emqx_sn 连接至 EMQX 的密码。

# 插件 `emqx_prometheus`

# prometheus.push.gateway.server

Type	Default
string	`http://127.0.0.1:9091`

# 说明

指定 Prometheus gateway 的 URI。

# prometheus.interval

Type	Default
integer	`15000`

# 说明

指定 Stats 数据的收集间隔，单位: 毫秒。

# prometheus.collector.<N>

Type	Default
string	`emqx_prometheus`

# 说明

指定 Prometheus 的 Collector。

# 插件 `emqx_stomp`

# stomp.listener

Type	Default
integer	`61613`

# 说明

指定 Stomp 插件监听的本地端口。

# stomp.listener.acceptors

Type	Default
integer	`4`

# 说明

指定 Stomp 服务 Acceptor 线程池的大小。

# stomp.listener.max_connections

Type	Default
integer	`512`

# 说明

指定 Stomp 服务支持的最大连接数。

# stomp.listener.ssl

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

指定是否使用 SSL。

# stomp.listener.keyfile

Type	Default
string	`etc/certs/key.pem`

# 说明

若使用 SSL，指定 SSL 的私钥文件。

# stomp.listener.certfile

Type	Default
string	`etc/certs/cert.pem`

# 说明

若使用 SSL，指定 SSL 的证书文件。

# stomp.listener.cacertfile

Type	Default
string	`etc/certs/cacert.pem`

# 说明

若使用 SSL，指定 SSL 的 CA 证书文件。

# stomp.listener.dhfile

Type	Default
string	`etc/certs/dh-params.pem`

# 说明

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

# stomp.listener.verify

Type	Optional Value	Default
enum	`verify_peer`, `verify_none`	`verify_peer`

# 说明

若使用 SSL，指定握手过程中是否校验客户端。

# stomp.listener.fail_if_no_peer_cert

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

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

# stomp.listener.tls_versions

Type	Default
string	`tlsv1.2,tlsv1.1,tlsv1`

# 说明

若使用 SSL，指定服务端支持的 SSL 的版本列表。

# stomp.listener.handshake_timeout

Type	Default
duration	`15s`

# 说明

若使用 SSL，指定 SSL 握手过程的超时时间。

# stomp.listener.ciphers

Type Default

# 说明

若使用 SSL，指定服务端支持的 Cipher 列表。

# stomp.listener.secure_renegotiate

Type	Optional Value	Default
enum	`on`, `off`	`off`

# 说明

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

# stomp.listener.reuse_sessions

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

若使用 SSL，指定是否支持 SSL session 重用。

# stomp.listener.honor_cipher_order

Type	Optional Value	Default
enum	`on`, `off`	`on`

# 说明

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

Type	Default
string	`guest`

# 说明

指定 Stomp 插件登录使用的 Username。

# stomp.default_user.passcode

Type	Default
string	`guest`

# 说明

指定 Stomp 插件登录使用的 Password。

# stomp.allow_anonymous

Type	Optional Value	Default
enum	`true`, `false`	`true`

# 说明

是否允许匿名登录。

# stomp.frame.max_headers

Type	Default
integer	`10`

# 说明

指定 Stomp 最大报文头数量。

# stomp.frame.max_header_length

Type	Default
integer	`1024`

# 说明

指定 Stomp 最大报文头长度。

# stomp.frame.max_body_length

Type	Default
integer	`8192`

# 说明

指定 Stomp 最大报文体长度。

# 插件`emqx_web_hook`

# web.hook.url

Type	Default
string	http://127.0.0.1:80

# 说明

Webhook 请求转发的目的 Web 服务器地址。

# web.hook.headers.<Any>

# 示例

web.hook.headers.content-type = application/json
web.hook.headers.accept = */*

1
2

# 说明

# web.hook.encoding_of_payload_field

Type	Optional Value	Default
enum	`plain`, `base62`, `base64`	`plain`

# 说明

PUBLISH 报文中 Payload 字段的编码格式。

# web.hook.ssl.cacertfile

Type	Default
string	-

# 说明

CA 证书文件路径。

# web.hook.ssl.certfile

Type	Default
string	-

# 说明

客户端证书文件路径。

# web.hook.ssl.keyfile

Type	Default
string	-

# 说明

客户端私钥文件路径。

# web.hook.ssl.verify

Type	Optional Value	Default
enum	`true`, `false`	`false`

# 说明

指定是否校验对端证书。

# web.hook.ssl.pool_size

Type	Default
integer	`32`

# 说明

HTTP 连接进程池大小。

# web.hook.rule.client.connect.1

Type	Default
string	`{"action": "on_client_connect"}`

# 说明

转发 收到连接报文 事件。

# web.hook.rule.client.connack.1

Type	Default
string	`{"action": "on_client_connack"}`

# 说明

转发 下发连接应答 事件。

# web.hook.rule.client.connected.1

Type	Default
string	`{"action": "on_client_connected"}`

# 说明

转发 客户端成功接入 事件。

# web.hook.rule.client.disconnected.1

Type	Default
string	`{"action": "on_client_disconnected"}`

# 说明

转发 客户端已断开 事件。

Type	Default
string	`{"action": "on_client_subscribe"}`

# 说明

转发 将订阅 事件。

# web.hook.rule.client.unsubscribe.1

Type	Default
string	`{"action": "on_client_unsubscribe"}`

# 说明

转发 将取消订阅 事件。

# web.hook.rule.session.subscribed.1

Type	Default
string	`{"action": "on_session_subscribed"}`

# 说明

转发 已订阅 事件。

# web.hook.rule.session.unsubscribed.1

Type	Default
string	`{"action": "on_session_unsubscribed"}`

# 说明

转发 已取消订阅 事件。

# web.hook.rule.session.terminated.1

Type	Default
string	`{"action": "on_session_terminated"}`

# 说明

转发 会话已终止 事件。

# web.hook.rule.message.publish.1

Type	Default
string	`{"action": "on_message_publish"}`

# 说明

转发 消息发布 事件。

# web.hook.rule.message.delivered.1

Type	Default
string	`{"action": "on_message_delivered"}`

# 说明

转发 消息已投递 事件。

# web.hook.rule.message.acked.1

Type	Default
string	`{"action": "on_message_acked"}`

# 说明

转发 消息已应答 事件。

# license.file

Type	Default
string	`etc/emqx.lic`

# 说明

企业版证书存放的路径。

### license.connection_high_watermark_alarm

Type	Default
percent	`80%`

# 说明

连接数高水位线告警，达到企业版证书允许实时在线连接数的百分比。超出水位线时会产生告警，不影响实际使用，

发生告警后，可以参照[如何更新证书？](../faq/use-guide.md#怎样更新 EMQX license?)进行热更新。
当连接数超过最大允许值时，新客户端会被拒绝连接，已连接的客户端不受影响。

### license.connection_low_watermark_alarm

Type	Default
percent	`75%`

# 说明

连接数低水位线告警，低于达到企业版证书允许实时在线连接数的百分比则解除告警。

← HTTP API 环境变量 →

# 配置项

# Cluster

# cluster.name

# 说明

# cluster.proto_dist

# 说明

# cluster.discovery

# 说明

# cluster.autoheal

# 说明

# cluster.autoclean

# 说明

# cluster.static.seeds

# 说明

# cluster.mcast.addr

# 说明

# cluster.mcast.ports

# 说明

# cluster.mcast.iface

# 说明

# cluster.mcast.ttl

# 说明

# cluster.mcast.loop

# 说明

# cluster.dns.name

# 说明

# 示例

# cluster.dns.app

# 说明

# cluster.etcd.server

# 说明

# cluster.etcd.prefix

# 说明

# cluster.etcd.node_ttl

# 说明

# cluster.etcd.ssl.keyfile

# 说明

# cluster.etcd.ssl.certfile

# 说明

# cluster.etcd.ssl.cacertfile

# 说明

# cluster.k8s.apiserver

# 说明

# cluster.k8s.service_name

# 说明

# cluster.k8s.address_type

# 说明

# 示例

# cluster.k8s.app_name

# 说明

# cluster.k8s.suffix

# 说明

# cluster.k8s.namespace

# 说明

# 示例

# Node

# node.name

# 说明

# node.cookie

# 说明

# node.data_dir

# 说明

# node.heartbeat

# 说明

# node.async_threads

# 说明

# node.process_limit

# 说明

# node.max_ports

# 说明

# node.dist_buffer_size

# 说明

# node.max_ets_tables

# 说明

# node.global_gc_interval

# 说明

# node.fullsweep_after

# 说明

# node.crash_dump

# 说明