# 配置文件

EMQX的配置文件格式是 HOCON (opens new window) 。 HOCON(Human-Optimized Config Object Notation)是一个JSON的超集,非常适用于易于人类读写的配置数据存储。

# 分层结构

EMQX的配置文件可分为三层,自底向上依次是:

  1. 不可变的基础层 emqx.conf 加上 EMQX_ 前缀的环境变量。
    修改这一层的配置之后,需要重启节点来使之生效。
  2. 集群范围重载层:$EMQX_NODE__DATA_DIR/configs/cluster-override.conf
  3. 节点本地重载层:$EMQX_NODE__DATA_DIR/configs/local-override.conf

如果环境变量 $EMQX_NODE__DATA_DIR 没有设置,那么该目录会从 emqx.confnode.data_dir配置中读取。

配置文件 cluster-override.conf 的内容会在运行时被EMQX重写。 这些重写发生在 dashboard UI,管理HTTP API,或者CLI对集群配置进行修改时。 当EMQX运行在集群中时,一个EMQX节点重启之后,会从集群中其他节点复制该文件内容到本地。

Tip

有些配置项是不能被重载的(例如 node.name)。 配置项如果有 mapping: path.to.boot.config.key 这个属性, 则不能被添加到重载文件 *-override.conf 中。

更多的重载规则,请参考下文 配置重载规则

# 配置文件语法

在配置文件中,值可以被记为类似JSON的对象,例如

node {
    name = "emqx@127.0.0.1"
    cookie = "mysecret"
}
1
2
3
4

另一种等价的表示方法是扁平的,例如

node.name = "127.0.0.1"
node.cookie = "mysecret"
1
2

这种扁平格式几乎与EMQX的配置文件格式向后兼容 在4.x系列中(所谓的'cuttlefish'格式)。

它并不是完全兼容,因为HOCON经常要求字符串两端加上引号。 而cuttlefish把=符右边的所有字符都视为值。

例如,cuttlefish:node.name = emqx@127.0.0.1,HOCON:node.name = "emqx@127.0.0.1"

没有特殊字符的字符串在HOCON中也可以不加引号。 例如:foofoo_barfoo_bar_1

关于更多的HOCON语法,请参考规范 (opens new window)

# Schema

为了使HOCON对象类型安全,EMQX为它引入了一个schema。 该schema定义了数据类型,以及数据字段的名称和元数据,用于配置值的类型检查等等。

Tip

当前阅读到配置文件的文档本身就是由模式元数据生成的。

# 复杂数据类型

EMQX的配置文件中,有4中复杂数据结构类型,它们分别是:

  1. Struct:结构体都是有类型名称的,结构体中可以有任意多个字段。 结构体和字段的名称由不带特殊字符的全小些字母组成,名称中可以带数字,但不得以数字开头,多个单词可用下划线分隔。
  2. Map:Map与Struct(结构体)类似,但是内部的字段不是预先定义好的。
  3. Union:联合 MemberType1 | MemberType2 | ...,可以理解为:“不是这个,就是那个”
  4. Array:数组 [ElementType]

Tip

如果Map的字段名称是纯数字,它会被解释成一个数组。 例如

myarray.1 = 74
myarray.2 = 75
1
2

会被解析成 myarray = [74, 75]。这个用法在重载数组元素的值时候非常有用。

# 原始数据类型

复杂类型定义了数据 "盒子",其中可能包含其他复杂数据或原始值。 有很多不同的原始类型,仅举几个例子。

  • 原子 atom()
  • 布尔 boolean()
  • 字符串 string()
  • 整形 integer()
  • 浮点数 float()
  • 数值 number()
  • 二进制编码的字符串 binary()string() 的另一种格式
  • 时间间隔 emqx_schema:duration()integer() 的另一种格式
  • ...

Tip

原始类型的名称大多是自我描述的,所以不需要过多的注释。 但是有一些不是那么直观的数据类型,则需要配合字段的描述文档进行理解

# 配置路径

如果我们把EMQX的配置值理解成一个类似目录树的结构,那么类似于文件系统中使用斜杠或反斜杠进行层级分割, EMQX使用的配置路径的层级分割符是 '.'

'.'号分割的每一段,则是 Struct(结构体)的字段,或 Map 的 key。

下面有几个例子:

node.name = "emqx.127.0.0.1"
zone.zone1.max_packet_size = "10M"
authentication.1.enable = true
1
2
3

# 环境变量重载

因为'.' 分隔符不能使用于环境变量,所以我们需要使用另一个分割符。EMQX选用的是双下划线__。 为了与其他的环境变量有所区分,EMQX还增加了一个前缀 EMQX_ 来用作环境变量命名空间。

例如 node.name 的重载变量名是 EMQX_NODE__NAME

环境变量的值,是解析成HOCON值的。所以这也使得环境变量可以用来传递复杂数据类型的值。

例如,下面这个环境变量传入一个数组类型的值。

export EMQX_LISTENERS__SSL__L1__AUTHENTICATION__SSL__CIPHERS="[\"TLS_AES_256_GCM_SHA384\"]"
1

Tip

未定义的根路径会被EMQX忽略,例如 EMQX_UNKNOWN_ROOT__FOOBAR 这个环境变量会被EMQX忽略, 因为 UNKNOWN_ROOT 不是预先定义好的根路径。 对于已知的根路径,未知的字段名称将被记录为warning日志,比如下面这个例子。

[warning] unknown_env_vars: ["EMQX_AUTHENTICATION__ENABLED"]
1

这是因为正确的字段名称是 enable,而不是 enabled

# 配置重载规则

HOCON的值是分层覆盖的,普遍规则如下:

  • 在同一个文件中,后(在文件底部)定义的值,覆盖前(在文件顶部)到值。
  • 当按层级覆盖时,高层级的值覆盖低层级的值。

结下来的文档将解释更详细的规则。

# 结构体

合并覆盖规则。在如下配置中,最后一行的 debug 值会覆盖覆盖原先 level 字段的 error 值,但是 enable 字段保持不变。

log {
    console_handler{
        enable=true,
        level=error
    }
}

## 控制台日志打印先定义为 `error` 级别,后被覆写成 `debug` 级别

log.console_handler.level=debug
1
2
3
4
5
6
7
8
9
10

# Map

Map与结构体类似,也是合并覆盖规则。 如下例子中,zone1max_packet_size 可以在文件后面覆写。

zone {
    zone1 {
        mqtt.max_packet_size = 1M
    }
}

## 报文大小限制最先被设置成1MB,后被覆写为10MB

zone.zone1.mqtt.max_packet_size = 10M
1
2
3
4
5
6
7
8
9

# 数组元素

如上面介绍过,EMQX配置中的数组有两种表达方式。

  • 列表格式,例如: [1, 2, 3]
  • 带下标的Map格式,例如: {"1"=1, "2"=2, "3"=3}

点好('.')分隔到路径中的纯数字会被解析成数组下标。 例如,authentication.1={...} 会被解析成 authentication={"1": {...}},进而进一步解析成 authentication=[{...}] 有了这个特性,我们就可以轻松覆写数组某个元素的值,例如:

authentication=[{enable=true, backend="built_in_database", mechanism="password_based"}]
# 可以用下面的方式将第一个元素的 `enable` 字段覆写
authentication.1.enable=false
1
2
3

Warning

使用列表格式是的数组将全量覆写原值,如下例:

authentication=[{enable=true, backend="built_in_database", mechanism="password_based"}]
## 下面这中方式会导致数组第一个元素的除了 `enable` 以外的其他字段全部丢失
authentication=[{enable=true}]
1
2
3

# Root Config Keys

Fields

# authz:file

使用静态文件授权

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: file

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • path: string()

    包含 ACL 规则的文件路径。 如果在启动 EMQX 节点前预先配置该路径, 那么可以将该文件置于任何 EMQX 可以访问到的位置。

    如果从 EMQX Dashboard 或 HTTP API 创建或修改了规则集, 那么EMQX将会生成一个新的文件并将它存放在 data_dir 下的 authz 子目录中, 并从此弃用旧的文件。

# authz:http_get

使用外部 HTTP 服务器授权(GET 请求)。

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: http

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • url: binary()

    HTTP 服务器地址。

  • request_timeout: string()

    • default: "30s"

    HTTP 请求超时时长。

  • body: map()

    HTTP request body。

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    连接HTTP服务器的超时时间。

  • enable_pipelining: pos_integer()

    • default: 100

    正整数,设置最大可发送的异步 HTTP 请求数量。当设置为 1 时,表示每次发送完成 HTTP 请求后都需要等待服务器返回,再继续发送下一个请求。

  • max_retries: non_neg_integer()

    • default: 5

    请求出错时的最大重试次数。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • request: connector-http:request

    如果提供了请求,调用者可以通过以下方式发送 HTTP 请求 emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    重试之间的间隔时间。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • method: get

    • default: get

    HTTP 请求方法

  • headers: [{binary(), binary()}]

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6

    HTTP Headers 列表 (无 content-type) 。

# authz:http_post

使用外部 HTTP 服务器授权(POST 请求)。

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: http

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • url: binary()

    HTTP 服务器地址。

  • request_timeout: string()

    • default: "30s"

    HTTP 请求超时时长。

  • body: map()

    HTTP request body。

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    连接HTTP服务器的超时时间。

  • enable_pipelining: pos_integer()

    • default: 100

    正整数,设置最大可发送的异步 HTTP 请求数量。当设置为 1 时,表示每次发送完成 HTTP 请求后都需要等待服务器返回,再继续发送下一个请求。

  • max_retries: non_neg_integer()

    • default: 5

    请求出错时的最大重试次数。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • request: connector-http:request

    如果提供了请求,调用者可以通过以下方式发送 HTTP 请求 emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    重试之间的间隔时间。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • method: post

    • default: post

    HTTP 请求方法

  • headers: [{binary(), binary()}]

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "content-type" = "application/json"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6
    7

    HTTP Headers 列表

# authz:mnesia

使用内部数据库授权 (mnesia)。

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: built_in_database

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

# authz:mongo_rs

使用 MongoDB 授权(副本集模式)

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mongodb

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • collection: atom()

    MongoDB 授权数据集

  • filter: map()

    • default: {}

    在查询中定义过滤条件的条件表达式。 过滤器支持如下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
  • mongo_type: rs

    • default: rs

    Replica set模式。

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • w_mode: unsafe | safe

    • default: unsafe

    写模式。

  • r_mode: master | slave_ok

    • default: master

    读模式。

  • replica_set_name: binary()

    副本集的名称。

  • srv_record: boolean()

    • default: false

    使用 DNS SRV 记录。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auth_source: binary()

    与用户证书关联的数据库名称。

  • database: binary()

    数据库名字。

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authz:mongo_sharded

使用 MongoDB 授权(分片集群模式)

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mongodb

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • collection: atom()

    MongoDB 授权数据集

  • filter: map()

    • default: {}

    在查询中定义过滤条件的条件表达式。 过滤器支持如下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
  • mongo_type: sharded

    • default: sharded

    Sharded cluster模式。

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • w_mode: unsafe | safe

    • default: unsafe

    写模式。

  • srv_record: boolean()

    • default: false

    使用 DNS SRV 记录。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auth_source: binary()

    与用户证书关联的数据库名称。

  • database: binary()

    数据库名字。

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authz:mongo_single

使用 MongoDB 授权(单实例)

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mongodb

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • collection: atom()

    MongoDB 授权数据集

  • filter: map()

    • default: {}

    在查询中定义过滤条件的条件表达式。 过滤器支持如下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
  • mongo_type: single

    • default: single

    Standalone模式。

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • w_mode: unsafe | safe

    • default: unsafe

    写模式。

  • srv_record: boolean()

    • default: false

    使用 DNS SRV 记录。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auth_source: binary()

    与用户证书关联的数据库名称。

  • database: binary()

    数据库名字。

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authz:mysql

使用 MySOL 数据库授权

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mysql

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 MySQL 默认端口 3306。

  • database: binary()

    数据库名字。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • prepare_statement: map()

    SQL 预处理语句列表。

  • query: binary()

    访问控制数据查询语句/查询命令

# authz:postgresql

使用 PostgreSQL 数据库授权

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: postgresql

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 PostgreSQL 默认端口 5432。

  • database: binary()

    数据库名字。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • prepare_statement: map()

    SQL 预处理语句列表。

  • query: binary()

    访问控制数据查询语句/查询命令

# authz:redis_cluster

使用 Redis 授权(集群模式)

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: redis

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 Redis 默认端口 6379。

  • redis_type: cluster

    集群模式。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • password: binary()

    内部数据库密码。

  • database: integer()

    • default: 0

    Redis 数据库 ID。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • cmd: binary()

    访问控制数据查查询命令

# authz:redis_sentinel

使用 Redis 授权(哨兵模式)

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: redis

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 Redis 默认端口 6379。

  • redis_type: sentinel

    哨兵模式。

  • sentinel: string()

    Redis 哨兵模式下的集群名称。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • password: binary()

    内部数据库密码。

  • database: integer()

    • default: 0

    Redis 数据库 ID。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • cmd: binary()

    访问控制数据查查询命令

# authz:redis_single

使用 Redis 授权(单实例)

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: redis

    数据后端类型

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此访问控制数据源

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • redis_type: single

    单机模式。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • password: binary()

    内部数据库密码。

  • database: integer()

    • default: 0

    Redis 数据库 ID。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • cmd: binary()

    访问控制数据查查询命令

# broker:alarm

Settings for the alarms.

Config paths

  • alarm

Env overrides

  • EMQX_ALARM

Fields

  • actions: [atom()]

    • default: [log, publish]

    警报激活时触发的动作。
    目前,支持以下操作:logpublish. log 将告警写入日志 (控制台或者文件). publish 将告警作为 MQTT 消息发布到系统主题: $SYS/brokers/emqx@xx.xx.xx.x/alarms/activate and $SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivate

  • size_limit: 1..3000

    • default: 1000

    要保留为历史记录的已停用报警的最大总数。当超过此限制时,将删除最旧的停用报警,以限制总数。

  • validity_period: emqx_schema:duration()

    • default: "24h"

    停用报警的保留时间。报警在停用时不会立即删除,而是在保留时间之后删除。

# broker

Message broker options.

Config paths

  • broker

Env overrides

  • EMQX_BROKER

Fields

  • enable_session_registry: boolean()

    • default: true

    是否启用 Session Registry

  • session_locking_strategy: local | leader | quorum | all

    • default: quorum

    Session 在集群中的锁策略。

    • loca: 仅锁本节点的 Session
    • one: 任选一个其它节点加锁
    • quorum: 选择集群中半数以上的节点加锁
    • all: 选择所有节点加锁
  • shared_subscription_strategy: random | round_robin | sticky | local | hash_topic | hash_clientid

    • default: round_robin

    共享订阅消息派发策略。

    • random: 随机挑选一个共享订阅者派发
    • round_robin: 使用 round-robin 策略派发
    • sticky: 总是使用上次选中的订阅者派发,直到它断开连接
    • hash: 使用发送者的 Client ID 进行 Hash 来选择订阅者
  • shared_dispatch_ack_enabled: boolean()

    • default: false

    启用/禁用 QoS 1 和 QoS 2 消息的共享派发确认。 开启后,允许将消息从未及时回复 ACK 的订阅者 (例如,客户端离线)重新派发给另外一个订阅者。

  • route_batch_clean: boolean()

    • default: true

    是否开启批量清除路由。

  • perf: broker:broker_perf

  • shared_subscription_group: {$name -> broker:shared_subscription_group}

# broker:broker_perf

Broker performance tuning parameters.

Config paths

  • broker.perf

Env overrides

  • EMQX_BROKER__PERF

Fields

  • route_lock_type: key | tab | global

    • default: key

    通配主题订阅/取消订阅性能调优。 建议仅当通配符主题较多时才更改此参数。

    注:当从/更改为 global 锁时,它要求集群中的所有节点在更改之前停止。

    • key: 为 Mnesia 事务涉及到的每个 key 上锁,建议单节点时使用。
    • tab: 为 Mnesia 事务涉及到的表上锁,建议在集群中使用。
    • global: 所以更新操作都被全局的锁保护,仅建议在超大规模集群中使用。
  • trie_compaction: boolean()

    • default: true

    是否开启主题表压缩存储。 启用它会显着提高通配符主题订阅率,如果通配符主题具有唯一前缀,例如:'sensor//+/',其中每个订阅者的 ID 是唯一的。 如果消息主要发布到具有大量级别的主题,则主题匹配性能(发布时)可能会降低。

    注意:这是一个集群范围的配置。 它要求在更改之前停止所有节点。

# broker:cache

Settings for the authorization cache.

Config paths

  • authorization.cache

Env overrides

  • EMQX_AUTHORIZATION__CACHE

Fields

  • enable: boolean()

    • default: true

    启用或禁用授权缓存。

  • max_size: 1..1048576

    • default: 32

    缓存项的最大数量。

  • ttl: emqx_schema:duration()

    • default: "1m"

    缓存数据的生存时间。

# broker:conn_congestion

Settings for conn_congestion alarm.

Sometimes the MQTT connection (usually an MQTT subscriber) may get "congested", because there are too many packets to be sent. The socket tries to buffer the packets until the buffer is full. If more packets arrive after that, the packets will be "pending" in the queue, and we consider the connection congested.

Note: sndbuf can be set to larger value if the alarm is triggered too often. The name of the alarm is of format conn_congestion/<ClientID>/<Username>, where the <ClientID> is the client ID of the congested MQTT connection, and <Username> is the username or unknown_user.

Config paths

  • conn_congestion

Env overrides

  • EMQX_CONN_CONGESTION

Fields

  • enable_alarm: boolean()

    • default: true

    启用或者禁用连接阻塞告警功能

  • min_alarm_sustain_duration: emqx_schema:duration()

    • default: "1m"

    清除警报前的最短时间。

    只有当队列中没有挂起的数据,并且连接至少被堵塞了 "min_alarm_sustain_duration" 毫秒时, 报警才会被清除。这是为了避免太频繁地清除和再次发出警报。

# broker:deflate_opts

Compression options.

Config paths

  • listeners.ws.$name.websocket.deflate_opts
  • listeners.wss.$name.websocket.deflate_opts

Env overrides

  • EMQX_LISTENERS__WS__$NAME__WEBSOCKET__DEFLATE_OPTS
  • EMQX_LISTENERS__WSS__$NAME__WEBSOCKET__DEFLATE_OPTS

Fields

  • level: none | default | best_compression | best_speed

    压缩级别

  • mem_level: 1..9

    • default: 8

    指定压缩状态的大小
    较低的值会减少每个连接的内存使用。

  • strategy: default | filtered | huffman_only | rle

    • default: default

    指定压缩策略。

  • server_context_takeover: takeover | no_takeover

    • default: takeover

    接管意味着在服务器消息之间保留压缩状态。

  • client_context_takeover: takeover | no_takeover

    • default: takeover

    接管意味着在客户端消息之间保留压缩状态。

  • server_max_window_bits: 8..15

    • default: 15

    指定服务器压缩上下文的大小。

  • client_max_window_bits: 8..15

    • default: 15

    指定客户端压缩上下文的大小。

# broker:event_names

Enable or disable client lifecycle event publishing.

The following options affect MQTT clients as well as gateway clients. The types of the clients are distinguished by the topic prefix:

  • For the MQTT clients, the format is: $SYS/broker/<node>/clients/<clientid>/<event>
  • For the Gateway clients, it is $SYS/broker/<node>/gateway/<gateway-name>/clients/<clientid>/<event>

Config paths

  • sys_topics.sys_event_messages

Env overrides

  • EMQX_SYS_TOPICS__SYS_EVENT_MESSAGES

Fields

  • client_connected: boolean()

    • default: true

    是否开启客户端已连接事件消息。

  • client_disconnected: boolean()

    • default: true

    是否开启客户端已断开连接事件消息。

  • client_subscribed: boolean()

    • default: false

    是否开启客户端已成功订阅主题事件消息。

  • client_unsubscribed: boolean()

    • default: false

    是否开启客户端已成功取消订阅主题事件消息。

# broker:flapping_detect

This config controls the allowed maximum number of CONNECT packets received from the same clientid in a time frame defined by window_time. After the limit is reached, successive CONNECT requests are forbidden (banned) until the end of the time period defined by ban_time.

Config paths

  • flapping_detect

Env overrides

  • EMQX_FLAPPING_DETECT

Fields

  • enable: boolean()

    • default: false

    启用抖动检测功能

  • max_count: integer()

    • default: 15

    MQTT 客户端在"窗口"时间内允许的最大断开次数

  • window_time: emqx_schema:duration()

    • default: "1m"

    抖动检测的时间窗口。

  • ban_time: emqx_schema:duration()

    • default: "5m"

    抖动的客户端将会被禁止登录多长时间

# broker:force_gc

Force garbage collection in MQTT connection process after they process certain number of messages or bytes of data.

Config paths

  • force_gc

Env overrides

  • EMQX_FORCE_GC

Fields

  • enable: boolean()

    • default: true

    启用强制垃圾回收

  • count: 0..inf

    • default: 16000

    在进程收到多少消息之后,对此进程执行垃圾回收

  • bytes: emqx_schema:bytesize()

    • default: "16MB"

    在进程处理过多少个字节之后,对此进程执行垃圾回收

# broker:force_shutdown

When the process message queue length, or the memory bytes reaches a certain value, the process is forced to close.

Note: "message queue" here refers to the "message mailbox" of the Erlang process, not the mqueue of QoS 1 and QoS 2.

Config paths

  • force_shutdown

Env overrides

  • EMQX_FORCE_SHUTDOWN

Fields

  • enable: boolean()

    • default: true

    启用 force_shutdown 功能

  • max_message_queue_len: 0..inf

    • default: 1000

    消息队列的最大长度

  • max_heap_size: emqx_schema:wordsize()

    • default: "32MB"

    Heap 的总大小

# broker:listener_ssl_opts

Socket options for SSL connections.

Config paths

  • gateway.exproto.listeners.ssl.$name.ssl_options
  • gateway.stomp.listeners.ssl.$name.ssl_options
  • listeners.ssl.$name.ssl_options

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__SSL_OPTIONS
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__SSL_OPTIONS
  • EMQX_LISTENERS__SSL__$NAME__SSL_OPTIONS

Fields

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    用于查找预共享密钥(PSK)标识的 EMQX 内部回调。

  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • dhfile: string()

    如果协商使用Diffie-Hellman密钥交换的密码套件,则服务器将使用包含PEM编码的Diffie-Hellman参数的文件的路径。如果未指定,则使用默认参数

    注意:TLS 1.3不支持dhfile选项。

  • fail_if_no_peer_cert: boolean()

    • default: false

    TLS/DTLS 服务器与 {verify,verify_peer} 一起使用。 如果设置为true,则如果客户端没有要发送的证书,即发送空证书,服务器将失败。 如果设置为false,则仅当客户端发送无效证书(空证书被视为有效证书)时才会失败。

  • honor_cipher_order: boolean()

    • default: true

    一个重要的安全设置,它强制根据服务器指定的顺序而不是客户机指定的顺序设置密码,从而强制服务器管理员执行(通常配置得更正确)安全顺序。

  • client_renegotiation: boolean()

    • default: true

    在支持客户机发起的重新协商的协议中,这种操作的资源成本对于服务器来说高于客户机。 这可能会成为拒绝服务攻击的载体。 SSL 应用程序已经采取措施来反击此类尝试,但通过将此选项设置为 false,可以严格禁用客户端发起的重新协商。 默认值为 true。请注意,由于基础密码套件可以加密的消息数量有限,禁用重新协商可能会导致长期连接变得不可用。

# broker:listener_wss_opts

Socket options for WebSocket/SSL connections.

Config paths

  • listeners.wss.$name.ssl_options

Env overrides

  • EMQX_LISTENERS__WSS__$NAME__SSL_OPTIONS

Fields

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    用于查找预共享密钥(PSK)标识的 EMQX 内部回调。

  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • dhfile: string()

    如果协商使用Diffie-Hellman密钥交换的密码套件,则服务器将使用包含PEM编码的Diffie-Hellman参数的文件的路径。如果未指定,则使用默认参数

    注意:TLS 1.3不支持dhfile选项。

  • fail_if_no_peer_cert: boolean()

    • default: false

    TLS/DTLS 服务器与 {verify,verify_peer} 一起使用。 如果设置为true,则如果客户端没有要发送的证书,即发送空证书,服务器将失败。 如果设置为false,则仅当客户端发送无效证书(空证书被视为有效证书)时才会失败。

  • honor_cipher_order: boolean()

    • default: true

    一个重要的安全设置,它强制根据服务器指定的顺序而不是客户机指定的顺序设置密码,从而强制服务器管理员执行(通常配置得更正确)安全顺序。

  • client_renegotiation: boolean()

    • default: true

    在支持客户机发起的重新协商的协议中,这种操作的资源成本对于服务器来说高于客户机。 这可能会成为拒绝服务攻击的载体。 SSL 应用程序已经采取措施来反击此类尝试,但通过将此选项设置为 false,可以严格禁用客户端发起的重新协商。 默认值为 true。请注意,由于基础密码套件可以加密的消息数量有限,禁用重新协商可能会导致长期连接变得不可用。

  • handshake_timeout: emqx_schema:duration()

    • default: "15s"

    握手完成所允许的最长时间

# broker:listeners

MQTT listeners identified by their protocol type and assigned names

Config paths

  • listeners

Env overrides

  • EMQX_LISTENERS

Fields

# broker:mqtt

Global MQTT configuration.
The configs here work as default values which can be overridden in zone configs

Config paths

  • mqtt

Env overrides

  • EMQX_MQTT

Fields

  • idle_timeout: infinity | emqx_schema:duration()

    • default: "15s"

    TCP 连接建立后,如果在 idle_timeout 指定的时间内未收到客户端的 MQTT CONNECT 报文,则连接将被断开。

  • max_packet_size: emqx_schema:bytesize()

    • default: "1MB"

    允许的最大 MQTT 报文大小。

  • max_clientid_len: 23..65535

    • default: 65535

    允许的最大 MQTT Client ID 长度。

  • max_topic_levels: 1..65535

    • default: 65535

    允许的最大主题层级。

  • max_qos_allowed: qos()

    • default: 2

    允许的最大 QoS 等级。

  • max_topic_alias: 0..65535

    • default: 65535

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

  • retain_available: boolean()

    • default: true

    是否启用对 MQTT 保留消息的支持。

  • wildcard_subscription: boolean()

    • default: true

    是否启用对 MQTT 通配符订阅的支持。

  • shared_subscription: boolean()

    • default: true

    是否启用对 MQTT 共享订阅的支持。

  • exclusive_subscription: boolean()

    • default: false

    是否启用对 MQTT 排它订阅的支持。

  • ignore_loop_deliver: boolean()

    • default: false

    是否为 MQTT v3.1.1/v3.1.0 客户端忽略投递自己发布的消息,类似于 MQTT 5.0 中的 No Local 订阅选项

  • strict_mode: boolean()

    • default: false

    是否以严格模式解析 MQTT 消息。 当设置为 true 时,例如客户端 ID、主题名称等中的无效 utf8 字符串将导致客户端断开连接。

  • response_information: string()

    • default: ""

    指定返回给客户端的响应信息。如果设置为 "",则禁用此功能。仅适用于使用 MQTT 5.0 协议的客户端。

  • server_keepalive: integer() | disabled

    • default: disabled

    EMQX 要求客户端使用的保活时间,配置为 disabled 表示将使用客户端指定的保活时间。需要用到 MQTT 5.0 中的 Server Keep Alive,因此仅适用于使用 MQTT 5.0 协议的客户端。

  • keepalive_backoff: number()

    • default: 0.75

    Broker 判定客户端保活超时使用的退避乘数。如果 EMQX 在 Keep Alive * Backoff * 2 秒内未收到任何报文,EMQX 将关闭当前连接。

  • max_subscriptions: 1..inf | infinity

    • default: infinity

    允许每个客户端建立的最大订阅数量。

  • upgrade_qos: boolean()

    • default: false

    投递消息时,是否根据订阅主题时的 QoS 等级来强制提升派发的消息的 QoS 等级。

  • max_inflight: 1..65535

    • default: 32

    允许在完成应答前同时投递的 QoS 1 和 QoS 2 消息的最大数量。

  • retry_interval: emqx_schema:duration()

    • default: "30s"

    QoS 1/2 消息的重新投递间隔。

  • max_awaiting_rel: integer() | infinity

    • default: 100

    PUBREL (Client -> Broker) 最大等待队列长度。

  • await_rel_timeout: emqx_schema:duration()

    • default: "300s"

    PUBREL (Client -> Broker) 最大等待时间,超时则会被丢弃。

  • session_expiry_interval: emqx_schema:duration()

    • default: "2h"

    指定会话将在连接断开后多久过期,仅适用于非 MQTT 5.0 的连接。

  • max_mqueue_len: non_neg_integer() | infinity

    • default: 1000

    消息队列最大长度。持久客户端断开连接或飞行窗口已满时排队的消息长度。

  • mqueue_priorities: map() | disabled

    • default: disabled

    主题优先级。取值范围 [1-255] 默认优先级表为空,即所有的主题优先级相同。

    注:优先主题名称中不支持使用逗号和等号。 注:不在此列表中的主题,被视为最高/最低优先级,这取决于mqtt.mqueue_default_priority 的配置

    示例: 配置 "topic/1" > "topic/2": mqueue_priorities: {"topic/1": 10, "topic/2": 8}

  • mqueue_default_priority: highest | lowest

    • default: lowest

    默认的主题优先级,不在 主题优先级mqueue_priorities) 中的主题将会使用该优先级。

  • mqueue_store_qos0: boolean()

    • default: true

    指定在连接断开但会话保持期间,是否需要在消息队列中存储 QoS 0 消息。

  • use_username_as_clientid: boolean()

    • default: false

    是否使用用户名作为客户端 ID。 此设置的作用时间晚于 使用对端证书作为用户名peer_cert_as_username) 和 使用对端证书作为客户端 IDpeer_cert_as_clientid)。

  • peer_cert_as_username: disabled | cn | dn | crt | pem | md5

    • default: disabled

    使用对端证书中的 CN, DN 字段或整个证书内容来作为用户名。仅适用于 TLS 连接。 目前支持配置为以下内容:

    • cn: 取证书的 CN 字段作为 Username
    • dn: 取证书的 DN 字段作为 Username
    • crt: 取 DERPEM 证书的内容作为 Username
    • pem: 将 DER 证书内容转换为 PEM 格式后作为 Username
    • md5: 取 DERPEM 证书的内容的 MD5 值作为 Username
  • peer_cert_as_clientid: disabled | cn | dn | crt | pem | md5

    • default: disabled

    使用对端证书中的 CN, DN 字段或整个证书内容来作为客户端 ID。仅适用于 TLS 连接。 目前支持配置为以下内容:

    • cn: 取证书的 CN 字段作为 Client ID
    • dn: 取证书的 DN 字段作为 Client ID
    • crt: 取 DERPEM 证书的内容作为 Client ID
    • pem: 将 DER 证书内容转换为 PEM 格式后作为 Client ID
    • md5: 取 DERPEM 证书的内容的 MD5 值作为 Client ID

# broker:mqtt_quic_listener

Settings for the MQTT over QUIC listener.

Config paths

  • listeners.quic.$name

Env overrides

  • EMQX_LISTENERS__QUIC__$NAME

Fields

  • certfile: string()

    证书文件

  • keyfile: string()

    私钥文件

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件,tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

    注:QUIC 监听器不支持 tlsv1.3 的 ciphers

  • idle_timeout: emqx_schema:duration()

    • default: "15s"

    关闭在此间隔内未发送 MQTT CONNECT 消息的客户端的传输层连接。

  • enabled: boolean()

    • default: true

    启停监听器

  • bind: emqx_schema:ip_port() | integer()

    • default: 14567

    监听套接字的 IP 地址和端口。

  • acceptors: pos_integer()

    • default: 16

    监听器接收池的大小。

  • max_connections: infinity | pos_integer()

    • default: infinity

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

  • mountpoint: binary()

    • default: ""

    发布或订阅时,请在所有主题前面加上 mountpoint 字符串。

    将消息传递给订阅者时,将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

    例如,如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant',那么客户端实际上订阅了主题'some_tenant/t'。
    类似地,如果另一个客户端B(与客户端A连接到同一个侦听器)向主题 't' 发送消息,该消息将路由到所有订阅了'some_租户/t'的客户端,因此客户端 A 将接收主题名为't'的消息

    设置为"" 以禁用该功能

    mountpoint 字符串中的变量:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    监听器所属的配置组。

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    速率限制类型

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

# broker:mqtt_ssl_listener

Settings for the MQTT over SSL listener.

Config paths

  • listeners.ssl.$name

Env overrides

  • EMQX_LISTENERS__SSL__$NAME

Fields

  • enabled: boolean()

    • default: true

    启停监听器

  • bind: emqx_schema:ip_port() | integer()

    • default: 8883

    监听套接字的 IP 地址和端口。

  • acceptors: pos_integer()

    • default: 16

    监听器接收池的大小。

  • max_connections: infinity | pos_integer()

    • default: infinity

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

  • mountpoint: binary()

    • default: ""

    发布或订阅时,请在所有主题前面加上 mountpoint 字符串。

    将消息传递给订阅者时,将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

    例如,如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant',那么客户端实际上订阅了主题'some_tenant/t'。
    类似地,如果另一个客户端B(与客户端A连接到同一个侦听器)向主题 't' 发送消息,该消息将路由到所有订阅了'some_租户/t'的客户端,因此客户端 A 将接收主题名为't'的消息

    设置为"" 以禁用该功能

    mountpoint 字符串中的变量:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    监听器所属的配置组。

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    速率限制类型

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • access_rules: [string()]

    • default: ["allow all"]

    此监听器的访问控制规则。

  • proxy_protocol: boolean()

    • default: false

    如果EMQX集群部署在 HAProxy 或 Nginx 之后,请启用代理协议 V1/2
    详情见: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    代理协议超时。如果在超时时间内未收到代理协议数据包,EMQX将关闭TCP连接。

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    监听器认证重载。

    认证配置可以是单个认证器实例,也可以是一个认证器数组组成的认证链。 执行登录验证时(用户名、客户端 ID 等),将按配置的顺序执行

  • tcp_options: broker:tcp_opts

  • ssl_options: broker:listener_ssl_opts

# broker:mqtt_tcp_listener

Settings for the MQTT over TCP listener.

Config paths

  • listeners.tcp.$name

Env overrides

  • EMQX_LISTENERS__TCP__$NAME

Fields

  • enabled: boolean()

    • default: true

    启停监听器

  • bind: emqx_schema:ip_port() | integer()

    • default: 1883

    监听套接字的 IP 地址和端口。

  • acceptors: pos_integer()

    • default: 16

    监听器接收池的大小。

  • max_connections: infinity | pos_integer()

    • default: infinity

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

  • mountpoint: binary()

    • default: ""

    发布或订阅时,请在所有主题前面加上 mountpoint 字符串。

    将消息传递给订阅者时,将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

    例如,如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant',那么客户端实际上订阅了主题'some_tenant/t'。
    类似地,如果另一个客户端B(与客户端A连接到同一个侦听器)向主题 't' 发送消息,该消息将路由到所有订阅了'some_租户/t'的客户端,因此客户端 A 将接收主题名为't'的消息

    设置为"" 以禁用该功能

    mountpoint 字符串中的变量:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    监听器所属的配置组。

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    速率限制类型

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • access_rules: [string()]

    • default: ["allow all"]

    此监听器的访问控制规则。

  • proxy_protocol: boolean()

    • default: false

    如果EMQX集群部署在 HAProxy 或 Nginx 之后,请启用代理协议 V1/2
    详情见: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    代理协议超时。如果在超时时间内未收到代理协议数据包,EMQX将关闭TCP连接。

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    监听器认证重载。

    认证配置可以是单个认证器实例,也可以是一个认证器数组组成的认证链。 执行登录验证时(用户名、客户端 ID 等),将按配置的顺序执行

  • tcp_options: broker:tcp_opts

# broker:mqtt_ws_listener

Settings for the MQTT over WebSocket listener.

Config paths

  • listeners.ws.$name

Env overrides

  • EMQX_LISTENERS__WS__$NAME

Fields

  • enabled: boolean()

    • default: true

    启停监听器

  • bind: emqx_schema:ip_port() | integer()

    • default: 8083

    监听套接字的 IP 地址和端口。

  • acceptors: pos_integer()

    • default: 16

    监听器接收池的大小。

  • max_connections: infinity | pos_integer()

    • default: infinity

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

  • mountpoint: binary()

    • default: ""

    发布或订阅时,请在所有主题前面加上 mountpoint 字符串。

    将消息传递给订阅者时,将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

    例如,如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant',那么客户端实际上订阅了主题'some_tenant/t'。
    类似地,如果另一个客户端B(与客户端A连接到同一个侦听器)向主题 't' 发送消息,该消息将路由到所有订阅了'some_租户/t'的客户端,因此客户端 A 将接收主题名为't'的消息

    设置为"" 以禁用该功能

    mountpoint 字符串中的变量:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    监听器所属的配置组。

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    速率限制类型

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • access_rules: [string()]

    • default: ["allow all"]

    此监听器的访问控制规则。

  • proxy_protocol: boolean()

    • default: false

    如果EMQX集群部署在 HAProxy 或 Nginx 之后,请启用代理协议 V1/2
    详情见: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    代理协议超时。如果在超时时间内未收到代理协议数据包,EMQX将关闭TCP连接。

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    监听器认证重载。

    认证配置可以是单个认证器实例,也可以是一个认证器数组组成的认证链。 执行登录验证时(用户名、客户端 ID 等),将按配置的顺序执行

  • tcp_options: broker:tcp_opts

  • websocket: broker:ws_opts

# broker:mqtt_wss_listener

Settings for the MQTT over WebSocket/SSL listener.

Config paths

  • listeners.wss.$name

Env overrides

  • EMQX_LISTENERS__WSS__$NAME

Fields

  • enabled: boolean()

    • default: true

    启停监听器

  • bind: emqx_schema:ip_port() | integer()

    • default: 8084

    监听套接字的 IP 地址和端口。

  • acceptors: pos_integer()

    • default: 16

    监听器接收池的大小。

  • max_connections: infinity | pos_integer()

    • default: infinity

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

  • mountpoint: binary()

    • default: ""

    发布或订阅时,请在所有主题前面加上 mountpoint 字符串。

    将消息传递给订阅者时,将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。

    例如,如果客户机 A 使用 listeners.tcp.<name>.mountpoint 设置为'some_tenant',那么客户端实际上订阅了主题'some_tenant/t'。
    类似地,如果另一个客户端B(与客户端A连接到同一个侦听器)向主题 't' 发送消息,该消息将路由到所有订阅了'some_租户/t'的客户端,因此客户端 A 将接收主题名为't'的消息

    设置为"" 以禁用该功能

    mountpoint 字符串中的变量:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    监听器所属的配置组。

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    速率限制类型

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • access_rules: [string()]

    • default: ["allow all"]

    此监听器的访问控制规则。

  • proxy_protocol: boolean()

    • default: false

    如果EMQX集群部署在 HAProxy 或 Nginx 之后,请启用代理协议 V1/2
    详情见: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    代理协议超时。如果在超时时间内未收到代理协议数据包,EMQX将关闭TCP连接。

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    监听器认证重载。

    认证配置可以是单个认证器实例,也可以是一个认证器数组组成的认证链。 执行登录验证时(用户名、客户端 ID 等),将按配置的顺序执行

  • tcp_options: broker:tcp_opts

  • ssl_options: broker:listener_wss_opts

  • websocket: broker:ws_opts

# broker:overload_protection

Overload protection mechanism monitors the load of the system and temporarily disables some features (such as accepting new connections) when the load is high.

Config paths

  • overload_protection

Env overrides

  • EMQX_OVERLOAD_PROTECTION

Fields

  • enable: boolean()

    • default: false

    是否对系统过载做出反应

  • backoff_delay: 0..inf

    • default: 1

    一些不重要的任务可能会延迟执行,以毫秒为单位设置延迟

  • backoff_gc: boolean()

    • default: false

    如有必要,跳过强制GC

  • backoff_hibernation: boolean()

    • default: true

    如有必要,跳过进程休眠

  • backoff_new_conn: boolean()

    • default: true

    如有必要,关闭新进来的连接

# broker:persistent_session_builtin

Settings for the built-in storage engine of persistent messages.

Config paths

  • persistent_session_store.backend

Env overrides

  • EMQX_PERSISTENT_SESSION_STORE__BACKEND

Fields

# broker:persistent_session_store

Settings for message persistence.

Config paths

  • persistent_session_store

Env overrides

  • EMQX_PERSISTENT_SESSION_STORE

Fields

  • enabled: boolean()

    • default: false

    使用数据库存储有关持久会话的信息。 这使得在节点停止时,可以将客户端连接迁移到另一个群集节点。

  • on_disc: boolean()

    • default: true

    将持久会话数据保存在磁盘上。如果为 false 则存储在内存中。 如开启, 持久会话数据可在集群重启后恢复。 如关闭, 数据仅存储在内存中, 则在整个集群停止后丢失。

  • ram_cache: boolean()

    • default: false

    在内存中保持一份数据的副本,以便更快地访问。

  • backend: broker:persistent_session_builtin

    • default:
    {
      messages {ram_cache = "false"}
      session {ram_cache = "true"}
      session_messages {ram_cache = "true"}
      type = "builtin"
    }
    
    1
    2
    3
    4
    5
    6

    用于存储持久性会话和信息的数据库管理后端

    • builtin: 使用内置的数据库(mria)
  • max_retain_undelivered: emqx_schema:duration()

    • default: "1h"

    如果重新启动时处理上一个会话的节点已停止,则未传递到持久会话的消息在垃圾收集之前会被存储。

  • message_gc_interval: emqx_schema:duration()

    • default: "1h"

    将未送达的消息垃圾收集到持久会话的开始间隔。 这会影响检查 "max_retain_undelivered"(最大保留未送达)的删除频率。

  • session_message_gc_interval: emqx_schema:duration()

    • default: "1m"

    持久会话消息的临时数据垃圾收集的开始间隔。 这不会影响持久会话消息的生命周期长度。

# broker:persistent_table_mria_opts

Tuning options for the mria table.

Config paths

  • persistent_session_store.backend.messages
  • persistent_session_store.backend.session
  • persistent_session_store.backend.session_messages

Env overrides

  • EMQX_PERSISTENT_SESSION_STORE__BACKEND__MESSAGES
  • EMQX_PERSISTENT_SESSION_STORE__BACKEND__SESSION
  • EMQX_PERSISTENT_SESSION_STORE__BACKEND__SESSION_MESSAGES

Fields

  • ram_cache: boolean()

    • default: true

    在内存中保持一份数据的副本,以便更快地访问。

# broker:shared_subscription_group

Per group dispatch strategy for shared subscription

Config paths

  • broker.shared_subscription_group.$name

Env overrides

  • EMQX_BROKER__SHARED_SUBSCRIPTION_GROUP__$NAME

Fields

  • strategy: random | round_robin | sticky | local | hash_topic | hash_clientid
    • default: random

# broker:ssl_client_opts

Socket options for SSL clients.

Config paths

  • authentication.$INDEX.ssl
  • authorization.sources.$INDEX.ssl
  • bridges.mqtt.$name.connector.ssl
  • bridges.webhook.$name.ssl
  • cluster.etcd.ssl
  • connectors.mqtt.$name.ssl
  • gateway.coap.authentication.ssl
  • gateway.coap.listeners.dtls.$name.authentication.ssl
  • gateway.coap.listeners.udp.$name.authentication.ssl
  • gateway.exproto.authentication.ssl
  • gateway.exproto.handler.ssl_options
  • gateway.exproto.listeners.dtls.$name.authentication.ssl
  • gateway.exproto.listeners.ssl.$name.authentication.ssl
  • gateway.exproto.listeners.tcp.$name.authentication.ssl
  • gateway.exproto.listeners.udp.$name.authentication.ssl
  • gateway.lwm2m.authentication.ssl
  • gateway.lwm2m.listeners.dtls.$name.authentication.ssl
  • gateway.lwm2m.listeners.udp.$name.authentication.ssl
  • gateway.mqttsn.authentication.ssl
  • gateway.mqttsn.listeners.dtls.$name.authentication.ssl
  • gateway.mqttsn.listeners.udp.$name.authentication.ssl
  • gateway.stomp.authentication.ssl
  • gateway.stomp.listeners.ssl.$name.authentication.ssl
  • gateway.stomp.listeners.tcp.$name.authentication.ssl
  • listeners.ssl.$name.authentication.$INDEX.ssl
  • listeners.tcp.$name.authentication.$INDEX.ssl
  • listeners.ws.$name.authentication.$INDEX.ssl
  • listeners.wss.$name.authentication.$INDEX.ssl

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__SSL
  • EMQX_AUTHORIZATION__SOURCES__$INDEX__SSL
  • EMQX_BRIDGES__MQTT__$NAME__CONNECTOR__SSL
  • EMQX_BRIDGES__WEBHOOK__$NAME__SSL
  • EMQX_CLUSTER__ETCD__SSL
  • EMQX_CONNECTORS__MQTT__$NAME__SSL
  • EMQX_GATEWAY__COAP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__HANDLER__SSL_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__SSL

Fields

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    用于查找预共享密钥(PSK)标识的 EMQX 内部回调。

  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • enable: boolean()

    • default: false

    启用 TLS

  • server_name_indication: disable | string()

    指定要在 TLS 服务器名称指示扩展中使用的主机名
    例如,当连接到 "server.example.net" 时,接受连接并执行 TLS 握手的真正服务器可能与 TLS 客户端最初连接到的主机不同, 例如,当连接到 IP 地址时,或者当主机具有多个可解析的 DNS 记录时
    如果未指定,它将默认为使用的主机名字符串 建立连接,除非使用 IP 地址
    然后,主机名也用于对等机的主机名验证 证书
    特殊值'disable'阻止发送服务器名称指示扩展,并禁用主机名验证检查。

# broker:stats

Enable/disable statistic data collection. Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.

Config paths

  • stats

Env overrides

  • EMQX_STATS

Fields

  • enable: boolean()

    • default: true

    启用/禁用统计数据收集功能

# broker:sys_topics

The EMQX Broker periodically publishes its own status, message statistics, client online and offline events to the system topic starting with $SYS/.

The following options control the behavior of $SYS topics.

Config paths

  • sys_topics

Env overrides

  • EMQX_SYS_TOPICS

Fields

  • sys_msg_interval: disabled | emqx_schema:duration()

    • default: "1m"

    发送 $SYS 主题的间隔时间。

  • sys_heartbeat_interval: disabled | emqx_schema:duration()

    • default: "30s"

    发送心跳系统消息的间隔时间,它包括:

    • $SYS/brokers/<node>/uptime
    • $SYS/brokers/<node>/datetime
  • sys_event_messages: broker:event_names

    客户端事件消息

# broker:sysmon

Features related to system monitoring and introspection.

Config paths

  • sysmon

Env overrides

  • EMQX_SYSMON

Fields

# broker:sysmon_os

This part of the configuration is responsible for monitoring the host OS health, such as free memory, disk space, CPU load, etc.

Config paths

  • sysmon.os

Env overrides

  • EMQX_SYSMON__OS

Fields

  • cpu_check_interval: emqx_schema:duration()

    • default: "60s"

    定期 CPU 检查的时间间隔。

  • cpu_high_watermark: emqx_schema:percent()

    • default: "80%"

    在发出相应警报之前可以使用多少系统 CPU 的阈值,以系统CPU负载的百分比表示。

  • cpu_low_watermark: emqx_schema:percent()

    • default: "60%"

    在解除相应警报之前可以使用多少系统 CPU 的阈值,以系统CPU负载的百分比表示。

  • mem_check_interval: disabled | emqx_schema:duration()

    • default: "60s"

    定期内存检查的时间间隔。

  • sysmem_high_watermark: emqx_schema:percent()

    • default: "70%"

    在发出相应报警之前可以分配多少系统内存的阈值,以系统内存的百分比表示。

  • procmem_high_watermark: emqx_schema:percent()

    • default: "5%"

    在发出相应警报之前,一个Erlang进程可以分配多少系统内存的阈值,以系统内存的百分比表示。

# broker:sysmon_top

This part of the configuration is responsible for monitoring the Erlang processes in the VM. This information can be sent to an external PostgreSQL database. This feature is inactive unless the PostgreSQL sink is configured.

Config paths

  • sysmon.top

Env overrides

  • EMQX_SYSMON__TOP

Fields

  • num_items: non_neg_integer()

    • default: 10
    • mapping: system_monitor.top_num_items

    每个监视组的顶级进程数

  • sample_interval: emqx_schema:duration()

    • default: "2s"
    • mapping: system_monitor.top_sample_interval

    指定应收集进程顶部的频率

  • max_procs: non_neg_integer()

    • default: 1000000
    • mapping: system_monitor.top_max_procs

    当VM中的进程数超过此值时,停止收集数据

  • db_hostname: string()

    • default: []
    • mapping: system_monitor.db_hostname

    收集数据点的 PostgreSQL 数据库的主机名

  • db_port: integer()

    • default: 5432
    • mapping: system_monitor.db_port

    收集数据点的 PostgreSQL 数据库的端口

  • db_username: string()

    • default: "system_monitor"
    • mapping: system_monitor.db_username

    PostgreSQL 数据库的用户名

  • db_password: binary()

    • default: "system_monitor_password"
    • mapping: system_monitor.db_password

    PostgreSQL 数据库的密码

  • db_name: string()

    • default: "postgres"
    • mapping: system_monitor.db_name

    PostgreSQL 数据库的数据库名

# broker:sysmon_vm

This part of the configuration is responsible for collecting BEAM VM events, such as long garbage collection, traffic congestion in the inter-broker communication, etc.

Config paths

  • sysmon.vm

Env overrides

  • EMQX_SYSMON__VM

Fields

  • process_check_interval: emqx_schema:duration()

    • default: "30s"

    定期进程限制检查的时间间隔。

  • process_high_watermark: emqx_schema:percent()

    • default: "80%"

    在发出相应警报之前,本地节点上可以同时存在多少进程的阈值(以进程百分比表示)。

  • process_low_watermark: emqx_schema:percent()

    • default: "60%"

    在清除相应警报之前,本地节点上可以同时存在多少进程的阈值(以进程百分比表示)。

  • long_gc: disabled | emqx_schema:duration()

    • default: disabled

    启用长垃圾回收监控

  • long_schedule: disabled | emqx_schema:duration()

    • default: "240ms"

    启用长调度监控

  • large_heap: disabled | emqx_schema:bytesize()

    • default: "32MB"

    启用大 heap 监控

  • busy_dist_port: boolean()

    • default: true

    启用分布式端口过忙监控

  • busy_port: boolean()

    • default: true

    启用端口过忙监控

# broker:tcp_opts

TCP listener options.

Config paths

  • gateway.exproto.listeners.ssl.$name.tcp_options
  • gateway.exproto.listeners.tcp.$name.tcp_options
  • gateway.stomp.listeners.ssl.$name.tcp_options
  • gateway.stomp.listeners.tcp.$name.tcp_options
  • listeners.ssl.$name.tcp_options
  • listeners.tcp.$name.tcp_options
  • listeners.ws.$name.tcp_options
  • listeners.wss.$name.tcp_options

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__TCP_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__TCP_OPTIONS
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__TCP_OPTIONS
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__SSL__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__TCP__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__WS__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__WSS__$NAME__TCP_OPTIONS

Fields

  • active_n: integer()

    • default: 100

    为此套接字指定{active,N}选项
    See: https://erlang.org/doc/man/inet.html#setopts-2

  • backlog: pos_integer()

    • default: 1024

    TCP backlog 定义了挂起连接队列可以增长到的最大长度。

  • send_timeout: emqx_schema:duration()

    • default: "15s"

    连接的TCP发送超时。

  • send_timeout_close: boolean()

    • default: true

    如果发送超时,则关闭连接。

  • recbuf: emqx_schema:bytesize()

    连接的 TCP 接收缓冲区(OS内核)。

  • sndbuf: emqx_schema:bytesize()

    连接的 TCP 发送缓冲区(OS内核)。

  • buffer: emqx_schema:bytesize()

    • default: "4KB"

    驱动程序使用的用户空间缓冲区的大小。

  • high_watermark: emqx_schema:bytesize()

    • default: "1MB"

    当 VM 套接字实现内部排队的数据量达到此限制时,套接字将设置为忙碌状态。

  • nodelay: boolean()

    • default: true

    连接的 TCP_NODELAY 标识

  • reuseaddr: boolean()

    • default: true

    连接的 SO_REUSEADDR 标识

# broker:trace

Real-time filtering logs for the ClientID or Topic or IP for debugging.

Config paths

  • trace

Env overrides

  • EMQX_TRACE

Fields

  • payload_encode: hex | text | hidden

    • default: text

    确定跟踪文件中有效负载格式的格式
    text:基于文本的协议或纯文本协议。 建议在有效负载为JSON编码时使用
    hex:二进制十六进制编码。当有效负载是自定义二进制协议时,建议使用此选项
    hidden:有效负载被模糊化为 ******

# broker:ws_opts

WebSocket listener options.

Config paths

  • listeners.ws.$name.websocket
  • listeners.wss.$name.websocket

Env overrides

  • EMQX_LISTENERS__WS__$NAME__WEBSOCKET
  • EMQX_LISTENERS__WSS__$NAME__WEBSOCKET

Fields

  • mqtt_path: string()

    • default: "/mqtt"

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

  • mqtt_piggyback: single | multiple

    • default: multiple

    WebSocket消息是否允许包含多个 MQTT 数据包。

  • compress: boolean()

    • default: false

    如果 true,则使用zlib 压缩 WebSocket 消息
    deflate_opts 下的配置项属于压缩相关参数配置。

  • idle_timeout: emqx_schema:duration()

    • default: "7200s"

    关闭在此间隔内未发送 MQTT CONNECT 消息的客户端的传输层连接。

  • max_frame_size: infinity | integer()

    • default: infinity

    单个 MQTT 数据包的最大长度。

  • fail_if_no_subprotocol: boolean()

    • default: true

    如果true,当客户端未携带Sec WebSocket Protocol字段时,服务器将返回一个错误。
    注意:微信小程序需要禁用此验证。

  • supported_subprotocols: emqx_schema:comma_separated_list()

    • default: "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5"

    逗号分隔的 subprotocols 支持列表。

  • check_origin_enable: boolean()

    • default: false

    如果trueoriginHTTP 头将根据check_origins参数中配置的允许来源列表进行验证。

  • allow_origin_absence: boolean()

    • default: true

    If false and check_origin_enable is true, the server will reject requests that don't have origin HTTP header.

  • check_origins: emqx_schema:comma_separated_binary()

    • default: "http://localhost:18083, http://127.0.0.1:18083"

    允许的 origins 列表

  • proxy_address_header: string()

    • default: "x-forwarded-for"

    HTTP 头,用于传递有关客户端 IP 地址的信息。 当 EMQX 集群部署在负载平衡器后面时,这一点非常重要。

  • proxy_port_header: string()

    • default: "x-forwarded-port"

    HTTP 头,用于传递有关客户端端口的信息。 当 EMQX 集群部署在负载平衡器后面时,这一点非常重要。

  • deflate_opts: broker:deflate_opts

# broker:zone

A Zone defines a set of configuration items (such as the maximum number of connections) that can be shared between multiple listeners.

Listener can refer to a Zone through the configuration item listener.<Protocol>.<Listener Name>.zone.

The configs defined in the zones will override the global configs with the same key.

For example, given the following config:

a {
    b: 1, c: 1
}
zone.my_zone {
  a {
    b:2
  }
}
1
2
3
4
5
6
7
8

The global config a is overridden by the configs a inside the zone my_zone.

If there is a listener using the zone my_zone, the value of config a will be: {b:2, c: 1}. Note that although the default value of a.c is 0, the global value is used, i.e. configs in the zone have no default values. To override a.c one must configure it explicitly in the zone.

All the global configs that can be overridden in zones are:

  • stats.*
  • mqtt.*
  • authorization.*
  • flapping_detect.*
  • force_shutdown.*
  • conn_congestion.*
  • force_gc.*

Config paths

  • zones.$name

Env overrides

  • EMQX_ZONES__$NAME

Fields

# connector:connectors

EMQX 连接器的配置。
连接器维护与外部资源相关的数据,比如 MySQL 数据库。

Config paths

  • connectors

Env overrides

  • EMQX_CONNECTORS

Fields

# dashboard

EMQX仪表板配置

Config paths

  • dashboard

Env overrides

  • EMQX_DASHBOARD

Fields

  • listeners: dashboard:listeners

    仪表盘监听器设置。

  • default_username: binary()

    • default: "admin"

    默认的仪表板用户名

  • default_password: binary()

    • default: "public"

    默认的仪表板用户密码 为了安全,应该尽快修改密码。

  • sample_interval: emqx_schema:duration_s()

    • default: "10s"

    更新仪表板中显示的指标的时间间隔。必须小于60,且被60的整除。

  • token_expired_time: emqx_schema:duration()

    • default: "60m"

    JWT token 过期时间

  • cors: boolean()

    • default: false

    支持跨域资源共享(CORS) 允许服务器指示任何来源(域名、协议或端口),除了本服务器之外的任何浏览器应允许加载资源。

  • i18n_lang: en | zh

    • default: en

    swagger多语言支持

# dashboard:http

仪表板监听器(HTTP)配置

Config paths

  • dashboard.listeners.http

Env overrides

  • EMQX_DASHBOARD__LISTENERS__HTTP

Fields

  • enable: boolean()

    • default: true

    忽略或启用该监听器配置

  • bind: non_neg_integer() | emqx_schema:ip_port()

    • default: 18083

    监听的地址与端口,在dashboard更新此配置时,会重启dashboard服务。

  • num_acceptors: integer()

    • default: 4

    TCP协议的Socket acceptor池大小

  • max_connections: integer()

    • default: 512

    同时处理的最大连接数

  • backlog: integer()

    • default: 1024

    排队等待连接的队列的最大长度

  • send_timeout: emqx_schema:duration()

    • default: "5s"

    Socket发送超时时间

  • inet6: boolean()

    • default: false

    启用IPv6, 如果机器不支持IPv6,请关闭此选项,否则会导致仪表盘无法使用。

  • ipv6_v6only: boolean()

    • default: false

    当开启 inet6 功能的同时禁用 IPv4-to-IPv6 映射。该配置仅在 inet6 功能开启时有效。

# dashboard:https

仪表板监听器(HTTPS)配置

Config paths

  • dashboard.listeners.https

Env overrides

  • EMQX_DASHBOARD__LISTENERS__HTTPS

Fields

  • enable: boolean()

    • default: false

    忽略或启用该监听器配置

  • bind: non_neg_integer() | emqx_schema:ip_port()

    • default: 18084

    监听的地址与端口,在dashboard更新此配置时,会重启dashboard服务。

  • num_acceptors: integer()

    • default: 4

    TCP协议的Socket acceptor池大小

  • max_connections: integer()

    • default: 512

    同时处理的最大连接数

  • backlog: integer()

    • default: 1024

    排队等待连接的队列的最大长度

  • send_timeout: emqx_schema:duration()

    • default: "5s"

    Socket发送超时时间

  • inet6: boolean()

    • default: false

    启用IPv6, 如果机器不支持IPv6,请关闭此选项,否则会导致仪表盘无法使用。

  • ipv6_v6only: boolean()

    • default: false

    当开启 inet6 功能的同时禁用 IPv4-to-IPv6 映射。该配置仅在 inet6 功能开启时有效。

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    用于查找预共享密钥(PSK)标识的 EMQX 内部回调。

  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • dhfile: string()

    如果协商使用Diffie-Hellman密钥交换的密码套件,则服务器将使用包含PEM编码的Diffie-Hellman参数的文件的路径。如果未指定,则使用默认参数

    注意:TLS 1.3不支持dhfile选项。

  • honor_cipher_order: boolean()

    • default: true

    一个重要的安全设置,它强制根据服务器指定的顺序而不是客户机指定的顺序设置密码,从而强制服务器管理员执行(通常配置得更正确)安全顺序。

  • client_renegotiation: boolean()

    • default: true

    在支持客户机发起的重新协商的协议中,这种操作的资源成本对于服务器来说高于客户机。 这可能会成为拒绝服务攻击的载体。 SSL 应用程序已经采取措施来反击此类尝试,但通过将此选项设置为 false,可以严格禁用客户端发起的重新协商。 默认值为 true。请注意,由于基础密码套件可以加密的消息数量有限,禁用重新协商可能会导致长期连接变得不可用。

  • handshake_timeout: emqx_schema:duration()

    • default: "15s"

    握手完成所允许的最长时间

# dashboard:listeners

仪表板监听器配置

Config paths

  • dashboard.listeners

Env overrides

  • EMQX_DASHBOARD__LISTENERS

Fields

# exhook

External hook (exhook) configuration.

Config paths

  • exhook

Env overrides

  • EMQX_EXHOOK

Fields

# exhook:server

gRPC server configuration.

Config paths

  • exhook.servers.$INDEX

Env overrides

  • EMQX_EXHOOK__SERVERS__$INDEX

Fields

  • name: binary()

    ExHook 服务器名称

  • enable: boolean()

    • default: true

    开启这个 Exhook 服务器

  • url: binary()

    gRPC 服务器地址

  • request_timeout: emqx_schema:duration()

    • default: "5s"

    gRPC 服务器请求超时时间

  • failed_action: deny | ignore

    • default: deny

    当 gRPC 请求失败后的操作

  • ssl: exhook:ssl_conf

  • socket_options: exhook:socket_options

    • default: {keepalive = true, nodelay = true}
  • auto_reconnect: false | emqx_schema:duration()

    • default: "60s"

    自动重连到 gRPC 服务器的设置。 当 gRPC 服务器不可用时,Exhook 将会按照这里设置的间隔时间进行重连,并重新初始化注册的钩子

  • pool_size: pos_integer()

    • default: 8

    gRPC 客户端进程池大小

# exhook:socket_options

连接套接字设置

Config paths

  • exhook.servers.$INDEX.socket_options

Env overrides

  • EMQX_EXHOOK__SERVERS__$INDEX__SOCKET_OPTIONS

Fields

  • keepalive: boolean()

    • default: true

    当没有其他数据交换时,是否向连接的对端套接字定期的发送探测包。如果另一端没有响应,则认为连接断开,并向控制进程发送错误消息

  • nodelay: boolean()

    • default: true

    如果为 true,则为套接字设置 TCP_NODELAY 选项,这意味着会立即发送数据包

  • recbuf: emqx_schema:bytesize()

    套接字的最小接收缓冲区大小

  • sndbuf: emqx_schema:bytesize()

    套接字的最小发送缓冲区大小

# exhook:ssl_conf

SSL client configuration.

Config paths

  • exhook.servers.$INDEX.ssl

Env overrides

  • EMQX_EXHOOK__SERVERS__$INDEX__SSL

Fields

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • enable: boolean()

    • default: false

    启用 TLS

  • server_name_indication: disable | string()

    指定要在 TLS 服务器名称指示扩展中使用的主机名
    例如,当连接到 "server.example.net" 时,接受连接并执行 TLS 握手的真正服务器可能与 TLS 客户端最初连接到的主机不同, 例如,当连接到 IP 地址时,或者当主机具有多个可解析的 DNS 记录时
    如果未指定,它将默认为使用的主机名字符串 建立连接,除非使用 IP 地址
    然后,主机名也用于对等机的主机名验证 证书
    特殊值'disable'阻止发送服务器名称指示扩展,并禁用主机名验证检查。

# gateway:clientinfo_override

ClientInfo override.

Config paths

  • gateway.coap.clientinfo_override
  • gateway.exproto.clientinfo_override
  • gateway.lwm2m.clientinfo_override
  • gateway.mqttsn.clientinfo_override
  • gateway.stomp.clientinfo_override

Env overrides

  • EMQX_GATEWAY__COAP__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__EXPROTO__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__LWM2M__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__MQTTSN__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__STOMP__CLIENTINFO_OVERRIDE

Fields

  • username: binary()

    username 重写模板

  • password: binary()

    password 重写模板

  • clientid: binary()

    clientid 重写模板

# gateway:coap

The CoAP protocol gateway provides EMQX with the access capability of the CoAP protocol. It allows publishing, subscribing, and receiving messages to EMQX in accordance with a certain defined CoAP message format.

Config paths

  • gateway.coap

Env overrides

  • EMQX_GATEWAY__COAP

Fields

  • heartbeat: emqx_gateway_schema:duration()

    • default: "30s"

    CoAP 网关要求客户端的最小心跳间隔时间。 当 connection_required 开启后,该参数用于检查客户端连接是否存活

  • connection_required: boolean()

    • default: false

    是否开启连接模式。 连接模式是非标准协议的功能。它维护 CoAP 客户端上线、认证、和连接状态的保持

  • notify_type: non | con | qos

    • default: qos

    投递给 CoAP 客户端的通知消息类型。当客户端 Observe 一个资源(或订阅某个主题)时,网关会向客户端推送新产生的消息。其消息类型可设置为:

    • non: 不需要客户端返回确认消息;
    • con: 需要客户端返回一个确认消息;
    • qos: 取决于消息的 QoS 等级; QoS 0 会以 non 类型下发,QoS 1/2 会以 con 类型下发
  • subscribe_qos: qos0 | qos1 | qos2 | coap

    • default: coap

    客户端订阅请求的默认 QoS 等级。 当 CoAP 客户端发起订阅请求时,如果未携带 qos 参数则会使用该默认值。默认值可设置为:

    • qos0、qos1、qos2: 设置为固定的 QoS 等级
    • coap: 依据订阅操作的 CoAP 报文类型来动态决定
      • 当订阅请求为 non-confirmable 类型时,取值为 qos0
      • 当订阅请求为 confirmable 类型时,取值为 qos1
  • publish_qos: qos0 | qos1 | qos2 | coap

    • default: coap

    客户端发布请求的默认 QoS 等级。 当 CoAP 客户端发起发布请求时,如果未携带 qos 参数则会使用该默认值。默认值可设置为:

    • qos0、qos1、qos2: 设置为固定的 QoS 等级
    • coap: 依据发布操作的 CoAP 报文类型来动态决定
      • 当发布请求为 non-confirmable 类型时,取值为 qos0
      • 当发布请求为 confirmable 类型时,取值为 qos1
  • mountpoint: binary()

    • default: ""
  • listeners: gateway:udp_listeners

    配置 UDP 类型的监听器

  • enable: boolean()

    • default: true

    是否启用该网关

  • enable_stats: boolean()

    • default: true

    是否开启客户端统计

  • idle_timeout: emqx_gateway_schema:duration()

    • default: "30s"

    客户端连接过程的空闲时间。该配置用于:

    1. 一个新创建的客户端进程如果在该时间间隔内没有收到任何客户端请求,将被直接关闭。
    2. 一个正在运行的客户进程如果在这段时间后没有收到任何客户请求,将进入休眠状态以节省资源。
  • clientinfo_override: gateway:clientinfo_override

    ClientInfo 重写。

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    网关的认证器配置,对该网关下所以的监听器生效。如果每个监听器需要配置不同的认证器,需要配置监听器下的 authentication 字段

# gateway:dtls_listener

Settings for the DTLS listener.

Config paths

  • gateway.coap.listeners.dtls.$name
  • gateway.exproto.listeners.dtls.$name
  • gateway.lwm2m.listeners.dtls.$name
  • gateway.mqttsn.listeners.dtls.$name

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME

Fields

  • acceptors: integer()

    • default: 16

    Acceptor 进程池大小。

  • udp_options: gateway:udp_opts

  • enable: boolean()

    • default: true

    是否启用该监听器。

  • bind: emqx_gateway_schema:ip_port() | integer()

    监听器绑定的 IP 地址或端口。

  • max_connections: integer()

    • default: 1024

    监听器支持的最大连接数。

  • max_conn_rate: integer()

    • default: 1000

    监听器支持的最大连接速率。

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    网关的认证器配置,对该网关下所以的监听器生效。如果每个监听器需要配置不同的认证器,需要配置监听器下的 authentication 字段

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • mountpoint: binary()

    发布或订阅时,在所有主题前增加前缀字符串。 当消息投递给订阅者时,前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。 例如,如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t,则客户端实际上订阅了 some_tenant/t 主题。 类似地,如果另一个客户端 B(连接到与客户端 A 相同的侦听器)向主题 t 发送消息,则该消息被路由到所有订阅了 some_tenant/t 的客户端,因此客户端 A 将收到该消息,带有 主题名称t。 设置为 "" 以禁用该功能。 挂载点字符串中可用的变量:

    • ${clientid}:clientid
    • ${username}:用户名
  • access_rules: [string()]

    • default: []

    配置监听器的访问控制规则。 见:https://github.com/emqtt/esockd#allowdeny

  • dtls_options: gateway:dtls_opts

    DTLS Socket 配置

# gateway:dtls_opts

Settings for the DTLS protocol.

Config paths

  • gateway.coap.listeners.dtls.$name.dtls_options
  • gateway.exproto.listeners.dtls.$name.dtls_options
  • gateway.lwm2m.listeners.dtls.$name.dtls_options
  • gateway.mqttsn.listeners.dtls.$name.dtls_options

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__DTLS_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__DTLS_OPTIONS
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__DTLS_OPTIONS
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__DTLS_OPTIONS

Fields

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [dtlsv1.2, dtlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    用于查找预共享密钥(PSK)标识的 EMQX 内部回调。

  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • dhfile: string()

    如果协商使用Diffie-Hellman密钥交换的密码套件,则服务器将使用包含PEM编码的Diffie-Hellman参数的文件的路径。如果未指定,则使用默认参数

    注意:TLS 1.3不支持dhfile选项。

  • fail_if_no_peer_cert: boolean()

    • default: false

    TLS/DTLS 服务器与 {verify,verify_peer} 一起使用。 如果设置为true,则如果客户端没有要发送的证书,即发送空证书,服务器将失败。 如果设置为false,则仅当客户端发送无效证书(空证书被视为有效证书)时才会失败。

  • honor_cipher_order: boolean()

    • default: true

    一个重要的安全设置,它强制根据服务器指定的顺序而不是客户机指定的顺序设置密码,从而强制服务器管理员执行(通常配置得更正确)安全顺序。

  • client_renegotiation: boolean()

    • default: true

    在支持客户机发起的重新协商的协议中,这种操作的资源成本对于服务器来说高于客户机。 这可能会成为拒绝服务攻击的载体。 SSL 应用程序已经采取措施来反击此类尝试,但通过将此选项设置为 false,可以严格禁用客户端发起的重新协商。 默认值为 true。请注意,由于基础密码套件可以加密的消息数量有限,禁用重新协商可能会导致长期连接变得不可用。

# gateway:exproto

Settings for EMQX extension protocol (exproto).

Config paths

  • gateway.exproto

Env overrides

  • EMQX_GATEWAY__EXPROTO

Fields

# gateway:exproto_grpc_handler

Settings for the exproto gRPC connection handler.

Config paths

  • gateway.exproto.handler

Env overrides

  • EMQX_GATEWAY__EXPROTO__HANDLER

Fields

  • address: binary()

    对端 gRPC 服务器地址。

  • ssl_options: broker:ssl_client_opts

    gRPC 客户端的 SSL 配置。

# gateway:exproto_grpc_server

Settings for the exproto gRPC server.

Config paths

  • gateway.exproto.server

Env overrides

  • EMQX_GATEWAY__EXPROTO__SERVER

Fields

  • bind: emqx_gateway_schema:ip_port() | integer()

    服务监听地址和端口。

  • ssl_options: gateway:ssl_server_opts

    服务 SSL 配置。

# gateway

EMQX Gateway configuration root.

Config paths

  • gateway

Env overrides

  • EMQX_GATEWAY

Fields

  • stomp: gateway:stomp

    Stomp 网关配置。当前实现支持 v1.2/1.1/1.0 协议版本

  • mqttsn: gateway:mqttsn

    MQTT-SN 网关配置。当前实现仅支持 v1.2 版本

  • coap: gateway:coap

    CoAP 网关配置。 该网关的实现基于 RFC-7252 和 https://core-wg.github.io/coap-pubsub/draft-ietf-core-pubsub.html

  • lwm2m: gateway:lwm2m

    LwM2M 网关配置。仅支持 v1.0.1 协议

  • exproto: gateway:exproto

    ExProto 网关

# gateway:lwm2m

The LwM2M protocol gateway.

Config paths

  • gateway.lwm2m

Env overrides

  • EMQX_GATEWAY__LWM2M

Fields

  • xml_dir: binary()

    • default: "etc/lwm2m_xml"

    LwM2M Resource 定义的 XML 文件目录路径

  • lifetime_min: emqx_gateway_schema:duration()

    • default: "15s"

    允许 LwM2M 客户端允许设置的心跳最小值

  • lifetime_max: emqx_gateway_schema:duration()

    • default: "86400s"

    允许 LwM2M 客户端允许设置的心跳最大值

  • qmode_time_window: emqx_gateway_schema:duration_s()

    • default: "22s"

    在QMode模式下,LwM2M网关认为网络链接有效的时间窗口的值。 例如,在收到客户端的更新信息后,在这个时间窗口内的任何信息都会直接发送到LwM2M客户端,而超过这个时间窗口的所有信息都会暂时储存在内存中

  • auto_observe: boolean()

    • default: false

    自动 Observe REGISTER 数据包的 Object 列表

  • update_msg_publish_condition: always | contains_object_list

    • default: contains_object_list

    发布UPDATE事件消息的策略。

    • always: 只要收到 UPDATE 请求,就发送更新事件。
    • contains_object_list: 仅当 UPDATE 请求携带 Object 列表时才发送更新事件
  • translators: gateway:lwm2m_translators

    LwM2M 网关订阅/发布消息的主题映射配置

  • mountpoint: binary()

    • default: "lwm2m/${endpoint_name}/"
  • listeners: gateway:udp_listeners

    配置 UDP 类型的监听器

  • enable: boolean()

    • default: true

    是否启用该网关

  • enable_stats: boolean()

    • default: true

    是否开启客户端统计

  • idle_timeout: emqx_gateway_schema:duration()

    • default: "30s"

    客户端连接过程的空闲时间。该配置用于:

    1. 一个新创建的客户端进程如果在该时间间隔内没有收到任何客户端请求,将被直接关闭。
    2. 一个正在运行的客户进程如果在这段时间后没有收到任何客户请求,将进入休眠状态以节省资源。
  • clientinfo_override: gateway:clientinfo_override

    ClientInfo 重写。

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    网关的认证器配置,对该网关下所以的监听器生效。如果每个监听器需要配置不同的认证器,需要配置监听器下的 authentication 字段

# gateway:lwm2m_translators

MQTT topics that correspond to LwM2M events.

Config paths

  • gateway.lwm2m.translators

Env overrides

  • EMQX_GATEWAY__LWM2M__TRANSLATORS

Fields

  • command: gateway:translator

    下行命令主题。 对于每个成功上线的新 LwM2M 客户端,网关会创建一个订阅关系来接收下行消息并将其发送给客户端

  • response: gateway:translator

    用于网关发布来自 LwM2M 客户端的确认事件的主题

  • notify: gateway:translator

    用于发布来自 LwM2M 客户端的通知事件的主题。 在成功 Observe 到 LwM2M 客户端的资源后,如果客户端报告任何资源状态的变化,网关将通过该主题发送通知事件

  • register: gateway:translator

    用于发布来自 LwM2M 客户端的注册事件的主题

  • update: gateway:translator

    用于发布来自LwM2M客户端的更新事件的主题

# gateway:mqttsn

The MQTT-SN (MQTT for Sensor Networks) protocol gateway.

Config paths

  • gateway.mqttsn

Env overrides

  • EMQX_GATEWAY__MQTTSN

Fields

# gateway:mqttsn_predefined

The pre-defined topic name corresponding to the pre-defined topic ID of N.

Note: the pre-defined topic ID of 0 is reserved.

Config paths

  • gateway.mqttsn.predefined.$INDEX

Env overrides

  • EMQX_GATEWAY__MQTTSN__PREDEFINED__$INDEX

Fields

  • id: integer()

    主题 ID。范围:1-65535

  • topic: binary()

    主题名称。注:不支持通配符

# gateway:ssl_listener

Settings for the SSL listener.

Config paths

  • gateway.exproto.listeners.ssl.$name
  • gateway.stomp.listeners.ssl.$name

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME

Fields

  • acceptors: integer()

    • default: 16

    Acceptor 进程池大小。

  • tcp_options: broker:tcp_opts

    TCP Socket 配置

  • proxy_protocol: boolean()

    • default: false

    是否开启 Proxy Protocol V1/2。当 EMQX 集群部署在 HAProxy 或 Nginx 后需要获取客户端真实 IP 时常用到该选项。参考:https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_gateway_schema:duration()

    • default: "15s"

    接收 Proxy Protocol 报文头的超时时间。如果在超时内没有收到 Proxy Protocol 包,EMQX 将关闭 TCP 连接。

  • enable: boolean()

    • default: true

    是否启用该监听器。

  • bind: emqx_gateway_schema:ip_port() | integer()

    监听器绑定的 IP 地址或端口。

  • max_connections: integer()

    • default: 1024

    监听器支持的最大连接数。

  • max_conn_rate: integer()

    • default: 1000

    监听器支持的最大连接速率。

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    网关的认证器配置,对该网关下所以的监听器生效。如果每个监听器需要配置不同的认证器,需要配置监听器下的 authentication 字段

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • mountpoint: binary()

    发布或订阅时,在所有主题前增加前缀字符串。 当消息投递给订阅者时,前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。 例如,如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t,则客户端实际上订阅了 some_tenant/t 主题。 类似地,如果另一个客户端 B(连接到与客户端 A 相同的侦听器)向主题 t 发送消息,则该消息被路由到所有订阅了 some_tenant/t 的客户端,因此客户端 A 将收到该消息,带有 主题名称t。 设置为 "" 以禁用该功能。 挂载点字符串中可用的变量:

    • ${clientid}:clientid
    • ${username}:用户名
  • access_rules: [string()]

    • default: []

    配置监听器的访问控制规则。 见:https://github.com/emqtt/esockd#allowdeny

  • ssl_options: broker:listener_ssl_opts

    SSL Socket 配置

# gateway:ssl_server_opts

SSL configuration for the server.

Config paths

  • gateway.exproto.server.ssl_options

Env overrides

  • EMQX_GATEWAY__EXPROTO__SERVER__SSL_OPTIONS

Fields

  • cacertfile: binary()

    受信任的PEM格式CA证书捆绑文件
    此文件中的证书用于验证TLS对等方的证书。 如果要信任新CA,请将新证书附加到文件中。 无需重启EMQX即可加载更新的文件,因为系统会定期检查文件是否已更新(并重新加载)
    注意:从文件中失效(删除)证书不会影响已建立的连接。

  • certfile: binary()

    PEM格式证书链文件
    此文件中的证书应与证书颁发链的顺序相反。也就是说,主机的证书应该放在文件的开头,然后是直接颁发者证书,依此类推。 虽然根CA证书是可选的,但它应该放在 如果要添加文件,请将其删除。

  • keyfile: binary()

    PEM格式的私钥文件。

  • verify: verify_peer | verify_none

    • default: verify_none

    启用或禁用对等验证。

  • reuse_sessions: boolean()

    • default: true

    启用 TLS 会话重用。

  • depth: integer()

    • default: 10

    在有效的证书路径中,可以跟随对等证书的非自颁发中间证书的最大数量。因此,如果深度为0,则对等方必须由受信任的根CA直接签名;如果1,路径可以是PEER、CA、ROOT-CA;如果是2,则路径可以是PEER、CA、CA、ROOT-CA等等。默认值为10。

  • password: string()

    包含用户密码的字符串。 仅在私钥文件受密码保护时使用。

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    支持所有TLS/DTLS版本

    注:PSK 的 Ciphers 无法在 tlsv1.3 中使用,如果打算使用 PSK 密码套件,请确保这里配置为 ["tlsv1.2","tlsv1.1"]

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "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", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    此配置保存由逗号分隔的 TLS 密码套件名称,或作为字符串数组。例如 "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256"["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
    密码(及其顺序)定义了客户端和服务器通过网络连接加密信息的方式。 选择一个好的密码套件对于应用程序的数据安全性、机密性和性能至关重要。

    名称应为 OpenSSL 字符串格式(而不是 RFC 格式)。 EMQX 配置文档提供的所有默认值和示例都是 OpenSSL 格式
    注意:某些密码套件仅与特定的 TLS 版本兼容('tlsv1.1'、'tlsv1.2'或'tlsv1.3')。 不兼容的密码套件将被自动删除。

    例如,如果只有 versions 仅配置为 tlsv1.3。为其他版本配置密码套件将无效。


    注:PSK 的 Ciphers 不支持 tlsv1.3
    如果打算使用PSK密码套件 tlsv1.3。应在ssl.versions中禁用。
    PSK 密码套件: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"
  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    用于查找预共享密钥(PSK)标识的 EMQX 内部回调。

  • secure_renegotiate: boolean()

    • default: true

    SSL 参数重新协商是一种允许客户端和服务器动态重新协商 SSL 连接参数的功能。 RFC 5746 定义了一种更安全的方法。通过启用安全的重新协商,您就失去了对不安全的重新协商的支持,从而容易受到 MitM 攻击。

  • dhfile: string()

    如果协商使用Diffie-Hellman密钥交换的密码套件,则服务器将使用包含PEM编码的Diffie-Hellman参数的文件的路径。如果未指定,则使用默认参数

    注意:TLS 1.3不支持dhfile选项。

  • fail_if_no_peer_cert: boolean()

    • default: false

    TLS/DTLS 服务器与 {verify,verify_peer} 一起使用。 如果设置为true,则如果客户端没有要发送的证书,即发送空证书,服务器将失败。 如果设置为false,则仅当客户端发送无效证书(空证书被视为有效证书)时才会失败。

  • honor_cipher_order: boolean()

    • default: true

    一个重要的安全设置,它强制根据服务器指定的顺序而不是客户机指定的顺序设置密码,从而强制服务器管理员执行(通常配置得更正确)安全顺序。

  • client_renegotiation: boolean()

    • default: true

    在支持客户机发起的重新协商的协议中,这种操作的资源成本对于服务器来说高于客户机。 这可能会成为拒绝服务攻击的载体。 SSL 应用程序已经采取措施来反击此类尝试,但通过将此选项设置为 false,可以严格禁用客户端发起的重新协商。 默认值为 true。请注意,由于基础密码套件可以加密的消息数量有限,禁用重新协商可能会导致长期连接变得不可用。

  • handshake_timeout: emqx_schema:duration()

    • default: "15s"

    握手完成所允许的最长时间

# gateway:stomp

The STOMP protocol gateway provides EMQX with the ability to access STOMP (Simple (or Streaming) Text Orientated Messaging Protocol) protocol.

Config paths

  • gateway.stomp

Env overrides

  • EMQX_GATEWAY__STOMP

Fields

# gateway:stomp_frame

Size limits for the STOMP frames.

Config paths

  • gateway.stomp.frame

Env overrides

  • EMQX_GATEWAY__STOMP__FRAME

Fields

  • max_headers: non_neg_integer()

    • default: 10

    允许的 Header 最大数量

  • max_headers_length: non_neg_integer()

    • default: 1024

    允许的 Header 字符串的最大长度

  • max_body_length: integer()

    • default: 65536

    允许的 Stomp 报文 Body 的最大字节数

# gateway:tcp_listener

Settings for the TCP listener.

Config paths

  • gateway.exproto.listeners.tcp.$name
  • gateway.stomp.listeners.tcp.$name

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME

Fields

  • acceptors: integer()

    • default: 16

    Acceptor 进程池大小。

  • tcp_options: broker:tcp_opts

    TCP Socket 配置

  • proxy_protocol: boolean()

    • default: false

    是否开启 Proxy Protocol V1/2。当 EMQX 集群部署在 HAProxy 或 Nginx 后需要获取客户端真实 IP 时常用到该选项。参考:https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_gateway_schema:duration()

    • default: "15s"

    接收 Proxy Protocol 报文头的超时时间。如果在超时内没有收到 Proxy Protocol 包,EMQX 将关闭 TCP 连接。

  • enable: boolean()

    • default: true

    是否启用该监听器。

  • bind: emqx_gateway_schema:ip_port() | integer()

    监听器绑定的 IP 地址或端口。

  • max_connections: integer()

    • default: 1024

    监听器支持的最大连接数。

  • max_conn_rate: integer()

    • default: 1000

    监听器支持的最大连接速率。

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    网关的认证器配置,对该网关下所以的监听器生效。如果每个监听器需要配置不同的认证器,需要配置监听器下的 authentication 字段

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • mountpoint: binary()

    发布或订阅时,在所有主题前增加前缀字符串。 当消息投递给订阅者时,前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。 例如,如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t,则客户端实际上订阅了 some_tenant/t 主题。 类似地,如果另一个客户端 B(连接到与客户端 A 相同的侦听器)向主题 t 发送消息,则该消息被路由到所有订阅了 some_tenant/t 的客户端,因此客户端 A 将收到该消息,带有 主题名称t。 设置为 "" 以禁用该功能。 挂载点字符串中可用的变量:

    • ${clientid}:clientid
    • ${username}:用户名
  • access_rules: [string()]

    • default: []

    配置监听器的访问控制规则。 见:https://github.com/emqtt/esockd#allowdeny

# gateway:tcp_listeners

Settings for the TCP listeners.

Config paths

  • gateway.stomp.listeners

Env overrides

  • EMQX_GATEWAY__STOMP__LISTENERS

Fields

# gateway:tcp_udp_listeners

Settings for the listeners.

Config paths

  • gateway.exproto.listeners

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS

Fields

# gateway:translator

MQTT topic that corresponds to a particular type of event.

Config paths

  • gateway.lwm2m.translators.command
  • gateway.lwm2m.translators.notify
  • gateway.lwm2m.translators.register
  • gateway.lwm2m.translators.response
  • gateway.lwm2m.translators.update

Env overrides

  • EMQX_GATEWAY__LWM2M__TRANSLATORS__COMMAND
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__NOTIFY
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__REGISTER
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__RESPONSE
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__UPDATE

Fields

  • topic: binary()

    主题名称

  • qos: qos()

    • default: 0

    QoS 等级

# gateway:udp_listener

Settings for the UDP listener.

Config paths

  • gateway.coap.listeners.udp.$name
  • gateway.exproto.listeners.udp.$name
  • gateway.lwm2m.listeners.udp.$name
  • gateway.mqttsn.listeners.udp.$name

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME

Fields

  • udp_options: gateway:udp_opts

  • enable: boolean()

    • default: true

    是否启用该监听器。

  • bind: emqx_gateway_schema:ip_port() | integer()

    监听器绑定的 IP 地址或端口。

  • max_connections: integer()

    • default: 1024

    监听器支持的最大连接数。

  • max_conn_rate: integer()

    • default: 1000

    监听器支持的最大连接速率。

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    网关的认证器配置,对该网关下所以的监听器生效。如果每个监听器需要配置不同的认证器,需要配置监听器下的 authentication 字段

  • enable_authn: boolean()

    • default: true

    配置 true (默认值)启用客户端进行身份认证。 配置 false 时,将不对客户端做任何认证。

  • mountpoint: binary()

    发布或订阅时,在所有主题前增加前缀字符串。 当消息投递给订阅者时,前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。 例如,如果客户端 A 在 listeners.tcp.\<name>.mountpoint 设置为 some_tenant 的情况下订阅 t,则客户端实际上订阅了 some_tenant/t 主题。 类似地,如果另一个客户端 B(连接到与客户端 A 相同的侦听器)向主题 t 发送消息,则该消息被路由到所有订阅了 some_tenant/t 的客户端,因此客户端 A 将收到该消息,带有 主题名称t。 设置为 "" 以禁用该功能。 挂载点字符串中可用的变量:

    • ${clientid}:clientid
    • ${username}:用户名
  • access_rules: [string()]

    • default: []

    配置监听器的访问控制规则。 见:https://github.com/emqtt/esockd#allowdeny

# gateway:udp_listeners

Settings for the UDP listeners.

Config paths

  • gateway.coap.listeners
  • gateway.lwm2m.listeners
  • gateway.mqttsn.listeners

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS
  • EMQX_GATEWAY__LWM2M__LISTENERS
  • EMQX_GATEWAY__MQTTSN__LISTENERS

Fields

# gateway:udp_opts

Settings for the UDP sockets.

Config paths

  • gateway.coap.listeners.dtls.$name.udp_options
  • gateway.coap.listeners.udp.$name.udp_options
  • gateway.exproto.listeners.dtls.$name.udp_options
  • gateway.exproto.listeners.udp.$name.udp_options
  • gateway.lwm2m.listeners.dtls.$name.udp_options
  • gateway.lwm2m.listeners.udp.$name.udp_options
  • gateway.mqttsn.listeners.dtls.$name.udp_options
  • gateway.mqttsn.listeners.udp.$name.udp_options

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__UDP_OPTIONS

Fields

  • active_n: integer()

    • default: 100

    为 Socket 指定 {active, N} 选项。 参见:https://erlang.org/doc/man/inet.html#setopts-2

  • recbuf: emqx_gateway_schema:bytesize()

    Socket 在内核空间接收缓冲区的大小。

  • sndbuf: emqx_gateway_schema:bytesize()

    Socket 在内核空间发送缓冲区的大小。

  • buffer: emqx_gateway_schema:bytesize()

    Socket 在用户空间的缓冲区大小。

  • reuseaddr: boolean()

    • default: true

    允许重用本地处于 TIME_WAIT 的端口号

# limiter:bucket_opts

Settings for the bucket.

Config paths

  • limiter.batch.bucket.$bucket_name
  • limiter.bytes_in.bucket.$bucket_name
  • limiter.connection.bucket.$bucket_name
  • limiter.message_in.bucket.$bucket_name
  • limiter.message_routing.bucket.$bucket_name

Env overrides

  • EMQX_LIMITER__BATCH__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__BYTES_IN__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__CONNECTION__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__MESSAGE_IN__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__MESSAGE_ROUTING__BUCKET__$BUCKET_NAME

Fields

  • rate: emqx_limiter_schema:rate()

    • default: "infinity"

    桶的令牌生成速率

  • capacity: emqx_limiter_schema:capacity()

    • default: "infinity"

    该令牌桶的容量

  • initial: emqx_limiter_schema:initial()

    • default: "0"

    桶中的初始令牌数

  • per_client: limiter:client_bucket

    • default: {}

    对桶的每个使用者的速率控制设置,这个不是必须的

# limiter:client_bucket

Settings for the client bucket.

Config paths

  • limiter.batch.bucket.$bucket_name.per_client
  • limiter.bytes_in.bucket.$bucket_name.per_client
  • limiter.connection.bucket.$bucket_name.per_client
  • limiter.message_in.bucket.$bucket_name.per_client
  • limiter.message_routing.bucket.$bucket_name.per_client

Env overrides

  • EMQX_LIMITER__BATCH__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__BYTES_IN__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__CONNECTION__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__MESSAGE_IN__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__MESSAGE_ROUTING__BUCKET__$BUCKET_NAME__PER_CLIENT

Fields

  • rate: emqx_limiter_schema:rate()

    • default: "infinity"

    桶的令牌生成速率

  • initial: emqx_limiter_schema:initial()

    • default: "0"

    桶中的初始令牌数

  • low_watermark: emqx_limiter_schema:initial()

    • default: "0"

    当桶中剩余的令牌数低于这个值,即使令牌申请成功了,也会被强制暂停一会儿

  • capacity: emqx_limiter_schema:capacity()

    • default: "infinity"

    每个使用者的令牌容量上限

  • divisible: boolean()

    • default: false

    申请的令牌数是否可以被分割

  • max_retry_time: emqx_schema:duration()

    • default: "10s"

    申请失败后,尝试重新申请的时长最大值

  • failure_strategy: emqx_limiter_schema:failure_strategy()

    • default: force

    当所有的重试都失败后的处理策略

# limiter

Settings for the rate limiter.

Config paths

  • limiter

Env overrides

  • EMQX_LIMITER

Fields

  • bytes_in: limiter:limiter_opts

    • default: {}

    流入字节率控制器. 这个是用来控制当前节点上的数据流入的字节率,每条消息将会消耗和其二进制大小等量的令牌,当达到最大速率后,会话将会被限速甚至被强制挂起一小段时间

  • message_in: limiter:limiter_opts

    • default: {}

    流入速率控制器。 这个用来控制当前节点上的消息流入速率,当达到最大速率后,会话将会被限速甚至被强制挂起一小段时间

  • connection: limiter:limiter_opts

    • default:
    {
      bucket {
        default {capacity = 1000, rate = "1000/s"}
      }
      rate = "1000/s"
    }
    
    1
    2
    3
    4
    5
    6

    连接速率控制器。 这个用来控制当前节点上的连接速率,当达到最大速率后,新的连接将会被拒绝

  • message_routing: limiter:limiter_opts

    • default: {}

    消息派发速率控制器。 这个用来控制当前节点内的消息派发速率,当达到最大速率后,新的推送将会被拒绝

  • batch: limiter:limiter_opts

    • default: {}

    批量操作速率控制器。 这是给 EMQX 内部的批量操作使用的,比如用来控制保留消息的派发速率

# limiter:limiter_opts

Settings for the limiter.

Config paths

  • limiter.batch
  • limiter.bytes_in
  • limiter.connection
  • limiter.message_in
  • limiter.message_routing

Env overrides

  • EMQX_LIMITER__BATCH
  • EMQX_LIMITER__BYTES_IN
  • EMQX_LIMITER__CONNECTION
  • EMQX_LIMITER__MESSAGE_IN
  • EMQX_LIMITER__MESSAGE_ROUTING

Fields

  • rate: emqx_limiter_schema:rate()

    • default: "infinity"

    桶的令牌生成速率

  • burst: emqx_limiter_schema:burst_rate()

    • default: 0

    突发速率。 突发速率允许短时间内速率超过设置的速率值,突发速率 + 速率 = 当前桶能达到的最大速率值

  • bucket: {$bucket_name -> limiter:bucket_opts}

    • default:
    {
      default {}
    }
    
    1
    2
    3

    桶的配置

# modules:delayed

Settings for the delayed module.

Config paths

  • delayed

Env overrides

  • EMQX_DELAYED

Fields

  • enable: boolean()

    • default: true

    是否开启该功能

  • max_delayed_messages: integer()

    • default: 0

    延迟消息的数量上限(0 代表无限)

# modules:rewrite

EMQX 的主题重写功能支持根据用户配置的规则在客户端订阅主题、发布消息、取消订阅的时候将 A 主题重写为 B 主题。 重写规则分为 Pub 规则和 Sub 规则,Pub 规则匹配 PUSHLISH 报文携带的主题,Sub 规则匹配 SUBSCRIBE、UNSUBSCRIBE 报文携带的主题。 每条重写规则都由主题过滤器、正则表达式、目标表达式三部分组成。 在主题重写功能开启的前提下,EMQX 在收到诸如 PUBLISH 报文等带有主题的 MQTT 报文时,将使用报文中的主题去依次匹配配置文件中规则的主题过滤器部分,一旦成功匹配,则使用正则表达式提取主题中的信息,然后替换至目标表达式以构成新的主题。 目标表达式中可以使用 $N 这种格式的变量匹配正则表达中提取出来的元素,$N 的值为正则表达式中提取出来的第 N 个元素,比如 $1 即为正则表达式提取的第一个元素。 需要注意的是,EMQX 使用倒序读取配置文件中的重写规则,当一条主题可以同时匹配多条主题重写规则的主题过滤器时,EMQX 仅会使用它匹配到的第一条规则进行重写,如果该条规则中的正则表达式与 MQTT 报文主题不匹配,则重写失败,不会再尝试使用其他的规则进行重写。 因此用户在使用时需要谨慎的设计 MQTT 报文主题以及主题重写规则。

Config paths

  • rewrite.$INDEX

Env overrides

  • EMQX_REWRITE__$INDEX

Fields

  • action: subscribe | publish | all

    主题重写在哪种操作上生效:

    • subscribe:订阅时重写主题;
    • publish:发布时重写主题; -all:全部重写主题
  • source_topic: binary()

    源主题,客户端业务指定的主题

  • dest_topic: binary()

    目标主题。

  • re: binary()

    正则表达式

# modules:telemetry

Settings for the telemetry module.

Config paths

  • telemetry

Env overrides

  • EMQX_TELEMETRY

Fields

  • enable: boolean()

    • default: true

    Enable telemetry.

# modules:topic_metrics

Config paths

  • topic_metrics.$INDEX

Env overrides

  • EMQX_TOPIC_METRICS__$INDEX

Fields

  • topic: binary()

    Collect metrics for the topic.

# rule_engine:builtin_action_console

配置打印到控制台

Config paths

  • rule_engine.rules.$id.actions.$INDEX

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX

Fields

  • function: console

    将输出打印到控制台

# rule_engine:builtin_action_republish

配置重新发布。

Config paths

  • rule_engine.rules.$id.actions.$INDEX

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX

Fields

# rule_engine:republish_args

内置 'republish' 动作的参数。 可以在参数中使用变量。 变量是规则中选择的字段。 例如规则 SQL 定义如下:

SELECT clientid, qos, payload FROM "t/1"
1

然后有 3 个变量可用:clientidqospayload。 如果我们将参数设置为:

{
    topic = "t/${clientid}"
    qos = "${qos}"
    payload = "msg: ${payload}"
}
1
2
3
4
5

当收到一条 Payload 为 hello,QoS 为 1,Client ID 为 Steve 的消息时,将重新发布一条新的 MQTT 消息到主题 t/Steve,该消息的 Payload 为 msg: hello,QoS 为 1。

Config paths

  • rule_engine.rules.$id.actions.$INDEX.args

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX__ARGS

Fields

  • topic: binary()

    重新发布消息的目标主题。 允许使用带有变量的模板,请参阅“republish_args”的描述。

  • qos: qos() | binary()

    • default: "${qos}"

    要重新发布的消息的 qos。允许使用带有变量的模板,请参阅“republish_args”的描述。 默认为 ${qos}。 如果从规则的选择结果中没有找到变量 ${qos},则使用 0。

  • retain: boolean() | binary()

    • default: "${retain}"

    要重新发布的消息的“保留”标志。允许使用带有变量的模板,请参阅“republish_args”的描述。 默认为 ${retain}。 如果从所选结果中未找到变量 ${retain},则使用 false。

  • payload: binary()

    • default: "${payload}"

    要重新发布的消息的有效负载。允许使用带有变量的模板,请参阅“republish_args”的描述。。 默认为 ${payload}。 如果从所选结果中未找到变量 ${payload},则使用字符串 "undefined"。

# rule_engine

配置 EMQX 规则引擎。

Config paths

  • rule_engine

Env overrides

  • EMQX_RULE_ENGINE

Fields

  • ignore_sys_message: boolean()

    • default: true

    当设置为“true”(默认)时,规则引擎将忽略发布到 $SYS 主题的消息。

  • rules: {$id -> rule_engine:rules}

    • default: {}

    规则

  • jq_function_default_timeout: emqx_schema:duration_ms()

    • default: "10s"

    规则引擎内建函数 jq 默认时间限制

# rule_engine:rules

配置规则

Config paths

  • rule_engine.rules.$id

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID

Fields

  • name: binary()

    • default: ""

    规则名字

  • sql: binary()

    用于处理消息的 SQL 。 示例:SELECT * FROM "test/topic" WHERE payload.x = 1

  • actions: [binary() | rule_engine:builtin_action_republish | rule_engine:builtin_action_console | rule_engine:user_provided_function]

    • default: []

    规则的动作列表。 动作可以是指向 EMQX bridge 的引用,也可以是一个指向函数的对象。 我们支持一些内置函数,如“republish”和“console”,我们还支持用户提供的函数,它的格式为:“{module}:{function}”。 列表中的动作按顺序执行。这意味着如果其中一个动作执行缓慢,则以下所有动作都不会被执行直到它返回。 如果其中一个动作崩溃,在它之后的所有动作仍然会被按照原始顺序执行。 如果运行动作时出现任何错误,则会出现错误消息,并且相应的计数器会增加。

  • enable: boolean()

    • default: true

    启用或禁用规则引擎

  • description: binary()

    • default: ""

    规则的描述

# rule_engine:user_provided_function

配置用户函数

Config paths

  • rule_engine.rules.$id.actions.$INDEX

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX

Fields

  • function: binary()

    用户提供的函数。 格式应为:'{module}:{function}'。 其中 {module} 是 Erlang 回调模块, {function} 是 Erlang 函数。 要编写自己的函数,请检查源文件:apps/emqx_rule_engine/src/emqx_rule_actions.erl 中的示例函数 consolerepublish

  • args: map()

    • default: {}

    用户提供的参数将作为函数 module:function/3 的第三个参数, 请检查源文件:apps/emqx_rule_engine/src/emqx_rule_actions.erl 中的示例函数 consolerepublish

# egress

MQTT Bridge 配置

Config paths

  • bridges.mqtt.$name

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME

Fields

  • direction: egress

    • default: egress

    The direction of the bridge. Can be one of 'ingress' or 'egress'.
    The egress config defines how this bridge forwards messages from the local broker to the remote broker.
    Template with variables is allowed in 'remote_topic', 'qos', 'retain', 'payload'.
    NOTE: if this bridge is used as the action of a rule (emqx rule engine), and also local_topic is configured, then both the data got from the rule and the MQTT messages that matches local_topic will be forwarded.

  • enable: boolean()

    • default: true

    启用/禁用 Bridge

  • connector: binary() | connector-mqtt:connector

    Bridge 使用的 Connector 的 ID 或者配置。Connector ID 的格式必须为:{type}:{name}.
    在配置文件中,您可以通过以下路径找到 Connector 的相应配置条目:'connector.{type}.{name}'。

  • local_topic: binary()

    要转发到远程broker的本地主题

  • remote_topic: binary()

    转发到远程broker的哪个topic。
    允许使用带有变量的模板。

  • remote_qos: qos() | binary()

    待发送 MQTT 消息的 QoS。
    允许使用带有变量的模板。

  • retain: boolean() | binary()

    要发送的 MQTT 消息的“保留”标志。
    允许使用带有变量的模板。

  • payload: binary()

    要发送的 MQTT 消息的负载。
    允许使用带有变量的模板。

# ingress

MQTT Bridge 配置

Config paths

  • bridges.mqtt.$name

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME

Fields

  • direction: ingress

    • default: egress

    The direction of the bridge. Can be one of 'ingress' or 'egress'.
    The ingress config defines how this bridge receive messages from the remote MQTT broker, and then send them to the local broker.
    Template with variables is allowed in 'local_topic', 'remote_qos', 'qos', 'retain', 'payload'.
    NOTE: if this bridge is used as the input of a rule (emqx rule engine), and also local_topic is configured, then messages got from the remote broker will be sent to both the 'local_topic' and the rule.

  • enable: boolean()

    • default: true

    启用/禁用 Bridge

  • connector: binary() | connector-mqtt:connector

    Bridge 使用的 Connector 的 ID 或者配置。Connector ID 的格式必须为:{type}:{name}.
    在配置文件中,您可以通过以下路径找到 Connector 的相应配置条目:'connector.{type}.{name}'。

  • remote_topic: binary()

    从远程broker的哪个topic接收消息

  • remote_qos: qos() | binary()

    • default: 1

    订阅远程borker时要使用的 QoS 级别

  • local_topic: binary()

    向本地broker的哪个topic发送消息。
    允许使用带有变量的模板。

  • local_qos: qos() | binary()

    • default: "${qos}"

    待发送 MQTT 消息的 QoS。
    允许使用带有变量的模板。

  • retain: boolean() | binary()

    • default: "${retain}"

    要发送的 MQTT 消息的“保留”标志。
    允许使用带有变量的模板。

  • payload: binary()

    • default: "${payload}"

    要发送的 MQTT 消息的负载。
    允许使用带有变量的模板。

# cluster_dns

DNS SRV 记录服务发现。

Config paths

  • cluster.dns

Env overrides

  • EMQX_CLUSTER__DNS

Fields

  • name: string()

    • default: "localhost"

    指定 DNS A 记录的名字。emqx 会通过访问这个 DNS A 记录来获取 IP 地址列表。 当cluster.discovery_strategydns 时有效。

  • record_type: a | srv

    • default: a

    DNS 记录类型。

# cluster_etcd

使用 'etcd' 服务的服务发现。

Config paths

  • cluster.etcd

Env overrides

  • EMQX_CLUSTER__ETCD

Fields

  • server: emqx_schema:comma_separated_list()

    指定 etcd 服务的地址。如有多个服务使用逗号 , 分隔。 当 cluster.discovery_strategy 为 etcd 时,此配置项才有效。

  • prefix: string()

    • default: "emqxcl"

    指定 etcd 路径的前缀。每个节点在 etcd 中都会创建一个路径: v2/keys/<prefix>/<cluster.name>/<node.name>
    当 cluster.discovery_strategy 为 etcd 时,此配置项才有效。

  • node_ttl: emqx_schema:duration()

    • default: "1m"

    指定 etcd 中节点信息的过期时间。 当 cluster.discovery_strategy 为 etcd 时,此配置项才有效。

  • ssl: broker:ssl_client_opts

    当使用 TLS 连接 etcd 时的配置选项。 当 cluster.discovery_strategy 为 etcd 时,此配置项才有效。

# cluster_k8s

Kubernetes 服务发现。

Config paths

  • cluster.k8s

Env overrides

  • EMQX_CLUSTER__K8S

Fields

  • apiserver: string()

    • default: "http://10.110.111.204:8080"

    指定 Kubernetes API Server。如有多个 Server 使用逗号 , 分隔。 当 cluster.discovery_strategy 为 k8s 时,此配置项才有效。

  • service_name: string()

    • default: "emqx"

    指定 Kubernetes 中 EMQX 的服务名。 当 cluster.discovery_strategy 为 k8s 时,此配置项才有效。

  • address_type: ip | dns | hostname

    • default: ip

    当使用 k8s 方式集群时,address_type 用来从 Kubernetes 接口的应答里获取什么形式的 Host 列表。 指定 cluster.k8s.address_typeip,则将从 Kubernetes 接口中获取集群中其他节点 的IP地址。

  • namespace: string()

    • default: "default"

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

  • suffix: string()

    • default: "pod.local"

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

# cluster_mcast

UDP 组播服务发现。

Config paths

  • cluster.mcast

Env overrides

  • EMQX_CLUSTER__MCAST

Fields

  • addr: string()

    • default: "239.192.0.1"

    指定多播 IPv4 地址。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • ports: [integer()]

    • default: [4369,4370]

    指定多播端口。如有多个端口使用逗号 , 分隔。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • iface: string()

    • default: "0.0.0.0"

    指定节点发现服务需要绑定到本地 IP 地址。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • ttl: 0..255

    • default: 255

    指定多播的 Time-To-Live 值。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • loop: boolean()

    • default: true

    设置多播的报文是否投递到本地回环地址。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • sndbuf: emqx_schema:bytesize()

    • default: "16KB"

    外发数据报的内核级缓冲区的大小。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • recbuf: emqx_schema:bytesize()

    • default: "16KB"

    接收数据报的内核级缓冲区的大小。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

  • buffer: emqx_schema:bytesize()

    • default: "32KB"

    用户级缓冲区的大小。 当 cluster.discovery_strategy 为 mcast 时,此配置项才有效。

# cluster_static

静态节点服务发现。新节点通过连接一个节点来加入集群。

Config paths

  • cluster.static

Env overrides

  • EMQX_CLUSTER__STATIC

Fields

  • seeds: [atom()]

    • default: []

    集群中的EMQX节点名称列表, 指定固定的节点列表,多个节点间使用逗号 , 分隔。 当 cluster.discovery_strategy 为 static 时,此配置项才有效。 适合于节点数量较少且固定的集群。

# authorization

授权相关

Config paths

  • authorization

Env overrides

  • EMQX_AUTHORIZATION

Fields

  • no_match: allow | deny

    • default: allow

    如果用户或客户端不匹配ACL规则,或者从可配置授权源(比如内置数据库、HTTP API 或 PostgreSQL 等。)内未找 到此类用户或客户端时,模式的认访问控制操作。 在“授权”中查找更多详细信息。

  • deny_action: ignore | disconnect

    • default: ignore

    授权检查拒绝操作时的操作。

  • cache: broker:cache

  • sources: [authz:file | authz:http_get | authz:http_post | authz:mnesia | authz:mongo_single | authz:mongo_rs | authz:mongo_sharded | authz:mysql | authz:postgresql | authz:redis_single | authz:redis_sentinel | authz:redis_cluster]

    • default: []

    授权数据源。
    授权(ACL)数据源的列表。 它被设计为一个数组,而不是一个散列映射, 所以可以作为链式访问控制。

    当授权一个 'publish' 或 'subscribe' 行为时, 该配置列表中的所有数据源将按顺序进行检查。 如果在某个客户端未找到时(使用 ClientID 或 Username), 将会移动到下一个数据源。直至得到 'allow' 或 'deny' 的结果。

    如果在任何数据源中都未找到对应的客户端信息, 配置的默认行为 ('authorization.no_match') 将生效。

    注意: 数据源使用 'type' 进行标识。 使用同一类型的数据源多于一次不被允许。

# cluster

EMQX 节点可以组成一个集群,以提高总容量。
这里指定了节点之间如何连接。

Config paths

  • cluster

Env overrides

  • EMQX_CLUSTER

Fields

  • name: atom()

    • default: emqxcl
    • mapping: ekka.cluster_name

    EMQX集群名称。每个集群都有一个唯一的名称。服务发现时会用于做路径的一部分。

  • discovery_strategy: manual | static | mcast | dns | etcd | k8s

    • default: manual

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

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

    • default: []
    • mapping: mria.core_nodes

    当前节点连接的核心节点列表。
    注意:该参数仅在设置backend时生效到 rlog 并且设置rolereplicant时生效。
    该值需要在手动或静态集群发现机制下设置。
    如果使用了自动集群发现机制(如etcd),则不需要设置该值。

  • autoclean: emqx_schema:duration()

    • default: "5m"
    • mapping: ekka.cluster_autoclean

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

  • autoheal: boolean()

    • default: true
    • mapping: ekka.cluster_autoheal

    集群脑裂自动恢复机制开关。

  • proto_dist: inet_tcp | inet6_tcp | inet_tls

    • default: inet_tcp
    • mapping: ekka.proto_dist

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

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

  • mcast: cluster_mcast

  • dns: cluster_dns

  • etcd: cluster_etcd

  • k8s: cluster_k8s

# cluster_call

集群调用功能的选项。

Config paths

  • node.cluster_call

Env overrides

  • EMQX_NODE__CLUSTER_CALL

Fields

  • retry_interval: emqx_schema:duration()

    • default: "1m"

    当集群间调用出错时,多长时间重试一次。

  • max_history: 1..500

    • default: 100

    集群间调用最多保留的历史记录数。只用于排错时查看。

  • cleanup_interval: emqx_schema:duration()

    • default: "5m"

    清理过期事务的时间间隔

# console_handler

日志处理进程将日志事件打印到 EMQX 控制台。

Config paths

  • log.console_handler

Env overrides

  • EMQX_LOG__CONSOLE_HANDLER

Fields

  • enable: boolean()

    • default: false

    启用此日志处理进程。

  • level: emqx_conf_schema:log_level()

    • default: warning

    当前日志处理进程的日志级别。 默认为 warning 级别。

  • time_offset: string()

    • default: "system"

    日志中的时间戳使用的时间偏移量。 可选值为:

    • system: 本地系统使用的时区偏移量
    • utc: 0 时区的偏移量
    • +-[hh]:[mm]: 自定义偏移量,比如 "-02:00" 或者 "+00:00" 默认值为本地系统的时区偏移量:system
  • chars_limit: unlimited | 100..inf

    • default: unlimited

    设置单个日志消息的最大长度。 如果超过此长度,则日志消息将被截断。最小可设置的长度为100。

  • formatter: text | json

    • default: text

    选择日志格式类型。 text 用于纯文本,json 用于结构化日志记录。

  • single_line: boolean()

    • default: true

    如果设置为 true,则单行打印日志。 否则,日志消息可能跨越多行。

  • sync_mode_qlen: non_neg_integer()

    • default: 100

    只要缓冲的日志事件的数量低于这个值,所有的日志事件都会被异步处理。 这意味着,日志落地速度不会影响正常的业务进程,因为它们不需要等待日志处理进程的响应。 如果消息队列的增长超过了这个值,处理程序开始同步处理日志事件。也就是说,发送事件的客户进程必须等待响应。 当处理程序将消息队列减少到低于sync_mode_qlen阈值的水平时,异步操作就会恢复。 默认为100条信息,当等待的日志事件大于100条时,就开始同步处理日志。

  • drop_mode_qlen: pos_integer()

    • default: 3000

    当缓冲的日志事件数大于此值时,新的日志事件将被丢弃。起到过载保护的功能。 为了使过载保护算法正常工作必须要:sync_mode_qlen =< drop_mode_qlen =< flush_qlen 且 drop_mode_qlen > 1 要禁用某些模式,请执行以下操作。

    • 如果sync_mode_qlen被设置为0,所有的日志事件都被同步处理。也就是说,异步日志被禁用。
    • 如果sync_mode_qlen被设置为与drop_mode_qlen相同的值,同步模式被禁用。也就是说,处理程序总是以异步模式运行,除非调用drop或flushing。
    • 如果drop_mode_qlen被设置为与flush_qlen相同的值,则drop模式被禁用,永远不会发生。
  • flush_qlen: pos_integer()

    • default: 8000

    如果缓冲日志事件的数量增长大于此阈值,则会发生冲刷(删除)操作。 日志处理进程会丢弃缓冲的日志消息。 来缓解自身不会由于内存瀑涨而影响其它业务进程。日志内容会提醒有多少事件被删除。

  • overload_kill: log_overload_kill

  • burst_limit: log_burst_limit

  • supervisor_reports: error | progress

    • default: error

    Supervisor 报告的类型。默认为 error 类型。

    • error:仅记录 Erlang 进程中的错误。
    • progress:除了 error 信息外,还需要记录进程启动的详细信息。
  • max_depth: unlimited | non_neg_integer()

    • default: 100

    Erlang 内部格式日志格式化和 Erlang 进程消息队列检查的最大深度。

# log

EMQX 日志记录支持日志事件的多个接收器。 每个接收器由一个_log handler_表示,可以独立配置。

Config paths

  • log

Env overrides

  • EMQX_LOG

Fields

# log_burst_limit

短时间内产生的大量日志事件可能会导致问题,例如:

  • 日志文件变得非常大
  • 日志文件轮换过快,有用信息被覆盖
  • 对系统的整体性能影响

日志突发限制功能可以暂时禁用日志记录以避免这些问题。

Config paths

  • log.console_handler.burst_limit
  • log.file_handlers.$name.burst_limit

Env overrides

  • EMQX_LOG__CONSOLE_HANDLER__BURST_LIMIT
  • EMQX_LOG__FILE_HANDLERS__$NAME__BURST_LIMIT

Fields

  • enable: boolean()

    • default: true

    启用日志限流保护机制。

  • max_count: pos_integer()

    • default: 10000

    window_time 间隔内处理的最大日志事件数。 达到限制后,将丢弃连续事件,直到 window_time 结束。

  • window_time: emqx_schema:duration()

    • default: "1s"

    参考 max_count

# log_file_handler

日志处理进程将日志事件打印到文件。

Config paths

  • log.file_handlers.$name

Env overrides

  • EMQX_LOG__FILE_HANDLERS__$NAME

Fields

  • file: emqx_conf_schema:file()

    日志文件路径及名字。

  • rotation: log_rotation

  • max_size: infinity | emqx_schema:bytesize()

    • default: "50MB"

    此参数控制日志文件轮换。 infinity 意味着日志文件将无限增长,否则日志文件将在达到 max_size(以字节为单位)时进行轮换。 与 rotation count配合使用。如果 counter 为 10,则是10个文件轮换。

  • enable: boolean()

    • default: true

    启用此日志处理进程。

  • level: emqx_conf_schema:log_level()

    • default: warning

    当前日志处理进程的日志级别。 默认为 warning 级别。

  • time_offset: string()

    • default: "system"

    日志中的时间戳使用的时间偏移量。 可选值为:

    • system: 本地系统使用的时区偏移量
    • utc: 0 时区的偏移量
    • +-[hh]:[mm]: 自定义偏移量,比如 "-02:00" 或者 "+00:00" 默认值为本地系统的时区偏移量:system
  • chars_limit: unlimited | 100..inf

    • default: unlimited

    设置单个日志消息的最大长度。 如果超过此长度,则日志消息将被截断。最小可设置的长度为100。

  • formatter: text | json

    • default: text

    选择日志格式类型。 text 用于纯文本,json 用于结构化日志记录。

  • single_line: boolean()

    • default: true

    如果设置为 true,则单行打印日志。 否则,日志消息可能跨越多行。

  • sync_mode_qlen: non_neg_integer()

    • default: 100

    只要缓冲的日志事件的数量低于这个值,所有的日志事件都会被异步处理。 这意味着,日志落地速度不会影响正常的业务进程,因为它们不需要等待日志处理进程的响应。 如果消息队列的增长超过了这个值,处理程序开始同步处理日志事件。也就是说,发送事件的客户进程必须等待响应。 当处理程序将消息队列减少到低于sync_mode_qlen阈值的水平时,异步操作就会恢复。 默认为100条信息,当等待的日志事件大于100条时,就开始同步处理日志。

  • drop_mode_qlen: pos_integer()

    • default: 3000

    当缓冲的日志事件数大于此值时,新的日志事件将被丢弃。起到过载保护的功能。 为了使过载保护算法正常工作必须要:sync_mode_qlen =< drop_mode_qlen =< flush_qlen 且 drop_mode_qlen > 1 要禁用某些模式,请执行以下操作。

    • 如果sync_mode_qlen被设置为0,所有的日志事件都被同步处理。也就是说,异步日志被禁用。
    • 如果sync_mode_qlen被设置为与drop_mode_qlen相同的值,同步模式被禁用。也就是说,处理程序总是以异步模式运行,除非调用drop或flushing。
    • 如果drop_mode_qlen被设置为与flush_qlen相同的值,则drop模式被禁用,永远不会发生。
  • flush_qlen: pos_integer()

    • default: 8000

    如果缓冲日志事件的数量增长大于此阈值,则会发生冲刷(删除)操作。 日志处理进程会丢弃缓冲的日志消息。 来缓解自身不会由于内存瀑涨而影响其它业务进程。日志内容会提醒有多少事件被删除。

  • overload_kill: log_overload_kill

  • burst_limit: log_burst_limit

  • supervisor_reports: error | progress

    • default: error

    Supervisor 报告的类型。默认为 error 类型。

    • error:仅记录 Erlang 进程中的错误。
    • progress:除了 error 信息外,还需要记录进程启动的详细信息。
  • max_depth: unlimited | non_neg_integer()

    • default: 100

    Erlang 内部格式日志格式化和 Erlang 进程消息队列检查的最大深度。

# log_overload_kill

日志过载终止,具有过载保护功能。当日志处理进程使用过多内存,或者缓存的日志消息过多时该功能被激活。
检测到过载时,日志处理进程将终止,并在冷却期后重新启动。

Config paths

  • log.console_handler.overload_kill
  • log.file_handlers.$name.overload_kill

Env overrides

  • EMQX_LOG__CONSOLE_HANDLER__OVERLOAD_KILL
  • EMQX_LOG__FILE_HANDLERS__$NAME__OVERLOAD_KILL

Fields

  • enable: boolean()

    • default: true

    日志处理进程过载时为保护自己节点其它的业务能正常,强制杀死日志处理进程。

  • mem_size: emqx_schema:bytesize()

    • default: "30MB"

    日志处理进程允许使用的最大内存。

  • qlen: pos_integer()

    • default: 20000

    允许的最大队列长度。

  • restart_after: emqx_schema:duration_ms() | infinity

    • default: "5s"

    如果处理进程终止,它会在以指定的时间后后自动重新启动。 infinity 不自动重启。

# log_rotation

默认情况下,日志存储在 ./log 目录(用于从 zip 文件安装)或 /var/log/emqx(用于二进制安装)。
这部分配置,控制每个日志处理进程保留的文件数量。

Config paths

  • log.file_handlers.$name.rotation

Env overrides

  • EMQX_LOG__FILE_HANDLERS__$NAME__ROTATION

Fields

  • enable: boolean()

    • default: true

    启用日志轮换功能。启动后生成日志文件后缀会加上对应的索引数字,比如:log/emqx.log.1。 系统会默认生成.siz/.idx用于记录日志位置,请不要手动修改这两个文件。

  • count: 1..2048

    • default: 10

    轮换的最大日志文件数。

# node

节点名称、Cookie、配置文件、数据目录和 Erlang 虚拟机(BEAM)启动参数。

Config paths

  • node

Env overrides

  • EMQX_NODE

Fields

  • name: string()

    • default: "emqx@127.0.0.1"

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

  • cookie: string()

    • default: "emqxsecretcookie"
    • mapping: vm_args.-setcookie

    分布式 Erlang 集群使用的 cookie 值。集群间保持一致

  • process_limit: 1024..134217727

    • default: 2097152
    • mapping: vm_args.+P

    Erlang系统同时存在的最大进程数。 实际选择的最大值可能比设置的数字大得多。 参考: https://www.erlang.org/doc/man/erl.html

  • max_ports: 1024..134217727

    • default: 1048576
    • mapping: vm_args.+Q

    Erlang系统同时存在的最大端口数。 实际选择的最大值可能比设置的数字大得多。 参考: https://www.erlang.org/doc/man/erl.html

  • dist_buffer_size: 1..2097151

    • default: 8192
    • mapping: vm_args.+zdbbl

    Erlang分布式缓冲区的繁忙阈值,单位是KB。

  • max_ets_tables: pos_integer()

    • default: 262144
    • mapping: vm_args.+e

    Erlang ETS 表的最大数量

  • data_dir: string()

    • mapping: emqx.data_dir

    节点数据存放目录,可能会自动创建的子目录如下:

    • mnesia/<node_name>。EMQX的内置数据库目录。例如,mnesia/emqx@127.0.0.1
      如果节点要被重新命名(例如,emqx@10.0.1.1)。旧目录应该首先被删除。
    • configs。在启动时生成的配置,以及集群/本地覆盖的配置。
    • patches: 热补丁文件将被放在这里。
    • trace: 日志跟踪文件。

    注意: 一个数据dir不能被两个或更多的EMQX节点同时使用。

  • config_files: [string()]

    • mapping: emqx.config_files

    启动时读取的配置文件列表。后面的配置文件项覆盖前面的文件。

  • global_gc_interval: emqx_schema:duration()

    • default: "15m"
    • mapping: emqx_machine.global_gc_interval

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

  • crash_dump_file: emqx_conf_schema:file()

    • default: "log/erl_crash.dump"
    • mapping: vm_args.-env ERL_CRASH_DUMP

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

  • crash_dump_seconds: emqx_schema:duration_s()

    • default: "30s"
    • mapping: vm_args.-env ERL_CRASH_DUMP_SECONDS

    保存崩溃文件最大允许时间,如果文件太大,在规则时间内没有保存完成,则会直接结束。

  • crash_dump_bytes: emqx_schema:bytesize()

    • default: "100MB"
    • mapping: vm_args.-env ERL_CRASH_DUMP_BYTES

    限制崩溃文件的大小,当崩溃时节点内存太大, 如果为了保存现场,需要全部存到崩溃文件中,此处限制最多能保存多大的文件。

  • dist_net_ticktime: emqx_schema:duration_s()

    • default: "2m"
    • mapping: vm_args.-kernel net_ticktime

    系统调优参数,此配置将覆盖 vm.args 文件里的 -kernel net_ticktime 参数。当一个节点持续无响应多久之后,认为其已经宕机并断开连接。

  • backtrace_depth: integer()

    • default: 23
    • mapping: emqx_machine.backtrace_depth

    错误信息中打印的最大堆栈层数

  • applications: emqx_schema:comma_separated_atoms()

    • default: []
    • mapping: emqx_machine.applications

    当新EMQX 加入集群时,应重启的Erlang应用程序的列表。

  • etc_dir: string()

    etc 存放目录

  • cluster_call: cluster_call

  • db_backend: mnesia | rlog

    • default: rlog
    • mapping: mria.db_backend

    rlog是默认的数据库,他适用于大规模的集群。 mnesia是备选数据库,在小集群中提供了很好的性能。

  • db_role: core | replicant

    • default: core
    • mapping: mria.node_role

    选择节点的角色。
    core 节点提供数据的持久性,并负责写入。建议将核心节点放置在不同的机架或不同的可用区。
    repliant 节点是临时工作节点。 从集群中删除它们,不影响数据库冗余
    建议复制节点多于核心节点。
    注意:该参数仅在设置backend时生效到 rlog

  • rpc_module: gen_rpc | rpc

    • default: gen_rpc
    • mapping: mria.rlog_rpc_module

    集群间推送事务日志到复制节点使用的协议。

  • tlog_push_mode: sync | async

    • default: async
    • mapping: mria.tlog_push_mode

    同步模式下,核心节点等待复制节点的确认信息,然后再发送下一条事务日志。

# rpc

EMQX 使用 gen_rpc 库来实现跨节点通信。
大多数情况下,默认的配置应该可以工作,但如果你需要做一些性能优化或者实验,可以尝试调整这些参数。

Config paths

  • rpc

Env overrides

  • EMQX_RPC

Fields

  • mode: sync | async

    • default: async

    sync 模式下,发送端等待接收端的 ack信号。

  • driver: tcp | ssl

    • default: tcp
    • mapping: gen_rpc.driver

    集群间通信使用的传输协议。

  • async_batch_size: integer()

    • default: 256
    • mapping: gen_rpc.max_batch_size

    异步模式下,发送的批量消息的最大数量。

  • port_discovery: manual | stateless

    • default: stateless
    • mapping: gen_rpc.port_discovery

    manual: 通过 tcp_server_port 来发现端口。
    stateless: 使用无状态的方式来发现端口,使用如下算法。如果节点名称是 emqxN@127.0.0.1, N 是一个数字,那么监听端口就是 5370 + N。

  • tcp_server_port: integer()

    • default: 5369
    • mapping: gen_rpc.tcp_server_port

    RPC 本地服务使用的 TCP 端口。
    只有当 rpc.port_discovery 设置为 manual 时,此配置才会生效。

  • ssl_server_port: integer()

    • default: 5369
    • mapping: gen_rpc.ssl_server_port

    RPC 本地服务使用的监听SSL端口。
    只有当 rpc.port_discovery 设置为 manual 且 dirver 设置为 ssl, 此配置才会生效。

  • tcp_client_num: 1..256

    • default: 10

    设置本节点与远程节点之间的 RPC 通信通道的最大数量。

  • connect_timeout: emqx_schema:duration()

    • default: "5s"
    • mapping: gen_rpc.connect_timeout

    建立 RPC 连接的超时时间。

  • certfile: emqx_conf_schema:file()

    • mapping: gen_rpc.certfile

    TLS 证书文件的路径,用于验证集群节点的身份。 只有当 rpc.driver 设置为 ssl 时,此配置才会生效。

  • keyfile: emqx_conf_schema:file()

    • mapping: gen_rpc.keyfile

    rpc.certfile 的私钥文件的路径。
    注意:此文件内容是私钥,所以需要设置权限为 600。

  • cacertfile: emqx_conf_schema:file()

    • mapping: gen_rpc.cacertfile

    验证 rpc.certfile 的 CA 证书文件的路径。
    注意:集群中所有节点的证书必须使用同一个 CA 签发。

  • send_timeout: emqx_schema:duration()

    • default: "5s"
    • mapping: gen_rpc.send_timeout

    发送 RPC 请求的超时时间。

  • authentication_timeout: emqx_schema:duration()

    • default: "5s"
    • mapping: gen_rpc.authentication_timeout

    远程节点认证的超时时间。

  • call_receive_timeout: emqx_schema:duration()

    • default: "15s"
    • mapping: gen_rpc.call_receive_timeout

    同步 RPC 的回复超时时间。

  • socket_keepalive_idle: emqx_schema:duration_s()

    • default: "15m"
    • mapping: gen_rpc.socket_keepalive_idle

    broker 之间的连接在最后一条消息发送后保持打开的时间。

  • socket_keepalive_interval: emqx_schema:duration_s()

    • default: "75s"
    • mapping: gen_rpc.socket_keepalive_interval

    keepalive 消息的间隔。

  • socket_keepalive_count: integer()

    • default: 9
    • mapping: gen_rpc.socket_keepalive_count

    keepalive 探测消息发送失败的次数,直到 RPC 连接被认为已经断开。

  • socket_sndbuf: emqx_schema:bytesize()

    • default: "1MB"
    • mapping: gen_rpc.socket_sndbuf

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

  • socket_recbuf: emqx_schema:bytesize()

    • default: "1MB"
    • mapping: gen_rpc.socket_recbuf

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

  • socket_buffer: emqx_schema:bytesize()

    • default: "1MB"
    • mapping: gen_rpc.socket_buffer

    TCP 调节参数。用户模式套接字缓冲区大小。

# topology

配置 Topology

Config paths

  • authentication.$INDEX.topology
  • authorization.sources.$INDEX.topology
  • gateway.coap.authentication.topology
  • gateway.coap.listeners.dtls.$name.authentication.topology
  • gateway.coap.listeners.udp.$name.authentication.topology
  • gateway.exproto.authentication.topology
  • gateway.exproto.listeners.dtls.$name.authentication.topology
  • gateway.exproto.listeners.ssl.$name.authentication.topology
  • gateway.exproto.listeners.tcp.$name.authentication.topology
  • gateway.exproto.listeners.udp.$name.authentication.topology
  • gateway.lwm2m.authentication.topology
  • gateway.lwm2m.listeners.dtls.$name.authentication.topology
  • gateway.lwm2m.listeners.udp.$name.authentication.topology
  • gateway.mqttsn.authentication.topology
  • gateway.mqttsn.listeners.dtls.$name.authentication.topology
  • gateway.mqttsn.listeners.udp.$name.authentication.topology
  • gateway.stomp.authentication.topology
  • gateway.stomp.listeners.ssl.$name.authentication.topology
  • gateway.stomp.listeners.tcp.$name.authentication.topology
  • listeners.ssl.$name.authentication.$INDEX.topology
  • listeners.tcp.$name.authentication.$INDEX.topology
  • listeners.ws.$name.authentication.$INDEX.topology
  • listeners.wss.$name.authentication.$INDEX.topology

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_AUTHORIZATION__SOURCES__$INDEX__TOPOLOGY
  • EMQX_GATEWAY__COAP__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY

Fields

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • max_overflow: non_neg_integer()

    • default: 0

    最大溢出。

  • overflow_ttl: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • overflow_check_period: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • local_threshold_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • connect_timeout_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • socket_timeout_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • server_selection_timeout_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • wait_queue_timeout_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • heartbeat_frequency_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

  • min_heartbeat_frequency_ms: emqx_schema:duration_ms()

    时间间隔,例如超时或 TTL。

# zone:conn_congestion

Settings for conn_congestion alarm.

Sometimes the MQTT connection (usually an MQTT subscriber) may get "congested", because there are too many packets to be sent. The socket tries to buffer the packets until the buffer is full. If more packets arrive after that, the packets will be "pending" in the queue, and we consider the connection congested.

Note: sndbuf can be set to larger value if the alarm is triggered too often. The name of the alarm is of format conn_congestion/<ClientID>/<Username>, where the <ClientID> is the client ID of the congested MQTT connection, and <Username> is the username or unknown_user.

Config paths

  • zones.$name.conn_congestion

Env overrides

  • EMQX_ZONES__$NAME__CONN_CONGESTION

Fields

  • enable_alarm: boolean()

    启用或者禁用连接阻塞告警功能

  • min_alarm_sustain_duration: emqx_schema:duration()

    清除警报前的最短时间。

    只有当队列中没有挂起的数据,并且连接至少被堵塞了 "min_alarm_sustain_duration" 毫秒时, 报警才会被清除。这是为了避免太频繁地清除和再次发出警报.

# zone:flapping_detect

This config controls the allowed maximum number of CONNECT packets received from the same clientid in a time frame defined by window_time. After the limit is reached, successive CONNECT requests are forbidden (banned) until the end of the time period defined by ban_time.

Config paths

  • zones.$name.flapping_detect

Env overrides

  • EMQX_ZONES__$NAME__FLAPPING_DETECT

Fields

  • enable: boolean()

    启用抖动检测功能

  • max_count: integer()

    MQTT 客户端在"窗口"时间内允许的最大断开次数

  • window_time: emqx_schema:duration()

    抖动检测的时间窗口。

  • ban_time: emqx_schema:duration()

    抖动的客户端将会被禁止登录多长时间

# zone:force_gc

Force garbage collection in MQTT connection process after they process certain number of messages or bytes of data.

Config paths

  • zones.$name.force_gc

Env overrides

  • EMQX_ZONES__$NAME__FORCE_GC

Fields

  • enable: boolean()

    启用强制垃圾回收

  • count: 0..inf

    在进程收到多少消息之后,对此进程执行垃圾回收

  • bytes: emqx_schema:bytesize()

    在进程处理过多少个字节之后,对此进程执行垃圾回收

# zone:force_shutdown

When the process message queue length, or the memory bytes reaches a certain value, the process is forced to close.

Note: "message queue" here refers to the "message mailbox" of the Erlang process, not the mqueue of QoS 1 and QoS 2.

Config paths

  • zones.$name.force_shutdown

Env overrides

  • EMQX_ZONES__$NAME__FORCE_SHUTDOWN

Fields

  • enable: boolean()

    启用 force_shutdown 功能

  • max_message_queue_len: 0..inf

    消息队列的最大长度

  • max_heap_size: emqx_schema:wordsize()

    Heap 的总大小

# zone:mqtt

Global MQTT configuration.
The configs here work as default values which can be overridden in zone configs

Config paths

  • zones.$name.mqtt

Env overrides

  • EMQX_ZONES__$NAME__MQTT

Fields

  • idle_timeout: infinity | emqx_schema:duration()

    TCP 连接建立后,如果在 idle_timeout 指定的时间内未收到客户端的 MQTT CONNECT 报文,则连接将被断开。

  • max_packet_size: emqx_schema:bytesize()

    允许的最大 MQTT 报文大小。

  • max_clientid_len: 23..65535

    允许的最大 MQTT Client ID 长度。

  • max_topic_levels: 1..65535

    允许的最大主题层级。

  • max_qos_allowed: qos()

    允许的最大 QoS 等级。

  • max_topic_alias: 0..65535

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

  • retain_available: boolean()

    是否启用对 MQTT 保留消息的支持。

  • wildcard_subscription: boolean()

    是否启用对 MQTT 通配符订阅的支持。

  • shared_subscription: boolean()

    是否启用对 MQTT 共享订阅的支持。

  • exclusive_subscription: boolean()

    是否启用对 MQTT 排它订阅的支持。

  • ignore_loop_deliver: boolean()

    是否为 MQTT v3.1.1/v3.1.0 客户端忽略投递自己发布的消息,类似于 MQTT 5.0 中的 No Local 订阅选项

  • strict_mode: boolean()

    是否以严格模式解析 MQTT 消息。 当设置为 true 时,例如客户端 ID、主题名称等中的无效 utf8 字符串将导致客户端断开连接。

  • response_information: string()

    指定返回给客户端的响应信息。如果设置为 "",则禁用此功能。仅适用于使用 MQTT 5.0 协议的客户端。

  • server_keepalive: integer() | disabled

    EMQX 要求客户端使用的保活时间,配置为 disabled 表示将使用客户端指定的保活时间。需要用到 MQTT 5.0 中的 Server Keep Alive,因此仅适用于使用 MQTT 5.0 协议的客户端。

  • keepalive_backoff: number()

    Broker 判定客户端保活超时使用的退避乘数。如果 EMQX 在 Keep Alive * Backoff * 2 秒内未收到任何报文,EMQX 将关闭当前连接。

  • max_subscriptions: 1..inf | infinity

    允许每个客户端建立的最大订阅数量。

  • upgrade_qos: boolean()

    投递消息时,是否根据订阅主题时的 QoS 等级来强制提升派发的消息的 QoS 等级。

  • max_inflight: 1..65535

    允许在完成应答前同时投递的 QoS 1 和 QoS 2 消息的最大数量。

  • retry_interval: emqx_schema:duration()

    QoS 1/2 消息的重新投递间隔。

  • max_awaiting_rel: integer() | infinity

    PUBREL (Client -> Broker) 最大等待队列长度。

  • await_rel_timeout: emqx_schema:duration()

    PUBREL (Client -> Broker) 最大等待时间,超时则会被丢弃。

  • session_expiry_interval: emqx_schema:duration()

    指定会话将在连接断开后多久过期,仅适用于非 MQTT 5.0 的连接。

  • max_mqueue_len: non_neg_integer() | infinity

    消息队列最大长度。持久客户端断开连接或飞行窗口已满时排队的消息长度。

  • mqueue_priorities: map() | disabled

    主题优先级。取值范围 [1-255] 默认优先级表为空,即所有的主题优先级相同。

    注:优先主题名称中不支持使用逗号和等号。 注:不在此列表中的主题,被视为最高/最低优先级,这取决于mqtt.mqueue_default_priority 的配置

    示例: 配置 "topic/1" > "topic/2": mqueue_priorities: {"topic/1": 10, "topic/2": 8}

  • mqueue_default_priority: highest | lowest

    默认的主题优先级,不在 主题优先级mqueue_priorities) 中的主题将会使用该优先级。

  • mqueue_store_qos0: boolean()

    指定在连接断开但会话保持期间,是否需要在消息队列中存储 QoS 0 消息。

  • use_username_as_clientid: boolean()

    是否使用用户名作为客户端 ID。 此设置的作用时间晚于 使用对端证书作为用户名peer_cert_as_username) 和 使用对端证书作为客户端 IDpeer_cert_as_clientid)。

  • peer_cert_as_username: disabled | cn | dn | crt | pem | md5

    使用对端证书中的 CN、DN 字段或整个证书内容来作为用户名。仅适用于 TLS 连接。 目前支持配置为以下内容:

    • cn: 取证书的 CN 字段作为 Username
    • dn: 取证书的 DN 字段作为 Username
    • crt: 取 DERPEM 证书的内容作为 Username
    • pem: 将 DER 证书内容转换为 PEM 格式后作为 Username
    • md5: 取 DERPEM 证书的内容的 MD5 值作为 Username
  • peer_cert_as_clientid: disabled | cn | dn | crt | pem | md5

    使用对端证书中的 CN、DN 字段或整个证书内容来作为客户端 ID。仅适用于 TLS 连接。 目前支持配置为以下内容:

    • cn: 取证书的 CN 字段作为 Client ID
    • dn: 取证书的 DN 字段作为 Client ID
    • crt: 取 DERPEM 证书的内容作为 Client ID
    • pem: 将 DER 证书内容转换为 PEM 格式后作为 Client ID
    • md5: 取 DERPEM 证书的内容的 MD5 值作为 Client ID

# zone:overload_protection

Overload protection mechanism monitors the load of the system and temporarily disables some features (such as accepting new connections) when the load is high.

Config paths

  • zones.$name.overload_protection

Env overrides

  • EMQX_ZONES__$NAME__OVERLOAD_PROTECTION

Fields

  • enable: boolean()

    是否对系统过载做出反应

  • backoff_delay: 0..inf

    一些不重要的任务可能会延迟执行,以毫秒为单位设置延迟

  • backoff_gc: boolean()

    如有必要,跳过强制GC

  • backoff_hibernation: boolean()

    如有必要,跳过进程休眠

  • backoff_new_conn: boolean()

    如有必要,关闭新进来的连接

# zone:stats

Enable/disable statistic data collection. Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.

Config paths

  • zones.$name.stats

Env overrides

  • EMQX_ZONES__$NAME__STATS

Fields

  • enable: boolean()

    启用/禁用统计数据收集功能

# authn-builtin_db:authentication

使用内置数据库作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: built_in_database

    后端类型。

  • user_id_type: clientid | username

    • default: "username"

    指定使用客户端ID clientid 还是用户名 username 进行认证。

  • password_hash_algorithm: authn-hash:bcrypt_rw | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash creation and verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

# authn-hash:bcrypt

Settings for bcrypt password hashing algorithm.

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: bcrypt

    BCRYPT password hashing.

# authn-hash:bcrypt_rw

Settings for bcrypt password hashing algorithm (for DB backends with write capability).

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: bcrypt

    BCRYPT password hashing.

  • salt_rounds: integer()

    • default: 10

    Salt rounds for BCRYPT password generation.

# authn-hash:other_algorithms

Settings for other password hashing algorithms.

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: plain | md5 | sha | sha256 | sha512

    Simple password hashing algorithm.

  • salt_position: disable | prefix | suffix

    • default: prefix

    Salt position for PLAIN, MD5, SHA, SHA256 and SHA512 algorithms.

# authn-hash:pbkdf2

Settings for PBKDF2 password hashing algorithm.

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: pbkdf2

    PBKDF2 password hashing.

  • mac_fun: md4 | md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512

    Specifies mac_fun for PBKDF2 hashing algorithm.

  • iterations: integer()

    Iteration count for PBKDF2 hashing algorithm.

  • dk_length: integer()

    Derived length for PBKDF2 hashing algorithm. If not specified, calculated automatically based on mac_fun.

# authn-http:get

使用 HTTP Server 作为认证服务的认证器的配置项 (使用 GET 请求)。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • method: get

    • default: get

    HTTP 请求方法。

  • headers: map()

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6

    HTTP Headers 列表 (无 content-type) 。

  • mechanism: password_based

    认证机制。

  • backend: http

    后端类型。

  • url: binary()

    认证 HTTP 服务器地址。

  • body: #{term() => binary()}

    HTTP request body。

  • request_timeout: emqx_schema:duration_ms()

    • default: "5s"

    HTTP 请求超时时长。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    连接HTTP服务器的超时时间。

  • enable_pipelining: pos_integer()

    • default: 100

    正整数,设置最大可发送的异步 HTTP 请求数量。当设置为 1 时,表示每次发送完成 HTTP 请求后都需要等待服务器返回,再继续发送下一个请求。

  • max_retries: non_neg_integer()

    • default: 5

    请求出错时的最大重试次数。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • request: connector-http:request

    如果提供了请求,调用者可以通过以下方式发送 HTTP 请求 emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    重试之间的间隔时间。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-http:post

使用 HTTP Server 作为认证服务的认证器的配置项 (使用 POST 请求)。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • method: post

    • default: post

    HTTP 请求方法。

  • headers: map()

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "content-type" = "application/json"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6
    7

    HTTP Headers 列表

  • mechanism: password_based

    认证机制。

  • backend: http

    后端类型。

  • url: binary()

    认证 HTTP 服务器地址。

  • body: #{term() => binary()}

    HTTP request body。

  • request_timeout: emqx_schema:duration_ms()

    • default: "5s"

    HTTP 请求超时时长。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    连接HTTP服务器的超时时间。

  • enable_pipelining: pos_integer()

    • default: 100

    正整数,设置最大可发送的异步 HTTP 请求数量。当设置为 1 时,表示每次发送完成 HTTP 请求后都需要等待服务器返回,再继续发送下一个请求。

  • max_retries: non_neg_integer()

    • default: 5

    请求出错时的最大重试次数。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • request: connector-http:request

    如果提供了请求,调用者可以通过以下方式发送 HTTP 请求 emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    重试之间的间隔时间。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-jwt:hmac-based

用于认证的 JWT 使用 HMAC 算法签发时的配置。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • use_jwks: false

    是否使用 JWKS。

  • algorithm: hmac-based

    JWT 签名算法,支持 HMAC (配置为 hmac-based)和 RSA、ECDSA (配置为 public-key)。

  • secret: binary()

    使用 HMAC 算法时用于验证 JWT 的密钥

  • secret_base64_encoded: boolean()

    • default: false

    密钥是否为 Base64 编码。

  • mechanism: jwt

    认证机制。

  • acl_claim_name: binary()

    • default: "acl"

    JWT claim name to use for getting ACL rules.

  • verify_claims: [term()]

    • default: {}

    需要验证的自定义声明列表,它是一个名称/值对列表。 值可以使用以下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符 认证时将验证 JWT(取自 Password 字段)中 claims 的值是否与 verify_claims 中要求的相匹配。
  • from: username | password

    • default: password

    要从中获取 JWT 的字段。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

# authn-jwt:jwks

用于认证的 JWTs 需要从 JWKS 端点获取时的配置。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • use_jwks: true

    是否使用 JWKS。

  • endpoint: string()

    JWKS 端点,它是一个以 JWKS 格式返回服务端的公钥集的只读端点。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • refresh_interval: integer()

    • default: 300

    JWKS 刷新间隔。

  • ssl: authn-jwt:ssl_enable | authn-jwt:ssl_disable

    • default: {enable = false}

    SSL 选项。

  • mechanism: jwt

    认证机制。

  • acl_claim_name: binary()

    • default: "acl"

    JWT claim name to use for getting ACL rules.

  • verify_claims: [term()]

    • default: {}

    需要验证的自定义声明列表,它是一个名称/值对列表。 值可以使用以下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符 认证时将验证 JWT(取自 Password 字段)中 claims 的值是否与 verify_claims 中要求的相匹配。
  • from: username | password

    • default: password

    要从中获取 JWT 的字段。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

# authn-jwt:public-key

用于认证的 JWT 使用 RSA 或 ECDSA 算法签发时的配置。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • use_jwks: false

    是否使用 JWKS。

  • algorithm: public-key

    JWT 签名算法,支持 HMAC (配置为 hmac-based)和 RSA、ECDSA (配置为 public-key)。

  • public_key: string()

    用于验证 JWT 的公钥。

  • mechanism: jwt

    认证机制。

  • acl_claim_name: binary()

    • default: "acl"

    JWT claim name to use for getting ACL rules.

  • verify_claims: [term()]

    • default: {}

    需要验证的自定义声明列表,它是一个名称/值对列表。 值可以使用以下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符 认证时将验证 JWT(取自 Password 字段)中 claims 的值是否与 verify_claims 中要求的相匹配。
  • from: username | password

    • default: password

    要从中获取 JWT 的字段。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

# authn-jwt:ssl_disable

SSL 配置。

Config paths

  • authentication.$INDEX.ssl
  • gateway.coap.authentication.ssl
  • gateway.coap.listeners.dtls.$name.authentication.ssl
  • gateway.coap.listeners.udp.$name.authentication.ssl
  • gateway.exproto.authentication.ssl
  • gateway.exproto.listeners.dtls.$name.authentication.ssl
  • gateway.exproto.listeners.ssl.$name.authentication.ssl
  • gateway.exproto.listeners.tcp.$name.authentication.ssl
  • gateway.exproto.listeners.udp.$name.authentication.ssl
  • gateway.lwm2m.authentication.ssl
  • gateway.lwm2m.listeners.dtls.$name.authentication.ssl
  • gateway.lwm2m.listeners.udp.$name.authentication.ssl
  • gateway.mqttsn.authentication.ssl
  • gateway.mqttsn.listeners.dtls.$name.authentication.ssl
  • gateway.mqttsn.listeners.udp.$name.authentication.ssl
  • gateway.stomp.authentication.ssl
  • gateway.stomp.listeners.ssl.$name.authentication.ssl
  • gateway.stomp.listeners.tcp.$name.authentication.ssl
  • listeners.ssl.$name.authentication.$INDEX.ssl
  • listeners.tcp.$name.authentication.$INDEX.ssl
  • listeners.ws.$name.authentication.$INDEX.ssl
  • listeners.wss.$name.authentication.$INDEX.ssl

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__SSL
  • EMQX_GATEWAY__COAP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__SSL

Fields

  • enable: false

    启用/禁用 SSL。

# authn-jwt:ssl_enable

SSL 配置。

Config paths

  • authentication.$INDEX.ssl
  • gateway.coap.authentication.ssl
  • gateway.coap.listeners.dtls.$name.authentication.ssl
  • gateway.coap.listeners.udp.$name.authentication.ssl
  • gateway.exproto.authentication.ssl
  • gateway.exproto.listeners.dtls.$name.authentication.ssl
  • gateway.exproto.listeners.ssl.$name.authentication.ssl
  • gateway.exproto.listeners.tcp.$name.authentication.ssl
  • gateway.exproto.listeners.udp.$name.authentication.ssl
  • gateway.lwm2m.authentication.ssl
  • gateway.lwm2m.listeners.dtls.$name.authentication.ssl
  • gateway.lwm2m.listeners.udp.$name.authentication.ssl
  • gateway.mqttsn.authentication.ssl
  • gateway.mqttsn.listeners.dtls.$name.authentication.ssl
  • gateway.mqttsn.listeners.udp.$name.authentication.ssl
  • gateway.stomp.authentication.ssl
  • gateway.stomp.listeners.ssl.$name.authentication.ssl
  • gateway.stomp.listeners.tcp.$name.authentication.ssl
  • listeners.ssl.$name.authentication.$INDEX.ssl
  • listeners.tcp.$name.authentication.$INDEX.ssl
  • listeners.ws.$name.authentication.$INDEX.ssl
  • listeners.wss.$name.authentication.$INDEX.ssl

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__SSL
  • EMQX_GATEWAY__COAP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__SSL

Fields

  • enable: true

    启用/禁用 SSL。

  • cacertfile: string()

    包含 PEM 编码的 CA 证书的文件的路径。

  • certfile: string()

    包含用户证书的文件的路径。

  • keyfile: string()

    包含 PEM 编码的用户私钥的文件的路径。

  • verify: verify_peer | verify_none

    • default: verify_none

    指定握手过程中是否校验对端证书。

  • server_name_indication: string()

    服务器名称指示(SNI)。

# authn-mongodb:replica-set

使用 MongoDB (Replica Set) 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: mongodb

    后端类型。

  • collection: binary()

    存储认证数据的集合。

  • filter: map()

    • default: {}

    在查询中定义过滤条件的条件表达式。 过滤器支持如下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
  • password_hash_field: binary()

    • default: "password_hash"

    文档中用于存放密码散列的字段。

  • salt_field: binary()

    • default: "salt"

    文档中用于存放盐值的字段。

  • is_superuser_field: binary()

    • default: "is_superuser"

    文档中用于定义用户是否具有超级用户权限的字段。

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • mongo_type: rs

    • default: rs

    Replica set模式。

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • w_mode: unsafe | safe

    • default: unsafe

    写模式。

  • r_mode: master | slave_ok

    • default: master

    读模式。

  • replica_set_name: binary()

    副本集的名称。

  • srv_record: boolean()

    • default: false

    使用 DNS SRV 记录。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auth_source: binary()

    与用户证书关联的数据库名称。

  • database: binary()

    数据库名字。

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-mongodb:sharded-cluster

使用 MongoDB (Sharded Cluster) 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: mongodb

    后端类型。

  • collection: binary()

    存储认证数据的集合。

  • filter: map()

    • default: {}

    在查询中定义过滤条件的条件表达式。 过滤器支持如下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
  • password_hash_field: binary()

    • default: "password_hash"

    文档中用于存放密码散列的字段。

  • salt_field: binary()

    • default: "salt"

    文档中用于存放盐值的字段。

  • is_superuser_field: binary()

    • default: "is_superuser"

    文档中用于定义用户是否具有超级用户权限的字段。

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • mongo_type: sharded

    • default: sharded

    Sharded cluster模式。

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • w_mode: unsafe | safe

    • default: unsafe

    写模式。

  • srv_record: boolean()

    • default: false

    使用 DNS SRV 记录。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auth_source: binary()

    与用户证书关联的数据库名称。

  • database: binary()

    数据库名字。

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-mongodb:standalone

使用 MongoDB (Standalone) 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: mongodb

    后端类型。

  • collection: binary()

    存储认证数据的集合。

  • filter: map()

    • default: {}

    在查询中定义过滤条件的条件表达式。 过滤器支持如下占位符:

    • ${username}: 将在运行时被替换为客户端连接时使用的用户名
    • ${clientid}: 将在运行时被替换为客户端连接时使用的客户端标识符
  • password_hash_field: binary()

    • default: "password_hash"

    文档中用于存放密码散列的字段。

  • salt_field: binary()

    • default: "salt"

    文档中用于存放盐值的字段。

  • is_superuser_field: binary()

    • default: "is_superuser"

    文档中用于定义用户是否具有超级用户权限的字段。

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • mongo_type: single

    • default: single

    Standalone模式。

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • w_mode: unsafe | safe

    • default: unsafe

    写模式。

  • srv_record: boolean()

    • default: false

    使用 DNS SRV 记录。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auth_source: binary()

    与用户证书关联的数据库名称。

  • database: binary()

    数据库名字。

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-mysql:authentication

使用 MySQL 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: mysql

    后端类型。

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • query: string()

    用于查询密码散列等用于认证的数据的 SQL 语句。

  • query_timeout: emqx_schema:duration_ms()

    • default: "5s"

    SQL 查询的超时时间。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 MySQL 默认端口 3306。

  • database: binary()

    数据库名字。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-postgresql:authentication

使用 PostgreSQL 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: postgresql

    后端类型。

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • query: string()

    用于查询密码散列等用于认证的数据的 SQL 语句。

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 PostgreSQL 默认端口 5432。

  • database: binary()

    数据库名字。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • username: binary()

    内部数据库的用户名。

  • password: binary()

    内部数据库密码。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-psk:psk_authentication

此配置用于启用 TLS-PSK 身份验证。

PSK 是 “Pre-Shared-Keys” 的缩写。

注意: 确保 SSL 监听器仅启用了 'tlsv1.2',并且配置了PSK 密码套件,例如 'RSA-PSK-AES256-GCM-SHA384'。

可以通过查看监听器中的 SSL 选项,了解更多详细信息。

可以通过配置 'init_file' 来设置初始化的 ID 和 密钥

Config paths

  • psk_authentication

Env overrides

  • EMQX_PSK_AUTHENTICATION

Fields

  • enable: boolean()

    • default: false

    是否开启 TLS PSK 支持

  • init_file: binary()

    如果设置了初始化文件,EMQX 将在启动时从初始化文件中导入 PSK 信息到内建数据库中。 这个文件需要按行进行组织,每一行必须遵守如下格式: PSKIdentity:SharedSecret 例如: mydevice1:c2VjcmV0

  • separator: binary()

    • default: ":"

    PSK 文件中 PSKIdentitySharedSecret 之间的分隔符

  • chunk_size: integer()

    • default: 50

    将 PSK 文件导入到内建数据时每个块的大小

# authn-redis:cluster

使用 Redis (Cluster) 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: redis

    后端类型。

  • cmd: string()

    用于查询密码散列等用于认证的数据的 Redis Command,目前仅支持 HGETHMGET

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 Redis 默认端口 6379。

  • redis_type: cluster

    集群模式。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • password: binary()

    内部数据库密码。

  • database: integer()

    • default: 0

    Redis 数据库 ID。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-redis:sentinel

使用 Redis (Sentinel) 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: redis

    后端类型。

  • cmd: string()

    用于查询密码散列等用于认证的数据的 Redis Command,目前仅支持 HGETHMGET

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • servers: [term()]

    集群将要连接的节点列表。 节点之间用逗号分隔,如:Node[,Node]. 每个节点的配置为:将要连接的 IPv4 或 IPv6 地址或主机名。 主机名具有以下形式:Host[:Port]。 如果未指定 [:Port],则使用 Redis 默认端口 6379。

  • redis_type: sentinel

    哨兵模式。

  • sentinel: string()

    Redis 哨兵模式下的集群名称。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • password: binary()

    内部数据库密码。

  • database: integer()

    • default: 0

    Redis 数据库 ID。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-redis:standalone

使用 Redis (Standalone) 作为认证数据源的认证器的配置项。

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    认证机制。

  • backend: redis

    后端类型。

  • cmd: string()

    用于查询密码散列等用于认证的数据的 Redis Command,目前仅支持 HGETHMGET

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

  • server: emqx_schema:ip_port()

    将要连接的 IPv4 或 IPv6 地址,或者主机名。
    主机名具有以下形式:Host[:Port]
    如果未指定 [:Port],则使用 MongoDB 默认端口 27017。

  • redis_type: single

    单机模式。

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • password: binary()

    内部数据库密码。

  • database: integer()

    • default: 0

    Redis 数据库 ID。

  • auto_reconnect: boolean()

    • default: true

    自动重连数据库。

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# authn-scram-builtin_db:authentication

Settings for Salted Challenge Response Authentication Mechanism (SCRAM) authentication.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: scram

    认证机制。

  • backend: built_in_database

    后端类型。

  • algorithm: sha256 | sha512

    • default: sha256

    Hashing algorithm.

  • iteration_count: non_neg_integer()

    • default: 4096

    Iteration count.

  • enable: boolean()

    • default: true

    设为 truefalse 以启用或禁用此认证数据源。

# auto_subscribe

设备登录成功之后,通过预设的订阅表示符,为设备自动完成订阅。支持使用占位符。

Config paths

  • auto_subscribe

Env overrides

  • EMQX_AUTO_SUBSCRIBE

Fields

  • topics: [auto_subscribe:topic]

    • default: []

    设备登录成功之后,通过预设的订阅表示符,为设备自动完成订阅。支持使用占位符。

# auto_subscribe:topic

订阅标识符,支持使用占位符,例如 client/${clientid}/username/${username}/host/${host}/port/${port} 必填,且不可为空字符串

Config paths

  • auto_subscribe.topics.$INDEX

Env overrides

  • EMQX_AUTO_SUBSCRIBE__TOPICS__$INDEX

Fields

  • topic: binary()

    订阅标识符,支持使用占位符,例如 client/${clientid}/username/${username}/host/${host}/port/${port} 必填,且不可为空字符串

  • qos: qos()

    • default: 0

    缺省值为 0,服务质量, QoS 0:消息最多传递一次,如果当时客户端不可用,则会丢失该消息。 QoS 1:消息传递至少 1 次。 QoS 2:消息仅传送一次。

  • rh: 0..2

    • default: 0

    指定订阅建立时服务端是否向客户端发送保留消息, 可选值 0:只要客户端订阅成功,服务端就发送保留消息。 可选值 1:客户端订阅成功且该订阅此前不存在,服务端才发送保留消息。毕竟有些时候客户端重新发起订阅可能只是为了改变一下 QoS,并不意味着它想再次接收保留消息。 可选值 2:即便客户订阅成功,服务端也不会发送保留消息。

  • rap: 0..1

    • default: 0

    缺省值为 0,这一选项用来指定服务端向客户端转发消息时是否要保留其中的 RETAIN 标识,注意这一选项不会影响保留消息中的 RETAIN 标识。因此当 Retain As Publish 选项被设置为 0 时,客户端直接依靠消息中的 RETAIN 标识来区分这是一个正常的转发消息还是一个保留消息,而不是去判断消息是否是自己订阅后收到的第一个消息(转发消息甚至可能会先于保留消息被发送,视不同 Broker 的具体实现而定)。

  • nl: 0..1

    • default: 0

    缺省值为0, MQTT v3.1.1:如果设备订阅了自己发布消息的主题,那么将收到自己发布的所有消息。 MQTT v5:如果设备在订阅时将此选项设置为 1,那么服务端将不会向设备转发自己发布的消息

# bridge:bridges

MQTT Bridge 配置

Config paths

  • bridges

Env overrides

  • EMQX_BRIDGES

Fields

  • webhook: {$name -> bridge:config}

    转发消息到 HTTP 服务器的 WebHook

  • mqtt: {$name -> ingress | egress}

    桥接到另一个 MQTT Broker 的 MQTT Bridge

# bridge:config

HTTP Bridge 配置

Config paths

  • bridges.webhook.$name

Env overrides

  • EMQX_BRIDGES__WEBHOOK__$NAME

Fields

  • enable: boolean()

    • default: true

    启用/禁用 Bridge

  • direction: egress

    • default: egress

    Bridge 的方向, 必须是 egress

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    连接HTTP服务器的超时时间。

  • max_retries: non_neg_integer()

    • default: 5

    请求出错时的最大重试次数。

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    重试之间的间隔时间。

  • pool_type: emqx_connector_http:pool_type()

    • default: random

    连接池的类型,可用类型有random, hash

  • pool_size: pos_integer()

    • default: 8

    连接池大小。

  • enable_pipelining: pos_integer()

    • default: 100

    正整数,设置最大可发送的异步 HTTP 请求数量。当设置为 1 时,表示每次发送完成 HTTP 请求后都需要等待服务器返回,再继续发送下一个请求。

  • request: connector-http:request

    如果提供了请求,调用者可以通过以下方式发送 HTTP 请求 emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

  • url: binary()

    HTTP Bridge 的 URL。
    路径中允许使用带变量的模板,但是 host, port 不允许使用变量模板。
    例如,http://localhost:9901/${topic} 是允许的, 但是http://${host}:9901/messagehttp://localhost:${port}/message 不允许。

  • local_topic: binary()

    发送到 'local_topic' 的消息都会转发到 HTTP 服务器。
    注意:如果这个 Bridge 被用作规则(EMQX 规则引擎)的输出,同时也配置了 'local_topic' ,那么这两部分的消息都会被转发到 HTTP 服务器。

  • method: post | put | get | delete

    • default: post

    HTTP 请求的方法。 所有可用的方法包括:post、put、get、delete。
    允许使用带有变量的模板。

  • headers: map()

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "content-type" = "application/json"
      "keep-alive" = "timeout=5"
    }
    
    1
    2
    3
    4
    5
    6
    7

    HTTP 请求的标头。
    允许使用带有变量的模板。

  • body: binary()

    • default: "${payload}"

    HTTP 请求的正文。
    允许使用带有变量的模板。

  • request_timeout: emqx_schema:duration_ms()

    • default: "15s"

    HTTP 请求超时

# connector-http:request

Config paths

  • authentication.$INDEX.request
  • authorization.sources.$INDEX.request
  • bridges.webhook.$name.request
  • gateway.coap.authentication.request
  • gateway.coap.listeners.dtls.$name.authentication.request
  • gateway.coap.listeners.udp.$name.authentication.request
  • gateway.exproto.authentication.request
  • gateway.exproto.listeners.dtls.$name.authentication.request
  • gateway.exproto.listeners.ssl.$name.authentication.request
  • gateway.exproto.listeners.tcp.$name.authentication.request
  • gateway.exproto.listeners.udp.$name.authentication.request
  • gateway.lwm2m.authentication.request
  • gateway.lwm2m.listeners.dtls.$name.authentication.request
  • gateway.lwm2m.listeners.udp.$name.authentication.request
  • gateway.mqttsn.authentication.request
  • gateway.mqttsn.listeners.dtls.$name.authentication.request
  • gateway.mqttsn.listeners.udp.$name.authentication.request
  • gateway.stomp.authentication.request
  • gateway.stomp.listeners.ssl.$name.authentication.request
  • gateway.stomp.listeners.tcp.$name.authentication.request
  • listeners.ssl.$name.authentication.$INDEX.request
  • listeners.tcp.$name.authentication.$INDEX.request
  • listeners.ws.$name.authentication.$INDEX.request
  • listeners.wss.$name.authentication.$INDEX.request

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__REQUEST
  • EMQX_AUTHORIZATION__SOURCES__$INDEX__REQUEST
  • EMQX_BRIDGES__WEBHOOK__$NAME__REQUEST
  • EMQX_GATEWAY__COAP__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__REQUEST
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__REQUEST
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__REQUEST
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__REQUEST

Fields

  • method: post | put | get | delete

    HTTP 请求方法。

  • path: binary()

    HTTP请求路径。

  • body: binary()

    HTTP请求报文主体。

  • headers: map()

    HTTP 头字段列表。

  • request_timeout: emqx_schema:duration_ms()

    HTTP 请求超时。

# connector-mqtt:connector

连接器的通用配置。

Config paths

  • bridges.mqtt.$name.connector
  • connectors.mqtt.$name

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME__CONNECTOR
  • EMQX_CONNECTORS__MQTT__$NAME

Fields

  • mode: cluster_shareload

    • default: cluster_shareload

    MQTT 桥的模式。 可用的类型有“cluster_singleton”,“cluster_shareload”。

    • cluster_singleton:在 emqx 集群内创建唯一的 MQTT 连接。
      在“cluster_singleton”节点中,所有发往远程代理的消息都通过相同的MQTT 连接。

    • cluster_shareload:在 emqx 集群的每个节点上创建一个 MQTT 连接。
      在“cluster_shareload”模式下,来自远程代理的传入负载通过共享订阅的方式接收。
      请注意,“clientid”以节点名称为后缀,这是为了避免不同节点之间的clientid冲突。 而且对于入口连接的“remote_topic”,我们只能使用共享订阅主题过滤器。

  • server: emqx_schema:ip_port()

    远程 MQTT Broker的主机和端口。

  • reconnect_interval: string()

    • default: "15s"

    Reconnect interval. Delay for the MQTT bridge to retry establishing the connection in case of transportation failure. Time interval is a string that contains a number followed by time unit:

    • ms for milliseconds,
    • s for seconds,
    • m for minutes,
    • h for hours;
      or combination of whereof: 1h5m0s
  • proto_ver: v3 | v4 | v5

    • default: v4

    MQTT 协议版本

  • bridge_mode: boolean()

    • default: false

    是否启用 Bridge Mode。 注意:此设置只针对 MQTT 协议版本 < 5.0 有效,并且需要远程 MQTT Broker 支持 Bridge Mode。

  • username: binary()

    • default: "emqx"

    MQTT 协议的用户名

  • password: binary()

    • default: "emqx"

    MQTT 协议的密码

  • clean_start: boolean()

    • default: true

    MQTT 清除会话

  • keepalive: string()

    • default: "300s"

    MQTT Keepalive. Time interval is a string that contains a number followed by time unit:

    • ms for milliseconds,
    • s for seconds,
    • m for minutes,
    • h for hours;
      or combination of whereof: 1h5m0s
  • retry_interval: string()

    • default: "15s"

    Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:

    • ms for milliseconds,
    • s for seconds,
    • m for minutes,
    • h for hours;
      or combination of whereof: 1h5m0s
  • max_inflight: non_neg_integer()

    • default: 32

    MQTT 协议的最大飞行(已发送但未确认)消息

  • replayq: connector-mqtt:replayq

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    启用 SSL 连接。

# connector-mqtt:replayq

本地磁盘消息队列

Config paths

  • bridges.mqtt.$name.connector.replayq
  • connectors.mqtt.$name.replayq

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME__CONNECTOR__REPLAYQ
  • EMQX_CONNECTORS__MQTT__$NAME__REPLAYQ

Fields

  • dir: boolean() | string()

    replayq 文件保存的目录。
    设置为 'false' 会禁用 replayq 功能。

  • seg_bytes: emqx_schema:bytesize()

    • default: "100MB"

    单个段的大小(以字节为单位)。
    一个段映射到 replayq 目录中的一个文件。 如果当前段已满,则新段(文件)将被打开写入。

  • offload: boolean()

    • default: false

    在Offload模式下,磁盘队列仅用于卸载队列尾段。
    消息首先缓存在内存中,然后写入replayq文件。内存缓大小为“seg_bytes” 指定的值。

# plugin:plugins

管理EMQX插件。
插件可以是EMQX安装包中的一部分,也可以是一个独立的安装包。
独立安装的插件称为“外部插件”。

Config paths

  • plugins

Env overrides

  • EMQX_PLUGINS

Fields

  • states: [plugin:state]

    • default: []

    一组插件的状态。插件将按照定义的顺序启动

  • install_dir: string()

    • default: "plugins"

    插件安装包的目录,不要自己创建,只能由emqx用户创建与修改

  • check_interval: emqx_schema:duration()

    • default: "5s"

    检查间隔:检查集群中插件的状态是否一致,
    如果连续3次检查结果不一致,则报警。

# plugin:state

描述插件的状态

Config paths

  • plugins.states.$INDEX

Env overrides

  • EMQX_PLUGINS__STATES__$INDEX

Fields

  • name_vsn: string()

    插件的名称{name}-{version}。
    它应该与插件的发布包名称一致,如my_plugin-0.1.0。

  • enable: boolean()

    设置为“true”以启用此插件

# prometheus

Prometheus 监控数据推送

Config paths

  • prometheus

Env overrides

  • EMQX_PROMETHEUS

Fields

  • push_gateway_server: string()

    • default: "http://127.0.0.1:9091"

    Prometheus 服务器地址

  • interval: emqx_schema:duration_ms()

    • default: "15s"

    数据推送间隔,单位 毫秒

  • enable: boolean()

    • default: false

    开启或关闭 Prometheus 数据推送

# retainer:flow_control

Retainer batching and rate limiting.

Config paths

  • retainer.flow_control

Env overrides

  • EMQX_RETAINER__FLOW_CONTROL

Fields

  • batch_read_number: non_neg_integer()

    • default: 0

    从存储后端批量加载时的每批数量上限,0 代表一次性读取

  • batch_deliver_number: 0..1000

    • default: 0

    批量派发时每批的数量。0 代表一次性全部派发

  • batch_deliver_limiter: emqx_limiter_schema:bucket_name()

    批量发送的限流器的名称。 限流器可以用来防止短时间内向客户端发送太多的消息,从而避免过多的消息导致客户端队列堵塞甚至崩溃。 这个名称需要是指向 limiter.batch 下的一个真实存在的限流器。 如果这个字段为空,则不使用限流器。

# retainer:mnesia_config

Configuration of the internal database storing retained messages.

Config paths

  • retainer.backend

Env overrides

  • EMQX_RETAINER__BACKEND

Fields

  • type: built_in_database

    • default: built_in_database

    后端类型

  • storage_type: ram | disc

    • default: ram

    选择消息是存放在磁盘还是内存中

  • max_retained_messages: non_neg_integer()

    • default: 0

    消息保留的数量上限。0 表示无限

  • index_specs: [[integer()]]

    • default:
    [
      [1, 2, 3],
      [1, 3],
      [2, 3],
      [3]
    ]
    
    1
    2
    3
    4
    5
    6

    Retainer index specifications: list of arrays of positive ascending integers. Each array specifies an index. Numbers in an index specification are 1-based word positions in topics. Words from specified positions will be used for indexing.
    For example, it is good to have [2, 4] index to optimize +/X/+/Y/... topic wildcard subscriptions.

# retainer

Configuration related to handling PUBLISH packets with a retain flag set to 1.

Config paths

  • retainer

Env overrides

  • EMQX_RETAINER

Fields

  • enable: boolean()

    • default: true

    是否开启消息保留功能

  • msg_expiry_interval: emqx_schema:duration_ms()

    • default: "0s"

    消息保留时间。0 代表永久保留

  • msg_clear_interval: emqx_schema:duration_ms()

    • default: "0s"

    消息清理间隔。0 代表不进行清理

  • flow_control: retainer:flow_control

    流控设置

  • max_payload_size: emqx_schema:bytesize()

    • default: "1MB"

    消息大小最大值

  • stop_publish_clear_msg: boolean()

    • default: false

    是否不发送保留消息的清理消息,在 MQTT 5.0 中如果一条保留消息的消息体为空,则会清除掉之前存储 的对应的保留消息,通过这个值控制是否停止发送清理消息

  • backend: retainer:mnesia_config

    保留消息的存储后端

# slow_subs

Configuration for slow_subs feature.

Config paths

  • slow_subs

Env overrides

  • EMQX_SLOW_SUBS

Fields

  • enable: boolean()

    • default: false

    开启慢订阅

  • threshold: emqx_schema:duration_ms()

    • default: "500ms"

    慢订阅统计的阈值

  • expire_interval: emqx_schema:duration_ms()

    • default: "300s"

    慢订阅记录的有效时间

  • top_k_num: pos_integer()

    • default: 10

    慢订阅统计表的记录数量上限

  • stats_type: whole | internal | response

    • default: whole

    慢订阅的统计类型

# statsd

Statsd 监控数据推送

Config paths

  • statsd

Env overrides

  • EMQX_STATSD

Fields

  • enable: boolean()

    • default: false

    开启或关闭 Statsd 数据推送

  • server: emqx_schema:ip_port()

    • default: "127.0.0.1:8125"

    Statsd 服务器地址

  • sample_time_interval: emqx_schema:duration_ms()

    • default: "10s"

    数据收集间隔,单位 毫秒

  • flush_time_interval: emqx_schema:duration_ms()

    • default: "10s"

    数据推送间隔,单位 毫秒

本页导航