# 配置说明

# 简介

NanoMQ 的配置文件格式是 HOCON 。 HOCON(Human-Optimized Config Object Notation)是一个JSON的超集,非常适用于易于人类读写的配置数据存储。你可以在 etc 目录找到这些配置文件,主要配置文件包括:

配置文件说明
etc/nanomq.confNanoMQ 配置文件
etc/nanomq_gateway.confNanoMQ 网关配置文件 (用于 nanomq_cli)

# 配置文件语法

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

websocket {
     enable=false
     bind="0.0.0.0:8083/mqtt"
}
1
2
3
4

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

websocket.enable = false
websocket.bind="0.0.0.0:8083/mqtt"
1
2

这种扁平格式几乎与 NanoMQ 的配置文件格式向后兼容(所谓的 'cuttlefish' 格式)。

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

例如,cuttlefish:websocket.bind = 0.0.0.0:8083/mqtt,HOCON:websocket.bind = "0.0.0.0:8083/mqtt"

# 配置重载规则

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

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

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

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

log {
    to=[file,console]
    level=error
}

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

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

# 参数说明

# nanomq.conf

# 基本配置参数

参数名数据类型参数说明
system.daemonBoolean后台启动(默认false)。
system.num_taskq_threadInteger任务线程数。
system.max_taskq_threadInteger最大任务线程数。
system.parallelLong并行数。
mqtt.session.property_sizeInteger最大属性长度。
mqtt.session.msq_lenInteger队列长度。
mqtt.session.qos_durationDurationQOS消息定时间隔时间。
mqtt.session.allow_anonymousBoolean允许匿名登录。
mqtt.session.max_packet_sizeKbytesNanoMQ 的最大包大小 (Kbytes)
mqtt.session.client_max_packet_sizeKbytes每个 client 的 最大包大小
mqtt.session.keepalive_backoffIntegerMQTT keepalive 的退避指数
listeners.tcp.enableBoolean启动TCP监听(默认true)。
listeners.tcp.bindString监听 tcp url。
listeners.ssl.enableBoolean启动TLS监听(默认false)。
listeners.ssl.bindString监听 tls url。
listeners.ssl.keyStringTLS私钥数据。
listeners.ssl.keypassStringTLS私钥密码。
listeners.ssl.certStringTLS Cert证书数据。
listeners.ssl.cacertStringTLS CA证书数据。
listeners.ssl.verify_peerBoolean验证客户端证书。
listeners.ssl.fail_if_no_peer_certBoolean拒绝无证书连接,与 tls.verify_peer 配合使用。
listeners.ws.enableBoolean启动websocket监听(默认true)。
listeners.ws.bindStringWebsocket监听URL。
http_server.enableBoolean启动Http服务监听(默认false)。
http_server.portIntegerHttp服务端监听端口。
http_server.usernameString访问Http服务用户名。
http_server.passwordString访问Http服务密码。
http_server.auth_typeStringHttp鉴权方式。(默认 basic
http_server.jwt.public.keyfileStringJWT 公钥文件.
http_server.jwt.private.keyfileStringJWT 私钥文件.
log.toArray[String]日志输出类型数组,使用逗号,分隔多种类型
支持文件,控制台,Syslog输出,对应参数:
file, console, syslog
log.levelString日志等级:trace, debug, info, warn, error, fatal
log.dirString日志文件存储路径 (输出文件时生效)
log.fileString日志文件名(输出文件时生效)
log.rotation.sizeString每个日志文件的最大占用空间;
支持单位: KB| MB | GB;
默认:10MB
log.rotation.countInteger轮换的最大日志文件数;
默认: 5

# 标准MQTT桥接配置参数

参数名数据类型参数说明
bridge.mqtt.nodes[0].nameString节点名字。
bridge.mqtt.nodes[0].enableBoolean启动桥接功能(默认false不启用)。
bridge.mqtt.nodes[0].connector.serverString桥接目标 broker 地址 URL。
bridge.mqtt.nodes[0].connector.proto_verInteger桥接客户端 MQTT 版本(3|4|5)。
bridge.mqtt.nodes[0].connector.clientidString桥接客户端ID(默认 NULL 为自动生成随机 ID)。
bridge.mqtt.nodes[0].connector.keepaliveDuration保活间隔时间。
bridge.mqtt.nodes[0].connector.clean_startBoolean清除会话。
bridge.mqtt.nodes[0].connector.usernameString登录用户名。
bridge.mqtt.nodes[0].connector.passwordString登录密码。
bridge.mqtt.nodes[0].quic_keepaliveDurationQuic 传输层保活时间, (默认 120s )
bridge.mqtt.nodes[0].quic_idle_timeoutDurationQuic 连接最大过期时间 (默认 120s )
bridge.mqtt.nodes[0].quic_discon_timeoutDurationQuic 等待连接 ACK 最大时间 (默认 20s )
bridge.mqtt.nodes[0].quic_handshake_timeoutDurationQUIC 握手最大超时时间(默认 60s )
bridge.mqtt.nodes[0].hybrid_bridgingBoolean混合桥接模式开关,(默认 false 不启用), 如果想最大利用 QUIC,建议启用
bridge.mqtt.nodes[0].congestion_controlString拥塞控制选项 (cubic
bridge.mqtt.nodes[0].multi_streamBooleanMultiple stream 开关,(默认false不启用
bridge.mqtt.nodes[0].parallelLong桥接客户端并发数。
bridge.mqtt.nodes[0].forwardsArray[String]转发Topic数组, 使用逗号,分隔多个Topic
bridge.mqtt.nodes[0].subscription[0].topicString第1个订阅Topic
bridge.mqtt.nodes[0].subscription[0].qosInteger第1个订阅Qos
bridge.mqtt.nodes[0].ssl.enableBoolean启动TLS监听(默认false)。
bridge.mqtt.nodes[0].ssl.key_passwordStringTLS私钥密码。
bridge.mqtt.nodes[0].ssl.keyfileStringTLS私钥数据。
bridge.mqtt.nodes[0].ssl.certfileStringTLS Cert证书数据。
bridge.mqtt.nodes[0].ssl.cacertfileStringTLS CA证书数据。

# Aws IoT Core MQTT桥接配置参数

参数名数据类型参数说明
bridge.aws.nodes[0].nameBoolean节点名字。
bridge.aws.nodes[0].enableBoolean启动桥接功能(默认false不启用)。
bridge.aws.nodes[0].connector.serverStringAWS IoT Core 地址 URL (IP:PORT)。
bridge.aws.nodes[0].connector.proto_verInteger桥接客户端 MQTT 版本(3|4|5)。
bridge.aws.nodes[0].connector.clientidString桥接客户端ID(默认 NULL 为自动生成随机 ID)。
bridge.aws.nodes[0].connector.keepaliveDuration保活间隔时间。
bridge.aws.nodes[0].connector.clean_startBoolean清除会话。
bridge.aws.nodes[0].connector.usernameString登录用户名。
bridge.aws.nodes[0].connector.passwordString登录密码。
bridge.aws.nodes[0].parallelLong桥接客户端并发数。
bridge.aws.nodes[0].forwardsArray[String]转发Topic数组, 使用逗号,分隔多个Topic
bridge.aws.nodes[0].subscription[0].topicString第1个订阅Topic
bridge.aws.nodes[0].subscription[0].qosInteger第1个订阅Qos
bridge.aws.nodes[0].tls.enableBoolean启动TLS监听(默认false)。
bridge.aws.nodes[0].tls.key_passwordStringTLS私钥密码。
bridge.aws.nodes[0].tls.keyfileStringTLS私钥数据。
bridge.aws.nodes[0].tls.certfileStringTLS Cert证书数据。
bridge.aws.nodes[0].tls.cacertfileStringTLS CA证书数据。

# WebHook配置

参数名数据类型参数说明
webhook.enableBoolean启动WebHook (默认: false)
webhook.urlStringWebhook URL
webhook.headers.<Any>StringHTTP Headers
Example:
1. webhook.headers.content-type=application/json
2. webhook.headers.accept=*
webhook.body.encodingStringPayload编码方式
Options:
plain | base64 | base62
webhook.pool_sizeInteger连接池大小 (默认: 32).
webhook.rule.client.connack.<No>String示例:
webhook.rule.client.connack=[{"action": "on_client_connack"}]
webhook.rule.client.disconnected.<No>String示例:
webhook.rule.client.disconnected=[{"action": "on_client_disconnected"}]
webhook.rule.message.publish.<No>String示例:
webhook.rule.message.publish=[{"action": "on_message_publish"}]
webhook.rule.message.publish=[{"action": "on_message_publish"}, {"topic": "topic/1/2"}]
webhook.rule.message.publish = [{"action": "on_message_publish"}, {"topic": "foo/#"}]

# 授权配置

授权配置结构大致如下。

authorization {
  no_match = allow
  deny_action = ignore
  cache {
    enable = true
    max_size = 1024
    duration = 1m
  }
  sources = [
    { ...   },
    { ...   }
  ]
} 
1
2
3
4
5
6
7
8
9
10
11
12
13

sources

带顺序的数组(非必需字段)。每个数组元素是一个 Authorizer 的数据源相关配置。 数组中的每个元素都有一个 enable 字段,可用于快速启停切换。 如果该配置项缺失,则当作空链处理。

每个 Authorizer 的详细配置,可以参考相应的配置文件文档。

no_match

可选值,可以设置为 allowdeny。缺省值是 allow。 当 EMQX 无法从认证链中为某个客户端匹配到任何规则时候,将会使用这个默认的规则。

deny_action

可选值,可以设置为 ignoredisconnect。默认值是 ignore。 这个配置用于指定当拒绝访问发生时,应该如何对待这个客户端的 MQTT 连接。 如果配置成 ignore,那么这个操作会被丢弃,例如,如果是一个发布动作,那么这消息会被丢弃;如果是一个订阅操作,那么订阅请求会被拒绝。 如果配置成 disconnect,那么这个客户端将会被断开连接。

cache

ACL 缓存的配置。

  • cache.enable — 默认是 true。为 ACL 开启缓存。
  • cache.max_size — 默认值 32。此配置规定每个客户端允许缓存的 ACL 规则数量。当超过上限时,老的记录将会被删掉。
  • cache.ttl — 默认 1m(一分钟)。 该配置规定 ACL 规则缓存有效时间。
# 用户登陆验证
参数名数据类型参数说明
usernameString登录用户名。
passwordString登录密码。

例子:

authorization {
	no_match = allow
	deny_action = ignore

	cache = {
		enable = false
		max_size = 32
		ttl = 1m
	}

	sources = [
		{
			type = simple
			enable = false
			users = [
				{
					username = "admin"
					password = "public"
				}
				{
					username = "client"
					password = "public"
				}
			]
		}
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# ACL文件验证配置

ACL规则的匹配遵循自顶向下的顺序。当一个规则匹配到当前客户端时,规则允许或拒绝的动作就会生效,后面的规则不再继续检查。

字段名数据类型必填描述
permitenum规则权限:允许:allow拒绝:deny
actionenum指定动作:发布: publish订阅: subscribe以上二者: pubsub
topicsArrary[String]主题或主题过滤器数组
usernameString用户名若输入值为"#",表示所有用户
clientidString客户端ID若输入值为"#",表示所有客户端
andArray[Map]与操作
orArray[Map]或操作

例子:

authorization {
	## Allow or deny if no ACL rules matched.
	##
	## Value: allow | deny
	no_match = allow
	
	## The action when acl check reject current operation
	##
	## Value: ignore | disconnect
	## Default: ignore
	deny_action = ignore

	cache = {
		## Whether to enable ACL cache.
		##
		## If enabled, ACLs roles for each client will be cached in the memory
		##
		## Value: on | off
		enable = false

		## The maximum count of ACL entries can be cached for a client.
		##
		## Value: Integer greater than 0
		## Default: 32
		max_size = 32

		## The time after which an ACL cache entry will be deleted
		##
		## Value: Duration
		## Default: 1 minute
		ttl = 1m
	}
	sources = [
    {
        type = file
        enable = false

        rules = [
          ## Allow MQTT client using username "dashboard"  to subscribe to "$SYS/#" topics
          {"permit": "allow", "username": "dashboard", "action": "subscribe", "topics": ["$SYS/#"]}

          ## Allow users with IP address "127.0.0.1" to publish/subscribe to topics "$SYS/#", "#"
          {"permit": "allow", "ipaddr": "127.0.0.1", "action": "pubsub", "topics": ["$SYS/#", "#"]}

          ## Deny "All Users" subscribe to "$SYS/#" "#" Topics
          {"permit": "deny", "username": "#", "action": "subscribe", "topics": ["$SYS/#", "#"]}

          ## Allow any other publish/subscribe operation
          {"permit": "allow"}
        ]
      }
	]
	
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# HTTP身份验证
参数名数据类型参数说明默认
auth_http.enableBoolean启动HTTP认证false
auth_http.auth_req.urlString认证请求的目标 URL。http://127.0.0.1:80/mqtt/auth
auth_http.auth_req.methodString认证请求的请求方法。
(POST , GET)
POST
auth_http.auth_req.headers.<Any>String指定 HTTP 请求头部中的数据。<Key> 指定 HTTP 请求头部中的字段名,此配置项的值为相应的字段值。<Key> 可以是标准的 HTTP 请求头部字段,也可以自定义的字段,可以配置多个不同的请求头部字段。
auth_http.auth_req.headers.content-type = application/x-www-form-urlencoded
auth_http.auth_req.headers.accept = */*
auth_http.auth_req.paramsArray[Object]指定认证请求中携带的数据。
, 分隔的 k=v 键值对,v 可以是固定内容,也可以是占位符。
使用 GET 方法时 auth_http.auth_req.params 的值将被转换为以 & 分隔的 k=v 键值对以查询字符串参数的形式发送。
使用 POST 方法时 auth_http.auth_req.params 的值将被转换为以 & 分隔的 k=v 键值对以 Request Body 的形式发送。所有的占位符都会被运行时数据所替换,可用的占位符如下:
%u: 用户名
%c: MQTT Client ID
%a: 客户端的网络 IP 地址
%r: 客户端使用的协议,可以是:mqtt, mqtt-sn, coap, lwm2m 以及 stomp
%P: 密码
%p: 客户端连接的服务端端口
%C: 客户端证书中的 Common Name
%d: 客户端证书中的 Subject
auth_http.auth_req.params = {clientid= "%c", username= "%u", password= "%P"}
auth_http.super_req.urlString指定超级用户认证请求的目标 URL。http://127.0.0.1:80/mqtt/superuser
auth_http.super_req.methodString指定超级用户认证请求的请求方法。
(POST , GET)
POST
auth_http.super_req.headers.<Any>String指定 HTTP 请求头部中的数据。<Key> 指定 HTTP 请求头部中的字段名,此配置项的值为相应的字段值。<Key> 可以是标准的 HTTP 请求头部字段,也可以自定义的字段,可以配置多个不同的请求头部字段。auth_http.super_req.headers.content-type = application/x-www-form-urlencoded
auth_http.super_req.headers.accept = */*
auth_http.super_req.paramsArray[Object]指定超级用户认证请求中携带的数据。
使用 GET 方法时 auth_http.super_req.params 的值将被转换为以 & 分隔的 k=v 键值对以查询字符串参数的形式发送。
使用 POST 方法时 auth_http.super_req.params 的值将被转换为以 & 分隔的 k=v 键值对以 Request Body 的形式发送。所有的占位符都会被运行时数据所替换,可用的占位符同 auth_http.auth_req.params
auth_http.super_req.params = {clientid= "%c", username= "%u", password= "%P"}
auth_http.acl_req.urlString指定 ACL 验证请求的目标 URL。http://127.0.0.1:8991/mqtt/acl
auth_http.acl_req.methodString指定 ACL 验证请求的请求方法。(POST , GET)POST
auth_http.acl_req.headers.<Any>String指定 HTTP 请求头部中的数据。<Key> 指定 HTTP 请求头部中的字段名,此配置项的值为相应的字段值。<Key> 可以是标准的 HTTP 请求头部字段,也可以自定义的字段,可以配置多个不同的请求头部字段。auth_http.super_req.headers.content-type = application/x-www-form-urlencoded
auth_http.super_req.headers.accept = */*
auth_http.acl_req.paramsArray[Object]指定 ACL 验证请求中携带的数据。以 , 分隔的 k=v 键值对,v 可以是固定内容,也可以是占位符。
使用 GET 方法时 auth_http.acl_req.params 的值将被转换为以 & 分隔的 k=v 键值对以查询字符串参数的形式发送。
使用 POST 方法时 auth_http.acl_req.params 的值将被转换为以 & 分隔的 k=v 键值对以 Request Body 的形式发送。所有的占位符都会被运行时数据所替换,可用的占位符如下:
%A: 需要验证的权限,1 表示订阅,2 表示发布
%u: 用户名
%c: MQTT Client ID
%a: 客户端的网络 IP 地址
%r: 客户端使用的协议,可以是:mqtt, mqtt-sn, coap, lwm2m 以及 stomp
%m: 挂载点
%t: 主题
auth_http.acl_req.params = {clientid = "%c", username = "%u", access = "%A", ipaddr = "%a", topic = "%t", mountpoint = "%m"}
auth_http.timeoutIntegerHTTP 请求超时时间。任何等价于 0s 的设定值都表示永不超时。5s
auth_http.connect_timeoutIntegerHTTP 请求的连接超时时间。任何等价于 0s 的设定值都表示永不超时。5s

例子:

authorization {
			sources = [
        type = http
        enable = false
        auth_req {
          url = "http://127.0.0.1:80/mqtt/auth"
          method = post
          headers.content-type = "application/x-www-form-urlencoded"
          params = {clientid = "%c", username = "%u", password = "%p"}
        }

        super_req {
          url = "http://127.0.0.1:80/mqtt/superuser"
          method = "post"
          headers.content-type = "application/x-www-form-urlencoded"
          params = {clientid = "%c", username = "%u", password = "%p"}
        }

        acl_req {
          url = "http://127.0.0.1:8991/mqtt/acl"
          method = "post"
          headers.content-type = "application/x-www-form-urlencoded"
          params = {clientid = "%c", username = "%u", access = "%A", ipaddr = "%a", topic = "%t", mountpoint = "%m"}
        }

        timeout = 5s
        connect_timeout = 5s
        pool_size = 32	
		]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 规则引擎配置

参数名数据类型参数说明
rule.optionString规则引擎开关, 当时用规则引擎进行持久化,必须设置该选项为 ON。

# SQLITE规则配置

参数名数据类型参数说明
rule.sqlite.pathString规则引擎 SQLite3 数据库路径, 默认是 /tmp/rule_engine.db
rule.sqlite.enabledBoolen规则引擎 SQLite3 数据库开关状态, 默认是 true
rule.sqlite.rules[0].enabledBoolen规则引擎 SQLite3 数据库当前规则开关状态, 默认是 true
rule.sqlite.rules[0].tableString规则引擎 SQLite3 数据库表名
rule.sqlite.rules[0].sqlString规则引擎 sql 语句

# MYSQL规则配置

参数名数据类型参数说明
rule.mysql.nameString规则引擎 mysql 数据库名字, 默认是 mysql_rule_db
rule.mysql.enabledBoolen规则引擎 mysql 数据库开关状态, 默认是 true
rule.mysql.rules[0].enabledBoolen规则引擎 mysql 数据库当前规则开关状态, 默认是 true
rule.mysql.rules[0].tableString规则引擎 mysql 数据库表名字
rule.mysql.rules[0].hostString规则引擎 mysql 数据库主机名
rule.mysql.rules[0].usernameString规则引擎 mysql 数据库用户
rule.mysql.rules[0].passwordString规则引擎 mysql 数据库密
rule.mysql.rules[0].sqlString规则引擎 sql 语句

# Repub规则配置

参数名数据类型参数说明
rule.repub.enabledBoolen规则引擎 repub 开关状态, 默认是 true
rule.repub.rules[0].enabledBoolen规则引擎 repub 当前规则开关状态, 默认是 true
rule.repub.rules[0].addressString规则引擎重新发布地址 (mqtt-tcp://host:port)
rule.repub.rules[0].topicString规则引擎重新发布主题
rule.repub.rules[0].usernameString规则引擎重新发布用户名
rule.repub.rules[0].passwordString规则引擎重新发布密码
rule.repub.rules[0].proto_verInteger规则引擎重新发布协议版本, 默认是 4
rule.repub.rules[0].clientidString规则引擎重新发布客户端标识符
rule.repub.rules[0].keepaliveDuration规则引擎重新发布保活时间, 默认值是 60
rule.repub.rules[0].clean_startBoolean规则引擎重新发布 clean_start 标志, 默认是 true
rule.repub.rules[0].sqlString规则引擎 sql 语句

# nanomq_gateway.conf

参数名数据类型参数说明
gateway.mqtt.addressString远端 Broker 地址。
gateway.mqtt.proto_verIntegerMQTT 客户端版本(3|4|5)。
gateway.mqtt.clientidStringMQTT 客户端标识符。
gateway.mqtt.keepaliveDuration保活间隔时间。
gateway.mqtt.clean_startBoolean清除会话标志。
gateway.mqtt.parallelInteger并行的 mqtt 客户端数量。
gateway.mqtt.usernameString登陆的用户名。
gateway.mqtt.passwordString登陆的密码。
gateway.mqtt.forwardString转发的主题。
gateway.mqtt.sub_topicString订阅的 Mqtt 主题。
gateway.mqtt.sub_qosInteger订阅的 Mqtt 服务级别。
gateway.zmq.sub_addressString远端的 ZMQ 服务订阅地址。
gateway.zmq.pub_addressString远端的 ZMQ 服务发布地址。
gateway.zmq.sub_preString远端的 ZMQ 服务订阅前缀。
gateway.zmq.pub_preString远端的 ZMQ 服务发布前缀。