# Configuration File

EMQX configuration file is in HOCON (opens new window) format. HOCON, or Human-Optimized Config Object Notation is a format for human-readable data, and a superset of JSON.

# Layered

EMQX configuration consists of 3 layers. From bottom up:

  1. Immutable base: emqx.conf + EMQX_ prefixed environment variables.
    Changes in this layer require a full node restart to take effect.
  2. Cluster overrides: $EMQX_NODE__DATA_DIR/configs/cluster-override.conf
  3. Local node overrides: $EMQX_NODE__DATA_DIR/configs/local-override.conf

When environment variable $EMQX_NODE__DATA_DIR is not set, config node.data_dir is used.

The cluster-override.conf file is overwritten at runtime when changes are made from dashboard UI, management HTTP API, or CLI. When clustered, after EMQX restarts, it copies the file from the node which has the greatest uptime.

Tip

Some of the configs (such as node.name) are boot-only configs and not overridable. Config values from *-override.conf are not mapped to boot configs for the config fields attributed with mapping: path.to.boot.config.key

For detailed override rules, see Config Overlay Rules.

# Syntax

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

node {
    name = "emqx@127.0.0.1"
    cookie = "mysecret"
}
1
2
3
4

Another equivalent representation is flat, such as

node.name = "127.0.0.1"
node.cookie = "mysecret"
1
2

This flat format is almost backward compatible with EMQX's config file format in 4.x series (the so called 'cuttlefish' format).

It is not fully compatible because the often HOCON requires strings to be quoted, while cuttlefish treats all characters to the right of the = mark as the value.

e.g. cuttlefish: node.name = emqx@127.0.0.1, HOCON: node.name = "emqx@127.0.0.1".

Strings without special characters in them can be unquoted in HOCON too, e.g. foo, foo_bar and foo_bar_1.

For more HOCON syntax, please refer to the specification (opens new window)

# Schema

To make the HOCON objects type-safe, EMQX introduced a schema for it. The schema defines data types, and data fields' names and metadata for config value validation and more.

Tip

The configuration document you are reading now is generated from schema metadata.

# Complex Data Types

There are 4 complex data types in EMQX's HOCON config:

  1. Struct: Named using an unquoted string, followed by a predefined list of fields. Only lowercase letters and digits are allowed in struct and field names. Alos, only underscore can be used as word separator.
  2. Map: Map is like Struct, however the fields are not predefined.
  3. Union: MemberType1 | MemberType2 | ...
  4. Array: [ElementType]

Tip

If map filed name is a positive integer number, it is interpreted as an alternative representation of an Array. For example:

myarray.1 = 74
myarray.2 = 75
1
2

will be interpreated as myarray = [74, 75], which is handy when trying to override array elements.

# Primitive Data Types

Complex types define data 'boxes' which may contain other complex data or primitive values. There are quite some different primitive types, to name a few:

  • atom()
  • boolean()
  • string()
  • integer()
  • float()
  • number()
  • binary() # another format of string()
  • emqx_schema:duration() # time duration, another format of integer()
  • ...

Tip

The primitive types are mostly self-describing, so there is usually not a lot to document. For types that are not so clear by their names, the field description is to be used to find the details.

# Config Paths

If we consider the whole EMQX config as a tree, to reference a primitive value, we can use a dot-separated names form string for the path from the tree-root (always a Struct) down to the primitive values at tree-leaves.

Each segment of the dotted string is a Struct filed name or Map key. For Array elements, 1-based index is used.

below are some examples

node.name = "emqx.127.0.0.1"
zone.zone1.max_packet_size = "10M"
authentication.1.enable = true
1
2
3

# Environment variables

Environment variables can be used to define or override config values.

Due to the fact that dots (.) are not allowed in environment variables, dots are replaced with double-underscores (__).

And the EMQX_ prefix is used as the namespace.

For example node.name can be represented as EMQX_NODE__NAME

Environment variable values are parsed as HOCON values, this allows users to even set complex values from environment variables.

For example, this environment variable sets an array value.

export EMQX_LISTENERS__SSL__L1__AUTHENTICATION__SSL__CIPHERS="[\"TLS_AES_256_GCM_SHA384\"]"
1

Tip

Unknown root paths are silently discarded by EMQX, for example EMQX_UNKNOWN_ROOT__FOOBAR is silently discarded because unknown_root is not a predefined root path.

Unknown field names in environment variables are logged as a warning level log, for example:

[warning] unknown_env_vars: ["EMQX_AUTHENTICATION__ENABLED"]
1

because the field name is enable, not enabled.

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

# Struct Fields

Later config values overwrites earlier values. For example, in below config, the last line debug overwrites error for console log handler's level config, but leaving enable unchanged.

log {
    console_handler{
        enable=true,
        level=error
    }
}

## ... more configs ...

log.console_handler.level=debug
1
2
3
4
5
6
7
8
9
10

# Map Values

Maps are like structs, only the files are user-defined rather than the config schema. For instance, zone1 in the example below.

zone {
    zone1 {
        mqtt.max_packet_size = 1M
    }
}

## The maximum packet size can be defined as above,
## then overridden as below

zone.zone1.mqtt.max_packet_size = 10M
1
2
3
4
5
6
7
8
9
10

# Array Elements

Arrays in EMQX config have two different representations

  • list, such as: [1, 2, 3]
  • indexed-map, such as: {"1"=1, "2"=2, "3"=3}

Dot-separated paths with number in it are parsed to indexed-maps e.g. authentication.1={...} is parsed as authentication={"1": {...}}

This feature makes it easy to override array elment values. For example:

authentication=[{enable=true, backend="built_in_database", mechanism="password_based"}]
# we can disable this authentication provider with:
authentication.1.enable=false
1
2
3

Warning

List arrays is a full-array override, but not a recursive merge, into indexed-map arrays. e.g.

authentication=[{enable=true, backend="built_in_database", mechanism="password_based"}]
## below value will replace the whole array, but not to override just one field.
authentication=[{enable=true}]
1
2
3

# Root Config Keys

Fields

# authz:file

Authorization using a static file.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: file

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • path: string()

    Path to the file which contains the ACL rules. If the file provisioned before starting EMQX node, it can be placed anywhere as long as EMQX has read access to it. That is, EMQX will treat it as read only.

    In case the rule-set is created or updated from EMQX Dashboard or HTTP API, a new file will be created and placed in authz subdirectory inside EMQX's data_dir, and the old file will not be used anymore.

# authz:http_get

Authorization using an external HTTP server (via GET requests).

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: http

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • url: binary()

    URL of the auth server.

  • request_timeout: string()

    • default: "30s"

    HTTP request timeout.

  • body: map()

    HTTP request body.

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    The timeout when connecting to the HTTP server.

  • enable_pipelining: pos_integer()

    • default: 100

    A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

  • max_retries: non_neg_integer()

    • default: 5

    Max retry times if error on sending request.

  • pool_size: pos_integer()

    • default: 8

    The pool size.

  • request: connector-http:request

    If the request is provided, the caller can send HTTP requests via emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    Interval between retries.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • method: get

    • default: get

    HTTP method.

  • headers: [{binary(), binary()}]

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6

    List of HTTP headers (without content-type).

# authz:http_post

Authorization using an external HTTP server (via POST requests).

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: http

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • url: binary()

    URL of the auth server.

  • request_timeout: string()

    • default: "30s"

    HTTP request timeout.

  • body: map()

    HTTP request body.

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    The timeout when connecting to the HTTP server.

  • enable_pipelining: pos_integer()

    • default: 100

    A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

  • max_retries: non_neg_integer()

    • default: 5

    Max retry times if error on sending request.

  • pool_size: pos_integer()

    • default: 8

    The pool size.

  • request: connector-http:request

    If the request is provided, the caller can send HTTP requests via emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    Interval between retries.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • method: post

    • default: post

    HTTP method.

  • headers: [{binary(), binary()}]

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "content-type" = "application/json"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6
    7

    List of HTTP Headers.

# authz:mnesia

Authorization using a built-in database (mnesia).

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: built_in_database

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

# authz:mongo_rs

Authorization using a MongoDB replica set.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mongodb

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • collection: atom()

    MongoDB collection containing the authorization data.

  • filter: map()

    • default: {}

    Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
  • mongo_type: rs

    • default: rs

    Replica set.

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • w_mode: unsafe | safe

    • default: unsafe

    Write mode.

  • r_mode: master | slave_ok

    • default: master

    Read mode.

  • replica_set_name: binary()

    Name of the replica set.

  • srv_record: boolean()

    • default: false

    Use DNS SRV record.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auth_source: binary()

    Database name associated with the user's credentials.

  • database: binary()

    Database name.

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authz:mongo_sharded

Authorization using a sharded MongoDB cluster.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mongodb

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • collection: atom()

    MongoDB collection containing the authorization data.

  • filter: map()

    • default: {}

    Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
  • mongo_type: sharded

    • default: sharded

    Sharded cluster.

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • w_mode: unsafe | safe

    • default: unsafe

    Write mode.

  • srv_record: boolean()

    • default: false

    Use DNS SRV record.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auth_source: binary()

    Database name associated with the user's credentials.

  • database: binary()

    Database name.

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authz:mongo_single

Authorization using a single MongoDB instance.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mongodb

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • collection: atom()

    MongoDB collection containing the authorization data.

  • filter: map()

    • default: {}

    Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
  • mongo_type: single

    • default: single

    Standalone instance.

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The MongoDB default port 27017 is used if [:Port] is not specified.

  • w_mode: unsafe | safe

    • default: unsafe

    Write mode.

  • srv_record: boolean()

    • default: false

    Use DNS SRV record.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auth_source: binary()

    Database name associated with the user's credentials.

  • database: binary()

    Database name.

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authz:mysql

Authorization using a MySQL database.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: mysql

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The MySQL default port 3306 is used if [:Port] is not specified.

  • database: binary()

    Database name.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • prepare_statement: map()

    Key-value list of SQL prepared statements.

  • query: binary()

    Database query used to retrieve authorization data.

# authz:postgresql

Authorization using a PostgreSQL database.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: postgresql

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The PostgreSQL default port 5432 is used if [:Port] is not specified.

  • database: binary()

    Database name.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • prepare_statement: map()

    Key-value list of SQL prepared statements.

  • query: binary()

    Database query used to retrieve authorization data.

# authz:redis_cluster

Authorization using a Redis cluster.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: redis

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • redis_type: cluster

    Cluster mode

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • password: binary()

    EMQX's password in the external database.

  • database: integer()

    • default: 0

    Redis database ID.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • cmd: binary()

    Database query used to retrieve authorization data.

# authz:redis_sentinel

Authorization using a Redis Sentinel.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: redis

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • redis_type: sentinel

    Sentinel mode

  • sentinel: string()

    The cluster name in Redis sentinel mode.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • password: binary()

    EMQX's password in the external database.

  • database: integer()

    • default: 0

    Redis database ID.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • cmd: binary()

    Database query used to retrieve authorization data.

# authz:redis_single

Authorization using a single Redis instance.

Config paths

  • authorization.sources.$INDEX

Env overrides

  • EMQX_AUTHORIZATION__SOURCES__$INDEX

Fields

  • type: redis

    Backend type.

  • enable: boolean()

    • default: true

    Set to true or false to disable this ACL provider

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The Redis default port 6379 is used if [:Port] is not specified.

  • redis_type: single

    Single mode

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • password: binary()

    EMQX's password in the external database.

  • database: integer()

    • default: 0

    Redis database ID.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • cmd: binary()

    Database query used to retrieve authorization data.

# broker:alarm

Settings for the alarms.

Config paths

  • alarm

Env overrides

  • EMQX_ALARM

Fields

  • actions: [atom()]

    • default: [log, publish]

    The actions triggered when the alarm is activated.
    Currently, the following actions are supported: log and publish. log is to write the alarm to log (console or file). publish is to publish the alarm as an MQTT message to the system topics: $SYS/brokers/emqx@xx.xx.xx.x/alarms/activate and $SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivate

  • size_limit: 1..3000

    • default: 1000

    The maximum total number of deactivated alarms to keep as history.
    When this limit is exceeded, the oldest deactivated alarms are deleted to cap the total number.

  • validity_period: emqx_schema:duration()

    • default: "24h"

    Retention time of deactivated alarms. Alarms are not deleted immediately when deactivated, but after the retention time.

# broker

Message broker options.

Config paths

  • broker

Env overrides

  • EMQX_BROKER

Fields

  • enable_session_registry: boolean()

    • default: true

    Enable session registry

  • session_locking_strategy: local | leader | quorum | all

    • default: quorum

    Session locking strategy in a cluster.

    • local: only lock the session on the current node
    • one: select only one remote node to lock the session
    • quorum: select some nodes to lock the session
    • all: lock the session on all the nodes in the cluster
  • shared_subscription_strategy: random | round_robin | sticky | local | hash_topic | hash_clientid

    • default: round_robin

    Dispatch strategy for shared subscription.

    • random: dispatch the message to a random selected subscriber
    • round_robin: select the subscribers in a round-robin manner
    • sticky: always use the last selected subscriber to dispatch, until the subscriber disconnects.
    • hash: select the subscribers by the hash of clientIds
  • shared_dispatch_ack_enabled: boolean()

    • default: false

    Enable/disable shared dispatch acknowledgement for QoS 1 and QoS 2 messages. This should allow messages to be dispatched to a different subscriber in the group in case the picked (based on shared_subscription_strategy) subscriber is offline.

  • route_batch_clean: boolean()

    • default: true

    Enable batch clean for deleted routes.

  • perf: broker:broker_perf

  • shared_subscription_group: {$name -> broker:shared_subscription_group}

    Per group dispatch strategy for shared subscription. This config is a map from shared subscription group name to the strategy name. The group name should be of format [A-Za-z0-9]. i.e. no special characters are allowed.

# broker:broker_perf

Broker performance tuning parameters.

Config paths

  • broker.perf

Env overrides

  • EMQX_BROKER__PERF

Fields

  • route_lock_type: key | tab | global

    • default: key

    Performance tuning for subscribing/unsubscribing a wildcard topic. Change this parameter only when there are many wildcard topics.

    NOTE: when changing from/to global lock, it requires all nodes in the cluster to be stopped before the change.

    • key: mnesia transactional updates with per-key locks. Recommended for a single-node setup.
    • tab: mnesia transactional updates with table lock. Recommended for a cluster setup.
    • global: updates are protected with a global lock. Recommended for large clusters.
  • trie_compaction: boolean()

    • default: true

    Enable trie path compaction. Enabling it significantly improves wildcard topic subscribe rate, if wildcard topics have unique prefixes like: 'sensor//+/', where ID is unique per subscriber. Topic match performance (when publishing) may degrade if messages are mostly published to topics with large number of levels.

    NOTE: This is a cluster-wide configuration. It requires all nodes to be stopped before changing it.

# broker:cache

Settings for the authorization cache.

Config paths

  • authorization.cache

Env overrides

  • EMQX_AUTHORIZATION__CACHE

Fields

  • enable: boolean()

    • default: true

    Enable or disable the authorization cache.

  • max_size: 1..1048576

    • default: 32

    Maximum number of cached items.

  • ttl: emqx_schema:duration()

    • default: "1m"

    Time to live for the cached data.

# broker:conn_congestion

Settings for conn_congestion alarm.

Sometimes the MQTT connection (usually an MQTT subscriber) may get "congested", because there are too many packets to be sent. The socket tries to buffer the packets until the buffer is full. If more packets arrive after that, the packets will be "pending" in the queue, and we consider the connection congested.

Note: sndbuf can be set to larger value if the alarm is triggered too often. The name of the alarm is of format conn_congestion/<ClientID>/<Username>, where the <ClientID> is the client ID of the congested MQTT connection, and <Username> is the username or unknown_user.

Config paths

  • conn_congestion

Env overrides

  • EMQX_CONN_CONGESTION

Fields

  • enable_alarm: boolean()

    • default: true

    Enable or disable connection congestion alarm.

  • min_alarm_sustain_duration: emqx_schema:duration()

    • default: "1m"

    Minimal time before clearing the alarm.

    The alarm is cleared only when there's no pending data in the queue, and at least min_alarm_sustain_duration milliseconds passed since the last time we considered the connection "congested".

    This is to avoid clearing and raising the alarm again too often.

# broker:deflate_opts

Compression options.

Config paths

  • listeners.ws.$name.websocket.deflate_opts
  • listeners.wss.$name.websocket.deflate_opts

Env overrides

  • EMQX_LISTENERS__WS__$NAME__WEBSOCKET__DEFLATE_OPTS
  • EMQX_LISTENERS__WSS__$NAME__WEBSOCKET__DEFLATE_OPTS

Fields

  • level: none | default | best_compression | best_speed

    Compression level.

  • mem_level: 1..9

    • default: 8

    Specifies the size of the compression state.
    Lower values decrease memory usage per connection.

  • strategy: default | filtered | huffman_only | rle

    • default: default

    Specifies the compression strategy.

  • server_context_takeover: takeover | no_takeover

    • default: takeover

    Takeover means the compression state is retained between server messages.

  • client_context_takeover: takeover | no_takeover

    • default: takeover

    Takeover means the compression state is retained between client messages.

  • server_max_window_bits: 8..15

    • default: 15

    Specifies the size of the compression context for the server.

  • client_max_window_bits: 8..15

    • default: 15

    Specifies the size of the compression context for the client.

# broker:event_names

Enable or disable client lifecycle event publishing.

The following options affect MQTT clients as well as gateway clients. The types of the clients are distinguished by the topic prefix:

  • For the MQTT clients, the format is: $SYS/broker/<node>/clients/<clientid>/<event>
  • For the Gateway clients, it is $SYS/broker/<node>/gateway/<gateway-name>/clients/<clientid>/<event>

Config paths

  • sys_topics.sys_event_messages

Env overrides

  • EMQX_SYS_TOPICS__SYS_EVENT_MESSAGES

Fields

  • client_connected: boolean()

    • default: true

    Enable to publish client connected event messages

  • client_disconnected: boolean()

    • default: true

    Enable to publish client disconnected event messages.

  • client_subscribed: boolean()

    • default: false

    Enable to publish event message that client subscribed a topic successfully.

  • client_unsubscribed: boolean()

    • default: false

    Enable to publish event message that client unsubscribed a topic successfully.

# broker:flapping_detect

This config controls the allowed maximum number of CONNECT packets received from the same clientid in a time frame defined by window_time. After the limit is reached, successive CONNECT requests are forbidden (banned) until the end of the time period defined by ban_time.

Config paths

  • flapping_detect

Env overrides

  • EMQX_FLAPPING_DETECT

Fields

  • enable: boolean()

    • default: false

    Enable flapping connection detection feature.

  • max_count: integer()

    • default: 15

    The maximum number of disconnects allowed for a MQTT Client in window_time

  • window_time: emqx_schema:duration()

    • default: "1m"

    The time window for flapping detection.

  • ban_time: emqx_schema:duration()

    • default: "5m"

    How long the flapping clientid will be banned.

# broker:force_gc

Force garbage collection in MQTT connection process after they process certain number of messages or bytes of data.

Config paths

  • force_gc

Env overrides

  • EMQX_FORCE_GC

Fields

  • enable: boolean()

    • default: true

    Enable forced garbage collection.

  • count: 0..inf

    • default: 16000

    GC the process after this many received messages.

  • bytes: emqx_schema:bytesize()

    • default: "16MB"

    GC the process after specified number of bytes have passed through.

# broker:force_shutdown

When the process message queue length, or the memory bytes reaches a certain value, the process is forced to close.

Note: "message queue" here refers to the "message mailbox" of the Erlang process, not the mqueue of QoS 1 and QoS 2.

Config paths

  • force_shutdown

Env overrides

  • EMQX_FORCE_SHUTDOWN

Fields

  • enable: boolean()

    • default: true

    Enable force_shutdown feature.

  • max_message_queue_len: 0..inf

    • default: 1000

    Maximum message queue length.

  • max_heap_size: emqx_schema:wordsize()

    • default: "32MB"

    Total heap size

# broker:listener_ssl_opts

Socket options for SSL connections.

Config paths

  • gateway.exproto.listeners.ssl.$name.ssl_options
  • gateway.stomp.listeners.ssl.$name.ssl_options
  • listeners.ssl.$name.ssl_options

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__SSL_OPTIONS
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__SSL_OPTIONS
  • EMQX_LISTENERS__SSL__$NAME__SSL_OPTIONS

Fields

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    EMQX-internal callback that is used to lookup pre-shared key (PSK) identity.

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • dhfile: string()

    Path to a file containing PEM-encoded Diffie-Hellman parameters to be used by the server if a cipher suite using Diffie-Hellman key exchange is negotiated. If not specified, default parameters are used.
    NOTE: The dhfile option is not supported by TLS 1.3.

  • fail_if_no_peer_cert: boolean()

    • default: false

    Used together with {verify, verify_peer} by an TLS/DTLS server. If set to true, the server fails if the client does not have a certificate to send, that is, sends an empty certificate. If set to false, it fails only if the client sends an invalid certificate (an empty certificate is considered valid).

  • honor_cipher_order: boolean()

    • default: true

    An important security setting, it forces the cipher to be set based on the server-specified order instead of the client-specified order, hence enforcing the (usually more properly configured) security ordering of the server administrator.

  • client_renegotiation: boolean()

    • default: true

    In protocols that support client-initiated renegotiation, the cost of resources of such an operation is higher for the server than the client. This can act as a vector for denial of service attacks. The SSL application already takes measures to counter-act such attempts, but client-initiated renegotiation can be strictly disabled by setting this option to false. The default value is true. Note that disabling renegotiation can result in long-lived connections becoming unusable due to limits on the number of messages the underlying cipher suite can encipher.

# broker:listener_wss_opts

Socket options for WebSocket/SSL connections.

Config paths

  • listeners.wss.$name.ssl_options

Env overrides

  • EMQX_LISTENERS__WSS__$NAME__SSL_OPTIONS

Fields

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    EMQX-internal callback that is used to lookup pre-shared key (PSK) identity.

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • dhfile: string()

    Path to a file containing PEM-encoded Diffie-Hellman parameters to be used by the server if a cipher suite using Diffie-Hellman key exchange is negotiated. If not specified, default parameters are used.
    NOTE: The dhfile option is not supported by TLS 1.3.

  • fail_if_no_peer_cert: boolean()

    • default: false

    Used together with {verify, verify_peer} by an TLS/DTLS server. If set to true, the server fails if the client does not have a certificate to send, that is, sends an empty certificate. If set to false, it fails only if the client sends an invalid certificate (an empty certificate is considered valid).

  • honor_cipher_order: boolean()

    • default: true

    An important security setting, it forces the cipher to be set based on the server-specified order instead of the client-specified order, hence enforcing the (usually more properly configured) security ordering of the server administrator.

  • client_renegotiation: boolean()

    • default: true

    In protocols that support client-initiated renegotiation, the cost of resources of such an operation is higher for the server than the client. This can act as a vector for denial of service attacks. The SSL application already takes measures to counter-act such attempts, but client-initiated renegotiation can be strictly disabled by setting this option to false. The default value is true. Note that disabling renegotiation can result in long-lived connections becoming unusable due to limits on the number of messages the underlying cipher suite can encipher.

  • handshake_timeout: emqx_schema:duration()

    • default: "15s"

    Maximum time duration allowed for the handshake to complete

# broker:listeners

MQTT listeners identified by their protocol type and assigned names

Config paths

  • listeners

Env overrides

  • EMQX_LISTENERS

Fields

# broker:mqtt

Global MQTT configuration.
The configs here work as default values which can be overridden in zone configs

Config paths

  • mqtt

Env overrides

  • EMQX_MQTT

Fields

  • idle_timeout: infinity | emqx_schema:duration()

    • default: "15s"

    After the TCP connection is established, if the MQTT CONNECT packet from the client is not received within the time specified by idle_timeout, the connection will be disconnected.

  • max_packet_size: emqx_schema:bytesize()

    • default: "1MB"

    Maximum MQTT packet size allowed.

  • max_clientid_len: 23..65535

    • default: 65535

    Maximum allowed length of MQTT Client ID.

  • max_topic_levels: 1..65535

    • default: 65535

    Maximum topic levels allowed.

  • max_qos_allowed: qos()

    • default: 2

    Maximum QoS allowed.

  • max_topic_alias: 0..65535

    • default: 65535

    Maximum topic alias, 0 means no topic alias supported.

  • retain_available: boolean()

    • default: true

    Whether to enable support for MQTT retained message.

  • wildcard_subscription: boolean()

    • default: true

    Whether to enable support for MQTT wildcard subscription.

  • shared_subscription: boolean()

    • default: true

    Whether to enable support for MQTT shared subscription.

  • exclusive_subscription: boolean()

    • default: false

    Whether to enable support for MQTT exclusive subscription.

  • ignore_loop_deliver: boolean()

    • default: false

    Ignore loop delivery of messages for MQTT v3.1.1/v3.1.0, similar to No Local subscription option in MQTT 5.0

  • strict_mode: boolean()

    • default: false

    Parse MQTT messages in strict mode. When set to true, invalid utf8 strings in for example client ID, topic name, etc. will cause the client to be disconnected

  • response_information: string()

    • default: ""

    Specify the response information returned to the client. This feature is disabled if is set to "". Applies only to clients using MQTT 5.0.

  • server_keepalive: integer() | disabled

    • default: disabled

    The keep alive that EMQX requires the client to use. If configured as disabled, it means that the keep alive specified by the client will be used. Requires Server Keep Alive in MQTT 5.0, so it is only applicable to clients using MQTT 5.0 protocol.

  • keepalive_backoff: number()

    • default: 0.75

    The backoff multiplier used by the broker to determine the client keep alive timeout. If EMQX doesn't receive any packet in Keep Alive * Backoff * 2 seconds, EMQX will close the current connection.

  • max_subscriptions: 1..inf | infinity

    • default: infinity

    Maximum number of subscriptions allowed per client.

  • upgrade_qos: boolean()

    • default: false

    Force upgrade of QoS level according to subscription.

  • max_inflight: 1..65535

    • default: 32

    Maximum number of QoS 1 and QoS 2 messages that are allowed to be delivered simultaneously before completing the acknowledgment.

  • retry_interval: emqx_schema:duration()

    • default: "30s"

    Retry interval for QoS 1/2 message delivering.

  • max_awaiting_rel: integer() | infinity

    • default: 100

    Maximum QoS 2 packets (Client -> Broker) awaiting PUBREL.

  • await_rel_timeout: emqx_schema:duration()

    • default: "300s"

    The QoS 2 messages (Client -> Broker) will be dropped if awaiting PUBREL timeout.

  • session_expiry_interval: emqx_schema:duration()

    • default: "2h"

    Specifies how long the session will expire after the connection is disconnected, only for non-MQTT 5.0 connections.

  • max_mqueue_len: non_neg_integer() | infinity

    • default: 1000

    Maximum queue length. Enqueued messages when persistent client disconnected, or inflight window is full.

  • mqueue_priorities: map() | disabled

    • default: disabled

    Topic priorities. Priority number [1-255] There's no priority table by default, hence all messages are treated equal.

    NOTE: Comma and equal signs are not allowed for priority topic names. NOTE: Messages for topics not in the priority table are treated as either highest or lowest priority depending on the configured value for mqtt.mqueue_default_priority.

    Examples: To configure "topic/1" > "topic/2": mqueue_priorities: {"topic/1": 10, "topic/2": 8}

  • mqueue_default_priority: highest | lowest

    • default: lowest

    Default topic priority, which will be used by topics not in Topic Priorities (mqueue_priorities).

  • mqueue_store_qos0: boolean()

    • default: true

    Specifies whether to store QoS 0 messages in the message queue while the connection is down but the session remains.

  • use_username_as_clientid: boolean()

    • default: false

    Whether to user Client ID as Username. This setting takes effect later than Use Peer Certificate as Username (peer_cert_as_username) and Use peer certificate as Client ID (peer_cert_as_clientid).

  • peer_cert_as_username: disabled | cn | dn | crt | pem | md5

    • default: disabled

    Use the CN, DN field in the peer certificate or the entire certificate content as Username. Only works for the TLS connection. Supported configurations are the following:

    • cn: Take the CN field of the certificate as Username
    • dn: Take the DN field of the certificate as Username
    • crt: Take the content of the DER or PEM certificate as Username
    • pem: Convert DER certificate content to PEM format as Username
    • md5: Take the MD5 value of the content of the DER or PEM certificate as Username
  • peer_cert_as_clientid: disabled | cn | dn | crt | pem | md5

    • default: disabled

    Use the CN, DN field in the peer certificate or the entire certificate content as Client ID. Only works for the TLS connection. Supported configurations are the following:

    • cn: Take the CN field of the certificate as Client ID
    • dn: Take the DN field of the certificate as Client ID
    • crt: Take the content of the DER or PEM certificate as Client ID
    • pem: Convert DER certificate content to PEM format as Client ID
    • md5: Take the MD5 value of the content of the DER or PEM certificate as Client ID

# broker:mqtt_quic_listener

Settings for the MQTT over QUIC listener.

Config paths

  • listeners.quic.$name

Env overrides

  • EMQX_LISTENERS__QUIC__$NAME

Fields

  • certfile: string()

    Path to the certificate file.

  • keyfile: string()

    Path to the secret key file.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

    NOTE: QUIC listener supports only 'tlsv1.3' ciphers

  • idle_timeout: emqx_schema:duration()

    • default: "15s"

    Close transport-layer connections from the clients that have not sent MQTT CONNECT message within this interval.

  • enabled: boolean()

    • default: true

    Enable listener.

  • bind: emqx_schema:ip_port() | integer()

    • default: 14567

    IP address and port for the listening socket.

  • acceptors: pos_integer()

    • default: 16

    The size of the listener's receiving pool.

  • max_connections: infinity | pos_integer()

    • default: infinity

    The maximum number of concurrent connections allowed by the listener.

  • mountpoint: binary()

    • default: ""

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t.
    Set to "" to disable the feature.

    Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    The configuration zone to which the listener belongs.

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    Type of the rate limit.

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

# broker:mqtt_ssl_listener

Settings for the MQTT over SSL listener.

Config paths

  • listeners.ssl.$name

Env overrides

  • EMQX_LISTENERS__SSL__$NAME

Fields

  • enabled: boolean()

    • default: true

    Enable listener.

  • bind: emqx_schema:ip_port() | integer()

    • default: 8883

    IP address and port for the listening socket.

  • acceptors: pos_integer()

    • default: 16

    The size of the listener's receiving pool.

  • max_connections: infinity | pos_integer()

    • default: infinity

    The maximum number of concurrent connections allowed by the listener.

  • mountpoint: binary()

    • default: ""

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t.
    Set to "" to disable the feature.

    Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    The configuration zone to which the listener belongs.

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    Type of the rate limit.

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • access_rules: [string()]

    • default: ["allow all"]

    The access control rules for this listener.
    See: https://github.com/emqtt/esockd#allowdeny

  • proxy_protocol: boolean()

    • default: false

    Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
    See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    Per-listener authentication override. Authentication can be one single authenticator instance or a chain of authenticators as an array. When authenticating a login (username, client ID, etc.) the authenticators are checked in the configured order.

  • tcp_options: broker:tcp_opts

  • ssl_options: broker:listener_ssl_opts

# broker:mqtt_tcp_listener

Settings for the MQTT over TCP listener.

Config paths

  • listeners.tcp.$name

Env overrides

  • EMQX_LISTENERS__TCP__$NAME

Fields

  • enabled: boolean()

    • default: true

    Enable listener.

  • bind: emqx_schema:ip_port() | integer()

    • default: 1883

    IP address and port for the listening socket.

  • acceptors: pos_integer()

    • default: 16

    The size of the listener's receiving pool.

  • max_connections: infinity | pos_integer()

    • default: infinity

    The maximum number of concurrent connections allowed by the listener.

  • mountpoint: binary()

    • default: ""

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t.
    Set to "" to disable the feature.

    Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    The configuration zone to which the listener belongs.

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    Type of the rate limit.

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • access_rules: [string()]

    • default: ["allow all"]

    The access control rules for this listener.
    See: https://github.com/emqtt/esockd#allowdeny

  • proxy_protocol: boolean()

    • default: false

    Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
    See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    Per-listener authentication override. Authentication can be one single authenticator instance or a chain of authenticators as an array. When authenticating a login (username, client ID, etc.) the authenticators are checked in the configured order.

  • tcp_options: broker:tcp_opts

# broker:mqtt_ws_listener

Settings for the MQTT over WebSocket listener.

Config paths

  • listeners.ws.$name

Env overrides

  • EMQX_LISTENERS__WS__$NAME

Fields

  • enabled: boolean()

    • default: true

    Enable listener.

  • bind: emqx_schema:ip_port() | integer()

    • default: 8083

    IP address and port for the listening socket.

  • acceptors: pos_integer()

    • default: 16

    The size of the listener's receiving pool.

  • max_connections: infinity | pos_integer()

    • default: infinity

    The maximum number of concurrent connections allowed by the listener.

  • mountpoint: binary()

    • default: ""

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t.
    Set to "" to disable the feature.

    Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    The configuration zone to which the listener belongs.

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    Type of the rate limit.

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • access_rules: [string()]

    • default: ["allow all"]

    The access control rules for this listener.
    See: https://github.com/emqtt/esockd#allowdeny

  • proxy_protocol: boolean()

    • default: false

    Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
    See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    Per-listener authentication override. Authentication can be one single authenticator instance or a chain of authenticators as an array. When authenticating a login (username, client ID, etc.) the authenticators are checked in the configured order.

  • tcp_options: broker:tcp_opts

  • websocket: broker:ws_opts

# broker:mqtt_wss_listener

Settings for the MQTT over WebSocket/SSL listener.

Config paths

  • listeners.wss.$name

Env overrides

  • EMQX_LISTENERS__WSS__$NAME

Fields

  • enabled: boolean()

    • default: true

    Enable listener.

  • bind: emqx_schema:ip_port() | integer()

    • default: 8084

    IP address and port for the listening socket.

  • acceptors: pos_integer()

    • default: 16

    The size of the listener's receiving pool.

  • max_connections: infinity | pos_integer()

    • default: infinity

    The maximum number of concurrent connections allowed by the listener.

  • mountpoint: binary()

    • default: ""

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t.
    Set to "" to disable the feature.

    Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • zone: atom()

    • default: default

    The configuration zone to which the listener belongs.

  • limiter: {$ratelimit_name -> emqx_limiter_schema:bucket_name()}

    • default: {connection = "default"}

    Type of the rate limit.

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • access_rules: [string()]

    • default: ["allow all"]

    The access control rules for this listener.
    See: https://github.com/emqtt/esockd#allowdeny

  • proxy_protocol: boolean()

    • default: false

    Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
    See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_schema:duration()

    • default: "3s"

    Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

  • authentication: [authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication]

    Per-listener authentication override. Authentication can be one single authenticator instance or a chain of authenticators as an array. When authenticating a login (username, client ID, etc.) the authenticators are checked in the configured order.

  • tcp_options: broker:tcp_opts

  • ssl_options: broker:listener_wss_opts

  • websocket: broker:ws_opts

# broker:overload_protection

Overload protection mechanism monitors the load of the system and temporarily disables some features (such as accepting new connections) when the load is high.

Config paths

  • overload_protection

Env overrides

  • EMQX_OVERLOAD_PROTECTION

Fields

  • enable: boolean()

    • default: false

    React on system overload or not

  • backoff_delay: 0..inf

    • default: 1

    Some unimportant tasks could be delayed for execution, here set the delays in ms

  • backoff_gc: boolean()

    • default: false

    Skip forceful GC if necessary

  • backoff_hibernation: boolean()

    • default: true

    Skip process hibernation if necessary

  • backoff_new_conn: boolean()

    • default: true

    Close new incoming connections if necessary

# broker:persistent_session_builtin

Settings for the built-in storage engine of persistent messages.

Config paths

  • persistent_session_store.backend

Env overrides

  • EMQX_PERSISTENT_SESSION_STORE__BACKEND

Fields

# broker:persistent_session_store

Settings for message persistence.

Config paths

  • persistent_session_store

Env overrides

  • EMQX_PERSISTENT_SESSION_STORE

Fields

  • enabled: boolean()

    • default: false

    Use the database to store information about persistent sessions. This makes it possible to migrate a client connection to another cluster node if a node is stopped.

  • on_disc: boolean()

    • default: true

    Save information about the persistent sessions on disc. If this option is enabled, persistent sessions will survive full restart of the cluster. Otherwise, all the data will be stored in RAM, and it will be lost when all the nodes in the cluster are stopped.

  • ram_cache: boolean()

    • default: false

    Maintain a copy of the data in RAM for faster access.

  • backend: broker:persistent_session_builtin

    • default:
    {
      messages {ram_cache = "false"}
      session {ram_cache = "true"}
      session_messages {ram_cache = "true"}
      type = "builtin"
    }
    
    1
    2
    3
    4
    5
    6

    Database management system used to store information about persistent sessions and messages.

    • builtin: Use the embedded database (mria)
  • max_retain_undelivered: emqx_schema:duration()

    • default: "1h"

    The time messages that was not delivered to a persistent session is stored before being garbage collected if the node the previous session was handled on restarts of is stopped.

  • message_gc_interval: emqx_schema:duration()

    • default: "1h"

    The starting interval for garbage collection of undelivered messages to a persistent session. This affects how often the "max_retain_undelivered" is checked for removal.

  • session_message_gc_interval: emqx_schema:duration()

    • default: "1m"

    The starting interval for garbage collection of transient data for persistent session messages. This does not affect the lifetime length of persistent session messages.

# broker:persistent_table_mria_opts

Tuning options for the mria table.

Config paths

  • persistent_session_store.backend.messages
  • persistent_session_store.backend.session
  • persistent_session_store.backend.session_messages

Env overrides

  • EMQX_PERSISTENT_SESSION_STORE__BACKEND__MESSAGES
  • EMQX_PERSISTENT_SESSION_STORE__BACKEND__SESSION
  • EMQX_PERSISTENT_SESSION_STORE__BACKEND__SESSION_MESSAGES

Fields

  • ram_cache: boolean()

    • default: true

    Maintain a copy of the data in RAM for faster access.

# broker:shared_subscription_group

Per group dispatch strategy for shared subscription

Config paths

  • broker.shared_subscription_group.$name

Env overrides

  • EMQX_BROKER__SHARED_SUBSCRIPTION_GROUP__$NAME

Fields

  • strategy: random | round_robin | sticky | local | hash_topic | hash_clientid

    • default: random

    Dispatch strategy for shared subscription.

    • random: dispatch the message to a random selected subscriber
    • round_robin: select the subscribers in a round-robin manner
    • sticky: always use the last selected subscriber to dispatch, until the subscriber disconnects.
    • hash: select the subscribers by the hash of clientIds
    • local: send to a random local subscriber. If local subscriber was not found, send to a random subscriber cluster-wide

# broker:ssl_client_opts

Socket options for SSL clients.

Config paths

  • authentication.$INDEX.ssl
  • authorization.sources.$INDEX.ssl
  • bridges.mqtt.$name.connector.ssl
  • bridges.webhook.$name.ssl
  • cluster.etcd.ssl
  • connectors.mqtt.$name.ssl
  • gateway.coap.authentication.ssl
  • gateway.coap.listeners.dtls.$name.authentication.ssl
  • gateway.coap.listeners.udp.$name.authentication.ssl
  • gateway.exproto.authentication.ssl
  • gateway.exproto.handler.ssl_options
  • gateway.exproto.listeners.dtls.$name.authentication.ssl
  • gateway.exproto.listeners.ssl.$name.authentication.ssl
  • gateway.exproto.listeners.tcp.$name.authentication.ssl
  • gateway.exproto.listeners.udp.$name.authentication.ssl
  • gateway.lwm2m.authentication.ssl
  • gateway.lwm2m.listeners.dtls.$name.authentication.ssl
  • gateway.lwm2m.listeners.udp.$name.authentication.ssl
  • gateway.mqttsn.authentication.ssl
  • gateway.mqttsn.listeners.dtls.$name.authentication.ssl
  • gateway.mqttsn.listeners.udp.$name.authentication.ssl
  • gateway.stomp.authentication.ssl
  • gateway.stomp.listeners.ssl.$name.authentication.ssl
  • gateway.stomp.listeners.tcp.$name.authentication.ssl
  • listeners.ssl.$name.authentication.$INDEX.ssl
  • listeners.tcp.$name.authentication.$INDEX.ssl
  • listeners.ws.$name.authentication.$INDEX.ssl
  • listeners.wss.$name.authentication.$INDEX.ssl

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__SSL
  • EMQX_AUTHORIZATION__SOURCES__$INDEX__SSL
  • EMQX_BRIDGES__MQTT__$NAME__CONNECTOR__SSL
  • EMQX_BRIDGES__WEBHOOK__$NAME__SSL
  • EMQX_CLUSTER__ETCD__SSL
  • EMQX_CONNECTORS__MQTT__$NAME__SSL
  • EMQX_GATEWAY__COAP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__HANDLER__SSL_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__SSL

Fields

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    EMQX-internal callback that is used to lookup pre-shared key (PSK) identity.

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • enable: boolean()

    • default: false

    Enable TLS.

  • server_name_indication: disable | string()

    Specify the host name to be used in TLS Server Name Indication extension.
    For instance, when connecting to "server.example.net", the genuine server which accepts the connection and performs TLS handshake may differ from the host the TLS client initially connects to, e.g. when connecting to an IP address or when the host has multiple resolvable DNS records
    If not specified, it will default to the host name string which is used to establish the connection, unless it is IP addressed used.
    The host name is then also used in the host name verification of the peer certificate.
    The special value 'disable' prevents the Server Name Indication extension from being sent and disables the hostname verification check.

# broker:stats

Enable/disable statistic data collection. Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.

Config paths

  • stats

Env overrides

  • EMQX_STATS

Fields

  • enable: boolean()

    • default: true

    Enable/disable statistic data collection.

# broker:sys_topics

The EMQX Broker periodically publishes its own status, message statistics, client online and offline events to the system topic starting with $SYS/.

The following options control the behavior of $SYS topics.

Config paths

  • sys_topics

Env overrides

  • EMQX_SYS_TOPICS

Fields

  • sys_msg_interval: disabled | emqx_schema:duration()

    • default: "1m"

    Time interval of publishing $SYS messages.

  • sys_heartbeat_interval: disabled | emqx_schema:duration()

    • default: "30s"

    Time interval for publishing following heartbeat messages:

    • $SYS/brokers/<node>/uptime
    • $SYS/brokers/<node>/datetime
  • sys_event_messages: broker:event_names

    Client events messages

# broker:sysmon

Features related to system monitoring and introspection.

Config paths

  • sysmon

Env overrides

  • EMQX_SYSMON

Fields

# broker:sysmon_os

This part of the configuration is responsible for monitoring the host OS health, such as free memory, disk space, CPU load, etc.

Config paths

  • sysmon.os

Env overrides

  • EMQX_SYSMON__OS

Fields

  • cpu_check_interval: emqx_schema:duration()

    • default: "60s"

    The time interval for the periodic CPU check.

  • cpu_high_watermark: emqx_schema:percent()

    • default: "80%"

    The threshold, as percentage of system CPU load, for how much system cpu can be used before the corresponding alarm is raised.

  • cpu_low_watermark: emqx_schema:percent()

    • default: "60%"

    The threshold, as percentage of system CPU load, for how much system cpu can be used before the corresponding alarm is cleared.

  • mem_check_interval: disabled | emqx_schema:duration()

    • default: "60s"

    The time interval for the periodic memory check.

  • sysmem_high_watermark: emqx_schema:percent()

    • default: "70%"

    The threshold, as percentage of system memory, for how much system memory can be allocated before the corresponding alarm is raised.

  • procmem_high_watermark: emqx_schema:percent()

    • default: "5%"

    The threshold, as percentage of system memory, for how much system memory can be allocated by one Erlang process before the corresponding alarm is raised.

# broker:sysmon_top

This part of the configuration is responsible for monitoring the Erlang processes in the VM. This information can be sent to an external PostgreSQL database. This feature is inactive unless the PostgreSQL sink is configured.

Config paths

  • sysmon.top

Env overrides

  • EMQX_SYSMON__TOP

Fields

  • num_items: non_neg_integer()

    • default: 10
    • mapping: system_monitor.top_num_items

    The number of top processes per monitoring group

  • sample_interval: emqx_schema:duration()

    • default: "2s"
    • mapping: system_monitor.top_sample_interval

    Specifies how often process top should be collected

  • max_procs: non_neg_integer()

    • default: 1000000
    • mapping: system_monitor.top_max_procs

    Stop collecting data when the number of processes in the VM exceeds this value

  • db_hostname: string()

    • default: []
    • mapping: system_monitor.db_hostname

    Hostname of the PostgreSQL database that collects the data points

  • db_port: integer()

    • default: 5432
    • mapping: system_monitor.db_port

    Port of the PostgreSQL database that collects the data points

  • db_username: string()

    • default: "system_monitor"
    • mapping: system_monitor.db_username

    Username of the PostgreSQL database

  • db_password: binary()

    • default: "system_monitor_password"
    • mapping: system_monitor.db_password

    EMQX user password in the PostgreSQL database

  • db_name: string()

    • default: "postgres"
    • mapping: system_monitor.db_name

    PostgreSQL database name

# broker:sysmon_vm

This part of the configuration is responsible for collecting BEAM VM events, such as long garbage collection, traffic congestion in the inter-broker communication, etc.

Config paths

  • sysmon.vm

Env overrides

  • EMQX_SYSMON__VM

Fields

  • process_check_interval: emqx_schema:duration()

    • default: "30s"

    The time interval for the periodic process limit check.

  • process_high_watermark: emqx_schema:percent()

    • default: "80%"

    The threshold, as percentage of processes, for how many processes can simultaneously exist at the local node before the corresponding alarm is raised.

  • process_low_watermark: emqx_schema:percent()

    • default: "60%"

    The threshold, as percentage of processes, for how many processes can simultaneously exist at the local node before the corresponding alarm is cleared.

  • long_gc: disabled | emqx_schema:duration()

    • default: disabled

    Enable Long GC monitoring.

  • long_schedule: disabled | emqx_schema:duration()

    • default: "240ms"

    Enable Long Schedule monitoring.

  • large_heap: disabled | emqx_schema:bytesize()

    • default: "32MB"

    Enable Large Heap monitoring.

  • busy_dist_port: boolean()

    • default: true

    Enable Busy Distribution Port monitoring.

  • busy_port: boolean()

    • default: true

    Enable Busy Port monitoring.

# broker:tcp_opts

TCP listener options.

Config paths

  • gateway.exproto.listeners.ssl.$name.tcp_options
  • gateway.exproto.listeners.tcp.$name.tcp_options
  • gateway.stomp.listeners.ssl.$name.tcp_options
  • gateway.stomp.listeners.tcp.$name.tcp_options
  • listeners.ssl.$name.tcp_options
  • listeners.tcp.$name.tcp_options
  • listeners.ws.$name.tcp_options
  • listeners.wss.$name.tcp_options

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__TCP_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__TCP_OPTIONS
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__TCP_OPTIONS
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__SSL__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__TCP__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__WS__$NAME__TCP_OPTIONS
  • EMQX_LISTENERS__WSS__$NAME__TCP_OPTIONS

Fields

  • active_n: integer()

    • default: 100

    Specify the {active, N} option for this Socket.
    See: https://erlang.org/doc/man/inet.html#setopts-2

  • backlog: pos_integer()

    • default: 1024

    TCP backlog defines the maximum length that the queue of pending connections can grow to.

  • send_timeout: emqx_schema:duration()

    • default: "15s"

    The TCP send timeout for the connections.

  • send_timeout_close: boolean()

    • default: true

    Close the connection if send timeout.

  • recbuf: emqx_schema:bytesize()

    The TCP receive buffer (OS kernel) for the connections.

  • sndbuf: emqx_schema:bytesize()

    The TCP send buffer (OS kernel) for the connections.

  • buffer: emqx_schema:bytesize()

    • default: "4KB"

    The size of the user-space buffer used by the driver.

  • high_watermark: emqx_schema:bytesize()

    • default: "1MB"

    The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.

  • nodelay: boolean()

    • default: true

    The TCP_NODELAY flag for the connections.

  • reuseaddr: boolean()

    • default: true

    The SO_REUSEADDR flag for the connections.

# broker:trace

Real-time filtering logs for the ClientID or Topic or IP for debugging.

Config paths

  • trace

Env overrides

  • EMQX_TRACE

Fields

  • payload_encode: hex | text | hidden

    • default: text

    Determine the format of the payload format in the trace file.
    text: Text-based protocol or plain text protocol. It is recommended when payload is JSON encoded.
    hex: Binary hexadecimal encode. It is recommended when payload is a custom binary protocol.
    hidden: payload is obfuscated as ******

# broker:ws_opts

WebSocket listener options.

Config paths

  • listeners.ws.$name.websocket
  • listeners.wss.$name.websocket

Env overrides

  • EMQX_LISTENERS__WS__$NAME__WEBSOCKET
  • EMQX_LISTENERS__WSS__$NAME__WEBSOCKET

Fields

  • mqtt_path: string()

    • default: "/mqtt"

    WebSocket's MQTT protocol path. So the address of EMQX Broker's WebSocket is: ws://{ip}:{port}/mqtt

  • mqtt_piggyback: single | multiple

    • default: multiple

    Whether a WebSocket message is allowed to contain multiple MQTT packets.

  • compress: boolean()

    • default: false

    If true, compress WebSocket messages using zlib.
    The configuration items under deflate_opts belong to the compression-related parameter configuration.

  • idle_timeout: emqx_schema:duration()

    • default: "7200s"

    Close transport-layer connections from the clients that have not sent MQTT CONNECT message within this interval.

  • max_frame_size: infinity | integer()

    • default: infinity

    The maximum length of a single MQTT packet.

  • fail_if_no_subprotocol: boolean()

    • default: true

    If true, the server will return an error when the client does not carry the Sec-WebSocket-Protocol field.
    Note: WeChat applet needs to disable this verification.

  • supported_subprotocols: emqx_schema:comma_separated_list()

    • default: "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5"

    Comma-separated list of supported subprotocols.

  • check_origin_enable: boolean()

    • default: false

    If true, origin HTTP header will be validated against the list of allowed origins configured in check_origins parameter.

  • allow_origin_absence: boolean()

    • default: true

    If false and check_origin_enable is true, the server will reject requests that don't have origin HTTP header.

  • check_origins: emqx_schema:comma_separated_binary()

    • default: "http://localhost:18083, http://127.0.0.1:18083"

    List of allowed origins.
    See check_origin_enable.

  • proxy_address_header: string()

    • default: "x-forwarded-for"

    HTTP header used to pass information about the client IP address. Relevant when the EMQX cluster is deployed behind a load-balancer.

  • proxy_port_header: string()

    • default: "x-forwarded-port"

    HTTP header used to pass information about the client port. Relevant when the EMQX cluster is deployed behind a load-balancer.

  • deflate_opts: broker:deflate_opts

# broker:zone

A Zone defines a set of configuration items (such as the maximum number of connections) that can be shared between multiple listeners.

Listener can refer to a Zone through the configuration item listener.<Protocol>.<Listener Name>.zone.

The configs defined in the zones will override the global configs with the same key.

For example, given the following config:

a {
    b: 1, c: 1
}
zone.my_zone {
  a {
    b:2
  }
}
1
2
3
4
5
6
7
8

The global config a is overridden by the configs a inside the zone my_zone.

If there is a listener using the zone my_zone, the value of config a will be: {b:2, c: 1}. Note that although the default value of a.c is 0, the global value is used, i.e. configs in the zone have no default values. To override a.c one must configure it explicitly in the zone.

All the global configs that can be overridden in zones are:

  • stats.*
  • mqtt.*
  • authorization.*
  • flapping_detect.*
  • force_shutdown.*
  • conn_congestion.*
  • force_gc.*

Config paths

  • zones.$name

Env overrides

  • EMQX_ZONES__$NAME

Fields

# connector:connectors

Configuration for EMQX connectors.
A connector maintains the data related to the external resources, such as MySQL database.

Config paths

  • connectors

Env overrides

  • EMQX_CONNECTORS

Fields

# dashboard

Configuration for EMQX dashboard.

Config paths

  • dashboard

Env overrides

  • EMQX_DASHBOARD

Fields

  • listeners: dashboard:listeners

    HTTP(s) listeners are identified by their protocol type and are used to serve dashboard UI and restful HTTP API. Listeners must have a unique combination of port number and IP address. For example, an HTTP listener can listen on all configured IP addresses on a given port for a machine by specifying the IP address 0.0.0.0. Alternatively, the HTTP listener can specify a unique IP address for each listener, but use the same port.

  • default_username: binary()

    • default: "admin"

    The default username of the automatically created dashboard user.

  • default_password: binary()

    • default: "public"

    The initial default password for dashboard 'admin' user. For safety, it should be changed as soon as possible.

  • sample_interval: emqx_schema:duration_s()

    • default: "10s"

    How often to update metrics displayed in the dashboard. Note: sample_interval should be a divisor of 60.

  • token_expired_time: emqx_schema:duration()

    • default: "60m"

    JWT token expiration time.

  • cors: boolean()

    • default: false

    Support Cross-Origin Resource Sharing (CORS). Allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources.

  • i18n_lang: en | zh

    • default: en

    Internationalization language support.

# dashboard:http

Configuration for the dashboard listener (plaintext).

Config paths

  • dashboard.listeners.http

Env overrides

  • EMQX_DASHBOARD__LISTENERS__HTTP

Fields

  • enable: boolean()

    • default: true

    Ignore or enable this listener

  • bind: non_neg_integer() | emqx_schema:ip_port()

    • default: 18083

    Port without IP(18083) or port with specified IP(127.0.0.1:18083).

  • num_acceptors: integer()

    • default: 4

    Socket acceptor pool size for TCP protocols.

  • max_connections: integer()

    • default: 512

    Maximum number of simultaneous connections.

  • backlog: integer()

    • default: 1024

    Defines the maximum length that the queue of pending connections can grow to.

  • send_timeout: emqx_schema:duration()

    • default: "5s"

    Send timeout for the socket.

  • inet6: boolean()

    • default: false

    Enable IPv6 support, default is false, which means IPv4 only.

  • ipv6_v6only: boolean()

    • default: false

    Disable IPv4-to-IPv6 mapping for the listener.

# dashboard:https

Configuration for the dashboard listener (TLS).

Config paths

  • dashboard.listeners.https

Env overrides

  • EMQX_DASHBOARD__LISTENERS__HTTPS

Fields

  • enable: boolean()

    • default: false

    Ignore or enable this listener

  • bind: non_neg_integer() | emqx_schema:ip_port()

    • default: 18084

    Port without IP(18083) or port with specified IP(127.0.0.1:18083).

  • num_acceptors: integer()

    • default: 4

    Socket acceptor pool size for TCP protocols.

  • max_connections: integer()

    • default: 512

    Maximum number of simultaneous connections.

  • backlog: integer()

    • default: 1024

    Defines the maximum length that the queue of pending connections can grow to.

  • send_timeout: emqx_schema:duration()

    • default: "5s"

    Send timeout for the socket.

  • inet6: boolean()

    • default: false

    Enable IPv6 support, default is false, which means IPv4 only.

  • ipv6_v6only: boolean()

    • default: false

    Disable IPv4-to-IPv6 mapping for the listener.

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    EMQX-internal callback that is used to lookup pre-shared key (PSK) identity.

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • dhfile: string()

    Path to a file containing PEM-encoded Diffie-Hellman parameters to be used by the server if a cipher suite using Diffie-Hellman key exchange is negotiated. If not specified, default parameters are used.
    NOTE: The dhfile option is not supported by TLS 1.3.

  • honor_cipher_order: boolean()

    • default: true

    An important security setting, it forces the cipher to be set based on the server-specified order instead of the client-specified order, hence enforcing the (usually more properly configured) security ordering of the server administrator.

  • client_renegotiation: boolean()

    • default: true

    In protocols that support client-initiated renegotiation, the cost of resources of such an operation is higher for the server than the client. This can act as a vector for denial of service attacks. The SSL application already takes measures to counter-act such attempts, but client-initiated renegotiation can be strictly disabled by setting this option to false. The default value is true. Note that disabling renegotiation can result in long-lived connections becoming unusable due to limits on the number of messages the underlying cipher suite can encipher.

  • handshake_timeout: emqx_schema:duration()

    • default: "15s"

    Maximum time duration allowed for the handshake to complete

# dashboard:listeners

Configuration for the dashboard listener.

Config paths

  • dashboard.listeners

Env overrides

  • EMQX_DASHBOARD__LISTENERS

Fields

# exhook

External hook (exhook) configuration.

Config paths

  • exhook

Env overrides

  • EMQX_EXHOOK

Fields

# exhook:server

gRPC server configuration.

Config paths

  • exhook.servers.$INDEX

Env overrides

  • EMQX_EXHOOK__SERVERS__$INDEX

Fields

  • name: binary()

    Name of the exhook server

  • enable: boolean()

    • default: true

    Enable this Exhook server

  • url: binary()

    URL of the gRPC server

  • request_timeout: emqx_schema:duration()

    • default: "5s"

    The timeout of request gRPC server

  • failed_action: deny | ignore

    • default: deny

    The value that is returned when the request to the gRPC server fails for any reason

  • ssl: exhook:ssl_conf

  • socket_options: exhook:socket_options

    • default: {keepalive = true, nodelay = true}
  • auto_reconnect: false | emqx_schema:duration()

    • default: "60s"

    Whether to automatically reconnect (initialize) the gRPC server. When gRPC is not available, Exhook tries to request the gRPC service at that interval and reinitialize the list of mounted hooks.

  • pool_size: pos_integer()

    • default: 8

    The process pool size for gRPC client

# exhook:socket_options

Connection socket options

Config paths

  • exhook.servers.$INDEX.socket_options

Env overrides

  • EMQX_EXHOOK__SERVERS__$INDEX__SOCKET_OPTIONS

Fields

  • keepalive: boolean()

    • default: true

    Enables/disables periodic transmission on a connected socket when no other data is exchanged. If the other end does not respond, the connection is considered broken and an error message is sent to the controlling process.

  • nodelay: boolean()

    • default: true

    If true, option TCP_NODELAY is turned on for the socket, which means that also small amounts of data are sent immediately

  • recbuf: emqx_schema:bytesize()

    The minimum size of receive buffer to use for the socket

  • sndbuf: emqx_schema:bytesize()

    The minimum size of send buffer to use for the socket

# exhook:ssl_conf

SSL client configuration.

Config paths

  • exhook.servers.$INDEX.ssl

Env overrides

  • EMQX_EXHOOK__SERVERS__$INDEX__SSL

Fields

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • enable: boolean()

    • default: false

    Enable TLS.

  • server_name_indication: disable | string()

    Specify the host name to be used in TLS Server Name Indication extension.
    For instance, when connecting to "server.example.net", the genuine server which accepts the connection and performs TLS handshake may differ from the host the TLS client initially connects to, e.g. when connecting to an IP address or when the host has multiple resolvable DNS records
    If not specified, it will default to the host name string which is used to establish the connection, unless it is IP addressed used.
    The host name is then also used in the host name verification of the peer certificate.
    The special value 'disable' prevents the Server Name Indication extension from being sent and disables the hostname verification check.

# gateway:clientinfo_override

ClientInfo override.

Config paths

  • gateway.coap.clientinfo_override
  • gateway.exproto.clientinfo_override
  • gateway.lwm2m.clientinfo_override
  • gateway.mqttsn.clientinfo_override
  • gateway.stomp.clientinfo_override

Env overrides

  • EMQX_GATEWAY__COAP__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__EXPROTO__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__LWM2M__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__MQTTSN__CLIENTINFO_OVERRIDE
  • EMQX_GATEWAY__STOMP__CLIENTINFO_OVERRIDE

Fields

  • username: binary()

    Template for overriding username.

  • password: binary()

    Template for overriding password.

  • clientid: binary()

    Template for overriding clientid.

# gateway:coap

The CoAP protocol gateway provides EMQX with the access capability of the CoAP protocol. It allows publishing, subscribing, and receiving messages to EMQX in accordance with a certain defined CoAP message format.

Config paths

  • gateway.coap

Env overrides

  • EMQX_GATEWAY__COAP

Fields

  • heartbeat: emqx_gateway_schema:duration()

    • default: "30s"

    The gateway server required minimum heartbeat interval. When connection mode is enabled, this parameter is used to set the minimum heartbeat interval for the connection to be alive

  • connection_required: boolean()

    • default: false

    Enable or disable connection mode. Connection mode is a feature of non-standard protocols. When connection mode is enabled, it is necessary to maintain the creation, authentication and alive of connection resources

  • notify_type: non | con | qos

    • default: qos

    The Notification Message will be delivered to the CoAP client if a new message received on an observed topic. The type of delivered coap message can be set to:

    • non: Non-confirmable;
    • con: Confirmable;
    • qos: Mapping from QoS type of received message, QoS0 -> non, QoS1,2 -> con
  • subscribe_qos: qos0 | qos1 | qos2 | coap

    • default: coap

    The Default QoS Level indicator for subscribe request. This option specifies the QoS level for the CoAP Client when establishing a subscription membership, if the subscribe request is not carried qos option. The indicator can be set to:

    • qos0, qos1, qos2: Fixed default QoS level
    • coap: Dynamic QoS level by the message type of subscribe request
      • qos0: If the subscribe request is non-confirmable
      • qos1: If the subscribe request is confirmable
  • publish_qos: qos0 | qos1 | qos2 | coap

    • default: coap

    The Default QoS Level indicator for publish request. This option specifies the QoS level for the CoAP Client when publishing a message to EMQX PUB/SUB system, if the publish request is not carried qos option. The indicator can be set to:

    • qos0, qos1, qos2: Fixed default QoS level
    • coap: Dynamic QoS level by the message type of publish request
      • qos0: If the publish request is non-confirmable
      • qos1: If the publish request is confirmable
  • mountpoint: binary()

    • default: ""
  • listeners: gateway:udp_listeners

    Settings for the UDP listeners.

  • enable: boolean()

    • default: true

    Whether to enable this gateway

  • enable_stats: boolean()

    • default: true

    Whether to enable client process statistic

  • idle_timeout: emqx_gateway_schema:duration()

    • default: "30s"

    The idle time of the client connection process. It has two purposes:

    1. A newly created client process that does not receive any client requests after that time will be closed directly.
    2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.
  • clientinfo_override: gateway:clientinfo_override

    ClientInfo override.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

# gateway:dtls_listener

Settings for the DTLS listener.

Config paths

  • gateway.coap.listeners.dtls.$name
  • gateway.exproto.listeners.dtls.$name
  • gateway.lwm2m.listeners.dtls.$name
  • gateway.mqttsn.listeners.dtls.$name

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME

Fields

  • acceptors: integer()

    • default: 16

    Size of the acceptor pool.

  • udp_options: gateway:udp_opts

  • enable: boolean()

    • default: true

    Enable the listener.

  • bind: emqx_gateway_schema:ip_port() | integer()

    The IP address and port that the listener will bind.

  • max_connections: integer()

    • default: 1024

    Maximum number of concurrent connections.

  • max_conn_rate: integer()

    • default: 1000

    Maximum connections per second.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • mountpoint: binary()

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t. Set to "" to disable the feature. Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • access_rules: [string()]

    • default: []

    The access control rules for this listener. See: https://github.com/emqtt/esockd#allowdeny

  • dtls_options: gateway:dtls_opts

    DTLS socket options

# gateway:dtls_opts

Settings for the DTLS protocol.

Config paths

  • gateway.coap.listeners.dtls.$name.dtls_options
  • gateway.exproto.listeners.dtls.$name.dtls_options
  • gateway.lwm2m.listeners.dtls.$name.dtls_options
  • gateway.mqttsn.listeners.dtls.$name.dtls_options

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__DTLS_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__DTLS_OPTIONS
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__DTLS_OPTIONS
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__DTLS_OPTIONS

Fields

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [dtlsv1.2, dtlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    EMQX-internal callback that is used to lookup pre-shared key (PSK) identity.

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • dhfile: string()

    Path to a file containing PEM-encoded Diffie-Hellman parameters to be used by the server if a cipher suite using Diffie-Hellman key exchange is negotiated. If not specified, default parameters are used.
    NOTE: The dhfile option is not supported by TLS 1.3.

  • fail_if_no_peer_cert: boolean()

    • default: false

    Used together with {verify, verify_peer} by an TLS/DTLS server. If set to true, the server fails if the client does not have a certificate to send, that is, sends an empty certificate. If set to false, it fails only if the client sends an invalid certificate (an empty certificate is considered valid).

  • honor_cipher_order: boolean()

    • default: true

    An important security setting, it forces the cipher to be set based on the server-specified order instead of the client-specified order, hence enforcing the (usually more properly configured) security ordering of the server administrator.

  • client_renegotiation: boolean()

    • default: true

    In protocols that support client-initiated renegotiation, the cost of resources of such an operation is higher for the server than the client. This can act as a vector for denial of service attacks. The SSL application already takes measures to counter-act such attempts, but client-initiated renegotiation can be strictly disabled by setting this option to false. The default value is true. Note that disabling renegotiation can result in long-lived connections becoming unusable due to limits on the number of messages the underlying cipher suite can encipher.

# gateway:exproto

Settings for EMQX extension protocol (exproto).

Config paths

  • gateway.exproto

Env overrides

  • EMQX_GATEWAY__EXPROTO

Fields

# gateway:exproto_grpc_handler

Settings for the exproto gRPC connection handler.

Config paths

  • gateway.exproto.handler

Env overrides

  • EMQX_GATEWAY__EXPROTO__HANDLER

Fields

  • address: binary()

    gRPC server address.

  • ssl_options: broker:ssl_client_opts

    SSL configuration for the gRPC client.

# gateway:exproto_grpc_server

Settings for the exproto gRPC server.

Config paths

  • gateway.exproto.server

Env overrides

  • EMQX_GATEWAY__EXPROTO__SERVER

Fields

  • bind: emqx_gateway_schema:ip_port() | integer()

    Listening address and port for the gRPC server.

  • ssl_options: gateway:ssl_server_opts

    SSL configuration for the gRPC server.

# gateway

EMQX Gateway configuration root.

Config paths

  • gateway

Env overrides

  • EMQX_GATEWAY

Fields

  • stomp: gateway:stomp

    The Stomp Gateway configuration. This gateway supports v1.2/1.1/1.0

  • mqttsn: gateway:mqttsn

    The MQTT-SN Gateway configuration. This gateway only supports the v1.2 protocol

  • coap: gateway:coap

    The CoAP Gateway configuration. This gateway is implemented based on RFC-7252 and https://core-wg.github.io/coap-pubsub/draft-ietf-core-pubsub.html

  • lwm2m: gateway:lwm2m

    The LwM2M Gateway configuration. This gateway only supports the v1.0.1 protocol

  • exproto: gateway:exproto

    The Extension Protocol configuration

# gateway:lwm2m

The LwM2M protocol gateway.

Config paths

  • gateway.lwm2m

Env overrides

  • EMQX_GATEWAY__LWM2M

Fields

  • xml_dir: binary()

    • default: "etc/lwm2m_xml"

    The Directory for LwM2M Resource definition

  • lifetime_min: emqx_gateway_schema:duration()

    • default: "15s"

    Minimum value of lifetime allowed to be set by the LwM2M client

  • lifetime_max: emqx_gateway_schema:duration()

    • default: "86400s"

    Maximum value of lifetime allowed to be set by the LwM2M client

  • qmode_time_window: emqx_gateway_schema:duration_s()

    • default: "22s"

    The value of the time window during which the network link is considered valid by the LwM2M Gateway in QMode mode. For example, after receiving an update message from a client, any messages within this time window are sent directly to the LwM2M client, and all messages beyond this time window are temporarily stored in memory.

  • auto_observe: boolean()

    • default: false

    Automatically observe the object list of REGISTER packet

  • update_msg_publish_condition: always | contains_object_list

    • default: contains_object_list

    Policy for publishing UPDATE event message.

    • always: send update events as long as the UPDATE request is received.
    • contains_object_list: send update events only if the UPDATE request carries any Object List
  • translators: gateway:lwm2m_translators

    Topic configuration for LwM2M's gateway publishing and subscription

  • mountpoint: binary()

    • default: "lwm2m/${endpoint_name}/"
  • listeners: gateway:udp_listeners

    Settings for the UDP listeners.

  • enable: boolean()

    • default: true

    Whether to enable this gateway

  • enable_stats: boolean()

    • default: true

    Whether to enable client process statistic

  • idle_timeout: emqx_gateway_schema:duration()

    • default: "30s"

    The idle time of the client connection process. It has two purposes:

    1. A newly created client process that does not receive any client requests after that time will be closed directly.
    2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.
  • clientinfo_override: gateway:clientinfo_override

    ClientInfo override.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

# gateway:lwm2m_translators

MQTT topics that correspond to LwM2M events.

Config paths

  • gateway.lwm2m.translators

Env overrides

  • EMQX_GATEWAY__LWM2M__TRANSLATORS

Fields

  • command: gateway:translator

    The topic for receiving downstream commands. For each new LwM2M client that succeeds in going online, the gateway creates a subscription relationship to receive downstream commands and send it to the LwM2M client

  • response: gateway:translator

    The topic for gateway to publish the acknowledge events from LwM2M client

  • notify: gateway:translator

    The topic for gateway to publish the notify events from LwM2M client. After succeed observe a resource of LwM2M client, Gateway will send the notify events via this topic, if the client reports any resource changes

  • register: gateway:translator

    The topic for gateway to publish the register events from LwM2M client.

  • update: gateway:translator

    The topic for gateway to publish the update events from LwM2M client

# gateway:mqttsn

The MQTT-SN (MQTT for Sensor Networks) protocol gateway.

Config paths

  • gateway.mqttsn

Env overrides

  • EMQX_GATEWAY__MQTTSN

Fields

  • gateway_id: integer()

    • default: 1

    MQTT-SN Gateway ID. When the broadcast option is enabled, the gateway will broadcast ADVERTISE message with this value

  • broadcast: boolean()

    • default: false

    Whether to periodically broadcast ADVERTISE messages

  • enable_qos3: boolean()

    • default: true

    Allows connectionless clients to publish messages with a Qos of -1. This feature is defined for very simple client implementations which do not support any other features except this one. There is no connection setup nor tear down, no registration nor subscription. The client just sends its 'PUBLISH' messages to a GW

  • subs_resume: boolean()

    • default: false

    Whether to initiate all subscribed topic name registration messages to the client after the Session has been taken over by a new channel

  • predefined: [gateway:mqttsn_predefined]

    • default: []

    The pre-defined topic IDs and topic names. A 'pre-defined' topic ID is a topic ID whose mapping to a topic name is known in advance by both the client's application and the gateway

  • mountpoint: binary()

    • default: ""
  • listeners: gateway:udp_listeners

    Settings for the UDP listeners.

  • enable: boolean()

    • default: true

    Whether to enable this gateway

  • enable_stats: boolean()

    • default: true

    Whether to enable client process statistic

  • idle_timeout: emqx_gateway_schema:duration()

    • default: "30s"

    The idle time of the client connection process. It has two purposes:

    1. A newly created client process that does not receive any client requests after that time will be closed directly.
    2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.
  • clientinfo_override: gateway:clientinfo_override

    ClientInfo override.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

# gateway:mqttsn_predefined

The pre-defined topic name corresponding to the pre-defined topic ID of N.

Note: the pre-defined topic ID of 0 is reserved.

Config paths

  • gateway.mqttsn.predefined.$INDEX

Env overrides

  • EMQX_GATEWAY__MQTTSN__PREDEFINED__$INDEX

Fields

  • id: integer()

    Topic ID. Range: 1-65535

  • topic: binary()

    Topic Name

# gateway:ssl_listener

Settings for the SSL listener.

Config paths

  • gateway.exproto.listeners.ssl.$name
  • gateway.stomp.listeners.ssl.$name

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME

Fields

  • acceptors: integer()

    • default: 16

    Size of the acceptor pool.

  • tcp_options: broker:tcp_opts

    Setting the TCP socket options.

  • proxy_protocol: boolean()

    • default: false

    Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx. See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_gateway_schema:duration()

    • default: "15s"

    Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

  • enable: boolean()

    • default: true

    Enable the listener.

  • bind: emqx_gateway_schema:ip_port() | integer()

    The IP address and port that the listener will bind.

  • max_connections: integer()

    • default: 1024

    Maximum number of concurrent connections.

  • max_conn_rate: integer()

    • default: 1000

    Maximum connections per second.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • mountpoint: binary()

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t. Set to "" to disable the feature. Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • access_rules: [string()]

    • default: []

    The access control rules for this listener. See: https://github.com/emqtt/esockd#allowdeny

  • ssl_options: broker:listener_ssl_opts

    SSL Socket options.

# gateway:ssl_server_opts

SSL configuration for the server.

Config paths

  • gateway.exproto.server.ssl_options

Env overrides

  • EMQX_GATEWAY__EXPROTO__SERVER__SSL_OPTIONS

Fields

  • cacertfile: binary()

    Trusted PEM format CA certificates bundle file.
    The certificates in this file are used to verify the TLS peer's certificates. Append new certificates to the file if new CAs are to be trusted. There is no need to restart EMQX to have the updated file loaded, because the system regularly checks if file has been updated (and reload).
    NOTE: invalidating (deleting) a certificate from the file will not affect already established connections.

  • certfile: binary()

    PEM format certificates chain file.
    The certificates in this file should be in reversed order of the certificate issue chain. That is, the host's certificate should be placed in the beginning of the file, followed by the immediate issuer certificate and so on. Although the root CA certificate is optional, it should be placed at the end of the file if it is to be added.

  • keyfile: binary()

    PEM format private key file.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable peer verification.

  • reuse_sessions: boolean()

    • default: true

    Enable TLS session reuse.

  • depth: integer()

    • default: 10

    Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path. So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, and so on. The default value is 10.

  • password: string()

    String containing the user's password. Only used if the private key file is password-protected.

  • versions: [atom()]

    • default: [tlsv1.3, tlsv1.2, tlsv1.1, tlsv1]

    All TLS/DTLS versions to be supported.
    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
    In case PSK cipher suites are intended, make sure to configured ['tlsv1.2', 'tlsv1.1'] here.

  • ciphers: [string()]

    • default: ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_CCM_SHA256", "TLS_AES_128_CCM_8_SHA256", "ECDHE-ECDSA-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-ECDSA-AES256-SHA384", "ECDHE-RSA-AES256-SHA384", "ECDH-ECDSA-AES256-GCM-SHA384", "ECDH-RSA-AES256-GCM-SHA384", "ECDH-ECDSA-AES256-SHA384", "ECDH-RSA-AES256-SHA384", "DHE-DSS-AES256-GCM-SHA384", "DHE-DSS-AES256-SHA256", "AES256-GCM-SHA384", "AES256-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256", "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-SHA256", "ECDHE-RSA-AES128-SHA256", "ECDH-ECDSA-AES128-GCM-SHA256", "ECDH-RSA-AES128-GCM-SHA256", "ECDH-ECDSA-AES128-SHA256", "ECDH-RSA-AES128-SHA256", "DHE-DSS-AES128-GCM-SHA256", "DHE-DSS-AES128-SHA256", "AES128-GCM-SHA256", "AES128-SHA256", "ECDHE-ECDSA-AES256-SHA", "ECDHE-RSA-AES256-SHA", "DHE-DSS-AES256-SHA", "ECDH-ECDSA-AES256-SHA", "ECDH-RSA-AES256-SHA", "ECDHE-ECDSA-AES128-SHA", "ECDHE-RSA-AES128-SHA", "DHE-DSS-AES128-SHA", "ECDH-ECDSA-AES128-SHA", "ECDH-RSA-AES128-SHA", "RSA-PSK-AES256-GCM-SHA384", "RSA-PSK-AES256-CBC-SHA384", "RSA-PSK-AES128-GCM-SHA256", "RSA-PSK-AES128-CBC-SHA256", "RSA-PSK-AES256-CBC-SHA", "RSA-PSK-AES128-CBC-SHA"]

    This config holds TLS cipher suite names separated by comma, or as an array of strings. e.g. "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].
    Ciphers (and their ordering) define the way in which the client and server encrypts information over the network connection. Selecting a good cipher suite is critical for the application's data security, confidentiality and performance.

    The names should be in OpenSSL string format (not RFC format). All default values and examples provided by EMQX config documentation are all in OpenSSL format.

    NOTE: Certain cipher suites are only compatible with specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') incompatible cipher suites will be silently dropped. For instance, if only 'tlsv1.3' is given in the versions, configuring cipher suites for other versions will have no effect.

    NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
    If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
    PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384, RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256, RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA, RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"

  • user_lookup_fun: string()

    • default: "emqx_tls_psk:lookup"

    EMQX-internal callback that is used to lookup pre-shared key (PSK) identity.

  • secure_renegotiate: boolean()

    • default: true

    SSL parameter renegotiation is a feature that allows a client and a server to renegotiate the parameters of the SSL connection on the fly. RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation, you drop support for the insecure renegotiation, prone to MitM attacks.

  • dhfile: string()

    Path to a file containing PEM-encoded Diffie-Hellman parameters to be used by the server if a cipher suite using Diffie-Hellman key exchange is negotiated. If not specified, default parameters are used.
    NOTE: The dhfile option is not supported by TLS 1.3.

  • fail_if_no_peer_cert: boolean()

    • default: false

    Used together with {verify, verify_peer} by an TLS/DTLS server. If set to true, the server fails if the client does not have a certificate to send, that is, sends an empty certificate. If set to false, it fails only if the client sends an invalid certificate (an empty certificate is considered valid).

  • honor_cipher_order: boolean()

    • default: true

    An important security setting, it forces the cipher to be set based on the server-specified order instead of the client-specified order, hence enforcing the (usually more properly configured) security ordering of the server administrator.

  • client_renegotiation: boolean()

    • default: true

    In protocols that support client-initiated renegotiation, the cost of resources of such an operation is higher for the server than the client. This can act as a vector for denial of service attacks. The SSL application already takes measures to counter-act such attempts, but client-initiated renegotiation can be strictly disabled by setting this option to false. The default value is true. Note that disabling renegotiation can result in long-lived connections becoming unusable due to limits on the number of messages the underlying cipher suite can encipher.

  • handshake_timeout: emqx_schema:duration()

    • default: "15s"

    Maximum time duration allowed for the handshake to complete

# gateway:stomp

The STOMP protocol gateway provides EMQX with the ability to access STOMP (Simple (or Streaming) Text Orientated Messaging Protocol) protocol.

Config paths

  • gateway.stomp

Env overrides

  • EMQX_GATEWAY__STOMP

Fields

# gateway:stomp_frame

Size limits for the STOMP frames.

Config paths

  • gateway.stomp.frame

Env overrides

  • EMQX_GATEWAY__STOMP__FRAME

Fields

  • max_headers: non_neg_integer()

    • default: 10

    The maximum number of Header

  • max_headers_length: non_neg_integer()

    • default: 1024

    The maximum string length of the Header Value

  • max_body_length: integer()

    • default: 65536

    Maximum number of bytes of Body allowed per Stomp packet

# gateway:tcp_listener

Settings for the TCP listener.

Config paths

  • gateway.exproto.listeners.tcp.$name
  • gateway.stomp.listeners.tcp.$name

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME

Fields

  • acceptors: integer()

    • default: 16

    Size of the acceptor pool.

  • tcp_options: broker:tcp_opts

    Setting the TCP socket options.

  • proxy_protocol: boolean()

    • default: false

    Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx. See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

  • proxy_protocol_timeout: emqx_gateway_schema:duration()

    • default: "15s"

    Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

  • enable: boolean()

    • default: true

    Enable the listener.

  • bind: emqx_gateway_schema:ip_port() | integer()

    The IP address and port that the listener will bind.

  • max_connections: integer()

    • default: 1024

    Maximum number of concurrent connections.

  • max_conn_rate: integer()

    • default: 1000

    Maximum connections per second.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • mountpoint: binary()

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t. Set to "" to disable the feature. Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • access_rules: [string()]

    • default: []

    The access control rules for this listener. See: https://github.com/emqtt/esockd#allowdeny

# gateway:tcp_listeners

Settings for the TCP listeners.

Config paths

  • gateway.stomp.listeners

Env overrides

  • EMQX_GATEWAY__STOMP__LISTENERS

Fields

# gateway:tcp_udp_listeners

Settings for the listeners.

Config paths

  • gateway.exproto.listeners

Env overrides

  • EMQX_GATEWAY__EXPROTO__LISTENERS

Fields

# gateway:translator

MQTT topic that corresponds to a particular type of event.

Config paths

  • gateway.lwm2m.translators.command
  • gateway.lwm2m.translators.notify
  • gateway.lwm2m.translators.register
  • gateway.lwm2m.translators.response
  • gateway.lwm2m.translators.update

Env overrides

  • EMQX_GATEWAY__LWM2M__TRANSLATORS__COMMAND
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__NOTIFY
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__REGISTER
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__RESPONSE
  • EMQX_GATEWAY__LWM2M__TRANSLATORS__UPDATE

Fields

  • topic: binary()

    Topic Name

  • qos: qos()

    • default: 0

    QoS Level

# gateway:udp_listener

Settings for the UDP listener.

Config paths

  • gateway.coap.listeners.udp.$name
  • gateway.exproto.listeners.udp.$name
  • gateway.lwm2m.listeners.udp.$name
  • gateway.mqttsn.listeners.udp.$name

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME

Fields

  • udp_options: gateway:udp_opts

  • enable: boolean()

    • default: true

    Enable the listener.

  • bind: emqx_gateway_schema:ip_port() | integer()

    The IP address and port that the listener will bind.

  • max_connections: integer()

    • default: 1024

    Maximum number of concurrent connections.

  • max_conn_rate: integer()

    • default: 1000

    Maximum connections per second.

  • authentication: authn-builtin_db:authentication | authn-mysql:authentication | authn-postgresql:authentication | authn-mongodb:standalone | authn-mongodb:replica-set | authn-mongodb:sharded-cluster | authn-redis:standalone | authn-redis:cluster | authn-redis:sentinel | authn-http:get | authn-http:post | authn-jwt:hmac-based | authn-jwt:public-key | authn-jwt:jwks | authn-scram-builtin_db:authentication

    Default authentication configs for all the gateway listeners. For per-listener overrides see authentication in listener configs

  • enable_authn: boolean()

    • default: true

    Set true (default) to enable client authentication on this listener. When set to false clients will be allowed to connect without authentication.

  • mountpoint: binary()

    When publishing or subscribing, prefix all topics with a mountpoint string. The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners. For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant, then the client actually subscribes to the topic some_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t, the message is routed to all the clients subscribed some_tenant/t, so client A will receive the message, with topic name t. Set to "" to disable the feature. Variables in mountpoint string:

    • ${clientid}: clientid
    • ${username}: username
  • access_rules: [string()]

    • default: []

    The access control rules for this listener. See: https://github.com/emqtt/esockd#allowdeny

# gateway:udp_listeners

Settings for the UDP listeners.

Config paths

  • gateway.coap.listeners
  • gateway.lwm2m.listeners
  • gateway.mqttsn.listeners

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS
  • EMQX_GATEWAY__LWM2M__LISTENERS
  • EMQX_GATEWAY__MQTTSN__LISTENERS

Fields

# gateway:udp_opts

Settings for the UDP sockets.

Config paths

  • gateway.coap.listeners.dtls.$name.udp_options
  • gateway.coap.listeners.udp.$name.udp_options
  • gateway.exproto.listeners.dtls.$name.udp_options
  • gateway.exproto.listeners.udp.$name.udp_options
  • gateway.lwm2m.listeners.dtls.$name.udp_options
  • gateway.lwm2m.listeners.udp.$name.udp_options
  • gateway.mqttsn.listeners.dtls.$name.udp_options
  • gateway.mqttsn.listeners.udp.$name.udp_options

Env overrides

  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__UDP_OPTIONS
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__UDP_OPTIONS

Fields

  • active_n: integer()

    • default: 100

    Specify the {active, N} option for the socket. See: https://erlang.org/doc/man/inet.html#setopts-2

  • recbuf: emqx_gateway_schema:bytesize()

    Size of the kernel-space receive buffer for the socket.

  • sndbuf: emqx_gateway_schema:bytesize()

    Size of the kernel-space send buffer for the socket.

  • buffer: emqx_gateway_schema:bytesize()

    Size of the user-space buffer for the socket.

  • reuseaddr: boolean()

    • default: true

    Allow local reuse of port numbers.

# limiter:bucket_opts

Settings for the bucket.

Config paths

  • limiter.batch.bucket.$bucket_name
  • limiter.bytes_in.bucket.$bucket_name
  • limiter.connection.bucket.$bucket_name
  • limiter.message_in.bucket.$bucket_name
  • limiter.message_routing.bucket.$bucket_name

Env overrides

  • EMQX_LIMITER__BATCH__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__BYTES_IN__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__CONNECTION__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__MESSAGE_IN__BUCKET__$BUCKET_NAME
  • EMQX_LIMITER__MESSAGE_ROUTING__BUCKET__$BUCKET_NAME

Fields

  • rate: emqx_limiter_schema:rate()

    • default: "infinity"

    Rate for this bucket.

  • capacity: emqx_limiter_schema:capacity()

    • default: "infinity"

    The capacity of this token bucket.

  • initial: emqx_limiter_schema:initial()

    • default: "0"

    The initial number of tokens for this bucket.

  • per_client: limiter:client_bucket

    • default: {}

    The rate limit for each user of the bucket, this field is not required

# limiter:client_bucket

Settings for the client bucket.

Config paths

  • limiter.batch.bucket.$bucket_name.per_client
  • limiter.bytes_in.bucket.$bucket_name.per_client
  • limiter.connection.bucket.$bucket_name.per_client
  • limiter.message_in.bucket.$bucket_name.per_client
  • limiter.message_routing.bucket.$bucket_name.per_client

Env overrides

  • EMQX_LIMITER__BATCH__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__BYTES_IN__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__CONNECTION__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__MESSAGE_IN__BUCKET__$BUCKET_NAME__PER_CLIENT
  • EMQX_LIMITER__MESSAGE_ROUTING__BUCKET__$BUCKET_NAME__PER_CLIENT

Fields

  • rate: emqx_limiter_schema:rate()

    • default: "infinity"

    Rate for this bucket.

  • initial: emqx_limiter_schema:initial()

    • default: "0"

    The initial number of tokens for this bucket.

  • low_watermark: emqx_limiter_schema:initial()

    • default: "0"

    If the remaining tokens are lower than this value, the check/consume will succeed, but it will be forced to wait for a short period of time.

  • capacity: emqx_limiter_schema:capacity()

    • default: "infinity"

    The capacity of per user.

  • divisible: boolean()

    • default: false

    Is it possible to split the number of requested tokens?

  • max_retry_time: emqx_schema:duration()

    • default: "10s"

    The maximum retry time when acquire failed.

  • failure_strategy: emqx_limiter_schema:failure_strategy()

    • default: force

    The strategy when all the retries failed.

# limiter

Settings for the rate limiter.

Config paths

  • limiter

Env overrides

  • EMQX_LIMITER

Fields

  • bytes_in: limiter:limiter_opts

    • default: {}

    The bytes_in limiter. This is used to limit the inbound bytes rate for this EMQX node. Once the limit is reached, the restricted client will be slow down even be hung for a while.

  • message_in: limiter:limiter_opts

    • default: {}

    The message in limiter. This is used to limit the inbound message numbers for this EMQX node Once the limit is reached, the restricted client will be slow down even be hung for a while.

  • connection: limiter:limiter_opts

    • default:
    {
      bucket {
        default {capacity = 1000, rate = "1000/s"}
      }
      rate = "1000/s"
    }
    
    1
    2
    3
    4
    5
    6

    The connection limiter. This is used to limit the connection rate for this EMQX node. Once the limit is reached, new connections will be refused

  • message_routing: limiter:limiter_opts

    • default: {}

    The message routing limiter. This is used to limit the forwarding rate for this EMQX node. Once the limit is reached, new publish will be refused

  • batch: limiter:limiter_opts

    • default: {}

    The batch limiter. This is used for EMQX internal batch operation e.g. limit the retainer's deliver rate

# limiter:limiter_opts

Settings for the limiter.

Config paths

  • limiter.batch
  • limiter.bytes_in
  • limiter.connection
  • limiter.message_in
  • limiter.message_routing

Env overrides

  • EMQX_LIMITER__BATCH
  • EMQX_LIMITER__BYTES_IN
  • EMQX_LIMITER__CONNECTION
  • EMQX_LIMITER__MESSAGE_IN
  • EMQX_LIMITER__MESSAGE_ROUTING

Fields

  • rate: emqx_limiter_schema:rate()

    • default: "infinity"

    Rate for this bucket.

  • burst: emqx_limiter_schema:burst_rate()

    • default: 0

    The burst, This value is based on rate.
    This value + rate = the maximum limit that can be achieved when limiter burst.

  • bucket: {$bucket_name -> limiter:bucket_opts}

    • default:
    {
      default {}
    }
    
    1
    2
    3

    Bucket Configs

# modules:delayed

Settings for the delayed module.

Config paths

  • delayed

Env overrides

  • EMQX_DELAYED

Fields

  • enable: boolean()

    • default: true

    Enable this feature

  • max_delayed_messages: integer()

    • default: 0

    Maximum number of delayed messages (0 is no limit).

# modules:rewrite

The topic rewriting function of EMQX supports rewriting topic A to topic B when the client subscribes to topics, publishes messages, and cancels subscriptions according to user-configured rules. Each rewrite rule consists of three parts: subject filter, regular expression, and target expression. Under the premise that the subject rewriting function is enabled, when EMQX receives a subject-based MQTT message such as a PUBLISH message, it will use the subject of the message to sequentially match the subject filter part of the rule in the configuration file. If the match is successful, the regular expression is used to extract the information in the subject, and then replaced with the target expression to form a new subject. Variables in the format of $N can be used in the target expression to match the elements extracted from the regular expression. The value of $N is the Nth element extracted from the regular expression. For example, $1 is the regular expression. The first element extracted by the expression. It should be noted that EMQX uses reverse order to read the rewrite rules in the configuration file. When a topic can match the topic filter of multiple topic rewrite rules at the same time, EMQX will only use the first rule it matches. Rewrite. If the regular expression in this rule does not match the subject of the MQTT message, the rewriting will fail, and no other rules will be attempted for rewriting. Therefore, users need to carefully design MQTT message topics and topic rewriting rules when using them.

Config paths

  • rewrite.$INDEX

Env overrides

  • EMQX_REWRITE__$INDEX

Fields

  • action: subscribe | publish | all

    Topic rewriting takes effect on the type of operation:

    • subscribe: Rewrite topic when client do subscribe.
    • publish: Rewrite topic when client do publish.
    • all: Both
  • source_topic: binary()

    Source topic, specified by the client.

  • dest_topic: binary()

    Destination topic.

  • re: binary()

    Regular expressions

# modules:telemetry

Settings for the telemetry module.

Config paths

  • telemetry

Env overrides

  • EMQX_TELEMETRY

Fields

  • enable: boolean()

    • default: true

    Enable telemetry.

# modules:topic_metrics

Config paths

  • topic_metrics.$INDEX

Env overrides

  • EMQX_TOPIC_METRICS__$INDEX

Fields

  • topic: binary()

    Collect metrics for the topic.

# rule_engine:builtin_action_console

Configuration for a built-in action.

Config paths

  • rule_engine.rules.$id.actions.$INDEX

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX

Fields

  • function: console

    Print the actions to the console

# rule_engine:builtin_action_republish

Configuration for a built-in action.

Config paths

  • rule_engine.rules.$id.actions.$INDEX

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX

Fields

# rule_engine:republish_args

The arguments of the built-in 'republish' action.One can use variables in the args. The variables are selected by the rule. For example, if the rule SQL is defined as following: SELECT clientid, qos, payload FROM "t/1" Then there are 3 variables available: clientid, qos and payload. And if we've set the args to: { topic = "t/${clientid}" qos = "${qos}" payload = "msg: ${payload}" } When the rule is triggered by an MQTT message with payload = hello, qos = 1, clientid = Steve, the rule will republish a new MQTT message to topic t/Steve, payload = msg: hello, and qos = 1.

Config paths

  • rule_engine.rules.$id.actions.$INDEX.args

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX__ARGS

Fields

  • topic: binary()

    The target topic of message to be re-published. Template with variables is allowed, see description of the 'republish_args'.

  • qos: qos() | binary()

    • default: "${qos}"

    The qos of the message to be re-published. Template with variables is allowed, see description of the 'republish_args'. Defaults to ${qos}. If variable ${qos} is not found from the selected result of the rule, 0 is used.

  • retain: boolean() | binary()

    • default: "${retain}"

    The 'retain' flag of the message to be re-published. Template with variables is allowed, see description of the 'republish_args'. Defaults to ${retain}. If variable ${retain} is not found from the selected result of the rule, false is used.

  • payload: binary()

    • default: "${payload}"

    The payload of the message to be re-published. Template with variables is allowed, see description of the 'republish_args'. Defaults to ${payload}. If variable ${payload} is not found from the selected result of the rule, then the string "undefined" is used.

# rule_engine

Configuration for the EMQX Rule Engine.

Config paths

  • rule_engine

Env overrides

  • EMQX_RULE_ENGINE

Fields

  • ignore_sys_message: boolean()

    • default: true

    When set to 'true' (default), rule-engine will ignore messages published to $SYS topics.

  • rules: {$id -> rule_engine:rules}

    • default: {}

    The rules

  • jq_function_default_timeout: emqx_schema:duration_ms()

    • default: "10s"

    Default timeout for the jq rule engine function

# rule_engine:rules

Configuration for a rule.

Config paths

  • rule_engine.rules.$id

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID

Fields

  • name: binary()

    • default: ""

    The name of the rule

  • sql: binary()

    SQL query to transform the messages. Example: SELECT * FROM "test/topic" WHERE payload.x = 1

  • actions: [binary() | rule_engine:builtin_action_republish | rule_engine:builtin_action_console | rule_engine:user_provided_function]

    • default: []

    A list of actions of the rule. An action can be a string that refers to the channel ID of an EMQX bridge, or an object that refers to a function. There a some built-in functions like "republish" and "console", and we also support user provided functions in the format: "{module}:{function}". The actions in the list are executed sequentially. This means that if one of the action is executing slowly, all the following actions will not be executed until it returns. If one of the action crashed, all other actions come after it will still be executed, in the original order. If there's any error when running an action, there will be an error message, and the 'failure' counter of the function action or the bridge channel will increase.

  • enable: boolean()

    • default: true

    Enable or disable the rule

  • description: binary()

    • default: ""

    The description of the rule

# rule_engine:user_provided_function

Configuration for a built-in action.

Config paths

  • rule_engine.rules.$id.actions.$INDEX

Env overrides

  • EMQX_RULE_ENGINE__RULES__$ID__ACTIONS__$INDEX

Fields

  • function: binary()

    The user provided function. Should be in the format: '{module}:{function}'. Where {module} is the Erlang callback module and {function} is the Erlang function.

    To write your own function, checkout the function console and republish in the source file: apps/emqx_rule_engine/src/emqx_rule_actions.erl as an example.

  • args: map()

    • default: {}

    The args will be passed as the 3rd argument to module:function/3, checkout the function console and republish in the source file: apps/emqx_rule_engine/src/emqx_rule_actions.erl as an example.

# egress

Configuration for MQTT bridge.

Config paths

  • bridges.mqtt.$name

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME

Fields

  • direction: egress

    • default: egress

    The direction of the bridge. Can be one of 'ingress' or 'egress'.
    The egress config defines how this bridge forwards messages from the local broker to the remote broker.
    Template with variables is allowed in 'remote_topic', 'qos', 'retain', 'payload'.
    NOTE: if this bridge is used as the action of a rule (emqx rule engine), and also local_topic is configured, then both the data got from the rule and the MQTT messages that matches local_topic will be forwarded.

  • enable: boolean()

    • default: true

    Enable or disable this bridge

  • connector: binary() | connector-mqtt:connector

    The ID or the configs of the connector to be used for this bridge. Connector IDs must be of format: {type}:{name}.
    In config files, you can find the corresponding config entry for a connector by such path: 'connectors.{type}.{name}'.

  • local_topic: binary()

    The local topic to be forwarded to the remote broker

  • remote_topic: binary()

    Forward to which topic of the remote broker.
    Template with variables is allowed.

  • remote_qos: qos() | binary()

    The QoS of the MQTT message to be sent.
    Template with variables is allowed.

  • retain: boolean() | binary()

    The 'retain' flag of the MQTT message to be sent.
    Template with variables is allowed.

  • payload: binary()

    The payload of the MQTT message to be sent.
    Template with variables is allowed.

# ingress

Configuration for MQTT bridge.

Config paths

  • bridges.mqtt.$name

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME

Fields

  • direction: ingress

    • default: egress

    The direction of the bridge. Can be one of 'ingress' or 'egress'.
    The ingress config defines how this bridge receive messages from the remote MQTT broker, and then send them to the local broker.
    Template with variables is allowed in 'local_topic', 'remote_qos', 'qos', 'retain', 'payload'.
    NOTE: if this bridge is used as the input of a rule (emqx rule engine), and also local_topic is configured, then messages got from the remote broker will be sent to both the 'local_topic' and the rule.

  • enable: boolean()

    • default: true

    Enable or disable this bridge

  • connector: binary() | connector-mqtt:connector

    The ID or the configs of the connector to be used for this bridge. Connector IDs must be of format: {type}:{name}.
    In config files, you can find the corresponding config entry for a connector by such path: 'connectors.{type}.{name}'.

  • remote_topic: binary()

    Receive messages from which topic of the remote broker

  • remote_qos: qos() | binary()

    • default: 1

    The QoS level to be used when subscribing to the remote broker

  • local_topic: binary()

    Send messages to which topic of the local broker.
    Template with variables is allowed.

  • local_qos: qos() | binary()

    • default: "${qos}"

    The QoS of the MQTT message to be sent.
    Template with variables is allowed.

  • retain: boolean() | binary()

    • default: "${retain}"

    The 'retain' flag of the MQTT message to be sent.
    Template with variables is allowed.

  • payload: binary()

    • default: "${payload}"

    The payload of the MQTT message to be sent.
    Template with variables is allowed.

# config

Configuration for an HTTP bridge.

Config paths

  • bridges.webhook.$name

Env overrides

  • EMQX_BRIDGES__WEBHOOK__$NAME

Fields

  • enable: boolean()

    • default: true

    Enable or disable this bridge

  • direction: egress

    • default: egress

    The direction of this bridge, MUST be 'egress'

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    The timeout when connecting to the HTTP server.

  • max_retries: non_neg_integer()

    • default: 5

    Max retry times if error on sending request.

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    Interval between retries.

  • pool_type: emqx_connector_http:pool_type()

    • default: random

    The type of the pool. Can be one of random, hash.

  • pool_size: pos_integer()

    • default: 8

    The pool size.

  • enable_pipelining: pos_integer()

    • default: 100

    A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

  • request: connector-http:request

    If the request is provided, the caller can send HTTP requests via emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

  • url: binary()

    The URL of the HTTP Bridge.
    Template with variables is allowed in the path, but variables cannot be used in the scheme, host, or port part.
    For example, http://localhost:9901/${topic} is allowed, but http://${host}:9901/message or http://localhost:${port}/message is not allowed.

  • local_topic: binary()

    The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic matching the local_topic will be forwarded.
    NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is configured, then both the data got from the rule and the MQTT messages that match local_topic will be forwarded.

  • method: post | put | get | delete

    • default: post

    The method of the HTTP request. All the available methods are: post, put, get, delete.
    Template with variables is allowed.

  • headers: map()

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "content-type" = "application/json"
      "keep-alive" = "timeout=5"
    }
    
    1
    2
    3
    4
    5
    6
    7

    The headers of the HTTP request.
    Template with variables is allowed.

  • body: binary()

    • default: "${payload}"

    The body of the HTTP request.
    Template with variables is allowed.

  • request_timeout: emqx_schema:duration_ms()

    • default: "15s"

    HTTP request timeout.

# cluster_dns

Service discovery via DNS SRV records.

Config paths

  • cluster.dns

Env overrides

  • EMQX_CLUSTER__DNS

Fields

  • name: string()

    • default: "localhost"

    The domain name from which to discover peer EMQX nodes' IP addresses. Applicable when cluster.discovery_strategy = dns

  • record_type: a | srv

    • default: a

    DNS record type.

# cluster_etcd

Service discovery using 'etcd' service.

Config paths

  • cluster.etcd

Env overrides

  • EMQX_CLUSTER__ETCD

Fields

  • server: emqx_schema:comma_separated_list()

    List of endpoint URLs of the etcd cluster

  • prefix: string()

    • default: "emqxcl"

    Key prefix used for EMQX service discovery.

  • node_ttl: emqx_schema:duration()

    • default: "1m"

    Expiration time of the etcd key associated with the node. It is refreshed automatically, as long as the node is alive.

  • ssl: broker:ssl_client_opts

    Options for the TLS connection to the etcd cluster.

# cluster_k8s

Service discovery via Kubernetes API server.

Config paths

  • cluster.k8s

Env overrides

  • EMQX_CLUSTER__K8S

Fields

  • apiserver: string()

    • default: "http://10.110.111.204:8080"

    Kubernetes API endpoint URL.

  • service_name: string()

    • default: "emqx"

    EMQX broker service name.

  • address_type: ip | dns | hostname

    • default: ip

    Address type used for connecting to the discovered nodes. Setting cluster.k8s.address_type to ip will make EMQX to discover IP addresses of peer nodes from Kubernetes API.

  • namespace: string()

    • default: "default"

    Kubernetes namespace.

  • suffix: string()

    • default: "pod.local"

    Node name suffix.
    Note: this parameter is only relevant when address_type is dns or hostname.

# cluster_mcast

Service discovery via UDP multicast.

Config paths

  • cluster.mcast

Env overrides

  • EMQX_CLUSTER__MCAST

Fields

  • addr: string()

    • default: "239.192.0.1"

    Multicast IPv4 address.

  • ports: [integer()]

    • default: [4369,4370]

    List of UDP ports used for service discovery.
    Note: probe messages are broadcast to all the specified ports.

  • iface: string()

    • default: "0.0.0.0"

    Local IP address the node discovery service needs to bind to.

  • ttl: 0..255

    • default: 255

    Time-to-live (TTL) for the outgoing UDP datagrams.

  • loop: boolean()

    • default: true

    If true, loop UDP datagrams back to the local socket.

  • sndbuf: emqx_schema:bytesize()

    • default: "16KB"

    Size of the kernel-level buffer for outgoing datagrams.

  • recbuf: emqx_schema:bytesize()

    • default: "16KB"

    Size of the kernel-level buffer for incoming datagrams.

  • buffer: emqx_schema:bytesize()

    • default: "32KB"

    Size of the user-level buffer.

# cluster_static

Service discovery via static nodes. The new node joins the cluster by connecting to one of the bootstrap nodes.

Config paths

  • cluster.static

Env overrides

  • EMQX_CLUSTER__STATIC

Fields

  • seeds: [atom()]

    • default: []

    List EMQX node names in the static cluster. See node.name.

# authorization

Settings that control client authorization.

Config paths

  • authorization

Env overrides

  • EMQX_AUTHORIZATION

Fields

  • no_match: allow | deny

    • default: allow

    Default access control action if the user or client matches no ACL rules, or if no such user or client is found by the configurable authorization sources such as built_in_database, an HTTP API, or a query against PostgreSQL. Find more details in 'authorization.sources' config.

  • deny_action: ignore | disconnect

    • default: ignore

    The action when the authorization check rejects an operation.

  • cache: broker:cache

  • sources: [authz:file | authz:http_get | authz:http_post | authz:mnesia | authz:mongo_single | authz:mongo_rs | authz:mongo_sharded | authz:mysql | authz:postgresql | authz:redis_single | authz:redis_sentinel | authz:redis_cluster]

    • default: []

    Authorization data sources.
    An array of authorization (ACL) data providers. It is designed as an array, not a hash-map, so the sources can be ordered to form a chain of access controls.

    When authorizing a 'publish' or 'subscribe' action, the configured sources are checked in order. When checking an ACL source, in case the client (identified by username or client ID) is not found, it moves on to the next source. And it stops immediately once an 'allow' or 'deny' decision is returned.

    If the client is not found in any of the sources, the default action configured in 'authorization.no_match' is applied.

    NOTE: The source elements are identified by their 'type'. It is NOT allowed to configure two or more sources of the same type.

# cluster

EMQX nodes can form a cluster to scale up the total capacity.
Here holds the configs to instruct how individual nodes can discover each other.

Config paths

  • cluster

Env overrides

  • EMQX_CLUSTER

Fields

  • name: atom()

    • default: emqxcl
    • mapping: ekka.cluster_name

    Human-friendly name of the EMQX cluster.

  • discovery_strategy: manual | static | mcast | dns | etcd | k8s

    • default: manual

    Service discovery method for the cluster nodes.

  • core_nodes: emqx_schema:comma_separated_atoms()

    • default: []
    • mapping: mria.core_nodes

    List of core nodes that the replicant will connect to.
    Note: this parameter only takes effect when the backend is set to rlog and the role is set to replicant.
    This value needs to be defined for manual or static cluster discovery mechanisms.
    If an automatic cluster discovery mechanism is being used (such as etcd), there is no need to set this value.

  • autoclean: emqx_schema:duration()

    • default: "5m"
    • mapping: ekka.cluster_autoclean

    Remove disconnected nodes from the cluster after this interval.

  • autoheal: boolean()

    • default: true
    • mapping: ekka.cluster_autoheal

    If true, the node will try to heal network partitions automatically.

  • proto_dist: inet_tcp | inet6_tcp | inet_tls

    • default: inet_tcp
    • mapping: ekka.proto_dist

    The Erlang distribution protocol for the cluster.

  • static: cluster_static

  • mcast: cluster_mcast

  • dns: cluster_dns

  • etcd: cluster_etcd

  • k8s: cluster_k8s

# cluster_call

Options for the 'cluster call' feature that allows to execute a callback on all nodes in the cluster.

Config paths

  • node.cluster_call

Env overrides

  • EMQX_NODE__CLUSTER_CALL

Fields

  • retry_interval: emqx_schema:duration()

    • default: "1m"

    Time interval to retry after a failed call.

  • max_history: 1..500

    • default: 100

    Retain the maximum number of completed transactions (for queries).

  • cleanup_interval: emqx_schema:duration()

    • default: "5m"

    Time interval to clear completed but stale transactions. Ensure that the number of completed transactions is less than the max_history.

# console_handler

Log handler that prints log events to the EMQX console.

Config paths

  • log.console_handler

Env overrides

  • EMQX_LOG__CONSOLE_HANDLER

Fields

  • enable: boolean()

    • default: false

    Enable this log handler.

  • level: emqx_conf_schema:log_level()

    • default: warning

    The log level for the current log handler. Defaults to warning.

  • time_offset: string()

    • default: "system"

    The time offset to be used when formatting the timestamp. Can be one of:

    • system: the time offset used by the local system
    • utc: the UTC time offset
    • +-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to: system.
  • chars_limit: unlimited | 100..inf

    • default: unlimited

    Set the maximum length of a single log message. If this length is exceeded, the log message will be truncated.

  • formatter: text | json

    • default: text

    Choose log formatter. text for free text, and json for structured logging.

  • single_line: boolean()

    • default: true

    Print logs in a single line if set to true. Otherwise, log messages may span multiple lines.

  • sync_mode_qlen: non_neg_integer()

    • default: 100

    As long as the number of buffered log events is lower than this value, all log events are handled asynchronously. This means that the client process sending the log event, by calling a log function in the Logger API, does not wait for a response from the handler but continues executing immediately after the event is sent. It is not affected by the time it takes the handler to print the event to the log device. If the message queue grows larger than this value, the handler starts handling log events synchronously instead, meaning that the client process sending the event must wait for a response. When the handler reduces the message queue to a level below the sync_mode_qlen threshold, asynchronous operation is resumed.

  • drop_mode_qlen: pos_integer()

    • default: 3000

    When the number of buffered log events is larger than this value, the new log events are dropped. When drop mode is activated or deactivated, a message is printed in the logs.

  • flush_qlen: pos_integer()

    • default: 8000

    If the number of buffered log events grows larger than this threshold, a flush (delete) operation takes place. To flush events, the handler discards the buffered log messages without logging.

  • overload_kill: log_overload_kill

  • burst_limit: log_burst_limit

  • supervisor_reports: error | progress

    • default: error

    Type of supervisor reports that are logged. Defaults to error

    • error: only log errors in the Erlang processes.
    • progress: log process startup.
  • max_depth: unlimited | non_neg_integer()

    • default: 100

    Maximum depth for Erlang term log formatting and Erlang process message queue inspection.

# log

EMQX logging supports multiple sinks for the log events. Each sink is represented by a log handler, which can be configured independently.

Config paths

  • log

Env overrides

  • EMQX_LOG

Fields

# log_burst_limit

Large bursts of log events produced in a short time can potentially cause problems, such as:

  • Log files grow very large
  • Log files are rotated too quickly, and useful information gets overwritten
  • Overall performance impact on the system

Log burst limit feature can temporarily disable logging to avoid these issues.

Config paths

  • log.console_handler.burst_limit
  • log.file_handlers.$name.burst_limit

Env overrides

  • EMQX_LOG__CONSOLE_HANDLER__BURST_LIMIT
  • EMQX_LOG__FILE_HANDLERS__$NAME__BURST_LIMIT

Fields

  • enable: boolean()

    • default: true

    Enable log burst control feature.

  • max_count: pos_integer()

    • default: 10000

    Maximum number of log events to handle within a window_time interval. After the limit is reached, successive events are dropped until the end of the window_time.

  • window_time: emqx_schema:duration()

    • default: "1s"

    See max_count.

# log_file_handler

Log handler that prints log events to files.

Config paths

  • log.file_handlers.$name

Env overrides

  • EMQX_LOG__FILE_HANDLERS__$NAME

Fields

  • file: emqx_conf_schema:file()

    Name the log file.

  • rotation: log_rotation

  • max_size: infinity | emqx_schema:bytesize()

    • default: "50MB"

    This parameter controls log file rotation. The value infinity means the log file will grow indefinitely, otherwise the log file will be rotated once it reaches max_size in bytes.

  • enable: boolean()

    • default: true

    Enable this log handler.

  • level: emqx_conf_schema:log_level()

    • default: warning

    The log level for the current log handler. Defaults to warning.

  • time_offset: string()

    • default: "system"

    The time offset to be used when formatting the timestamp. Can be one of:

    • system: the time offset used by the local system
    • utc: the UTC time offset
    • +-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to: system.
  • chars_limit: unlimited | 100..inf

    • default: unlimited

    Set the maximum length of a single log message. If this length is exceeded, the log message will be truncated.

  • formatter: text | json

    • default: text

    Choose log formatter. text for free text, and json for structured logging.

  • single_line: boolean()

    • default: true

    Print logs in a single line if set to true. Otherwise, log messages may span multiple lines.

  • sync_mode_qlen: non_neg_integer()

    • default: 100

    As long as the number of buffered log events is lower than this value, all log events are handled asynchronously. This means that the client process sending the log event, by calling a log function in the Logger API, does not wait for a response from the handler but continues executing immediately after the event is sent. It is not affected by the time it takes the handler to print the event to the log device. If the message queue grows larger than this value, the handler starts handling log events synchronously instead, meaning that the client process sending the event must wait for a response. When the handler reduces the message queue to a level below the sync_mode_qlen threshold, asynchronous operation is resumed.

  • drop_mode_qlen: pos_integer()

    • default: 3000

    When the number of buffered log events is larger than this value, the new log events are dropped. When drop mode is activated or deactivated, a message is printed in the logs.

  • flush_qlen: pos_integer()

    • default: 8000

    If the number of buffered log events grows larger than this threshold, a flush (delete) operation takes place. To flush events, the handler discards the buffered log messages without logging.

  • overload_kill: log_overload_kill

  • burst_limit: log_burst_limit

  • supervisor_reports: error | progress

    • default: error

    Type of supervisor reports that are logged. Defaults to error

    • error: only log errors in the Erlang processes.
    • progress: log process startup.
  • max_depth: unlimited | non_neg_integer()

    • default: 100

    Maximum depth for Erlang term log formatting and Erlang process message queue inspection.

# log_overload_kill

Log overload kill features an overload protection that activates when the log handlers use too much memory or have too many buffered log messages.
When the overload is detected, the log handler is terminated and restarted after a cooldown period.

Config paths

  • log.console_handler.overload_kill
  • log.file_handlers.$name.overload_kill

Env overrides

  • EMQX_LOG__CONSOLE_HANDLER__OVERLOAD_KILL
  • EMQX_LOG__FILE_HANDLERS__$NAME__OVERLOAD_KILL

Fields

  • enable: boolean()

    • default: true

    Enable log handler overload kill feature.

  • mem_size: emqx_schema:bytesize()

    • default: "30MB"

    Maximum memory size that the log handler process is allowed to use.

  • qlen: pos_integer()

    • default: 20000

    Maximum allowed queue length.

  • restart_after: emqx_schema:duration_ms() | infinity

    • default: "5s"

    If the handler is terminated, it restarts automatically after a delay specified in milliseconds. The value infinity prevents restarts.

# log_rotation

By default, the logs are stored in ./log directory (for installation from zip file) or in /var/log/emqx (for binary installation).
This section of the configuration controls the number of files kept for each log handler.

Config paths

  • log.file_handlers.$name.rotation

Env overrides

  • EMQX_LOG__FILE_HANDLERS__$NAME__ROTATION

Fields

  • enable: boolean()

    • default: true

    Enable log rotation feature.

  • count: 1..2048

    • default: 10

    Maximum number of log files.

# node

Node name, cookie, config & data directories and the Erlang virtual machine (BEAM) boot parameters.

Config paths

  • node

Env overrides

  • EMQX_NODE

Fields

  • name: string()

    • default: "emqx@127.0.0.1"

    Unique name of the EMQX node. It must follow %name%@FQDN or %name%@IPv4 format.

  • cookie: string()

    • default: "emqxsecretcookie"
    • mapping: vm_args.-setcookie

    Secret cookie is a random string that should be the same on all nodes in the given EMQX cluster, but unique per EMQX cluster. It is used to prevent EMQX nodes that belong to different clusters from accidentally connecting to each other.

  • process_limit: 1024..134217727

    • default: 2097152
    • mapping: vm_args.+P

    Maximum number of simultaneously existing processes for this Erlang system. The actual maximum chosen may be much larger than the Number passed. For more information, see: https://www.erlang.org/doc/man/erl.html

  • max_ports: 1024..134217727

    • default: 1048576
    • mapping: vm_args.+Q

    Maximum number of simultaneously existing ports for this Erlang system. The actual maximum chosen may be much larger than the Number passed. For more information, see: https://www.erlang.org/doc/man/erl.html

  • dist_buffer_size: 1..2097151

    • default: 8192
    • mapping: vm_args.+zdbbl

    Erlang's distribution buffer busy limit in kilobytes.

  • max_ets_tables: pos_integer()

    • default: 262144
    • mapping: vm_args.+e

    Max number of ETS tables

  • data_dir: string()

    • mapping: emqx.data_dir

    Path to the persistent data directory.
    Possible auto-created subdirectories are:

    • mnesia/<node_name>: EMQX's built-in database directory.
      For example, mnesia/emqx@127.0.0.1.
      There should be only one such subdirectory.
      Meaning, in case the node is to be renamed (to e.g. emqx@10.0.1.1),
      the old dir should be deleted first.
    • configs: Generated configs at boot time, and cluster/local override configs.
    • patches: Hot-patch beam files are to be placed here.
    • trace: Trace log files.

    NOTE: One data dir cannot be shared by two or more EMQX nodes.

  • config_files: [string()]

    • mapping: emqx.config_files

    List of configuration files that are read during startup. The order is significant: later configuration files override the previous ones.

  • global_gc_interval: emqx_schema:duration()

    • default: "15m"
    • mapping: emqx_machine.global_gc_interval

    Periodic garbage collection interval.

  • crash_dump_file: emqx_conf_schema:file()

    • default: "log/erl_crash.dump"
    • mapping: vm_args.-env ERL_CRASH_DUMP

    Location of the crash dump file.

  • crash_dump_seconds: emqx_schema:duration_s()

    • default: "30s"
    • mapping: vm_args.-env ERL_CRASH_DUMP_SECONDS

    The number of seconds that the broker is allowed to spend writing a crash dump.

  • crash_dump_bytes: emqx_schema:bytesize()

    • default: "100MB"
    • mapping: vm_args.-env ERL_CRASH_DUMP_BYTES

    The maximum size of a crash dump file in bytes.

  • dist_net_ticktime: emqx_schema:duration_s()

    • default: "2m"
    • mapping: vm_args.-kernel net_ticktime

    This is the approximate time an EMQX node may be unresponsive until it is considered down and thereby disconnected.

  • backtrace_depth: integer()

    • default: 23
    • mapping: emqx_machine.backtrace_depth

    Maximum depth of the call stack printed in error messages and process_info.

  • applications: emqx_schema:comma_separated_atoms()

    • default: []
    • mapping: emqx_machine.applications

    List of Erlang applications that shall be rebooted when the EMQX broker joins the cluster.

  • etc_dir: string()

    etc dir for the node

  • cluster_call: cluster_call

  • db_backend: mnesia | rlog

    • default: rlog
    • mapping: mria.db_backend

    Select the backend for the embedded database.
    rlog is the default backend, that is suitable for very large clusters.
    mnesia is a backend that offers decent performance in small clusters.

  • db_role: core | replicant

    • default: core
    • mapping: mria.node_role

    Select a node role.
    core nodes provide durability of the data, and take care of writes. It is recommended to place core nodes in different racks or different availability zones.
    replicant nodes are ephemeral worker nodes. Removing them from the cluster doesn't affect database redundancy
    It is recommended to have more replicant nodes than core nodes.
    Note: this parameter only takes effect when the backend is set to rlog.

  • rpc_module: gen_rpc | rpc

    • default: gen_rpc
    • mapping: mria.rlog_rpc_module

    Protocol used for pushing transaction logs to the replicant nodes.

  • tlog_push_mode: sync | async

    • default: async
    • mapping: mria.tlog_push_mode

    In sync mode the core node waits for an ack from the replicant nodes before sending the next transaction log entry.

# rpc

EMQX uses a library called gen_rpc for inter-broker communication.
Most of the time the default config should work, but in case you need to do performance fine-tuning or experiment a bit, this is where to look.

Config paths

  • rpc

Env overrides

  • EMQX_RPC

Fields

  • mode: sync | async

    • default: async

    In sync mode the sending side waits for the ack from the receiving side.

  • driver: tcp | ssl

    • default: tcp
    • mapping: gen_rpc.driver

    Transport protocol used for inter-broker communication

  • async_batch_size: integer()

    • default: 256
    • mapping: gen_rpc.max_batch_size

    The maximum number of batch messages sent in asynchronous mode. Note that this configuration does not work in synchronous mode.

  • port_discovery: manual | stateless

    • default: stateless
    • mapping: gen_rpc.port_discovery

    manual: discover ports by tcp_server_port.
    stateless: discover ports in a stateless manner, using the following algorithm. If node name is emqxN@127.0.0.1, where the N is an integer, then the listening port will be 5370 + N.

  • tcp_server_port: integer()

    • default: 5369
    • mapping: gen_rpc.tcp_server_port

    Listening port used by RPC local service.
    Note that this config only takes effect when rpc.port_discovery is set to manual.

  • ssl_server_port: integer()

    • default: 5369
    • mapping: gen_rpc.ssl_server_port

    Listening port used by RPC local service.
    Note that this config only takes effect when rpc.port_discovery is set to manual and driver is set to ssl.

  • tcp_client_num: 1..256

    • default: 10

    Set the maximum number of RPC communication channels initiated by this node to each remote node.

  • connect_timeout: emqx_schema:duration()

    • default: "5s"
    • mapping: gen_rpc.connect_timeout

    Timeout for establishing an RPC connection.

  • certfile: emqx_conf_schema:file()

    • mapping: gen_rpc.certfile

    Path to TLS certificate file used to validate identity of the cluster nodes. Note that this config only takes effect when rpc.driver is set to ssl.

  • keyfile: emqx_conf_schema:file()

    • mapping: gen_rpc.keyfile

    Path to the private key file for the rpc.certfile.
    Note: contents of this file are secret, so it's necessary to set permissions to 600.

  • cacertfile: emqx_conf_schema:file()

    • mapping: gen_rpc.cacertfile

    Path to certification authority TLS certificate file used to validate rpc.certfile.
    Note: certificates of all nodes in the cluster must be signed by the same CA.

  • send_timeout: emqx_schema:duration()

    • default: "5s"
    • mapping: gen_rpc.send_timeout

    Timeout for sending the RPC request.

  • authentication_timeout: emqx_schema:duration()

    • default: "5s"
    • mapping: gen_rpc.authentication_timeout

    Timeout for the remote node authentication.

  • call_receive_timeout: emqx_schema:duration()

    • default: "15s"
    • mapping: gen_rpc.call_receive_timeout

    Timeout for the reply to a synchronous RPC.

  • socket_keepalive_idle: emqx_schema:duration_s()

    • default: "15m"
    • mapping: gen_rpc.socket_keepalive_idle

    How long the connections between the brokers should remain open after the last message is sent.

  • socket_keepalive_interval: emqx_schema:duration_s()

    • default: "75s"
    • mapping: gen_rpc.socket_keepalive_interval

    The interval between keepalive messages.

  • socket_keepalive_count: integer()

    • default: 9
    • mapping: gen_rpc.socket_keepalive_count

    How many times the keepalive probe message can fail to receive a reply until the RPC connection is considered lost.

  • socket_sndbuf: emqx_schema:bytesize()

    • default: "1MB"
    • mapping: gen_rpc.socket_sndbuf

    TCP tuning parameters. TCP sending buffer size.

  • socket_recbuf: emqx_schema:bytesize()

    • default: "1MB"
    • mapping: gen_rpc.socket_recbuf

    TCP tuning parameters. TCP receiving buffer size.

  • socket_buffer: emqx_schema:bytesize()

    • default: "1MB"
    • mapping: gen_rpc.socket_buffer

    TCP tuning parameters. Socket buffer size in user mode.

# topology

Topology of MongoDB.

Config paths

  • authentication.$INDEX.topology
  • authorization.sources.$INDEX.topology
  • gateway.coap.authentication.topology
  • gateway.coap.listeners.dtls.$name.authentication.topology
  • gateway.coap.listeners.udp.$name.authentication.topology
  • gateway.exproto.authentication.topology
  • gateway.exproto.listeners.dtls.$name.authentication.topology
  • gateway.exproto.listeners.ssl.$name.authentication.topology
  • gateway.exproto.listeners.tcp.$name.authentication.topology
  • gateway.exproto.listeners.udp.$name.authentication.topology
  • gateway.lwm2m.authentication.topology
  • gateway.lwm2m.listeners.dtls.$name.authentication.topology
  • gateway.lwm2m.listeners.udp.$name.authentication.topology
  • gateway.mqttsn.authentication.topology
  • gateway.mqttsn.listeners.dtls.$name.authentication.topology
  • gateway.mqttsn.listeners.udp.$name.authentication.topology
  • gateway.stomp.authentication.topology
  • gateway.stomp.listeners.ssl.$name.authentication.topology
  • gateway.stomp.listeners.tcp.$name.authentication.topology
  • listeners.ssl.$name.authentication.$INDEX.topology
  • listeners.tcp.$name.authentication.$INDEX.topology
  • listeners.ws.$name.authentication.$INDEX.topology
  • listeners.wss.$name.authentication.$INDEX.topology

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_AUTHORIZATION__SOURCES__$INDEX__TOPOLOGY
  • EMQX_GATEWAY__COAP__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__TOPOLOGY
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__TOPOLOGY

Fields

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • max_overflow: non_neg_integer()

    • default: 0

    Max Overflow.

  • overflow_ttl: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • overflow_check_period: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • local_threshold_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • connect_timeout_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • socket_timeout_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • server_selection_timeout_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • wait_queue_timeout_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • heartbeat_frequency_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

  • min_heartbeat_frequency_ms: emqx_schema:duration_ms()

    Time interval, such as timeout or TTL.

# zone:conn_congestion

Settings for conn_congestion alarm.

Sometimes the MQTT connection (usually an MQTT subscriber) may get "congested", because there are too many packets to be sent. The socket tries to buffer the packets until the buffer is full. If more packets arrive after that, the packets will be "pending" in the queue, and we consider the connection congested.

Note: sndbuf can be set to larger value if the alarm is triggered too often. The name of the alarm is of format conn_congestion/<ClientID>/<Username>, where the <ClientID> is the client ID of the congested MQTT connection, and <Username> is the username or unknown_user.

Config paths

  • zones.$name.conn_congestion

Env overrides

  • EMQX_ZONES__$NAME__CONN_CONGESTION

Fields

  • enable_alarm: boolean()

    Enable or disable connection congestion alarm.

  • min_alarm_sustain_duration: emqx_schema:duration()

    Minimal time before clearing the alarm.

    The alarm is cleared only when there's no pending data in the queue, and at least min_alarm_sustain_duration milliseconds passed since the last time we considered the connection "congested".

    This is to avoid clearing and raising the alarm again too often.

# zone:flapping_detect

This config controls the allowed maximum number of CONNECT packets received from the same clientid in a time frame defined by window_time. After the limit is reached, successive CONNECT requests are forbidden (banned) until the end of the time period defined by ban_time.

Config paths

  • zones.$name.flapping_detect

Env overrides

  • EMQX_ZONES__$NAME__FLAPPING_DETECT

Fields

  • enable: boolean()

    Enable flapping connection detection feature.

  • max_count: integer()

    The maximum number of disconnects allowed for a MQTT Client in window_time

  • window_time: emqx_schema:duration()

    The time window for flapping detection.

  • ban_time: emqx_schema:duration()

    How long the flapping clientid will be banned.

# zone:force_gc

Force garbage collection in MQTT connection process after they process certain number of messages or bytes of data.

Config paths

  • zones.$name.force_gc

Env overrides

  • EMQX_ZONES__$NAME__FORCE_GC

Fields

  • enable: boolean()

    Enable forced garbage collection.

  • count: 0..inf

    GC the process after this many received messages.

  • bytes: emqx_schema:bytesize()

    GC the process after specified number of bytes have passed through.

# zone:force_shutdown

When the process message queue length, or the memory bytes reaches a certain value, the process is forced to close.

Note: "message queue" here refers to the "message mailbox" of the Erlang process, not the mqueue of QoS 1 and QoS 2.

Config paths

  • zones.$name.force_shutdown

Env overrides

  • EMQX_ZONES__$NAME__FORCE_SHUTDOWN

Fields

  • enable: boolean()

    Enable force_shutdown feature.

  • max_message_queue_len: 0..inf

    Maximum message queue length.

  • max_heap_size: emqx_schema:wordsize()

    Total heap size

# zone:mqtt

Global MQTT configuration.
The configs here work as default values which can be overridden in zone configs

Config paths

  • zones.$name.mqtt

Env overrides

  • EMQX_ZONES__$NAME__MQTT

Fields

  • idle_timeout: infinity | emqx_schema:duration()

    After the TCP connection is established, if the MQTT CONNECT packet from the client is not received within the time specified by idle_timeout, the connection will be disconnected.

  • max_packet_size: emqx_schema:bytesize()

    Maximum MQTT packet size allowed.

  • max_clientid_len: 23..65535

    Maximum allowed length of MQTT Client ID.

  • max_topic_levels: 1..65535

    Maximum topic levels allowed.

  • max_qos_allowed: qos()

    Maximum QoS allowed.

  • max_topic_alias: 0..65535

    Maximum topic alias, 0 means no topic alias supported.

  • retain_available: boolean()

    Whether to enable support for MQTT retained message.

  • wildcard_subscription: boolean()

    Whether to enable support for MQTT wildcard subscription.

  • shared_subscription: boolean()

    Whether to enable support for MQTT shared subscription.

  • exclusive_subscription: boolean()

    Whether to enable support for MQTT exclusive subscription.

  • ignore_loop_deliver: boolean()

    Ignore loop delivery of messages for MQTT v3.1.1/v3.1.0, similar to No Local subscription option in MQTT 5.0

  • strict_mode: boolean()

    Parse MQTT messages in strict mode. When set to true, invalid utf8 strings in for example client ID, topic name, etc. will cause the client to be disconnected

  • response_information: string()

    Specify the response information returned to the client. This feature is disabled if is set to "". Applies only to clients using MQTT 5.0.

  • server_keepalive: integer() | disabled

    The keep alive that EMQX requires the client to use. If configured as disabled, it means that the keep alive specified by the client will be used. Requires Server Keep Alive in MQTT 5.0, so it is only applicable to clients using MQTT 5.0 protocol.

  • keepalive_backoff: number()

    The backoff multiplier used by the broker to determine the client keep alive timeout. If EMQX doesn't receive any packet in Keep Alive * Backoff * 2 seconds, EMQX will close the current connection.

  • max_subscriptions: 1..inf | infinity

    Maximum number of subscriptions allowed per client.

  • upgrade_qos: boolean()

    Force upgrade of QoS level according to subscription.

  • max_inflight: 1..65535

    Maximum number of QoS 1 and QoS 2 messages that are allowed to be delivered simultaneously before completing the acknowledgment.

  • retry_interval: emqx_schema:duration()

    Retry interval for QoS 1/2 message delivering.

  • max_awaiting_rel: integer() | infinity

    Maximum QoS 2 packets (Client -> Broker) awaiting PUBREL.

  • await_rel_timeout: emqx_schema:duration()

    The QoS 2 messages (Client -> Broker) will be dropped if awaiting PUBREL timeout.

  • session_expiry_interval: emqx_schema:duration()

    Specifies how long the session will expire after the connection is disconnected, only for non-MQTT 5.0 connections.

  • max_mqueue_len: non_neg_integer() | infinity

    Maximum queue length. Enqueued messages when persistent client disconnected, or inflight window is full.

  • mqueue_priorities: map() | disabled

    Topic priorities. Priority number [1-255] There's no priority table by default, hence all messages are treated equal.

    NOTE: Comma and equal signs are not allowed for priority topic names. NOTE: Messages for topics not in the priority table are treated as either highest or lowest priority depending on the configured value for mqtt.mqueue_default_priority.

    Examples: To configure "topic/1" > "topic/2": mqueue_priorities: {"topic/1": 10, "topic/2": 8}

  • mqueue_default_priority: highest | lowest

    Default topic priority, which will be used by topics not in Topic Priorities (mqueue_priorities).

  • mqueue_store_qos0: boolean()

    Specifies whether to store QoS 0 messages in the message queue while the connection is down but the session remains.

  • use_username_as_clientid: boolean()

    Whether to user Client ID as Username. This setting takes effect later than Use Peer Certificate as Username (peer_cert_as_username) and Use peer certificate as Client ID (peer_cert_as_clientid).

  • peer_cert_as_username: disabled | cn | dn | crt | pem | md5

    Use the CN, DN field in the peer certificate or the entire certificate content as Username. Only works for the TLS connection. Supported configurations are the following:

    • cn: Take the CN field of the certificate as Username
    • dn: Take the DN field of the certificate as Username
    • crt: Take the content of the DER or PEM certificate as Username
    • pem: Convert DER certificate content to PEM format as Username
    • md5: Take the MD5 value of the content of the DER or PEM certificate as Username
  • peer_cert_as_clientid: disabled | cn | dn | crt | pem | md5

    Use the CN, DN field in the peer certificate or the entire certificate content as Client ID. Only works for the TLS connection. Supported configurations are the following:

    • cn: Take the CN field of the certificate as Client ID
    • dn: Take the DN field of the certificate as Client ID
    • crt: Take the content of the DER or PEM certificate as Client ID
    • pem: Convert DER certificate content to PEM format as Client ID
    • md5: Take the MD5 value of the content of the DER or PEM certificate as Client ID

# zone:overload_protection

Overload protection mechanism monitors the load of the system and temporarily disables some features (such as accepting new connections) when the load is high.

Config paths

  • zones.$name.overload_protection

Env overrides

  • EMQX_ZONES__$NAME__OVERLOAD_PROTECTION

Fields

  • enable: boolean()

    React on system overload or not

  • backoff_delay: 0..inf

    Some unimportant tasks could be delayed for execution, here set the delays in ms

  • backoff_gc: boolean()

    Skip forceful GC if necessary

  • backoff_hibernation: boolean()

    Skip process hibernation if necessary

  • backoff_new_conn: boolean()

    Close new incoming connections if necessary

# zone:stats

Enable/disable statistic data collection. Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.

Config paths

  • zones.$name.stats

Env overrides

  • EMQX_ZONES__$NAME__STATS

Fields

  • enable: boolean()

    Enable/disable statistic data collection.

# authn-builtin_db:authentication

Configuration of authenticator using built-in database as data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: built_in_database

    Backend type.

  • user_id_type: clientid | username

    • default: "username"

    Specify whether to use clientid or username for authentication.

  • password_hash_algorithm: authn-hash:bcrypt_rw | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash creation and verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

# authn-hash:bcrypt

Settings for bcrypt password hashing algorithm.

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: bcrypt

    BCRYPT password hashing.

# authn-hash:bcrypt_rw

Settings for bcrypt password hashing algorithm (for DB backends with write capability).

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: bcrypt

    BCRYPT password hashing.

  • salt_rounds: integer()

    • default: 10

    Salt rounds for BCRYPT password generation.

# authn-hash:other_algorithms

Settings for other password hashing algorithms.

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: plain | md5 | sha | sha256 | sha512

    Simple password hashing algorithm.

  • salt_position: disable | prefix | suffix

    • default: prefix

    Salt position for PLAIN, MD5, SHA, SHA256 and SHA512 algorithms.

# authn-hash:pbkdf2

Settings for PBKDF2 password hashing algorithm.

Config paths

  • authentication.$INDEX.password_hash_algorithm
  • gateway.coap.authentication.password_hash_algorithm
  • gateway.coap.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.coap.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.exproto.authentication.password_hash_algorithm
  • gateway.exproto.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.tcp.$name.authentication.password_hash_algorithm
  • gateway.exproto.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.lwm2m.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.dtls.$name.authentication.password_hash_algorithm
  • gateway.mqttsn.listeners.udp.$name.authentication.password_hash_algorithm
  • gateway.stomp.authentication.password_hash_algorithm
  • gateway.stomp.listeners.ssl.$name.authentication.password_hash_algorithm
  • gateway.stomp.listeners.tcp.$name.authentication.password_hash_algorithm
  • listeners.ssl.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.tcp.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.ws.$name.authentication.$INDEX.password_hash_algorithm
  • listeners.wss.$name.authentication.$INDEX.password_hash_algorithm

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__PASSWORD_HASH_ALGORITHM

Fields

  • name: pbkdf2

    PBKDF2 password hashing.

  • mac_fun: md4 | md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512

    Specifies mac_fun for PBKDF2 hashing algorithm.

  • iterations: integer()

    Iteration count for PBKDF2 hashing algorithm.

  • dk_length: integer()

    Derived length for PBKDF2 hashing algorithm. If not specified, calculated automatically based on mac_fun.

# authn-http:get

Configuration of authenticator using HTTP Server as authentication service (Using GET request).

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • method: get

    • default: get

    HTTP request method.

  • headers: map()

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6

    List of HTTP headers (without content-type).

  • mechanism: password_based

    Authentication mechanism.

  • backend: http

    Backend type.

  • url: binary()

    URL of the HTTP server.

  • body: #{term() => binary()}

    HTTP request body.

  • request_timeout: emqx_schema:duration_ms()

    • default: "5s"

    HTTP request timeout.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    The timeout when connecting to the HTTP server.

  • enable_pipelining: pos_integer()

    • default: 100

    A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

  • max_retries: non_neg_integer()

    • default: 5

    Max retry times if error on sending request.

  • pool_size: pos_integer()

    • default: 8

    The pool size.

  • request: connector-http:request

    If the request is provided, the caller can send HTTP requests via emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    Interval between retries.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-http:post

Configuration of authenticator using HTTP Server as authentication service (Using POST request).

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • method: post

    • default: post

    HTTP request method.

  • headers: map()

    • default:
    {
      accept = "application/json"
      "cache-control" = "no-cache"
      connection = "keep-alive"
      "content-type" = "application/json"
      "keep-alive" = "timeout=30, max=1000"
    }
    
    1
    2
    3
    4
    5
    6
    7

    List of HTTP Headers.

  • mechanism: password_based

    Authentication mechanism.

  • backend: http

    Backend type.

  • url: binary()

    URL of the HTTP server.

  • body: #{term() => binary()}

    HTTP request body.

  • request_timeout: emqx_schema:duration_ms()

    • default: "5s"

    HTTP request timeout.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • connect_timeout: emqx_schema:duration_ms()

    • default: "15s"

    The timeout when connecting to the HTTP server.

  • enable_pipelining: pos_integer()

    • default: 100

    A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

  • max_retries: non_neg_integer()

    • default: 5

    Max retry times if error on sending request.

  • pool_size: pos_integer()

    • default: 8

    The pool size.

  • request: connector-http:request

    If the request is provided, the caller can send HTTP requests via emqx_resource:query(ResourceId, {send_message, BridgeId, Message})

  • retry_interval: emqx_schema:duration()

    • default: "1s"

    Interval between retries.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-jwt:hmac-based

Configuration when the JWT for authentication is issued using the HMAC algorithm.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • use_jwks: false

    Whether to use JWKS.

  • algorithm: hmac-based

    JWT signing algorithm, Supports HMAC (configured as hmac-based) and RSA, ECDSA (configured as public-key).

  • secret: binary()

    The key to verify the JWT using HMAC algorithm.

  • secret_base64_encoded: boolean()

    • default: false

    Whether secret is base64 encoded.

  • mechanism: jwt

    Authentication mechanism.

  • acl_claim_name: binary()

    • default: "acl"

    JWT claim name to use for getting ACL rules.

  • verify_claims: [term()]

    • default: {}

    A list of custom claims to validate, which is a list of name/value pairs. Values can use the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.
  • from: username | password

    • default: password

    Field to take JWT from.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

# authn-jwt:jwks

Configuration when JWTs used for authentication need to be fetched from the JWKS endpoint.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • use_jwks: true

    Whether to use JWKS.

  • endpoint: string()

    JWKS endpoint, it's a read-only endpoint that returns the server's public key set in the JWKS format.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • refresh_interval: integer()

    • default: 300

    JWKS refresh interval.

  • ssl: authn-jwt:ssl_enable | authn-jwt:ssl_disable

    • default: {enable = false}

    SSL options.

  • mechanism: jwt

    Authentication mechanism.

  • acl_claim_name: binary()

    • default: "acl"

    JWT claim name to use for getting ACL rules.

  • verify_claims: [term()]

    • default: {}

    A list of custom claims to validate, which is a list of name/value pairs. Values can use the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.
  • from: username | password

    • default: password

    Field to take JWT from.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

# authn-jwt:public-key

Configuration when the JWT for authentication is issued using RSA or ECDSA algorithm.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • use_jwks: false

    Whether to use JWKS.

  • algorithm: public-key

    JWT signing algorithm, Supports HMAC (configured as hmac-based) and RSA, ECDSA (configured as public-key).

  • public_key: string()

    The public key used to verify the JWT.

  • mechanism: jwt

    Authentication mechanism.

  • acl_claim_name: binary()

    • default: "acl"

    JWT claim name to use for getting ACL rules.

  • verify_claims: [term()]

    • default: {}

    A list of custom claims to validate, which is a list of name/value pairs. Values can use the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.
  • from: username | password

    • default: password

    Field to take JWT from.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

# authn-jwt:ssl_disable

SSL configuration.

Config paths

  • authentication.$INDEX.ssl
  • gateway.coap.authentication.ssl
  • gateway.coap.listeners.dtls.$name.authentication.ssl
  • gateway.coap.listeners.udp.$name.authentication.ssl
  • gateway.exproto.authentication.ssl
  • gateway.exproto.listeners.dtls.$name.authentication.ssl
  • gateway.exproto.listeners.ssl.$name.authentication.ssl
  • gateway.exproto.listeners.tcp.$name.authentication.ssl
  • gateway.exproto.listeners.udp.$name.authentication.ssl
  • gateway.lwm2m.authentication.ssl
  • gateway.lwm2m.listeners.dtls.$name.authentication.ssl
  • gateway.lwm2m.listeners.udp.$name.authentication.ssl
  • gateway.mqttsn.authentication.ssl
  • gateway.mqttsn.listeners.dtls.$name.authentication.ssl
  • gateway.mqttsn.listeners.udp.$name.authentication.ssl
  • gateway.stomp.authentication.ssl
  • gateway.stomp.listeners.ssl.$name.authentication.ssl
  • gateway.stomp.listeners.tcp.$name.authentication.ssl
  • listeners.ssl.$name.authentication.$INDEX.ssl
  • listeners.tcp.$name.authentication.$INDEX.ssl
  • listeners.ws.$name.authentication.$INDEX.ssl
  • listeners.wss.$name.authentication.$INDEX.ssl

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__SSL
  • EMQX_GATEWAY__COAP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__SSL

Fields

  • enable: false

    Enable/disable SSL.

# authn-jwt:ssl_enable

SSL configuration.

Config paths

  • authentication.$INDEX.ssl
  • gateway.coap.authentication.ssl
  • gateway.coap.listeners.dtls.$name.authentication.ssl
  • gateway.coap.listeners.udp.$name.authentication.ssl
  • gateway.exproto.authentication.ssl
  • gateway.exproto.listeners.dtls.$name.authentication.ssl
  • gateway.exproto.listeners.ssl.$name.authentication.ssl
  • gateway.exproto.listeners.tcp.$name.authentication.ssl
  • gateway.exproto.listeners.udp.$name.authentication.ssl
  • gateway.lwm2m.authentication.ssl
  • gateway.lwm2m.listeners.dtls.$name.authentication.ssl
  • gateway.lwm2m.listeners.udp.$name.authentication.ssl
  • gateway.mqttsn.authentication.ssl
  • gateway.mqttsn.listeners.dtls.$name.authentication.ssl
  • gateway.mqttsn.listeners.udp.$name.authentication.ssl
  • gateway.stomp.authentication.ssl
  • gateway.stomp.listeners.ssl.$name.authentication.ssl
  • gateway.stomp.listeners.tcp.$name.authentication.ssl
  • listeners.ssl.$name.authentication.$INDEX.ssl
  • listeners.tcp.$name.authentication.$INDEX.ssl
  • listeners.ws.$name.authentication.$INDEX.ssl
  • listeners.wss.$name.authentication.$INDEX.ssl

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__SSL
  • EMQX_GATEWAY__COAP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__SSL
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__SSL
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__SSL
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__SSL

Fields

  • enable: true

    Enable/disable SSL.

  • cacertfile: string()

    Path to a file containing PEM-encoded CA certificates.

  • certfile: string()

    Path to a file containing the user certificate.

  • keyfile: string()

    Path to a file containing the user's private PEM-encoded key.

  • verify: verify_peer | verify_none

    • default: verify_none

    Enable or disable SSL peer verification.

  • server_name_indication: string()

    Server Name Indication (SNI).

# authn-mongodb:replica-set

Configuration of authenticator using MongoDB (Replica Set) as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: mongodb

    Backend type.

  • collection: binary()

    Collection used to store authentication data.

  • filter: map()

    • default: {}

    Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
  • password_hash_field: binary()

    • default: "password_hash"

    Document field that contains password hash.

  • salt_field: binary()

    • default: "salt"

    Document field that contains the password salt.

  • is_superuser_field: binary()

    • default: "is_superuser"

    Document field that defines if the user has superuser privileges.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • mongo_type: rs

    • default: rs

    Replica set.

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • w_mode: unsafe | safe

    • default: unsafe

    Write mode.

  • r_mode: master | slave_ok

    • default: master

    Read mode.

  • replica_set_name: binary()

    Name of the replica set.

  • srv_record: boolean()

    • default: false

    Use DNS SRV record.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auth_source: binary()

    Database name associated with the user's credentials.

  • database: binary()

    Database name.

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-mongodb:sharded-cluster

Configuration of authenticator using MongoDB (Sharded Cluster) as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: mongodb

    Backend type.

  • collection: binary()

    Collection used to store authentication data.

  • filter: map()

    • default: {}

    Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
  • password_hash_field: binary()

    • default: "password_hash"

    Document field that contains password hash.

  • salt_field: binary()

    • default: "salt"

    Document field that contains the password salt.

  • is_superuser_field: binary()

    • default: "is_superuser"

    Document field that defines if the user has superuser privileges.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • mongo_type: sharded

    • default: sharded

    Sharded cluster.

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • w_mode: unsafe | safe

    • default: unsafe

    Write mode.

  • srv_record: boolean()

    • default: false

    Use DNS SRV record.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auth_source: binary()

    Database name associated with the user's credentials.

  • database: binary()

    Database name.

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-mongodb:standalone

Configuration of authenticator using MongoDB (Standalone) as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: mongodb

    Backend type.

  • collection: binary()

    Collection used to store authentication data.

  • filter: map()

    • default: {}

    Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:

    • ${username}: Will be replaced at runtime with Username used by the client when connecting
    • ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
  • password_hash_field: binary()

    • default: "password_hash"

    Document field that contains password hash.

  • salt_field: binary()

    • default: "salt"

    Document field that contains the password salt.

  • is_superuser_field: binary()

    • default: "is_superuser"

    Document field that defines if the user has superuser privileges.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • mongo_type: single

    • default: single

    Standalone instance.

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The MongoDB default port 27017 is used if [:Port] is not specified.

  • w_mode: unsafe | safe

    • default: unsafe

    Write mode.

  • srv_record: boolean()

    • default: false

    Use DNS SRV record.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auth_source: binary()

    Database name associated with the user's credentials.

  • database: binary()

    Database name.

  • topology: topology

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-mysql:authentication

Configuration of authenticator using MySQL as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: mysql

    Backend type.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • query: string()

    SQL used to query data for authentication, such as password hash.

  • query_timeout: emqx_schema:duration_ms()

    • default: "5s"

    Timeout for the SQL query.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The MySQL default port 3306 is used if [:Port] is not specified.

  • database: binary()

    Database name.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-postgresql:authentication

Configuration of authenticator using PostgreSQL as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: postgresql

    Backend type.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • query: string()

    SQL used to query data for authentication, such as password hash.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The PostgreSQL default port 5432 is used if [:Port] is not specified.

  • database: binary()

    Database name.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • username: binary()

    EMQX's username in the external database.

  • password: binary()

    EMQX's password in the external database.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-psk:psk_authentication

PSK stands for 'Pre-Shared Keys'. This config to enable TLS-PSK authentication.

Important! Make sure the SSL listener with only tlsv1.2 enabled, and also PSK cipher suites configured, such as RSA-PSK-AES256-GCM-SHA384.

See listener SSL options config for more details.

The IDs and secrets can be provided from a file which is configurable by the init_file field.

Config paths

  • psk_authentication

Env overrides

  • EMQX_PSK_AUTHENTICATION

Fields

  • enable: boolean()

    • default: false

    Whether to enable TLS PSK support

  • init_file: binary()

    If init_file is specified, EMQX will import PSKs from the file into the built-in database at startup for use by the runtime. The file has to be structured line-by-line, each line must be in the format of PSKIdentity:SharedSecret. For example: mydevice1:c2VjcmV0

  • separator: binary()

    • default: ":"

    The separator between PSKIdentity and SharedSecret in the PSK file

  • chunk_size: integer()

    • default: 50

    The size of each chunk used to import to the built-in database from PSK file

# authn-redis:cluster

Configuration of authenticator using Redis (Cluster) as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: redis

    Backend type.

  • cmd: string()

    The Redis Command used to query data for authentication such as password hash, currently only supports HGET and HMGET.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • redis_type: cluster

    Cluster mode

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • password: binary()

    EMQX's password in the external database.

  • database: integer()

    • default: 0

    Redis database ID.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-redis:sentinel

Configuration of authenticator using Redis (Sentinel) as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: redis

    Backend type.

  • cmd: string()

    The Redis Command used to query data for authentication such as password hash, currently only supports HGET and HMGET.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • servers: [term()]

    A Node list for Cluster to connect to. The nodes should be separated with commas, such as: Node[,Node]. For each Node should be: The IPv4 or IPv6 address or the hostname to connect to. A host entry has the following form: Host[:Port]. The MongoDB default port 27017 is used if [:Port] is not specified.

  • redis_type: sentinel

    Sentinel mode

  • sentinel: string()

    The cluster name in Redis sentinel mode.

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • password: binary()

    EMQX's password in the external database.

  • database: integer()

    • default: 0

    Redis database ID.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-redis:standalone

Configuration of authenticator using Redis (Standalone) as authentication data source.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: password_based

    Authentication mechanism.

  • backend: redis

    Backend type.

  • cmd: string()

    The Redis Command used to query data for authentication such as password hash, currently only supports HGET and HMGET.

  • password_hash_algorithm: authn-hash:bcrypt | authn-hash:pbkdf2 | authn-hash:other_algorithms

    • default: {name = sha256, salt_position = prefix}

    Options for password hash verification.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

  • server: emqx_schema:ip_port()

    The IPv4 or IPv6 address or the hostname to connect to.
    A host entry has the following form: Host[:Port].
    The Redis default port 6379 is used if [:Port] is not specified.

  • redis_type: single

    Single mode

  • pool_size: pos_integer()

    • default: 8

    Size of the connection pool.

  • password: binary()

    EMQX's password in the external database.

  • database: integer()

    • default: 0

    Redis database ID.

  • auto_reconnect: boolean()

    • default: true

    Enable automatic reconnect to the database.

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# authn-scram-builtin_db:authentication

Settings for Salted Challenge Response Authentication Mechanism (SCRAM) authentication.

Config paths

  • authentication.$INDEX
  • gateway.coap.authentication
  • gateway.coap.listeners.dtls.$name.authentication
  • gateway.coap.listeners.udp.$name.authentication
  • gateway.exproto.authentication
  • gateway.exproto.listeners.dtls.$name.authentication
  • gateway.exproto.listeners.ssl.$name.authentication
  • gateway.exproto.listeners.tcp.$name.authentication
  • gateway.exproto.listeners.udp.$name.authentication
  • gateway.lwm2m.authentication
  • gateway.lwm2m.listeners.dtls.$name.authentication
  • gateway.lwm2m.listeners.udp.$name.authentication
  • gateway.mqttsn.authentication
  • gateway.mqttsn.listeners.dtls.$name.authentication
  • gateway.mqttsn.listeners.udp.$name.authentication
  • gateway.stomp.authentication
  • gateway.stomp.listeners.ssl.$name.authentication
  • gateway.stomp.listeners.tcp.$name.authentication
  • listeners.ssl.$name.authentication.$INDEX
  • listeners.tcp.$name.authentication.$INDEX
  • listeners.ws.$name.authentication.$INDEX
  • listeners.wss.$name.authentication.$INDEX

Env overrides

  • EMQX_AUTHENTICATION__$INDEX
  • EMQX_GATEWAY__COAP__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX

Fields

  • mechanism: scram

    Authentication mechanism.

  • backend: built_in_database

    Backend type.

  • algorithm: sha256 | sha512

    • default: sha256

    Hashing algorithm.

  • iteration_count: non_neg_integer()

    • default: 4096

    Iteration count.

  • enable: boolean()

    • default: true

    Set to true or false to disable this auth provider.

# auto_subscribe

After the device logs in successfully, the subscription is automatically completed for the device through the pre-defined subscription representation. Supports the use of placeholders.

Config paths

  • auto_subscribe

Env overrides

  • EMQX_AUTO_SUBSCRIBE

Fields

  • topics: [auto_subscribe:topic]

    • default: []

    After the device logs in successfully, the subscription is automatically completed for the device through the pre-defined subscription representation. Supports the use of placeholders.

# auto_subscribe:topic

Topic name, placeholders are supported. For example: client/${clientid}/username/${username}/host/${host}/port/${port} Required field, and cannot be empty string

Config paths

  • auto_subscribe.topics.$INDEX

Env overrides

  • EMQX_AUTO_SUBSCRIBE__TOPICS__$INDEX

Fields

  • topic: binary()

    Topic name, placeholders are supported. For example: client/${clientid}/username/${username}/host/${host}/port/${port} Required field, and cannot be empty string

  • qos: qos()

    • default: 0

    Default value 0. Quality of service. At most once (0) At least once (1) Exactly once (2)

  • rh: 0..2

    • default: 0

    Default value 0. This option is used to specify whether the server forwards the retained message to the client when establishing a subscription. Retain Handling is equal to 0, as long as the client successfully subscribes, the server will send the retained message. Retain Handling is equal to 1, if the client successfully subscribes and this subscription does not exist previously, the server sends the retained message. After all, sometimes the client re-initiate the subscription just to change the QoS, but it does not mean that it wants to receive the reserved messages again. Retain Handling is equal to 2, even if the client successfully subscribes, the server does not send the retained message.

  • rap: 0..1

    • default: 0

    Default value 0. This option is used to specify whether the server retains the RETAIN mark when forwarding messages to the client, and this option does not affect the RETAIN mark in the retained message. Therefore, when the option Retain As Publish is set to 0, the client will directly distinguish whether this is a normal forwarded message or a retained message according to the RETAIN mark in the message, instead of judging whether this message is the first received after subscribing(the forwarded message may be sent before the retained message, which depends on the specific implementation of different brokers).

  • nl: 0..1

    • default: 0

    Default value 0. MQTT v3.1.1: if you subscribe to the topic published by yourself, you will receive all messages that you published. MQTT v5: if you set this option as 1 when subscribing, the server will not forward the message you published to you.

# bridge:bridges

Configuration for MQTT bridges.

Config paths

  • bridges

Env overrides

  • EMQX_BRIDGES

Fields

  • webhook: {$name -> bridge:config}

    WebHook to an HTTP server.

  • mqtt: {$name -> ingress | egress}

    MQTT bridges to/from another MQTT broker

# connector-http:request

Config paths

  • authentication.$INDEX.request
  • authorization.sources.$INDEX.request
  • bridges.webhook.$name.request
  • gateway.coap.authentication.request
  • gateway.coap.listeners.dtls.$name.authentication.request
  • gateway.coap.listeners.udp.$name.authentication.request
  • gateway.exproto.authentication.request
  • gateway.exproto.listeners.dtls.$name.authentication.request
  • gateway.exproto.listeners.ssl.$name.authentication.request
  • gateway.exproto.listeners.tcp.$name.authentication.request
  • gateway.exproto.listeners.udp.$name.authentication.request
  • gateway.lwm2m.authentication.request
  • gateway.lwm2m.listeners.dtls.$name.authentication.request
  • gateway.lwm2m.listeners.udp.$name.authentication.request
  • gateway.mqttsn.authentication.request
  • gateway.mqttsn.listeners.dtls.$name.authentication.request
  • gateway.mqttsn.listeners.udp.$name.authentication.request
  • gateway.stomp.authentication.request
  • gateway.stomp.listeners.ssl.$name.authentication.request
  • gateway.stomp.listeners.tcp.$name.authentication.request
  • listeners.ssl.$name.authentication.$INDEX.request
  • listeners.tcp.$name.authentication.$INDEX.request
  • listeners.ws.$name.authentication.$INDEX.request
  • listeners.wss.$name.authentication.$INDEX.request

Env overrides

  • EMQX_AUTHENTICATION__$INDEX__REQUEST
  • EMQX_AUTHORIZATION__SOURCES__$INDEX__REQUEST
  • EMQX_BRIDGES__WEBHOOK__$NAME__REQUEST
  • EMQX_GATEWAY__COAP__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__COAP__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__COAP__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__SSL__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__TCP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__EXPROTO__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__LWM2M__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__LWM2M__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__LWM2M__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__MQTTSN__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__MQTTSN__LISTENERS__DTLS__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__MQTTSN__LISTENERS__UDP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__STOMP__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__STOMP__LISTENERS__SSL__$NAME__AUTHENTICATION__REQUEST
  • EMQX_GATEWAY__STOMP__LISTENERS__TCP__$NAME__AUTHENTICATION__REQUEST
  • EMQX_LISTENERS__SSL__$NAME__AUTHENTICATION__$INDEX__REQUEST
  • EMQX_LISTENERS__TCP__$NAME__AUTHENTICATION__$INDEX__REQUEST
  • EMQX_LISTENERS__WS__$NAME__AUTHENTICATION__$INDEX__REQUEST
  • EMQX_LISTENERS__WSS__$NAME__AUTHENTICATION__$INDEX__REQUEST

Fields

  • method: post | put | get | delete

    HTTP method.

  • path: binary()

    URL path.

  • body: binary()

    HTTP request body.

  • headers: map()

    List of HTTP headers.

  • request_timeout: emqx_schema:duration_ms()

    HTTP request timeout.

# connector-mqtt:connector

Generic configuration for the connector.

Config paths

  • bridges.mqtt.$name.connector
  • connectors.mqtt.$name

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME__CONNECTOR
  • EMQX_CONNECTORS__MQTT__$NAME

Fields

  • mode: cluster_shareload

    • default: cluster_shareload

    The mode of the MQTT Bridge. Can be one of 'cluster_singleton' or 'cluster_shareload'

    • cluster_singleton: create a unique MQTT connection within the emqx cluster.
      In 'cluster_singleton' node, all messages toward the remote broker go through the same MQTT connection.
    • cluster_shareload: create an MQTT connection on each node in the emqx cluster.
      In 'cluster_shareload' mode, the incoming load from the remote broker is shared by using shared subscription.
      Note that the 'clientid' is suffixed by the node name, this is to avoid clientid conflicts between different nodes. And we can only use shared subscription topic filters for 'remote_topic' of ingress connections.
  • server: emqx_schema:ip_port()

    The host and port of the remote MQTT broker

  • reconnect_interval: string()

    • default: "15s"

    Reconnect interval. Delay for the MQTT bridge to retry establishing the connection in case of transportation failure. Time interval is a string that contains a number followed by time unit:

    • ms for milliseconds,
    • s for seconds,
    • m for minutes,
    • h for hours;
      or combination of whereof: 1h5m0s
  • proto_ver: v3 | v4 | v5

    • default: v4

    The MQTT protocol version

  • bridge_mode: boolean()

    • default: false

    If enable bridge mode. NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT broker MUST support this feature.

  • username: binary()

    • default: "emqx"

    The username of the MQTT protocol

  • password: binary()

    • default: "emqx"

    The password of the MQTT protocol

  • clean_start: boolean()

    • default: true

    The clean-start or the clean-session of the MQTT protocol

  • keepalive: string()

    • default: "300s"

    MQTT Keepalive. Time interval is a string that contains a number followed by time unit:

    • ms for milliseconds,
    • s for seconds,
    • m for minutes,
    • h for hours;
      or combination of whereof: 1h5m0s
  • retry_interval: string()

    • default: "15s"

    Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:

    • ms for milliseconds,
    • s for seconds,
    • m for minutes,
    • h for hours;
      or combination of whereof: 1h5m0s
  • max_inflight: non_neg_integer()

    • default: 32

    Max inflight (sent, but un-acked) messages of the MQTT protocol

  • replayq: connector-mqtt:replayq

  • ssl: broker:ssl_client_opts

    • default: {enable = false}

    SSL connection settings.

# connector-mqtt:replayq

Queue messages in disk files.

Config paths

  • bridges.mqtt.$name.connector.replayq
  • connectors.mqtt.$name.replayq

Env overrides

  • EMQX_BRIDGES__MQTT__$NAME__CONNECTOR__REPLAYQ
  • EMQX_CONNECTORS__MQTT__$NAME__REPLAYQ

Fields

  • dir: boolean() | string()

    The dir where the replayq file saved.
    Set to 'false' disables the replayq feature.

  • seg_bytes: emqx_schema:bytesize()

    • default: "100MB"

    The size in bytes of a single segment.
    A segment is mapping to a file in the replayq dir. If the current segment is full, a new segment (file) will be opened to write.

  • offload: boolean()

    • default: false

    In offload mode, the disk queue is only used to offload queue tail segments.
    The messages are cached in the memory first, then it writes to the replayq files after the size of the memory cache reaches 'seg_bytes'.

# plugin:plugins

Manage EMQX plugins.
Plugins can be pre-built as a part of EMQX package, or installed as a standalone package in a location specified by install_dir config key
The standalone-installed plugins are referred to as 'external' plugins.

Config paths

  • plugins

Env overrides

  • EMQX_PLUGINS

Fields

  • states: [plugin:state]

    • default: []

    An array of plugins in the desired states.
    The plugins are started in the defined order

  • install_dir: string()

    • default: "plugins"

    The installation directory for the external plugins. The plugin beam files and configuration files should reside in the subdirectory named as emqx_foo_bar-0.1.0.
    NOTE: For security reasons, this directory should NOT be writable by anyone except emqx (or any user which runs EMQX).

  • check_interval: emqx_schema:duration()

    • default: "5s"

    Check interval: check if the status of the plugins in the cluster is consistent,
    if the results of 3 consecutive checks are not consistent, then alarm.

# plugin:state

A per-plugin config to describe the desired state of the plugin.

Config paths

  • plugins.states.$INDEX

Env overrides

  • EMQX_PLUGINS__STATES__$INDEX

Fields

  • name_vsn: string()

    The {name}-{version} of the plugin.
    It should match the plugin application name-version as the for the plugin release package name
    For example: my_plugin-0.1.0.

  • enable: boolean()

    Set to 'true' to enable this plugin

# prometheus

Settings for reporting metrics to Prometheus

Config paths

  • prometheus

Env overrides

  • EMQX_PROMETHEUS

Fields

  • push_gateway_server: string()

    • default: "http://127.0.0.1:9091"

    URL of Prometheus server

  • interval: emqx_schema:duration_ms()

    • default: "15s"

    Data reporting interval, in milliseconds.

  • enable: boolean()

    • default: false

    Turn Prometheus data pushing on or off

# retainer:flow_control

Retainer batching and rate limiting.

Config paths

  • retainer.flow_control

Env overrides

  • EMQX_RETAINER__FLOW_CONTROL

Fields

  • batch_read_number: non_neg_integer()

    • default: 0

    Size of the batch when reading messages from storage. 0 means no limit.

  • batch_deliver_number: 0..1000

    • default: 0

    The number of retained messages can be delivered per batch.

  • batch_deliver_limiter: emqx_limiter_schema:bucket_name()

    The rate limiter name for retained messages' delivery. Limiter helps to avoid delivering too many messages to the client at once, which may cause the client to block or crash, or drop messages due to exceeding the size of the message queue. The names of the available rate limiters are taken from the existing rate limiters under limiter.batch. If this field is empty, limiter is not used.

# retainer:mnesia_config

Configuration of the internal database storing retained messages.

Config paths

  • retainer.backend

Env overrides

  • EMQX_RETAINER__BACKEND

Fields

  • type: built_in_database

    • default: built_in_database

    Backend type.

  • storage_type: ram | disc

    • default: ram

    Specifies whether the messages are stored in RAM or persisted on disc.

  • max_retained_messages: non_neg_integer()

    • default: 0

    Maximum number of retained messages. 0 means no limit.

  • index_specs: [[integer()]]

    • default:
    [
      [1, 2, 3],
      [1, 3],
      [2, 3],
      [3]
    ]
    
    1
    2
    3
    4
    5
    6

    Retainer index specifications: list of arrays of positive ascending integers. Each array specifies an index. Numbers in an index specification are 1-based word positions in topics. Words from specified positions will be used for indexing.
    For example, it is good to have [2, 4] index to optimize +/X/+/Y/... topic wildcard subscriptions.

# retainer

Configuration related to handling PUBLISH packets with a retain flag set to 1.

Config paths

  • retainer

Env overrides

  • EMQX_RETAINER

Fields

  • enable: boolean()

    • default: true

    Enable retainer feature

  • msg_expiry_interval: emqx_schema:duration_ms()

    • default: "0s"

    Message retention time. 0 means message will never be expired.

  • msg_clear_interval: emqx_schema:duration_ms()

    • default: "0s"

    Periodic interval for cleaning up expired messages. Never clear if the value is 0.

  • flow_control: retainer:flow_control

    Flow control.

  • max_payload_size: emqx_schema:bytesize()

    • default: "1MB"

    Maximum retained message size.

  • stop_publish_clear_msg: boolean()

    • default: false

    When the retained flag of the PUBLISH message is set and Payload is empty, whether to continue to publish the message. See: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718038

  • backend: retainer:mnesia_config

    Settings for the database storing the retained messages.

# slow_subs

Configuration for slow_subs feature.

Config paths

  • slow_subs

Env overrides

  • EMQX_SLOW_SUBS

Fields

  • enable: boolean()

    • default: false

    Enable this feature

  • threshold: emqx_schema:duration_ms()

    • default: "500ms"

    The latency threshold for statistics

  • expire_interval: emqx_schema:duration_ms()

    • default: "300s"

    The eviction time of the record, which in the statistics record table

  • top_k_num: pos_integer()

    • default: 10

    The maximum number of records in the slow subscription statistics record table

  • stats_type: whole | internal | response

    • default: whole

    The method to calculate the latency

# statsd

Settings for reporting metrics to Statsd

Config paths

  • statsd

Env overrides

  • EMQX_STATSD

Fields

  • enable: boolean()

    • default: false

    Turn Statsd data pushing on or off

  • server: emqx_schema:ip_port()

    • default: "127.0.0.1:8125"

    URL of Statsd server

  • sample_time_interval: emqx_schema:duration_ms()

    • default: "10s"

    Data collection interval in second.

  • flush_time_interval: emqx_schema:duration_ms()

    • default: "10s"

    Data reporting interval, in second.

What’s on this page