Will Mosquitto let your devices in straight away?
No, and that is deliberate. Mosquitto's 1.x-to-2.0 guide spells out two situations. With no configuration, or a file with no listener line, it listens on 127.0.0.1 and ::1 only: programs on the same computer can connect, in this one case without a username. Once your file has a listener, it is open on every interface, but allow_anonymous is false unless you say otherwise, so a client with no username is turned away.
The guide offers a password file with an access list, a plugin that checks logins, or setting allow_anonymous true for a genuine need. You will take the first. Also new in 2.0: after reading its main configuration the broker switches to the low-privilege mosquitto account, so the password file, access list, certificates and saved-message file must be ones that account can read.
Two doors: one for the machine, one for the world
| Port | What it carries | Who can reach it here |
|---|---|---|
| 1883 | Plain MQTT; usernames and passwords readable on the wire | Only this server: bound to 127.0.0.1, no firewall rule |
| 8883 | MQTT inside TLS, the encrypted version | Everyone, after a username and password |
| 80 | The Let's Encrypt check at issue and renewal | Open, though only certbot listens, and only then |
SSH stays open through ufw's OpenSSH rule.
How much server does a broker need?
The docs give no number; Mosquitto's home page calls the broker fit for anything from a single-board computer to a full server. What fills the machine is how many clients stay connected and how many messages wait for slow or absent ones. You can cap both:
max_queued_messages: 1000 per client by default, for QoS 1 and 2 messages waiting beyond those being delivered.max_connections: no cap unless you set one, though the system's open-file limit still applies.max_packet_size: 2,000,000 bytes by default from version 2.1, no cap before.
Our advice: start modest and watch memory with real devices.
The server that fits
Your broker is the address every device remembers, so it should stay put. A dedicated server gives it a whole physical computer that nobody else shares: root login, a port nobody meters, no allowance to overrun. A racked one reaches you within 30 minutes of approval; a build to order needs hours with the parts on hand, working days if they have to be ordered. The server is yours to manage; the hardware under it and the network stay our job.
- If SSH ever stops answering, you want the out-of-band console, a screen and power button of its own. Rack servers, blades and the m510 and m710x cartridges have it; any other cartridge has power control alone.
- The ARM cartridge is out: Ubuntu 16.04 and 18.04 are its only choices, and these steps need 24.04 or later.
- Pick the city nearest your devices; our locations page lists all five.
The server has one IPv4 address, plus IPv6 at no charge. Point the broker's DNS name at it before step one: the certificate check reaches this machine by that name.
Step one: firewall, broker and a free certificate
Mosquitto's download page says Ubuntu ships it; a PPA called mosquitto-dev carries newer releases. This block turns the firewall on first, installs the broker, its test clients and certbot, then gets a Let's Encrypt certificate in standalone mode, where certbot briefly runs a small web server on port 80.
Certbot's user guide says it keeps certificates in folders only root can open (mode 0700), and the current Mosquitto manual says the broker refuses sensitive files whose path runs through a symlink. So a small hook copies both files to /etc/mosquitto/certs, hands them to the mosquitto account, and sends the broker a HUP to load the new pair. The idea is mosquitto-copy.sh from Mosquitto's own repository, which already reads $RENEWED_LINEAGE. What we changed: no domain check, install copies with the owner and permissions already applied (the certs folder gets 700), and certbot receives the hook through --deploy-hook, run by sh, not from its renewal-hooks folder. Certbot remembers the hook for every renewal. It is safe to repeat.
# Run as root on Ubuntu 24.04 or 26.04. First fill in your broker's DNS name and your email address.
N=broker.example.net; E=you@example.net
if [ "$N" = broker.example.net ] || [ "$E" = you@example.net ]; then echo "STOP - fill in N and E first"
else
sed -i 's/^IPV6=.*/IPV6=yes/' /etc/default/ufw && ufw allow OpenSSH && ufw --force enable &&
apt-get update && apt-get install -y mosquitto mosquitto-clients certbot &&
ufw allow 8883/tcp && ufw allow 80/tcp &&
printf '%s\n' 'set -e' 'K=/etc/mosquitto/certs' 'install -d -o mosquitto -g mosquitto -m 700 $K' \
'install -m 600 -o mosquitto -g mosquitto $RENEWED_LINEAGE/fullchain.pem $K/server.pem' \
'install -m 600 -o mosquitto -g mosquitto $RENEWED_LINEAGE/privkey.pem $K/server.key' \
'pkill -HUP -x mosquitto || true' > /usr/local/sbin/mosquitto-certs.sh &&
certbot certonly --standalone -n --agree-tos -m "$E" -d "$N" \
--deploy-hook "sh /usr/local/sbin/mosquitto-certs.sh" &&
test -s /etc/mosquitto/certs/server.pem && echo "step one done" || echo "STOP - something above did not work"
fi
Step two: tell the broker who may say what
Next you swap the package's settings file (kept as mosquitto.conf.dist) for a short one: no anonymous access, a password file and access list, saved messages in /var/lib/mosquitto/, and the two listeners from the table. Our picks, not defaults: a save every 300 seconds rather than 1800, so a crash costs a few minutes of retained messages at most, and forgetting clients absent 14 days (the default is never). With no include_dir line, conf.d is ignored; with no log_dest, logs land in journalctl -u mosquitto.
In the access list, %u means the username that connected: a sensor signed in as kitchen may publish and subscribe under sensors/kitchen/ and nowhere else, while display reads every sensor. The block makes random passwords for both, saves them in /root/mqtt-accounts.txt (root only) and hands them to mosquitto_passwd -b, which the manual warns exposes a password on the command line; your history gets only the variable name, the process list the value for an instant.
# Run as root after "step one done". Refuses a second run. Creates two accounts, starts the broker.
C=/etc/mosquitto/mosquitto.conf; S=/root/mqtt-accounts.txt; W=/etc/mosquitto/passwd
if [ -e $C.dist ] || [ -e $S ]; then echo "STOP - $C.dist or $S exists, so this ran before"
else
P1=$(openssl rand -hex 16) && P2=$(openssl rand -hex 16) && [ -n "$P1" ] && [ -n "$P2" ] &&
install -m 600 /dev/null $S && printf 'display %s\nkitchen %s\n' "$P1" "$P2" > $S &&
mv $C $C.dist &&
cat > $C <<'EOF' &&
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
persistence true
persistence_location /var/lib/mosquitto/
autosave_interval 300
persistent_client_expiration 14d
listener 1883 127.0.0.1
listener 8883
certfile /etc/mosquitto/certs/server.pem
keyfile /etc/mosquitto/certs/server.key
tls_version tlsv1.2
EOF
printf '%s\n' 'pattern readwrite sensors/%u/#' 'user display' 'topic read sensors/#' > /etc/mosquitto/acl &&
umask 077 && mosquitto_passwd -c -b $W display "$P1" && mosquitto_passwd -b $W kitchen "$P2" &&
chown mosquitto:mosquitto $W /etc/mosquitto/acl && chmod 600 $W /etc/mosquitto/acl &&
install -d -o mosquitto -g mosquitto -m 700 /var/lib/mosquitto &&
systemctl restart mosquitto && systemctl is-active mosquitto && ss -ltn | grep -q '127.0.0.1:1883 ' &&
! ss -ltn | grep -Eq '(0\.0\.0\.0|\[::\]|\*):1883 ' && echo "broker running, 1883 local only" ||
echo "STOP - read journalctl -u mosquitto -n 30"
fi
If it stops part-way, put the original back with cd /etc/mosquitto && mv mosquitto.conf.dist mosquitto.conf, remove /root/mqtt-accounts.txt, and run it again.
Try it with two terminals. Replace broker.example.net with your broker's name, then watch over TLS: P=$(grep '^display ' /root/mqtt-accounts.txt | cut -d' ' -f2) && mosquitto_sub -L "mqtts://display:$P@broker.example.net/sensors/#" -v. Since 2.0 the clients trust the system's certificate authorities for mqtts://. Then send a reading as the sensor: P=$(grep '^kitchen ' /root/mqtt-accounts.txt | cut -d' ' -f2) && mosquitto_pub -L "mqtt://kitchen:$P@127.0.0.1/sensors/kitchen/temp" -m 21.5. It appears in the first terminal; one aimed at sensors/hall/temp by kitchen should not. Store both passwords in your password manager, then delete the file.
New device later? mosquitto_passwd /etc/mosquitto/passwd hall && chmod 600 /etc/mosquitto/passwd && chown mosquitto: /etc/mosquitto/passwd && pkill -HUP -x mosquitto; the authentication guide says the broker rereads the file on that signal. Password files are meant for a modest, stable list of users; for users, groups and roles you manage remotely, the guide suggests the dynamic security plugin. Browser clients need one more listener with protocol websockets and the certificate lines.
A nightly copy, and getting it back
Everything the broker remembers lives in /etc/mosquitto (settings, users, rules, certificate copies) and /var/lib/mosquitto/mosquitto.db (subscriptions, queues and retained messages). The manual says SIGUSR1 makes the broker write that file at once, so the nightly job sends it, waits five seconds, packs both folders with the hook and the job, confirms mosquitto.db is in the archive, and only then deletes copies older than ten days. Your private key and password hashes are inside, so the folder is mode 700.
# Run as root. Creates /etc/cron.d/mqtt-backup: every night at 04:10, ten days kept, old copies removed only after a good one.
install -d -m 700 /var/backups/mqtt &&
printf '%s\n' 'SHELL=/bin/bash' 'PATH=/usr/sbin:/usr/bin:/sbin:/bin' \
'10 4 * * * root umask 077; B=/var/backups/mqtt; T=$(date +\%F-\%H\%M\%S); pkill -USR1 -x mosquitto; sleep 5; tar -czf $B/broker-$T.tgz -C / etc/mosquitto var/lib/mosquitto usr/local/sbin/mosquitto-certs.sh etc/cron.d/mqtt-backup && tar -tzf $B/broker-$T.tgz | grep -q mosquitto.db && find $B -name "broker-*.tgz" -mtime +10 -delete || echo "$T backup FAILED, see $B" >> $B/errors.log' \
> /etc/cron.d/mqtt-backup && chmod 644 /etc/cron.d/mqtt-backup && echo "nightly copy scheduled" || echo "STOP - the job was not created"
Next day, /var/backups/mqtt should hold one archive and no errors.log. Pull copies to another machine with rsync -a (never --delete). To bring a copy back on a fresh server, as root:
- Run step one only, put an archive in
/root, put its name in A, such asA=/root/broker-2026-11-01-041000.tgz, and test it:tar -tzf "$A" | grep -q var/lib/mosquitto/mosquitto.db && echo ok. No ok, no restore. - Move an old
/root/beforeor/root/unpackedaway first, then keep what is there now. Stop the broker:rm -f /run/mq?; [ ! -e /root/before ] && [ ! -e /root/unpacked ] && systemctl stop mosquitto && mkdir -m 700 /root/before && touch /run/mq1 && echo stopped || echo STOP - old folder there, or broker still up. Then copy:rm /run/mq1 && cp -a /etc/mosquitto /root/before/etc-mosquitto && cp -a /var/lib/mosquitto /root/before/lib-mosquitto && test -e /root/before/etc-mosquitto/mosquitto.conf && touch /run/mq2 && echo kept || echo STOP - nothing kept, do not go on. Each command needs the marker the last one left in/run. A STOP here has changed none of the broker's files: runsystemctl start mosquitto, clear the cause and begin this step again. - In that shell, unpack to a side folder:
test -e /run/mq2 && test -e /root/before/etc-mosquitto/mosquitto.conf && mkdir -m 700 /root/unpacked && tar -xzf "$A" -C /root/unpacked && touch /run/mq3 && echo unpacked || echo STOP - not unpacked, use step 4. Copy in settings and users:rm /run/mq3 && cd /root/unpacked/etc/mosquitto && install -m 600 -o mosquitto -g mosquitto passwd acl /etc/mosquitto/ && install -m 644 mosquitto.conf /etc/mosquitto/ && touch /run/mq4 && echo copied || echo STOP - not copied, use step 4. Then saved messages and the backup job:rm /run/mq4 && install -m 600 -o mosquitto -g mosquitto /root/unpacked/var/lib/mosquitto/mosquitto.db /var/lib/mosquitto/ && cp /root/unpacked/etc/cron.d/mqtt-backup /etc/cron.d/ && touch /run/mq5 && echo moved || echo STOP - not moved, use step 4. Start it:rm /run/mq5 && systemctl start mosquitto && sleep 1 && systemctl is-active --quiet mosquitto && echo restored || echo STOP - broker not running, use step 4. After a STOP here, use step 4. The certificate from step one stays. - Changed your mind?
test -e /run/mq2 && systemctl stop mosquitto && cp -a /root/before/etc-mosquitto/. /etc/mosquitto/ && cp -a /root/before/lib-mosquitto/. /var/lib/mosquitto/ && systemctl start mosquitto || echo STOP - no fresh copy from step 2, do not roll back./runempties on a reboot, so after one this refuses: check/root/beforeby hand first.
Updates, the licence, and when to pick something else
Before an update, copy mosquitto.db aside: a newer broker may save it in a format an older one cannot read, the manual warns. Then apt update && apt install --only-upgrade mosquitto mosquitto-clients. When your package reaches 2.1, read that ChangeLog entry first: the packet limit falls to 2,000,000 bytes, a broken password file or access list on reload now stops the broker, and the per_listener_settings, acl_file and password_file options are deprecated in favour of plugins, due to go in 3.0. They still work in 2.1, which adds mosquitto --test-config.
The licence, in our reading and not as legal advice: Mosquitto's LICENSE.txt lets you choose the EPL 2.0 or the EDL 1.0 (SPDX calls the EDL BSD-3-Clause). Under the permissive EDL, copies you pass on, changed or not, keep the copyright notice, the conditions and the disclaimer; no source is owed. The EPL is weak copyleft: distribute the program under it in any form and its source must be made available under the EPL too. Running a broker that devices connect to, yours or your customers', hands nobody a copy.
A lone broker is a single point of failure; the bridge options in mosquitto.conf pass chosen topics to a second broker, which in our view connects brokers rather than mirroring one. If what you have is applications handing work to each other, with queues and per-message acknowledgements, a RabbitMQ server is likely the better tool.
Questions people ask
- Clients connect on the server but not from outside. What is wrong?
- Probably no listener, so Mosquitto 2 listens on 127.0.0.1 and ::1 only. Add one, give each client a username, and check that ufw allows the port.
- Is port 1883 safe to open if every client has a password?
- Not really: on plain 1883 the password travels unencrypted and anyone on the path can read it. Keep 1883 on loopback or a private network, and send outside clients to 8883 with TLS.
- Can I use my own certificate authority instead of Let's Encrypt?
- Yes. The mosquitto-tls manual gives the openssl commands for a CA, a server key and a signed server certificate, and warns that CA, server and client certificates need different subject details. Point certfile and keyfile at your server files; every client then needs your CA certificate.