How to Migrate Mosquitto to a Cloud MQTT Broker Without Downtime

When you migrate Mosquitto to cloud MQTT, the risky part is not the new broker but the moment devices switch over. This tutorial gives you a zero-downtime runbook: inventory what runs on your Mosquitto today, map credentials to the cloud broker, run both brokers side by side with a Mosquitto bridge, move clients in waves and decommission with a rollback plan ready. The examples use ConnectMQ as the destination, but the method works with any standards-compliant broker.

Why Teams Migrate from Mosquitto

Mosquitto is an excellent, lightweight broker, and it remains the right choice for many edge and lab deployments. Teams usually move the central broker to the cloud for operational reasons rather than technical shortcomings: certificate renewals, OS patching, backups, monitoring and on-call all land on someone who has other work. Remote devices also need a reachable endpoint, which means firewall rules and public exposure for a server you maintain yourself. If you are still deciding, compare the trade-offs in self-hosted vs managed MQTT broker and Mosquitto cloud alternative first.

Step 1: Inventory Clients, Topics and Features

You cannot migrate what you have not listed. Collect four things from the current broker.

Configuration. Read mosquitto.conf and any files in conf.d. Note listeners and ports, allow_anonymous, password_file, acl_file, persistence settings, max_inflight_messages, message size limits and existing bridges.

Clients. Mosquitto logs every connection with its client ID. Extract the unique IDs and source addresses from the log:

grep "New client connected" /var/log/mosquitto/mosquitto.log \
  | sed -E 's/.*from ([0-9a-fA-F.:]+):[0-9]+ as ([^ ]+).*/\2 \1/' \
  | sort -u > clients.txt
wc -l clients.txt

Topics. Subscribe to everything for a representative period and record unique topic names, including retained ones:

timeout 600 mosquitto_sub -h localhost -p 1883 -u admin -P 'ADMIN_PASSWORD' \
  -i inventory-$RANDOM -t '#' -F '%t %r' | sort -u > topics.txt

The %r field prints 1 for retained messages, which you will need to re-create on the new broker.

Feature usage. Check whether clients use MQTT 5, QoS 2, persistent sessions, large payloads, wildcard subscriptions or per-topic ACLs. Each one becomes a requirement for the destination.

Step 2: Map Features and Credentials

Compare your inventory with the destination broker before touching any device:

Two rows deserve attention. First, client IDs: on Mosquitto any client can usually pick any ID, while ConnectMQ binds each client ID to its issued credentials. Plan one credential set per device or service, and update firmware or configuration so each device uses its issued client ID. Second, ACLs: if your Mosquitto setup relies on fine-grained topic ACLs to separate untrusted parties, redesign that boundary with separate brokers or a backend that mediates access, before migrating.

Then create the destination: sign up at app.connectmq.com, choose a plan sized to your peak connection count, create a broker and issue credentials for the bridge and for the first wave of clients.

Step 3: Dual-Run with a Mosquitto Bridge

The bridge is what makes a zero-downtime migration possible. Mosquitto connects to the cloud broker as a normal MQTT client and forwards selected topics in each direction, so devices on either broker see the same data during the transition. Add a file such as /etc/mosquitto/conf.d/bridge-connectmq.conf:

connection connectmq
address broker.connectmq.com:8883
bridge_protocol_version mqttv311
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
bridge_capath /etc/ssl/certs
bridge_insecure false
try_private false
notifications false
cleansession true
restart_timeout 5 60

# Telemetry produced by local devices goes up to the cloud
topic factory1/+/+/telemetry out 1
topic factory1/+/+/status out 1
# Commands issued by cloud-side applications come down to local devices
topic factory1/+/+/cmd in 1

Restart Mosquitto with sudo systemctl restart mosquitto and check the log for a successful bridge connection. A few settings matter:

• try_private false: the private bridge flag is a Mosquitto-specific extension; disable it when the remote is a different broker.
• notifications false: stops Mosquitto from publishing bridge state topics to the remote, which you do not need there.
• Directional topics: use out and in instead of both wherever possible. Bidirectional bridging of the same topics between two brokers can create message loops.
• restart_timeout: backs off reconnection attempts if the cloud side is briefly unreachable.

Verify the bridge by subscribing on the cloud side with your own credentials, or by watching the live topic explorer in the portal while a local device publishes.

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
  -t 'factory1/#' -v

Use a different credential set from the bridge here, because each client ID can hold only one connection.

Step 4: Move Clients in Waves

With the bridge running, every client can move independently. Move consumers first, then producers:

1. Backend consumers (databases, Node-RED, dashboards): point them at the cloud broker. Thanks to the bridge they keep receiving local telemetry.
2. A pilot group of devices: a handful of devices from different sites and firmware versions. Change host, port 8883, TLS and credentials, and watch them for a few days.
3. Remaining devices in batches: by site or by product line, with a checkpoint after each batch.
4. Command producers: once devices are on the cloud broker, move the applications that send commands.

For each batch, confirm connection state on $SYS/broker/connection/{clientId}/state, check that expected topics appear in the explorer, and recreate any retained messages your inventory flagged. Because ConnectMQ does not guarantee retained state across restarts, have devices republish their retained status and configuration whenever they connect, which is a good practice on any broker.

Watch your plan's limits during the waves. If a wave pushes connections past the quota, MQTT 5 clients receive reason code 0x97; 3.1.1 clients are refused. Upgrade the plan before the wave rather than during it.

Step 5: Cut Over, Then Decommission

When the local broker carries no direct clients except the bridge, the migration is functionally complete. Keep the bridge and the old broker running for an agreed observation period as a rollback path. Rolling back a device is simply a configuration change back to the old host, and the bridge keeps both sides in sync meanwhile.

Then decommission in order: remove the bridge configuration, stop Mosquitto, close firewall ports, revoke old credentials and archive the configuration files. If some sites need local MQTT for edge logic that must work offline, keep a Mosquitto instance there permanently and bridge it upward; that hybrid design is common and perfectly valid.

Migration Checklist

1. Configuration, client list and topic list exported from Mosquitto.
2. Feature gaps (ACLs, QoS 2, message size, persistence) resolved.
3. Destination broker created on a plan with enough connections.
4. One credential set per device or service issued.
5. Bridge running with directional topics; data verified on both sides.
6. Consumers moved and verified.
7. Devices moved in waves with checkpoints.
8. Retained state republished on connect.
9. Rollback path kept for the observation period.
10. Old broker decommissioned and credentials revoked.

The MQTT prototype to production guide covers hardening steps you may want to fold into the same project.

Migrate to ConnectMQ

Create a free broker at app.connectmq.com on the Serverless plan, no credit card required, and build the bridge against it to test the whole runbook before committing. ConnectMQ gives you a hosted MQTT broker with TLS, WebSockets, issued credentials and a portal with a live topic explorer. For background on deployment models, read the cloud MQTT broker guide, and use the public MQTT test broker for quick, non-sensitive experiments.

Frequently Asked Questions

Can I migrate Mosquitto to cloud MQTT without changing device firmware?

Only if host, port, TLS settings, credentials and client ID are configurable without a firmware update. Devices with hard-coded broker addresses can stay on a local Mosquitto that bridges to the cloud.

Should the bridge use QoS 1 or QoS 0?

QoS 1 is the usual choice for bridging telemetry and commands, because it protects messages across the bridge link. Use QoS 0 only for high-rate data where occasional loss is acceptable.

Do retained messages migrate automatically?

Retained messages already on Mosquitto are not copied in bulk. The bridge forwards new publishes; have devices republish retained status on connect, and verify retained topics on the cloud side.

How long should I keep the old Mosquitto broker?

Keep it, with the bridge running, until every client has been stable on the new broker for an agreed period. That gives you an instant rollback path at very low cost.