参数配置列表

配置项

Cluster

cluster.name

说明

集群名称。

cluster.proto_dist

说明

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

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

cluster.discovery

说明

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

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

cluster.autoheal

说明

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

cluster.autoclean

说明

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

cluster.static.seeds

说明

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

cluster.mcast.addr

说明

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

cluster.mcast.ports

说明

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

cluster.mcast.iface

说明

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

cluster.mcast.ttl

说明

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

cluster.mcast.loop

说明

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

cluster.dns.name

说明

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

示例

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

192.168.0.100
192.168.0.101
192.168.0.102

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

emqx@192.168.0.100
emqx@192.168.0.101
emqx@192.168.0.102

cluster.dns.app

说明

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

cluster.etcd.server

说明

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

cluster.etcd.prefix

说明

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

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

cluster.etcd.node_ttl

说明

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

cluster.etcd.ssl.keyfile

说明

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

cluster.etcd.ssl.certfile

说明

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

cluster.etcd.ssl.cacertfile

说明

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

cluster.k8s.apiserver

说明

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

cluster.k8s.service_name

说明

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

cluster.k8s.address_type

说明

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

示例

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

172.16.122.31
172.16.122.32
172.16.122.33

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

emqx@172.16.122.31
emqx@172.16.122.32
emqx@172.16.122.33

cluster.k8s.app_name

说明

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

cluster.k8s.suffix

说明

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

cluster.k8s.namespace

说明

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

示例

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

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

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

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

Node

node.name

说明

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

node.cookie

说明

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

node.data_dir

说明

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

node.heartbeat

说明

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

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

node.async_threads

说明

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

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

node.process_limit

说明

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

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

node.max_ports

说明

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

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

node.dist_buffer_size

说明

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

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

node.max_ets_tables

说明

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

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

node.global_gc_interval

说明

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

node.fullsweep_after

说明

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

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

node.crash_dump

说明

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

node.ssl_dist_optfile

说明

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

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

node.dist_net_ticktime

说明

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

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

node.dist_use_interface

说明

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

node.dist_listen_min

说明

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

node.dist_listen_max

说明

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

RPC

rpc.mode

说明

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

rpc.async_batch_size

说明

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

rpc.port_discovery

说明

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

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

rpc.tcp_server_ip

说明

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

rpc.tcp_server_port

说明

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

rpc.tcp_client_num

说明

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

rpc.connect_timeout

说明

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

rpc.send_timeout

说明

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

rpc.authentication_timeout

说明

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

rpc.call_receive_timeout

说明

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

rpc.socket_keepalive_idle

说明

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

rpc.socket_keepalive_interval

说明

发送 keepalive 探测报文的间隔。

rpc.socket_keepalive_count

说明

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

rpc.socket_sndbuf

说明

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

rpc.socket_recbuf

说明

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

rpc.socket_buffer

说明

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

Log

log.to

说明

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

• off: 完全关闭日志功能

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

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

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

log.level

说明

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

log.dir

说明

日志文件目录。

log.file

说明

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

log.chars_limit

说明

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

log.max_depth

Description

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

log.rotation.size

说明

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

log.rotation.count

说明

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

log.<level>.file

说明

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

示例

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

log.info.file = info.log

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

log.error.file = error.log

log.max_depth

说明

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

log.single_line

说明

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

log.formatter

说明

选择打印日志的格式

log.formatter.text.date.format

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

说明

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

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

举例:

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

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

authacl

allow_anonymous

说明

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

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

acl_nomatch

说明

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

acl_file

说明

默认 ACL 文件的路径。

enable_acl_cache

说明

是否启用 ACL 缓存。

acl_cache_max_size

说明

ACL 规则最大缓存条数。

acl_cache_ttl

说明

ACL 规则最大缓存时间。

acl_deny_action

说明

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

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

alias_enrichment_module

说明

Tip

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

在 “4.4.11 “中引入。

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

special_auth_module

说明

Tip

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

在 “4.4.11 “中引入。

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

acl_order

Description

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

Tip

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

auth_order

Description

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

Tip

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

flapping_detect_policy

说明

指定 Flapping 检查策略。

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

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

mqtt

mqtt.max_packet_size

说明

允许的 MQTT 报文最大长度。

mqtt.max_clientid_len

说明

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

mqtt.max_topic_levels

说明

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

Warning

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

mqtt.max_qos_allowed

说明

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

mqtt.max_topic_alias

说明

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

mqtt.retain_available

说明

是否支持 Retain 消息。

mqtt.wildcard_subscription

说明

是否支持订阅通配主题。

mqtt.shared_subscription

说明

是否支持共享订阅。

mqtt.ignore_loop_deliver

说明

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

mqtt.strict_mode

说明

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

zoneexternal

zone.external.idle_timeout

说明

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

zone.external.enable_acl

说明

是否开启 ACL 检查。

zone.external.enable_ban

说明

是否开启黑名单。

zone.external.enable_stats

说明

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

zone.external.acl_deny_action

说明

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

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

zone.external.force_gc_policy

说明

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

格式：<Number>|<Bytes>。

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

zone.external.force_shutdown_policy

说明

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

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

格式：<Number>|<Bytes>。

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

zone.external.max_packet_size

说明

允许的 MQTT 报文最大长度。

zone.external.max_clientid_len

说明

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

zone.external.max_topic_levels

说明

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

Warning

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

zone.external.max_qos_allowed

说明

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

zone.external.max_topic_alias

说明

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

zone.external.retain_available

说明

是否支持 Retain 消息。

zone.external.wildcard_subscription

说明

是否支持订阅通配主题。

zone.external.shared_subscription

说明

是否支持共享订阅。

zone.external.server_keepalive

说明

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

zone.external.keepalive_backoff

说明

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

zone.external.max_subscriptions

说明

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

zone.external.upgrade_qos

说明

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

zone.external.max_inflight

说明

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

zone.external.retry_interval

说明

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

zone.external.max_awaiting_rel

说明

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

zone.external.await_rel_timeout

说明

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

zone.external.session_expiry_interval

说明

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

zone.external.max_mqueue_len

说明

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

zone.external.mqueue_priorities

说明

队列消息优先级配置：

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

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

zone.external.mqueue_default_priority

说明

消息默认的优先等级。

zone.external.mqueue_store_qos0

说明

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

zone.external.enable_flapping_detect

说明

是否开启 Flapping 检查。

zone.external.mountpoint

说明

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

其中可用的占位符有：

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

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

zone.external.use_username_as_clientid

说明

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

zone.external.ignore_loop_deliver

说明

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

zone.external.strict_mode

说明

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

zoneinternal

zone.internal.allow_anonymous

说明

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

zone.internal.enable_stats

说明

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

zone.internal.enable_acl

说明

是否开启 ACL 检查。

zone.internal.acl_deny_action

说明

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

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

zone.internal.force_gc_policy

说明

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

格式：<Number>|<Bytes>。

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

zone.internal.wildcard_subscription

说明

是否支持订阅通配主题。

zone.internal.shared_subscription

说明

是否支持共享订阅。

zone.internal.max_subscriptions

说明

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

zone.internal.max_inflight

说明

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

zone.internal.max_awaiting_rel

说明

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

zone.internal.max_mqueue_len

说明

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

zone.internal.mqueue_store_qos0

说明

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

zone.internal.enable_flapping_detect

说明

是否开启 Flapping 检查。

zone.internal.force_shutdown_policy

说明

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

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

格式：<Number>|<Bytes>。

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

zone.internal.mountpoint

说明

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

其中可用的占位符有：

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

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

zone.internal.ignore_loop_deliver

说明

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

zone.internal.strict_mode

说明

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

zone.internal.bypass_auth_plugins

说明

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

tcpexternal

listener.tcp.external

说明

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

示例

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

listener.tcp.external.acceptors

说明

监听器的接收池大小。

listener.tcp.external.max_connections

说明

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

listener.tcp.external.max_conn_rate

说明

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

listener.tcp.external.active_n

说明

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

listener.tcp.external.zone

说明

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

listener.tcp.external.rate_limit

说明

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

示例

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

listener.tcp.external.access.1

说明

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

示例

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

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

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

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

listener.tcp.external.proxy_protocol

说明

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

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

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

listener.tcp.external.proxy_protocol_timeout

说明

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

listener.tcp.external.peer_cert_as_username

说明

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

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

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

listener.tcp.external.peer_cert_as_clientid

说明

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

listener.tcp.external.backlog

说明

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

listener.tcp.external.send_timeout

说明

TCP 报文发送超时时间。

listener.tcp.external.send_timeout_close

说明

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

listener.tcp.external.recbuf

说明

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

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

listener.tcp.external.sndbuf

说明

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

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

listener.tcp.external.buffer

说明

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

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

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

listener.tcp.external.tune_buffer

说明

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

listener.tcp.external.nodelay

说明

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

listener.tcp.external.reuseaddr

说明

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

tcpinternal

listener.tcp.internal

说明

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

示例

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

listener.tcp.internal.acceptors

说明

监听器的接收池大小。

listener.tcp.internal.max_connections

说明

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

listener.tcp.internal.max_conn_rate

说明

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

listener.tcp.internal.active_n

说明

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

listener.tcp.internal.zone

说明

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

listener.tcp.internal.rate_limit

说明

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

示例

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

listener.tcp.internal.backlog

说明

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

listener.tcp.internal.send_timeout

说明

TCP 报文发送超时时间。

listener.tcp.internal.send_timeout_close

说明

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

listener.tcp.internal.recbuf

说明

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

listener.tcp.internal.sndbuf

说明

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

listener.tcp.internal.buffer

说明

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

listener.tcp.internal.tune_buffer

说明

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

listener.tcp.internal.nodelay

说明

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

listener.tcp.internal.reuseaddr

说明

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

tlsexternal

listener.ssl.external

说明

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

listener.ssl.external.acceptors

说明

监听器的接收池大小。

listener.ssl.external.max_connections

说明

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

listener.ssl.external.max_conn_rate

说明

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

listener.ssl.external.active_n

说明

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

listener.ssl.external.zone

说明

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

listener.ssl.external.access.1

说明

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

例如:

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

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

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

listener.ssl.external.rate_limit

说明

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

listener.ssl.external.proxy_protocol

说明

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

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

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

listener.ssl.external.proxy_protocol_timeout

说明

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

listener.ssl.external.tls_versions

说明

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

listener.ssl.external.handshake_timeout

说明

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

listener.ssl.external.depth

说明

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

listener.ssl.external.key_password

说明

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

listener.ssl.external.keyfile

说明

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

listener.ssl.external.certfile

说明

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

listener.ssl.external.cacertfile

说明

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

listener.ssl.external.enable_ocsp_stapling

说明

在 e4.4.11 中引入。

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

listener.ssl.external.ocsp_responder_url

说明

在 e4.4.11 中引入。

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

listener.ssl.external.ocsp_issuer_pem

说明

在 e4.4.11 中引入。

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

listener.ssl.external.ocsp_refresh_interval

说明

在 e4.4.11 中引入。

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

listener.ssl.external.ocsp_refresh_http_timeout

说明

在 e4.4.11 中引入。

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

listener.ssl.external.enable_crl_check

说明

在 e4.4.11 中引入。

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

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

listener.ssl.external.crl_cache_urls

说明

在 e4.4.11 中引入。

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

crl_cache_http_timeout

说明

在 e4.4.11 中引入。

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

crl_cache_refresh_interval

说明

在 e4.4.11 中引入。

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

listener.ssl.external.dhfile

说明

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

listener.ssl.external.verify

说明

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

listener.ssl.external.fail_if_no_peer_cert

说明

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

listener.ssl.external.ciphers

说明

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

listener.ssl.external.psk_ciphers

说明

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

listener.ssl.external.secure_renegotiate

说明

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

listener.ssl.external.reuse_sessions

说明

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

listener.ssl.external.honor_cipher_order

说明

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

listener.ssl.external.peer_cert_as_username

说明

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

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

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

listener.ssl.external.peer_cert_as_clientid

说明

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

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

listener.ssl.external.backlog

说明

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

listener.ssl.external.send_timeout

说明

TCP 报文发送超时时间。

listener.ssl.external.send_timeout_close

说明

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

listener.ssl.external.recbuf

说明

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

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

listener.ssl.external.sndbuf

说明

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

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

listener.ssl.external.buffer

说明

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

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

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

listener.ssl.external.tune_buffer

说明

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

listener.ssl.external.nodelay

说明

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

listener.ssl.external.reuseaddr

说明

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

wsexternal

listener.ws.external

说明

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

示例

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

listener.ws.external.mqtt_path

说明

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

listener.ws.external.acceptors

说明

监听器的接收池大小。

listener.ws.external.max_connections

说明

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

listener.ws.external.max_conn_rate

说明

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

listener.ws.external.active_n

说明

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

listener.ws.external.rate_limit

说明

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

示例

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

（本文超出站点单文档体积上限，已按小节截断）