---
name: migrate-mosquitto
description: Inventory and verify a Mosquitto replacement using the installed CitusIO tier, explicit policy mappings and a resumable private migration case.
---

# Replace a Mosquitto deployment

Read [the case workflow](../references/migration-workflow.md). Inventory the
actual version, startup command, working directory, listeners, includes,
password/ACL files, plugins, TLS identity, persistence and bridges. Resolve the
installed runtime's include order and listener scope. Paths are not necessarily
relative to the config. Preserve winning and overridden source locations.

Map listeners/TLS to nginx stream and auth/ACL behavior to target policy. Check
password-hash and certificate-identity compatibility before copying credentials.
Define wildcard, deny priority and identity substitution with client tests.

Resolve `B3-MOSQ-ACL-001`: source broad-filter grants with filtered delivery can
differ from target rejection; denied publish ACK/close can also differ. Never
widen authorization to get a successful SUBACK. An accepted client filter or
response change needs a decision for this deployment.

Map persistence separately from state transfer. Evaluation accepted-memory
cannot satisfy a durable-source requirement. Source clean checkpoints and
target PostgreSQL durable acknowledgements have different guarantees. Select
a compatible tier and local recovery skill for durable requirements.

For bridges, inventory direction/remapping, QoS/retain, credentials, remote
sessions, reconnect and expiry. Check the tier's actual sink support.
Rules-based routing and reference adapters need Integration and Edge or higher.
Resolve `B3-MOSQ-BRIDGE-RETRY-001`: indefinite reconnect is not finite retry with
terminal dead letters. Prove payload bytes, QoS/retain, outage, retry, terminal
ownership, duplicate behavior and sink receipts.

Validate native configurations and declared traffic. Inventory actual client
filters as well as ACL entries. Read
[migration-cutover](../migration-cutover/SKILL.md) for source drain, retained
reseed, reconnect/resubscription, post-write reconciliation and rollback.