Skip to content

Operations

This page covers running the broker day to day: how it is secured, service management, logs, backups, updates and support.

Security model

  • Loopback and TLS. The only listener is 127.0.0.1:8883, with TLS.
  • No anonymous access. Every client needs a user name and password, and the topic ACL decides what each user may read and write.
  • Per-instance secrets. The CA, server certificate and passwords are created on first boot. The image contains none of them.
  • File permissions. The plaintext passwords in /etc/mosquitto/credentials/ are readable by root only. The broker reads only the hashed password file. The ubuntu user cannot read the private keys. Clients use the public CA copy in /usr/local/share/sushi/mosquitto/ca.pem.
  • Service sandbox. The mosquitto service runs as the mosquitto user and can write only to /var/lib/mosquitto/data. It can read, but not change, its configuration, ACL, passwords and certificates.

A single instance is not a clustered or highly available MQTT service.

Persistence

Retained messages and durable sessions are saved to /var/lib/mosquitto/data/mosquitto.db after every change, and come back after a restart or reboot.

Manage the service

sudo systemctl status mosquitto
sudo systemctl reload mosquitto
sudo systemctl restart mosquitto

The first-boot service, sushi-mosquitto-firstboot, runs before mosquitto on every boot. It creates anything that is missing and keeps your existing configuration, users and database.

Logs

Mosquitto logs errors, warnings, notices and client connections to the systemd journal:

sudo journalctl -u mosquitto -n 100 --no-pager

Backups

Back up /etc/mosquitto/ and /var/lib/mosquitto/ together. For a clean copy of retained messages and sessions, stop Mosquitto first, or copy a consistent mosquitto.db:

sudo systemctl stop mosquitto
sudo tar -czf /root/mosquitto-backup.tar.gz /etc/mosquitto /var/lib/mosquitto
sudo systemctl start mosquitto

The archive contains passwords and private keys. Store it somewhere private.

To restore on a replacement instance: let first boot finish, stop Mosquitto, restore the configuration, password file, ACL, TLS files and database, then check ownership and permissions:

  • /var/lib/mosquitto/data/mosquitto.db: mosquitto:mosquitto, mode 0600.
  • /var/lib/mosquitto and /var/lib/mosquitto/tls: root:mosquitto, mode 0750. Only data/ belongs to the broker.
  • /etc/mosquitto/credentials/: root only.

Start Mosquitto and check retained messages with a fresh subscriber before you switch clients. Keep the old instance until you are sure. Do not copy a database while the broker is writing it, and do not merge two brokers' databases.

Updates

  • Ubuntu packages, including OpenSSL, receive unattended security updates.
  • Mosquitto itself stays on 2.1.2. A new release comes as a new version of the image. Running instances are not migrated: launch the new version, restore your backup as above and switch clients over.

Support

Software Sushi supports the packaging, first-boot setup and this documentation. Email info@softwaresushi.com with your Mosquitto version, what you ran and the error. Never include passwords or private keys. Support coverage beyond installation questions requires a separate agreement. The Eclipse Foundation and the Mosquitto project do not provide support for this image.