Configuration

Why this matters

EMQX parameters are scattered across several places: the ones you adjust dynamically in the Dashboard, the ones tucked away in a config file, and the ones you override with an environment variable. In a home setup it is easy to write the same setting into two different layers by accident, and then find that your change does nothing and you are not sure which layer won.

This chapter sets out how EMQX configuration fits together. It starts with the Dashboard's Management module, then covers the precedence between the config files (emqx.conf, HOCON) and EMQX_ environment variables, and ends with secrets and the add-on's env_vars. After that you will not have to guess where a setting belongs.

Core concepts

EMQX splits its configuration into two kinds of directory: static and dynamic.

• Static configuration, etc: usually read-only, and it lives in the main config file (emqx.conf, for example). You mostly change it at deployment or upgrade time.
• Dynamic configuration, data/configs: writable. Changes you make from the Dashboard, the REST API or the CLI are saved into cluster.hocon.

Precedence, lowest to highest, is base.hocon (only there from 5.8.4 on) < cluster.hocon < emqx.conf < environment variables. In other words, the further along that chain, the higher it wins.

The Dashboard's Management module is the way in to dynamic changes: Cluster Settings, MQTT Settings, Logging and Monitoring can all be applied while EMQX is running, with no restart.

Terms at a glance

Hands-on

1. Open Cluster Settings to see the dynamic settings

   In the sidebar, choose Management → Cluster Settings. This is where you adjust MQTT, Listener and Logging settings, and they take effect as soon as you save.

2. Add an environment variable through the add-on's env_vars

   Home Assistant → the EMQX add-on in the sidebar → Configuration. Fill in name and value under env_vars. The add-on accepts only variable names that start with EMQX_, and remember to restart it once you have made the change.

3. Override one default with an environment variable

   To change the node name, for example, use EMQX_NODE__NAME (the double underscore stands for one level of the configuration). Save, restart the add-on, then read the value back in the Dashboard.

4. If you do need the static config file

   The add-on's data directory holds /data/emqx/etc/emqx.conf. Do not edit it by hand unless you have to, because everything the Dashboard writes lands in cluster.hocon.

Config files: HOCON and precedence

From EMQX 5.0 on, configuration is written in HOCON (a superset of JSON, so you can use nested objects or flat paths).

node {
  name = "[email protected]"
  cookie = "<your-cookie>"
}

The flat form works too: node.name = "[email protected]".

The real precedence order is easy to muddle if you have not committed it to memory. The two rules are that later wins and the higher layer wins: base.hocon is the weakest, environment variables the strongest. If a dynamic change of yours went into cluster.hocon but the same item is also set in emqx.conf or in an environment variable, it can be changed back after a restart.

Recommended: do not set the same item in both emqx.conf and cluster.hocon, or the value will snap back to one of the two after a restart.

EMQX_ environment variables and the add-on's env_vars

The rules for converting between a config file and an environment variable:

• A config file separates levels with a dot (.); an environment variable uses a double underscore (__).
• Variable names always start with EMQX_.
• The value is parsed as HOCON, so you can pass complex types.

In config.yaml, the Woow EMQX add-on defines the env_vars option. For example:

env_vars:
  - name: EMQX_NODE__NAME
    value: "[email protected]"
  - name: EMQX_LISTENERS__TCP__DEFAULT__MAX_CONNECTIONS
    value: "1000000"

It takes effect only after you save and restart the add-on.

Managing secrets: avoid the HOCON comment trap

EMQX configuration has a "Secret" type, used for sensitive values such as passwords and tokens. Whenever you write down what goes into an add-on or Dashboard field, use a placeholder (<your-password>, for example) in place of the real value, and never the actual secret.

One common trap: in HOCON, `#` starts a comment. If a password contains # — say MQtt#123 — and it is not quoted, the parser reads it as MQtt and throws `#123` away as a comment. Wrap it in HOCON-level double quotes to keep the whole literal value:

export EMQX_DASHBOARD__DEFAULT_PASSWORD='"MQtt#123"'

Do the same for values containing : or =. URL encoding (such as %23) does not apply here — EMQX does not decode URL encoding in environment variables.

Troubleshooting

• A setting you changed is back to what it was after a restart: usually emqx.conf or an environment variable has the higher precedence. Move the value you want up a layer (to an environment variable, say) and pin it there.
• env_vars has no effect: first check that the variable name starts with EMQX_ and uses a double underscore (__), and restart the add-on after saving. A misspelled name shows up as a warning in the startup log.
• A password containing # gets truncated: HOCON treats # as a comment. Store the whole thing wrapped in an extra pair of double quotes (quotes included) rather than pasting the raw value.
• You cannot find the setting you want to change: work out first whether the Dashboard can change it dynamically or whether it is a static item in a config file. Use Management for the first; go to emqx.conf or an environment variable for the second.

FAQ

Official sources

• EMQX 5.8 configuration files and environment variables (pinned docs branch)
• EMQX 5.8 Management dynamic configuration (pinned docs branch)
• Woow EMQX add-on README (pinned commit)
• Woow EMQX add-on config.yaml (env_vars)