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.ip_addr | String | IP address 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
Connector
property: 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 istrue
. 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 is1m
. 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 |