MQTT over QUIC Bridge Configuration Reference

This page explains how to configure MQTT over QUIC bridges in EMQX Edge. It describes the supported configuration approaches, explains all available configuration options, including both common MQTT bridge parameters and QUIC-specific settings, and provides example configurations for standalone MQTT over QUIC bridges and QUIC/TCP hybrid bridging.

Basic Configuration

MQTT over QUIC bridges can be configured via the EMQX Edge Dashboard (recommended) or by editing the configuration file directly. Regardless of the method used, all configurations are ultimately persisted in HOCON format and follow the same configuration model.

Configure via Dashboard (Recommended)

The EMQX Edge Dashboard provides a guided, UI-based workflow for creating and managing MQTT over QUIC bridges. It is the recommended way to get started, especially for initial setup and validation.

For step-by-step instructions on creating an MQTT over QUIC bridge using the Dashboard, see Quick Start: Create an MQTT over QUIC Bridge.

The Dashboard fields map directly to the configuration options described in this reference, making it easy to transition from UI-based configuration to file-based management if needed.

Configure via Configuration File

MQTT over QUIC bridges are configured in the nanomq.conf file using HOCON syntax. A QUIC-based bridge is defined in the same way as other MQTT bridges, with the main difference being the use of a QUIC-specific server URL and optional QUIC-related parameters.

To configure an MQTT over QUIC bridge:

1. Define a bridges.mqtt.<name> section to create a bridge instance.
2. Set the server parameter to a mqtt-quic://host:port URL.
3. Configure standard MQTT bridge parameters such as protocol version, authentication, and topic forwarding rules.
4. Optionally configure QUIC-specific options to tune connection behavior and performance.

The following sections describe all available configuration options in detail.

Configuration Options

The following sections describe the available configuration options for MQTT over QUIC bridges, including both common MQTT bridge parameters and QUIC-specific settings.

Basic MQTT Bridge Parameters

These parameters are common to TCP, TLS, and QUIC bridges. Only the most relevant options are listed below.

Parameter	Description	Notes / Values
bridges.mqtt.<name>.server	Target MQTT broker URL for the bridge connection.	Examples: mqtt-tcp://127.0.0.1:1883 (MQTT over TCP) tls+mqtt-tcp://127.0.0.1:8883 (MQTT over TLS) mqtt-quic://54.75.171.11:14567 (MQTT over QUIC)
bridges.mqtt.<name>.proto_ver	MQTT protocol version used by the bridge client.	5 = MQTT v5 4 = MQTT v3.1.1
bridges.mqtt.<name>.clientid	Client ID used by the bridge connection.	If not specified, a random Client ID is generated automatically.
bridges.mqtt.<name>.keepalive	MQTT protocol-level keepalive interval.	This is different from the QUIC-level quic_keepalive.
bridges.mqtt.<name>.username	Username for authenticating with the remote broker.	Used together with password.
bridges.mqtt.<name>.password	Password for authenticating with the remote broker.	-
bridges.mqtt.<name>.forwards	Rules defining which local topics are forwarded to the remote broker.	Each rule may include: local_topic: Local topic filter (supports wildcards) remote_topic: Remote topic used when forwarding Optional qos, retain, prefix, suffix, etc.
bridges.mqtt.<name>.subscription	Rules defining which remote topics are subscribed to and republished locally.	Each rule may include: remote_topic: Topics subscribed to on the remote broker local_topic: Local topic used when republishing qos QoS of this topic Optional: retain_as_published, retain_handling

When the server parameter uses the mqtt-quic:// scheme, all MQTT bridge semantics listed above operate over QUIC.

QUIC-Specific Options

The following options are defined under bridges.mqtt.<name> and apply only when the server parameter uses the mqtt-quic:// scheme.

Timeouts and Keepalive

Parameter	Type	Description	Default / Notes
quic_keepalive	Duration	Interval for sending QUIC-level keepalive probes.	Default: 120s
quic_idle_timeout	Duration	Maximum idle time before the QUIC connection is closed.	Default: 120s Set to 0 to disable the idle timeout.
quic_discon_timeout	Duration	Maximum time to wait for an ACK before declaring the path dead and disconnecting.	Default: 20s
quic_handshake_timeout	Duration	Maximum time allowed for completing the QUIC handshake.	Default: 20s

Congestion and RTT-Related Options

Parameter	Type	Description	Default
quic_send_idle_timeout	Duration	Resets congestion control after the connection has been idle for the specified period, allowing the network to be re-estimated.	2s
quic_initial_rtt_ms	Duration (ms)	Initial RTT estimate used before real RTT measurements are available.	800ms
quic_max_ack_delay_ms	Duration (ms)	Maximum delay between receiving data and sending an ACK.	100ms

Multiplexing and QoS Priority

Parameter	Type	Description	Default
quic_multi_stream	Boolean	Enables QUIC multi-stream mode. true: Map different topics or subscriptions to different streams. false: Use a single stream for all traffic.	false
quic_qos_priority	Boolean	Prioritizes QoS 1/2 messages over QoS 0 traffic when the link or buffers are congested.	true

0-RTT Fast Reconnect

Parameter	Type	Description	Default
quic_0rtt	Boolean	Enables QUIC 0-RTT, allowing application data to be sent during reconnection without waiting for a full handshake.	true

Hybrid Bridging (QUIC + TCP)

Hybrid bridging allows EMQX Edge to combine the performance benefits of QUIC with the robustness of traditional TLS/TCP connections. In this mode, multiple candidate remote servers can be configured, enabling EMQX Edge to prefer QUIC while automatically falling back to TLS/TCP when QUIC is unavailable or unstable.

Hybrid Bridging Options

Parameter	Type	Description
hybrid_bridging	Boolean	Enables or disables hybrid bridging mode. When enabled, EMQX Edge selects an available server from the configured candidate list.
hybrid_servers	Array of strings	Defines the list of candidate remote broker URLs. The order of the list determines priority. QUIC URLs are typically listed first, followed by TCP or TLS URLs as fallbacks.

In production environments, a "QUIC-first with TLS/TCP fallback" strategy is recommended. This approach allows operators to gradually adopt QUIC while maintaining connectivity and reliability if QUIC is not supported or experiences transient failures.

Configuration Examples

The following examples illustrate common MQTT over QUIC bridge configurations in EMQX Edge.

MQTT over QUIC Bridge

This example shows how to configure a standalone MQTT bridge that uses QUIC as the transport protocol to connect EMQX Edge to a remote broker.

bridges.mqtt.emqx_quic {
  server    = "mqtt-quic://your_server_address:14567"
  proto_ver = 4
  clientid  = "bridge_client"
  username  = "username"
  password  = "password"
  keepalive = "60s"

  # QUIC-specific options
  quic_keepalive         = "120s"
  quic_idle_timeout      = "120s"
  quic_discon_timeout    = "20s"
  quic_handshake_timeout = "20s"
  quic_send_idle_timeout = "2s"
  quic_initial_rtt_ms    = "800ms"
  quic_max_ack_delay_ms  = "100ms"
  quic_multi_stream      = false
  quic_qos_priority      = true
  quic_0rtt              = true
  hybrid_bridging        = false

  forwards = [
    { remote_topic = "fwd/topic1", local_topic = "topic1", qos = 1 },
    { remote_topic = "fwd/topic2", local_topic = "topic2", qos = 2 }
  ]

  subscription = [
    { remote_topic = "cmd/topic1", local_topic = "topic3", qos = 1 },
    { remote_topic = "cmd/topic2", local_topic = "topic4", qos = 2 }
  ]

  max_parallel_processes = 2
  max_send_queue_len     = 32
  max_recv_queue_len     = 128
}

QUIC/TCP Hybrid Bridge

This example demonstrates a hybrid bridge configuration that prefers QUIC for the remote connection and automatically falls back to MQTT over TCP if QUIC is unavailable.

bridges.mqtt.emqx_hybrid {
  server    = "mqtt-quic://your_server_address:14567"

  # Hybrid bridging: prefer QUIC, fall back to TCP
  hybrid_bridging = true
  hybrid_servers  = [
    "mqtt-tcp://your_server_address:1883"
  ]

  quic_keepalive      = "120s"
  quic_idle_timeout   = "120s"
  quic_discon_timeout = "20s"
  quic_0rtt           = true
  quic_qos_priority   = true
}