# Quick Start: Create an MQTT over QUIC Bridge
This guide demonstrates how to create an MQTT over QUIC (Quick UDP Internet Connections) bridge using a [free public MQTT broker](https://www.emqx.com/en/mqtt/public-mqtt5-broker). The bridge forwards MQTT messages between EMQX Edge and a remote broker over QUIC, providing built-in TLS 1.3 encryption, faster connection establishment, and improved performance on unreliable networks.
You can configure the bridge via the Dashboard or using the configuration file.
## Create an MQTT over QUIC Bridge via the Dashboard
Follow the steps below to configure an MQTT over QUIC bridge using the EMQX Edge Dashboard.
### Step 1: Open the Bridge Creation Wizard
1. In the Dashboard, navigate to **Bridges**.
2. On the **Bridges** page, click **Add** in the upper-right corner.
3. The bridge configuration form appears with the following tabs:
- **Connection**
- **Forwards**
- **Subscriptions**
- **Security**
- **Advanced**
### Step 2: Set Up the Connection
The **Connection** tab defines how EMQX Edge connects to the remote MQTT broker over QUIC.
Configure the following fields:
- **Name**: Specify a unique name for the bridge, for example, `emqx_quic`.
- **Server**: The remote broker address. EMQX Edge uses a decoupled protocol and transport design, where the URL prefix specifies the transport layer.
Supported transport prefixes include:
- `mqtt-tcp`
- `tls+mqtt-tcp`
- `mqtt-quic`
For this example, use: `mqtt-quic://broker.emqx.io:14567`.
- **Protocol version**: MQTT protocol version:
- `5` for MQTT 5.0
- `4` for MQTT 3.1.1
Example: `4`
- **Client ID**: Unique identifier for the bridge connection, for example, `bridge_quic_client`. If left empty, EMQX Edge automatically generates one.
- **Keepalive**: MQTT protocol-level keepalive interval in seconds. Default is `60's.
- **Username / Password**: Credentials for authenticating with the remote broker. In this example, set to `username/password`.
- **Clean start**: When enabled, the bridge always starts a new session. When disabled, it attempts to resume a previous session if supported by the broker. Default is `false`.
#### QUIC Configuration (Optional)
The **QUIC Configuration** section exposes QUIC transport-level parameters such as:
- Keep Alive Interval
- Idle Timeout
- Handshake Timeout
- Advanced Settings:
- Disconnect Timeout
- Send Idle Timeout
- Initial RTT
- Max ACK Delay
- QoS Priority
- 0-RTT Resumption
These options are optional. Default values are suitable for most use cases.
For detailed explanations of each QUIC option and tuning guidance, see [MQTT over QUIC Bridge Configuration Reference](./quic-config).
### Step 3: Define Forwarding Rules
The **Forwards** tab defines how messages published locally in EMQX Edge are forwarded to the remote MQTT broker.
To create a rule for message forwarding:
1. Click **Add**.
2. Configure the following fields:
- **Local topic**: Topic on your local EMQX Edge instance
- **Remote topic**: Target topic on the remote broker
- **QoS**: Select `0`, `1`, or `2`
**Example Forward Rule**:
| Local Topic | Remote Topic | QoS |
| ----------- | ------------ | ---- |
| topic1 | fwd/topic1 | 1 |
You can edit or delete rules later using the action buttons.
### Step 4: Define Subscription Rules
The **Subscriptions** tab defines how EMQX Edge subscribes to topics from the remote broker and republishes incoming messages locally.
To create a subscription rule:
1. Click **Add**.
2. Configure the following fields:
- **Remote topic**: Topic on the remote broker
- **Local topic**: The corresponding topic on EMQX Edge
- **QoS**: Select `0`, `1`, or `2`
**Example Subscription Rule:**
| Remote Topic | Local Topic | QoS |
| ------------ | ----------- | ---- |
| cmd/topic3 | topic3 | 1 |
You can edit or delete each rule later using the action buttons.
### Step 5: Security and Advanced Settings
#### Security
For MQTT over QUIC, unlike MQTT over TLS/TCP, where TLS operates as a separate layer above TCP, QUIC incorporates TLS 1.3 natively and encrypts nearly all packet contents, including control frames.
The **Security** tab allows you to set **TLS** configurations to establish a secure, encrypted QUIC connection to your self-signed remote broker:
- **Key Password**: Password used to unlock your private key file.
- **Key**: Path to your private key file (e.g., `/etc/certs/key.pem`).
- **Cert**: Path to your certificate file (e.g., `/etc/certs/cert.pem`).
- **Cacert**: Path to the certificate authority file (e.g., `/etc/certs/cacert.pem`).
- **Verify Peer**: When enabled, the client will verify the server’s certificate for authenticity.
- **Fail if No Peer Cert**: When enabled, the connection fails if the server doesn't provide a certificate.
In this example, `mqtt-quic://broker.emqx.io:14567` doesn't require custom certificates. So left it empty.
#### Advanced
The **Advanced** tab provides general bridge-level options:
- **Max parallel processes**: Number of concurrent bridge processes. Default: `2`. Increase this value to improve throughput if needed.
### Step 6: Save and Apply the Bridge Configuration
1. Click **Save** to persist the bridge configuration.
2. After clicking **Save**, a prompt is displayed indicating that the bridge configuration will take effect after restarting EMQX Edge. Click **Confirm** to close the prompt.
Once EMQX Edge restarts, the new bridge will appear in the **Bridges** list. You can toggle the switch in the **Action** column to enable or disable the bridge. When disabled, the bridge will not connect or exchange data, and no metrics will be shown on the **Bridges** page.
## Create an MQTT over QUIC Bridge via Configuration File
If you prefer file-based configuration, you can define the bridge in `nanomq.conf` or via **Settings** -> **All configurations** in the Dashboard.
### Option 1: Add Configuration via the Dashboard (`All configurations`)
1. Navigate to **Settings** in the left-hand menu.
2. Click the **All configurations** tab.
3. Define the bridge configuration settings by adding the following configuration snippet into the editor:
```hocon
bridges.mqtt.emqx_quic {
server = "mqtt-quic://broker.emqx.io:14567"
proto_ver = 4
clientid = "bridge_quic_client"
username = "username"
password = "password"
keepalive = 60s
clean_start = false
forwards = [
{
remote_topic = "fwd/topic1"
local_topic = "topic1"
qos = 1
}
]
subscription = [
{
remote_topic = "cmd/topic3"
local_topic = "topic3"
qos = 1
}
]
max_parallel_processes = 2
max_send_queue_len = 32
max_recv_queue_len = 128
}
```
4. After saving the configuration, restart EMQX Edge.
> For a complete list of available options (including QUIC-specific tuning and hybrid bridging), see [MQTT over QUIC Bridge Configuration Reference](./quic-config).
### Option 2: Edit the `nanomq.conf` File
1. Open the configuration file `nanomq.conf`.
2. Define the bridge configuration settings by adding the following HOCON snippet to the configuration file:
```
bridges.mqtt.emqx_quic {
server = "mqtt-quic://broker.emqx.io:14567"
proto_ver = 4
clientid = "bridge_quic_client"
username = "username"
password = "password"
keepalive = 60s
clean_start = false
forwards = [
{
remote_topic = "fwd/topic1"
local_topic = "topic1"
qos = 1
}
]
subscription = [
{
remote_topic = "cmd/topic3"
local_topic = "topic3"
qos = 1
}
]
max_parallel_processes = 2
max_send_queue_len = 32
max_recv_queue_len = 128
}
```
#### Start EMQX Edge with the Bridge Configuration
Run the following command to start EMQX Edge with your local configuration file:
```bash
emqx-edge start --conf /path/to/your/nanomq.conf --license /path/to/your/nanomq.lic
```
Replace `/path/to/your/nanomq.conf` with the actual path to your `nanomq.conf` file on your local machine.
For a complete list of configuration options, refer to the [MQTT over QUIC Bridge Configuration Reference](./quic-config). The settings will take effect after EMQX Edge is restarted.
::: tip
To view more log data during runtime, you can set the log level `log.level` in the configuration file.
:::
## Test the MQTT over QUIC Bridge
This section demonstrates how to use [MQTTX](https://mqttx.app/) to simulate clients and test the data bridge between EMQX Edge and the public MQTT broker. You will create two connections, one to EMQX Edge and another to the remote MQTT broker, to verify the bidirectional message forwarding.
### Connect a Client to EMQX Edge
Create a client named `NanoMQTest`, connecting to `localhost:1883`.
### Connect a Client to the Remote MQTT Broker
Create another client named `MQTTbridge`, connecting to `broker.emqx.io:1883`.
### Test Message Forwarding from EMQX Edge to Remote Broker
1. On the `MQTTbridge` client, subscribe to the topic `fwd/#`.
2. On the `NanoMQTest` client, publish a message to `topic1`, such as `Hello from NanoMQ`.
3. Confirm that the message appears on the `MQTTbridge` client, indicating successful forwarding.
### Test Message Subscription from Remote Broker to EMQX Edge
1. On the `NanoMQTest` client, subscribe to the topic `topic3`.
2. On the `MQTTbridge` client, publish a message to `cmd/topic3`, such as `Hello from broker.emqx.io`.
3. Verify that the message is received by the `NanoMQTest` client, confirming successful subscription.
### View Bridge Status and Metrics
After testing, you can monitor the bridge connection status and message metrics on the **Bridges** page in the Dashboard.
