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 StringDefault infinityDescription Used to limit the rate at which the current listener accepts connections.
Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.
For example:
1000/s: Only accepts 1000 connections per second.1000/10s: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Used to limit the number of messages a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
For example:
500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.
bytes_rate
Type StringDescription Used to limit the number of bytes a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
The unit of the bytes could be: B, KB, MB, GB.
For example:
500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.
access_rules
Type Array(String)Default ["allow all"]Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]proxy_protocol_timeout
Type DurationDefault "3s"Description If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.
EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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 StringDefault infinityDescription Used to limit the rate at which the current listener accepts connections.
Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.
For example:
1000/s: Only accepts 1000 connections per second.1000/10s: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Used to limit the number of messages a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
For example:
500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.
bytes_rate
Type StringDescription Used to limit the number of bytes a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
The unit of the bytes could be: B, KB, MB, GB.
For example:
500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.
access_rules
Type Array(String)Default ["allow all"]Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]proxy_protocol_timeout
Type DurationDefault "3s"Description If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.
EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order
Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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 StringDefault infinityDescription Used to limit the rate at which the current listener accepts connections.
Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.
For example:
1000/s: Only accepts 1000 connections per second.1000/10s: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Used to limit the number of messages a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
For example:
500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.
bytes_rate
Type StringDescription Used to limit the number of bytes a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
The unit of the bytes could be: B, KB, MB, GB.
For example:
500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.
access_rules
Type Array(String)Default ["allow all"]Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]proxy_protocol_timeout
Type DurationDefault "3s"Description If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.
EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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://{host}:{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 The timeout for waiting for the WebSocket upgrade request. After the timeout, the connection will be closed.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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 StringDefault infinityDescription Used to limit the rate at which the current listener accepts connections.
Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.
For example:
1000/s: Only accepts 1000 connections per second.1000/10s: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Used to limit the number of messages a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
For example:
500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.
bytes_rate
Type StringDescription Used to limit the number of bytes a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
The unit of the bytes could be: B, KB, MB, GB.
For example:
500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.
access_rules
Type Array(String)Default ["allow all"]Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]proxy_protocol_timeout
Type DurationDefault "3s"Description If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.
EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.tcp_options
Type Struct(tcp_opts)send_timeout
Type DurationDefault "15s"Description The maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark
Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order
Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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://{host}:{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 The timeout for waiting for the WebSocket upgrade request. After the timeout, the connection will be closed.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
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 StringDefault infinityDescription Used to limit the rate at which the current listener accepts connections.
Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.
For example:
1000/s: Only accepts 1000 connections per second.1000/10s: Only accepts 1000 connections every 10 seconds.
messages_rate
Type StringDescription Used to limit the number of messages a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
For example:
500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.
bytes_rate
Type StringDescription Used to limit the number of bytes a single client can send to EMQX per second.
Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.
The unit of the bytes could be: B, KB, MB, GB.
For example:
500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.
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.
max_packet_size
Type BytesizeDefault "1MB"Description Maximum MQTT packet size allowed. Default: 1 MB, Maximum: 256 MB
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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: Clients in a shared subscription group will consume messages in turn, and the progress of the loop is recorded independently in each publisher, so two adjacent messages from different publishers may be consumed by the same client in the subscription group;round_robin_per_group: Clients in a shared subscription group will consume messages in turn, and the progress of the loop is recorded independently in each node, so two adjacent messages from different nodes may be consumed by the same client in the subscription group;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. The initial selection is made based onmqtt_shared_subscription_initial_sticky_pick;hash_clientid: Hash the publisher's client ID to select a subscriber;hash_topic: Hash the publishing topic to select a subscriber.
shared_subscription_initial_sticky_pick
Type Enum(random,local,hash_topic,hash_clientid)Default randomDescription The strategy to use for the initial subscriber pick when shared_subscription_strategy is
sticky.random: Randomly select the subscriber;local: Randomly select a subscriber on the current node, if there are no subscribers on the current node, then randomly select within the cluster;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.
keepalive_check_interval
Type DurationDefault "30s"Description The frequency of checking for incoming MQTT packets determines how often the server will check for new MQTT packets. If a certain amount of time passes without any packets being sent from the client, this time will be added up. Once the accumulated time exceeds
keepalive-interval * keepalive-multiplier, the connection will be terminated. The default is set to 30 seconds, with a minimum value of 1 second and a maximum value ofkeepalive-interval / 2.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
clientid_override
Type OneOf(String("disabled"),String)Default disabledDescription 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(username, '.')).The variables pre-bound variables are:
cn: Client's TLS certificate common name.dn: Client's TLS certificate distinguished name (the subject).clientid: The original MQTT Client ID.username: MQTT Client's username.client_attrs.{NAME}: Client attributes initialized by per configclient_attrs_init.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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-Intervalproperty is not set in the message; otherwise, the value of theMessage-Expiry-Intervalproperty will be used. For MQTT versions older than 5.0, this configuration will always take effect. Please note that settingmessage_expiry_intervalgreater thansession_expiry_intervalis 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 priority list. Prioritize messages in the message queue by topic. The priority range is
[1, 255].The larger the value, the higher the priority. Messages with higher priority will be sent first.
Topics not in this list will use the default priority (specified by
mqueue_default_priority).By default, this list is empty, which means all topics have the same priority.
Note: commas and equal signs are not supported in topic names.
For example, if you want
topic/1to have a higher priority thantopic/2, you can configure it like this: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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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),Struct(gcp_device),Struct(scram_restapi_get),Struct(scram_restapi_post),Struct(kerberos),Struct(cinfo)))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.
bootstrap_type
Type Enum(hash,plain)Default plainDescription Specify which type of content the bootstrap file has.
-
plain:- Expected data fields:
user_id,password,is_superuser user_id: Can be Client ID or username, depending on built-in database authentication'suser_id_typeconfig.password: User's plaintext password.is_superuser: Boolean, user's administrative status.
- Expected data fields:
-
hash:- Expected data fields:
user_id,password_hash,salt,is_superuser - Definitions similar to
plaintype, withpassword_hashandsaltadded for security.
- Expected data fields:
The content can be either in CSV, or JSON format.
Here is a CSV example:
user_id,password_hash,salt,is_superuser\nmy_user,b6c743545a7817ae8c8f624371d5f5f0373234bb0ff36b8ffbf19bce0e06ab75,de1024f462fb83910fd13151bd4bd235,trueAnd JSON content should be decoded into an array of objects, for example:
[{"user_id": "my_user","password": "s3cr3tp@ssw0rd","is_superuser": true}].The hash string for
password_hashdepends on howpassword_hash_algorithmis configured for the built-in database authentication mechanism. For example, if it's configured aspassword_hash_algorithm {name = sha256, salt_position = suffix}, then the salt is appended to the password before hashed. Here is the equivalent Python expression:hashlib.sha256(password + salt).hexdigest().-
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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. The allowed formats are the following: A map where claim names are map keys and expected values are map values:
{ claim_name = "${username}", ...}.A list of maps with
name(claim name) andvalue(expected claim value) keys:[{name = "claim_name", value = "${username}"}, ...].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 in
verify_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. The allowed formats are the following: A map where claim names are map keys and expected values are map values:
{ claim_name = "${username}", ...}.A list of maps with
name(claim name) andvalue(expected claim value) keys:[{name = "claim_name", value = "${username}"}, ...].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 in
verify_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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. The allowed formats are the following: A map where claim names are map keys and expected values are map values:
{ claim_name = "${username}", ...}.A list of maps with
name(claim name) andvalue(expected claim value) keys:[{name = "claim_name", value = "${username}"}, ...].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 in
verify_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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
checks
Type Array(Struct(cinfo_check))Description A list of checks to perform on the client information. If all checks are skipped, the default result
ignoreis returned. Theignoreresult means to defer the authentication to the next authenticator in the chain.is_match
Type OneOf(String,Array(String))Description One Variform expression or an array of expressions to evaluate with a set of pre-bound variables derived from the client information. Supported variables:
username: the username of the client.password: the password of the client.clientid: the client ID of the client.client_attrs.*: the client attributes of the client.peerhost: the IP address of the client.cert_subject: the subject of the TLS certificate.cert_common_name: the issuer of the TLS certificate.zone: the config zone associated with the listener from which the client is accepted. If the expression(s) all yields the string value'true', then the associatedresultis returned from this authenticator. If any expression yields the other than'true', then the current check is skipped.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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,singleton,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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
links
Type Array(Struct(link))Default []Description The list of the linked EMQX clusters.
password
Type SecretDescription Optional MQTT username for connecting to the remote EMQX cluster.
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 configuration for connecting to the remote EMQX 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
topics
Type Array(String)Description MQTT topics to be forwarded by the linked remote EMQX broker to the local broker. Messages are only forwarded if the local EMQX broker has matching subscriber(s). Wildcards are supported. Setting empty topics list on one side of the link can be used to establish unidirectional links: the side with the empty topics won't receive remote messages, but it can forward relevant messages to its linked counterpart (according to the topics configured on that side of the link).
retry_interval
Type StringDefault "15s"Description MQTT Message retry interval. Delay for the link 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
resource_opts
Type Struct(creation_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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
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.
payload_encode
Type Enum(hex,text,hidden)Default textDescription Determine the format of the payload format in the trace file.
text: Text-based protocol or plain text protocol. It is recommended when payload is JSON encoded.
hex: Binary hexadecimal encode. It is recommended when payload is a custom binary protocol.
hidden: payload is obfuscated as******
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.
payload_encode
Type Enum(hex,text,hidden)Default textDescription Determine the format of the payload format in the trace file.
text: Text-based protocol or plain text protocol. It is recommended when payload is JSON encoded.
hex: Binary hexadecimal encode. It is recommended when payload is a custom binary protocol.
hidden: payload is obfuscated as******
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.
payload_encode
Type Enum(hex,text,hidden)Default textDescription Determine the format of the payload format in the trace file.
text: Text-based protocol or plain text protocol. It is recommended when payload is JSON encoded.
hex: Binary hexadecimal encode. It is recommended when payload is a custom binary protocol.
hidden: payload is obfuscated as******
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
audit
Type Struct(log_audit_handler)Default {enable = false, level = info}Description Audit file-based log 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.
payload_encode
Type Enum(hex,text,hidden)Default textDescription Determine the format of the payload format in the trace file.
text: Text-based protocol or plain text protocol. It is recommended when payload is JSON encoded.
hex: Binary hexadecimal encode. It is recommended when payload is a custom binary protocol.
hidden: payload is obfuscated as******
rpc
Type Struct(rpc)port_discovery
Type Enum(manual,stateless)Default statelessDescription manual: discover ports byserver_port.
stateless: discover ports in a stateless manner, using the following algorithm. If node name isemqxN@127.0.0.1, where the N is an integer, then the listening port will be 5370 + N. NOTE: whenport_discoveryismanual,server_portconfiguration has no effect.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.socket_keepalive_idle
Type Duration(s)Default "15m"Description Corresponds to the
TCP_KEEPIDLEsocket option. The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.socket_keepalive_interval
Type Duration(s)Default "75s"Description Corresponds to the
TCP_KEEPINTVLsocket option. The time (in seconds) between individual keepalive probes.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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 EMQX creates at least one lightweight process for each client connection.
Each process has its own message queue (aka mailbox) to hold messages from other processes (e.g. MQTT messages) so that the process can read messages from the message queue (mailbox) at any time.
If the system is busy or the process hangs due to a busy socket (see
high_watermark), the message queue can accumulate many messages.To avoid excessive memory usage, EMQX will force a process to shut down when the length of its message queue exceeds
max_mailbox_size.max_heap_size
Type BytesizeDefault "32MB"Description The maximum heap size of the process. If the
force_shutdownis enabled, processes that exceed this limit will automatically exit or be forcibly killed. Messages in the process message queue (mailbox) are also part of the heap. The shutdown of a process can be divided into the following two situations:- The process actively checks the current heap size during its own operation, and actively exits after finding that it exceeds the limit.
- The underlying scheduling system checks the current heap size after performing garbage collection for the process, and forcibly kills the process after finding that it exceeds the limit.
Note: The Error logs generated by the above two will be different. The log generated by the former is similar to
...errorContext: connection_shutdown, reason: #{max => 2097152, reason => proc_heap_too_large, value => 2787348}.., and the log generated by the latter is similar to...Context: maximum heap size reached....
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
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_raft),Struct(builtin_local))Default {backend = builtin_raft}Description Configuration related to the durable storage of MQTT messages.
replication_factor
Type Integer(1..+inf)Default 3Description Number of identical replicas each shard should have. Increasing this number improves durability and availability at the expense of greater resource consumption. Quorum of replicas is needed to be healthy for the replication to work, hence an odd number of replicas is a good pick in general. 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.
n_sites
Type Integer(1..+inf)Default 1Description Number of storage sites that need to share responsibility over the set of storage shards. In this context, sites are EMQX nodes with message durability enabled. Please note that it takes effect only during the initialization of the durable storage database. During this phase at least that many sites should come online to distribute shards between them, otherwise message storage will be unavailable until then. After the initialization is complete, sites may be offline, which will affect availability depending on the number of offline sites and replication factor.
n_shards
Type Integer(1..+inf)Default 16Description 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_v2),Struct(layout_builtin_wildcard_optimized),Struct(layout_builtin_reference))Default {type = wildcard_optimized_v2}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.
n_shards
Type Integer(1..+inf)Default 16Description 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_v2),Struct(layout_builtin_wildcard_optimized),Struct(layout_builtin_reference))Default {type = wildcard_optimized_v2}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 count limit check, used together with
process_high_watermarkandprocess_low_watermark.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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 The validity period of historical alarms. Calculated from the time of activation of the historical alarm instead of the time of cancelation.
If it exists longer than the validity period, the alarm will be deleted.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
durable_sessions
Type Struct(durable_sessions)enable
Type BooleanDefault falseDescription Use durable storage for client sessions persistence. If enabled, sessions configured to outlive client connections, along with their corresponding messages, will be durably stored and survive broker downtime.
:::warning Messages sent to the durable sessions are saved on disc. This inevitably limits the overall throughput of the system. :::
batch_size
Type Integer(1..+inf)Default 100Description This value affects the flow control for the persistent sessions. Persistent session queries the durable message storage in batches. This value specifies size of the batch.
Note: larger batches generally improve the throughput and overall performance of the system, but increase RAM usage per client.
idle_poll_interval
Type DurationDefault "10s"Description Expiry interval for poll requests sent by durable sessions to the storage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.heartbeat_interval
Type DurationDefault "5000ms"Description Durable sessions back up their state on disc every heartbeat interval.
Heartbeat interval is also taken into account during garbage collection of expired sessions. It is added to the session expiry time as a safety margin when precise time of session termination is not precisely known.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.session_gc_interval
Type DurationDefault "10m"Description The interval at which session garbage collection is executed for persistent sessions.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.message_retention_period
Type DurationDefault "1d"Description Broker keeps messages sent to the durable sessions for this period of time.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
connectors
Type Struct(connectors)kafka_consumer
Type Map($name->Struct(config_connector))Description Kafka Consumer Connector Config
connect_timeout
Type DurationDefault "5s"Description Maximum wait time for TCP connection establishment (including authentication time if enabled).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.min_metadata_refresh_interval
Type DurationDefault "3s"Description Minimum time interval the client has to wait before refreshing Kafka broker and topic metadata. Setting too small value may add extra load on Kafka.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.metadata_request_timeout
Type DurationDefault "5s"Description Maximum wait time when fetching topic metadata.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.authentication
Type OneOf(String("none"),Struct(auth_username_password),Struct(auth_gssapi_kerberos))Default noneDescription Authentication configs.
password
Type SecretDescription SASL authentication password.
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.
socket_opts
Type Struct(socket_opts)Description Extra socket options.
sndbuf
Type BytesizeDefault "1MB"Description Fine tune the socket send buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.recbuf
Type BytesizeDefault "1MB"Description Fine tune the socket receive buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.tcp_keepalive
Type StringDefault noneDescription Enable TCP keepalive. 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: TCP keepalive probes are sent after the connection is idle for 240 seconds, and the probes are sent every 30 seconds until a response is received, if it misses 5 consecutive responses, the connection should be closed. Default: 'none'
ssl
Type Struct(ssl_client_opts)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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"server_name_indication
Type OneOf(String("auto"),String("disable"),String)Default autoDescription Server Name Indication (SNI) setting for TLS handshake.
auto: Allow the client to automatically determine the appropriate SNI.disable: If you wish to prevent the client from sending the SNI.- Other string values will be sent as-is.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
kinesis
Type Map($name->Struct(config_connector))Description Kinesis Connector Config
aws_secret_access_key
Type SecretDescription AWS Secret Access Key for connecting to Amazon Kinesis.
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
rocketmq
Type Map($name->Struct(config_connector))Description RocketMQ Connector Config
secret_key
Type SecretDefault ""Description RocketMQ server
secretKey.
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.security_token
Type SecretDefault ""Description RocketMQ Server Security Token
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
rabbitmq
Type Map($name->Struct(config_connector))Description RabbitMQ Connector Config
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.timeout
Type DurationDefault "5s"Description The timeout for waiting on the connection to be established.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.heartbeat
Type DurationDefault "30s"Description The interval for sending heartbeat messages to the RabbitMQ server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
mysql
Type Map($name->Struct(config_connector))Description MySQL Connector Config
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
dynamo
Type Map($name->Struct(config_connector))Description DynamoDB Connector Config
aws_secret_access_key
Type SecretDescription AWS Secret Access Key for connecting to DynamoDB.
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
cassandra
Type Map($name->Struct(config_connector))Description Cassandra Connector Config
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
sqlserver
Type Map($name->Struct(config_connector))Description Microsoft SQL Server Connector Config
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
redis
Type Map($name->Struct(config_connector))Description Redis Connector Config
parameters
Type OneOf(Struct(redis_single_connector),Struct(redis_sentinel_connector),Struct(redis_cluster_connector))Description Set of parameters specific for the given type of this Redis connector,
redis_typecan be one ofsingle,clusterorsentinel.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.
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.
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.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
azure_blob_storage
Type Map($name->Struct(config_connector))Description Azure Blob Storage Connector Config
account_key
Type SecretDescription Account key for Azure Blob Storage service.
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
hstreamdb
Type Map($name->Struct(config_connector))Description HStreamDB Connector Config
grpc_timeout
Type DurationDefault "30s"Description The timeout for HStreamDB gRPC requests.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
couchbase
Type Map($name->Struct(config_connector))Description Couchbase 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.password
Type SecretDescription Password for Couchbase service.
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
azure_event_hub_producer
Type Map($name->Struct(config_connector))Description Azure Event Hub Connector Config
connect_timeout
Type DurationDefault "5s"Description Maximum wait time for TCP connection establishment (including authentication time if enabled).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.min_metadata_refresh_interval
Type DurationDefault "3s"Description Minimum time interval the client has to wait before refreshing Azure Event Hubs Kafka broker and topic metadata. Setting too small value may add extra load on Azure Event Hubs.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.metadata_request_timeout
Type DurationDefault "5s"Description Maximum wait time when fetching metadata from Azure Event Hubs.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.authentication
Type Struct(auth_username_password)Default {}Description Authentication configs.
password
Type SecretDescription The Connection String for connecting to Azure Event Hubs. Should be the "connection string-primary key" of a Namespace shared access policy.
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.
socket_opts
Type Struct(socket_opts)Description Extra socket options.
sndbuf
Type BytesizeDefault "1MB"Description Fine tune the socket send buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.recbuf
Type BytesizeDefault "1MB"Description Fine tune the socket receive buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.tcp_keepalive
Type StringDefault noneDescription Enable TCP keepalive. 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: TCP keepalive probes are sent after the connection is idle for 240 seconds, and the probes are sent every 30 seconds until a response is received, if it misses 5 consecutive responses, the connection should be closed. Default: 'none'
ssl
Type Struct(ssl_client_opts)Default {enable = true}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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"server_name_indication
Type OneOf(String("auto"),String("disable"),String)Default autoDescription Server Name Indication (SNI) setting for TLS handshake.
auto: The client will use"servicebus.windows.net"as SNI.disable: If you wish to prevent the client from sending the SNI.- Other string values it will be sent as-is.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
datalayers
Type Map($name->Struct(config_connector))Description Datalayers Connector Config
parameters
Type OneOf(Struct(datalayers_influxdb_v1_parameters))Description Set of parameters specific for the given type of this Datalayers connector.
password
Type SecretDescription Datalayers password.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
iotdb
Type Map($name->OneOf(Struct(config_restapi),Struct(config_thrift)))Description IoTDB 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
authentication
Type OneOf(Struct(authentication))Default auth_basicDescription Authentication configuration
password
Type SecretDescription The password as configured at the IoTDB/Thrift 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.
connect_timeout
Type DurationDefault "10s"Description Timeout for connecting to the IoTDB Thrift server
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.recv_timeout
Type DurationDefault "10s"Description Timeout for IoTDB Thrift server response
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.password
Type SecretDescription The password as configured at the IoTDB/Thrift 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.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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
gcp_pubsub_consumer
Type Map($name->Struct(config_connector))Description GCP PubSub Consumer 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.request_timeout
Type DurationDescription Deprecated since e5.0.1.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.service_account_json
Type StringDescription JSON containing the GCP Service Account credentials to be used with PubSub. When a GCP Service Account is created (as described in https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount), you have the option of downloading the credentials in JSON form. That's the file needed.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
greptimedb
Type Map($name->Struct(config_connector))Description GreptimeDB Connector Config
password
Type SecretDescription GreptimeDB password.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
kafka_producer
Type Map($name->Struct(config_connector))Description Kafka Producer Connector Config
connect_timeout
Type DurationDefault "5s"Description Maximum wait time for TCP connection establishment (including authentication time if enabled).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.min_metadata_refresh_interval
Type DurationDefault "3s"Description Minimum time interval the client has to wait before refreshing Kafka broker and topic metadata. Setting too small value may add extra load on Kafka.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.metadata_request_timeout
Type DurationDefault "5s"Description Maximum wait time when fetching topic metadata.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.authentication
Type OneOf(String("none"),Struct(auth_username_password),Struct(auth_gssapi_kerberos))Default noneDescription Authentication configs.
password
Type SecretDescription SASL authentication password.
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.
socket_opts
Type Struct(socket_opts)Description Extra socket options.
sndbuf
Type BytesizeDefault "1MB"Description Fine tune the socket send buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.recbuf
Type BytesizeDefault "1MB"Description Fine tune the socket receive buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.tcp_keepalive
Type StringDefault noneDescription Enable TCP keepalive. 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: TCP keepalive probes are sent after the connection is idle for 240 seconds, and the probes are sent every 30 seconds until a response is received, if it misses 5 consecutive responses, the connection should be closed. Default: 'none'
ssl
Type Struct(ssl_client_opts)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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"server_name_indication
Type OneOf(String("auto"),String("disable"),String)Default autoDescription Server Name Indication (SNI) setting for TLS handshake.
auto: Allow the client to automatically determine the appropriate SNI.disable: If you wish to prevent the client from sending the SNI.- Other string values will be sent as-is.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
syskeeper_proxy
Type Map($name->Struct(config))Description Syskeeper Proxy Connector Config
handshake_timeout
Type DurationDefault "10s"Description The maximum to wait for the handshake when a connection is created
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
pulsar
Type Map($name->Struct(config_connector))Description Pulsar Connector Config
authentication
Type OneOf(String("none"),Struct(auth_basic),Struct(auth_token))Default noneDescription Authentication configs.
password
Type SecretDescription Basic authentication password. The
passwordpart of theusername:passwordauthentication string.
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.
jwt
Type SecretDescription JWT authentication token.
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.
connect_timeout
Type DurationDefault "5s"Description Maximum wait time for TCP connection establishment (including authentication time if enabled).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
gcp_pubsub_producer
Type Map($name->Struct(config_connector))Description GCP PubSub Producer 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.request_timeout
Type DurationDescription Deprecated since e5.0.1.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.service_account_json
Type StringDescription JSON containing the GCP Service Account credentials to be used with PubSub. When a GCP Service Account is created (as described in https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount), you have the option of downloading the credentials in JSON form. That's the file needed.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
s3
Type Map($name->Struct(config_connector))Description S3 Connector Config
secret_access_key
Type SecretDescription The secret access key of the S3 bucket.
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.transport_options
Type Struct(transport_options)Description Options for the HTTP transport layer used by the S3 client.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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 DurationDescription HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
resource_opts
Type Struct(s3_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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
mongodb
Type Map($name->Struct(config_connector))Description MongoDB Connector Config
parameters
Type OneOf(Struct(connector_single),Struct(connector_sharded),Struct(connector_rs))Description Set of parameters specific for the given type of this MongoDB connector,
mongo_typecan be one ofsingle(Standalone),sharded(Sharded) orrs(Replica Set).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.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
syskeeper_forwarder
Type Map($name->Struct(config))Description Syskeeper Connector Config
ack_timeout
Type DurationDefault "10s"Description The maximum time to wait for an acknowledgement from the proxy server
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
timescale
Type Map($name->Struct(config_connector))Description Timescale Connector Config
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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(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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
matrix
Type Map($name->Struct(config_connector))Description Matrix Connector Config
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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(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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
opents
Type Map($name->Struct(config_connector))Description OpenTSDB Connector Config
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
oracle
Type Map($name->Struct(config_connector))Description Oracle Connector Config
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
pgsql
Type Map($name->Struct(config_connector))Description PostgreSQL Connector Config
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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(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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
tdengine
Type Map($name->Struct(config_connector))Description TDengine Connector Config
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
snowflake
Type Map($name->Struct(config_connector))Description Snowflake Connector Config
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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.enable_pipelining
Type Integer(1..+inf)Default 100Description The maximum number of HTTP requests that can be sent before an HTTP response is received.
Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
clickhouse
Type Map($name->Struct(config_connector))Description ClickHouse Connector Config
connect_timeout
Type DurationDefault "15s"Description The timeout when connecting to the Clickhouse server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
influxdb
Type Map($name->Struct(config_connector))Description InfluxDB Connector Config
parameters
Type OneOf(Struct(connector_influxdb_api_v1),Struct(connector_influxdb_api_v2))Description Set of parameters specific for the given type of this InfluxDB connector,
influxdb_typecan be one ofinfluxdb_api_v1,influxdb_api_v1.password
Type SecretDescription InfluxDB password.
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.
token
Type SecretDescription InfluxDB token.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
confluent_producer
Type Map($name->Struct(config_connector))Description Confluent Connector Config
connect_timeout
Type DurationDefault "5s"Description Maximum wait time for TCP connection establishment (including authentication time if enabled).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.min_metadata_refresh_interval
Type DurationDefault "3s"Description Minimum time interval the client has to wait before refreshing Confluent Kafka broker and topic metadata. Setting too small value may add extra load on Confluent.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.metadata_request_timeout
Type DurationDefault "5s"Description Maximum wait time when fetching metadata from Confluent.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.authentication
Type Struct(auth_username_password)Default {}Description Authentication configs.
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.
socket_opts
Type Struct(socket_opts)Description Extra socket options.
sndbuf
Type BytesizeDefault "1MB"Description Fine tune the socket send buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.recbuf
Type BytesizeDefault "1MB"Description Fine tune the socket receive buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.tcp_keepalive
Type StringDefault noneDescription Enable TCP keepalive. 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: TCP keepalive probes are sent after the connection is idle for 240 seconds, and the probes are sent every 30 seconds until a response is received, if it misses 5 consecutive responses, the connection should be closed. Default: 'none'
ssl
Type Struct(ssl_client_opts)Default {enable = true}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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"server_name_indication
Type OneOf(String("auto"),String("disable"),String)Default autoDescription Server Name Indication (SNI) setting for TLS handshake.
auto: The client will use"servicebus.windows.net"as SNI.disable: If you wish to prevent the client from sending the SNI.- Other string values it will be sent as-is.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
actions
Type Struct(actions)kinesis
Type Map($name->Struct(kinesis_action))Description Kinesis Action Config
parameters
Type Struct(action_parameters)Description Action specific configuration.
payload_template
Type StringDefault "${.}"Description The template for formatting the outgoing messages. If undefined, will send all the available context in JSON format.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
rocketmq
Type Map($name->Struct(rocketmq_action))Description RocketMQ Action Config
parameters
Type Struct(action_parameters)Description Action specific configuration.
template
Type StringDefault ""Description Template, the default value is empty. When this value is empty the whole message will be stored in the RocketMQ.
The template can be any valid string with placeholders, example:
- ${id}, ${username}, ${clientid}, ${timestamp}
- {"id" : ${id}, "username" : ${username}}
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.sync_timeout
Type DurationDefault "3s"Description Timeout of RocketMQ driver synchronous call.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.refresh_interval
Type DurationDefault "3s"Description RocketMQ Topic Route Refresh Interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
rabbitmq
Type Map($name->Struct(publisher_action))Description RabbitMQ Action Config
parameters
Type Struct(action_parameters)Description The action config defines how this bridge send messages to the remote RabbitMQ broker
publish_confirmation_timeout
Type DurationDefault "30s"Description The timeout for waiting on the connection to be established.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.delivery_mode
Type Enum(non_persistent,persistent)Default non_persistentDescription The delivery mode for messages published to RabbitMQ. Delivery mode non_persistent (1) is suitable for messages that don't require persistence across RabbitMQ restarts, whereas delivery mode persistent (2) is designed for messages that must survive RabbitMQ restarts.
payload_template
Type StringDefault ""Description The template for formatting the payload of the message before sending it to RabbitMQ. Template placeholders, such as ${field1.sub_field}, will be substituted with the respective field's value. When left empty, the entire input message will be used as the payload, formatted as a JSON text. This behavior is equivalent to specifying ${.} as the payload template.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
mysql
Type Map($name->Struct(mysql_action))Description Action to interact with a MySQL connector
parameters
Type Struct(action_parameters)Description Additional parameters specific to this action type
sql
Type StringDefault "insert into t_mqtt_msg(msgid, topic, qos, payload, arrived) values (${id}, ${topic}, ${qos}, ${payload}, FROM_UNIXTIME(${timestamp}/1000))"Description SQL Template
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.undefined_vars_as_null
Type BooleanDefault falseDescription When writing to databases, treat undefined variables as NULL. When this option is enabled, if undefined variables (like ${var}) are used in templates, they will be replaced with "NULL" instead of the string "undefined". If this option is not enabled (default), the string "undefined" might be inserted. This option should always be
trueif possible; the default valuefalseis only to ensure backward compatibility.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
dynamo
Type Map($name->Struct(dynamo_action))Description DynamoDB Action Config
parameters
Type Struct(action_parameters)Description Action specific configuration.
template
Type StringDefault ""Description Template, the default value is empty. When this value is empty the whole message will be stored in the database.
The template can be any valid JSON with placeholders and make sure all keys for table are here, example:
{"id" : "${id}", "clientid" : "${clientid}", "data" : "${payload.data}"}
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.undefined_vars_as_null
Type BooleanDefault falseDescription When writing to databases, treat undefined variables as NULL. When this option is enabled, if undefined variables (like ${var}) are used in templates, they will be replaced with "NULL" instead of the string "undefined". If this option is not enabled (default), the string "undefined" might be inserted. This option should always be
trueif possible; the default valuefalseis only to ensure backward compatibility.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
cassandra
Type Map($name->Struct(cassandra_action))Description Cassandra 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
sqlserver
Type Map($name->Struct(sqlserver_action))Description Configuration for Microsoft SOL Server action.
parameters
Type Struct(action_parameters)Description Action specific configuration.
undefined_vars_as_null
Type BooleanDefault falseDescription When writing to databases, treat undefined variables as NULL. When this option is enabled, if undefined variables (like ${var}) are used in templates, they will be replaced with "NULL" instead of the string "undefined". If this option is not enabled (default), the string "undefined" might be inserted. This option should always be
trueif possible; the default valuefalseis only to ensure backward compatibility.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
redis
Type Map($name->Struct(redis_action))Description Redis 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_size
Type Integer(1..+inf)Default 1Description This parameter defines the upper limit of the batch count. Setting this value to 1 effectively disables batching, as it indicates that only one item will be processed per batch. Note on Redis Cluster Mode: In the context of Redis Cluster Mode, it is important to note that batching is not supported. Consequently, the batch_size is always set to 1, reflecting the mode inherent limitation in handling batch operations.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
azure_blob_storage
Type Map($name->Struct(azure_blob_storage))Description Azure Blob Storage Action Config
parameters
Type OneOf(Struct(aggreg_parameters),Struct(direct_parameters))Description Set of parameters for the action.
aggregation
Type Struct(aggregation)Description Set of parameters governing the aggregation process.
container
Type OneOf(Struct(container_csv))Default {type = csv}Description Settings governing the file format of an upload containing aggregated events.
column_order Type Array(String)Default []Description Event fields that will be ordered first as columns in the resulting CSV file.
Regardless of this setting, resulting CSV will contain all the fields of aggregated events, but all the columns not explicitly mentioned here will be ordered after the ones listed here in the lexicographical order.
time_interval
Type Duration(s)Default "1h"Description Amount of time events will be aggregated in a single object before uploading.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_records
Type Integer(1..+inf)Default 1000000Description Number of records (events) allowed per each aggregated object. Each aggregated upload will contain no more than that number of events, but may contain less.
If event rate is high enough, there obviously may be more than one aggregated upload during the same time interval. These uploads will have different, but consecutive sequence numbers, which will be a part of Azure Blob Storage blob name.
blob
Type StringDescription Template for the Azure Blob Storage blob name of an aggregated upload.
Template may contain placeholders for the following variables:${action}: name of the action (required).${node}: name of the EMQX node conducting the upload (required).${datetime.{format}}: date and time when aggregation started, formatted according to the{format}string (required):${datetime.rfc3339utc}: RFC3339-formatted date and time in UTC,${datetime.rfc3339}: RFC3339-formatted date and time in local timezone,${datetime.unix}: Unix timestamp.
${datetime_until.{format}}: date and time when aggregation ended, with the same formatting options.${sequence}: sequence number of the aggregated upload within the same time interval (required).
A string for `${.path.to.var}` style value interpolation, where the leading dot is optional, and `${.}` represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "10ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
hstreamdb
Type Map($name->Struct(hstreamdb_action))Description HStreamDB Action Config
parameters
Type Struct(action_parameters)Description Action specific configuration.
grpc_flush_timeout
Type DurationDefault "10s"Description Time interval for flushing gRPC calls to the HStreamDB server.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.record_template
Type StringDefault "${payload}"Description The HStream Record template to be forwarded to the HStreamDB. Placeholders supported.
NOTE: When you useraw recordtemplate (which means the data is not a valid JSON), you should usereadorsubscriptionin HStream to get the data.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.batch_interval
Type DurationDefault "500ms"Description Maximum interval that is allowed between two successive (batch) request.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
couchbase
Type Map($name->Struct(couchbase))Description Couchbase 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
azure_event_hub_producer
Type Map($name->Struct(actions))Description Azure Event Hub Actions Config
parameters
Aliases kafka Type Struct(producer_kafka_opts)Description Azure Event Hubs producer configs.
message
Type Struct(kafka_message)Description Template for rendering a message.
key
Type StringDefault "${.clientid}"Description Template for rendering message key. If the template is rendered into a NULL value (i.e. there is no such data field in Rule Engine context) then
NULL(but not empty string) is used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.value
Type StringDefault "${.}"Description Template to render Azure Event Hubs message value. If the template is rendered into a NULL value (i.e. there is no such data field in Rule Engine context) then Azure Event Hubs'
NULL(but not empty string) is used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
max_linger_time
Type DurationDefault "0ms"Description Maximum duration for a per-partition producer to wait for messages in order to collect a batch to buffer. The default value
0means no wait. For non-memory buffer mode, it's advised to configure at least5msfor less IOPS.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_linger_bytes
Type BytesizeDefault "10MB"Description Maximum number of bytes for a per-partition producer to wait for messages in order to collect a batch to buffer.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.max_batch_bytes
Type BytesizeDefault "896KB"Description Maximum bytes to collect in an Azure Event Hubs message batch.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.partition_strategy
Type Enum(random,key_dispatch)Default randomDescription Partition strategy is to tell the producer how to dispatch messages to partitions.
random: Randomly pick a partition for each message.key_dispatch: Assigns messages to partitions based on a hash of the message key, ensuring consistent partition for messages with the same key.required_acks
Type Enum(all_isr,leader_only)Default all_isrDescription The acknowledgement criteria for the partition leader. It determines the level of confirmation required from partition replicas before sending an acknowledgement back to the producer.
all_isr: Require all in-sync replicas to acknowledge.leader_only: Require only the partition-leader's acknowledgement.none: No need for Kafka to acknowledge at all.kafka_headers
Type StringDescription Provide a placeholder for message headers
e.g.${pub_props}
Note that the value of the placeholder must be either an object:{"foo": "bar"}or an array of key-value pairs:[{"key": "foo", "value": "bar"}]
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.partition_count_refresh_interval
Type Duration(s)Default "60s"Description The time interval for Azure Event Hubs producer to discover increased number of partitions. After the number of partitions is increased in Azure Event Hubs, EMQX will start taking the discovered partitions into account when dispatching messages per
partition_strategy.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partitions_limit
Type OneOf(String("all_partitions"),Integer(1..+inf))Default all_partitionsDescription Limit the number of partitions to produce data for the given topic. The special value
all_partitionsis to utilize all partitions for the topic. Setting this to a value which is greater than the total number of partitions in has no effect.buffer
Type Struct(producer_buffer)Description Configure producer message buffer.
Tell Azure Event Hubs producer how to buffer messages when EMQX has more messages to send than Azure Event Hubs can keep up, or when Azure Event Hubs is down.
mode
Type Enum(memory,disk,hybrid)Default memoryDescription Message buffer mode.
memory: Buffer all messages in memory. The messages will be lost in case of EMQX node restartdisk: Buffer all messages on disk. The messages on disk are able to survive EMQX node restart.hybrid: Buffer message in memory first, when up to certain limit (seesegment_bytesconfig for more information), then start offloading messages to disk, Likememorymode, the messages will be lost in case of EMQX node restart.per_partition_limit
Type BytesizeDefault "2GB"Description Number of bytes allowed to buffer for each partition. When this limit is exceeded, older messages will be discarded to make room for new messages to be buffered.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.segment_bytes
Type BytesizeDefault "10MB"Description Applicable when buffer mode is set to
diskorhybrid. This setting specifies the size of each buffer file stored on disk.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
sync_query_timeout
Type DurationDefault "5s"Description This parameter defines the timeout limit for synchronous queries. It applies only when the bridge query mode is configured to 'sync'.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
resource_opts
Type Struct(resource_opts)Default {}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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
datalayers
Type Map($name->Struct(datalayers_action))Description Datalayers Action Config
parameters
Type Struct(action_parameters)Description Additional parameters specific to this action type
write_syntax
Type StringDescription Conf of InfluxDB line protocol to write data points. It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point, and placeholder supported. See also InfluxDB 1.8 Line Protocol
TLDR:<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]Please note that a placeholder for an integer value must be annotated with a suffix
i. For example${payload.int_value}i.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
iotdb
Type Map($name->Struct(action_config))Description IoTDB Action Config
parameters
Type Struct(action_parameters)Description IoTDB action parameters
device_id
Type StringDescription The IoTDB device ID this data should be inserted for. If left empty, the MQTT message payload must contain a
device_idfield, or EMQX's rule-engine SQL must produce adevice_idfield.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.data
Type Array(Struct(action_parameters_data))Default []Description IoTDB action parameter data
timestamp
Type OneOf(Enum(now,now_ms,now_ns,now_us),String)Default nowDescription Timestamp. Placeholders in format of ${var} is supported, the final value can be:
- now: use the
now_mswhich is contained in the payload as timestamp - now_ms: same as above
- now_us: use the
now_uswhich is contained in the payload as timestamp - now_ns: use the
now_nswhich is contained in the payload as timestamp - any other: use the value directly as the timestamp
- now: use the
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
greptimedb
Type Map($name->Struct(greptimedb_action))Description GreptimeDB Action Config
parameters
Type Struct(action_parameters)Description Additional parameters specific to this action type
write_syntax
Type StringDescription Conf of GreptimeDB gRPC protocol to write data points. Write syntax is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point, and placeholder supported, which is the same as InfluxDB line protocol. See also InfluxDB 2.3 Line Protocol and GreptimeDB 1.8 Line Protocol
TLDR:<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]Please note that a placeholder for an integer value must be annotated with a suffix
i. For example${payload.int_value}i.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
kafka_producer
Type Map($name->Struct(kafka_producer_action))Description Kafka Producer Action Config
parameters
Aliases kafka Type Struct(producer_kafka_opts)Description Kafka producer configs.
message
Type Struct(kafka_message)Description Template for rendering a message.
key
Type StringDefault "${.clientid}"Description Template for rendering message key. If the template is rendered into a NULL value (i.e. there is no such data field in Rule Engine context) then
NULL(but not empty string) is used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.value
Type StringDefault "${.}"Description Template for rendering Kafka message value. If the template is rendered into a NULL value (i.e. there is no such data field in Rule Engine context) then Kafka's
NULL(but not empty string) is used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.timestamp
Type StringDefault "${.timestamp}"Description Which timestamp to use. The timestamp is expected to be a millisecond precision Unix epoch which can be in string format, e.g.
1661326462115or'1661326462115'. When the desired data field for this template is not found, or if the found data is not a valid integer, the current system timestamp will be used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
max_linger_time
Type DurationDefault "0ms"Description Maximum duration for a per-partition producer to wait for messages in order to collect a batch to buffer. The default value
0means no wait. For non-memory buffer mode, it's advised to configure at least5msfor less IOPS.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_linger_bytes
Type BytesizeDefault "10MB"Description Maximum number of bytes for a per-partition producer to wait for messages in order to collect a batch to buffer.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.max_batch_bytes
Type BytesizeDefault "896KB"Description Maximum bytes to collect in a Kafka message batch. Most of the Kafka brokers default to a limit of 1 MB batch size. EMQX's default value is less than 1 MB in order to compensate Kafka message encoding overheads (especially when each individual message is very small). When a single message is over the limit, it is still sent (as a single element batch).
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.partition_strategy
Type Enum(random,key_dispatch)Default randomDescription Partition strategy is to tell the producer how to dispatch messages to partitions.
random: Randomly pick a partition for each message.key_dispatch: Assigns messages to partitions based on a hash of the message key, ensuring consistent partition for messages with the same key.required_acks
Type Enum(all_isr,leader_only,none)Default all_isrDescription The acknowledgement criteria for the partition leader. It determines the level of confirmation required from partition replicas before sending an acknowledgement back to the producer.
all_isr: Require all in-sync replicas to acknowledge.leader_only: Require only the partition-leader's acknowledgement.none: No need for Kafka to acknowledge at all.kafka_headers
Type StringDescription Provide a placeholder for message headers
e.g.${pub_props}
Note that the value of the placeholder must be either an object:{"foo": "bar"}or an array of key-value pairs:[{"key": "foo", "value": "bar"}]
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.partition_count_refresh_interval
Type Duration(s)Default "60s"Description The time interval for Kafka producer to discover increased number of partitions. After the number of partitions is increased in Kafka, EMQX will start taking the discovered partitions into account when dispatching messages per
partition_strategy.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partitions_limit
Type OneOf(String("all_partitions"),Integer(1..+inf))Default all_partitionsDescription Limit the number of partitions to produce data for the given topic. The special value
all_partitionsis to utilize all partitions for the topic. Setting this to a value which is greater than the total number of partitions in has no effect.buffer
Type Struct(producer_buffer)Description Configure producer message buffer.
Tell Kafka producer how to buffer messages when EMQX has more messages to send than Kafka can keep up, or when Kafka is down.
mode
Type Enum(memory,disk,hybrid)Default memoryDescription Message buffer mode.
memory: Buffer all messages in memory. The messages will be lost in case of EMQX node restartdisk: Buffer all messages on disk. The messages on disk are able to survive EMQX node restart.hybrid: Buffer message in memory first, when up to certain limit (seesegment_bytesconfig for more information), then start offloading messages to disk, Likememorymode, the messages will be lost in case of EMQX node restart.per_partition_limit
Type BytesizeDefault "2GB"Description Number of bytes allowed to buffer for each partition. When this limit is exceeded, older messages will be discarded to make room for new messages to be buffered.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.segment_bytes
Type BytesizeDefault "10MB"Description Applicable when buffer mode is set to
diskorhybrid. This setting specifies the size of each buffer file stored on disk.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
sync_query_timeout
Type DurationDefault "5s"Description This parameter defines the timeout limit for synchronous queries. It applies only when the query mode is configured to 'sync'.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
resource_opts
Type Struct(resource_opts)Default {}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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
pulsar
Type Map($name->Struct(publisher_action))Description Pulsar Action Config
parameters
Type Struct(action_parameters)Description Action specific configs.
sync_timeout
Type DurationDefault "3s"Description Maximum wait time for receiving a receipt from Pulsar when publishing synchronously.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.send_buffer
Type BytesizeDefault "1MB"Description Fine tune the socket send buffer. The default value is tuned for high throughput.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.max_batch_bytes
Type BytesizeDefault "900KB"Description Maximum bytes to collect in a Pulsar message batch. Most of the Pulsar brokers default to a limit of 5 MB batch size. EMQX's default value is less than 5 MB in order to compensate Pulsar message encoding overheads (especially when each individual message is very small). When a single message is over the limit, it is still sent (as a single element batch).
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.strategy
Type Enum(random,roundrobin,key_dispatch)Default randomDescription Partition strategy is to tell the producer how to dispatch messages to Pulsar partitions.
random: Randomly pick a partition for each message.roundrobin: Pick each available producer in turn for each message.key_dispatch: Hash Pulsar message key of the first message in a batch to a partition number.buffer
Type Struct(producer_buffer)Description Configure producer message buffer." Tell Pulsar producer how to buffer messages when EMQX has more messages to" send than Pulsar can keep up, or when Pulsar is down.
mode
Type Enum(memory,disk,hybrid)Default memoryDescription Message buffer mode.
memory: Buffer all messages in memory. The messages will be lost in case of EMQX node restart\ndisk: Buffer all messages on disk. The messages on disk are able to survive EMQX node restart.hybrid: Buffer message in memory first, when up to certain limit (seesegment_bytesconfig for more information), then start offloading messages to disk, Likememorymode, the messages will be lost in case of EMQX node restart.per_partition_limit
Type BytesizeDefault "2GB"Description Number of bytes allowed to buffer for each Pulsar partition. When this limit is exceeded, old messages will be dropped in a trade for credits for new messages to be buffered.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.segment_bytes
Type BytesizeDefault "100MB"Description Applicable when buffer mode is set to
diskorhybrid. This value is to specify the size of each on-disk buffer file.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
gcp_pubsub_producer
Type Map($name->Struct(producer_action))Description GCP PubSub Producer Action Config
parameters
Type Struct(action_parameters)Description Action configs.
ordering_key_template
Type StringDefault ""Description The template for formatting the outgoing message ordering key. Undefined values will be rendered as empty string values. This value will not be added to the message if it's empty.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
s3
Type Map($name->Struct(s3))Description S3 Upload Action Config
parameters
Type OneOf(Struct(s3_aggregated_upload_parameters),Struct(s3_direct_upload_parameters))Description Action that takes incoming events and uploads them to the S3 API compatible service.
container
Type OneOf(Struct(s3_aggregated_container_csv))Default {type = csv}Description Settings governing the file format of an upload containing aggregated events.
column_order
Type Array(String)Default []Description Event fields that will be ordered first as columns in the resulting CSV file.
Regardless of this setting, resulting CSV will contain all the fields of aggregated events, but all the columns not explicitly mentioned here will be ordered after the ones listed here in the lexicographical order.
aggregation
Type Struct(s3_aggregation)Description Set of parameters governing the aggregation process.
time_interval
Type Duration(s)Default "30m"Description Amount of time events will be aggregated in a single object before uploading.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_records
Type Integer(1..+inf)Default "100000"Description Number of records (events) allowed per each aggregated object. Each aggregated upload will contain no more than that number of events, but may contain less.
If event rate is high enough, there obviously may be more than one aggregated upload during the same time interval. These uploads will have different, but consecutive sequence numbers, which will be a part of S3 object key.
key
Type StringDescription Template for the S3 object key of an aggregated upload.
Template may contain placeholders for the following variables:${action}: name of the action (required).${node}: name of the EMQX node conducting the upload (required).${datetime.{format}}: date and time when aggregation started, formatted according to the{format}string (required):${datetime.rfc3339utc}: RFC3339-formatted date and time in UTC,${datetime.rfc3339}: RFC3339-formatted date and time in local timezone,${datetime.unix}: Unix timestamp.
${datetime_until.{format}}: date and time when aggregation ended, with the same formatting options.${sequence}: sequence number of the aggregated upload within the same time interval (required).
A string for `${.path.to.var}` style value interpolation, where the leading dot is optional, and `${.}` represents all values as an object.min_part_size
Type BytesizeDefault "5mb"Description The minimum part size for multipart uploads.
Uploaded data will be accumulated in memory until this size is reached.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.max_part_size
Type BytesizeDefault "5gb"Description The maximum part size for multipart uploads.
S3 uploader won't try to upload parts larger than this size.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
resource_opts
Type Struct(s3_upload_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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "10ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
mongodb
Type Map($name->Struct(mongodb_action))Description MongoDB Action Config
parameters
Type Struct(action_parameters)Description Additional parameters specific to this action type
payload_template
Type StringDescription The template for formatting the outgoing messages. If undefined, rule engine will use JSON format to serialize all visible inputs, such as clientid, topic, payload etc.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
syskeeper_forwarder
Type Map($name->Struct(config))Description Syskeeper Forwarder Action Config
resource_opts
Type Struct(creation_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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.request_ttl
Aliases request_timeout Type OneOf(Duration,String("infinity"))Default infinityDescription 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
timescale
Type Map($name->Struct(pgsql_action))Description Timescale Action Config
parameters
Type Struct(action_parameters)Description Configuration Parameters Specific to the PostgreSQL Action
sql
Type StringDefault "insert into t_mqtt_msg(msgid, topic, qos, payload, arrived) values (${id}, ${topic}, ${qos}, ${payload}, TO_TIMESTAMP((${timestamp} :: bigint)/1000))"Description SQL Template
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
matrix
Type Map($name->Struct(pgsql_action))Description Matrix Action Config
parameters
Type Struct(action_parameters)Description Configuration Parameters Specific to the PostgreSQL Action
sql
Type StringDefault "insert into t_mqtt_msg(msgid, topic, qos, payload, arrived) values (${id}, ${topic}, ${qos}, ${payload}, TO_TIMESTAMP((${timestamp} :: bigint)/1000))"Description SQL Template
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
opents
Type Map($name->Struct(action_config))Description OpenTSDB 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
oracle
Type Map($name->Struct(oracle_action))Description Oracle Action Config
parameters
Type Struct(action_parameters)Description Action specific configuration.
sql
Type StringDefault "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})"Description SQL Template. The template string can contain placeholders for message metadata and payload field. The placeholders are inserted without any checking and special formatting, so it is important to ensure that the inserted values are formatted and escaped correctly.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
pgsql
Type Map($name->Struct(pgsql_action))Description PostgreSQL Action Config
parameters
Type Struct(action_parameters)Description Configuration Parameters Specific to the PostgreSQL Action
sql
Type StringDefault "insert into t_mqtt_msg(msgid, topic, qos, payload, arrived) values (${id}, ${topic}, ${qos}, ${payload}, TO_TIMESTAMP((${timestamp} :: bigint)/1000))"Description SQL Template
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
tdengine
Type Map($name->Struct(action_config))Description TDengine Action Config
parameters
Type Struct(action_parameters)Description TDengine action parameters
sql
Type StringDefault "insert into t_mqtt_msg(ts, msgid, mqtt_topic, qos, payload, arrived) values (${ts}, '${id}', '${topic}', ${qos}, '${payload}', ${timestamp})"Description SQL Template
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.undefined_vars_as_null
Type BooleanDefault falseDescription When writing to databases, treat undefined variables as NULL. When this option is enabled, if undefined variables (like ${var}) are used in templates, they will be replaced with "NULL" instead of the string "undefined". If this option is not enabled (default), the string "undefined" might be inserted. This option should always be
trueif possible; the default valuefalseis only to ensure backward compatibility.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
snowflake
Type Map($name->Struct(snowflake))Description Snowflake Action Config
parameters
Type OneOf(Struct(aggreg_parameters))Description Set of parameters for the action.
aggregation
Type Struct(aggregation)Description Set of parameters governing the aggregation process.
container
Type OneOf(Struct(container_csv))Default {type = csv}Description Settings governing the file format of an upload containing aggregated events.
column_order Type Array(String)Default []Description Event fields that will be ordered first as columns in the resulting CSV file.
Regardless of this setting, resulting CSV will contain all the fields of aggregated events, but all the columns not explicitly mentioned here will be ordered after the ones listed here in the lexicographical order.
time_interval
Type Duration(s)Default "1h"Description Amount of time events will be aggregated in a single file on each node before uploading.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_records
Type Integer(1..+inf)Default 1000000Description Number of records (events) allowed per each aggregated file. Each aggregated upload will contain no more than that number of events, but may contain less.
If event rate is high enough, there obviously may be more than one aggregated upload during the same time interval. These uploads will have different, but consecutive sequence numbers, which will be a part of Snowflake staged file name.
private_key
Type SecretDescription The private key configured for the Pipe User. This supports the input formats below:
- Plain key: Enter the private key contents in PEM format directly as a string value.
- File Path: Specify the path to a file that contains the private key. Ensure the path starts with
file://. The file path must be the same on all nodes in the cluster.
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.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "10ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
clickhouse
Type Map($name->Struct(clickhouse_action))Description ClickHouse Action Config
parameters
Type Struct(action_parameters)Description Action specific configs.
sql
Type StringDefault "INSERT INTO messages(data, arrived) VALUES ('${payload}', ${timestamp})"Description The template string can contain ${field} placeholders for message metadata and payload field. Make sure that the inserted values are formatted and escaped correctly. Prepared Statement is not supported.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.undefined_vars_as_null
Type BooleanDefault falseDescription When writing to databases, treat undefined variables as NULL. When this option is enabled, if undefined variables (like ${var}) are used in templates, they will be replaced with "NULL" instead of the string "undefined". If this option is not enabled (default), the string "undefined" might be inserted. This option should always be
trueif possible; the default valuefalseis only to ensure backward compatibility.batch_value_separator
Type StringDefault ", "Description The default value ',' works for the VALUES format. You can also use other separator if other format is specified. See INSERT INTO Statement.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
influxdb
Type Map($name->Struct(influxdb_action))Description InfluxDB Action Config
parameters
Type Struct(action_parameters)Description Additional parameters specific to this action type
write_syntax
Type StringDescription Conf of InfluxDB line protocol to write data points. It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point, and placeholder supported. See also InfluxDB 2.3 Line Protocol and InfluxDB 1.8 Line Protocol
TLDR:<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]Please note that a placeholder for an integer value must be annotated with a suffix
i. For example${payload.int_value}i.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
batch_time
Type DurationDefault "0ms"Description Maximum waiting interval when accumulating a batch at a low message rates for more efficient resource usage.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
confluent_producer
Type Map($name->Struct(actions))Description Confluent Actions Config
parameters
Aliases kafka Type Struct(producer_kafka_opts)Description Confluent producer configs.
message
Type Struct(kafka_message)Description Template for rendering a message.
key
Type StringDefault "${.clientid}"Description Template for rendering message key. If the template is rendered into a NULL value (i.e. there is no such data field in Rule Engine context) then
NULL(but not empty string) is used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.value
Type StringDefault "${.}"Description Template to render Confluent message value. If the template is rendered into a NULL value (i.e. there is no such data field in Rule Engine context) then Confluent's
NULL(but not empty string) is used.
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.
max_linger_time
Type DurationDefault "0ms"Description Maximum duration for a per-partition producer to wait for messages in order to collect a batch to buffer. The default value
0means no wait. For non-memory buffer mode, it's advised to configure at least5msfor less IOPS.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_linger_bytes
Type BytesizeDefault "10MB"Description Maximum number of bytes for a per-partition producer to wait for messages in order to collect a batch to buffer.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.max_batch_bytes
Type BytesizeDefault "896KB"Description Maximum bytes to collect in a Confluent message batch. Most of the Kafka brokers default to a limit of 1 MB batch size. EMQX's default value is less than 1 MB in order to compensate Kafka message encoding overheads (especially when each individual message is very small). When a single message is over the limit, it is still sent (as a single element batch).
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.partition_strategy
Type Enum(random,key_dispatch)Default randomDescription Partition strategy is to tell the producer how to dispatch messages to partitions.
random: Randomly pick a partition for each message.key_dispatch: Assigns messages to partitions based on a hash of the message key, ensuring consistent partition for messages with the same key.required_acks
Type Enum(all_isr,leader_only,none)Default all_isrDescription The acknowledgement criteria for the partition leader. It determines the level of confirmation required from partition replicas before sending an acknowledgement back to the producer.
all_isr: Require all in-sync replicas to acknowledge.leader_only: Require only the partition-leader's acknowledgement.none: No need for Kafka to acknowledge at all.kafka_headers
Type StringDescription Provide a placeholder for message headers
e.g.${pub_props}
Note that the value of the placeholder must be either an object:{"foo": "bar"}or an array of key-value pairs:[{"key": "foo", "value": "bar"}]
A string for${.path.to.var}style value interpolation, where the leading dot is optional, and${.}represents all values as an object.partition_count_refresh_interval
Type Duration(s)Default "60s"Description The time interval for Confluent producer to discover increased number of partitions. After the number of partitions is increased in Confluent, EMQX will start taking the discovered partitions into account when dispatching messages per
partition_strategy.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partitions_limit
Type OneOf(String("all_partitions"),Integer(1..+inf))Default all_partitionsDescription Limit the number of partitions to produce data for the given topic. The special value
all_partitionsis to utilize all partitions for the topic. Setting this to a value which is greater than the total number of partitions in has no effect.buffer
Type Struct(producer_buffer)Description Configure producer message buffer.
Tell Confluent producer how to buffer messages when EMQX has more messages to send than Confluent can keep up, or when Confluent is down.
mode
Type Enum(memory,disk,hybrid)Default memoryDescription Message buffer mode.
memory: Buffer all messages in memory. The messages will be lost in case of EMQX node restartdisk: Buffer all messages on disk. The messages on disk are able to survive EMQX node restart.hybrid: Buffer message in memory first, when up to certain limit (seesegment_bytesconfig for more information), then start offloading messages to disk, Likememorymode, the messages will be lost in case of EMQX node restart.per_partition_limit
Type BytesizeDefault "2GB"Description Number of bytes allowed to buffer for each partition. When this limit is exceeded, older messages will be discarded to make room for new messages to be buffered.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.segment_bytes
Type BytesizeDefault "10MB"Description Applicable when buffer mode is set to
diskorhybrid. This setting specifies the size of each buffer file stored on disk.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
sync_query_timeout
Type DurationDefault "5s"Description This parameter defines the timeout limit for synchronous queries. It applies only when the action query mode is configured to 'sync'.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
resource_opts
Type Struct(resource_opts)Default {}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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.
max_buffer_bytes
Aliases max_queue_bytes Type BytesizeDefault "256MB"Description Maximum number of bytes to buffer for each buffer worker.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.
sources
Type Struct(sources)kafka_consumer
Type Map($name->Struct(consumer_source))Description Kafka Consumer Source Config
parameters
Type Struct(source_parameters)Description Source configs.
max_wait_time
Type DurationDefault "1s"Description Maximum amount of time that is waited for the Kafka broker to send a fetch response.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_batch_bytes
Type BytesizeDefault "896KB"Description Set how many bytes to pull from Kafka in each fetch request. Messages are fetched in batches by the consumer, and if the first record batch in the first non-empty partition of the fetch is larger than this value, the record batch will still be returned to ensure that the consumer can make progress. As such, this is not an absolute maximum. Set
1for minimal latency.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.offset_commit_interval_seconds
Type Duration(s)Default "5s"Description Defines the time interval between two offset commit requests sent for each consumer group.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.key_encoding_mode
Type Enum(none,base64)Default noneDescription Defines how the key from the Kafka message is encoded before being forwarded via MQTT.
noneUses the key from the Kafka message unchanged. Note: in this case, the key must be a valid UTF-8 string.base64Uses base-64 encoding on the received key.value_encoding_mode
Type Enum(none,base64)Default noneDescription Defines how the value from the Kafka message is encoded before being forwarded via MQTT.
noneUses the value from the Kafka message unchanged. Note: in this case, the value must be a valid UTF-8 string.base64Uses base-64 encoding on the received value.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
rabbitmq
Type Map($name->Struct(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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
gcp_pubsub_consumer
Type Map($name->Struct(consumer_source))Description GCP PubSub Consumer Source Config
resource_opts
Type Struct(source_resource_opts)Default {}Description Resource options.
health_check_interval
Type DurationDefault "30s"Description Health check interval.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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_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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
retainer
Type Struct(retainer)msg_expiry_interval
Type DurationDefault "0s"Description Expired retained messages will not be delivered again, and a setting of 0 means that retained messages will never expire.
However, if the
Message-Expiry-Intervalproperty is specified in the MQTT message, the value of that property prevails.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.msg_expiry_interval_override
Type OneOf(String("disabled"),Duration)Default disabledDescription If set, this value will take precedence over any
Message-Expiry-Intervalproperty specified in retained MQTT messages, allowing messages to expire earlier if necessary. This override only applies to the garbage collection process: it does not affect the expiry time of messages being written nor that of already written messages while iterating over them. Therefore, messages that are candidate for garbage collection when overridden may still be visible when subscribing to retained topics.msg_clear_interval
Type DurationDefault "0s"Description The time interval for checking and clearing expired retained messages. This can prevent expired retained messages from being stored for a long time.
If
msg_clear_intervalis set to 0, that is, expired retained messages are not actively checked regularly, EMQX will only check and delete expired retained messages when preparing for delivery.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.max_payload_size
Type BytesizeDefault "1MB"Description The maximum size of retained messages allowed to be stored. EMQX will refuse to store retained messages larger than this size and output an Error log with the keyword 'retain_failed_for_payload_size_exceeded_limit'.
0 means unlimited retained message size.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order
Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
default_password
Type StringDefault publicDescription The password used to initialize a database record for
adminuser. NOTE: Changing the default password after it has been initialized (boot up for the fist time) has no effect. Once initialized, the default passwordpublicmust be changed from dashboard or CLI as soon as possible.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.sso
Type Struct(sso)ldap
Type Struct(ldap)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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.filter
Type StringDefault "(& (objectClass=person) (uid=${username}))"Description The filter for matching users in LDAP is by default
(&(objectClass=person)(uid=${username})). For Active Directory, it should be set to(&(objectClass=user)(sAMAccountName=${username}))by default. Please refer to LDAP Filters for more details.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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
oidc
Type Struct(oidc)secret
Type SecretDescription The client secret.
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.session_expiry
Type Duration(s)Default "30s"Description The valid time span for an OIDC
state, the default is30s, if the code response returned by the authorization server exceeds this time span, it will be treated as invalid.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
gateway
Type Struct(gateway)coap
Type Struct(coap)heartbeat
Type Duration(s)Default "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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order
Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
gbt32960
Type Struct(gbt32960)mountpoint
Type StringDefault "gbt32960/${clientid}/"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
retry_interval
Type DurationDefault "8s"Description Re-send time interval
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
jt808
Type Struct(jt808)mountpoint
Type StringDefault "jt808/${clientid}/"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
retry_interval
Type DurationDefault "8s"Description Re-send time interval
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
ocpp
Type Struct(ocpp)mountpoint
Type StringDefault "ocpp/"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
default_heartbeat_interval
Type Duration(s)Default "60s"Description The default Heartbeat time interval
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.message_format_checking
Type OneOf(String("all"),String("upstream_only"),String("dnstream_only"),String("disable"))Default disableDescription Whether to enable message format legality checking. EMQX checks the message format of the upload stream and download stream against the format defined in json-schema. When the check fails, emqx will reply with a corresponding answer message.
The checking strategy can be one of the following values:
all: check all messagesupstream_only: check upload stream messages onlydnstream_only: check download stream messages onlydisable: don't check any messages
listeners
Type Struct(ws_listeners)ws
Type Map($name->Struct(ws_listener))Description Websocket listener.
tcp_options
Type Struct(tcp_opts)Description Setting the TCP socket options.
send_timeout Type DurationDefault "15s"Description The maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]websocket
Type Struct(websocket)idle_timeout Type DurationDefault "7200s"Description The timeout for waiting for the WebSocket upgrade request. After the timeout, the connection will be closed.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
wss
Type Map($name->Struct(wss_listener))Description Websocket over TLS listener.
tcp_options
Type Struct(tcp_opts)Description Setting the TCP socket options.
send_timeout Type DurationDefault "15s"Description The maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]ssl_options
Type Struct(listener_wss_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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
websocket
Type Struct(websocket)idle_timeout Type DurationDefault "7200s"Description The timeout for waiting for the WebSocket upgrade request. After the timeout, the connection will be closed.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]
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 maximum time a process is suspended for sending data to a busy socket. After the timeout, the TCP connection and the process will be closed.
The process is unsuspended only when the socket is unbusy, that is, the data accumulated in the Erlang internal buffer drops from the high watermark (specified by
high_watermark) to the low watermark (default 4 KB).Therefore,
(high_watermark - 4 KB) / send_timeoutmust be a suitable message outflow speed, otherwise the suspended process will never be able to recover before the timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.high_watermark Type BytesizeDefault "1MB"Description When EMQX tries to send more data than the OS has allocated for the socket's send buffer, the remaining data will be temporarily stored in Erlang's internal buffer and then sent in the background.
If the amount of data queued in the internal buffer exceeds
high_watermark, the corresponding socket will be marked as busy.The process sending data to this busy socket will be suspended until the socket is no longer busy, or the suspension time exceeds
send_timeout.The socket will only be unbusy when the data in the internal buffer is below the low watermark.
While the process is suspended, the message queue of the process may accumulate, see
max_mailbox_lenfor details.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.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
Type BooleanDefault falseDescription If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header. EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.
For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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
access_rules
Type Array(String)Default []Description An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first. The format is
allow | deny <address> | <CIDR> | all.For example:
[\"deny 192.168.1.1\", \"allow 192.168.1.0/24\", \"deny, all\"]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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"honor_cipher_order Type BooleanDefault trueDescription An important security setting. If this setting is enabled, the server will prioritize the cipher suites it prefers most from the list of cipher suites supported by the client, thus ignoring the client's preferences.
The server's cipher suites are specified by
ciphers, with preference decreasing from left to right.It is often better to use the server's preferences, as it is more likely that the server will be configured correctly.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.
For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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 Client ID and topic of the consumer whose message latency is greater than this threshold will be recorded in the slow subscription list.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.expire_interval
Type DurationDefault "300s"Description The expiration time of the slow subscription record, if the record is not updated within the expiration time, then the record will be deleted.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.stats_type
Type Enum(whole,internal,response)Default wholeDescription Message latency calculation method:
whole: The time from when the message arrives at the EMQX (the EMQX gets the message from the receive-buffer) until the message completes delivery.internal: The time from when the message arrives at the EMQX (the EMQX gets the message from the receive-buffer) to when the message begins to be delivered (the EMQX attempts to write the message to the send-buffer).response: The time from the start of message delivery to the completion.
Note: The completion delivery time refers to the time when QoS 1 and 2 messages complete the MQTT message response process, i.e., the time when QoS 1 message receives the PUBACK packet and QoS 2 message receives the PUBCOMP packet. Since there is no response packet for QoS 0 message, the completion delivery time of the QoS 0 message will be replaced by the time when the message starts to be delivered. Therefore, when using the
responsemethod to calculate the latency, the latency of a QoS 0 message will always be equal to 0.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.filter
Type Struct(trace_filter)Description Open Telemetry Trace Filter configuration
trace_mode
Type Enum(legacy,e2e)Default legacyDescription OpenTelemetry tracing mode.
legacy: follow the old tracing method, only trace message publishing and delivery. Span names will be compatible to versions before 5.9.e2e: end-to-end tracing mode. All client behaviors will be traced:- connect and disconnect
- subscribe and unsubscribe
- messaging events such as
PUBLISH,PUBACK,PUBRELetc. When enabled (for each type of events), there will be a background tracing for all clients at the configured sample ratio. From the dashboard, one can also add additional trace whitelist on top of the background tracing at full volume for a list of clients or topics. See dashboard or API documents for more details. More control and sampling options can be provided ine2e_tracing_options
trace_all
Type BooleanDefault falseDescription If enabled, all published messages are traced, a new trace ID is generated if it can't be extracted from the message. Otherwise, only messages published with trace context are traced. Disabled by default. Note: this config only takes effect when
trace_modeis set tolegacy.e2e_tracing_options
Type Struct(e2e_tracing_options)Default {}Description End-to-end tracing options
msg_trace_level
Type Integer(0..2)Default 0Description Trace level for all message exchanges during the message publishing process.
0: Basic events during message publish will be recorded as Spans. Including 'client.connect', 'client.authz', 'message.route', 'message.forward', 'message.handle_forward', 'broker.publish'.1: In addition to basic events. The events 'broker.puback', 'client.puback', 'broker.pubrec', 'client.pubrec' will be recorded as Spans. That is, the first response packet in the QoS1 or QoS2 message interaction.2: In addition to level 1. The events 'broker.pubrel', 'client.pubrel', 'broker.pubcomp', 'client.pubcomp' will be recorded as Spans.
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.password
Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after
Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain
Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage
Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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.
license
Type Struct(key_license)Description Defines the EMQX Enterprise license.
EMQX Enterprise is initially provided with a default trial license. This license, issued in April 2024, is valid for a period of 5 years. It supports up to 25 concurrent connections, catering to early-stage development and testing needs.
For deploying EMQX Enterprise in a production environment, a different license is required. You can apply for a production license by visiting https://www.emqx.com/apply-licenses/emqx?version=5
key
Type OneOf(String("default"),String)Default defaultDescription This configuration parameter is designated for the license key and supports below input formats:
- Direct Key: Enter the secret key directly as a string value.
- File Path: Specify the path to a file that contains the secret key. Ensure the path starts with
file://. - "default": Use string value
"default"to apply the default trial license.
Note: An invalid license key or an incorrect file path may prevent EMQX from starting successfully. If a file path is used, EMQX attempts to reload the license key from the file every 2 minutes. Any failure in reloading the license file will be recorded as an error level log message, and EMQX continues to apply the license loaded previously.
schema_registry
Type Struct(schema_registry)external
Type Map($name->OneOf(Struct(confluent_schema_registry)))Default {}Description Confluent External Schema Registry configuration.
auth
Type OneOf(String("none"),Struct(confluent_schema_registry_auth_basic))Default noneDescription Authentication options for accessing external registry.
password
Type SecretDescription Password for basic authentication method.
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.
file_transfer
Type Struct(file_transfer)enable
Type BooleanDefault falseDescription Enable the File Transfer feature.
Enabling File Transfer implies reserving special MQTT topics in order to serve the protocol.
This toggle also affects the availability of the File Transfer REST API and storage-dependent background activities (e.g. garbage collection).init_timeout
Type DurationDefault "10s"Description Timeout for EMQX to initialize the file transfer.
After reaching the timeout (e.g. due to system is overloaded), the PUBACK message forinitwill contain error code (0x80).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.store_segment_timeout
Type DurationDefault "5m"Description Timeout for storing a file segment.
After reaching the timeout (e.g. due to system overloaded), the PUBACK message will contain error code (0x80).
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.assemble_timeout
Type DurationDefault "5m"Description Timeout for assembling and exporting file segments into a final file.
After reaching the timeout (e.g. due to system is overloaded), the PUBACK message forfinwill contain error code (0x80)
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.storage
Type Struct(storage_backend)Default {local {}}Description Storage settings for file transfer.
local
Type Struct(local_storage)Description Local file system backend to store uploaded fragments and temporary data.
segments
Type Struct(local_storage_segments)Default {gc {}}Description Settings for local segments storage, which include uploaded transfer fragments and temporary data.
gc
Type Struct(local_storage_segments_gc)Description Garbage collection settings for the intermediate and temporary files in the local file system.
interval Type DurationDefault "1h"Description Interval of periodic garbage collection.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.maximum_segments_ttl Type Duration(s)Default "24h"Description Maximum TTL of a segment kept in the local file system.
This is a hard limit: no segment will outlive this TTL, even if some file transfer specifies a TTL more than that.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.minimum_segments_ttl Type Duration(s)Default "5m"Description Minimum TTL of a segment kept in the local file system.
This is a hard limit: no segment will be garbage collected before reaching this TTL, even if some file transfer specifies a TTL less than that.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
exporter
Type Struct(local_storage_exporter_backend)Default {local {}}Description Exporter for the local file system storage backend.
Exporter defines where and how fully transferred and assembled files are stored.s3
Type Struct(s3_exporter)Description Exporter to the S3 API compatible object storage.
secret_access_key Type SecretDescription The secret access key of the S3 bucket.
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.transport_options Type Struct(transport_options)Description Options for the HTTP transport layer used by the S3 client.
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. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). 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.password Type SecretDescription String containing the user's password. Only used if the private key file is password-protected.
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.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 Whether to reject TLS renegotiation attempts that are not compliant with RFC 5746.
By default,
secure_renegotiateis set totrue, which forces secure renegotiation. If set tofalse, secure renegotiation will still be used, but will fall back to insecure renegotiation if the peer does not support RFC 5746, which increases the risk of a MitM attack.Has no effect when TLS version is configured (or negotiated) to 1.3.
hibernate_after Type DurationDefault "5s"Description Specifies the amount of time that an SSL process will hibernate after being idle, thus reducing its memory footprint.
The hibernating process will be woken up when a new message arrives. Hibernating and waking up too often can cause CPU utilization to increase, as they both perform garbage collection on the process.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.partial_chain Type Enum(true,false,two_cacerts_from_cacertfile,cacert_from_cacertfile)Description Enable or disable peer verification with partial_chain. When local verifies a peer certificate during the x509 path validation process, it constructs a certificate chain that starts with the peer certificate and ends with a trust anchor. By default, if it is set to
false, the trust anchor is the Root CA, and the certificate chain must be complete. However, if the setting is set totrueorcacert_from_cacertfile, the last certificate incacertfilewill be used as the trust anchor certificate (intermediate CA). This creates a partial chain in the path validation. Alternatively, if it is configured withtwo_cacerts_from_cacertfile, one of the last two certificates incacertfilewill be used as the trust anchor certificate, forming a partial chain. This option is particularly useful for intermediate CA certificate rotation. However, please note that it incurs some additional overhead, so it should only be used for certificate rotation purposes.verify_peer_ext_key_usage Type StringDescription Verify extended key usage in peer's certificate For additional peer certificate validation, the value defined here must present in the 'Extended Key Usage' of peer certificate defined in rfc5280.
Allowed values are
clientAuthserverAuthcodeSigningemailProtectiontimeStampingocspSigning- raw OID, for example: "OID:1.3.6.1.5.5.7.3.2" means
id-pk 2which is equivalent toclientAuth
Comma-separated string is also supported for validating more than one key usages.
For example,
"serverAuth,OID:1.3.6.1.5.5.7.3.2"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 DurationDescription HTTP request timeout.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.
min_part_size Type BytesizeDefault "5mb"Description The minimum part size for multipart uploads.
Uploaded data will be accumulated in memory until this size is reached.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.max_part_size Type BytesizeDefault "5gb"Description The maximum part size for multipart uploads.
S3 uploader won't try to upload parts larger than this size.
A string that represents a number of bytes, for example:10B,640kb,4MB,1GB. Units are binary standardized, i.e., 1MB equals 1024KB. units are not case sensitive, i.e., 1kb equals 1KB.url_expire_time Type Duration(s)Default "1h"Description The time in seconds for which the signed URLs to the S3 objects are valid.
A string that represents a time duration, for example:10s,2.5m,1h30m,1W2D, or2345ms, which is the smallest unit. Each configuration item has its own minimum precision. The part of the setting value that exceeds the precision will be ignored.For example, if a configuration item of type
Duration(s)is set to1200ms, the final effective value will be1sinstead of1.2s.Durationis equivalent toDuration(ms). The unit part is case-insensitive.