Configuration¶

This page shows where the broker's configuration lives and how to make the common changes: users, the topic ACL, network access and certificates. Edit the files as root.

Where things live¶

Path	What it is
`/etc/mosquitto/mosquitto.conf`	Broker configuration. Created on first boot and kept afterwards.
`/var/lib/mosquitto/passwd`	User names and hashed passwords.
`/var/lib/mosquitto/acl`	Topic ACL: which user may read or write which topics.
`/etc/mosquitto/credentials/`	Plaintext passwords of the example users, one file per user. Root only.
`/var/lib/mosquitto/tls/`	CA and server certificates and keys.
`/usr/local/share/sushi/mosquitto/ca.pem`	Public copy of the CA certificate, for clients.
`/var/lib/mosquitto/data/mosquitto.db`	Persistence database: retained messages and durable sessions.

The files in /var/lib/mosquitto/ other than data/ are owned by root:mosquitto with mode 0640, so the broker can read them but not change them. Keep that ownership when you edit them.

The upstream example files mosquitto.conf.example, aclfile.example and pwfile.example are in /etc/mosquitto/ for reference.

Apply a change¶

Password and ACL changes take effect on a reload, which keeps clients connected:

sudo systemctl reload mosquitto

After you change a listener or certificate, restart instead:

sudo systemctl restart mosquitto

Users and topic ACL¶

First boot creates three example users:

User	Topics
`publisher`	read and write `sushi/pilot/#`
`subscriber`	read `sushi/pilot/#`
`denied`	read and write `sushi/denied/#` only

The ACL file lists each user and its topics:

user publisher
topic readwrite sushi/pilot/#

user subscriber
topic read sushi/pilot/#

Add a user¶

Add the user to the password file. mosquitto_passwd asks for the password twice, so it never appears on the command line:

sudo mosquitto_passwd /var/lib/mosquitto/passwd <user-name>
sudo chown root:mosquitto /var/lib/mosquitto/passwd
sudo chmod 0640 /var/lib/mosquitto/passwd

Add the user's topics to /var/lib/mosquitto/acl, for example:
```
user <user-name>
topic readwrite factory/line1/#
```
Reload Mosquitto.

To change a password, run the same mosquitto_passwd command for an existing user. If you change an example user's password, also update its file in /etc/mosquitto/credentials/ so the helper client keeps working.

To remove a user, delete it from the password file and its lines from the ACL, then reload:

sudo mosquitto_passwd -D /var/lib/mosquitto/passwd <user-name>

The helper /opt/sushi/bin/mosquitto-as.sh works only with the three example users and topics under sushi/. For your own users, use mosquitto_pub, mosquitto_sub or your client library directly.

Reach Mosquitto from your VPC¶

By default the broker listens on 127.0.0.1 only. You have two options:

Keep it on loopback and put a proxy or port forward in front of it, for example Session Manager port forwarding as shown in Getting started.
Listen on the private address:
1. Issue a server certificate that includes the private address or DNS name your clients use (see below). The certificate created on first boot covers only localhost and 127.0.0.1.
2. Change the listener line in /etc/mosquitto/mosquitto.conf:
```
listener 8883 <private-ip>
```
3. Allow TCP 8883 in the security group only from your clients.
4. Restart Mosquitto and give your clients /usr/local/share/sushi/mosquitto/ca.pem. Keep CA and host name verification on in the clients.
The helper client and the walkthrough connect to 127.0.0.1, so they stop working once the listener moves to the private address.

Test publishing, subscribing, a denied topic and retained messages from a separate host before you switch devices over.

Keep it private

Do not listen on 0.0.0.0 with an open security group. Do not set allow_anonymous true, and do not turn TLS off.

Issue a server certificate for a private address¶

This signs a new server certificate with the instance's own CA, the same way first boot does, with your private address added. Replace <private-ip> before you run it:

sudo bash -euo pipefail <<'CERT'
cd /var/lib/mosquitto/tls
ip=<private-ip>
umask 077
openssl genrsa -out server.key.new 2048
openssl req -new -key server.key.new -out server.csr -subj '/CN=localhost'
printf 'subjectAltName=DNS:localhost,IP:127.0.0.1,IP:%s\n' "$ip" > san.ext
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
  -days 825 -sha256 -out server.pem.new -extfile san.ext
rm -f server.csr san.ext ca.srl
mv server.key.new server.key
mv server.pem.new server.pem
chown root:mosquitto server.key server.pem
chmod 0640 server.key server.pem
CERT

Rotate the TLS certificates¶

The certificates created on first boot are valid for 825 days. The first-boot service creates any certificate pair that is missing, so you rotate by removing files and running it again.

To replace only the server certificate, keeping the CA your clients trust:

sudo systemctl stop mosquitto
sudo rm /var/lib/mosquitto/tls/server.pem /var/lib/mosquitto/tls/server.key
sudo systemctl restart sushi-mosquitto-firstboot
sudo systemctl start mosquitto

To replace the CA as well, also remove ca.pem and ca.key before you run the first-boot service, then give clients the new /usr/local/share/sushi/mosquitto/ca.pem. If you had added a private address, issue its server certificate again.

Client certificates and bridges¶

The default identity is a user name and password over TLS. Requiring client certificates (require_certificate true) and bridging to another broker, such as AWS IoT Core, are changes you make yourself; see the Mosquitto configuration reference.