Configuration

HOCON

EMQX Edge uses Human-Optimized Config Object Notation (HOCON) as its default configuration file format. HOCON is a superset of JSON, designed to be more human-friendly and easier to read and write, making it ideal for managing configuration data.

All main configuration files are located in the etc directory. In addition to the primary configuration file, EMQX Edge supports modular configuration through the include directive, allowing you to separate settings for specific features such as authentication.

The main configuration files include:

Configuration File	Description
etc/nanomq.conf	Core EMQX Edge configuration
etc/nanomq_pwd.conf	Username and password authentication settings
etc/nanomq_acl.conf	Access control (ACL) settings
etc/nanomq_bridge.conf	MQTT bridge configuration (used with nanomq_cli)

The sections below reference configuration syntax and examples using the HOCON format.

Syntax

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.

For example, cuttlefish：websocket.bind = 0.0.0.0:8083/mqtt，HOCON：websocket.bind = "0.0.0.0:8083/mqtt".

Configuration Overlay Rules

In HOCON, configuration objects are overlaid, meaning that later definitions can override earlier ones. This overlay behavior follows two main principles:

• Within one file, when the same object is defined multiple times, later definitions recursively override earlier ones.
• In layered configurations, objects from higher-priority layers override those in lower-priority layers.

Example

In the example below, the log.level=debug line appears after the initial log object definition. This causes the level field in the log object to be updated from error to debug, while the to field remains unchanged:

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

## ... more configs ...

log.level=debug

As a result, the final merged log configuration is:

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

This behavior allows fine-grained overrides without repeating the entire configuration structure.

Attention: The configuration method of the conf file no longer includes the "enable" option. Any configuration that appears in the configuration file is enabled by default.