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

TypeDefault
stringemqx@127.0.0.1
说明

节点名。格式为 <name>@<host>。其中 <host> 可以是 IP 地址,也可以是 FQDN。详见 http://erlang.org/doc/reference_manual/distributed.htmlcluster - 图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.htmlcluster - 图2 (opens new window)

node.process_limit

TypeOptional ValueDefault
integer1024 - 1342177272097152
说明

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

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

node.max_ports

TypeOptional ValueDefault
integer1024 - 1342177271048576
说明

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

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

node.dist_buffer_size

TypeOptional ValueDefault
bytesize1KB - 2GB8MB
说明

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

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

node.max_ets_tables

TypeDefault
integer262144
说明

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

设置 Erlang 运行时允许的最大 ETS 表数量。详情请参见 http://erlang.org/doc/man/erl.htmlcluster - 图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-4cluster - 图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_ticktimecluster - 图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.mode

TypeOptional ValueDefault
enumsync, asyncasync
说明

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

rpc.async_batch_size

TypeDefault
integer256
说明

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

node.tcp_server_port

TypeOptional ValueDefault
integer1024 - 655355369
说明

设置 RPC 本地服务使用的监听 port。

node.tcp_client_port

TypeOptional ValueDefault
integer1024-655355369
说明

设置远程 RPC 服务的端口。

node.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.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.<level>.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

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:断开连接。

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 报文的正确性。

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 报文的正确性。

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 下的客户端绕过认证插件的认证步骤。

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-protocolcluster - 图9 (opens new window)

listener.tcp.external.proxy_protocol_timeout

TypeDefault
duration-
说明

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

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.htmlcluster - 图10 (opens new window)

listener.tcp.external.buffer

TypeDefault
bytesize-
说明

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

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

参见:http://erlang.org/doc/man/inet.htmlcluster - 图11 (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 状态结束。

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 状态结束。

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-protocolcluster - 图12 (opens new window)

listener.ssl.external.proxy_protocol_timeout

TypeDefault
duration-
说明

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

listener.ssl.external.tls_versions

TypeDefault
stringtlsv1.2,tlsv1.1,tlsv1
说明

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

listener.ssl.external.handshake_timeout

TypeDefault
duration15s
说明

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

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)。

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.htmlcluster - 图14 (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, crtcn
说明

使用客户端证书中的 CN、DN 或者 CRT 字段的值作为 MQTT CONNECT 报文中的 Username 字段的值。 注意 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.htmlcluster - 图15 (opens new window)

listener.ssl.external.sndbuf

TypeDefault
bytesize-
说明

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

参见:http://erlang.org/doc/man/inet.htmlcluster - 图16 (opens new window)

listener.ssl.external.buffer

TypeDefault
bytesize-
说明

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

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

参见:http://erlang.org/doc/man/inet.htmlcluster - 图17 (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 状态结束。

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

TypeOptional ValueDefault
enumon, offon
说明

是否验证 WebSocket 携带的 HTTP 头部是否正确。微信小程序需关闭该验证

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-protocolcluster - 图18 (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 消息。压缩的实现依赖 zlibcluster - 图19 (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 报文长度的最大值。

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

TypeOptional ValueDefault
enumon, offon
说明

是否验证 WebSocket 携带的 HTTP 头部是否正确。微信小程序需关闭该验证

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-protocolcluster - 图20 (opens new window)

listener.wss.external.proxy_protocol_timeout

TypeDefault
duration-
说明

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

listener.wss.external.tls_versions

TypeDefault
stringtlsv1.2,tlsv1.1,tlsv1
说明

指定服务端支持的 SSL 的版本列表。详情请参见 http://erlang.org/doc/man/ssl.htmlcluster - 图21 (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,指定 SSL 的 CA 证书文件 (PEM)。

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.htmlcluster - 图22 (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, crtcn
说明

使用客户端证书中的 CN、DN 或者 CRT 字段的值作为 MQTT CONNECT 报文中的 Username 字段的值。 注意 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.etc_dir

TypeDefault
stringetc/plugins
说明

插件的配置目录。

plugins.loaded_file

TypeDefault
stringetc/loaded_plugins
说明

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

plugins.expand_plugins_dir

TypeDefault
stringplugins/
说明

外部插件存放目录。

broker.sys_interval

TypeDefault
duration1m
说明

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

broker.sys_heartbeat

TypeDefault
duration30s
说明

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

  • “$SYS/brokers/<node>/uptime”
  • “$SYS/brokers/<node>/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, hashrandom
说明

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

  • random: 在所有订阅者中随机选择
  • round_robin: 按照订阅顺序
  • sticky: 一直发往上次选取的订阅者
  • hash: 按照发布者 ClientID 的哈希值

broker.shared_dispatch_ack_enabled

TypeOptional ValueDefault
enumtrue, falsefalse
说明

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

broker.route_batch_clean

TypeOptional ValueDefault
enumon, offoff
说明

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

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 配置项决定。