# Configuration

# Cluster

# cluster.name

# Description

Cluster name.

# cluster.proto_dist

# Description

Distributed Erlang cluster protocol type. Available values are:

• inet_tcp: using IPv4
• inet6_tcp: using IPv6
• inet_tls: using TLS, required to be used with node.ssl_dist_optfile configuration

# cluster.discovery

# Description

Cluster node discovery method. Available values are:

• manual: join the cluster manually
• static: Configure static nodes. Configure several fixed nodes, and the new node joins the cluster by connecting one of the fixed nodes.
• mcast: Use UDP multicast to discover nodes.
• dns: Use DNS A records to discover nodes.
• etcd: Use etcd to discover nodes.
• k8s: Use Kubernetes to discover nodes.

# cluster.autoheal

# Description

Enable or disable the automatic recovery mechanism for cluster network partitions.

# cluster.autoclean

# Description

Specify how long to delete offline nodes from the cluster.

# cluster.static.seeds

# Description

When using static clustering, specify a fixed list of nodes, separated by commas , between multiple nodes.

# cluster.mcast.addr

# Description

When using the mcast cluster, specify the multicast address.

# cluster.mcast.ports

# Description

When using the mcast cluster, specify the multicast port. If there are multiple ports, separate them with commas ,.

# cluster.mcast.iface

# Description

When using mcast cluster, specify which local IP address the node discovery service needs to bind to.

# cluster.mcast.ttl

# Description

When using mcast cluster, specify the Time-To-Live value of multicast.

# cluster.mcast.loop

# Description

When using mcast clustering, set whether multicast packets are delivered to the local loopback address.

# cluster.dns.name

# Description

When using the dns cluster, specify the name of the DNS A record. emqx will access the DNS A record to obtain a list of IP addresses, and then splice the APP name specified in cluster.dns.app to get a list of all nodes in the cluster.

# Example

Set cluster.dns.app = emqx, and configure a DNS: mycluster.com, which points to 3 IP addresses:

192.168.0.100
192.168.0.101
192.168.0.102
 
    Copied!
  

Then get the list of cluster nodes as follows:

emqx@192.168.0.100
emqx@192.168.0.101
emqx@192.168.0.102
 
    Copied!
  

# cluster.dns.app

# Description

When using dns cluster, it is used to splice the IP list obtained from cluster.dns.name to get a list of node names.

# cluster.etcd.server

# Description

When using etcd cluster, specify the address of etcd service. If there are multiple services, use commas to separate them.

# cluster.etcd.prefix

# Description

When using etcd cluster, specify the prefix of etcd path. Each node creates a path in etcd:

v2/keys/<prefix>/<cluster.name>/<node.name>
 
    Copied!
  

# cluster.etcd.node_ttl

# Description

When using etcd cluster, specify the expiration time of the node path in etcd.

# cluster.etcd.ssl.keyfile

# Description

When using SSL to connect to etcd, specify the client's private key file.

# cluster.etcd.ssl.certfile

# Description

When using SSL to connect to etcd, specify the SSL client certificate file.

# cluster.etcd.ssl.cacertfile

# Description

When using SSL to connect to etcd, specify the CA certificate file for SSL.

# cluster.k8s.apiserver

# Description

When using the k8s cluster, specify the Kubernetes API Server. If there are multiple Servers, separate them with commas ,.

# cluster.k8s.service_name

# Description

When using k8s cluster, specify the service name of EMQX Broker in Kubernetes.

# cluster.k8s.address_type

# Description

When using k8s cluster, address_type is used to obtain the host list from the response of the Kubernetes interface.

# Example

Specifying cluster.k8s.address_type as ip, it will get the list of IP addresses of emqx services from the Kubernetes interface:

172.16.122.31
172.16.122.32
172.16.122.33
 
    Copied!
  

Then splice with the app name specified by cluster.k8s.app_name configuration to get a list of emqx nodes:

emqx@172.16.122.31
emqx@172.16.122.32
emqx@172.16.122.33
 
    Copied!
  

# cluster.k8s.app_name

# Description

When using k8s clustering, app_name is used to splice with the obtained Host list to get the node list.

# cluster.k8s.suffix

# Description

When using the k8s method and specifying cluster.k8s.address_type as the dns type, you can set the suffix of the emqx node name, and splice with cluster.k8s.namespace to get a list of node names.

# cluster.k8s.namespace

# Description

When using the k8s method and specifying cluster.k8s.address_type as the dns type, you can set the namespace of the emqx node name, and splice with cluster.k8s.suffix to get a list of node names.

# Example

Setting cluster.k8s.address_type to dns, you will get the dns list of emqx service from the Kubernetes interface:

172-16-122-31
172-16-122-32
172-16-122-33
 
    Copied!
  

Then splice with cluster.k8s.app_name = emqx，cluster.k8s.suffix = pod.cluster.local，cluster.k8s.namespace = default to get a list of emqx node names in the form of dns:

emqx@172-16-122-31.default.pod.cluster.local
emqx@172-16-122-32.default.pod.cluster.local
emqx@172-16-122-33.default.pod.cluster.local
 
    Copied!
  

# node.name

# Description

The node name. The format is <name> @ <host>. Where <host> can be an IP address or FQDN. See http://erlang.org/doc/reference_manual/distributed.html (opens new window) for details

# node.cookie

# Description

The cookie value used by the distributed Erlang cluster.

# node.data_dir

# Description

The node's data directory, which is used to store Mnesia data files.

# node.heartbeat

# Description

System tuning parameters. This configuration will override the -heart parameter in the vm.args file.

Enable or disable Erlang runtime detection mechanism, and restart automatically when the runtime terminates. Use with care to avoid restarting the monitored process when emqx is closed manually.

# node.async_threads

# Description

System tuning parameters. This configuration will override the +A parameter in the vm.args file.

Set the number of threads in the asynchronous thread pool in Erlang runtime, see http://erlang.org/doc/man/erl.html (opens new window) for details.

# node.process_limit

# Description

System tuning parameters. This configuration will override the +P parameter in the vm.args file.

Set the maximum number of processes allowed by Erlang, which will affect the number of connections that emqx nodes can process. See http://erlang.org/doc/man/erl.html (opens new window) for details.

# node.max_ports

# Description

System tuning parameters. This configuration will override the +Q parameter in the vm.args file.

Set the maximum number of ports allowed by Erlang. See http://erlang.org/doc/man/erl.html (opens new window) for details.

# node.dist_buffer_size

# Description

System tuning parameters. This configuration will override the +zdbbl parameter in the vm.args file.

Set the maximum cache size used by Erlang distributed communication. See http://erlang.org/doc/man/erl.html (opens new window) for details.

# node.max_ets_tables

# Description

System tuning parameters. This configuration will override the +e parameter in the vm.args file.

Set the maximum number of ETS tables allowed in Erlang runtime. See http://erlang.org/doc/man/erl.html (opens new window) for details.

# node.global_gc_interval

# Description

System tuning parameters, which set how often Erlang runs to force a global garbage collection.

# node.fullsweep_after

# Description

System tuning parameters. This configuration will override the -env ERL_FULLSWEEP_AFTER parameter in the vm.args file.

Set how many times the generational GC will run before Erlang runs a fullsweep GC. For details, see http://erlang.org/doc/man/erlang.html#spawn_opt-4 (opens new window).

# node.crash_dump

# Description

Set the storage path and file name of the Erlang crash_dump file.

# node.ssl_dist_optfile

# Description

This configuration will override the -ssl_dist_optfile parameter in the vm.args file.

If you use SSL to establish an emqx cluster, you need to specify the SSL distributed protocol configuration file. It needs to be used with cluster.proto_dist = inet_tls.

# node.dist_net_ticktime

# Description

System tuning parameters. This configuration will override the -kernel net_ticktime parameter in the vm.args file.

Specifying how long time when a node has been unresponsive, it is considered to be down and disconnected. For details, see http://www.erlang.org/doc/man/kernel_app.html#net_ticktime (opens new window).

# node.dist_use_interface

# Description

The default is to use 0.0.0.0 to specify all network-interfaces to listen to, or to specify the IP of the network-interface to listen to.

# node.dist_listen_min

# Description

Set a TCP port range together with node.dist_listen_max. This port ranget is used for distribution to distributed Erlang as a listening port for distributed channels. Note that if a firewall is set between nodes, this port range needs to be placed into the firewall's whitelist.

# node.dist_listen_max

# Description

Set a TCP port range together with node.dist_listen_min. This port range is used for distribution to distributed Erlang as a listening port for distributed channels. Note that if a firewall is set up between nodes, this port rangeneeds to be put in The firewall's whitelist.

# rpc.mode

# Description

RPC mode. Synchronous or asynchronous mode is optional.

# rpc.async_batch_size

# Description

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

# rpc.port_discovery

# Description

manual: discover ports by tcp_server_port and tcp_client_port. stateless: discover ports in a stateless manner. If node name is emqx<N>@127.0.0.1, where the <N> is an integer, then the listening port will be 5370 + <N>

Default is manual when started from docker (environment variable override from docker-entrypoint) otherwise stateless.

# rpc.tcp_server_ip

# Description

Set the listening network-interface used by RPC local service. Use 0.0.0.0 to listen to all network-interfaces. NOTE: this config only takes effect when rpc.port_discovery is set to manual

# rpc.tcp_server_port

# Description

Set the listening port used by RPC local service NOTE: this config only takes effect when rpc.port_discovery is set to manual

# rpc.tcp_client_num

# Description

Set the number of RPC communication channels initiated by this node to each remote node. Set to 1 to ensure the order of messages. Keep the default value (half the number of CPU cores) to improve RPC throughput.

# rpc.driver

# Description

Transport-layer protocol used for communication between the brokers.

# rpc.default_client_driver

# Description

Transport-layer protocol used for communication between the brokers (client side). This parameter should match the value of rpc.driver.

# rpc.enable_ssl

# Description

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.

# rpc.certfile

# Description

Path to TLS certificate file used to validate identity of the cluster nodes. This configuration is mandatory when rpc.driver is set to ssl, otherwise it doesn't take any effect.

# rpc.cacertfile

# Description

Path to certification authority TLS certificate file used to validate rpc.certfile. This configuration is mandatory when rpc.driver is set to ssl, otherwise it doesn't take any effect.

# rpc.keyfile

# Description

Path to the private key file for the rpc.certfile. This configuration is mandatory when rpc.driver is set to ssl, otherwise it doesn't take any effect. Note: contents of this file are secret, so it's necessary to set permissions to 600.

# rpc.connect_timeout

# Description

Timeout for establishing an RPC connection. It means how long will it give up after trying if the remote node does not respond when establishing a connection, .

# rpc.send_timeout

# Description

Timeout for sending, which means how long to give up after sending the message.

# rpc.authentication_timeout

# Description

RPC authentication timeout. It means how long it will give up if the remote node does not respond, .

# rpc.call_receive_timeout

# Description

The timeout period of RPC synchronous mode. It means how long it will take before giving up if the RPC synchronous call fails to receive a reply.

# rpc.socket_keepalive_idle

# Description

It means how long after the last packet was sent, keepalive probe packets are sent.

# rpc.socket_keepalive_interval

# Description

The interval between keepalive detection messages.

# rpc.socket_keepalive_count

# Description

For how many times if the keepalive probe message fails to receive a reply, the RPC connection is considered lost.

# rpc.socket_sndbuf

# Description

TCP tuning parameters. TCP sending buffer size.

# rpc.socket_recbuf

# Description

TCP tuning parameters. TCP receiving buffer size.

# rpc.socket_buffer

# Description

TCP tuning parameters. Socket buffer size in user mode.

# log.to

# Description

Where to output the log. The optional values are:

• off: Disable logging completely
• file: Only output log to file
• console: Only output logs to standard output (emqx console)
• both: output log to file and standard output at the same time (emqx console)

# log.level

# Description

Global log level. This includes the primary log level and all log handlers. For details, see log level and log handlers.

# log.dir

# Description

Log file directory.

# log.file

# Description

The prefix of the log file. For example, if you use the default value (log.file = emqx.log), the log file name will be emqx.log.1, emqx.log.2, ...

# log.chars_limit

# Description

Set the maximum length of a single log message. If this length is exceeded, the log message will be truncated. -1 means no limit.

# log.max_depth

# Description

Maximum depth for Erlang term log formatting and Erlang process message queue inspection. Set 'unlimited' (without quotes) to print Erlang terms without depth limit.

# log.rotation.size

# Description

Set the size of a single log file. If it exceeds this size, the log file will be rolled to create a new log file.

# log.rotation.count

# Description

Set the total number of log files. If this number is exceeded, the next log file will overwrite the first file.

# log.<level>.file

# Description

Set a separate log file for a certain log level.

# Example

Separately output info and above logs to info.log.N file:

log.info.file = info.log
 
    Copied!
  

Output error and error logs separately to the error.log.N file

log.error.file = error.log
 
    Copied!
  

# log.max_depth

# Description

Max depth when printing large data blob to log. Exceeding parts will be logge as '...'.

# log.single_line

# Description

Print logs in a single line if set to true. If set to false, information like stacktraces in crash logs may span multiple lines.

# log.formatter

# Description

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

# log.formatter.text.date.format

NOTE: This config is available start from EMQX Opensource 4.3.15, 4.4.4 and EMQX Enterprise 4.3.10, 4.4.4.

# Description

The timestamp format for the text logger. Can be one of rfc3339 or a FORMAT string.

Supported specifiers in the FORMAT string are:

Examples:

## 2022-06-02T14:23:09.230000 +08:00
log.formatter.text.date.format = %Y-%m-%dT%H:%M:%S.%6N %:z

## To make the timestamp look the same as that of version 4.2.x (2022-06-02 14:24:36.124):
log.formatter.text.date.format = %Y-%m-%d %H:%M:%S.%3N
 
    Copied!
  

# authacl

# allow_anonymous

# Description

Whether to allow anonymous users to log in to the system.

# acl_nomatch

# Description

When the ACL is not hit, allow or deny the publish/subscribe operation.

# acl_file

# Description

The default path of ACL file.

# enable_acl_cache

# Description

Whether to enable ACL caching.

# acl_cache_max_size

# Description

Maximum cache number of ACL rule.

# acl_cache_ttl

# Description

Maximum cache time of ACL rule.

# acl_deny_action

# Description

What to do after the ACL check fails.

• ignore：No operation
• disconnect：disconnect.

# acl_order

# Description

When using multiple ACL backends, this config can be used to define their order. The default value none means no explicit ordering, in which case the order depends on the plugin (or module) start/restart order. Use comma to separate the names (or aliases), for example jwt,http means jwt authentication should be checked before http. Supported aliases are: internal (or file), http, jwt, ldap, mnesia, mongo (or mongodb), mysql, pgsql (or postgres), redis. It is not necessary to enumerate all the in-use ACL backends here, if only a part of the backends are listed here, the ones not listed will be ordered at the end. When using a third-party plugin, there is no alias support for it, so it has to be the specific callback module name, e.g. my_auth_plugin_module.

# auth_order

# Description

When using multiple authentication backends, this config can be used to define their order. This config is similar to acl_order, only there is no internal authentication backend.

# alias_enrichment_module

# Description

Introduced in 4.4.11.

Specify a module that defines the enrich_with_aliases/2 function. This function will be used to enrich the client/channel information with clientid and/or common name aliases (or other enrichments the module may implement).

# special_auth_module

# Description

Introduced in 4.4.11.

Specify a module that defines the check_authn/2 function. This function will be used in the client.authenticate hook as a way to implement custom authentication logic.

# mqtt

# flapping_detect_policy

# Description

Specify the Flapping inspection strategy.

Format: <threshold>,<duration>,<banned>.

For example, 30, 1m, 5m, it means that if the client disconnects 30 times within 1 minute, then login is prohibited for the next 5 minutes

# mqtt.max_packet_size

# Description

The maximum allowed length of MQTT messages.

# mqtt.max_clientid_len

# Description

The maximum allowed length of Client ID string.

# mqtt.max_topic_levels

# Description

The maximum allowed level of topics for client subscription. 0 means no limit.

::: Warning Too many topic levels may cause performance problems during subscription. :::

# mqtt.max_qos_allowed

# Description

The maximum allowed QoS level for client to publish.

# mqtt.max_topic_alias

# Description

The maximum allowed number of topic aliases. 0 means that topic aliases are not supported.

# mqtt.retain_available

# Description

Whether to support Retain message.

# mqtt.wildcard_subscription

# Description

Whether to support subscribing to wildcard topics.

# mqtt.shared_subscription

# Description

Whether to support shared subscriptions.

# mqtt.ignore_loop_deliver

# Description

Whether to ignore the message sent by itself. If it is ignored, it means that EMQX Broker will not deliver this message to the sender of the message.

# mqtt.strict_mode

# Description

Whether to enable the strict check mode. The strict check mode will check the correctness of the MQTT message in more detail.

# mqtt.response_information

# Description

Configures the Response-Information property returned in the server's CONNACK packet (MQTT 5.0). For more details, see: CONNACK: Response Information (opens new window)

# mqtt.message_expiry_interval

# Description

Sets the message expiration interval.

• For MQTT 5.0 clients, this configuration only takes effect when the Message-Expiry-Interval property is not set in the message; otherwise, the value of the Message-Expiry-Interval property is used.
• For MQTT versions below 5.0, this configuration always takes effect.

Note: Setting message_expiry_interval to a value greater than session_expiry_interval is meaningless, as all messages will be cleared when the session expires.

# zone.external.idle_timeout

# Description

The daze time after the TCP connection is established. If no packets are received within this time, the connection will be shutdown.

# zone.external.enable_acl

# Description

Whether to enable ACL check.

# zone.external.enable_ban

# Description

Whether to enable blacklist.

# zone.external.enable_stats

# Description

Whether to enable client status statistics.

# zone.external.acl_deny_action

# Description

What to do after the ACL check fails.

• ignore：No any operation.
• disconnect：disconnect.

# zone.external.force_gc_policy

# Description

When a certain number of messages, or bytes, are received, a garbage collection is forced.

Format: <Number> | <Bytes>.

For example, 16000|16MB means that when 16000 messages are received, or a byte of 16MB flows in, a garbage collection is forced.

# zone.external.force_shutdown_policy

# Description

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

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

Format: <Number> | <Bytes>.

For example, 32000|32MB means that when the process accumulates 32000 messages, or the process occupies memory up to 32MB, the process is closed.

# zone.external.max_packet_size

# Description

The maximum allowed length of MQTT packet.

# zone.external.max_clientid_len

# Description

The maximum length of Client ID string.

# zone.external.max_topic_levels

# Description

The maximum allowed level of topics for client subscription. 0 means no limit.

::: Warning Too many topic levels may cause performance problems during subscription. :::

# zone.external.max_qos_allowed

# Description

The maximum QoS level allowed for the client to publish.

# zone.external.max_topic_alias

# Description

The maximum number of topic aliases. 0 means that topic aliases are not supported.

# zone.external.retain_available

# Description

Whether to support Retain message.

# zone.external.wildcard_subscription

# Description

Whether to support subscribing to wildcard topics.

# zone.external.shared_subscription

# Description

Whether to support shared subscriptions.

# zone.external.server_keepalive

# Description

Keepalive time specified by the server, used for MQTT v5.0 CONNACK messages

# zone.external.keepalive_backoff

# Description

Keepalive backoff index. If no data packet is received from the client within the time of Keepalive * backoff * 2, it is considered that the client has heartbeat timeout.

# zone.external.max_subscriptions

# Description

The maximum number of topics that a single client is allowed to subscribe to. 0 means no limit.

# zone.external.upgrade_qos

# Description

Allow EMQX Broker to force the QoS level of the message upgrading to the subscribed QoS level when publishing the message.

# zone.external.max_inflight

# Description

Inflight window size: The inflight window is used to store unacknowledged QoS 1 and QoS 2 messages.

# zone.external.retry_interval

# Description

Message retransmission interval: EMQX Broker checks whether message retransmission is required at each interval.

# zone.external.max_awaiting_rel

# Description

The maximum receiving window for QoS 2 messages, which configures how many QoS 2 messages from the client can be processed by EMQX Broker simultaneously. 0 means no limit.

# zone.external.await_rel_timeout

# Description

Time for QoS 2 message processing timeout. If the QoS PUBREL message has not been received after the timeout, the message is dropped from the receiving window.

# zone.external.session_expiry_interval

# Description

The default timeout period of the session, which is mainly used for MQTT v3.1 and v3.1.1 protocols. In MQTT v5.0, this value is usually carried in the client's connection message.

# zone.external.max_mqueue_len

# Description

The maximum length of the message queue. When the flight window is full, or the client is offline, the message will be stored in the queue. 0 means no limit.

# zone.external.mqueue_priorities

# Description

Queue message priority configuration:

• none：no prioritization.
• <Spec>：A message priority table, which configures the priority of messages under a certain topic. For example:
  • topic/1=10: indicates that the message priority of the topic topic/1 is 10.
  • topic/1=10,topic/2=8: indicates that the priority of two topics is configured, which are 10 and 8 respectively.
  • Among them, the higher the priority value, the higher the priority level.

When the length of the message queue is limited, low priority messages will be dropped first.

# zone.external.mqueue_default_priority

# Description

The default priority level of the message.

# zone.external.mqueue_store_qos0

# Description

Whether the message queue stores QoS 0 messages.

# zone.external.enable_flapping_detect

# Description

Whether to enable Flapping check.

# zone.external.mountpoint

# Description

After topic mount point is configured, all subscribed and published topics will be prefixed by EMQX Broker.

The available placeholders are:

• %c：Client ID.
• %u：Username.

For example, if the mount point is set to user/%c/. , when the client with client ID tom publishes the topic open message, the topic actually routed in EMQX Broker is user/tom/open.

# zone.external.use_username_as_clientid

# Description

Whether to use the client's Username as its Client ID.

# zone.external.ignore_loop_deliver

# Description

Whether to ignore the message sent by yourself. If ignored, it means that EMQX Broker will not deliver this message to the sender of the message.

# zone.external.strict_mode

# Description

Whether to enable the strict check mode. The strict check mode will check the correctness of the MQTT message in more detail.

# zone.internal.allow_anonymous

# Description

Whether to allow anonymous users to log in to the system.

# zone.internal.enable_stats

# Description

Whether to enable client status statistics.

# zone.internal.enable_acl

# Description

Whether to enable ACL check.

# zone.internal.acl_deny_action

# Description

What to do after the ACL check fails.

• ignore：No operation.
• disconnect：Disconnect.

# zone.internal.force_gc_policy

# Description

When a certain number of messages, or bytes, are received, a garbage collection is forced.

Format: <Number> | <Bytes>.

For example, 16000|16MB means that when 16000 messages are received, or a byte of 16MB flows in, a garbage collection is forced.

# zone.internal.wildcard_subscription

# Description

Whether to support subscribing to wildcard topics.

# zone.internal.shared_subscription

# Description

Whether to support shared subscriptions.

# zone.internal.max_subscriptions

# Description

The maximum number of topics that a single client is allowed to subscribe to. 0 means no limit.

# zone.internal.max_inflight

# Description

Inflight window size: The flight window is used to store unanswered QoS 1 and QoS 2 messages.

# zone.internal.max_awaiting_rel

# Description

The maximum receiving window for QoS 2 messages, that configures how many QoS 2 messages from the client can be processed by EMQX Broker simultaneously. 0 means no limit.

# zone.internal.max_mqueue_len

# Description

The maximum length of the message queue. When the flight window is full, or the client is offline, the message will be stored in the queue. 0 means no limit.

# zone.internal.mqueue_store_qos0

# Description

Whether the message queue stores QoS 0 messages.

# zone.internal.enable_flapping_detect

# Description

Whether to enable Flapping check.

# zone.internal.force_shutdown_policy

# Description

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

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

Format: <Number> | <Bytes>.

For example, 32000|32MB means that when the process accumulates 32000 messages, or the process occupies memory up to 32MB, the process is closed.

# zone.internal.mountpoint

# Description

After topic mount point is configured, all subscribed and published topics will be prefixed by EMQX Broker.

The available placeholders are:

• %c：Client ID.
• %u：Username.

For example, if the mount point is set to user/%c/. , when the client with client ID tom publishes the topic open message, the topic actually routed in EMQX Broker is user/tom/open.

# zone.internal.ignore_loop_deliver

# Description

Whether to ignore the message sent by itself. If ignored, it means that EMQX Broker will not deliver this message to the sender of the message.

# zone.internal.strict_mode

# Description

Whether to enable the strict check mode. The strict check mode will check the correctness of the MQTT message in more detail.

# zone.internal.bypass_auth_plugins

# Description

Whether to allow clients under this zone to bypass the authentication step of the authentication plugin.

# listener.tcp.external

# Description

Configure the listening address of the MQTT / TCP listener named external, both IPv4 and IPv6 are supported.

# Example

To configure an IPv4 address, you may refer to:

• 0.0.0.0:1883: Listen to activities from all IPs on port 1883.
• 127.0.0.1:1883: Listen to all activities from IP 127.0.0.1 on port 1883.

To configure an IPv6 address, you may refer to:

• ::1:1883: Listen to all activities from IP ::1 on port 1883.

# listener.tcp.external.acceptors

# Description

The size of the listener's receiving pool.

# listener.tcp.external.max_connections

# Description

The maximum number of concurrent connections allowed by the listener.

# listener.tcp.external.max_conn_rate

# Description

The maximum access rate allowed by the listener. Unit: pcs / sec

# listener.tcp.external.active_n

# Description

The number of times the listener continues to receive TCP packets.

# listener.tcp.external.zone

# Description

The configuration zone to which the listener belongs.

# listener.tcp.external.rate_limit

# Description

The rate limit of the listener. The format is <limit>,<duration>.

# Example

100KB,10s：Limit the number of incoming bytes within 10 seconds not to exceed 100 KB.

# listener.tcp.external.access.1

# Description

List of ACL rules of the listener. It is used to set the white/black list of the connection layer.

# Example

allow all：Allow all TCP connections. allow 192.168.0.0/24：Allow TCP connection with network address 192.168.0.0/24.

At the same time, this configuration can configure multiple rules:

listener.tcp.external.access.1 = deny 192.168.0.1
listener.tcp.external.access.2 = allow all
 
    Copied!
  

It means that all TCP connections except 192.168.0.1 are allowed.

# listener.tcp.external.proxy_protocol

# Description

Whether the listener enables Proxy Protocol support.

If the EMQX cluster is deployed behind HAProxy or Nginx, and you need to get the client's real source IP address and port, you need to enable this configuration.

Proxy Protcol : https://www.haproxy.com/blog/haproxy/proxy-protocol (opens new window).

# listener.tcp.external.proxy_protocol_timeout

# Description

Set the timeout for Proxy Protocol parsing. If no Proxy Protocol packet is received within this time, EMQX Broker will close its connection.

# listener.tcp.external.peer_cert_as_username

# Description

Use the client certificate to override the value of the Username field. The optional values are:

• cn: the Common Name of the client certificate
• dn: the Subject Name of the client certificate
• crt: the DER-encoded binary of the client certificate
• pem: base64 encoded string based on the DER-encoded binary
• md5: MD5 hash of the DER-encoded binary

Note: Under TCP listener, this configuration is only available if the load balancing server terminates the SSL deployment; and the load balancing server needs to be configured to send the content of the certificate domain to EMQX. For example, for HAProxy, see send-proxy-v2-ssl (opens new window)

# listener.tcp.external.peer_cert_as_clientid

# Description

Use the client certificate to override the value of the ClientID field. The meaning of the optional values is the same as above.

# listener.tcp.external.backlog

# Description

The maximum length of the TCP connection queue. It indicates the maximum number of TCP connection queues that are allowed in the system to undergo three-time handshake.

# listener.tcp.external.send_timeout

# Description

Timeout for sending TCP packets.

# listener.tcp.external.send_timeout_close

# Description

Whether to close the connection after TCP packet sending timeout.

# listener.tcp.external.recbuf

# Description

TCP receiving buffer size (operating system kernel parameter)

Reference: http://erlang.org/doc/man/inet.html

# listener.tcp.external.sndbuf

# Description

TCP sending buffer size (operating system kernel parameter).

Reference:http://erlang.org/doc/man/inet.html (opens new window).

# listener.tcp.external.buffer

# Description

TCP buffer size (user level).

This value is recommended to be greater than or equal to the maximum value of sndbuff and recbuff to avoid some performance problems. Without configuration, it equals to the maximum value of sndbuff and recbuff by default.

Reference: http://erlang.org/doc/man/inet.html (opens new window).

# listener.tcp.external.tune_buffer

# Description

If this configuration is enabled, please set the value equal to the maximum value of sndbuff and recbuff.

# listener.tcp.external.nodelay

# Description

This is the TCP_NODELAY parameter. Enabling this option allows small TCP data packets to be sent immediately.

# listener.tcp.external.reuseaddr

# Description

This is the SO_REUSEADDR parameter. Enabling this option allows the local port to be reused without waiting for the end of the TIME_WAIT state.

# listener.tcp.internal

# Description

Configure the listening address of the MQTT / TCP listener named internal, both IPv4 and IPv6 are supported.

# Example

To configure an IPv4 address, you may refer to:

• 0.0.0.0:11883: Listen to activities from all IPs on port 11883.
• 127.0.0.1:11883: Listen to all activities from IP 127.0.0.1 on port 11883.

To configure an IPv6 address, you may refer to:

• ::1:11883: Listen to all activities from IP ::1 on port 11883.

# listener.tcp.internal.acceptors

# Description

The size of the listener's receiving pool.

# listener.tcp.internal.max_connections

# Description

The maximum number of concurrent connections allowed by the listener.

# listener.tcp.internal.max_conn_rate

# Description

The maximum access rate allowed by the listener. Unit: pcs / sec

# listener.tcp.internal.active_n

# Description

The number of times the listener continues to receive TCP packets.

# listener.tcp.internal.zone

# Description

The configuration zone to which the listener belongs.

# listener.tcp.internal.rate_limit

# Description

The rate limit of the listener. The format is <limit>,<duration>.

# Example

100KB,10s：Limit the number of incoming bytes within 10 seconds no tot exceed 100 KB.

# listener.tcp.internal.backlog

# Description

The maximum length of the TCP connection queue. It indicates the maximum number of TCP connection queues that are allowed in the system to undergo three-time handshake.

# listener.tcp.internal.send_timeout

# Description

Timeout for sending TCP packets.

# listener.tcp.internal.send_timeout_close

# Description

Whether to close the connection after TCP packet sending timeout.

# listener.tcp.internal.recbuf

# Description

TCP receiving buffer size (operating system kernel parameter)

# listener.tcp.internal.sndbuf

# Description

TCP sending buffer size (operating system kernel parameter)

# listener.tcp.internal.buffer

# Description

TCP buffer size (user level).

# listener.tcp.internal.tune_buffer

# Description

If this configuration is enabled, please set the value equal to the maximum value of sndbuff and recbuff.

# listener.tcp.internal.nodelay

# Description

This is the TCP_NODELAY parameter. Enabling this option allows small TCP data packets to be sent immediately.

# listener.tcp.internal.reuseaddr

# Description

This is the SO_REUSEADDR parameter. Enabling this option allows the local port to be reused without waiting for the end of the TIME_WAIT state.

# listener.ssl.external

# Description

Configure an SSL listener named external, both IPv4 and IPv6 are supported.

# Example

To configure an IPv4 address, you may refer to:

• 0.0.0.0:8883: Listen to activities from all IPs on port 8883.
• 127.0.0.1:8883: Listen to all activities from IP 127.0.0.1 on port 8883.

To configure an IPv6 address, you may refer to:

• ::1:8883: Listen to all activities from IP ::1 on port 8883.

# listener.ssl.external.acceptors

# Description

The size of the listener's receiving pool.

# listener.ssl.external.max_connections

# Description

The maximum number of concurrent connections allowed by the listener.

# listener.ssl.external.max_conn_rate

# Description

The maximum access rate allowed by the listener. Unit: pcs / sec.

# listener.ssl.external.active_n

# Description

The number of times the listener continues to receive TCP packets.

# listener.ssl.external.zone

# Description

The configuration group to which the listener belongs.

# listener.ssl.external.access.1

# Description

List of ACL rules of the listener. It is used to set the white/black list of the connection layer.

For example:

allow all：Allow all TCP connections. allow 192.168.0.0/24：Allow TCP connection with network address 192.168.0.0/24 to access.

At the same time, the configuration can configure multiple rules:

listener.ssl.external.access.1 = deny 192.168.0.1
listener.ssl.external.access.2 = allow all
 
    Copied!
  

# listener.ssl.external.rate_limit

# Description

Listener rate limit, with the format of <limit>,<duration>.

# listener.ssl.external.proxy_protocol

# Description

Whether the listener enables Proxy Protocol support.

If the EMQX cluster is deployed behind HAProxy or Nginx, and it is required to get the client's real source IP address and port, you need to enable this configuration.

Proxy Protcol reference: https://www.haproxy.com/blog/haproxy/proxy-protocol (opens new window).

# listener.ssl.external.proxy_protocol_timeout

# Description

Set the timeout for Proxy Protocol parsing. If no Proxy Protocol packet is received within this time, EMQX Broker will close its connection.

# listener.ssl.external.tls_versions

# Description

Specify the SSL version list supported by the server. For details, see http://erlang.org/doc/man/ssl.html (opens new window).

# listener.ssl.external.handshake_timeout

# Description

Specify the timeout period for the SSL handshake process.

# listener.ssl.external.depth

# Description

Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.

# listener.ssl.external.key_password

# Description

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

# listener.ssl.external.keyfile

# Description

File path to the server's private key.

# listener.ssl.external.certfile

# Description

File path to the server's certificate.

# listener.ssl.external.cacertfile

# Description

File path to the CA certificates. It should include all intermediate CA certificates and root CA certificate of the server certificate. It should also include trusted CAs to validate client certificates when verify configuration is set to verify_peer.

# listener.ssl.external.enable_ocsp_stapling

# Description

Introduced in e4.4.11.

Whether to enable OCSP stapling for the listener. If set to true, requires definining the OCSP responder URL. Such responses will be cached and sent to the connecting clients as part of the TLS handshake. This is only supported for TLS 1.2 and TLS 1.3.

# listener.ssl.external.ocsp_responder_url

# Description

Introduced in e4.4.11.

URL for the OCSP responder to check the server certificate against when OCSP stapling is enabled. This response is cached and refresh periodically.

# listener.ssl.external.ocsp_issuer_pem

# Description

Introduced in e4.4.11.

Path to the file containing PEM-encoded certificate of the OCSP Stapling issuer. This certificate is used to validate that the stapling sent by a trusted server.

# listener.ssl.external.ocsp_refresh_interval

# Description

Introduced in e4.4.11.

The period to refresh the OCSP response for the server. Even if the response fails to be fetched during a refresh, the previously cached response will still be used until a newer response is successfully retrieved from the OCSP responder. Cannot be shorter than 1 minute.

# listener.ssl.external.ocsp_refresh_http_timeout

# Description

Introduced in e4.4.11.

The timeout for the HTTP request when fetching OCSP responses from the OCSP responder.

# listener.ssl.external.enable_crl_check

# Description

Introduced in e4.4.11.

Whether to enable CRL verification and caching for this listener.

Note: In the event of cache miss, EMQX will attempt to fetch the CRL on the fly from the URL declared in the client certificate's distribution point(s). If no corresponding CRL is cached or fetched successfully and CRL check is enabled, then the client will be denied connection.

# listener.ssl.external.crl_cache_urls

# Description

Introduced in e4.4.11.

Comma-separated URL list for CRL servers to fetch and cache CRLs from. Must include the path to the CRL file(s) in the paths (e.g.: http://my.crl.server/intermediate.crl.pem, http://my.other.crl.server/another.crl.pem).

# crl_cache_http_timeout

# Description

Introduced in e4.4.11.

The timeout for the HTTP request when fetching CRLs. This is global for all listeners.

# crl_cache_refresh_interval

# Description

Introduced in e4.4.11.

The period to refresh the CRLs from the servers. This is global for all URLs and listeners. Cannot be shorter than 1 minute.

# listener.ssl.external.dhfile

# Description

If using the Ephemeral Diffie-Hellman algorithm, specify the key file used by the algorithm.

# listener.ssl.external.verify

# Description

Specifies whether to verify the client during the handshake.

# listener.ssl.external.partial_chain

# Description

When EMQX verifies a client certificate during the x509 path validation process, it constructs a certificate chain that starts with the client certificate and ends with a trust anchor.

By default, if the setting is set to false, the trust anchor is the rootCA, and the certificate chain must be complete.

However, if the setting is set to true or cacert_from_cacertfile, the last certificate in the cacertfile will be used as the trust anchor certificate (such as an intermediate CA). This creates a partial chain in the path validation.

Alternatively, if the setting is set to two_cacerts_from_cacertfile, one of the last two certificates in the cacertfile will be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.

# listener.ssl.external.verify_peer_ext_key_usage

# Description

For additional client certificate validation, the value defined here must present in the 'Extended Key Usage' of client certificate defined in rfc5280 (opens new window).

Allowed values are

• "clientAuth"
• "serverAuth"
• "codeSigning"
• "emailProtection"
• "timeStamping"
• "ocspSigning"
• raw OID, example: "OID:1.3.6.1.5.5.7.3.2"

Comma-separated string is also supported for validating the subset of key usages.

example, "serverAuth,OID:1.3.6.1.5.5.7.3.2"

# listener.ssl.external.fail_if_no_peer_cert

# Description

If the client does not have a certificate during the SSL handshake, it determines whether to let the handshake fail.

# listener.ssl.external.ciphers

# Description

Specify the cipher suite supported by the server.

# listener.ssl.external.psk_ciphers

# Description

If using the PSK algorithm, specify the PSK Cipher list supported by the server. Note that only one of 'listener.ssl.external.ciphers' and 'listener.ssl.external.psk_ciphers' can be configured.

# listener.ssl.external.secure_renegotiate

# Description

Specifies whether to reject renegotiation requests if the client does not follow RFC 5746

# listener.ssl.external.reuse_sessions

# Description

Specify whether to support SSL session reuse. For details, seehttp://erlang.org/doc/man/ssl.html (opens new window).

# listener.ssl.external.honor_cipher_order

# Description

Specify whether to use the server's preferences to select Ciphers.

# listener.ssl.external.peer_cert_as_username

# Description

Use the client certificate to override the value of the Username field. The optional values are:

• cn: the Common Name of the client certificate
• dn: the Subject Name of the client certificate
• crt: the DER-encoded binary of the client certificate
• pem: base64 encoded string based on the DER-encoded binary
• md5: MD5 hash of the DER-encoded binary

Note that listener.ssl.external.verify should be set to verify_peer.

# listener.tcp.external.peer_cert_as_clientid

# Description

Use the client certificate to override the value of the ClientID field. The meaning of the optional values is the same as above.

# listener.ssl.external.backlog

# Description

The maximum length of the TCP connection queue. It indicates the maximum number of TCP connection queues that are allowed in the system to undergo three-time handshake.

# listener.ssl.external.send_timeout

# Description

Timeout for sending TCP packets.

# listener.ssl.external.send_timeout_close

# Description

Whether to close the connection after TCP packet sending timeout.

# listener.ssl.external.recbuf

# Description

TCP receiving buffer size (operating system kernel level parameter).

Reference:http://erlang.org/doc/man/inet.html (opens new window).

# listener.ssl.external.sndbuf

# Description

TCP sending buffer size (operating system kernel level parameter).

Reference:http://erlang.org/doc/man/inet.html (opens new window).

# listener.ssl.external.buffer

# Description

CP buffer size (user level).

This value is recommended to be greater than or equal to the maximum value of sndbuff and recbuff to avoid some performance problems. Without configuration, it equals to the maximum value of sndbuff and recbuff by default.

Reference:http://erlang.org/doc/man/inet.html (opens new window).

# listener.ssl.external.tune_buffer

# Description

If this configuration is enabled, please set the value equal to the maximum value of sndbuff and recbuff.

# listener.ssl.external.nodelay

# Description

This is the TCP_NODELAY parameter. Enabling this option means that the Nagle algorithm is disabled and small packets will be sent immediately.

# listener.ssl.external.reuseaddr

# Description

This is the SO_REUSEADDR parameter. Enabling this option allows the local port to be reused without waiting for the end of the TIME_WAIT state.

# listener.ws.external

# Description

Configure the listening address of the MQTT/WS listener named external, both IPv4 and IPv6 are supported.

# Example

To configure an IPv4 address, you may refer to:

• 0.0.0.0:8083: Listen to activities from all IPs on port 8083.
• 127.0.0.1:8083: Listen to all activities from IP 127.0.0.1 on port 8083.

To configure an IPv6 address, you may refer to:

• ::1:8083: Listen to all activities from IP ::1 on port 8083.

# listener.ws.external.mqtt_path

# Description

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

# listener.ws.external.acceptors

# Description

The size of the listener's receiving pool.

# listener.ws.external.max_connections

# Description

The maximum number of concurrent connections allowed by the listener.

# listener.ws.external.max_conn_rate

# Description

The maximum access rate allowed by the listener. Unit: pcs/sec

# listener.ws.external.active_n

# Description

The number of times the listener continues to receive TCP packets.

# listener.ws.external.rate_limit

# Description

The rate limit of the listener. The format is <limit>,<duration>.

# Example

100KB,10s： Limit the number of incoming bytes within 10 seconds to not exceed 100 KB.

# listener.ws.external.zone

# Description

The configuration zone to which the listener belongs.

# listener.ws.external.access.1

# Description

List of ACL rules of the listener. It is used to set the white/black list of the connection layer.

# listener.ws.external.verify_protocol_header

# Description

Whether to verify that the HTTP header carried by WebSocket is correct. WeChat applet needs to disable this verification.

# listener.ws.external.fail_if_no_subprotocol

# Description

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

# listener.ws.external.supported_subprotocols

# Description

Specify the supported subprotocols, separated by commas.

# listener.ws.external.proxy_address_header

# Description

If the EMQX cluster is deployed behind HAProxy or Nginx, you can open the configuration to obtain the real IP address of the client.

# listener.ws.external.proxy_port_header

# Description

If the EMQX cluster is deployed behind HAProxy or Nginx, you can open the configuration to get the real port of the client.

# listener.ws.external.proxy_protocol

# Description

Whether the listener enables Proxy Protocol support.

If the EMQX cluster is deployed behind HAProxy or Nginx, and you need to get the client's real source IP address and port, you need to open this configuration.

Proxy Protcol reference: https://www.haproxy.com/blog/haproxy/proxy-protocol (opens new window).

# listener.ws.external.proxy_protocol_timeout

# Description

Set the timeout for Proxy Protocol parsing. If no Proxy Protocol packet is received within this time, EMQX Broker will close its connection.

# listener.ws.external.backlog

# Description

The maximum length of the TCP connection queue. It indicates the maximum number of TCP connection queues that are allowed in the system to undergo three-time handshake.

# listener.ws.external.send_timeout

# Description

Timeout for sending TCP packets.

# listener.ws.external.send_timeout_close

# Description

Whether to close the connection after TCP packet sending timeout.

# listener.ws.external.recbuf

# Description

TCP receiving buffer size (operating system kernel level parameter)

# listener.ws.external.sndbuf

# Description

TCP sending buffer size (operating system kernel level parameter)

# listener.ws.external.buffer

# Description

TCP buffer size (user level).

# listener.ws.external.tune_buffer

# Description

If this configuration is enabled, please set the value equal to the maximum value of sndbuff and recbuff.

# listener.ws.external.nodelay

# Description

This is the TCP_NODELAY parameter. Enabling this option allows small TCP data packets to be sent immediately.

# listener.ws.external.compress

# Description

Whether to compress WebSocket messages. The implementation of compression depends on zlib (opens new window).

The configuration items under defalte_opts belong to the compression-related parameter configuration, if not necessary, please do not modify it.

# listener.ws.external.deflate_opts.level

# Description

compression level

# listener.ws.external.deflate_opts.mem_level

# Description

Compression parameters. It means memory usage limit level, and configure how much memory can be opened to participate in the compression process.

1: The least memory, but will reduce the compression rate. 9: The most memory, and will increase the calculation speed and compression rate.

If not configured, the default is 8.

# listener.ws.external.deflate_opts.strategy

# Description

Compression strategy for tuning compression ratio:

• default: for ordinary data.
• filtered: data generated by filters or predictors, suitable for content with strong randomness.
• huffman_only: Mandatory use of Huffman algorithm. Better than filtered.
• rle: limit the matching distance to 1 (Run-Lenght Encoding), faster than huffman_only, but mainly used for PNG images.

These strategies only affect the compression ratio and will not have any impact on correctness.

# listener.ws.external.deflate_opts.server_context_takeover

# Description

Whether to allow the server's compression context to be passed between frames.

# listener.ws.external.deflate_opts.client_context_takeover

# Description

Whether to allow the client's compression context to be passed between frames.

# listener.ws.external.deflate_opts.server_max_window_bits

# Description

Maximum window value on the server side. Setting a larger value will result in better compression ratio, but will consume additional memory.

# listener.ws.external.deflate_opts.client_max_window_bits

# Description

Client maximum window value. Setting a larger value will result in better compression ratio, but will consume additional memory.

# listener.ws.external.idle_timeout

# Description

The daze time after the TCP connection is established. If no packets are received within this time, the connection will be closed.

# listener.ws.external.max_frame_size

# Description

The maximum allowed length of a single MQTT packet.

# listener.wss.external

# Description

Configure a WSS (MQTT/WebSocket/SSL) listener named external, both IPv4 and IPv6 are supported.

# Example

To configure an IPv4 address, you may refer to:

• 0.0.0.0:8084: Listen to activities from all IPs on port 8084.
• 127.0.0.1:8084: Listen to all activities from IP 127.0.0.1 on port 8084.

To configure an IPv6 address, you may refer to:

• ::1:8084: Listen to all activities from IP ::1 on port 8084.

# listener.wss.external.mqtt_path

# Description

WebSocket URL Path.

# listener.wss.external.acceptors

# Description

The size of the listener's receiving pool.

# listener.wss.external.max_connections

# Description

The maximum number of concurrent connections allowed by the listener.

# listener.wss.external.max_conn_rate

# Description

The maximum access rate allowed by the listener. Unit: pcs/sec.

# listener.wss.external.active_n

# Description

The number of times the listener continues to receive TCP packets.

# listener.wss.external.rate_limit

# Description

The rate limit of the listener. The format is <limit>,<duration>.

# listener.wss.external.zone

# Description

The configuration group to which the listener belongs.

# listener.wss.external.access.1

# Description

List of ACL rules of the listener. It is used to set the white/black list of the connection layer.

E.g:

allow all: Allow all TCP connections. allow 192.168.0.0/24: Allow TCP connections with a network address of 192.168.0.0 / 24 to access.

At the same time, the configuration can configure multiple rules:

listener.wss.external.access.1 = deny 192.168.0.1
listener.wss.external.access.2 = allow all
 
    Copied!
  

# listener.wss.external.fail_if_no_subprotocol

# Description

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

# listener.wss.external.supported_subprotocols

# Description

Specify the supported subprotocols, separated by commas.

# listener.wss.external.proxy_address_header

# Description

If the EMQX cluster is deployed in HAProxy or Nginx, you can open the configuration to obtain the real IP address of the client.

# listener.wss.external.proxy_protocol

# Description

Whether the listener enables Proxy Protocol support.

If the EMQX cluster is deployed behind HAProxy or Nginx, and you need to get the client's real source IP address and port, you need to open this configuration.

Proxy Protcol reference:https://www.haproxy.com/blog/haproxy/proxy-protocol (opens new window).

# listener.wss.external.proxy_protocol_timeout

# Description

Set the timeout for Proxy Protocol parsing. If no Proxy Protocol packet is received within this time, EMQX Broker will close its connection.

# listener.wss.external.peer_cert_as_username

# Description

Use the client certificate to override the value of the Username field. The optional values are:

• cn: the Common Name of the client certificate
• dn: the Subject Name of the client certificate
• crt: the DER-encoded binary of the client certificate
• pem: base64 encoded string based on the DER-encoded binary
• md5: MD5 hash of the DER-encoded binary

Note that listener.wss.external.verify should be set to verify_peer.

# listener.wss.external.peer_cert_as_clientid

# Description

Use the client certificate to override the value of the ClientID field. The meaning of the optional values is the same as above.

# listener.wss.external.tls_versions

# Description

Specify the SSL version list supported by the server. For details, see http://erlang.org/doc/man/ssl.html (opens new window).

# listener.wss.external.keyfile

# Description

File path to server's private key.

# listener.wss.external.certfile

# Description

File path to the server's certificate.

# listener.wss.external.cacertfile

# Description

File path to the CA certificates. It should include all intermediate CA certificates and root CA certificate of the server certificate. It should also include trusted CAs to validate client certificates when verify configuration is set to verify_peer.

# listener.wss.external.depth

# Description

Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.

# listener.wss.external.key_password

# Description

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

# listener.wss.external.dhfile

# Description

If using the Ephemeral Diffie-Hellman algorithm, specify the key file used by the algorithm.

# listener.wss.external.verify

# Description

Specifies whether to verify the client during the handshake.

# listener.wss.external.fail_if_no_peer_cert

# Description

If the client does not have a certificate during the SSL handshake, it determines whether to let the handshake fail.

# listener.wss.external.ciphers

# Description

Specifies the cipher suite supported by the server.

# listener.wss.external.psk_ciphers

# Description

If using the PSK algorithm, specify the PSK Cipher list supported by the server. Note that only one of 'listener.wss.external.ciphers' and 'listener.wss.external.psk_ciphers' can be configured.

# listener.wss.external.secure_renegotiate

# Description

Specifies whether to reject renegotiation requests if the client does not follow RFC 5746

# listener.wss.external.reuse_sessions

# Description

Specifies whether to support SSL session reuse. For details, see http://erlang.org/doc/man/ssl.html (opens new window).

# listener.wss.external.honor_cipher_order

# Description

Specify whether to use the server's preferences to select Ciphers.

# listener.wss.external.peer_cert_as_username

# Description

Use the value of the CN, DN, or CRT field in the client certificate as the value of the Username field in the MQTT CONNECT packet. Note that listener.wss.external.verify should be set to verify_peer.

# listener.wss.external.backlog

# Description

The maximum length of the TCP connection queue. It indicates the maximum number of TCP connection queues that are allowed in the system to undergo three-time handshake.

# listener.wss.external.send_timeout

# Description

Timeout for sending TCP packets.

# listener.wss.external.send_timeout_close

# Description

Whether to close the connection after TCP packet sending timeout.

# listener.wss.external.recbuf

# Description

TCP receiving buffer size (operating system kernel level parameter)

Reference:http://erlang.org/doc/man/inet.html

# listener.wss.external.sndbuf

# Description

TCP sending buffer size (operating system kernel level parameter)

Reference:http://erlang.org/doc/man/inet.html

# listener.wss.external.buffer

# Description

TCP buffer size (user level).

This value is recommended to be greater than or equal to the maximum value of sndbuff and recbuff to avoid some performance problems. Without configuration, it equals to the maximum value of sndbuff and recbuff by default.

Reference:http://erlang.org/doc/man/inet.html

# listener.wss.external.tune_buffer

# Description

If you open this configuration, please set the value equal to the maximum value of sndbuff and recbuff.

# listener.wss.external.nodelay

# Description

This is the TCP_NODELAY parameter. Enabling this option allows small TCP data packets to be sent immediately.

# listener.wss.external.compress

# Description

If this option is set to true, Websocket messages will be compressed.

# listener.wss.external.deflate_opts.level

# Description

Compression level.

# listener.wss.external.deflate_opts.mem_level

# Description

Compression parameters. It means memory usage limit level, configures how much memory can be opened to participate in the compression process.

1: The least memory, but will reduce the compression rate. 9: The most memory, and will increase the calculation speed and compression rate.

If not configured, the default is 8.

# listener.wss.external.deflate_opts.strategy

# Description

Compression strategy for tuning compression ratio:

• default: for ordinary data.
• filtered: data generated by filters or predictors, suitable for content with strong randomness.
• huffman_only: Mandatory use of Huffman algorithm. Better than filtered.
• rle: limit the matching distance to 1 (Run-Lenght Encoding), faster than huffman_only, but mainly used for PNG images.

These strategies only affect the compression ratio and will not have any impact on correctness.

# listener.wss.external.deflate_opts.server_context_takeover

# Description

Whether to allow the server's compression context to be passed between frames.

# listener.wss.external.deflate_opts.client_context_takeover

# Description

Whether to allow the client's compression context to be passed between frames.

# listener.wss.external.deflate_opts.server_max_window_bits

# Description

Maximum window value on the server side. Setting a larger value will result in better compression ratio, but will consume additional memory.

# listener.wss.external.deflate_opts.client_max_window_bits

# Description

Client maximum window value. Setting a larger value will result in better compression ratio, but will consume additional memory.

# listener.wss.external.idle_timeout

# Description

The daze time after the TCP connection is established. If no packets are received within this time, the connection will be closed.

# listener.wss.external.max_frame_size

# Description

The maximum length of a single MQTT packet.

# plugins.etc_dir

# Description

The configuration directory of the plugin.

# plugins.loaded_file

# Description

The configuration file path of the plugin startup list.

# plugins.expand_plugins_dir

# Description

External plugin storage directory.

# broker.sys_interval

# Description

Set the system topic ($SYS) message release interval.

# broker.sys_heartbeat

# Description

Set the system heartbeat message release interval. The system heartbeat message includes the following two topics:

• "$SYS/brokers/<node>/uptime"
• "$SYS/brokers/<node>/datetime"

# broker.enable_session_registry

# Description

Enable or disable global session registration.

# broker.session_locking_strategy

# Description

Set the type of session cluster lock. The session cluster lock is used to prevent the same client from creating multiple sessions on multiple different nodes, which is common when clients frequently switch between nodes for logging.

# broker.shared_subscription_strategy

# Description

Set a dispatch strategy for shared subscribers. Options are:

• hash_clientid: Map (hash) publisher ClientID to subscriber.
• hash_topic: Map (hash) source MQTT topic to subscriber.
• local: Select a random subscriber in the group locally in the node which is processing the shared-publish request. If there is no such local subscriber, it fallbacks to random strategy
• random: Choose randomly among all subscribers.
• round_robin: Enumerate subscribers in (unsorted) order.
• sticky: First dispatch is random, then stick to it for all subsequent messages until that subscriber goes disconnected or that publisher reconnects.

# broker.sample_group.shared_subscription_strategy

Overrides the dispatch strategy for a shared subscription group named sample_group. If not configured, broker.shared_subscription_strategy is used,

Where sample_group can be configured to any group name.

The available strategies are the same as broker.shared_subscription_strategy.

# broker.shared_dispatch_ack_enabled

# Description

Enable or disable the ACK check function for qos1/qos2 messages in shared subscriptions. After enabling, if it is delivered to a subscriber but fails to receive the ACK, it will try to deliver to the next subscriber in the subscription group.

# broker.route_batch_clean

# Description

Enable or disable batch cleanup routing information. Batch cleanup routing can be used in a short period of time when a large number of clients go offline to improve cleanup efficiency.

# broker.perf.route_lock_type = key

# Description

Choose the granularity of the database lock when updating the routing information for whildcard subscriptions.

• key (default) is to take a lock for each key representing prefixes of a wildcard topic;
• tab is to take the lock for the entire table which stores prefixes of wildcard topics;
• global is to take a global lock.

Options tab and global are recommended for large scale clusters (e.g. more than 7 nodes) especially when network latency between the nodes is at milliseconds level. NOTE: It requires entire cluster to be stopped before changing this config.

# broker.perf.trie_compaction

# Description

Set to true to compact the routing information table for wildcard topics. Compaction is optimized for writes, handles high rate subscription requests quicker, it also requires half of the RAM comparing to non-compacted. Non-compaction is optimized for reads (e.g. large number of topic levels in publish requests).

NOTE: Changing from false to true can be done by rolling-restart the nodes in a cluster. The safe way of changing from true to false is to stop all nodes in the cluster, otherwise some message may not get routed before all nodes have restarted.

# sysmon.long_gc

# Description

Enable garbage collection time monitoring and trigger an alarm when the collection time exceeds the set value, 0 means disabling this monitoring.

# monitor

# sysmon.long_schedule

# Description

Enable process scheduling time monitoring and trigger an alarm when the scheduling time exceeds the set value, 0 means disabling this monitoring.

# sysmon.large_heap

# Description

Enable stack size monitoring and trigger an alarm when the stack size is still greater than the set value after the process performs garbage collection. 0 means disabling this monitoring.

# sysmon.busy_port

# Description

Specifies whether to enable inter-process message channel busy monitoring.

# sysmon.busy_dist_port

# Description

Specifies whether to enable cluster RPC channel busy monitoring.

# os_mon.cpu_check_interval

# Description

CPU usage rate check cycle.

# os_mon.cpu_high_watermark

# Description

An alarm will be triggered when the CPU usage exceeds os_mon.cpu_high_watermark.

# os_mon.cpu_low_watermark

# Description

The alarm will be cleared when the CPU usage drops back below os_mon.cpu_low_watermark .

# os_mon.mem_check_interval

# Description

Memory usage check cycle.

# os_mon.sysmem_high_watermark

# Description

When the memory allocated by EMQX Broker for all processes as a percentage of system memory exceeds os_mon.procmem_high_watermark, an alarm will be triggered.

# os_mon.procmem_high_watermark

# Description

When the memory allocated by EMQX Broker for a single process as a percentage of system memory exceeds os_mon.procmem_high_watermark, an alarm will be triggered.

# vm_mon.check_interval

# Description

Check interval for process number.

# vm_mon.process_high_watermark

# Description

When the current process number as a percentage of the maximum process number exceeds vm_mon.process_high_watermark, an alarm will be triggered. The maximum process number is determined by the node.process_limit configuration item.

# vm_mon.process_low_watermark

# Description

When the percentage of the current number of processes in the maximum number of processes falls below vm_mon.process_low_watermark, an alarm will be triggered. The maximum number of processes is determined by the node.process_limit configuration item.

# Plugin emqx_auth_http

# auth.http.auth_req.url

# Description

Specify the target URL of the authentication request.

# auth.http.auth_req.method

# Description

Specify the request method of the authentication request.

# auth.http.auth_req.headers.<Any>

# Example

auth.http.auth_req.headers.content-type = application/x-www-form-urlencoded
auth.http.auth_req.headers.accept = */*
 
    Copied!
  

# Description

Specify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields.

# auth.http.auth_req.params

# Description

Specify the data carried in the authentication request. When using the GET method, the value of auth.http.auth_req.params will be converted into k=v key-value pairs separated by & and sent as query string parameters. When using the POST method, the value of auth.http.auth_req.params will be converted into k=v key-value pairs separated by & and sent in the form of Request Body. All placeholders will be replaced by run-time data , and the available placeholders are as follows:

# auth.http.super_req.url

# Description

Specify the target URL for the superuser authentication request.

# auth.http.super_req.method

# Description

Specifies the request method of the super user authentication request.

# auth.http.super_req.headers.<Any>

# Example

auth.http.super_req.headers.content-type = application/x-www-form-urlencoded
auth.http.super_req.headers.accept = */*
 
    Copied!
  

# Description

Specify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields.

# auth.http.super_req.params

# Description

Specify the data carried in the authentication request. When using the GET method, the value of auth.http.auth_req.params will be converted into k=v key-value pairs separated by & and sent as query string parameters. When using the POST method, the value of auth.http.auth_req.params will be converted into k=v key-value pairs separated by & and sent in the form of Request Body. All placeholders will be replaced by run-time data , and the available placeholders are the same as those of auth.http.auth_req.params.

# auth.http.acl_req.url

# Description

Specify the target URL for ACL verification requests.

# auth.http.acl_req.method

# Description

Specifies the request method for ACL verification requests.

# auth.http.acl_req.headers.<Any>

# Example

auth.http.acl_req.headers.content-type = application/x-www-form-urlencoded
auth.http.acl_req.headers.accept = */*
 
    Copied!
  

# Description

Specify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields.

# auth.http.acl_req.params

# Description

Specify the data carried in the authentication request. When using the GET method, the value of auth.http.auth_req.params will be converted into k=v key-value pairs separated by & and sent as query string parameters. When using the POST method, the value of auth.http.auth_req.params will be converted into k=v key-value pairs separated by & and sent in the form of Request Body. All placeholders will be replaced by run-time data , and the available placeholders are as follows:

# auth.http.timeout

# Description

HTTP request timeout. Any setting equivalent to 0s means never timeout.

# auth.http.connect_timeout

# Description

Connection timeout for HTTP requests. Any setting value equivalent to 0s means never time out.

# auth.http.pool_size

# Description

HTTP client connection process pool size.

# auth.http.ssl.cacertfile

# Description

CA certificate file path.

# auth.http.ssl.certfile

# Description

Client certificate file path.

# auth.http.ssl.keyfile

# Description

Client private key file path.

# Plugin emqx_auth_jwt

# auth.jwt.secret

# Description

Set HMAC Secret.

# auth.jwt.from

# Description

Where to get JWT. Optional values are

• username: The username field of the MQTT CONNECT packet is used as JWT.
• password: The password field of the MQTT CONNECT packet is used as JWT.

# auth.jwt.pubkey

# Description

If you use RSA or ECDSA encryption algorithm, you must specify the private key file.

# auth.jwt.verify_claims

# Description

Enable or disable Claims verification.

# auth.jwt.verify_claims.<claims>

# Description

When the Claims verification function is enabled, you can set optional values for fields in the JWT.

For example, if the value of sub in the Claim in JWT is expected to be" abc ", the following rules can be configured:

auth.jwt.verify_claims.sub = abc
 
    Copied!
  

The expected value supports two wildcards:

• %u: username
• %c: clientid

For example, if the value of the sub field in the JWT is expected to be the same as the username field in the MQTT CONNECT message, the following rules can be configured:

auth.jwt.verify_claims.sub = %u
 
    Copied!
  

# Plugin emqx_auth_ldap

# auth.ldap.servers

# Description

LDAP service address.

# auth.ldap.port

# Description

LDAP service port.

# auth.ldap.pool

# Description

Connection pool size.

# auth.ldap.bind_dn

# Description

The DN for logging into the LDAP service.

# auth.ldap.bind_password

# Description

The password for logging into the LDAP service.

# auth.ldap.timeout

# Description

The query timeout.

# auth.ldap.device_dn

# Description

The DN to which the client belongs.

# auth.ldap.match_objectclass

# Description

The name of the client object.

# auth.ldap.username.attributetype

# Description

The data type of the Username attribute.

# auth.ldap.password.attributetype

# Description

The data type of the Password attribute.

# auth.ldap.ssl

# Description

Whether to enable SSL.

# auth.ldap.ssl.certfile

# Description

SSL server certificate path.

# auth.ldap.ssl.keyfile

# Description

SSL server key file path.

# auth.ldap.ssl.cacertfile

# Description

CA certificate file path.

# auth.ldap.ssl.verify

# Description

SSL authentication method:

• verify_none：One-way authentication.
• verify_peer：Two-way authentication.

# auth.ldap.ssl.fail_if_no_peer_cert

# Description

If the client does not provide an SSL certificate, disconnect it.

# Plugin emqx_auth_mongo

# auth.mongo.type

# Description

Set the topology type of MongoDB:

• single: single node
• unknown: unknown
• sharded: sharding mode
• rs: replicated set

# auth.mongo.rs_set_name

# Description

Set the address of MongoDB service. If there are multiple items, use comma , to separate them.

# auth.mongo.pool

# Description

Set the number of processes in the MongoDB connection pool.

# auth.mongo.login

# Description

Set the MongoDB's username.

# auth.mongo.password

# Description

Set the MongoDB's password.

# auth.mongo.auth_source

# Description

Set the MongoDB authentication source database name.

# auth.mongo.database

# Description

Set MongoDB database name.

# auth.mongo.query_timeout

# Description

Set the timeout for accessing MongoDB.

# auth.mongo.ssl

# Description

Set whether to use SSL to access MongoDB.

# auth.mongo.ssl_opts.keyfile

# Description

If using SSL to access MongoDB, set the private key file of the SSL client.

# auth.mongo.ssl_opts.certfile

# Description

If using SSL to access MongoDB, set the SSL client certificate file.

# auth.mongo.ssl_opts.cacertfile

# Description

If you use SSL to access MongoDB, set the SSL certificate file.

# auth.mongo.w_mode

# Description

Set the write mode of MongoDB.

# auth.mongo.r_mode

# Description

Set the read mode of MongoDB.

# auth.mongo.auth_query.collection

# Description

Collection name used in the authentication process.

# auth.mongo.auth_query.password_field

# Description

The main fields used in the authentication process. To add salt after the password, it can be configured as:

auth.mongo.auth_query.password_field = password,salt
 
    Copied!
  

# auth.mongo.auth_query.password_hash

# Description

Set the hash algorithm used for the password field. To add salt after the sha256 password, you can set it to:

auth.mongo.auth_query.password_hash = sha256,salt
 
    Copied!
  

To add salt before the sha256 password, you can set it to:

auth.mongo.auth_query.password_hash = salt,sha256
 
    Copied!
  

To add salt before the bcrypt password, you can set it to:

auth.mongo.auth_query.password_hash = salt,bcrypt
 
    Copied!
  

# auth.mongo.auth_query.selector

# Description

MongoDB statements are executed during the authentication process. Commands can support following wildcards:

• %u: username
• %c: clientid
• %C: Common Name in client TLS certificate
• %d: Subject in the client's TLS certificate

# auth.mongo.auth_query.super_query

# Description

Whether to use SuperUser in authentication.

# auth.mongo.super_query.collection

# Description

If using SuperUser, specify the MongoDB Collection of SuperUser.

# auth.mongo.super_query.selector

# Description

If SuperUser is used, specify the MongoDB statement used to query SuperUser.

# auth.mongo.acl_query

# Description

Whether to enable the ACL function.

# auth.mongo.acl_query.collection

# Description

If using the ACL function, specify the MongoDB Collection that queries the ACL rules.

# auth.mongo.acl_query.selector

# Description

If the ACL function is used, specify the MongoDB statement used to query the ACL rules. It can support multiple ACL statements, and "or" is used to connect multiple statements.

For example, configure the following two access rules:

auth.mongo.acl_query.selector.1 = username=%u
auth.mongo.acl_query.selector.2 = username=$all
 
    Copied!