Skip to content

NanoMQ 0.14-0.18 配置说明

此文档介绍 0.14-0.18.2 版本的 HOCON 配置。由于在 0.19 版本 NanoMQ 的 HOCON 格式配置文件内容进行了全方位的重构,所以不再与0.14-0.18.2兼容。

基本配置参数

参数名数据类型参数说明
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。
listeners.wss.bindStringWebsocket over TLS监听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
log.rotation.countInteger轮换的最大日志文件数;
默认: 5

标准MQTT桥接配置参数

参数名数据类型参数说明
bridges.mqtt.nodes[0].nameString节点名字。
bridges.mqtt.nodes[0].enableBoolean启动桥接功能(默认false不启用)。
bridges.mqtt.nodes[0].connector.serverString桥接目标 broker 地址 URL。
bridges.mqtt.nodes[0].connector.proto_verInteger桥接客户端 MQTT 版本(3|4|5)。
bridges.mqtt.nodes[0].connector.clientidString桥接客户端ID(默认 NULL 为自动生成随机 ID)。
bridges.mqtt.nodes[0].connector.keepaliveDuration保活间隔时间。
bridges.mqtt.nodes[0].connector.clean_startBoolean清除会话。
bridges.mqtt.nodes[0].connector.usernameString登录用户名。
bridges.mqtt.nodes[0].connector.passwordString登录密码。
bridges.mqtt.nodes[0].connector.conn_propertiesObjectConnector的 MQTT V5属性(见下表)
bridges.mqtt.nodes[0].connector.ssl.enableBoolean启动TLS监听(默认false)。
bridges.mqtt.nodes[0].connector.ssl.key_passwordStringTLS私钥密码。
bridges.mqtt.nodes[0].connector.ssl.keyfileStringTLS私钥数据。
bridges.mqtt.nodes[0].connector.ssl.certfileStringTLS Cert证书数据。
bridges.mqtt.nodes[0].connector.ssl.cacertfileStringTLS CA证书数据。
bridges.mqtt.nodes[0].hybrid_bridgingBoolean混合桥接模式开关,(默认 false 不启用), 如果想最大利用 QUIC,建议启用
bridges.mqtt.nodes[0].quic_keepaliveDurationQuic 传输层保活时间, (默认 120s )
bridges.mqtt.nodes[0].quic_idle_timeoutDurationQuic 连接最大过期时间 (默认 120s )
bridges.mqtt.nodes[0].quic_discon_timeoutDurationQuic 等待连接 ACK 最大时间 (默认 20s )
bridges.mqtt.nodes[0].quic_handshake_timeoutDurationQUIC 握手最大超时时间(默认 60s )
bridges.mqtt.nodes[0].quic_send_idle_timeoutDurationQUIC传输层重置拥塞控制算法的等待超时时间 (默认60 s)
bridges.mqtt.nodes[0].quic_initial_rtt_msDuration初始 RTT 估计时间 (默认 800ms)
bridges.mqtt.nodes[0].quic_max_ack_delay_msDuration发送 ACK 之前接收数据后等待时长(默认100ms)
bridges.mqtt.nodes[0].quic_qos_priorityBoolean高优先级发送QOS 1或2的消息(默认 true)
bridges.mqtt.nodes[0].quic_0rttBoolean0RTT 是 QUIC 协议的一个特性,用于快速重新建立连接 (默认 true)
bridges.mqtt.nodes[0].quic_multi_streamBooleanQuic Multiple stream 开关(默认false不启用
bridges.mqtt.nodes[0].parallelLong桥接客户端并发数。
bridges.mqtt.nodes[0].forwardsArray[String]转发Topic数组, 使用逗号,分隔多个Topic
bridges.mqtt.nodes[0].subscription[0].topicString第1个订阅Topic
bridges.mqtt.nodes[0].subscription[0].qosInteger第1个订阅Qos
bridges.mqtt.nodes[0].sub_propertiesObjectSubscription的MQTT V5属性(见下表)
bridges.mqtt.nodes[0].max_send_queue_lenInteger最大发送队列长度
bridges.mqtt.nodes[0].max_recv_queue_lenInteger最大接收队列长度

MQTT V5 属性配置参数

Connector属性:bridges.mqtt.nodes[0].connector.conn_properties

参数名数据类型参数说明
maximum_packet_sizeInteger最大报文长度
Value: 1 ~ 4294967295
receive_maximumInteger接收最大数量
Value: 1 ~ 65535
topic_alias_maximumInteger主题别名最大长度
Value: 0 ~ 65535
request_problem_infomationInteger请求问题信息
Default: 1
Value: 0 | 1
request_response_infomationInteger请求响应信息
Default: 0
Value: 0 | 1
session_expiry_intervalInteger会话过期间隔
Value: 0 ~ 4294967295
user_propertyMap[String, String]用户属性Map[key(String) - value(String)]*

Subscription属性: bridges.mqtt.nodes[0].sub_properties

参数名数据类型参数说明
identifierInteger订阅标识符
Value: 1 ~ 268,435,455
user_propertyMap[String, String]用户属性
Value: Map[key(String) - value(String)]

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].connector.ssl.enableBoolean启动TLS监听(默认false)。
bridge.aws.nodes[0].connector.ssl.key_passwordStringTLS私钥密码。
bridge.aws.nodes[0].connector.ssl.keyfileStringTLS私钥数据。
bridge.aws.nodes[0].connector.ssl.certfileStringTLS Cert证书数据。
bridge.aws.nodes[0].connector.ssl.cacertfileStringTLS CA证书数据。
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

WebHook

NanoMQ (0.14-0.18) 提供了可拓展的事件驱动型 WebHook 接口,本节将介绍如何启用 WebHook 功能,如何通过规则定义 WebHook 的触发时间和方式。

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/#"}]

启用 WebHook

bash
web.hook.enable=true

触发规则

etc/nanomq.conf 可配置触发规则,其配置的格式如下:

bash
## 格式示例
web.hook.rule.<Event>.<Number>=<Rule>


## 示例值
web.hook.rule.message.publish.1={"action": "on_message_publish", "topic": "a/b/c"}
web.hook.rule.message.publish.2={"action": "on_message_publish", "topic": "foo/#"}

Event 触发事件

目前支持以下事件:

名称说明执行时机
client.connack下发连接应答服务端准备下发连接应答报文时
client.disconnected连接断开客户端连接层在准备关闭时
message.publish消息发布服务端在发布(路由)消息前

Number

同一个事件可以配置多个触发规则,配置相同的事件应当依次递增。

Rule

触发规则,其值为一个 JSON 字符串,其中可用的 Key 有:

  • action :字符串,取固定值
  • topic :字符串,表示一个主题过滤器,操作的主题只有与该主题匹配才能触发事件的转发

例如,我们只将与 a/b/c 和 foo/# 主题匹配的消息转发到 Web 服务器上,其配置应该为:

bash
web.hook.rule.message.publish.1 = {"action": "on_message_publish", "topic": "a/b/c"}
web.hook.rule.message.publish.2 = {"action": "on_message_publish", "topic": "foo/#"}

这样 WebHook 仅会转发与 a/b/c 和 foo/# 主题匹配的消息,例如 foo/bar 等。

WebHook 事件参数

事件触发时 WebHook 会按照配置将每个事件组成一个 HTTP 请求发送到 url 所配置的 Web 服务器上。其请求格式为:

bash
URL: <url>      # 来自于配置中的 `url` 字段
Method: POST    # 固定为 POST 方法

Body: <JSON>    # Body 为 JSON 格式字符串

对于不同的事件,请求 Body 体内容有所不同,下表列举了各个事件中 Body 的参数列表:

client.connack

Key类型说明
actionstring事件名称 固定为:"client_connack"
clientidstring客户端 ClientId
usernamestring客户端 Username ,不存在时该值为 "undefined"
keepaliveinteger客户端申请的心跳保活时间
proto_verinteger协议版本号 ( 3 | 4 | 5 )
conn_ackstring"success" 表示成功,其它表示失败的原因

client.disconnected

Key类型说明
actionstring事件名称 固定为:"client_disconnected"
clientidstring客户端 ClientId
usernamestring客户端 Username ,不存在时该值为 "undefined"
reasonstring错误原因

message.publish

Key类型说明
actionstring事件名称 固定为:"message_publish"
from_client_idstring发布端 ClientId
from_usernamestring发布端 Username ,不存在时该值为 "undefined"
topicstring取消订阅的主题
qosenumQoS 等级,可取 0 1 2
retainbool是否为 Retain 消息
payloadstring消息 Payload
tsinteger消息的时间戳(毫秒)

授权配置

授权配置结构大致如下。

bash
authorization {
  no_match = allow
  deny_action = ignore
  cache {
    enable = true
    max_size = 1024
    duration = 1m
  }
  sources = [
    { ...   },
    { ...   }
  ]
}

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登录密码。

例子:

bash
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"
				}
			]
		}
  ]
}

ACL文件验证配置

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

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

例子:

bash
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"}
        ]
      }
	]
	
}

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

例子:

bash
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	
		]
}

规则引擎配置

参数名数据类型参数说明
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 语句