Configuration Manual
listeners
Type Struct(listeners)tcp
Type Map($name->OneOf(Struct(mqtt_tcp_listener),String("marked_for_deletion")))Description TCP listeners.
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet.
Set to""to disable the feature.Variables in mountpoint string:
${clientid}: clientid${username}: username
zone
Type StringDefault defaultDescription The configuration zone to which the listener belongs. Clients connected to this listener will inherit zone-settings created under this zone name.
A zone can override the configs under below root names:
mqttforce_shutdownforce_gcflapping_detectdurable_sessions
enable_authn
Type Enum(true,false,quick_deny_anonymous)Default trueDescription Set
true(default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set tofalse, any client (with or without username/password) is allowed to connect. When set toquick_deny_anonymous, it behaves like when set totrue, but clients will be denied immediately without going through any authenticators ifusernameis not provided. This is useful to fence off anonymous clients early.max_conn_rate
Type StringDescription Maximum connection rate.
This is used to limit the connection rate for this node. Once the limit is reached, new connections will be deferred or refused.
For example:1000/s:: Only accepts 1000 connections per second1000/10s:: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Messages publish rate.
This is used to limit the inbound message numbers for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
For example:500/s:: Only the first 500 messages are sent per second and other messages are buffered.500/10s:: Only the first 500 messages are sent even 10 second and other messages are buffered.
bytes_rate
Type StringDescription Data publish rate.
This is used to limit the inbound bytes rate for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
The unit of the bytes could be:KB MB GB.
For example:500KB/s:: Only the first 500 kilobytes are sent per second and other messages are buffered.500MB/10s:: Only the first 500 megabytes are sent even 10 second and other messages are buffered.
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive
Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
ssl
Type Map($name->OneOf(Struct(mqtt_ssl_listener),String("marked_for_deletion")))Description SSL listeners.
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet.
Set to""to disable the feature.Variables in mountpoint string:
${clientid}: clientid${username}: username
zone
Type StringDefault defaultDescription The configuration zone to which the listener belongs. Clients connected to this listener will inherit zone-settings created under this zone name.
A zone can override the configs under below root names:
mqttforce_shutdownforce_gcflapping_detectdurable_sessions
enable_authn
Type Enum(true,false,quick_deny_anonymous)Default trueDescription Set
true(default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set tofalse, any client (with or without username/password) is allowed to connect. When set toquick_deny_anonymous, it behaves like when set totrue, but clients will be denied immediately without going through any authenticators ifusernameis not provided. This is useful to fence off anonymous clients early.max_conn_rate
Type StringDescription Maximum connection rate.
This is used to limit the connection rate for this node. Once the limit is reached, new connections will be deferred or refused.
For example:1000/s:: Only accepts 1000 connections per second1000/10s:: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Messages publish rate.
This is used to limit the inbound message numbers for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
For example:500/s:: Only the first 500 messages are sent per second and other messages are buffered.500/10s:: Only the first 500 messages are sent even 10 second and other messages are buffered.
bytes_rate
Type StringDescription Data publish rate.
This is used to limit the inbound bytes rate for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
The unit of the bytes could be:KB MB GB.
For example:500KB/s:: Only the first 500 kilobytes are sent per second and other messages are buffered.500MB/10s:: Only the first 500 megabytes are sent even 10 second and other messages are buffered.
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive
Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
ssl_options
Type Struct(listener_ssl_opts)cacertfile
Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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
Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert
Type BooleanDefault falseDescription 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).
client_renegotiation
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout
Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp
Type Struct(ocsp)refresh_interval
Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout
Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ws
Type Map($name->OneOf(Struct(mqtt_ws_listener),String("marked_for_deletion")))Description HTTP websocket listeners.
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet.
Set to""to disable the feature.Variables in mountpoint string:
${clientid}: clientid${username}: username
zone
Type StringDefault defaultDescription The configuration zone to which the listener belongs. Clients connected to this listener will inherit zone-settings created under this zone name.
A zone can override the configs under below root names:
mqttforce_shutdownforce_gcflapping_detectdurable_sessions
enable_authn
Type Enum(true,false,quick_deny_anonymous)Default trueDescription Set
true(default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set tofalse, any client (with or without username/password) is allowed to connect. When set toquick_deny_anonymous, it behaves like when set totrue, but clients will be denied immediately without going through any authenticators ifusernameis not provided. This is useful to fence off anonymous clients early.max_conn_rate
Type StringDescription Maximum connection rate.
This is used to limit the connection rate for this node. Once the limit is reached, new connections will be deferred or refused.
For example:1000/s:: Only accepts 1000 connections per second1000/10s:: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Messages publish rate.
This is used to limit the inbound message numbers for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
For example:500/s:: Only the first 500 messages are sent per second and other messages are buffered.500/10s:: Only the first 500 messages are sent even 10 second and other messages are buffered.
bytes_rate
Type StringDescription Data publish rate.
This is used to limit the inbound bytes rate for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
The unit of the bytes could be:KB MB GB.
For example:500KB/s:: Only the first 500 kilobytes are sent per second and other messages are buffered.500MB/10s:: Only the first 500 megabytes are sent even 10 second and other messages are buffered.
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive
Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
websocket
Type Struct(ws_opts)mqtt_path
Type StringDefault "/mqtt"Description WebSocket's MQTT protocol path. By default, the full URL for the WebSocket client to connect is:
ws://{ip}:{port}/mqtt. Append/[...]to the end of the path to make EMQX accept any subpath. For example, specifyingmqtt/[...]would allow clients to connect at paths likemqtt/org1ormqtt/group2, etc.NOTE: An unmatched path will cause the client to be rejected immediately at the HTTP layer, meaning it will not be traceable at the MQTT layer.
idle_timeout
Type DurationDefault "7200s"Description Close transport-layer connections from the clients that have not sent MQTT CONNECT message within this interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
wss
Type Map($name->OneOf(Struct(mqtt_wss_listener),String("marked_for_deletion")))Description HTTPS websocket listeners.
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet.
Set to""to disable the feature.Variables in mountpoint string:
${clientid}: clientid${username}: username
zone
Type StringDefault defaultDescription The configuration zone to which the listener belongs. Clients connected to this listener will inherit zone-settings created under this zone name.
A zone can override the configs under below root names:
mqttforce_shutdownforce_gcflapping_detectdurable_sessions
enable_authn
Type Enum(true,false,quick_deny_anonymous)Default trueDescription Set
true(default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set tofalse, any client (with or without username/password) is allowed to connect. When set toquick_deny_anonymous, it behaves like when set totrue, but clients will be denied immediately without going through any authenticators ifusernameis not provided. This is useful to fence off anonymous clients early.max_conn_rate
Type StringDescription Maximum connection rate.
This is used to limit the connection rate for this node. Once the limit is reached, new connections will be deferred or refused.
For example:1000/s:: Only accepts 1000 connections per second1000/10s:: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Messages publish rate.
This is used to limit the inbound message numbers for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
For example:500/s:: Only the first 500 messages are sent per second and other messages are buffered.500/10s:: Only the first 500 messages are sent even 10 second and other messages are buffered.
bytes_rate
Type StringDescription Data publish rate.
This is used to limit the inbound bytes rate for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
The unit of the bytes could be:KB MB GB.
For example:500KB/s:: Only the first 500 kilobytes are sent per second and other messages are buffered.500MB/10s:: Only the first 500 megabytes are sent even 10 second and other messages are buffered.
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive
Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
ssl_options
Type Struct(listener_wss_opts)cacertfile
Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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
Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert
Type BooleanDefault falseDescription 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).
client_renegotiation
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout
Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
websocket
Type Struct(ws_opts)mqtt_path
Type StringDefault "/mqtt"Description WebSocket's MQTT protocol path. By default, the full URL for the WebSocket client to connect is:
ws://{ip}:{port}/mqtt. Append/[...]to the end of the path to make EMQX accept any subpath. For example, specifyingmqtt/[...]would allow clients to connect at paths likemqtt/org1ormqtt/group2, etc.NOTE: An unmatched path will cause the client to be rejected immediately at the HTTP layer, meaning it will not be traceable at the MQTT layer.
idle_timeout
Type DurationDefault "7200s"Description Close transport-layer connections from the clients that have not sent MQTT CONNECT message within this interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
quic
Type Map($name->OneOf(Struct(mqtt_quic_listener),String("marked_for_deletion")))Description QUIC listeners.
ciphers
Type Array(String)Default [TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256]Description 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 theversions, 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 fromversions.
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
ssl_options
Type Struct(listener_quic_ssl_opts)Description TLS options for QUIC transport
cacertfile
Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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
Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet.
Set to""to disable the feature.Variables in mountpoint string:
${clientid}: clientid${username}: username
zone
Type StringDefault defaultDescription The configuration zone to which the listener belongs. Clients connected to this listener will inherit zone-settings created under this zone name.
A zone can override the configs under below root names:
mqttforce_shutdownforce_gcflapping_detectdurable_sessions
enable_authn
Type Enum(true,false,quick_deny_anonymous)Default trueDescription Set
true(default) to enable client authentication on this listener, the authentication process goes through the configured authentication chain. When set tofalse, any client (with or without username/password) is allowed to connect. When set toquick_deny_anonymous, it behaves like when set totrue, but clients will be denied immediately without going through any authenticators ifusernameis not provided. This is useful to fence off anonymous clients early.max_conn_rate
Type StringDescription Maximum connection rate.
This is used to limit the connection rate for this node. Once the limit is reached, new connections will be deferred or refused.
For example:1000/s:: Only accepts 1000 connections per second1000/10s:: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Messages publish rate.
This is used to limit the inbound message numbers for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
For example:500/s:: Only the first 500 messages are sent per second and other messages are buffered.500/10s:: Only the first 500 messages are sent even 10 second and other messages are buffered.
bytes_rate
Type StringDescription Data publish rate.
This is used to limit the inbound bytes rate for this node. Once the limit is reached, the restricted client will slow down and even be hung for a while.
The unit of the bytes could be:KB MB GB.
For example:500KB/s:: Only the first 500 kilobytes are sent per second and other messages are buffered.500MB/10s:: Only the first 500 megabytes are sent even 10 second and other messages are buffered.
mqtt
Type Struct(mqtt)Description Global MQTT configuration. The configs here work as default values which can be overridden in
zoneconfigsidle_timeout
Type OneOf(String("infinity"),Duration)Default "15s"Description Configure the duration of time that a connection can remain idle (i.e., without any data transfer) before being:
- Automatically disconnected if no CONNECT package is received from the client yet.
- Put into hibernation mode to save resources if some CONNECT packages are already received. Note: Please set the parameter with caution as long idle time will lead to resource waste.
shared_subscription_strategy
Type Enum(random,round_robin,round_robin_per_group,sticky,local,hash_topic,hash_clientid)Default round_robinDescription Dispatch strategy for shared subscription.
random: Randomly select a subscriber for dispatch;round_robin: Messages from a single publisher are dispatched to subscribers in turn;round_robin_per_group: All messages are dispatched to subscribers in turn;local: Randomly select a subscriber on the current node, if there are no subscribers on the current node, then randomly select within the cluster;sticky: Continuously dispatch messages to the initially selected subscriber until their session ends;hash_clientid: Hash the publisher's client ID to select a subscriber;hash_topic: Hash the publishing topic to select a subscriber.
keepalive_multiplier
Type NumberDefault 1.5Description Keep-Alive Timeout = Keep-Alive interval × Keep-Alive Multiplier. The default value 1.5 is following the MQTT 5.0 specification. This multiplier is adjustable, providing system administrators flexibility for tailoring to their specific needs. For instance, if a client's 10-second Keep-Alive interval PINGREQ gets delayed by an extra 10 seconds, changing the multiplier to 2 lets EMQX tolerate this delay.
retry_interval
Type DurationDefault "30s"Description Retry interval for QoS 1/2 message delivering.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.peer_cert_as_username
Type Enum(disabled,cn,dn,crt,pem,md5)Default disabledDescription 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: CN field of the certificatedn: DN field of the certificatecrt: Content of theDERorPEMcertificatepem: ConvertDERcertificate content toPEMformat and use as Usernamemd5: MD5 value of theDERorPEMcertificate
peer_cert_as_clientid
Type Enum(disabled,cn,dn,crt,pem,md5)Default disabledDescription 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: CN field of the certificatedn: DN field of the certificatecrt:DERorPEMcertificatepem: ConvertDERcertificate content toPEMformat and use as Client IDmd5: MD5 value of theDERorPEMcertificate
client_attrs_init
Type Array(Struct(client_attrs_init))Default []Description Specify how to initialize client attributes. Each client attribute can be initialized as
client_attrs.{NAME}, where{NAME}is the name of the attribute specified in the config fieldset_as_attr. The initialized client attribute will be stored in theclient_attrsproperty with the specified name, and can be used as a placeholder in a template for authentication and authorization. For example, use${client_attrs.alias}to render an HTTP POST body whenset_as_attr = alias, or render listener configmoutpoint = devices/${client_attrs.alias}/to initialize a per-client topic namespace.expression
Type StringDescription A one line expression to evaluate a set of predefined string functions (like in the rule engine SQL statements). The expression can be a function call with nested calls as its arguments, or direct variable reference. So far, it does not provide user-defined variable binding (like
var a=1) or user-defined functions. As an example, to extract the prefix of client ID delimited by a dot:nth(1, tokens(clientid, '.')).The variables pre-bound variables are:
cn: Client's TLS certificate common name.dn: Client's TLS certificate distinguished name (the subject).clientid: MQTT Client ID.username: MQTT Client's username.user_property.{NAME}: User properties in the CONNECT packet.
You can read more about variform expressions in EMQX docs.
session_expiry_interval
Type DurationDefault "2h"Description Specifies how long the session will expire after the connection is disconnected, only for non-MQTT 5.0 connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.message_expiry_interval
Type OneOf(Duration,String("infinity"))Default infinityDescription The expiry interval of MQTT messages. For MQTT 5.0 clients, this configuration will only take effect when the Message-Expiry-Interval property is not set in the message; otherwise, the value of the Message-Expiry-Interval property will be used. For MQTT versions older than 5.0, this configuration will always take effect. Please note that setting message_expiry_interval greater than session_expiry_interval is meaningless, as all messages will be cleared when the session expires.
max_awaiting_rel
Type OneOf(Integer(0..+inf),String("infinity"))Default 100Description 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.mqueue_priorities
Type OneOf(String("disabled"),Map)Default disabledDescription 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}await_rel_timeout
Type DurationDefault "300s"Description For client to broker QoS 2 message, the time limit for the broker to wait before the
PUBRELmessage is received. The wait is aborted after timed out, meaning the packet ID is freed for newPUBLISHrequests. Receiving a stalePUBRELcauses a warning level log. Note, the message is delivered to subscribers before entering the wait for PUBREL.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
authentication
Type Array(OneOf(Struct(builtin_db),Struct(mysql),Struct(postgresql),Struct(mongo_single),Struct(mongo_rs),Struct(mongo_sharded),Struct(redis_single),Struct(redis_cluster),Struct(redis_sentinel),Struct(http_get),Struct(http_post),Struct(jwt_hmac),Struct(jwt_public_key),Struct(jwt_jwks),Struct(scram),Struct(ldap),Struct(ldap_deprecated)))Default []Description Default authentication configs for all MQTT listeners.
For per-listener overrides see
authenticationin listener configsThis 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.
query_timeout
Type DurationDefault "5s"Description Timeout for the SQL query.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
disable_prepared_statements
Type BooleanDefault falseDescription Disables the usage of prepared statements in the connections. Some endpoints, like PGBouncer or Supabase in Transaction mode, do not support session features such as prepared statements. For such connections, this option should be enabled.
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
filter
Type MapDefault {}Description Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:
${username}: Will be replaced at runtime withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused by the client when connecting
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.topology
Type Struct(topology)overflow_ttl
Type DurationDescription Period of time before workers that exceed the configured pool size ("overflow") to be terminated.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.overflow_check_period
Type DurationDescription Period for checking if there are more workers than configured ("overflow").
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.local_threshold_ms
Type DurationDescription The size of the latency window for selecting among multiple suitable MongoDB instances.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.connect_timeout_ms
Type DurationDescription The duration to attempt a connection before timing out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_timeout_ms
Type DurationDescription The duration to attempt to send or to receive on a socket before the attempt times out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_selection_timeout_ms
Type DurationDescription Specifies how long to block for server selection before throwing an exception.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.wait_queue_timeout_ms
Type DurationDescription The maximum duration that a worker can wait for a connection to become available.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.heartbeat_frequency_ms
Type DurationDefault "200s"Description Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one. If the number of connections is increased (which will happen, for example, if you increase the pool size), you may need to increase this period as well to avoid creating too many log entries in the MongoDB log file.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.min_heartbeat_frequency_ms
Type DurationDescription Controls the minimum amount of time to wait between heartbeats.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
filter
Type MapDefault {}Description Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:
${username}: Will be replaced at runtime withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused by the client when connecting
servers
Type StringDescription 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.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.topology
Type Struct(topology)overflow_ttl
Type DurationDescription Period of time before workers that exceed the configured pool size ("overflow") to be terminated.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.overflow_check_period
Type DurationDescription Period for checking if there are more workers than configured ("overflow").
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.local_threshold_ms
Type DurationDescription The size of the latency window for selecting among multiple suitable MongoDB instances.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.connect_timeout_ms
Type DurationDescription The duration to attempt a connection before timing out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_timeout_ms
Type DurationDescription The duration to attempt to send or to receive on a socket before the attempt times out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_selection_timeout_ms
Type DurationDescription Specifies how long to block for server selection before throwing an exception.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.wait_queue_timeout_ms
Type DurationDescription The maximum duration that a worker can wait for a connection to become available.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.heartbeat_frequency_ms
Type DurationDefault "200s"Description Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one. If the number of connections is increased (which will happen, for example, if you increase the pool size), you may need to increase this period as well to avoid creating too many log entries in the MongoDB log file.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.min_heartbeat_frequency_ms
Type DurationDescription Controls the minimum amount of time to wait between heartbeats.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
filter
Type MapDefault {}Description Conditional expression that defines the filter condition in the query. Filter supports the following placeholders:
${username}: Will be replaced at runtime withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused by the client when connecting
servers
Type StringDescription 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.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.topology
Type Struct(topology)overflow_ttl
Type DurationDescription Period of time before workers that exceed the configured pool size ("overflow") to be terminated.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.overflow_check_period
Type DurationDescription Period for checking if there are more workers than configured ("overflow").
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.local_threshold_ms
Type DurationDescription The size of the latency window for selecting among multiple suitable MongoDB instances.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.connect_timeout_ms
Type DurationDescription The duration to attempt a connection before timing out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_timeout_ms
Type DurationDescription The duration to attempt to send or to receive on a socket before the attempt times out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_selection_timeout_ms
Type DurationDescription Specifies how long to block for server selection before throwing an exception.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.wait_queue_timeout_ms
Type DurationDescription The maximum duration that a worker can wait for a connection to become available.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.heartbeat_frequency_ms
Type DurationDefault "200s"Description Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one. If the number of connections is increased (which will happen, for example, if you increase the pool size), you may need to increase this period as well to avoid creating too many log entries in the MongoDB log file.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.min_heartbeat_frequency_ms
Type DurationDescription Controls the minimum amount of time to wait between heartbeats.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
servers
Type StringDescription 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 Redis default port 6379 is used if[:Port]is not specified.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
servers
Type StringDescription 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 Redis default port 6379 is used if[:Port]is not specified.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
request_timeout
Type DurationDefault "5s"Description HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request
Type Struct(request)Description Configure HTTP request parameters.
request_timeout
Type DurationDescription HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the HTTP server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.retry_interval
Type DurationDescription Deprecated since 5.0.4.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
request_timeout
Type DurationDefault "5s"Description HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request
Type Struct(request)Description Configure HTTP request parameters.
request_timeout
Type DurationDescription HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the HTTP server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.retry_interval
Type DurationDescription Deprecated since 5.0.4.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
acl_claim_name
Type StringDefault aclDescription The JWT claim designated for accessing ACL (Access Control List) rules can be specified, such as using the
aclclaim. A typical decoded JWT with this claim might appear as:{"username": "user1", "acl": ...}.Supported ACL Rule Formats:
-
Object Format: Utilizes action types pub (publish), sub (subscribe), or all (both publish and subscribe). The value is a list of topic filters. Example:
{"pub": ["topic1"], "sub": [], "all": ["${username}/#"]}. This example signifies that the token owner can publish to topic1 and perform both publish and subscribe actions on topics starting with their username. Note: In this format, if no topic matches, the action is denied, and the authorization process terminates. -
Array Format (resembles File-Based ACL Rules): Example:
[{"permission": "allow", "action": "all", "topic": "${username}/#"}]. Additionally, thepuborpublishaction rules can be extended withqosandretainfield, andsuborsubscribeaction rules can be extended with aqosfield. Note: Here, if no rule matches, the action is not immediately denied. The process continues to other configured authorization sources, and ultimately falls back to the default permission in configauthorization.no_match.
The ACL claim utilizes MQTT topic wildcard matching rules for publishing or subscribing. A special syntax for the 'subscribe' action allows the use of
eqfor an exact match. For instance,eq t/#permits or denies subscription tot/#, but not tot/1.-
verify_claims
Type MapDefault []Description 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 withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused 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 inverify_claims.
acl_claim_name
Type StringDefault aclDescription The JWT claim designated for accessing ACL (Access Control List) rules can be specified, such as using the
aclclaim. A typical decoded JWT with this claim might appear as:{"username": "user1", "acl": ...}.Supported ACL Rule Formats:
-
Object Format: Utilizes action types pub (publish), sub (subscribe), or all (both publish and subscribe). The value is a list of topic filters. Example:
{"pub": ["topic1"], "sub": [], "all": ["${username}/#"]}. This example signifies that the token owner can publish to topic1 and perform both publish and subscribe actions on topics starting with their username. Note: In this format, if no topic matches, the action is denied, and the authorization process terminates. -
Array Format (resembles File-Based ACL Rules): Example:
[{"permission": "allow", "action": "all", "topic": "${username}/#"}]. Additionally, thepuborpublishaction rules can be extended withqosandretainfield, andsuborsubscribeaction rules can be extended with aqosfield. Note: Here, if no rule matches, the action is not immediately denied. The process continues to other configured authorization sources, and ultimately falls back to the default permission in configauthorization.no_match.
The ACL claim utilizes MQTT topic wildcard matching rules for publishing or subscribing. A special syntax for the 'subscribe' action allows the use of
eqfor an exact match. For instance,eq t/#permits or denies subscription tot/#, but not tot/1.-
verify_claims
Type MapDefault []Description 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 withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused 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 inverify_claims.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL options.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
acl_claim_name
Type StringDefault aclDescription The JWT claim designated for accessing ACL (Access Control List) rules can be specified, such as using the
aclclaim. A typical decoded JWT with this claim might appear as:{"username": "user1", "acl": ...}.Supported ACL Rule Formats:
-
Object Format: Utilizes action types pub (publish), sub (subscribe), or all (both publish and subscribe). The value is a list of topic filters. Example:
{"pub": ["topic1"], "sub": [], "all": ["${username}/#"]}. This example signifies that the token owner can publish to topic1 and perform both publish and subscribe actions on topics starting with their username. Note: In this format, if no topic matches, the action is denied, and the authorization process terminates. -
Array Format (resembles File-Based ACL Rules): Example:
[{"permission": "allow", "action": "all", "topic": "${username}/#"}]. Additionally, thepuborpublishaction rules can be extended withqosandretainfield, andsuborsubscribeaction rules can be extended with aqosfield. Note: Here, if no rule matches, the action is not immediately denied. The process continues to other configured authorization sources, and ultimately falls back to the default permission in configauthorization.no_match.
The ACL claim utilizes MQTT topic wildcard matching rules for publishing or subscribing. A special syntax for the 'subscribe' action allows the use of
eqfor an exact match. For instance,eq t/#permits or denies subscription tot/#, but not tot/1.-
verify_claims
Type MapDefault []Description 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 withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused 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 inverify_claims.
query_timeout
Type DurationDefault "5s"Description Timeout for the LDAP query.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.request_timeout
Type DurationDefault "10s"Description Sets the maximum time in milliseconds that is used for each individual request.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl
Type Struct(ssl)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
query_timeout
Type DurationDefault "5s"Description Timeout for the LDAP query.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.request_timeout
Type DurationDefault "10s"Description Sets the maximum time in milliseconds that is used for each individual request.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl
Type Struct(ssl)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
authorization
Type Struct(authorization)Description 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 databasesno_match
Type Enum(allow,deny)Default allowDescription 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.
cache
Type Struct(authz_cache)ttl
Type DurationDefault "1m"Description Time to live for the cached data.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
sources
Type Array(OneOf(Struct(file),Struct(builtin_db),Struct(http_get),Struct(http_post),Struct(redis_single),Struct(redis_sentinel),Struct(redis_cluster),Struct(mysql),Struct(postgresql),Struct(mongo_single),Struct(mongo_rs),Struct(mongo_sharded),Struct(ldap)))Default [{enable = true, path = "${EMQX_ETC_DIR}/acl.conf", type = file}]Description 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.
path
Type StringDescription 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
authzsubdirectory inside EMQX'sdata_dir, and the old file will not be used anymore.
connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the HTTP server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.retry_interval
Type DurationDescription Deprecated since 5.0.4.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request
Type Struct(request)Description Configure HTTP request parameters.
request_timeout
Type DurationDescription HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the HTTP server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.retry_interval
Type DurationDescription Deprecated since 5.0.4.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request
Type Struct(request)Description Configure HTTP request parameters.
request_timeout
Type DurationDescription HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
servers
Type StringDescription 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 Redis default port 6379 is used if[:Port]is not specified.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
servers
Type StringDescription 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 Redis default port 6379 is used if[:Port]is not specified.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
disable_prepared_statements
Type BooleanDefault falseDescription Disables the usage of prepared statements in the connections. Some endpoints, like PGBouncer or Supabase in Transaction mode, do not support session features such as prepared statements. For such connections, this option should be enabled.
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
filter
Type MapDefault {}Description Conditional expression that defines the filter condition in the query. Filter supports the following placeholders
${username}: Will be replaced at runtime withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused by the client when connecting
password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.topology
Type Struct(topology)overflow_ttl
Type DurationDescription Period of time before workers that exceed the configured pool size ("overflow") to be terminated.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.overflow_check_period
Type DurationDescription Period for checking if there are more workers than configured ("overflow").
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.local_threshold_ms
Type DurationDescription The size of the latency window for selecting among multiple suitable MongoDB instances.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.connect_timeout_ms
Type DurationDescription The duration to attempt a connection before timing out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_timeout_ms
Type DurationDescription The duration to attempt to send or to receive on a socket before the attempt times out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_selection_timeout_ms
Type DurationDescription Specifies how long to block for server selection before throwing an exception.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.wait_queue_timeout_ms
Type DurationDescription The maximum duration that a worker can wait for a connection to become available.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.heartbeat_frequency_ms
Type DurationDefault "200s"Description Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one. If the number of connections is increased (which will happen, for example, if you increase the pool size), you may need to increase this period as well to avoid creating too many log entries in the MongoDB log file.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.min_heartbeat_frequency_ms
Type DurationDescription Controls the minimum amount of time to wait between heartbeats.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
filter
Type MapDefault {}Description Conditional expression that defines the filter condition in the query. Filter supports the following placeholders
${username}: Will be replaced at runtime withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused by the client when connecting
servers
Type StringDescription 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.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.topology
Type Struct(topology)overflow_ttl
Type DurationDescription Period of time before workers that exceed the configured pool size ("overflow") to be terminated.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.overflow_check_period
Type DurationDescription Period for checking if there are more workers than configured ("overflow").
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.local_threshold_ms
Type DurationDescription The size of the latency window for selecting among multiple suitable MongoDB instances.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.connect_timeout_ms
Type DurationDescription The duration to attempt a connection before timing out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_timeout_ms
Type DurationDescription The duration to attempt to send or to receive on a socket before the attempt times out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_selection_timeout_ms
Type DurationDescription Specifies how long to block for server selection before throwing an exception.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.wait_queue_timeout_ms
Type DurationDescription The maximum duration that a worker can wait for a connection to become available.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.heartbeat_frequency_ms
Type DurationDefault "200s"Description Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one. If the number of connections is increased (which will happen, for example, if you increase the pool size), you may need to increase this period as well to avoid creating too many log entries in the MongoDB log file.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.min_heartbeat_frequency_ms
Type DurationDescription Controls the minimum amount of time to wait between heartbeats.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
filter
Type MapDefault {}Description Conditional expression that defines the filter condition in the query. Filter supports the following placeholders
${username}: Will be replaced at runtime withUsernameused by the client when connecting${clientid}: Will be replaced at runtime withClient IDused by the client when connecting
servers
Type StringDescription 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.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.topology
Type Struct(topology)overflow_ttl
Type DurationDescription Period of time before workers that exceed the configured pool size ("overflow") to be terminated.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.overflow_check_period
Type DurationDescription Period for checking if there are more workers than configured ("overflow").
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.local_threshold_ms
Type DurationDescription The size of the latency window for selecting among multiple suitable MongoDB instances.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.connect_timeout_ms
Type DurationDescription The duration to attempt a connection before timing out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_timeout_ms
Type DurationDescription The duration to attempt to send or to receive on a socket before the attempt times out.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_selection_timeout_ms
Type DurationDescription Specifies how long to block for server selection before throwing an exception.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.wait_queue_timeout_ms
Type DurationDescription The maximum duration that a worker can wait for a connection to become available.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.heartbeat_frequency_ms
Type DurationDefault "200s"Description Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one. If the number of connections is increased (which will happen, for example, if you increase the pool size), you may need to increase this period as well to avoid creating too many log entries in the MongoDB log file.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.min_heartbeat_frequency_ms
Type DurationDescription Controls the minimum amount of time to wait between heartbeats.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
query_timeout
Type DurationDefault "5s"Description Timeout for the LDAP query.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.password
Type SecretDescription The password associated with the bridge, used for authentication with the external database.
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.request_timeout
Type DurationDefault "10s"Description Sets the maximum time in milliseconds that is used for each individual request.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl
Type Struct(ssl)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
node
Type Struct(node)data_dir
Type StringDescription 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.
role
Aliases db_role Type Enum(core,replicant)Default coreDescription Select a node role.
corenodes provide durability of the data, and take care of writes. It is recommended to place core nodes in different racks or different availability zones.
replicantnodes 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 thebackendis set torlog.
cluster
Type Struct(cluster)discovery_strategy
Type Enum(manual,static,dns,etcd,k8s)Default manualDescription Service discovery method for the cluster nodes. Possible values are:
- manual: Use
emqx ctl clustercommand to manage cluster. - static: Configure static nodes list by setting
seedsin config file. - dns: Use DNS A record to discover peer nodes.
- etcd: Use etcd to discover peer nodes.
- k8s: Use Kubernetes API to discover peer pods.
- manual: Use
autoclean
Type DurationDefault "24h"Description Remove disconnected nodes from the cluster after this interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.etcd
Type Struct(cluster_etcd)node_ttl
Type DurationDefault "1m"Description Expiration time of the etcd key associated with the node. It is refreshed automatically, as long as the node is alive.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl_options
Aliases ssl Type Struct(ssl_client_opts)Description Options for the TLS connection to the etcd cluster.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
log
Type Struct(log)Description EMQX provides support for two primary log handlers:
fileandconsole, with an additionalaudithandler specifically designed to always direct logs to files. The system's default log handling behavior can be configured via the environment variableEMQX_DEFAULT_LOG_HANDLER, which accepts the following settings:file: Directs log output exclusively to files.console: Channels log output solely to the console.
It's noteworthy that
EMQX_DEFAULT_LOG_HANDLERis set tofilewhen EMQX is initiated via systemd'semqx.servicefile. In scenarios outside systemd initiation,consoleserves as the default log handler.console
Aliases console_handler Type Struct(console_handler)time_offset
Type StringDefault systemDescription The time offset to be used when formatting the timestamp. Can be one of:
system: the time offset used by the local systemutc: the UTC time offset+-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to:system. This config has no effect for when formatter isjsonas the timestamp in JSON is milliseconds since epoch.
file
Aliases file_handlers Type OneOf(Struct(log_file_handler),Map($handler_name->Struct(log_file_handler)))Default {level = warning}Description File-based log handlers.
time_offset
Type StringDefault systemDescription The time offset to be used when formatting the timestamp. Can be one of:
system: the time offset used by the local systemutc: the UTC time offset+-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to:system. This config has no effect for when formatter isjsonas the timestamp in JSON is milliseconds since epoch.
time_offset
Type StringDefault systemDescription The time offset to be used when formatting the timestamp. Can be one of:
system: the time offset used by the local systemutc: the UTC time offset+-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to:system. This config has no effect for when formatter isjsonas the timestamp in JSON is milliseconds since epoch.
throttling
Type Struct(log_throttling)time_window
Type Duration(s)Default "1m"Description This configuration setting controls the logging behavior for throttled messages, including, but not limited to messages like 'authorization_permission_denied'. Within each defined time window, only one instance of a throttled message will be logged to prevent log flooding. At the conclusion of each time window, a summary log will be generated, detailing the occurrence of any throttled messages during that period. It's important to note that the shortest effective time window for this setting is 1 second (
1s). Should a value lower than1sbe specified, it will automatically be adjusted to1s.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
rpc
Type Struct(rpc)connect_timeout
Type DurationDefault "5s"Description Timeout for establishing an RPC connection.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.send_timeout
Type DurationDefault "5s"Description Timeout for sending the RPC request.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.authentication_timeout
Type DurationDefault "5s"Description Timeout for the remote node authentication.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.call_receive_timeout
Type DurationDefault "15s"Description Timeout for the reply to a synchronous RPC.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_keepalive_idle
Type Duration(s)Default "15m"Description How long the connections between the brokers should remain open after the last message is sent.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.socket_keepalive_interval
Type Duration(s)Default "75s"Description The interval between keepalive messages.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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"
force_shutdown
Type Struct(force_shutdown)max_mailbox_size
Aliases max_message_queue_len Type Integer(0..inf)Default 1000Description In EMQX, each online client corresponds to an individual Erlang process. The configuration value establishes a mailbox size limit for these processes. If the mailbox size surpasses this limit, the client will be automatically terminated.
durable_storage
Type Struct(durable_storage)Description Configuration related to the EMQX durable storages.
EMQX uses durable storages to offload various data, such as MQTT messages, to disc.
messages
Type OneOf(Struct(builtin))Default {backend = builtin}Description Configuration related to the durable storage of MQTT messages.
n_shards
Type Integer(1..+inf)Default 12Description The built-in durable storage partitions data into shards. This configuration parameter defines the number of shards. Please note that it takes effect only during the initialization of the durable storage database. Changing this configuration parameter after the database has been already created won't take any effect.
layout
Type OneOf(Struct(layout_builtin_wildcard_optimized),Struct(layout_builtin_reference))Default {type = wildcard_optimized}Description Storage layout is a method of arranging messages from various topics and clients on disc.
Depending on the type of workload and the topic structure, different types of strategies for storing the data can be employed to maximize efficiency of reading messages from the durable storage.
sysmon
Type Struct(sysmon)vm
Type Struct(sysmon_vm)process_check_interval
Type DurationDefault "30s"Description The time interval for the periodic process limit check.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
os
Type Struct(sysmon_os)cpu_check_interval
Type DurationDefault "60s"Description The time interval for the periodic CPU check. Disabled on Windows platform.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
alarm
Type Struct(alarm)actions
Type Array(Enum(log,publish))Default [log, publish]Description The actions triggered when the alarm is activated.
Currently, the following actions are supported:logandpublish.logis to write the alarm to log (console or file).publishis to publish the alarm as an MQTT message to the system topics:$SYS/brokers/emqx@xx.xx.xx.x/alarms/activateand$SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivatevalidity_period
Type DurationDefault "24h"Description Retention time of deactivated alarms. Alarms are not deleted immediately when deactivated, but after the retention time.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
flapping_detect
Type Struct(flapping_detect)window_time
Type DurationDefault "1m"Description The time window for flapping detection.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ban_time
Type DurationDefault "5m"Description How long the flapping clientid will be banned.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
connectors
Type Struct(connectors)http
Type Map($name->Struct(config_connector))Description HTTP Connector Config
url
Type StringDescription The URL of the HTTP action.
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, buthttp://${host}:9901/messageorhttp://localhost:${port}/messageis not allowed.connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the HTTP server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.retry_interval
Type DurationDescription Deprecated since 5.0.4.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
resource_opts
Type Struct(connector_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.start_timeout
Type DurationDefault "5s"Description Time interval to wait for an auto-started resource to become healthy before responding resource creation requests.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
mqtt
Type Map($name->Struct(config_connector))Description MQTT Connector Config
resource_opts
Type Struct(resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.start_timeout
Type DurationDefault "5s"Description Time interval to wait for an auto-started resource to become healthy before responding resource creation requests.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
bridge_mode
Type BooleanDefault falseDescription 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. If bridge_mode is set to true, the bridge will indicate to the remote broker that it is a bridge not an ordinary client. This means that loop detection will be more effective and that retained messages will be propagated correctly.
password
Type SecretDescription The password of the MQTT protocol
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.retry_interval
Type StringDefault "15s"Description 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:
-msfor milliseconds,sfor seconds,mfor minutes,hfor hours;
or combination of whereof:1h5m0s
ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
elasticsearch
Type Map($name->Struct(config))Description ElasticSearch Connector Config
connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the HTTP server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl
Type Struct(ssl_client_opts)Default {enable = false}Description SSL connection settings.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
resource_opts
Type Struct(connector_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.start_timeout
Type DurationDefault "5s"Description Time interval to wait for an auto-started resource to become healthy before responding resource creation requests.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
authentication
Type OneOf(Struct(auth_basic))Description Authentication configuration
password
Type SecretDescription The password as configured at the ElasticSearch REST interface
A string holding some sensitive information, such as a password. When secret starts withfile://, the rest of the string is interpreted as a path to a file containing the secret itself: whole content of the file except any trailing whitespace characters is considered a secret value. Note: when clustered, all EMQX nodes should have the same file present before usingfile://secrets.
actions
Type Struct(actions)http
Aliases webhook Type Map($name->Struct(http_action))Description HTTP Action Config
parameters
Type Struct(parameters_opts)Description The parameters for HTTP action.
path
Type StringDescription The URL path for this Action.
This path will be appended to the Connector'surlconfiguration to form the full URL address. Template with variables is allowed in this option. For example,/room/{$room_no}
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.body
Type StringDescription The body of the HTTP request.
If not provided, the body will be a JSON object of all the available fields.
There, 'all the available fields' means the context of a MQTT message when this webhook is triggered by receiving a MQTT message (thelocal_topicis set), or the context of the event when this webhook is triggered by a rule (i.e. this webhook is used as an action of a rule).
Template with variables is allowed.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.request_timeout
Type DurationDescription Deprecated since v5.0.26.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
resource_opts
Type Struct(action_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request_ttl
Aliases request_timeout Type OneOf(Duration,String("infinity"))Default "45s"Description Starting from the moment when the request enters the buffer, if the request remains in the buffer for the specified time or is sent but does not receive a response or acknowledgement in time, the request is considered expired.
mqtt
Type Map($name->Struct(mqtt_publisher_action))Description MQTT Publisher Action Config
resource_opts
Type Struct(action_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request_ttl
Aliases request_timeout Type OneOf(Duration,String("infinity"))Default "45s"Description Starting from the moment when the request enters the buffer, if the request remains in the buffer for the specified time or is sent but does not receive a response or acknowledgement in time, the request is considered expired.
elasticsearch
Type Map($action_name->Struct(action_config))Description Elasticsearch Bridge
resource_opts
Type Struct(action_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.request_ttl
Aliases request_timeout Type OneOf(Duration,String("infinity"))Default "45s"Description Starting from the moment when the request enters the buffer, if the request remains in the buffer for the specified time or is sent but does not receive a response or acknowledgement in time, the request is considered expired.
sources
Type Struct(sources)mqtt
Type Map($name->Struct(mqtt_subscriber_source))Description MQTT Subscriber Source Config
resource_opts
Type Struct(source_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "15s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
retainer
Type Struct(retainer)msg_expiry_interval
Type DurationDefault "0s"Description Message retention time. This config is only applicable for messages without the Message Expiry Interval message property. 0 means message will never expire.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.msg_clear_interval
Type DurationDefault "0s"Description Interval for EMQX to scan expired messages and delete them. Never scan if the value is 0.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.backend
Type Struct(mnesia_config)Description Settings for the database storing the retained messages.
index_specs
Type Array(Integer)Default [[1, 2, 3], [1, 3], [2, 3], [3]]Description 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.
plugins
Type Struct(plugins)install_dir
Type StringDefault pluginsDescription 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 exceptemqx(or any user which runs EMQX).check_interval
Type DurationDescription Deprecated since 5.0.24.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
dashboard
Type Struct(dashboard)listeners
Type Struct(listeners)Description 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.
http
Type Struct(http)Description TCP listeners
send_timeout
Type DurationDefault "10s"Description Send timeout for the socket.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
https
Type Struct(https)Description SSL listeners
ssl_options
Type Struct(ssl_options)Description SSL/TLS options for the dashboard listener.
cacertfile
Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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
Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.client_renegotiation
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout
Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
send_timeout
Type DurationDefault "10s"Description Send timeout for the socket.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
token_expired_time
Type DurationDefault "60m"Description JWT token expiration time. Default is 60 minutes
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
gateway
Type Struct(gateway)coap
Type Struct(coap)heartbeat
Type DurationDefault "30s"Description 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
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.notify_type
Type Enum(non,con,qos)Default qosDescription 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
- non: Non-confirmable;
subscribe_qos
Type Enum(qos0,qos1,qos2,coap)Default coapDescription 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
qosoption. 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
- qos0: If the subscribe request is non-confirmable
- qos0, qos1, qos2: Fixed default QoS level
publish_qos
Type Enum(qos0,qos1,qos2,coap)Default coapDescription 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
qosoption. 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
- qos0: If the publish request is non-confirmable
- qos0, qos1, qos2: Fixed default QoS level
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
listeners
Type Struct(udp_listeners)udp
Type Map($name->Struct(udp_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls
Type Map($name->Struct(dtls_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls_options
Type Struct(dtls_opts)Description DTLS socket options
cacertfile Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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 Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth Type Integer(0..+inf)Default 10Description 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.ciphers Type Array(String)Default []Description 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 theversions, 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 fromversions.
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 Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert Type BooleanDefault falseDescription 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).
client_renegotiation Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp Type Struct(ocsp)refresh_interval Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
idle_timeout
Type DurationDefault "30s"Description The idle time of the client connection process. It has two purposes:
- A newly created client process that does not receive any client requests after that time will be closed directly.
- A running client process that does not receive any client requests after this time will go into hibernation to save resources.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
exproto
Type Struct(exproto)server
Type Struct(exproto_grpc_server)Description Configurations for starting the
ConnectionAdapterservicessl_options
Type Struct(ssl_server_opts)Description SSL configuration for the gRPC server.
cacertfile
Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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
Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert
Type BooleanDefault falseDescription 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).
client_renegotiation
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout
Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
handler
Type Struct(exproto_grpc_handler)Description Configurations for request to
ConnectionHandlerserviceservice_name
Type OneOf(String("ConnectionHandler"),String("ConnectionUnaryHandler"))Default ConnectionUnaryHandlerDescription The service name to handle the connection events. In the initial version, we expected to use streams to improve the efficiency of requests in
ConnectionHandler. But unfortunately, events between different streams are out of order. It causes theOnSocketCreatedevent to may arrive later thanOnReceivedBytes. So we added theConnectionUnaryHandlerservice since v5.0.25 and forced the use of Unary in it to avoid ordering problems.ssl_options
Type Struct(ssl_client_opts)Description SSL configuration for the gRPC client.
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
listeners
Type Struct(tcp_udp_listeners)tcp
Type Map($name->Struct(tcp_listener))Description A map from listener names to listener settings.
tcp_options
Type Struct(tcp_opts)Description Setting the TCP socket options.
send_timeout Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
ssl
Type Map($name->Struct(ssl_listener))Description A map from listener names to listener settings.
tcp_options
Type Struct(tcp_opts)Description Setting the TCP socket options.
send_timeout Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
ssl_options
Type Struct(listener_ssl_opts)Description SSL Socket options.
cacertfile Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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 Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth Type Integer(0..+inf)Default 10Description 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.ciphers Type Array(String)Default []Description 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 theversions, 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 fromversions.
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 Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert Type BooleanDefault falseDescription 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).
client_renegotiation Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp Type Struct(ocsp)refresh_interval Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
udp
Type Map($name->Struct(udp_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls
Type Map($name->Struct(dtls_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls_options
Type Struct(dtls_opts)Description DTLS socket options
cacertfile Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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 Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth Type Integer(0..+inf)Default 10Description 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.ciphers Type Array(String)Default []Description 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 theversions, 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 fromversions.
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 Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert Type BooleanDefault falseDescription 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).
client_renegotiation Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp Type Struct(ocsp)refresh_interval Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
idle_timeout
Type DurationDefault "30s"Description The idle time of the client connection process. It has two purposes:
- A newly created client process that does not receive any client requests after that time will be closed directly.
- A running client process that does not receive any client requests after this time will go into hibernation to save resources.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
lwm2m
Type Struct(lwm2m)lifetime_min
Type DurationDefault "15s"Description Minimum value of lifetime allowed to be set by the LwM2M client.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.lifetime_max
Type DurationDefault "86400s"Description Maximum value of lifetime allowed to be set by the LwM2M client.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.qmode_time_window
Type Duration(s)Default "22s"Description 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.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.update_msg_publish_condition
Type Enum(always,contains_object_list)Default contains_object_listDescription 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
- always: send update events as long as the UPDATE request is received.
translators
Type Struct(lwm2m_translators)Description Topic configuration for LwM2M's gateway publishing and subscription.
mountpoint
Type StringDefault "lwm2m/${endpoint_name}/"Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
listeners
Type Struct(udp_listeners)udp
Type Map($name->Struct(udp_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls
Type Map($name->Struct(dtls_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls_options
Type Struct(dtls_opts)Description DTLS socket options
cacertfile Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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 Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth Type Integer(0..+inf)Default 10Description 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.ciphers Type Array(String)Default []Description 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 theversions, 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 fromversions.
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 Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert Type BooleanDefault falseDescription 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).
client_renegotiation Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp Type Struct(ocsp)refresh_interval Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
idle_timeout
Type DurationDefault "30s"Description The idle time of the client connection process. It has two purposes:
- A newly created client process that does not receive any client requests after that time will be closed directly.
- A running client process that does not receive any client requests after this time will go into hibernation to save resources.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
mqttsn
Type Struct(mqttsn)enable_qos3
Type BooleanDefault trueDescription 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
mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
listeners
Type Struct(udp_listeners)udp
Type Map($name->Struct(udp_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls
Type Map($name->Struct(dtls_listener))Description A map from listener names to listener settings.
mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
dtls_options
Type Struct(dtls_opts)Description DTLS socket options
cacertfile Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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 Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth Type Integer(0..+inf)Default 10Description 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.ciphers Type Array(String)Default []Description 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 theversions, 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 fromversions.
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 Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert Type BooleanDefault falseDescription 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).
client_renegotiation Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp Type Struct(ocsp)refresh_interval Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
idle_timeout
Type DurationDefault "30s"Description The idle time of the client connection process. It has two purposes:
- A newly created client process that does not receive any client requests after that time will be closed directly.
- A running client process that does not receive any client requests after this time will go into hibernation to save resources.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
stomp
Type Struct(stomp)mountpoint
Type StringDefault ""Description 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
listeners
Type Struct(tcp_listeners)tcp
Type Map($name->Struct(tcp_listener))Description A map from listener names to listener settings.
tcp_options
Type Struct(tcp_opts)Description Setting the TCP socket options.
send_timeout Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
ssl
Type Map($name->Struct(ssl_listener))Description A map from listener names to listener settings.
tcp_options
Type Struct(tcp_opts)Description Setting the TCP socket options.
send_timeout Type DurationDefault "15s"Description The TCP send timeout for the connections.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are interpreted as powers of 1024, and the unit part is case-insensitive.keepalive Type StringDefault noneDescription Enable TCP keepalive for MQTT connections over TCP or SSL. The value is three comma separated numbers in the format of 'Idle,Interval,Probes'
- Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
- Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
- Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9). For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection. Default: 'none'
proxy_protocol_timeout
Type DurationDefault "3s"Description Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.mountpoint
Type StringDescription 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
twithlisteners.tcp.\<name>.mountpointset tosome_tenant, then the client actually subscribes to the topicsome_tenant/t. Similarly, if another client B (connected to the same listener as the client A) sends a message to topict, the message is routed to all the clients subscribedsome_tenant/t, so client A will receive the message, with topic namet. Set to""to disable the feature. Supported placeholders in mountpoint string:${clientid}: clientid${username}: username${endpoint_name}: endpoint name
ssl_options
Type Struct(listener_ssl_opts)Description SSL Socket options.
cacertfile Type StringDefault "${EMQX_ETC_DIR}/certs/cacert.pem"Description 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 Type StringDefault "${EMQX_ETC_DIR}/certs/cert.pem"Description 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.depth Type Integer(0..+inf)Default 10Description 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.ciphers Type Array(String)Default []Description 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 theversions, 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 fromversions.
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 Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.fail_if_no_peer_cert Type BooleanDefault falseDescription 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).
client_renegotiation Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3handshake_timeout Type DurationDefault "15s"Description Maximum time duration allowed for the handshake to complete
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ocsp Type Struct(ocsp)refresh_interval Type DurationDefault "5m"Description The period to refresh the OCSP response for the server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.refresh_http_timeout Type DurationDefault "15s"Description The timeout for the HTTP request when checking OCSP responses.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
idle_timeout
Type DurationDefault "30s"Description The idle time of the client connection process. It has two purposes:
- A newly created client process that does not receive any client requests after that time will be closed directly.
- A running client process that does not receive any client requests after this time will go into hibernation to save resources.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
prometheus
Type OneOf(Struct(recommend_setting),Struct(legacy_deprecated_setting))Default {}push_gateway
Type Struct(push_gateway)Description Push Gateway is optional, should not be configured if prometheus is to scrape EMQX.
interval
Type DurationDefault "15s"Description Data reporting interval
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.job_name
Type StringDefault "${name}/instance/${name}~${host}"Description Job Name that is pushed to the Push Gateway. Available variables:
- ${name}: Name of EMQX node.
- ${host}: Host name of EMQX node.
For example, when the EMQX node name isemqx@127.0.0.1then thenamevariable takes valueemqxand thehostvariable takes value127.0.0.1. Default value is:${name}/instance/${name}~${host}
- ${name}: Name of EMQX node.
interval
Type DurationDefault "15s"Description Deprecated since 5.4.0, use
prometheus.push_gateway.intervalinstead
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
exhook
Type Struct(exhook)servers
Type Array(Struct(server))Default []Description List of exhook servers
request_timeout
Type DurationDefault "5s"Description The timeout of request gRPC server
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.ssl
Type Struct(ssl_conf)cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
slow_subs
Type Struct(slow_subs)threshold
Type DurationDefault "500ms"Description The latency threshold for statistics
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.expire_interval
Type DurationDefault "300s"Description The eviction time of the record, which in the statistics record table
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
opentelemetry
Type Struct(opentelemetry)metrics
Type Struct(otel_metrics)Description Open Telemetry Metrics configuration.
interval
Aliases scheduled_delay Type DurationDefault "10s"Description The delay interval between two consecutive exports of Open Telemetry signals.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
logs
Type Struct(otel_logs)Description Open Telemetry Logs configuration. If enabled, EMQX installs a log handler that formats events according to Open Telemetry log data model and exports them to the configured Open Telemetry collector or backend.
scheduled_delay
Type DurationDefault "1s"Description The delay interval between two consecutive exports of Open Telemetry signals.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
traces
Type Struct(otel_traces)Description Open Telemetry Traces configuration.
scheduled_delay
Type DurationDefault "5s"Description The delay interval between two consecutive exports of Open Telemetry signals.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.
exporter
Type Struct(otel_exporter)Description Open Telemetry Exporter
ssl_options
Type Struct(ssl_client_opts)Default {enable = false}Description SSL configuration for the Open Telemetry exporter
cacertfile
Type StringDescription 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
Type StringDescription 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.depth
Type Integer(0..+inf)Default 10Description 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.ciphers
Type Array(String)Default []Description 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 theversions, 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 fromversions.
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
Type BooleanDefault trueDescription 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.
Has no effect when TLS version is configured (or negotiated) to 1.3hibernate_after
Type DurationDefault "5s"Description Hibernate the SSL process after idling for amount of time reducing its memory footprint.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. When precision is specified, finer portions of the duration may be ignored: writing1200msforDuration(s)is equivalent to writing1s. The unit part is case-insensitive.server_name_indication
Type OneOf(String("disable"),String)Description 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 address 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.
api_key
Type Struct(api_key)bootstrap_file
Type StringDefault ""Description The bootstrap file provides API keys for EMQX. EMQX will load these keys on startup to authorize API requests. It contains colon-separated values in the format:
api_key:api_secret:role. Each line specifies an API key and its associated secret, and the role of this key. The 'role' part should be the pre-defined access scope group name, for example,administratororviewer. The 'role' is introduced in 5.4, to be backward compatible, if it is missing, the key is implicitly grantedadministratorrole.