# Configuration

# Introduction

The configuration files of NanoMQ Broker is HOCON(Human-Optimized Config Object Notation).It is ideal for configuration data storage that is easy for humans to read and write. You can find these configuration files in the etc directory. Start from v0.14, for the sake of consistensy with EMQX 5.0, NanoMQ adapt to new HOCON style configuration.

FileDescription
etc/nanomq.confNanoMQ Configuration File
etc/nanomq_gateway.confNanoMQ Gateway File (for nanomq_cli)

Visit the old version of Config: Configuration (v0.13)

# Syntax

In config file the values can be notated as JSON like objects, such as

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

Another equivalent representation is flat, such as

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

This flat format is almost backward compatible (the so called 'cuttlefish' format).

It is not fully compatible because the often HOCON requires strings to be quoted, while cuttlefish treats all characters to the right of the = mark as the value.

e.g. cuttlefish: cuttlefish:websocket.bind = 0.0.0.0:8083/mqtt,HOCON:websocket.bind = "0.0.0.0:8083/mqtt".

# Config Overlay Rules

HOCON objects are overlaid, in general:

  • Within one file, objects defined 'later' recursively override objects defined 'earlier'
  • When layered, 'later' (higher layer) objects override objects defined 'earlier' (lower layer)

Below are more detailed rules.

For example, in below config, the last line debug overwrites error for console log handler's level config, but leaving to unchanged.

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

## ... more configs ...

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

# Parameter Description

# nanomq.conf

# basic configuration

NameTypeDescription
system.daemonBooleanLaunch with daemon(默认false)。
system.num_taskq_threadIntegerNumber of taskq threads used.
system.max_taskq_threadIntegerMaximum number of taskq threads used.
system.parallelLongNumber of parallel.
mqtt.session.property_sizeIntegerMax size for a MQTT property.
mqtt.session.msq_lenIntegerQueue length for resending messages.
mqtt.session.qos_durationIntegerThe interval of the qos timer.
mqtt.session.allow_anonymousBooleanAllow anonymous login.
mqtt.session.max_packet_sizeKbytesThe max packet size of NanoMQ (Kbytes)
mqtt.session.client_max_packet_sizeKbytesThe default max packet size of each client
mqtt.session.keepalive_backoffIntegerThe backoff for MQTT keepalive timeout.
listeners.tcp.enableBooleanEnable TCP listener(default: true).
listeners.tcp.bindStringUrl of listener.
listeners.ssl.enableBooleanEnable ssl listener(default: false).
listeners.ssl.bindStringURL of ssl listener.
listeners.ssl.keyStringUser's private PEM-encoded key.
listeners.ssl.keypassStringString containing the user's password. Only used if the private keyfile is password-protected.
listeners.ssl.certStringUser certificate data.
listeners.ssl.cacertStringUser's PEM-encoded CA certificates.
listeners.ssl.verify_peerBooleanVerify peer certificate.
listeners.ssl.fail_if_no_peer_certBooleanServer will fail if the client does not have a certificate to send.
listeners.ws.enableBooleanEnable websocket listener(default: true).
listeners.ws.bindStringURL of websocket listener.
http_server.enableBooleanEnable http server listerner (default: false).
http_server.portIntegerPort of http server.
http_server.usernameStringUser name of http server.
http_server.passwordStringPassword of http server.
http_server.auth_typeStringHttp server authentication type (default: basic).
http_server.jwt.public.keyfileStringpublic key file for JWT.
http_server.jwt.private.keyfileStringprivate key file for JWT.
log.toArray[String]Array of log types,( Use commas , to separate multiple types )
Log types: file, console, syslog
log.levelStringLog level:trace, debug, info, warn, error, fatal
log.dirStringThe dir for log files. (if log to file)
log.fileStringThe log filename. (if log to file)
log.rotation.sizeStringMaximum size of each log file;
Supported Unit: KB | MB | GB;
Default:10MB
log.rotation.countIntegerMaximum rotation count of log files;
Default: 5

# MQTT bridge configuration

NameTypeDescription
bridge.mqtt.nodes[0].nameStringNode name
bridge.mqtt.nodes[0].enableBooleanEnter MQTT bridge mode (default false ).
bridge.mqtt.nodes[0].connector.serverStringRemote Broker address.
bridge.mqtt.nodes[0].connector.proto_verBooleanMQTT client version(3|4|5).
bridge.mqtt.nodes[0].connector.clientidStringMQTT client identifier.
bridge.mqtt.nodes[0].connector.keepaliveIntegerInterval of keepalive.
bridge.mqtt.nodes[0].connector.clean_startBooleanClean session.
bridge.mqtt.nodes[0].connector.usernameStringLogin user name.
bridge.mqtt.nodes[0].connector.passwordStringLogin password.
bridge.mqtt.nodes[0].quic_keepaliveDurationInterval of a sending keepalive packet via QUIC transport., (default 120s )
bridge.mqtt.nodes[0].quic_idle_timeoutDurationHow long a connection can go idle before it is gracefully shut down. 0 to disable timeout, which may lost disconnect event msg. (default 120s )
bridge.mqtt.nodes[0].quic_discon_timeoutDurationHow long to wait for an ACK before declaring a path dead and disconnecting, This affects stream living time.(default 20s )
bridge.mqtt.nodes[0].quic_handshake_timeoutDurationThe Max time NanoMQ waits for establishing QUIC connection(default 60s )
bridge.mqtt.nodes[0].hybrid_bridgingBooleanHybrid bridging: enable or disable the hybrid bridging mode,(_default false _), recommend to enable it when you want to take advantage of QUIC
bridge.mqtt.nodes[0].congestion_controlStringCongestion control option (cubic
bridge.mqtt.nodes[0].multi_streamBooleanMultiple stream option,(default false
bridge.mqtt.nodes[0].parallelLongParallel of mqtt client.
bridge.mqtt.nodes[0].forwardsArray[String]Array of forward topics.( Use commas , to separate multiple topics )
bridge.mqtt.nodes[0].subscription[0].topicStringFirst Topic.
bridge.mqtt.nodes[0].subscription[0].qosIntegerFirst Qos.
bridge.mqtt.nodes[0].ssl.enableBooleanLaunch TLS ( default false)。
bridge.mqtt.nodes[0].ssl.key_passwordStringString containing the user's password. only used if the private keyfile is password-protected.
bridge.mqtt.nodes[0].ssl.keyfileStringUser's private PEM-encoded key.
bridge.mqtt.nodes[0].ssl.certfileStringUser certificate data.
bridge.mqtt.nodes[0].ssl.cacertfileStringUser's PEM-encoded CA certificates.

# AWS IoT Core bridge configuration

NameTypeDescription
bridge.aws.nodes[0].nameStringNode name
bridge.aws.nodes[0].enableBooleanEnter MQTT bridge mode (default false ).
bridge.aws.nodes[0].connector.serverStringAWS IoT Core URL (IP:PORT)。
bridge.aws.nodes[0].connector.clientidStringMQTT client identifier.
bridge.aws.nodes[0].connector.keepaliveDurationInterval of keepalive.
bridge.aws.nodes[0].connector.clean_startBooleanClean session.
bridge.aws.nodes[0].connector.usernameStringLogin user name.
bridge.aws.nodes[0].connector.passwordStringLogin password.
bridge.aws.nodes[0].parallelLongParallel of mqtt client.
bridge.aws.nodes[0].forwardsArray[String]Array of forward topics.( Use commas , to separate multiple topics )
bridge.aws.nodes[0].subscription[0].topicStringFirst Topic.
bridge.aws.nodes[0].subscription[0].qosIntegerFirst Qos.
bridge.aws.nodes[0].ssl.enableBooleanLaunch TLS ( default false)。
bridge.aws.nodes[0].ssl.key_passwordStringString containing the user's password. only used if the private keyfile is password-protected.
bridge.aws.nodes[0].ssl.keyfileStringUser's private PEM-encoded key.
bridge.aws.nodes[0].ssl.certfileStringUser certificate data.
bridge.aws.nodes[0].ssl.cacertfileStringUser's PEM-encoded CA certificates.

# WebHook configuration

NameTypeDescription
webhook.enableBooleanEnable WebHook (default: false)
webhook.urlStringWebhook URL
webhook.headers.<Any>StringHTTP Headers
Example:
1. webhook.headers.content-type=application/json
2. webhook.headers.accept=*
webhook.body.encodingStringThe encoding format of the payload field in the HTTP body
Options:
plain | base64 | base62
webhook.pool_sizeIntegerConnection process pool size (default: 32).
webhook.rule.client.connack.<No>StringExample:
webhook.rule.client.connack=[{"action": "on_client_connack"}]
webhook.rule.client.disconnected.<No>StringExample:
webhook.rule.client.disconnected=[{"action": "on_client_disconnected"}]
webhook.rule.message.publish.<No>StringExample:
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

The general config structure is the following:

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

sources

Optional list value that configures the chain of authorizers. Each authorizer can be enabled or disabled. Disabled authorizers are not taken into account. The absence of the value is treated as an empty chain.

For individual authorizer config formats, see the documentation for the corresponding authorizers.

no_match

Optional value, allow or deny. The default value is allow. Determines the default action for a publish/subscribe request if none of the configured authorizers found any authorization rules.

deny_action

Optional value, ignore or disconnect. The default value is ignore. Determines what to do if a publish/subscribe operation was rejected according to the authorization checks. If set to ignore, the operation is silently ignored. If set to disconnect, the client connection is dropped.

cache

Optional value with caching settings.

  • cache.enable — optional boolean value, default is true. Specifies whether to enable caching.
  • cache.max_size — optional integer value, default is 32. Specifies the maximum number of elements in the cache. Older records are evicted from the cache when the specified number is exceeded.
  • cache.ttl — optional duration value, default is 1m. Specifies how long cached values are kept in the cache.
# User Login authorization configuration
NameTypeDescription
usernameStringUsername.
passwordStringPassword.

Example:

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 configuration

ACL rules are matched from top to bottom. If a rule matches, its permission is applied, and the remaining rules are ignored.

NameTypeRequiredDescription
permitenumYespermission: allow ,deny
actionenumNooperation : publish, subscribe, pubsub
topicsArrary[String]NoArray of Topic
usernameStringNoUsername: "#" means all users
clientidStringNoClientID: "#" means all client IDs
andArray[Object]NoAND operator
orArray[Object]NoOR operator

Example:

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 authorication configuration
NameTypeDescriptiondefault
auth_http.enableBooleanEnable HTTP authenticationfalse
auth_http.auth_req.urlStringSpecify the target URL of the authentication request.http://127.0.0.1:80/mqtt/auth
auth_http.auth_req.methodStringSpecify the request method of the authentication request.
(POST , GET)
POST
auth_http.auth_req.headers.<Any>StringSpecify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields.auth_http.auth_req.headers.content-type = application/x-www-form-urlencoded
auth_http.auth_req.headers.accept = */*
auth_http.auth_req.paramsArray[Object]Specify the data carried in the authentication request.
When using the GET method, the value of auth_http.auth_req.params will be converted into k=v key-value pairs separated by & and sent as query string parameters.
When using the POST method, the value of auth_http.auth_req.params will be converted into k=v key-value pairs separated by & and sent in the form of Request Body. All placeholders will be replaced by run-time data , and the available placeholders are as follows:
%u: Username
%c: MQTT Client ID
%a: Client's network IP address
%r: The protocol used by the client can be:mqtt, mqtt-sn, coap, lwm2m and stomp
%P: Password
%p: Server port for client connection
%C: Common Name in client certificate
%d: Subject in client certificate
auth_http.auth_req.params = {clientid= "%c", username= "%u", password= "%P"}
auth_http.super_req.urlStringSpecify the target URL for the superuser authentication request.http://127.0.0.1:80/mqtt/superuser
auth_http.super_req.methodStringSpecifies the request method of the super user authentication request.
(POST , GET)
POST
auth_http.super_req.headers.<Any>StringSpecify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields.auth_http.super_req.headers.content-type = application/x-www-form-urlencoded
auth_http.super_req.headers.accept = */*
auth_http.super_req.paramsArray[Object]Specify the data carried in the authentication request.
When using the GET method, the value of auth_http.auth_req.params will be converted into k=v key-value pairs separated by & and sent as query string parameters.
When using the POST method, the value of auth_http.auth_req.params will be converted into k=v key-value pairs separated by & and sent in the form of Request Body. All placeholders will be replaced by run-time data , and the available placeholders are the same as those of auth_http.auth_req.params.
auth_http.super_req.params = {clientid= "%c", username= "%u", password= "%P"}
auth_http.acl_req.urlStringSpecify the target URL for ACL verification requests.http://127.0.0.1:8991/mqtt/acl
auth_http.acl_req.methodStringSpecifies the request method for ACL verification requests.
(POST , GET)
POST
auth_http.acl_req.headers.<Any>StringSpecify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields.auth_http.super_req.headers.content-type = application/x-www-form-urlencoded
auth_http.super_req.headers.accept = */*
auth_http.acl_req.paramsArray[Object]Specify the data carried in the authentication request.
When using the GET method, the value of auth_http.auth_req.params will be converted into k=v key-value pairs separated by & and sent as query string parameters.
When using the POST method, the value of auth_http.auth_req.params will be converted into k=v key-value pairs separated by & and sent in the form of Request Body. All placeholders will be replaced by run-time data , and the available placeholders are as follows:
%A: Permission to be verified, 1 means subscription, 2 means publish
%u: UserName
%c: MQTT Client ID
%a: Client network IP address
%r: The protocol used by the client can be: mqtt, mqtt-sn, coap, lwm2m and stomp
%m: Mount point
%t: Topic
auth_http.acl_req.params = {clientid = "%c", username = "%u", access = "%A", ipaddr = "%a", topic = "%t", mountpoint = "%m"}
auth_http.timeoutIntegerHTTP request timeout. Any setting equivalent to 0s means never timeout.5s
auth_http.connect_timeoutIntegerConnection timeout for HTTP requests. Any setting value equivalent to 0s means never time out.5s

Example :

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 engine configuration

NameTypeDescription
rule.optionStringRule engine option, when persistence with rule engine, this option is must be ON.

# Rule configuration for sqlite

NameTypeDescription
rule.sqlite.pathStringRule engine option SQLite3 database path, default is /tmp/rule_engine.db
rule.sqlite.enabledBoolenRule engine option SQLite3 is enabled, default is true
rule.sqlite.rules[0].enabledBoolenRule engine option rule is enbaled, default is true
rule.sqlite.rules[0].tableStringRule engine option SQLite3 database table name
rule.sqlite.rules[0].sqlStringRule engine sql clause

# Rule configuration for mysql

NameTypeDescription
rule.mysql.nameStringRule engine option mysql database name, default is mysql_rule_db
rule.mysql.enabledBoolenRule engine option mysql is enabled, default is true
rule.mysql.rules[0].enabledBoolenRule engine option rule is enbaled, default is true
rule.mysql.rules[0].tableStringRule engine option mysql database table name
rule.mysql.rules[0].hostStringRule engine option mysql database host
rule.mysql.rules[0].usernameStringRule engine option mysql database username
rule.mysql.rules[0].passwordStringRule engine option mysql database password
rule.mysql.rules[0].sqlStringRule engine sql clause

# Rule configuration for repub

NameTypeDescription
rule.repub.enabledBoolenRule engine option repub is enabled, default is true
rule.repub.rules[0].enabledBoolenRule engine option rule is enbaled, default is true
rule.repub.rules[0].addressStringRule engine option repub address (mqtt-tcp://host:port)
rule.repub.rules[0].topicStringRule engine option repub topic
rule.repub.rules[0].usernameStringRule engine option repub username
rule.repub.rules[0].passwordStringRule engine option repub password
rule.repub.rules[0].proto_verIntegerRule engine option repub protocol version, default is 4
rule.repub.rules[0].clientidStringRule engine option repub clientid
rule.repub.rules[0].keepaliveDurationRule engine option repub keepalive
rule.repub.rules[0].clean_startBooleanRule engine option repub clean_start flag, default is true
rule.repub.rules[0].sqlStringRule engine sql clause

# nanomq_gateway.conf

NameTypeDescription
gateway.mqtt.addressStringRemote Broker address.
gateway.mqtt.proto_verIntegerMQTT client version(3|4|5).
gateway.mqtt.clientidStringMQTT client identifier.
gateway.mqtt.keepaliveDurationInterval of keepalive.
gateway.mqtt.clean_startBooleanClean session.
gateway.mqtt.parallelLongParallel of mqtt client.
gateway.mqtt.usernameStringLogin user name.
gateway.mqtt.passwordStringLogin password.
gateway.mqtt.forwardStringForward topic.
gateway.mqtt.sub_topicStringMqtt subscribe topic.
gateway.mqtt.sub_qosIntegerMqtt subscribe qos.
gateway.zmq.sub_addressStringRemote ZMQ server subscribe address.
gateway.zmq.pub_addressStringRemote ZMQ server publish address.
gateway.zmq.sub_preStringRemote ZMQ server subscribe prefix.
gateway.zmq.pub_preStringRemote ZMQ server publish prefix.