Skip to content

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

NameTypeDescription
system.daemonBooleanLaunch with daemon (default: false)
system.num_taskq_threadIntegerNumber of taskq threads used.
system.max_taskq_threadIntegerMaximum number of taskq threads used.
system.parallelLongNumber of parallel threads.
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.
listeners.wss.bindStringURL of websocket over tls listener.
http_server.enableBooleanEnable http server listerner (default: false).
http_server.portIntegerPort of http server.
http_server.usernameStringUser name of http server.
http_server.ip_addrStringIP address 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
log.rotation.countIntegerMaximum rotation count of log files;
Default: 5

MQTT bridge configuration

NameTypeDescription
bridges.mqtt.nodes[0].nameStringNode name
bridges.mqtt.nodes[0].enableBooleanEnter MQTT bridge mode (default false ).
bridges.mqtt.nodes[0].connector.serverStringRemote Broker address.
bridges.mqtt.nodes[0].connector.proto_verBooleanMQTT client version(3|4|5).
bridges.mqtt.nodes[0].connector.clientidStringMQTT client identifier.
bridges.mqtt.nodes[0].connector.keepaliveIntegerInterval of keepalive.
bridges.mqtt.nodes[0].connector.clean_startBooleanClean session.
bridges.mqtt.nodes[0].connector.usernameStringLogin user name.
bridges.mqtt.nodes[0].connector.passwordStringLogin password.
bridges.mqtt.nodes[0].connector.conn_propertiesObjectMQTT V5 Property of Connector (see table below)
bridges.mqtt.nodes[0].connector.ssl.enableBooleanLaunch TLS ( default false)。
bridges.mqtt.nodes[0].connector.ssl.key_passwordStringString containing the user's password. only used if the private keyfile is password-protected.
bridges.mqtt.nodes[0].connector.ssl.keyfileStringUser's private PEM-encoded key.
bridges.mqtt.nodes[0].connector.ssl.certfileStringUser certificate data.
bridges.mqtt.nodes[0].connector.ssl.cacertfileStringUser's PEM-encoded CA certificates.
bridges.mqtt.nodes[0].quic_keepaliveDurationInterval of a sending keepalive packet via QUIC transport., (default 120s )
bridges.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 )
bridges.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 )
bridges.mqtt.nodes[0].quic_handshake_timeoutDurationThe Max time NanoMQ waits for establishing QUIC connection(default 60s )
bridges.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
bridges.mqtt.nodes[0].quic_send_idle_timeoutDurationReset congestion control after being idle SendIdleTimeout (default 60s)
bridges.mqtt.nodes[0].quic_initial_rtt_msDurationInitial RTT estimate. (ms)
(default: 800ms)
bridges.mqtt.nodes[0].quic_max_ack_delay_msDurationHow long to wait after receiving data before sending an ACK. (default: 100ms)
bridges.mqtt.nodes[0].quic_qos_priorityBooleanSend QoS 1/2 msg in high prority. (default: true)
bridges.mqtt.nodes[0].quic_0rttBoolean0RTT is a feature of QUIC to re-establish connection quickly. . (default: true
bridges.mqtt.nodes[0].multi_streamBooleanMultiple stream option,(default false
bridges.mqtt.nodes[0].parallelLongParallel of mqtt client.
bridges.mqtt.nodes[0].forwardsArray[String]Array of forward topics.( Use commas , to separate multiple topics )
bridges.mqtt.nodes[0].subscription[0].topicStringFirst Topic.
bridges.mqtt.nodes[0].subscription[0].qosIntegerFirst Qos.
bridges.mqtt.nodes[0].sub_propertiesObjectMQTT V5 Property of Subscription (see table below)
bridges.mqtt.nodes[0].max_send_queue_lenIntegerMaximum number of message send queue length
bridges.mqtt.nodes[0].max_recv_queue_lenIntegerMaximum number of message receive queue length

MQTT V5 Property

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

NameTypeDescription
maximum_packet_sizeIntegerMaximum Packet Size
Value: 1 ~ 4294967295
receive_maximumIntegerReceive Maximum
Value: 1 ~ 65535
topic_alias_maximumIntegerTopic Alias Maximum
Value: 0 ~ 65535
request_problem_infomationIntegerRequest Problem Information
Default: 1
Value: 0 | 1
request_response_infomationIntegerRequest Response Information
Default: 0
Value: 0 | 1
session_expiry_intervalIntegerSession Expiry Interval
Value: 0 ~ 4294967295
user_propertyMap[String, String]User Property
Value: Map[key(String) - value(String)]

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

NameTypeDescription
identifierIntegerSubscription Identifier
Value: 1 ~ 268,435,455
user_propertyMap[String, String]User Property
Value: Map[key(String) - value(String)]

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]..connector.ssl.enableBooleanLaunch TLS ( default false)。
bridge.aws.nodes[0]..connector.ssl.key_passwordStringString containing the user's password. only used if the private keyfile is password-protected.
bridge.aws.nodes[0]..connector.ssl.keyfileStringUser's private PEM-encoded key.
bridge.aws.nodes[0]..connector.ssl.certfileStringUser certificate data.
bridge.aws.nodes[0]..connector.ssl.cacertfileStringUser's PEM-encoded CA certificates.
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.

Configure with WebHook

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

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

Enable Webhook

bash
web.hook.enable=true

Trigger rule

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

bash
## 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:

NameDescriptionExecution timing
client.connackIssue connection acknowledgeWhen the server is ready to send connack packet
client.disconnecteddisconnectedWhen the client connection layer is about to close
message.publishmessage publishedBefore 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:

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

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:

bash
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

KeyTypeDescription
actionstringevent name
fixed at: "client_connack"
clientidstringclient ClientId
usernamestringclient Username, When not existed, the value is "undefined"
keepaliveintegerHeartbeat keepalive time applied by client
proto_verintegerProtocol version number (3 | 4 | 5)
conn_ackstring"success" means success, other means failure

client.disconnected

KeyTypeDescription
actionstringevent name
fixed at: "client_disconnected"
clientidstringclient ClientId
usernamestringclient Username, When not existed, the value is "undefined"
reasonstringerror reason

message.publish

KeyTypeDescription
actionstringevent name
fixed at: "message_publish"
from_client_idstringPublisher's ClientId
from_usernamestringPublisher's Username, When not existed, the value is "undefined"
topicstringUnsubscribed topic
qosenumQoS level, and the optional value is 0 1 2
retainboolWhether it is a Retain message
payloadstringMessage Payload
tsintegerTimestamp (second)

Authorization

The general config structure is the following:

bash
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

NameTypeDescription
usernameStringUsername.
passwordStringPassword.

Example:

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 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:

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 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 :

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