NanoMQ 0.14-0.18 Configuration Guide

This document introduces the HOCON configuration for NanoMQ 0.14 to 0.18.2. The HOCON format configuration files in NanoMQ 0.19 have been completely restructured, for NanoMQ 0.19 or higher versions, see Configuration Parameters - v019.

Basic Configuration

Name	Type	Description
system.daemon	Boolean	Launch with daemon (default: false)
system.num_taskq_thread	Integer	Number of taskq threads used.
system.max_taskq_thread	Integer	Maximum number of taskq threads used.
system.parallel	Long	Number of parallel threads.
mqtt.session.property_size	Integer	Max size for a MQTT property.
mqtt.session.msq_len	Integer	Queue length for resending messages.
mqtt.session.qos_duration	Integer	The interval of the qos timer.
mqtt.session.allow_anonymous	Boolean	Allow anonymous login.
mqtt.session.max_packet_size	Kbytes	The max packet size of NanoMQ (Kbytes)
mqtt.session.client_max_packet_size	Kbytes	The default max packet size of each client
mqtt.session.keepalive_backoff	Integer	The backoff for MQTT keepalive timeout.
listeners.tcp.enable	Boolean	Enable TCP listener(default: true).
listeners.tcp.bind	String	Url of listener.
listeners.ssl.enable	Boolean	Enable ssl listener(default: false).
listeners.ssl.bind	String	URL of ssl listener.
listeners.ssl.key	String	User's private PEM-encoded key.
listeners.ssl.keypass	String	String containing the user's password. Only used if the private keyfile is password-protected.
listeners.ssl.cert	String	User certificate data.
listeners.ssl.cacert	String	User's PEM-encoded CA certificates.
listeners.ssl.verify_peer	Boolean	Verify peer certificate.
listeners.ssl.fail_if_no_peer_cert	Boolean	Server will fail if the client does not have a certificate to send.
listeners.ws.enable	Boolean	Enable websocket listener(default: true).
listeners.ws.bind	String	URL of websocket listener.
listeners.wss.bind	String	URL of websocket over tls listener.
http_server.enable	Boolean	Enable http server listerner (default: false).
http_server.port	Integer	Port of http server.
http_server.username	String	User name of http server.
http_server.password	String	Password of http server.
http_server.auth_type	String	Http server authentication type (default: basic).
http_server.jwt.public.keyfile	String	public key file for JWT.
http_server.jwt.private.keyfile	String	private key file for JWT.
log.to	Array[String]	Array of log types，( Use commas , to separate multiple types ) Log types: file, console, syslog
log.level	String	Log level：trace, debug, info, warn, error, fatal
log.dir	String	The dir for log files. (if log to file)
log.file	String	The log filename. (if log to file)
log.rotation.size	String	Maximum size of each log file; Supported Unit: `KB
log.rotation.count	Integer	Maximum rotation count of log files; Default: 5

MQTT bridge configuration

Name	Type	Description
bridges.mqtt.nodes[0].name	String	Node name
bridges.mqtt.nodes[0].enable	Boolean	Enter MQTT bridge mode (default false ).
bridges.mqtt.nodes[0].connector.server	String	Remote Broker address.
bridges.mqtt.nodes[0].connector.proto_ver	Boolean	MQTT client version（3｜4｜5）.
bridges.mqtt.nodes[0].connector.clientid	String	MQTT client identifier.
bridges.mqtt.nodes[0].connector.keepalive	Integer	Interval of keepalive.
bridges.mqtt.nodes[0].connector.clean_start	Boolean	Clean session.
bridges.mqtt.nodes[0].connector.username	String	Login user name.
bridges.mqtt.nodes[0].connector.password	String	Login password.
bridges.mqtt.nodes[0].connector.conn_properties	Object	MQTT V5 Property of Connector (see table below)
bridges.mqtt.nodes[0].connector.ssl.enable	Boolean	Launch TLS （ default false）。
bridges.mqtt.nodes[0].connector.ssl.key_password	String	String containing the user's password. only used if the private keyfile is password-protected.
bridges.mqtt.nodes[0].connector.ssl.keyfile	String	User's private PEM-encoded key.
bridges.mqtt.nodes[0].connector.ssl.certfile	String	User certificate data.
bridges.mqtt.nodes[0].connector.ssl.cacertfile	String	User's PEM-encoded CA certificates.
bridges.mqtt.nodes[0].quic_keepalive	Duration	Interval of a sending keepalive packet via QUIC transport., （default 120s )
bridges.mqtt.nodes[0].quic_idle_timeout	Duration	How long a connection can go idle before it is gracefully shut down. 0 to disable timeout, which may lost disconnect event msg. （default 120s )
bridges.mqtt.nodes[0].quic_discon_timeout	Duration	How long to wait for an ACK before declaring a path dead and disconnecting, This affects stream living time.（default 20s )
bridges.mqtt.nodes[0].quic_handshake_timeout	Duration	The Max time NanoMQ waits for establishing QUIC connection（default 60s )
bridges.mqtt.nodes[0].hybrid_bridging	Boolean	Hybrid bridging: enable or disable the hybrid bridging mode，(default: false), recommend to enable it when you want to take advantage of QUIC
bridges.mqtt.nodes[0].quic_send_idle_timeout	Duration	Reset congestion control after being idle SendIdleTimeout (default 60s)
bridges.mqtt.nodes[0].quic_initial_rtt_ms	Duration	Initial RTT estimate. (ms) (default: 800ms)
bridges.mqtt.nodes[0].quic_max_ack_delay_ms	Duration	How long to wait after receiving data before sending an ACK. (default: 100ms)
bridges.mqtt.nodes[0].quic_qos_priority	Boolean	Send QoS 1/2 msg in high prority. (default: true)
bridges.mqtt.nodes[0].quic_0rtt	Boolean	0RTT is a feature of QUIC to re-establish connection quickly. . （default: true）
bridges.mqtt.nodes[0].multi_stream	Boolean	Multiple stream option，（default false）
bridges.mqtt.nodes[0].parallel	Long	Parallel of mqtt client.
bridges.mqtt.nodes[0].forwards	Array[String]	Array of forward topics.( Use commas , to separate multiple topics )
bridges.mqtt.nodes[0].subscription[0].topic	String	First Topic.
bridges.mqtt.nodes[0].subscription[0].qos	Integer	First Qos.
bridges.mqtt.nodes[0].sub_properties	Object	MQTT V5 Property of Subscription (see table below)
bridges.mqtt.nodes[0].max_send_queue_len	Integer	Maximum number of message send queue length
bridges.mqtt.nodes[0].max_recv_queue_len	Integer	Maximum number of message receive queue length

MQTT V5 Property

Connectorproperty: bridges.mqtt.nodes[0].connector.conn_properties

Name	Type	Description
maximum_packet_size	Integer	Maximum Packet Size Value: 1 ~ 4294967295
receive_maximum	Integer	Receive Maximum Value: 1 ~ 65535
topic_alias_maximum	Integer	Topic Alias Maximum Value: 0 ~ 65535
request_problem_infomation	Integer	Request Problem Information Default: 1 Value: 0 | 1
request_response_infomation	Integer	Request Response Information Default: 0 Value: 0 | 1
session_expiry_interval	Integer	Session Expiry Interval Value: 0 ~ 4294967295
user_property	Map[String, String]	User Property Value: Map[key(String) - value(String)]

Subscription property : bridges.mqtt.nodes[0].sub_properties

Name	Type	Description
identifier	Integer	Subscription Identifier Value: 1 ~ 268,435,455
user_property	Map[String, String]	User Property Value: Map[key(String) - value(String)]

AWS IoT Core bridge configuration

Name	Type	Description
bridge.aws.nodes[0].name	String	Node name
bridge.aws.nodes[0].enable	Boolean	Enter MQTT bridge mode (default false ).
bridge.aws.nodes[0].connector.server	String	AWS IoT Core URL (IP:PORT)。
bridge.aws.nodes[0].connector.clientid	String	MQTT client identifier.
bridge.aws.nodes[0].connector.keepalive	Duration	Interval of keepalive.
bridge.aws.nodes[0].connector.clean_start	Boolean	Clean session.
bridge.aws.nodes[0].connector.username	String	Login user name.
bridge.aws.nodes[0].connector.password	String	Login password.
bridge.aws.nodes[0]..connector.ssl.enable	Boolean	Launch TLS （ default false）。
bridge.aws.nodes[0]..connector.ssl.key_password	String	String containing the user's password. only used if the private keyfile is password-protected.
bridge.aws.nodes[0]..connector.ssl.keyfile	String	User's private PEM-encoded key.
bridge.aws.nodes[0]..connector.ssl.certfile	String	User certificate data.
bridge.aws.nodes[0]..connector.ssl.cacertfile	String	User's PEM-encoded CA certificates.
bridge.aws.nodes[0].parallel	Long	Parallel of mqtt client.
bridge.aws.nodes[0].forwards	Array[String]	Array of forward topics.( Use commas , to separate multiple topics )
bridge.aws.nodes[0].subscription[0].topic	String	First Topic.
bridge.aws.nodes[0].subscription[0].qos	Integer	First Qos.

Configure with WebHook

Only apply to classical KV-format config, before NanoMQ 0.18

WebHook configuration

Name	Type	Description
webhook.enable	Boolean	Enable WebHook (default: false)
webhook.url	String	Webhook URL
webhook.headers.<Any>	String	HTTP Headers Example: 1. webhook.headers.content-type=application/json 2. webhook.headers.accept=*
webhook.body.encoding	String	The encoding format of the payload field in the HTTP body Options: plain | base64 | base62
webhook.pool_size	Integer	Connection process pool size (default: 32).
webhook.rule.client.connack.<No>	String	Example: webhook.rule.client.connack=[{"action": "on_client_connack"}]
webhook.rule.client.disconnected.<No>	String	Example: webhook.rule.client.disconnected=[{"action": "on_client_disconnected"}]
webhook.rule.message.publish.<No>	String	Example: 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/#"}]

Enable Webhook

web.hook.enable=true

Trigger rule

Trigger rules can be configured in etc/nanomq.conf. The configuration format is as follows:

## Format example
web.hook.rule.<Event>.<Number>=<Rule>

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

Trigger event

The following events are currently supported:

Name	Description	Execution timing
client.connack	Issue connection acknowledge	When the server is ready to send connack packet
client.disconnected	disconnected	When the client connection layer is about to close
message.publish	message published	Before the server rpublishes (routes) the message

Number

Multiple trigger rules can be configured for the same event, and events with the same configuration should be incremented in sequence.

Rule

The trigger rule's 'value is a JSON string, and the available Keys are:

• action: string, taking a fixed value
• topic: a string, indicating a topic filter, the operation topic can only trigger the forwarding of the event if it matches the topic

For example, we only forward messages matching the topics of a/b/c and foo/# to the web server, and the configuration should be:

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

In this way, Webhook will only forward messages matching the topics of a/b/c and foo/#, such as foo/bar, etc., instead of forwarding a/b/d or fo/bar

Webhook event parameters

When the event is triggered, Webhook will group each event into an HTTP request and sent it to the web server configured by url according to the configuration. The request format is:

URL: <url>      # From the url field in the configuration
Method: POST    # Fixed as POST method

Body: <JSON>    # Body is a JSON format string

For different events, the content of the request body is different. The following table lists the parameters of the body in each event:

client.connack

Key	Type	Description
action	string	event name fixed at: "client_connack"
clientid	string	client ClientId
username	string	client Username, When not existed, the value is "undefined"
keepalive	integer	Heartbeat keepalive time applied by client
proto_ver	integer	Protocol version number （3 ｜ 4 ｜ 5）
conn_ack	string	"success" means success, other means failure

client.disconnected

Key	Type	Description
action	string	event name fixed at: "client_disconnected"
clientid	string	client ClientId
username	string	client Username, When not existed, the value is "undefined"
reason	string	error reason

message.publish

Key	Type	Description
action	string	event name fixed at: "message_publish"
from_client_id	string	Publisher's ClientId
from_username	string	Publisher's Username, When not existed, the value is "undefined"
topic	string	Unsubscribed topic
qos	enum	QoS level, and the optional value is 0 1 2
retain	bool	Whether it is a Retain message
payload	string	Message Payload
ts	integer	Timestamp (second)

Authorization

The general config structure is the following:

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

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

Name	Type	Description
username	String	Username.
password	String	Password.

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

ACL configuration

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

Name	Type	Required	Description
permit	enum	Yes	permission: allow ,deny
action	enum	No	operation : publish, subscribe, pubsub
topics	Arrary[String]	No	Array of Topic
username	String	No	Username: "#" means all users
clientid	String	No	ClientID: "#" means all client IDs
and	Array[Object]	No	AND operator
or	Array[Object]	No	OR 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"}
        ]
      }
	]
	
}

Http authorication configuration

Name	Type	Description	default
auth_http.enable	Boolean	Enable HTTP authentication	false
auth_http.auth_req.url	String	Specify the target URL of the authentication request.	http://127.0.0.1:80/mqtt/auth
auth_http.auth_req.method	String	Specify the request method of the authentication request. (POST , GET)	POST
auth_http.auth_req.headers.<Any>	String	Specify 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.params	Array[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.url	String	Specify the target URL for the superuser authentication request.	http://127.0.0.1:80/mqtt/superuser
auth_http.super_req.method	String	Specifies the request method of the super user authentication request. (POST , GET)	POST
auth_http.super_req.headers.<Any>	String	Specify 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.params	Array[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.url	String	Specify the target URL for ACL verification requests.	http://127.0.0.1:8991/mqtt/acl
auth_http.acl_req.method	String	Specifies the request method for ACL verification requests. (POST , GET)	POST
auth_http.acl_req.headers.<Any>	String	Specify 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.params	Array[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.timeout	Integer	HTTP request timeout. Any setting equivalent to 0s means never timeout.	5s
auth_http.connect_timeout	Integer	Connection 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	
		]
}

Rule engine configuration

Name	Type	Description
rule.option	String	Rule engine option, when persistence with rule engine, this option is must be ON.

Rule configuration for sqlite

Name	Type	Description
rule.sqlite.path	String	Rule engine option SQLite3 database path, default is /tmp/rule_engine.db
rule.sqlite.enabled	Boolen	Rule engine option SQLite3 is enabled, default is true
rule.sqlite.rules[0].enabled	Boolen	Rule engine option rule is enbaled, default is true
rule.sqlite.rules[0].table	String	Rule engine option SQLite3 database table name
rule.sqlite.rules[0].sql	String	Rule engine sql clause

Rule configuration for mysql

Name	Type	Description
rule.mysql.name	String	Rule engine option mysql database name, default is mysql_rule_db
rule.mysql.enabled	Boolen	Rule engine option mysql is enabled, default is true
rule.mysql.rules[0].enabled	Boolen	Rule engine option rule is enbaled, default is true
rule.mysql.rules[0].table	String	Rule engine option mysql database table name
rule.mysql.rules[0].host	String	Rule engine option mysql database host
rule.mysql.rules[0].username	String	Rule engine option mysql database username
rule.mysql.rules[0].password	String	Rule engine option mysql database password
rule.mysql.rules[0].sql	String	Rule engine sql clause

Rule configuration for repub

Name	Type	Description
rule.repub.enabled	Boolen	Rule engine option repub is enabled, default is true
rule.repub.rules[0].enabled	Boolen	Rule engine option rule is enbaled, default is true
rule.repub.rules[0].address	String	Rule engine option repub address (mqtt-tcp://host:port)
rule.repub.rules[0].topic	String	Rule engine option repub topic
rule.repub.rules[0].username	String	Rule engine option repub username
rule.repub.rules[0].password	String	Rule engine option repub password
rule.repub.rules[0].proto_ver	Integer	Rule engine option repub protocol version, default is 4
rule.repub.rules[0].clientid	String	Rule engine option repub clientid
rule.repub.rules[0].keepalive	Duration	Rule engine option repub keepalive
rule.repub.rules[0].clean_start	Boolean	Rule engine option repub clean_start flag, default is true
rule.repub.rules[0].sql	String	Rule engine sql clause