# Configuration Manual

# Root Config Keys

Fields

listeners: broker:listeners
zones: {$name -> broker:zone}
A zone is a set of configs grouped by the zone name. For flexible configuration mapping, the name can be set to a listener's zone config. NOTE: A built-in zone named default is auto created and can not be deleted.
mqtt: broker:mqtt
Global MQTT configuration. The configs here work as default values which can be overridden in zone configs
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 MQTT listeners.
For per-listener overrides see authentication in listener configs
This option can be configured with:
- []: The default value, it allows ALL logins
- one: For example {enable:true,backend:"built_in_database",mechanism="password_based"}
- chain: An array of structs.
When a chain is configured, the login credentials are checked against the backends per the configured order, until an 'allow' or 'deny' decision can be made.
If there is no decision after a full chain exhaustion, the login is rejected.
authorization: authorization
Authorization a.k.a. ACL.
In EMQX, MQTT client access control is extremely flexible.
An out-of-the-box set of authorization data sources are supported. For example,
'file' source is to support concise and yet generic ACL rules in a file;
'built_in_database' source can be used to store per-client customizable rule sets, natively in the EMQX node;
'http' source to make EMQX call an external HTTP API to make the decision;
'PostgreSQL' etc. to look up clients or rules from external databases;
node: node
cluster: cluster
log: log
rpc: rpc
broker: broker
Message broker options.
sys_topics: broker:sys_topics
System topics configuration.
force_shutdown: broker:force_shutdown
overload_protection: broker:overload_protection
force_gc: broker:force_gc
conn_congestion: broker:conn_congestion
stats: broker:stats
sysmon: broker:sysmon
alarm: broker:alarm
flapping_detect: broker:flapping_detect
persistent_session_store: broker:persistent_session_store
trace: broker:trace
bridges: bridge:bridges
retainer: retainer
statsd: statsd
auto_subscribe: auto_subscribe
delayed: modules:delayed
telemetry: modules:telemetry
rewrite: [modules:rewrite]
List of topic rewrite rules.
topic_metrics: [modules:topic_metrics]
List of topics whose metrics are reported.
plugins: plugin:plugins
dashboard: dashboard
gateway: gateway
prometheus: prometheus
rule_engine: rule_engine
exhook: exhook
psk_authentication: authn-psk:psk_authentication
limiter: limiter
slow_subs: slow_subs

# 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()
Deprecated since 5.0.4.
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()
Deprecated since 5.0.4.
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()
Deprecated since 5.0.4.
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()
Deprecated since 5.0.4.
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:host_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:host_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:host_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
- default: cluster
Cluster mode
pool_size: pos_integer()
- default: 8
Size of the connection pool.
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.
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
- default: 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:host_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
- default: 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 | round_robin_per_group | 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_durationmilliseconds 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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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
gc_after_handshake: boolean()
- default: false
Memory usage tuning. If enabled, will immediately perform a garbage collection after the TLS/SSL handshake.

# 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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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

tcp: {$name -> broker:mqtt_tcp_listener}
TCP listeners.
ssl: {$name -> broker:mqtt_ssl_listener}
SSL listeners.
ws: {$name -> broker:mqtt_ws_listener}
HTTP websocket listeners.
wss: {$name -> broker:mqtt_wss_listener}
HTTPS websocket listeners.
quic: {$name -> broker:mqtt_quic_listener}
QUIC listeners.

# 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: 128
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
For each publisher session, the maximum number of outstanding QoS 2 messages pending on the client to send PUBREL. After reaching this limit, new QoS 2 PUBLISH requests will be rejected with 147(0x93) until either PUBREL is received or timed out.
await_rel_timeout: emqx_schema:duration()
- default: "300s"
For client to broker QoS 2 message, the time limit for the broker to wait before the PUBREL message is received. The wait is aborted after timed out, meaning the packet ID is freed for new PUBLISH requests. Receiving a stale PUBREL causes a warning level log. Note, the message is delivered to subscribers before entering the wait for PUBREL.
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_ms()
- default: 0
How long a connection can go idle before it is gracefully shut down. 0 to disable
handshake_idle_timeout: emqx_schema:duration_ms()
- default: "10s"
How long a handshake can idle before it is discarded.
keep_alive_interval: emqx_schema:duration_ms()
- default: 0
How often to send PING frames to keep a connection alive. 0 means disabled.
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: limiter:listener_fields
- default:
```
{
  connection {capacity = 1000, rate = "1000/s"}
}
```
1
2
3
Type of the rate limit.
enable_authn: true | false | quick_deny_anonymous
- default: true
Set true (default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set to false to allow any clients with or without authentication information such as username or password to log in. When set to quick_deny_anonymous, it behaves like when set to true but clients will be denied immediately without going through any authenticators if username is not provided. This is useful to fence off anonymous clients early.

# 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: limiter:listener_fields
- default:
```
{
  connection {capacity = 1000, rate = "1000/s"}
}
```
1
2
3
Type of the rate limit.
enable_authn: true | false | quick_deny_anonymous
- default: true
Set true (default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set to false to allow any clients with or without authentication information such as username or password to log in. When set to quick_deny_anonymous, it behaves like when set to true but clients will be denied immediately without going through any authenticators if username is not provided. This is useful to fence off anonymous clients early.
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: limiter:listener_fields
- default:
```
{
  connection {capacity = 1000, rate = "1000/s"}
}
```
1
2
3
Type of the rate limit.
enable_authn: true | false | quick_deny_anonymous
- default: true
Set true (default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set to false to allow any clients with or without authentication information such as username or password to log in. When set to quick_deny_anonymous, it behaves like when set to true but clients will be denied immediately without going through any authenticators if username is not provided. This is useful to fence off anonymous clients early.
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: limiter:listener_fields
- default:
```
{
  connection {capacity = 1000, rate = "1000/s"}
}
```
1
2
3
Type of the rate limit.
enable_authn: true | false | quick_deny_anonymous
- default: true
Set true (default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set to false to allow any clients with or without authentication information such as username or password to log in. When set to quick_deny_anonymous, it behaves like when set to true but clients will be denied immediately without going through any authenticators if username is not provided. This is useful to fence off anonymous clients early.
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: limiter:listener_fields
- default:
```
{
  connection {capacity = 1000, rate = "1000/s"}
}
```
1
2
3
Type of the rate limit.
enable_authn: true | false | quick_deny_anonymous
- default: true
Set true (default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set to false to allow any clients with or without authentication information such as username or password to log in. When set to quick_deny_anonymous, it behaves like when set to true but clients will be denied immediately without going through any authenticators if username is not provided. This is useful to fence off anonymous clients early.
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
When at high load, some unimportant tasks could be delayed for execution, here set the duration in milliseconds precision.
backoff_gc: boolean()
- default: false
When at high load, skip forceful GC.
backoff_hibernation: boolean()
- default: true
When at high load, skip process hibernation.
backoff_new_conn: boolean()
- default: true
When at high load, close new incoming connections.

# 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

type: builtin
- default: builtin
session: broker:persistent_table_mria_opts
Performance tuning options for built-in session table.
session_messages: broker:persistent_table_mria_opts
Performance tuning options for built-in session messages table.
messages: broker:persistent_table_mria_opts
Performance tuning options for built-in messages table.

# 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 | round_robin_per_group | 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
- round_robin_per_group: select the subscribers in round-robin fashion within each shared subscriber group
- 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.ssl
bridges.webhook.$name.ssl
cluster.etcd.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__SSL
EMQX_BRIDGES__WEBHOOK__$NAME__SSL
EMQX_CLUSTER__ETCD__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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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

vm: broker:sysmon_vm
os: broker:sysmon_os
top: broker:sysmon_top

# 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

mqtt: zone:mqtt
stats: zone:stats
flapping_detect: zone:flapping_detect
force_shutdown: zone:force_shutdown
conn_congestion: zone:conn_congestion
force_gc: zone:force_gc
overload_protection: zone:overload_protection

# 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.
bootstrap_users_file: binary()
Initialize users file.

# 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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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

http: dashboard:http
TCP listeners
https: dashboard:https
SSL listeners

# exhook

External hook (exhook) configuration.

Config paths

exhook

Env overrides

EMQX_EXHOOK

Fields

servers: [exhook:server]
- default: []
List of exhook servers

# 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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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
gc_after_handshake: boolean()
- default: false
Memory usage tuning. If enabled, will immediately perform a garbage collection after the TLS/SSL handshake.

# gateway:exproto

Settings for EMQX extension protocol (exproto).

Config paths

gateway.exproto

Env overrides

EMQX_GATEWAY__EXPROTO

Fields

server: gateway:exproto_grpc_server
Configurations for starting the ConnectionAdapter service
handler: gateway:exproto_grpc_handler
Configurations for request to ConnectionHandler service
mountpoint: binary()
- default: ""
listeners: gateway:tcp_udp_listeners
Settings for the 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: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()
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, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
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 configure ['tlsv1.2', 'tlsv1.1'] here.
ciphers: [string()]
- default: []
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

frame: gateway:stomp_frame
mountpoint: binary()
- default: ""
listeners: gateway:tcp_listeners
Settings for the TCP 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: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

tcp: {$name -> gateway:tcp_listener}
ssl: {$name -> gateway:ssl_listener}

# gateway:tcp_udp_listeners

Settings for the listeners.

Config paths

gateway.exproto.listeners

Env overrides

EMQX_GATEWAY__EXPROTO__LISTENERS

Fields

tcp: {$name -> gateway:tcp_listener}
ssl: {$name -> gateway:ssl_listener}
udp: {$name -> gateway:udp_listener}
dtls: {$name -> gateway:dtls_listener}

# 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

udp: {$name -> gateway:udp_listener}
dtls: {$name -> gateway:dtls_listener}

# 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

listeners.quic.$name.limiter.bytes_in
listeners.quic.$name.limiter.connection
listeners.quic.$name.limiter.message_in
listeners.quic.$name.limiter.message_routing
listeners.ssl.$name.limiter.bytes_in
listeners.ssl.$name.limiter.connection
listeners.ssl.$name.limiter.message_in
listeners.ssl.$name.limiter.message_routing
listeners.tcp.$name.limiter.bytes_in
listeners.tcp.$name.limiter.connection
listeners.tcp.$name.limiter.message_in
listeners.tcp.$name.limiter.message_routing
listeners.ws.$name.limiter.bytes_in
listeners.ws.$name.limiter.connection
listeners.ws.$name.limiter.message_in
listeners.ws.$name.limiter.message_routing
listeners.wss.$name.limiter.bytes_in
listeners.wss.$name.limiter.connection
listeners.wss.$name.limiter.message_in
listeners.wss.$name.limiter.message_routing

Env overrides

EMQX_LISTENERS__QUIC__$NAME__LIMITER__BYTES_IN
EMQX_LISTENERS__QUIC__$NAME__LIMITER__CONNECTION
EMQX_LISTENERS__QUIC__$NAME__LIMITER__MESSAGE_IN
EMQX_LISTENERS__QUIC__$NAME__LIMITER__MESSAGE_ROUTING
EMQX_LISTENERS__SSL__$NAME__LIMITER__BYTES_IN
EMQX_LISTENERS__SSL__$NAME__LIMITER__CONNECTION
EMQX_LISTENERS__SSL__$NAME__LIMITER__MESSAGE_IN
EMQX_LISTENERS__SSL__$NAME__LIMITER__MESSAGE_ROUTING
EMQX_LISTENERS__TCP__$NAME__LIMITER__BYTES_IN
EMQX_LISTENERS__TCP__$NAME__LIMITER__CONNECTION
EMQX_LISTENERS__TCP__$NAME__LIMITER__MESSAGE_IN
EMQX_LISTENERS__TCP__$NAME__LIMITER__MESSAGE_ROUTING
EMQX_LISTENERS__WS__$NAME__LIMITER__BYTES_IN
EMQX_LISTENERS__WS__$NAME__LIMITER__CONNECTION
EMQX_LISTENERS__WS__$NAME__LIMITER__MESSAGE_IN
EMQX_LISTENERS__WS__$NAME__LIMITER__MESSAGE_ROUTING
EMQX_LISTENERS__WSS__$NAME__LIMITER__BYTES_IN
EMQX_LISTENERS__WSS__$NAME__LIMITER__CONNECTION
EMQX_LISTENERS__WSS__$NAME__LIMITER__MESSAGE_IN
EMQX_LISTENERS__WSS__$NAME__LIMITER__MESSAGE_ROUTING

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.

# limiter:client_fields

Fields of the client level.

Config paths

limiter.client

Env overrides

EMQX_LIMITER__CLIENT

Fields

bytes_in: limiter:client_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:client_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:client_opts
- default: {}
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:client_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
internal: limiter:client_opts
- default: {}
Limiter for EMQX internal app.

# limiter:client_opts

Settings for the client in bucket level.

Config paths

limiter.client.bytes_in
limiter.client.connection
limiter.client.internal
limiter.client.message_in
limiter.client.message_routing
listeners.quic.$name.limiter.client.bytes_in
listeners.quic.$name.limiter.client.connection
listeners.quic.$name.limiter.client.message_in
listeners.quic.$name.limiter.client.message_routing
listeners.ssl.$name.limiter.client.bytes_in
listeners.ssl.$name.limiter.client.connection
listeners.ssl.$name.limiter.client.message_in
listeners.ssl.$name.limiter.client.message_routing
listeners.tcp.$name.limiter.client.bytes_in
listeners.tcp.$name.limiter.client.connection
listeners.tcp.$name.limiter.client.message_in
listeners.tcp.$name.limiter.client.message_routing
listeners.ws.$name.limiter.client.bytes_in
listeners.ws.$name.limiter.client.connection
listeners.ws.$name.limiter.client.message_in
listeners.ws.$name.limiter.client.message_routing
listeners.wss.$name.limiter.client.bytes_in
listeners.wss.$name.limiter.client.connection
listeners.wss.$name.limiter.client.message_in
listeners.wss.$name.limiter.client.message_routing
retainer.flow_control.batch_deliver_limiter.client

Env overrides

EMQX_LIMITER__CLIENT__BYTES_IN
EMQX_LIMITER__CLIENT__CONNECTION
EMQX_LIMITER__CLIENT__INTERNAL
EMQX_LIMITER__CLIENT__MESSAGE_IN
EMQX_LIMITER__CLIENT__MESSAGE_ROUTING
EMQX_LISTENERS__QUIC__$NAME__LIMITER__CLIENT__BYTES_IN
EMQX_LISTENERS__QUIC__$NAME__LIMITER__CLIENT__CONNECTION
EMQX_LISTENERS__QUIC__$NAME__LIMITER__CLIENT__MESSAGE_IN
EMQX_LISTENERS__QUIC__$NAME__LIMITER__CLIENT__MESSAGE_ROUTING
EMQX_LISTENERS__SSL__$NAME__LIMITER__CLIENT__BYTES_IN
EMQX_LISTENERS__SSL__$NAME__LIMITER__CLIENT__CONNECTION
EMQX_LISTENERS__SSL__$NAME__LIMITER__CLIENT__MESSAGE_IN
EMQX_LISTENERS__SSL__$NAME__LIMITER__CLIENT__MESSAGE_ROUTING
EMQX_LISTENERS__TCP__$NAME__LIMITER__CLIENT__BYTES_IN
EMQX_LISTENERS__TCP__$NAME__LIMITER__CLIENT__CONNECTION
EMQX_LISTENERS__TCP__$NAME__LIMITER__CLIENT__MESSAGE_IN
EMQX_LISTENERS__TCP__$NAME__LIMITER__CLIENT__MESSAGE_ROUTING
EMQX_LISTENERS__WS__$NAME__LIMITER__CLIENT__BYTES_IN
EMQX_LISTENERS__WS__$NAME__LIMITER__CLIENT__CONNECTION
EMQX_LISTENERS__WS__$NAME__LIMITER__CLIENT__MESSAGE_IN
EMQX_LISTENERS__WS__$NAME__LIMITER__CLIENT__MESSAGE_ROUTING
EMQX_LISTENERS__WSS__$NAME__LIMITER__CLIENT__BYTES_IN
EMQX_LISTENERS__WSS__$NAME__LIMITER__CLIENT__CONNECTION
EMQX_LISTENERS__WSS__$NAME__LIMITER__CLIENT__MESSAGE_IN
EMQX_LISTENERS__WSS__$NAME__LIMITER__CLIENT__MESSAGE_ROUTING
EMQX_RETAINER__FLOW_CONTROL__BATCH_DELIVER_LIMITER__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:internal

Internal limiter.

Config paths

retainer.flow_control.batch_deliver_limiter

Env overrides

EMQX_RETAINER__FLOW_CONTROL__BATCH_DELIVER_LIMITER

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.
client: limiter:client_opts
The rate limit for each user of the bucket

# limiter

Settings for the rate limiter.

Config paths

limiter

Env overrides

EMQX_LIMITER

Fields

bytes_in: limiter:node_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:node_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:node_opts
- default: {}
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:node_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
internal: limiter:node_opts
- default: {}
Limiter for EMQX internal app.

client: limiter:client_fields

default:

{
  bytes_in {}
  connection {}
  internal {}
  message_in {}
  message_routing {}
}

1
2
3
4
5
6
7

The rate limit for each user of the bucket

# limiter:listener_client_fields

Fields of the client level of the listener.

Config paths

listeners.quic.$name.limiter.client
listeners.ssl.$name.limiter.client
listeners.tcp.$name.limiter.client
listeners.ws.$name.limiter.client
listeners.wss.$name.limiter.client

Env overrides

EMQX_LISTENERS__QUIC__$NAME__LIMITER__CLIENT
EMQX_LISTENERS__SSL__$NAME__LIMITER__CLIENT
EMQX_LISTENERS__TCP__$NAME__LIMITER__CLIENT
EMQX_LISTENERS__WS__$NAME__LIMITER__CLIENT
EMQX_LISTENERS__WSS__$NAME__LIMITER__CLIENT

Fields

bytes_in: limiter:client_opts
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:client_opts
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:client_opts
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:client_opts
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

# limiter:listener_fields

Fields of the listener.

Config paths

listeners.quic.$name.limiter
listeners.ssl.$name.limiter
listeners.tcp.$name.limiter
listeners.ws.$name.limiter
listeners.wss.$name.limiter

Env overrides

EMQX_LISTENERS__QUIC__$NAME__LIMITER
EMQX_LISTENERS__SSL__$NAME__LIMITER
EMQX_LISTENERS__TCP__$NAME__LIMITER
EMQX_LISTENERS__WS__$NAME__LIMITER
EMQX_LISTENERS__WSS__$NAME__LIMITER

Fields

bytes_in: limiter:bucket_opts
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:bucket_opts
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:bucket_opts
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:bucket_opts
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
client: limiter:listener_client_fields
The rate limit for each user of the bucket

# limiter:node_opts

Settings for the limiter of the node level.

Config paths

limiter.bytes_in
limiter.connection
limiter.internal
limiter.message_in
limiter.message_routing

Env overrides

EMQX_LIMITER__BYTES_IN
EMQX_LIMITER__CONNECTION
EMQX_LIMITER__INTERNAL
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.

# 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

function: republish
Republish the message as a new MQTT message
args: rule_engine:republish_args
- default: {}

# 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.
user_properties: binary()
- default: "${user_properties}"
From which variable should the MQTT message's User-Property pairs be taken from. The value must be a map. You may configure it to ${pub_props.'User-Property'} or use SELECT *,pub_props.'User-Property' as user_properties to forward the original user properties to the republished message. You may also call map_put function like map_put('my-prop-name', 'my-prop-value', user_properties) as user_properties to inject user properties. NOTE: MQTT spec allows duplicated user property names, but EMQX Rule-Engine does not.

# 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
jq_implementation_module: jq_nif | jq_port
- default: jq_nif
- mapping: jq.jq_implementation_module
The implementation module for the jq rule engine function. The two options are jq_nif and jq_port. With the jq_nif option an Erlang NIF library is used while with the jq_port option an implementation based on Erlang port programs is used. The jq_nif option (the default option) is the fastest implementation of the two but jq_port is safer as the jq programs will not execute in the same process as the Erlang VM.

# 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
metadata: map()
Rule metadata, do not change manually

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

# config

The config for MQTT Bridges.

Config paths

bridges.mqtt.$name

Env overrides

EMQX_BRIDGES__MQTT__$NAME

Fields

enable: boolean()
- default: true
Enable or disable this bridge
resource_opts: bridge_mqtt:creation_opts
- default: {}
Resource options.
mode: cluster_shareload
- default: cluster_shareload
The mode of the MQTT Bridge.
- 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:host_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()
The username of the MQTT protocol
password: binary()
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
ssl: broker:ssl_client_opts
- default: {enable = false}
SSL connection settings.
ingress: connector-mqtt:ingress
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 'remote.qos', 'local.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the input of a rule, and also 'local.topic' is configured, then messages got from the remote broker will be sent to both the 'local.topic' and the rule.
egress: connector-mqtt: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', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the action of a rule, 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.

# 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
resource_opts: bridge_webhook:creation_opts
- default: {}
Resource options.
connect_timeout: emqx_schema:duration_ms()
- default: "15s"
The timeout when connecting to the HTTP server.
retry_interval: emqx_schema:duration()
Deprecated since 5.0.4.
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.
max_retries: non_neg_integer()
- default: 2
HTTP request max retry times if failed.
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. NOTE: Restrict char limiter if formatter is JSON , it will get a truncated incomplete JSON data, which is not recommended.
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

console_handler: console_handler
file_handlers: {$name -> log_file_handler}
File-based log handlers.

# 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. NOTE: Restrict char limiter if formatter is JSON , it will get a truncated incomplete JSON data, which is not recommended.
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()
- 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: disabled | emqx_schema:duration()
- default: "15m"
- mapping: emqx_machine.global_gc_interval
Periodic garbage collection interval. Set to disabled to have it disabled.
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()
Deprecated since 5.0.8.
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.
insecure_fallback: boolean()
- default: true
- mapping: gen_rpc.insecure_auth_fallback_allowed
Enable compatibility with old RPC authentication.

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

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_durationmilliseconds 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

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
For each publisher session, the maximum number of outstanding QoS 2 messages pending on the client to send PUBREL. After reaching this limit, new QoS 2 PUBLISH requests will be rejected with 147(0x93) until either PUBREL is received or timed out.
await_rel_timeout: emqx_schema:duration()
For client to broker QoS 2 message, the time limit for the broker to wait before the PUBREL message is received. The wait is aborted after timed out, meaning the packet ID is freed for new PUBLISH requests. Receiving a stale PUBREL causes a warning level log. Note, the message is delivered to subscribers before entering the wait for PUBREL.
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
When at high load, some unimportant tasks could be delayed for execution, here set the duration in milliseconds precision.
backoff_gc: boolean()
When at high load, skip forceful GC.
backoff_hibernation: boolean()
When at high load, skip process hibernation.
backoff_new_conn: boolean()
When at high load, close new incoming connections.

# zone:stats

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()
Deprecated since 5.0.4.
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()
Deprecated since 5.0.4.
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()
Deprecated since 5.0.4.
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()
Deprecated since 5.0.4.
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: broker:ssl_client_opts
- 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-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:host_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:host_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:host_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
- default: cluster
Cluster mode
pool_size: pos_integer()
- default: 8
Size of the connection pool.
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-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
- default: 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:host_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
- default: 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.

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.

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_webhook:config}
WebHook to an HTTP server.
mqtt: {$name -> bridge_mqtt:config}
MQTT bridges to/from another MQTT broker

# bridge_mqtt:creation_opts

Creation options.

Config paths

bridges.mqtt.$name.resource_opts

Env overrides

EMQX_BRIDGES__MQTT__$NAME__RESOURCE_OPTS

Fields

worker_pool_size: pos_integer()
- default: 16
Resource worker pool size.
health_check_interval: emqx_schema:duration_ms()
- default: "15s"
Health check interval, in milliseconds.
auto_restart_interval: infinity | emqx_schema:duration_ms()
- default: "60s"
The auto restart interval after the resource is disconnected, in milliseconds.
query_mode: sync | async
- default: async
Query mode. Optional 'sync/async', default 'sync'.
async_inflight_window: pos_integer()
- default: 100
Async query inflight window.
enable_queue: boolean()
- default: false
Queue mode enabled.
max_queue_bytes: emqx_schema:bytesize()
- default: "100MB"
Maximum queue storage.

# bridge_webhook:creation_opts

Creation options.

Config paths

bridges.webhook.$name.resource_opts

Env overrides

EMQX_BRIDGES__WEBHOOK__$NAME__RESOURCE_OPTS

Fields

worker_pool_size: pos_integer()
- default: 16
Resource worker pool size.
health_check_interval: emqx_schema:duration_ms()
- default: "15s"
Health check interval, in milliseconds.
auto_restart_interval: infinity | emqx_schema:duration_ms()
- default: "60s"
The auto restart interval after the resource is disconnected, in milliseconds.
query_mode: sync | async
- default: async
Query mode. Optional 'sync/async', default 'sync'.
async_inflight_window: pos_integer()
- default: 100
Async query inflight window.
enable_queue: boolean()
- default: false
Queue mode enabled.
max_queue_bytes: emqx_schema:bytesize()
- default: "100MB"
Maximum queue storage.

# 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: binary()
HTTP method.
path: binary()
URL path.
body: binary()
HTTP request body.
headers: map()
List of HTTP headers.
max_retries: non_neg_integer()
Max retry times if error on sending request.
request_timeout: emqx_schema:duration_ms()
HTTP request timeout.

# connector-mqtt: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', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the action of a rule, 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.

Config paths

bridges.mqtt.$name.egress

Env overrides

EMQX_BRIDGES__MQTT__$NAME__EGRESS

Fields

local: connector-mqtt:egress_local
The configs about receiving messages from local broker.
remote: connector-mqtt:egress_remote
The configs about sending message to the remote broker.

# connector-mqtt:egress_local

The configs about receiving messages from local broker.

Config paths

bridges.mqtt.$name.egress.local

Env overrides

EMQX_BRIDGES__MQTT__$NAME__EGRESS__LOCAL

Fields

topic: binary()
The local topic to be forwarded to the remote broker

# connector-mqtt:egress_remote

The configs about sending message to the remote broker.

Config paths

bridges.mqtt.$name.egress.remote

Env overrides

EMQX_BRIDGES__MQTT__$NAME__EGRESS__REMOTE

Fields

topic: binary()
Forward to which topic of the remote broker.
Template with variables is allowed.
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.

# connector-mqtt:ingress

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 'remote.qos', 'local.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the input of a rule, and also 'local.topic' is configured, then messages got from the remote broker will be sent to both the 'local.topic' and the rule.

Config paths

bridges.mqtt.$name.ingress

Env overrides

EMQX_BRIDGES__MQTT__$NAME__INGRESS

Fields

remote: connector-mqtt:ingress_remote
The configs about subscribing to the remote broker.
local: connector-mqtt:ingress_local
The configs about sending message to the local broker.

# connector-mqtt:ingress_local

The configs about sending message to the local broker.

Config paths

bridges.mqtt.$name.ingress.local

Env overrides

EMQX_BRIDGES__MQTT__$NAME__INGRESS__LOCAL

Fields

topic: binary()
Send messages to which topic of the local broker.
Template with variables is allowed.
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()
The payload of the MQTT message to be sent.
Template with variables is allowed.

# connector-mqtt:ingress_remote

The configs about subscribing to the remote broker.

Config paths

bridges.mqtt.$name.ingress.remote

Env overrides

EMQX_BRIDGES__MQTT__$NAME__INGRESS__REMOTE

Fields

topic: binary()
Receive messages from which topic of the remote broker
qos: qos() | binary()
- default: 1
The QoS level to be used when subscribing to the remote broker

# 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
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: limiter:internal
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
- default: {}
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

StatsD metrics collection and push configuration.

Config paths

statsd

Env overrides

EMQX_STATSD

Fields

enable: boolean()
- default: false
Enable or disable StatsD metrics collection and push service.
server: emqx_schema:host_port()
- default: "127.0.0.1:8125"
StatsD server address.
sample_time_interval: emqx_schema:duration_ms()
- default: "30s"
The sampling interval for metrics.
flush_time_interval: emqx_schema:duration_ms()
- default: "30s"
The push interval for metrics.
tags: map()
- default: {}
The tags for metrics.

← Configuration Files Data backup and restoration →