mosquitto.conf generator
Choose listeners, TLS, WebSockets, authentication, persistence and logging, and get a commented Mosquitto 2.x configuration with the matching mosquitto_passwd, Docker and systemd commands.
# mosquitto.conf — Mosquitto 2.x
# Generated with the TestMQTT mosquitto.conf generator.
# Full reference: man mosquitto.conf / https://mosquitto.org/man/mosquitto-conf-5.html
# ------------------------------------------------------------------
# General
# ------------------------------------------------------------------
# One set of authentication settings shared by every listener.
per_listener_settings false
# ------------------------------------------------------------------
# Persistence
# ------------------------------------------------------------------
# Save retained messages, subscriptions and queued QoS 1/2 messages to disk.
persistence true
persistence_location /var/lib/mosquitto/
# ------------------------------------------------------------------
# Logging
# ------------------------------------------------------------------
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information
log_timestamp true
log_timestamp_format %Y-%m-%dT%H:%M:%S
# ------------------------------------------------------------------
# Security (applies to all listeners)
# ------------------------------------------------------------------
allow_anonymous false
password_file /etc/mosquitto/passwd
# ------------------------------------------------------------------
# Listeners
# ------------------------------------------------------------------
# MQTT over TCP
listener 1883
# MQTT over WebSockets
listener 9001
protocol websocketsCreate users
# Create the password file with the first user (-c creates / overwrites it)
sudo mosquitto_passwd -c /etc/mosquitto/passwd alice
# Add more users later — without -c
sudo mosquitto_passwd /etc/mosquitto/passwd bob
# Mosquitto 2.x warns if the file is readable by other users
sudo chown mosquitto:mosquitto /etc/mosquitto/passwd
sudo chmod 0700 /etc/mosquitto/passwdRun with Docker
# Layout: ./config/mosquitto.conf, ./config/passwd
mkdir -p config data log
cp mosquitto.conf config/mosquitto.conf
docker run -d --name mosquitto --restart unless-stopped \
-p 1883:1883 \
-p 9001:9001 \
-v "$PWD/config:/mosquitto/config" \
-v "$PWD/data:/mosquitto/data" \
-v "$PWD/log:/mosquitto/log" \
eclipse-mosquitto:2
docker logs -f mosquitto
# Tip: set "Paths for" to Docker so the file paths in the config match the container.Apply on a Linux server (systemd)
# Install the config
sudo cp mosquitto.conf /etc/mosquitto/mosquitto.conf
# Optional: run in the foreground to spot config errors (Ctrl+C to stop)
sudo systemctl stop mosquitto
sudo mosquitto -c /etc/mosquitto/mosquitto.conf -v
# Restart the service and follow its log
sudo systemctl restart mosquitto
sudo systemctl status mosquitto
sudo journalctl -u mosquitto -fThe Mosquitto 2.0 local-only default
Mosquitto 2.0 changed the defaults to be secure out of the box. If the configuration contains no listener line, the broker binds to localhost only, and anonymous clients are refused unless you explicitly allow them. That is why a fresh install often works with mosquitto_sub on the same machine but rejects every other device. The fix is an explicit listener plus a decision about authentication — exactly what this generator writes. Installing from scratch? Start with how to install Mosquitto.
Listeners
Each listener line opens a port and starts a block: the lines after it (protocol, certificates, max_connections) belong to that listener until the next one. Port 1883 is plain MQTT, 8883 is MQTT over TLS, and a listener with protocol websockets serves browser clients — 9001 is the usual choice. Add an optional bind address such as 127.0.0.1 to keep a listener private to the host. The MQTT ports guide and MQTT over WebSockets explain the conventions.
TLS listeners need a certfile and keyfile; with Let’s Encrypt these are fullchain.pem and privkey.pem. cafile is only required when you turn on require_certificate to authenticate clients with their own certificates.
Authentication and ACLs
allow_anonymous false together with a password_file is the baseline for any broker reachable from a network. Create the file with mosquitto_passwd -c — note that -c overwrites an existing file, so leave it off when adding more users. An acl_file then restricts which topics each user may read or write; the generated example shows user rules and pattern rules with %u and %c substitutions. Read Mosquitto authentication for a full walkthrough.
per_listener_settings must appear before the listeners. Leave it false for one shared set of rules; set it true when, for example, a localhost listener should stay anonymous while the public one requires passwords.
Persistence, logging and limits
With persistence true, retained messages, durable sessions and queued QoS 1 and 2 messages survive restarts in mosquitto.db inside persistence_location (keep the trailing slash). Log to a file on a server, or to stdout in Docker so docker logs shows everything. max_packet_size rejects oversized packets and replaces the deprecated message_size_limit; max_connections caps clients per listener.
Running it
For containers, switch the paths to Docker so they match the official image layout, then follow running Mosquitto in Docker. On a server, test the file in the foreground with mosquitto -c … -v before restarting the service. Once it is up, connect with the online MQTT client over WebSockets and review the MQTT security best practices before exposing it to the internet.
mosquitto.conf FAQ
Why can’t clients connect to Mosquitto 2.0 from another machine?
Since version 2.0, Mosquitto started without a listener directive only listens on localhost and refuses anonymous clients. Add an explicit listener such as "listener 1883" and either configure a password_file or set allow_anonymous true.
Where is mosquitto.conf located?
Linux packages install it at /etc/mosquitto/mosquitto.conf, Homebrew uses /opt/homebrew/etc/mosquitto/mosquitto.conf, and the official Docker image reads /mosquitto/config/mosquitto.conf.
What does per_listener_settings do?
When it is false (the default), allow_anonymous, password_file and acl_file apply to every listener. When true, each listener gets its own authentication settings — for example anonymous access on a localhost-only port and passwords on the public one.
Do I need to restart Mosquitto after adding a user?
Mosquitto rereads the password and ACL files when it receives SIGHUP, so systemctl reload mosquitto or a restart is enough. Listener changes always require a full restart.