配置项

Cluster

cluster.name

TypeDefault
stringemqxcl

说明

集群名称。

cluster.proto_dist

TypeOptional ValueDefault
enuminet_tcp, inet6_tcp, inet_tlsinet_tcp

说明

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

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

cluster.discovery

TypeOptional ValueDefault
enummanual, static, mcast, dns, etcd, k8smanual

说明

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

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

cluster.autoheal

TypeOptional ValueDefault
enumon, offon

说明

启用或关闭集群脑裂自动恢复机制。

cluster.autoclean

TypeDefault
duration5m

说明

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

cluster.static.seeds

TypeDefaultExample
string-emqx1@192.168.0.100,emqx2@192.168.0.101

说明

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

cluster.mcast.addr

TypeDefault
ipaddr239.192.0.1

说明

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

cluster.mcast.ports

TypeDefault
string4369

说明

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

cluster.mcast.iface

TypeDefault
ipaddr0.0.0.0

说明

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

cluster.mcast.ttl

TypeDefault
integer255

说明

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

cluster.mcast.loop

TypeOptional ValueDefault
enumon, offon

说明

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

cluster.dns.name

TypeDefaultExample
string-mycluster.com

说明

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

示例

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

  1. 192.168.0.100
  2. 192.168.0.101
  3. 192.168.0.102

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

  1. emqx@192.168.0.100
  2. emqx@192.168.0.101
  3. emqx@192.168.0.102

cluster.dns.app

TypeDefaultExample
string-emqx

说明

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

cluster.etcd.server

TypeDefaultExample
string-http://127.0.0.1:2379

说明

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

cluster.etcd.prefix

TypeDefaultExample
string-emqxcl

说明

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

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

cluster.etcd.node_ttl

TypeDefaultExample
duration-1m

说明

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

cluster.etcd.ssl.keyfile

TypeDefaultExample
string-etc/certs/client-key.pem

说明

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

cluster.etcd.ssl.certfile

TypeDefaultExample
string-etc/certs/client.pem

说明

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

cluster.etcd.ssl.cacertfile

TypeDefaultExample
string-etc/certs/ca.pem

说明

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

cluster.k8s.apiserver

TypeDefaultExample
string-http://10.110.111.204:8080

说明

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

cluster.k8s.service_name

TypeDefaultExample
string-emqx

说明

当使用 k8s 方式集群时,指定 Kubernetes 中 EMQ X 的服务名。

cluster.k8s.address_type

TypeOptional ValueDefault
enumip, dns, hostnameip

说明

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

示例

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

  1. 172.16.122.31
  2. 172.16.122.32
  3. 172.16.122.33

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

  1. emqx@172.16.122.31
  2. emqx@172.16.122.32
  3. emqx@172.16.122.33

cluster.k8s.app_name

TypeDefaultExample
string-emqx

说明

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

cluster.k8s.suffix

TypeDefaultExample
string-pod.cluster.local

说明

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

cluster.k8s.namespace

TypeDefaultExample
string-default

说明

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

示例

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

  1. 172-16-122-31
  2. 172-16-122-32
  3. 172-16-122-33

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

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

Node

node.name

TypeDefault
stringemqx@127.0.0.1

说明

节点名。格式为 <name>@<host>。其中 <host> 可以是 IP 地址,也可以是 FQDN。详见 http://erlang.org/doc/reference_manual/distributed.html参数配置列表 - 图1 (opens new window)

node.cookie

TypeDefault
stringemqxsecretcookie

说明

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

node.data_dir

TypeDefault
folder./data

说明

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

node.heartbeat

TypeOptional ValueDefault
enumon, offoff

说明

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

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

node.async_threads

TypeOptional ValueDefault
integer0 - 10244

说明

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

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

node.process_limit

TypeOptional ValueDefault
integer1024 - 1342177272097152

说明

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

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

node.max_ports

TypeOptional ValueDefault
integer1024 - 1342177271048576

说明

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

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

node.dist_buffer_size

TypeOptional ValueDefault
bytesize1KB - 2GB8MB

说明

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

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

node.max_ets_tables

TypeDefault
integer262144

说明

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

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

node.global_gc_interval

TypeDefault
duration15m

说明

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

node.fullsweep_after

TypeOptional ValueDefault
integer0 - 655351000

说明

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

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

node.crash_dump

TypeDefault
stringlog/crash.dump

说明

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

node.ssl_dist_optfile

TypeDefault
stringetc/ssl_dist.conf

说明

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

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

node.dist_net_ticktime

TypeDefault
integer120

说明

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

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

node.dist_listen_min

TypeOptional ValueDefault
integer1024 - 655356369

说明

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

node.dist_listen_max

TypeOptional ValueDefault
integer1024 - 655356369

说明

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

RPC

rpc.mode

TypeOptional ValueDefault
enumsync, asyncasync

说明

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

rpc.async_batch_size

TypeDefault
integer256

说明

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

rpc.port_discovery

TypeOptional Value Default
enummanual, 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.

node.tcp_server_port

TypeOptional ValueDefault
integer1024 - 655355369

说明

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

rpc.tcp_client_num

TypeOptional ValueDefault
integer1 - 256CPU 核心数 / 2

说明

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

rpc.connect_timeout

TypeDefault
duration5s

说明

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

rpc.send_timeout

TypeDefault
duration5s

说明

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

rpc.authentication_timeout

TypeDefault
duration5s

说明

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

rpc.call_receive_timeout

TypeDefault
duration15s

说明

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

rpc.socket_keepalive_idle

TypeDefault
duration900s

说明

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

rpc.socket_keepalive_interval

TypeDefault
duration75s

说明

发送 keepalive 探测报文的间隔。

rpc.socket_keepalive_count

TypeDefault
integer9

说明

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

rpc.socket_sndbuf

TypeDefault
bytesize1MB

说明

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

rpc.socket_recbuf

TypeDefault
bytesize1MB

说明

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

rpc.socket_buffer

TypeDefault
bytesize1MB

说明

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

Log

log.to

TypeOptional ValueDefault
enumoff, file, console, bothboth

说明

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

  • off: 完全关闭日志功能

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

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

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

log.level

TypeOptional ValueDefault
enumdebug, info, notice, warning
error, critical, alert, emergency
warning

说明

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

log.dir

TypeDefault
dir./log

说明

日志文件目录。

log.file

TypeDefault
stringemqx.log

说明

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

log.chars_limit

TypeDefault
integer-1

说明

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

log.rotation.size

TypeDefault
bytesize10MB

说明

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

log.rotation.count

TypeDefault
integer5

说明

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

log..file

TypeDefault
string-

说明

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

示例

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

  1. log.info.file = info.log

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

  1. log.error.file = error.log

log.max_depth

TypeDefault
integer20

说明

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

log.single_line

TypeDefault
booleantrue

说明

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

log.formatter

TypeOptional ValueDefault
enumtext, jsontext

说明

选择打印日志的格式

authacl

allow_anonymous

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

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

acl_nomatch

TypeOptional ValueDefault
enumallow, denyallow

说明

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

acl_file

TypeDefault
stringetc/acl.conf

说明

默认 ACL 文件的路径。

enable_acl_cache

TypeOptional ValueDefault
enumon, offon

说明

是否启用 ACL 缓存。

acl_cache_max_size

TypeDefault
integer32

说明

ACL 规则最大缓存条数。

acl_cache_ttl

TypeDefault
duration1m

说明

ACL 规则最大缓存时间。

acl_deny_action

TypeOptional ValueDefault
enumignore, disconnectignore

说明

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

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

mqtt

flapping_detect_policy

TypeDefault
string30, 1m, 5m

说明

指定 Flapping 检查策略。

格式:<threshold>,<duration>,<banned>

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

mqtt.max_packet_size

TypeDefault
bytesize1MB

说明

允许的 MQTT 报文最大长度。

mqtt.max_clientid_len

TypeDefault
integer65535

说明

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

mqtt.max_topic_levels

TypeDefault
integer0

说明

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

mqtt.max_qos_allowed

TypeOptional ValueDefault
enum0, 1, 22

说明

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

mqtt.max_topic_alias

TypeDefault
integer65535

说明

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

mqtt.retain_available

TypeOptional ValueDefault
enumtrue, falsetrue

说明

是否支持 Retain 消息。

mqtt.wildcard_subscription

TypeOptional ValueDefault
enumtrue, falsetrue

说明

是否支持订阅通配主题。

mqtt.shared_subscription

TypeOptional ValueDefault
enumtrue, falsetrue

说明

是否支持共享订阅。

mqtt.ignore_loop_deliver

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

mqtt.strict_mode

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

zoneexternal

zone.external.idle_timeout

TypeDefault
duration15s

说明

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

zone.external.enable_acl

TypeOptional ValueDefault
enumon, offon

说明

是否开启 ACL 检查。

zone.external.enable_ban

TypeOptional ValueDefault
enumon, offon

说明

是否开启黑名单。

zone.external.enable_stats

TypeOptional ValueDefault
enumon, offon

说明

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

zone.external.acl_deny_action

| Type | Optional Value | Default | | —— | —————————— - | ———— | | enum | ignore, disconnect | ignore |

说明

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

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

zone.external.force_gc_policy

TypeDefault
string16000|16MB

说明

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

格式:<Number>|<Bytes>

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

zone.external.force_shutdown_policy

TypeDefault
string-

说明

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

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

格式:<Number>|<Bytes>

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

zone.external.max_packet_size

TypeDefault
bytesize-

说明

允许的 MQTT 报文最大长度。

zone.external.max_clientid_len

TypeDefault
integer-

说明

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

zone.external.max_topic_levels

TypeDefault
integer-

说明

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

zone.external.max_qos_allowed

TypeOptional ValueDefault
enum0, 1, 2-

说明

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

zone.external.max_topic_alias

TypeDefault
integer-

说明

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

zone.external.retain_available

TypeOptional ValueDefault
enumtrue, false-

说明

是否支持 Retain 消息。

zone.external.wildcard_subscription

TypeOptional ValueDefault
enumtrue, false-

说明

是否支持订阅通配主题。

zone.external.shared_subscription

TypeOptional ValueDefault
enumtrue, false-

说明

是否支持共享订阅。

zone.external.server_keepalive

TypeDefault
integer-

说明

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

zone.external.keepalive_backoff

TypeOptional ValueDefault
float> 0.50.75

说明

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

zone.external.max_subscriptions

TypeDefault
integer0

说明

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

zone.external.upgrade_qos

TypeOptional ValueDefault
enumon, offoff

说明

允许 EMQ X 在投递消息时,强制升级消息的 QoS 等级为订阅的 QoS 等级。

zone.external.max_inflight

TypeDefault
integer32

说明

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

zone.external.retry_interval

TypeDefault
duration30s

说明

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

zone.external.max_awaiting_rel

TypeDefault
integer100

说明

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

zone.external.await_rel_timeout

TypeDefault
duration300s

说明

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

zone.external.session_expiry_interval

TypeDefault
duration2h

说明

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

zone.external.max_mqueue_len

TypeDefault
integer1000

说明

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

zone.external.mqueue_priorities

TypeOptional ValueDefault
stringnone, <Spec>none

说明

队列消息优先级配置:

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

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

zone.external.mqueue_default_priority

TypeOptional ValueDefault
enumhighest, lowesthighest

说明

消息默认的优先等级。

zone.external.mqueue_store_qos0

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

zone.external.enable_flapping_detect

TypeOptional ValueDefault
enumon, offoff

说明

是否开启 Flapping 检查。

zone.external.mountpoint

TypeDefault
string-

说明

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

其中可用的占位符有:

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

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

zone.external.use_username_as_clientid

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

zone.external.ignore_loop_deliver

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

zone.external.strict_mode

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

zoneinternal

zone.internal.allow_anonymous

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

zone.internal.enable_stats

TypeOptional ValueDefault
enumon, offon

说明

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

zone.internal.enable_acl

TypeOptional ValueDefault
enumon, offoff

说明

是否开启 ACL 检查。

zone.internal.acl_deny_action

TypeOptional ValueDefault
enumignore, disconnectignore

说明

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

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

zone.internal.force_gc_policy

TypeDefault
string-

说明

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

格式:<Number>|<Bytes>

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

zone.internal.wildcard_subscription

TypeOptional ValueDefault
enumtrue, false-

说明

是否支持订阅通配主题。

zone.internal.shared_subscription

TypeOptional ValueDefault
enumtrue, false-

说明

是否支持共享订阅。

zone.internal.max_subscriptions

TypeDefault
integer0

说明

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

zone.internal.max_inflight

TypeDefault
integer128

说明

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

zone.internal.max_awaiting_rel

TypeDefault
integer1000

说明

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

zone.internal.max_mqueue_len

TypeDefault
integer10000

说明

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

zone.internal.mqueue_store_qos0

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

zone.internal.enable_flapping_detect

TypeOptional ValueDefault
enumon, offoff

说明

是否开启 Flapping 检查。

zone.internal.force_shutdown_policy

TypeDefault
string-

说明

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

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

格式:<Number>|<Bytes>

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

zone.internal.mountpoint

TypeDefault
string-

说明

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

其中可用的占位符有:

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

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

zone.internal.ignore_loop_deliver

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

zone.internal.strict_mode

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

zone.internal.bypass_auth_plugins

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

tcpexternal

listener.tcp.external

TypeDefault
string0.0.0.0:1883

说明

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

示例

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

listener.tcp.external.acceptors

TypeDefault
integer8

说明

监听器的接收池大小。

listener.tcp.external.max_connections

TypeDefault
integer1024000

说明

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

listener.tcp.external.max_conn_rate

TypeDefault
integer1000

说明

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

listener.tcp.external.active_n

TypeDefault
integer100

说明

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

listener.tcp.external.zone

TypeDefault
stringexternal

说明

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

listener.tcp.external.rate_limit

TypeDefault
string-

说明

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

示例

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

listener.tcp.external.access.1

TypeDefault
stringallow all

说明

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

示例

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

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

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

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

listener.tcp.external.proxy_protocol

TypeOptional ValueDefault
enumon, off-

说明

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

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

Proxy Protcol 参考: https://www.haproxy.com/blog/haproxy/proxy-protocol参数配置列表 - 图9 (opens new window)

listener.tcp.external.proxy_protocol_timeout

TypeDefault
duration-

说明

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

listener.tcp.external.peer_cert_as_username

TypeOptional ValueDefault
enumcn, dn, crt, pem, md5cn

说明

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

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

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

listener.tcp.external.peer_cert_as_clientid

TypeOptional ValueDefault
enumcn, dn, crt, pem, md5cn

说明

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

listener.tcp.external.backlog

TypeDefault
integer1024

说明

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

listener.tcp.external.send_timeout

TypeDefault
duration15s

说明

TCP 报文发送超时时间。

listener.tcp.external.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

listener.tcp.external.recbuf

TypeDefault
bytesize-

说明

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

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

listener.tcp.external.sndbuf

TypeDefault
bytesize-

说明

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

参见:http://erlang.org/doc/man/inet.html参数配置列表 - 图11 (opens new window)

listener.tcp.external.buffer

TypeDefault
bytesize-

说明

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

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

参见:http://erlang.org/doc/man/inet.html参数配置列表 - 图12 (opens new window)

listener.tcp.external.tune_buffer

TypeOptional ValueDefault
enumon, off-

说明

如果打开此配置,请设置该值等于 sndbuffrecbuff 的最大值。

listener.tcp.external.nodelay

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

listener.tcp.external.reuseaddr

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

tcpinternal

listener.tcp.internal

TypeDefault
string127.0.0.1:11883

说明

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

示例

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

listener.tcp.internal.acceptors

TypeDefault
integer4

说明

监听器的接收池大小。

listener.tcp.internal.max_connections

TypeDefault
integer1024000

说明

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

listener.tcp.internal.max_conn_rate

TypeDefault
integer1000

说明

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

listener.tcp.internal.active_n

TypeDefault
integer1000

说明

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

listener.tcp.internal.zone

TypeDefault
stringinternal

说明

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

listener.tcp.internal.rate_limit

TypeDefault
string-

说明

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

示例

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

listener.tcp.internal.backlog

TypeDefault
integer512

说明

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

listener.tcp.internal.send_timeout

TypeDefault
duration5s

说明

TCP 报文发送超时时间。

listener.tcp.internal.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

listener.tcp.internal.recbuf

TypeDefault
bytesize64KB

说明

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

listener.tcp.internal.sndbuf

TypeDefault
bytesize64KB

说明

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

listener.tcp.internal.buffer

TypeDefault
bytesize-

说明

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

listener.tcp.internal.tune_buffer

TypeOptional ValueDefault
enumon, off-

说明

如果打开此配置,请设置该值等于 sndbuffrecbuff 的最大值。

listener.tcp.internal.nodelay

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

listener.tcp.internal.reuseaddr

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

tlsexternal

listener.ssl.external

TypeDefault
string0.0.0.0:8883

说明

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

listener.ssl.external.acceptors

TypeDefault
integer16

说明

监听器的接收池大小。

listener.ssl.external.max_connections

TypeDefault
integer102400

说明

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

listener.ssl.external.max_conn_rate

TypeDefault
integer500

说明

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

listener.ssl.external.active_n

TypeDefault
integer100

说明

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

listener.ssl.external.zone

TypeDefault
stringexternal

说明

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

listener.ssl.external.access.1

TypeDefault
stringallow all

说明

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

例如:

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

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

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

listener.ssl.external.rate_limit

TypeDefault
string-

说明

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

listener.ssl.external.proxy_protocol

TypeOptional ValueDefault
enumon, off-

说明

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

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

Proxy Protcol 参考: https://www.haproxy.com/blog/haproxy/proxy-protocol参数配置列表 - 图13 (opens new window)

listener.ssl.external.proxy_protocol_timeout

TypeDefault
duration-

说明

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

listener.ssl.external.tls_versions

TypeDefault
stringtlsv1.3,tlsv1.2,tlsv1.1,tlsv1

说明

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

listener.ssl.external.handshake_timeout

TypeDefault
duration15s

说明

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

listener.ssl.external.depth

TypeDefault
number10

说明

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

listener.ssl.external.key_password

TypeDefault
string-

说明

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

listener.ssl.external.keyfile

TypeDefault
stringetc/certs/key.pem

说明

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

listener.ssl.external.certfile

TypeDefault
stringetc/certs/cert.pem

说明

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

listener.ssl.external.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

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

listener.ssl.external.dhfile

TypeDefault
stringetc/certs/dh-params.pem

说明

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

listener.ssl.external.verify

TypeOptional ValueDefault
enumverify_peer, verify_noneverify_peer

说明

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

listener.ssl.external.fail_if_no_peer_cert

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

listener.ssl.external.ciphers

TypeDefault
stringECDHE-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

TypeDefault
stringPSK-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

TypeOptional ValueDefault
enumon, offoff

说明

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

listener.ssl.external.reuse_sessions

TypeOptional ValueDefault
enumon, offon

说明

指定是否支持 SSL session 重用。详情见 http://erlang.org/doc/man/ssl.html参数配置列表 - 图15 (opens new window)

listener.ssl.external.honor_cipher_order

TypeOptional ValueDefault
enumon, offon

说明

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

listener.ssl.external.peer_cert_as_username

TypeOptional ValueDefault
enumcn, dn, crt, pem, md5cn

说明

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

TypeOptional ValueDefault
enumcn, dn, crt, pem, md5cn

说明

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

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

listener.ssl.external.backlog

TypeDefault
integer1024

说明

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

listener.ssl.external.send_timeout

TypeDefault
duration15s

说明

TCP 报文发送超时时间。

listener.ssl.external.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

listener.ssl.external.recbuf

TypeDefault
bytesize-

说明

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

参见:http://erlang.org/doc/man/inet.html参数配置列表 - 图16 (opens new window)

listener.ssl.external.sndbuf

TypeDefault
bytesize-

说明

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

参见:http://erlang.org/doc/man/inet.html参数配置列表 - 图17 (opens new window)

listener.ssl.external.buffer

TypeDefault
bytesize-

说明

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

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

参见:http://erlang.org/doc/man/inet.html参数配置列表 - 图18 (opens new window)

listener.ssl.external.tune_buffer

TypeOptional ValueDefault
enumon, off-

说明

如果打开此配置,请设置该值等于 sndbuffrecbuff 的最大值。

listener.ssl.external.nodelay

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

listener.ssl.external.reuseaddr

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

wsexternal

listener.ws.external

TypeDefault
string8083

说明

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

示例

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

listener.ws.external.mqtt_path

TypeDefault
string/mqtt

说明

WebSocket 的 MQTT 协议路径。因此 EMQ X 的 WebSocket 的地址是: ws://<ip>:<port>/mqtt

listener.ws.external.acceptors

TypeDefault
integer4

说明

监听器的接收池大小。

listener.ws.external.max_connections

TypeDefault
integer102400

说明

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

listener.ws.external.max_conn_rate

TypeDefault
integer1000

说明

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

listener.ws.external.active_n

TypeDefault
integer100

说明

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

listener.ws.external.rate_limit

TypeDefault
string100KB,10s

说明

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

示例

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

listener.ws.external.zone

TypeDefault
stringexternal

说明

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

listener.ws.external.access.1

TypeDefault
stringallow all

说明

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

listener.ws.external.fail_if_no_subprotocol

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

listener.ws.external.supported_protocols

TypeDefault
stringmqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5

说明

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

listener.ws.external.proxy_address_header

TypeOptional ValueDefault
stringX-Forwarded-For-

说明

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

listener.ws.external.proxy_port_header

TypeOptional ValueDefault
stringX-Forwarded-Port-

说明

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

listener.ws.external.proxy_protocol

TypeOptional ValueDefault
enumon, off-

说明

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

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

Proxy Protcol 参考: https://www.haproxy.com/blog/haproxy/proxy-protocol参数配置列表 - 图19 (opens new window)

listener.ws.external.proxy_protocol_timeout

TypeDefault
duration-

说明

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

listener.ws.external.backlog

TypeDefault
integer1024

说明

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

listener.ws.external.send_timeout

TypeDefault
duration15s

说明

TCP 报文发送超时时间。

listener.ws.external.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

listener.ws.external.recbuf

TypeDefault
bytesize-

说明

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

listener.ws.external.sndbuf

TypeDefault
bytesize-

说明

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

listener.ws.external.buffer

TypeDefault
bytesize-

说明

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

listener.ws.external.tune_buffer

TypeOptional ValueDefault
enumon, off-

说明

如果打开此配置,请设置该值等于 sndbuffrecbuff 的最大值。

listener.ws.external.nodelay

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

listener.ws.external.compress

TypeOptional ValueDefault
enumtrue, false-

说明

是否压缩 WebSocket 消息。压缩的实现依赖 zlib参数配置列表 - 图20 (opens new window)

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

listener.ws.external.deflate_opts.level

TypeOptional ValueDefault
enumnone, default, best_compression, best_speed-

说明

压缩等级。

listener.ws.external.deflate_opts.mem_level

TypeOptional ValueDefault
integer1 - 9-

说明

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

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

不配置,则默认为 8

listener.ws.external.deflate_opts.strategy

TypeOptional ValueDefault
enumdefault, 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

TypeOptional ValueDefault
enumtakeover, no_takeover-

说明

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

listener.ws.external.deflate_opts.client_context_takeover

TypeOptional ValueDefault
enumtakeover, no_takeover-

说明

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

listener.ws.external.deflate_opts.server_max_window_bits

TypeOptional ValueDefault
integer8 - 15-

说明

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

listener.ws.external.deflate_opts.client_max_window_bits

TypeOptional ValueDefault
integer8 - 15-

说明

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

listener.ws.external.idle_timeout

TypeDefault
duration-

说明

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

listener.ws.external.max_frame_size

TypeDefault
integer-

说明

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

wssexternal

listener.wss.external

TypeDefault
string0.0.0.0:8084

说明

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

listener.wss.external.mqtt_path

TypeDefault
string/mqtt

说明

WebSocket 的 URL Path。

listener.wss.external.acceptors

TypeDefault
integer4

说明

监听器的接收池大小。

listener.wss.external.max_connections

TypeDefault
integer16

说明

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

listener.wss.external.max_conn_rate

TypeDefault
integer1000

说明

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

listener.wss.external.active_n

TypeDefault
integer100

说明

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

listener.wss.external.rate_limit

TypeDefault
string-

说明

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

listener.wss.external.zone

TypeDefault
stringexternal

说明

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

listener.wss.external.access.1

TypeDefault
stringallow all

说明

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

例如:

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

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

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

listener.wss.external.fail_if_no_subprotocol

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

listener.wss.external.supported_protocols

TypeDefault
stringmqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5

说明

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

listener.wss.external.proxy_address_header

TypeDefault
stringX-Forwarded-For

说明

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

listener.wss.external.proxy_protocol

TypeOptional ValueDefault
enumon, off-

说明

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

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

Proxy Protcol 参考:https://www.haproxy.com/blog/haproxy/proxy-protocol参数配置列表 - 图21 (opens new window)

listener.wss.external.proxy_protocol_timeout

TypeDefault
duration-

说明

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

listener.wss.external.tls_versions

TypeDefault
stringtlsv1.3,tlsv1.2,tlsv1.1,tlsv1

说明

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

listener.wss.external.keyfile

TypeDefault
stringetc/certs/key.pem

说明

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

listener.wss.external.certfile

TypeDefault
stringetc/certs/cert.pem

说明

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

listener.wss.external.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

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

listener.wss.external.depth

TypeDefault
number10

说明

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

listener.wss.external.key_password

TypeDefault
string-

说明

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

listener.wss.external.dhfile

TypeDefault
stringetc/certs/dh-params.pem

说明

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

listener.wss.external.verify

TypeOptional ValueDefault
enumverify_peer, verify_noneverify_peer

说明

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

listener.wss.external.fail_if_no_peer_cert

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

listener.wss.external.ciphers

TypeDefault
stringECDHE-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.wss.external.psk_ciphers

TypeDefault
stringPSK-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

TypeOptional ValueDefault
enumon, offoff

说明

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

listener.wss.external.reuse_sessions

TypeOptional ValueDefault
enumon, offon

说明

指定是否支持 SSL session 重用。详情见 http://erlang.org/doc/man/ssl.html参数配置列表 - 图23 (opens new window)

listener.wss.external.honor_cipher_order

TypeOptional ValueDefault
enumon, offon

说明

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

listener.wss.external.peer_cert_as_username

TypeOptional ValueDefault
enumcn, dn, crt, pem, md5cn

说明

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

TypeOptional ValueDefault
enumcn, dn, crt, pem, md5cn

说明

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

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

listener.wss.external.backlog

TypeDefault
integer1024

说明

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

listener.wss.external.send_timeout

TypeDefault
duration15s

说明

TCP 报文发送超时时间。

listener.wss.external.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

listener.wss.external.recbuf

TypeDefault
bytesize-

说明

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

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

listener.wss.external.sndbuf

TypeDefault
bytesize-

说明

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

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

listener.wss.external.buffer

TypeDefault
bytesize-

说明

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

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

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

listener.wss.external.tune_buffer

TypeOptional ValueDefault
enumon, off-

说明

如果打开此配置,请设置该值等于 sndbuffrecbuff 的最大值。

listener.wss.external.nodelay

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

listener.wss.external.compress

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

listener.wss.external.deflate_opts.level

TypeOptional ValueDefault
enumnone, default, best_compression, best_speeddefault

说明

压缩等级。

listener.wss.external.deflate_opts.mem_level

TypeOptional ValueDefault
integer1 - 9-

说明

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

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

不配置,则默认为 8

listener.wss.external.deflate_opts.strategy

TypeOptional ValueDefault
enumdefault, 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

TypeOptional ValueDefault
enumtakeover, no_takeover-

说明

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

listener.wss.external.deflate_opts.client_context_takeover

TypeOptional ValueDefault
enumtakeover, no_takeover-

说明

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

listener.wss.external.deflate_opts.server_max_window_bits

TypeOptional ValueDefault
integer8 - 15-

说明

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

listener.wss.external.deflate_opts.client_max_window_bits

TypeOptional ValueDefault
integer8 - 15-

说明

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

listener.wss.external.idle_timeout

TypeDefault
duration-

说明

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

listener.wss.external.max_frame_size

TypeDefault
integer-

说明

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

plugins

plugins.etc_dir

TypeDefault
stringetc/plugins

说明

插件的配置目录。

plugins.loaded_file

TypeDefault
stringetc/loaded_plugins

说明

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

plugins.expand_plugins_dir

TypeDefault
stringplugins/

说明

外部插件存放目录。

broker

broker.sys_interval

TypeDefault
duration1m

说明

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

broker.sys_heartbeat

TypeDefault
duration30s

说明

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

  • “$SYS/brokers//uptime”
  • “$SYS/brokers//datetime”

broker.enable_session_registry

TypeOptional ValueDefault
enumon, offon

说明

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

broker.session_locking_strategy

TypeOptional ValueDefault
enumlocal, one, quorum, allquorum

说明

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

broker.shared_subscription_strategy

TypeOptional ValueDefault
enumrandom, round_robin, sticky, hash_clientid, hash_topicrandom

说明

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

  • random: 在所有订阅者中随机选择
  • round_robin: 按照一个固定的顺序选择下一个订阅者
  • sticky: 首次分发时随机选择一个订阅者,后续消息一直发往这一个订阅者
  • hash_clientid: 按照发布者 ClientID 的哈希值
  • hash_topic: 按照源消息主题的哈希值

broker.shared_dispatch_ack_enabled

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

broker.route_batch_clean

TypeOptional ValueDefault
enumon, offoff

说明

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

monitor

sysmon.long_gc

TypeDefault
duration0ms

说明

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

sysmon.long_schedule

TypeDefault
duration240ms

说明

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

sysmon.large_heap

TypeDefault
bytesize8MB

说明

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

sysmon.busy_port

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

sysmon.busy_dist_port

TypeOptional ValueDefault
enumtrue, falsetrue

说明

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

os_mon.cpu_check_interval

TypeDefault
duration60s

说明

CPU 占用率检查周期。

os_mon.cpu_high_watermark

TypeDefault
percent80%

说明

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

os_mon.cpu_low_watermark

TypeDefault
percent60%

说明

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

os_mon.mem_check_interval

TypeDefault
duration60s

说明

内存占用率检查周期。

os_mon.sysmem_high_watermark

TypeDefault
percent70%

说明

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

os_mon.procmem_high_watermark

TypeDefault
percent5%

说明

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

vm_mon.check_interval

TypeDefault
duration30s

说明

进程数量检查周期。

vm_mon.process_high_watermark

TypeDefault
percent80%

说明

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

vm_mon.process_low_watermark

TypeDefault
percent60%

说明

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

插件 emqx-auth-http

auth.http.auth_req.url

TypeDefault
stringhttp://127.0.0.1:80/mqtt/auth

说明

指定认证请求的目标 URL。

auth.http.auth_req.method

TypeOptional ValueDefault
enumget, postpost

说明

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

auth.http.auth_req.headers.<Any>

示例

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

说明

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

auth.http.auth_req.params

TypeFormatDefault
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用户名
%cMQTT Client ID
%a客户端的网络 IP 地址
%r客户端使用的协议,可以是:mqtt, mqtt-sn, coap, lwm2m 以及 stomp
%P密码
%p客户端连接的服务端端口
%c客户端证书中的 Common Name
%d客户端证书中的 Subject

auth.http.super_req.url

TypeDefault
stringhttp://127.0.0.1:80/mqtt/superuser

说明

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

auth.http.super_req.method

TypeOptional ValueDefault
enumget, postpost

说明

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

auth.http.super_req.headers.<Any>

示例

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

说明

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

auth.http.super_req.params

TypeFormatDefault
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

TypeDefault
stringhttp://127.0.0.1:8991/mqtt/acl

说明

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

auth.http.acl_req.method

TypeOptional ValueDefault
enumget, postpost

说明

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

auth.http.acl_req.headers.<Any>

示例

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

说明

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

auth.http.acl_req.params

TypeFormatDefault
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 表示发布
%uMQTT Client ID
%c客户端标识符
%a客户端的网络 IP 地址
%r客户端使用的协议,可以是:mqtt, mqtt-sn, coap, lwm2m 以及 stomp
%m挂载点
%t主题

auth.http.timeout

TypeDefault
duration5s

说明

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

auth.http.connect_timeout

TypeDefault
duration5s

说明

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

auth.http.ssl.cacertfile

TypeDefault
stringetc/certs/ca.pem

说明

CA 证书文件路径。

auth.http.ssl.certfile

TypeDefault
stringetc/certs/client-cert.pem

说明

客户端证书文件路径。

auth.http.ssl.keyfile

TypeDefault
stringetc/certs/client.key.pem

说明

客户端私钥文件路径。

插件 emqx_auth_jwt

auth.jwt.secret

TypeDefault
stringemqxsecret

说明

设置 HMAC Secret。

auth.jwt.from

TypeOptional ValueDefault
enumusername, passwordpassword

说明

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

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

auth.jwt.pubkey

TypeDefault
stringetc/certs/jwt_public_key.pem

说明

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

auth.jwt.verify_claims

TypeOptional ValueDefault
enumon, offoff

说明

启用或关闭 Claims 校验功能。

auth.jwt.verify_claims

TypeDefault
string-

说明

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

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

  1. auth.jwt.verify_claims.sub = abc

期望值支持两个通配符:

  • %u: username
  • %c: clientid

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

  1. auth.jwt.verify_claims.sub = %u

插件 emqx_auth_ldap

auth.ldap.servers

TypeDefault
string127.0.0.1

说明

LDAP 服务地址。

auth.ldap.port

TypeDefault
integer389

说明

LDAP 服务端口。

auth.ldap.pool

TypeOptional ValueDefault
integer> 08

说明

连接池大小。

auth.ldap.bind_dn

TypeDefault
stringcn=root,dc=emqx,dc=io

说明

登入 LDAP 服务的 DN。

auth.ldap.bind_password

TypeDefault
stringpublic

说明

登入 LDAP 服务的密码。

auth.ldap.timeout

TypeDefault
duration30s

说明

查询操作的超时时间。

auth.ldap.device_dn

TypeDefault
stringou=device,dc=emqx,dc=io

说明

客户端隶属的 DN。

auth.ldap.match_objectclass

TypeDefault
stringmqttUser

说明

客户端对象的名称。

auth.ldap.username.attributetype

TypeDefault
stringuid

说明

Username 属性的数据类型。

auth.ldap.password.attributetype

TypeDefault
stringuserPassword

说明

Password 属性的数据类型。

auth.ldap.ssl

TypeOptional ValueDefault
enumtrue, falsefalse

说明

是否开启 SSL。

auth.ldap.ssl.certfile

TypeDefault
string-

说明

SSL 服务端证书路径。

auth.ldap.ssl.keyfile

TypeDefault
string-

说明

SSL 服务端秘钥文件路径。

auth.ldap.ssl.cacertfile

TypeDefault
string-

说明

CA 证书文件路径。

auth.ldap.ssl.verify

TypeOptional ValueDefault
enumverify_peer, verify_none-

说明

SSL 认证方式:

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

auth.ldap.ssl.fail_if_no_peer_cert

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

插件 emqx_auth_mongo

auth.mongo.type

TypeOptional ValueDefault
enumsingle, unknown, sharded, rssingle

说明

设置 MongoDB 的拓扑类型:

  • single: 单节点

  • unknown: 未知

  • sharded: 分片模式

  • rs: 副本模式 (replicated set)

auth.mongo.rs_set_name

TypeDefault
string127.0.0.1:27017

说明

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

auth.mongo.pool

TypeDefault
integer8

说明

设置 MongoDB 连接池的进程数。

auth.mongo.login

TypeDefault
string-

说明

设置 MongoDB 的用户名。

auth.mongo.password

TypeDefault
string-

说明

设置 MongoDB 的密码。

auth.mongo.auth_source

TypeDefault
stringmqtt

说明

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

auth.mongo.database

TypeDefault
stringmqtt

说明

设置 MongoDB 的数据库名。

auth.mongo.query_timeout

TypeDefault
duration5s

说明

设置访问 MongoDB 超时时间。

auth.mongo.ssl

TypeOptional ValueDefault
enumtrue, falsefalse

说明

设置是否使用 SSL 访问 MongoDB。

auth.mongo.ssl_opts.keyfile

TypeDefault
string-

说明

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

auth.mongo.ssl_opts.certfile

TypeDefault
string-

说明

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

auth.mongo.ssl_opts.cacertfile

TypeDefault
string-

说明

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

auth.mongo.w_mode

TypeOptional ValueDefault
enumunsafe, safe, undefundef

说明

设置 MongoDB 的写入模式。

auth.mongo.r_mode

TypeOptional ValueDefault
enummaster, slave_ok, undefundef

说明

设置 MongoDB 的读取模式。

auth.mongo.auth_query.collection

TypeDefault
stringmqtt_user

说明

认证过程用的 Collection 名字。

auth.mongo.auth_query.password_field

TypeDefault
stringpassword

说明

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

  1. auth.mongo.auth_query.password_field = password,salt

auth.mongo.auth_query.password_hash

TypeOptional ValueDefault
enumplain, md5, sha, sha256, bcryptsha256

说明

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

  1. auth.mongo.auth_query.password_hash = sha256,salt

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

  1. auth.mongo.auth_query.password_hash = salt,sha256

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

  1. auth.mongo.auth_query.password_hash = salt,bcrypt

auth.mongo.auth_query.selector

TypeDefault
stringusername=%u

说明

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

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

auth.mongo.auth_query.super_query

TypeOptional ValueDefault
enumon, offon

说明

认证中是否使用 SuperUser。

auth.mongo.super_query.collection

TypeDefault
stringmqtt_user

说明

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

auth.mongo.super_query.selector

TypeDefault
stringusername=%u, clientid=%c

说明

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

auth.mongo.acl_query

TypeOptional ValueDefault
enumon, offon

说明

是否开启 ACL 功能。

auth.mongo.acl_query.collection

TypeDefault
stringmqtt_acl

说明

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

auth.mongo.acl_query.selector

TypeDefault
stringusername=%u

说明

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

例如,配置如下两条访问规则:

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

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

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

auth.mongo.topology.pool_size

TypeDefault
integer1

说明

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

auth.mongo.topology.max_overflow

TypeDefault
integer0

说明

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

auth.mongo.topology.overflow_ttl

TypeDefault
integer1000

说明

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

auth.mongo.topology.overflow_check_period

TypeDefault
integer1000

说明

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

auth.mongo.topology.local_threshold_ms

TypeDefault
integer1000

说明

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

auth.mongo.topology.connect_timeout_ms

TypeDefault
integer20000

说明

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

auth.mongo.topology.socket_timeout_ms

TypeDefault
integer100

说明

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

auth.mongo.topology.server_selection_timeout_ms

TypeDefault
integer30000

说明

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

auth.mongo.topology.wait_queue_timeout_ms

TypeDefault
integer1000

说明

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

auth.mongo.topology.heartbeat_frequency_ms

TypeDefault
integer10000

说明

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

auth.mongo.topology.min_heartbeat_frequency_ms

TypeDefault
integer1000

说明

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

插件 emqx_auth_mysql

auth.mysql.server

TypeDefault
ip127.0.0.1:3306

说明

MySQL 服务器地址。

auth.mysql.pool

TypeDefault
integer8

说明

数据库连接线程池大小。

auth.mysql.username

TypeDefault
string-

说明

MySQL 用户名。

auth.mysql.password

TypeDefault
string-

说明

MySQL 密码。

auth.mysql.database

TypeDefault
stringmqtt

说明

MySQL 数据库名称。

auth.mysql.query_timeout

TypeDefault
duration5s

说明

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

auth.mysql.auth_query

TypeDefault
stringselect password from mqtt_user where username = ‘%u’ limit 1

说明

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

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

auth.mysql.password_hash

TypeDefault
stringsh256

说明

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

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

auth.mysql.super_query

TypeDefault
stringselect is_superuser from mqtt_user where username = ‘%u’ limit 1

说明

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

auth.mysql.acl_query

TypeDefault
stringselect 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

TypeDefault
ip127.0.0.1:5432

说明

PostgreSQL 服务器地址。

auth.pgsql.pool

TypeDefault
integer8

说明

数据库连接线程池大小。

auth.pgsql.username

TypeDefault
stringroot

说明

PostgreSQL 用户名。

auth.pgsql.password

TypeDefault
string-

说明

PostgreSQL 密码。

auth.pgsql.database

TypeDefault
stringmqtt

说明

PostgreSQL 数据库名称。

auth.pgsql.encoding

TypeDefault
stringutf8

说明

PostgreSQL 数据库字符编码格式。

auth.pgsql.ssl

TypeOptional ValueDefault
enumtrue, falsefalse

说明

是否启用 TLS 连接。

auth.pgsql.ssl_opts.keyfile

TypeDefault
string-

说明

客户端私钥文件路径。

auth.pgsql.ssl_opts.certfile

TypeDefault
string-

说明

客户端证书文件路径。

auth.pgsql.ssl_opts.cacertfile

TypeDefault
string-

说明

客户端 CA 证书文件路径。

auth.pgsql.auth_query

TypeDefault
stringselect password from mqtt_user where username = ‘%u’ limit 1

说明

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

auth.pgsql.password_hash

TypeDefault
stringsh256

说明

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

auth.pgsql.super_query

TypeDefault
stringselect is_superuser from mqtt_user where username = ‘%u’ limit 1

说明

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

auth.pgsql.acl_query

TypeDefault
stringselect 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

TypeOptional ValueDefault
enumsingle, sentinel, clustersingle

说明

Redis 服务集群类型:

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

auth.redis.server

TypeDefault
string127.0.0.1:6379

说明

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

auth.redis.sentinel

TypeDefault
string-

说明

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

auth.redis.pool

TypeOptional ValueDefault
integer> 08

说明

连接池大小。

auth.redis.database

TypeDefault
integer0

说明

要连接的 Redis 数据库序号。

auth.redis.password

TypeDefault
string-

说明

Redis 用户密码。

auth.redis.query_timeout

TypeDefault
duration5s

说明

Redis 查询超时时间。

auth.redis.auth_cmd

TypeDefault
stringHMGET mqtt_user:%u password

说明

认证查询命令,可用站位符有:

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

auth.redis.password_hash

TypeOptional ValueDefault
enumplain, md5, sha, sha256, bcryptplain

说明

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

auth.redis.super_cmd

TypeDefault
stringHGET mqtt_user:%u is_superuser

说明

超级用户查询命令,可用的占位符有:

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

auth.redis.acl_cmd

TypeDefault
stringHGETALL mqtt_acl:%u

说明

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

  • %u:客户端用户名。
  • %c:客户端标识。

插件 emqx_bridge_mqtt

bridge.mqtt.aws.address

TypeDefault
string127.0.0.1:1883

说明

桥接地址,支持两种格式,例如:

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

bridge.mqtt.aws.proto_ver

TypeOptional ValueDefault
enummqttv3, mqttv4, mqttv5mqttv4

说明

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

bridge.mqtt.aws.start_type

TypeOptional ValueDefault
eunmmanual, automanual

说明

启动类型:

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

bridge.mqtt.aws.bridge_mode

TypeOptional ValueDefault
booleantrue, falsetrue

说明

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

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

bridge.mqtt.aws.clientid

TypeDefault
stringbridge_aws

说明

MQTT 桥接的客户端标识。

bridge.mqtt.aws.clean_start

TypeOptional ValueDefault
booleantrue, falsetrue

说明

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

bridge.mqtt.aws.username

TypeDefault
stringuser

说明

MQTT 桥接客户端的用户名。

bridge.mqtt.aws.password

TypeDefault
stringpasswd

说明

MQTT 桥接客户端的密码。

bridge.mqtt.aws.forwards

TypeDefault
stringtopic1/#,topic2/#

说明

桥接转发规则。例如:

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

bridge.mqtt.aws.forward_mountpoint

TypeDefault
stringbridge/aws/${node}/

说明

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

bridge.mqtt.aws.subscription.1.topic

TypeDefault
string-

说明

订阅对端系统的主题。

bridge.mqtt.aws.subscription.1.qos

TypeOptional ValueDefault
enum0, 1, 21

说明

订阅对端系统主题的 QoS。

bridge.mqtt.aws.receive_mountpoint

TypeDefault
stringreceive/aws/

说明

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

bridge.mqtt.aws.ssl

TypeOptional ValueDefault
booleantrue, falsetrue

说明

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

bridge.mqtt.aws.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

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

bridge.mqtt.aws.certfile

TypeDefault
stringetc/certs/client-cert.pem

说明

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

bridge.mqtt.aws.keyfile

TypeDefault
stringetc/certs/client-key.pem

说明

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

bridge.mqtt.aws.ciphers

TypeDefault
stringECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384

说明

SSL 握手支持的加密套件。

bridge.mqtt.aws.psk_ciphers

TypeDefault
stringPSK-AES128-CBC-SHA,PSK-AES256-CBC-SHA,PSK-3DES-EDE-CBC-SHA,PSK-RC4-SHA

说明

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

bridge.mqtt.aws.keepalive

TypeDefault
duration60s

说明

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

bridge.mqtt.aws.tls_versions

TypeDefault
stringtlsv1.3,tlsv1.2,tlsv1.1,tlsv1

说明

MQTT 桥接客户端的 SSL 版本。

bridge.mqtt.aws.reconnect_interval

TypeDefault
duration30s

说明

重连间隔。

bridge.mqtt.aws.retry_interval

TypeDefault
duration20s

说明

QoS 1/2 消息重发间隔。

bridge.mqtt.aws.batch_size

TypeDefault
integer32

说明

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

bridge.mqtt.aws.max_inflight_size

TypeDefault
integer32

说明

飞行窗口大小。

bridge.mqtt.aws.queue.replayq_dir

TypeDefault
stringetc/emqx_aws_bridge/

说明

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

bridge.mqtt.aws.queue.replayq_seg_bytes

TypeDefault
bytesize10MB

说明

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

bridge.mqtt.aws.queue.max_total_size

TypeDefault
bytesize5GB

说明

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

插件 emqx_coap

coap.port

TypeDefault
integer5683

说明

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

coap.enable_stats

TypeOptional ValueDefault
enumon, offoff

说明

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

coap.dtls.port

TypeDefault
integer5684

说明

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

coap.dtls.verify

TypeOptional ValueDefault
enumverify_peer, verify_noneverify_peer

说明

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

coap.dtls.keyfile

TypeDefault
stringetc/certs/key.pem

说明

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

coap.dtls.certfile

TypeDefault
stringetc/certs/cert.pem

说明

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

coap.dtls.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

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

coap.dtls.fail_if_no_peer_cert

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

coap.dtls.ciphers

TypeDefault
stringECDHE-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

说明

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

插件 emqx_dashboard

dashboard.default_user.login&dashboard.default_user.password

TypeDefault
string-

说明

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

dashboard.listener.http

TypeDefault
integer18083

说明

HTTP 监听器的监听端口。

dashboard.listener.http.acceptors

TypeDefault
integer4

说明

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

dashboard.listener.http.max_clients

TypeDefault
integer512

说明

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

dashboard.listener.http.inet6

TypeOptional ValueDefault
enumture, falsefalse

说明

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

dashboard.listener.http.ipv6_v6only

TypeOptional ValueDefault
enumture, falsefalse

说明

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

dashboard.listener.https

TypeDefault
integer18084

说明

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

dashboard.listener.https.acceptors

TypeDefault
integer2

说明

dashboard.listener.http.acceptors

dashboard.listener.https.max_clients

TypeDefault
integer512

说明

dashboard.listener.http.max_clients

dashboard.listener.https.inet6

TypeOptional ValueDefault
enumture, falsefalse

说明

dashboard.listener.http.inet6

dashboard.listener.https.ipv6_v6only

TypeOptional ValueDefault
enumture, falsefalse

说明

dashboard.listener.http.ipv6_v6only

dashboard.listener.https.keyfile

TypeDefault
stringetc/certs/key.pem

说明

服务端私钥文件路径。

dashboard.listener.https.certfile

TypeDefault
stringetc/certs/cert.pem

说明

服务端证书文件路径。

dashboard.listener.https.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

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

dashboard.listener.https.dhfile

TypeDefault
stringetc/certs/dh-params.pem

说明

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

dashboard.listener.https.verify

TypeOptional ValueDefault
enumverify_peer, verify_noneverify_peer

说明

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

dashboard.listener.https.fail_if_no_peer_cert

TypeOptional ValueDefault
enumture, falsetrue

说明

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

dashboard.listener.https.tls_versions

TypeDefault
stringtlsv1.3,tlsv1.2,tlsv1.1,tlsv1

说明

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

dashboard.listener.https.ciphers

TypeDefault
stringECDHE-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

说明

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

dashboard.listener.https.secure_renegotiate

TypeOptional ValueDefault
enumon, offoff

说明

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

dashboard.listener.https.reuse_sessions

TypeOptional ValueDefault
enumon, offon

说明

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

dashboard.listener.https.honor_cipher_order

TypeOptional ValueDefault
enumon, offon

说明

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

插件 emqx_lwm2m

lwm2m.port

TypeDefault
integer5683

说明

指定 LwM2M 使用的 UDP 端口。

lwm2m.lifetime_min

TypeDefault
duration1s

说明

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

lwm2m.lifetime_max

TypeDefault
duration86400s

说明

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

lwm2m.qmode_time_window

TypeDefault
integer22

说明

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

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

lwm2m.lb

TypeOptional ValueDefault
enumcoaproxy, undefinedundefined

说明

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

lwm2m.auto_observe

TypeOptional ValueDefault
enumon, offoff

说明

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

lwm2m.mountpoint

TypeDefault
stringlwm2m/%e/

说明

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

  • ‘%e’: Endpoint Name
  • ‘%a’: IP Address

lwm2m.topics.command

TypeDefault
stringdn/#

说明

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

lwm2m.topics.response

TypeDefault
stringup/resp

说明

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

lwm2m.topics.notify

TypeDefault
stringup/notify

说明

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

lwm2m.topics.register

TypeDefault
stringup/resp

说明

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

lwm2m.topics.update

TypeDefault
stringup/resp

lwm2m.update_msg_publish_condition

TypeOptional ValueDefault
enumcontains_object_list, alwayscontains_object_list

Description

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

  • contains_object_list: 仅当 UPDATE 消息包含 object list 时发布

  • always: 总是发布

说明

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

lwm2m.opts.buffer

TypeDefault
bytesize1024KB

说明

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

lwm2m.opts.recbuf

TypeDefault
bytesize1024KB

说明

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

lwm2m.opts.sndbuf

TypeDefault
bytesize1024KB

说明

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

lwm2m.opts.read_packets

TypeDefault
integer20

说明

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

lwm2m.certfile

TypeDefault
stringetc/certs/cert.pem

说明

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

lwm2m.keyfile

TypeDefault
stringetc/certs/key.pem

说明

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

lwm2m.xml_dir

TypeDefault
diretc/lwm2m_xml

说明

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

插件 emqx_management

management.max_row_limit

TypeDefault
integer10000

说明

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

management.default_application.id

TypeDefault
stringadmin

说明

默认应用的 AppId。

management.default_application.secret

TypeDefault
stringpublic

说明

默认应用的 AppSecret。

management.listener.http

TypeDefault
integer8081

说明

HTTP 监听器的监听端口。

management.listener.http.acceptors

TypeDefault
integer2

说明

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

management.listener.http.max_clients

TypeDefault
integer512

说明

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

management.listener.http.backlog

TypeDefault
integer512

说明

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

management.listener.http.send_timeout

TypeDefault
duration15s

说明

HTTP 报文发送超时时间。

management.listener.http.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

management.listener.http.inet6

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

management.listener.http.ipv6_v6only

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

management.listener.https

TypeDefaultExample
integer-8081

说明

HTTPS 监听器的监听端口。

management.listener.https.acceptors

TypeDefault
integer2

说明

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

management.listener.https.max_clients

TypeDefault
integer512

说明

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

management.listener.https.backlog

TypeDefault
integer512

说明

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

management.listener.https.send_timeout

TypeDefault
duration15s

说明

HTTPS 报文发送超时时间。

management.listener.https.send_timeout_close

TypeOptional ValueDefault
enumon, offon

说明

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

management.listener.https.keyfile

TypeDefault
stringetc/certs/key.pem

说明

服务端私钥文件路径。

management.listener.https.certfile

TypeDefault
stringetc/certs/cert.pem

说明

服务端证书文件路径。

management.listener.https.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

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

management.listener.https.verify

TypeOptional ValueDefault
enumverify_peer, verify_noneverify_peer

说明

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

management.listener.https.fail_if_no_peer_cert

TypeOptional ValueDefault
enumture, falsetrue

说明

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

management.listener.https.inet6

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

management.listener.https.ipv6_v6only

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

插件emqx_retainer

retainer.storage_type

TypeOptional ValueDefault
enumram, disc, disc_onlyram

说明

保留消息的存储类型,以下选项可用:

ram

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

disc

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

disc_only

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

retainer.max_retained_messages

TypeDefault
integer0

说明

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

retainer.max_payload_size

TypeDefault
bytesize1MB

说明

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

retainer.expiry_interval

TypeDefault
duration0

说明

保留消息的过期间隔,仅对协议版本低于 MQTT v5.0 的客户端生效,MQTT v5.0 客户端的保留消息过期间隔将以 Message Expiry Interval 的值为准。0 表示永不过期。

插件emqx_rule_engine

rule-engine.ignore_sys_message

TypeOptional ValueDefault
enumon, offon

说明

忽略系统消息 ($SYS)。启用此选项规则引擎将不会处理系统消息。

rule-engine.events.

TypeOptional ValueDefault
enumon, offoff

说明

设置是否发布事件消息。可指定事件消息的 QoS,例如:

  1. rule-engine.events.client_connected = on, qos1

若启用此选项,规则引擎会将系统消息使用 $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,以下规则仍然可以使用:

  1. SELECT * FROM "$events/client_connected"

插件 emqx_sn

mqtt.sn.port

TypeDefault
string1884

说明

emqx_sn 监听的 UDP 端口。

mqtt.sn.advertise_duration

TypeDefault
duration15s

说明

ADVERTISE 消息广播间隔,单位:秒。

mqtt.sn.gateway_id

TypeDefault
integer1

说明

ADVERTISE 中的 MQTT-SN 网关 ID。

mqtt.sn.enable_stats

TypeOptional ValueDefault
enumon, offoff

说明

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

mqtt.sn.enable_qos3

TypeOptional ValueDefault
enumon, offoff

说明

是否处理 QoS 为 -1 的消息。

mqtt.sn.idle_timeout

TypeDefault
duration30s

说明

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

mqtt.sn.predefined.topic.0

TypeDefault
stringreserved

说明

预定义的 Topic 与 TopicId 映射。Id 为 0 的主题是保留项,固定为 reserved。例如,预定义主题 foo/bar 的 Id 为 1

  1. mqtt.sn.predefined.topic.1 = foo/bar

mqtt.sn.username

TypeDefault
stringmqtt_sn_user

说明

emqx_sn 连接至 EMQ X 的用户名。

mqtt.sn.password

TypeDefault
stringabc

说明

emqx_sn 连接至 EMQ X 的密码。

插件 emqx_prometheus

prometheus.push.gateway.server

TypeDefault
stringhttp://127.0.0.1:9091

说明

指定 Prometheus gateway 的 URI。

prometheus.interval

TypeDefault
integer15000

说明

指定 Stats 数据的收集间隔,单位: 毫秒。

prometheus.collector.

TypeDefault
stringemqx_prometheus

说明

指定 Prometheus 的 Collector。

插件 emqx_stomp

stomp.listener

TypeDefault
integer61613

说明

指定 Stomp 插件监听的本地端口。

stomp.listener.acceptors

TypeDefault
integer4

说明

指定 Stomp 服务 Acceptor 线程池的大小。

stomp.listener.max_connections

TypeDefault
integer512

说明

指定 Stomp 服务支持的最大连接数。

stomp.listener.ssl

TypeOptional ValueDefault
enumon, offoff

说明

指定是否使用 SSL。

stomp.listener.keyfile

TypeDefault
stringetc/certs/key.pem

说明

若使用 SSL,指定 SSL 的私钥文件。

stomp.listener.certfile

TypeDefault
stringetc/certs/cert.pem

说明

若使用 SSL,指定 SSL 的证书文件。

stomp.listener.cacertfile

TypeDefault
stringetc/certs/cacert.pem

说明

若使用 SSL,指定 SSL 的 CA 证书文件。

stomp.listener.dhfile

TypeDefault
stringetc/certs/dh-params.pem

说明

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

stomp.listener.verify

TypeOptional ValueDefault
enumverify_peer, verify_noneverify_peer

说明

若使用 SSL,指定握手过程中是否校验客户端。

stomp.listener.fail_if_no_peer_cert

TypeOptional ValueDefault
enumtrue, falsefalse

说明

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

stomp.listener.tls_versions

TypeDefault
stringtlsv1.2,tlsv1.1,tlsv1

说明

若使用 SSL,指定服务端支持的 SSL 的版本列表。

stomp.listener.handshake_timeout

TypeDefault
duration15s

说明

若使用 SSL,指定 SSL 握手过程的超时时间。

stomp.listener.ciphers

TypeDefault
stringECDHE-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

说明

若使用 SSL,指定服务端支持的 Cipher 列表。

stomp.listener.secure_renegotiate

TypeOptional ValueDefault
enumon, offoff

说明

若使用 SSL,指定在客户端不遵循 RFC 5746 的情况下,是否拒绝 renegotiation 请求。

stomp.listener.reuse_sessions

TypeOptional ValueDefault
enumon, offon

说明

若使用 SSL,指定是否支持 SSL session 重用。

stomp.listener.honor_cipher_order

TypeOptional ValueDefault
enumon, offon

说明

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

stomp.default_user.login

TypeDefault
stringguest

说明

指定 Stomp 插件登录使用的 Username。

stomp.default_user.passcode

TypeDefault
stringguest

说明

指定 Stomp 插件登录使用的 Password。

stomp.allow_anonymous

TypeOptional ValueDefault
enumtrue, falsetrue

说明

是否允许匿名登录。

stomp.frame.max_headers

TypeDefault
integer10

说明

指定 Stomp 最大报文头数量。

stomp.frame.max_header_length

TypeDefault
integer1024

说明

指定 Stomp 最大报文头长度。

stomp.frame.max_body_length

TypeDefault
integer8192

说明

指定 Stomp 最大报文体长度。

插件emqx_web_hook

web.hook.url

TypeDefault
stringhttp://127.0.0.1:80

说明

Webhook 请求转发的目的 Web 服务器地址。

web.hook.headers.<Any>

示例

  1. web.hook.headers.content-type = application/json
  2. web.hook.headers.accept = */*

说明

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

web.hook.encoding_of_payload_field

TypeOptional ValueDefault
enumplain, base62, base64plain

说明

PUBLISH 报文中 Payload 字段的编码格式。

web.hook.ssl.cacertfile

TypeDefault
string-

说明

CA 证书文件路径。

web.hook.ssl.certfile

TypeDefault
string-

说明

客户端证书文件路径。

web.hook.ssl.keyfile

TypeDefault
string-

说明

客户端私钥文件路径。

web.hook.ssl.verify

TypeOptional ValueDefault
enumtrue, falsefalse

说明

指定是否校验对端证书。

web.hook.ssl.pool_size

TypeDefault
integer32

说明

HTTP 连接进程池大小。

web.hook.rule.client.connect.1

TypeDefault
string{“action”: “on_client_connect”}

说明

转发 收到连接报文 事件。

web.hook.rule.client.connack.1

TypeDefault
string{“action”: “on_client_connack”}

说明

转发 下发连接应答 事件。

web.hook.rule.client.connected.1

TypeDefault
string{“action”: “on_client_connected”}

说明

转发 客户端成功接入 事件。

web.hook.rule.client.disconnected.1

TypeDefault
string{“action”: “on_client_disconnected”}

说明

转发 客户端已断开 事件。

web.hook.rule.client.subscribe.1

TypeDefault
string{“action”: “on_client_subscribe”}

说明

转发 将订阅 事件。

web.hook.rule.client.unsubscribe.1

TypeDefault
string{“action”: “on_client_unsubscribe”}

说明

转发 将取消订阅 事件。

web.hook.rule.session.subscribed.1

TypeDefault
string{“action”: “on_session_subscribed”}

说明

转发 已订阅 事件。

web.hook.rule.session.unsubscribed.1

TypeDefault
string{“action”: “on_session_unsubscribed”}

说明

转发 已取消订阅 事件。

web.hook.rule.session.terminated.1

TypeDefault
string{“action”: “on_session_terminated”}

说明

转发 会话已终止 事件。

web.hook.rule.message.publish.1

TypeDefault
string{“action”: “on_message_publish”}

说明

转发 消息发布 事件。

web.hook.rule.message.delivered.1

TypeDefault
string{“action”: “on_message_delivered”}

说明

转发 消息已投递 事件。

web.hook.rule.message.acked.1

TypeDefault
string{“action”: “on_message_acked”}

说明

转发 消息已应答 事件。