Skip to content


NanoMQ has incorporated HOCON syntax support since version 0.14. However, there have been syntax updates introduced in version 0.19. For this reason, users of NanoMQ versions 0.14 to 0.18 should consult the NanoMQ 0.14-0.18 Configuration Guide for specifics on the appropriate syntax.

While NanoMQ continues to support the traditional Key-Value (KV) configuration syntax, it's important to note that some new features will only be compatible with the HOCON configuration format. For details on the KV syntax, please refer to the Classic KV Format Configuration Guide.

The focus of this chapter is to provide guidance on configuring NanoMQ using the updated HOCON syntax.


NanoMQ's default configuration file format is HOCON. HOCON (Human-Optimized Config Object Notation) is a superset of JSON, making it ideal for storing configuration data in a human-readable format. You can find these configuration files in the etc directory. Peripheral functions such as authentication/gateways can use separate configuration files (specified by the include method). The main configuration files include:

Configuration FileDescription
etc/nanomq.confMain NanoMQ configuration file
etc/nanomq_pwd.confNanoMQ username and password auth config
etc/nanomq_acl.confNanoMQ ACL access control auth config
etc/nanomq_vsomeip_gateway.confNanoMQ SOME/IP gateway config (for nanomq_cli)
etc/nanomq_dds_gateway.confNanoMQ DDS gateway config (for nanomq_cli)
etc/nanomq_bridge.confNanoMQ bridge config (for nanomq_cli)
etc/nanomq_zmq_gateway.confNanoMQ ZeroMQ config (for nanomq_cli)

The below sections are based on the HOCON configuration format.


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

log {
    dir = "/tmp"
    file = "nanomq.log"

Another equivalent representation is flat, such as

log.dir = "/tmp"
log.file = "nanomq.log"

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

It is not fully compatible because 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 =,HOCON:websocket.bind = "".

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 {

## ... more configs ...