How To Install Eclipse Mosquitto on Debian 13

If you are building an IoT system, a smart home automation stack, or an industrial telemetry pipeline, you need a reliable MQTT message broker at the center of it all. Eclipse Mosquitto is that broker — lightweight, open-source, battle-tested, and available directly from Debian’s official repositories. In this guide, you will learn exactly how to install Eclipse Mosquitto on Debian 13, configure it securely with password authentication, open the right firewall ports, and optionally encrypt traffic with TLS. By the end, you will have a fully functional MQTT broker running on Debian 13 (Trixie) that is ready for real-world use.

What Is Eclipse Mosquitto and Why Does It Matter?

Eclipse Mosquitto is an open-source MQTT message broker maintained by the Eclipse Foundation. It implements the MQTT protocol versions 3.1, 3.1.1, and 5.0, making it compatible with virtually every IoT client library available today.

MQTT stands for Message Queuing Telemetry Transport. It is a publish/subscribe protocol designed specifically for low-bandwidth, high-latency, or unreliable networks. Instead of devices talking directly to each other, every device talks to the broker. Publishers push messages to a topic, and subscribers receive messages from that same topic. The broker handles all routing.

Here is why Mosquitto is the top choice for developers and sysadmins:

• It runs on minimal hardware — a Raspberry Pi handles it comfortably
• It integrates natively with Home Assistant, Node-RED, and Python IoT stacks
• It sits in Debian’s official repositories, so no third-party PPA is required
• It supports username/password authentication and TLS encryption out of the box
• The Mosquitto project actively maintains Debian packages, tracked at tracker.debian.org

Debian 13, codenamed Trixie, was officially released on August 9, 2025. It ships with Linux Kernel 6.12, APT 3.0 with parallel download support, and improved systemd integration. These upgrades make Debian 13 an excellent long-term base for a production MQTT server.

Understanding the Publish/Subscribe Model

When a temperature sensor publishes a reading to the topic home/sensor/temperature, every application subscribed to that topic receives the message instantly. The sensor and the application never communicate directly — the broker handles delivery entirely.

This decoupling is what makes MQTT so powerful in distributed systems. A single Mosquitto broker can serve hundreds of clients simultaneously with very low CPU and memory overhead.

Prerequisites

Before starting this Eclipse Mosquitto on Debian 13 setup, confirm you have the following in place:

• Operating System: Debian 13 (Trixie) — fresh install or upgraded system
• User privileges: A non-root user with sudo access (avoid running everything as root)
• SSH or terminal access: Direct console or remote SSH connection to your server
• Text editor: nano or vim for editing configuration files
• Network access: Port 1883 for standard MQTT, port 8883 if using TLS/SSL
• Basic knowledge: Familiarity with running commands in a Linux terminal

All commands in this guide have been tested on a clean Debian 13 install to ensure accuracy.

Step 1: Update Your Debian 13 System

Before installing any package on a Linux server, updating the system is non-negotiable. Outdated package lists lead to dependency conflicts, and skipping this step is the number one cause of installation failures.

Run the following command to refresh the package index and apply all available upgrades:

sudo apt update && sudo apt upgrade -y

apt update fetches the latest package metadata from Debian’s repositories. apt upgrade -y installs all pending updates without asking for confirmation on each one.

Debian 13 ships with APT 3.0, which supports parallel downloads. You will notice the update process completes noticeably faster compared to Debian 11 or 12.

Confirm Your Debian Version

If you are not sure which Debian version you are running, verify it with:

cat /etc/os-release

You should see output containing VERSION="13 (trixie)". If you see a different version, some configuration paths in this guide may differ slightly.

Step 2: Install Eclipse Mosquitto on Debian 13

With the system updated, you can install Mosquitto directly from Debian’s official repositories. No external repositories or manual downloads are required.

Install the Mosquitto Broker

Run this command to install the broker:

sudo apt install mosquitto -y

The mosquitto package installs the broker daemon, the default configuration file at /etc/mosquitto/mosquitto.conf, and the systemd service unit. APT handles all dependencies automatically.

Install the Mosquitto Client Tools

Install the command-line client utilities that you will use to test the broker:

sudo apt install mosquitto-clients -y

This package provides two essential tools:

• mosquitto_pub — publishes a message to a topic
• mosquitto_sub — subscribes to a topic and listens for incoming messages

You will use both tools throughout this guide to verify every configuration change works correctly.

Verify the Installation

Check the installed version to confirm the installation succeeded:

mosquitto -v

Or check via APT for the package version string:

apt-cache policy mosquitto

You should see output showing the installed version number and the candidate from the Debian 13 repository. As of Debian 13 Trixie, the available version is Mosquitto 2.x, which includes stricter security defaults compared to earlier releases.

Step 3: Manage the Mosquitto Service with systemd

Debian starts the Mosquitto service automatically right after installation. Before going further, confirm the service is actually running.

Check the Service Status

sudo systemctl status mosquitto

Look for this in the output:

Active: active (running) since ...

If you see that, the broker is live and accepting connections.

Enable Mosquitto to Start at Boot

Debian 13’s improved systemd integration makes enabling services straightforward. Run:

sudo systemctl enable mosquitto

This registers Mosquitto as a boot-time service. The command creates the necessary systemd symlinks so that even after a reboot, your broker comes back online without manual intervention.

Service Management Reference

Keep these commands handy throughout this guide:

sudo systemctl start mosquitto      # Start the service
sudo systemctl stop mosquitto       # Stop the service
sudo systemctl restart mosquitto    # Restart (drops active connections)
sudo systemctl reload mosquitto     # Reload config without dropping connections
sudo systemctl status mosquitto     # Check current status

Use reload instead of restart whenever possible in production to avoid interrupting connected clients.

Step 4: Test the Default Broker Installation

Before locking anything down with passwords or firewall rules, confirm the broker accepts connections. You need two terminal windows (or two SSH sessions) open at the same time for this test.

Subscribe to a Test Topic

In Terminal 1, start a subscriber listening on a test topic:

mosquitto_sub -h localhost -t "test/topic"

The -h flag sets the broker hostname, and -t sets the topic name. The terminal will now wait silently for incoming messages.

Publish a Test Message

In Terminal 2, publish a message to the same topic:

mosquitto_pub -h localhost -t "test/topic" -m "Hello from Debian 13"

The -m flag defines the message payload.

If Terminal 1 immediately displays Hello from Debian 13, your broker is working correctly. The message traveled from the publisher through Mosquitto and arrived at the subscriber in milliseconds.

A Note on Mosquitto 2.x Anonymous Connections

Starting with Mosquitto 2.0, anonymous connections are disabled by default. If the test above returned a Connection Refused error, you need to either configure anonymous access temporarily (for development only) or set up authentication, which Step 6 covers in detail.

To allow anonymous connections temporarily for local testing only, create a new config file:

sudo nano /etc/mosquitto/conf.d/default.conf

Add these two lines:

listener 1883
allow_anonymous true

Save, then restart:

sudo systemctl restart mosquitto

Never use allow_anonymous true on a publicly accessible server.

Step 5: Configure Eclipse Mosquitto on Debian 13

This is where you shape how your broker behaves. Mosquitto’s configuration system is modular — the main file is at /etc/mosquitto/mosquitto.conf, and you can drop additional .conf files into /etc/mosquitto/conf.d/. Mosquitto loads all of them automatically at startup.

Best Practice: Use a Custom Config File

Rather than editing the default config file directly, create a clean custom configuration. This keeps your changes separate from package defaults and makes future upgrades cleaner:

sudo nano /etc/mosquitto/conf.d/default.conf

Configure the Listener and Logging

Paste the following into your new config file:

listener 1883
allow_anonymous false
log_dest file /var/log/mosquitto/mosquitto.log
log_type all

Here is what each directive does:

• listener 1883 — tells Mosquitto to accept connections on port 1883
• allow_anonymous false — blocks all unauthenticated connections
• log_dest file — writes log output to a dedicated file instead of stdout
• log_type all — captures all log categories for easier debugging

After saving the file, restart the service:

sudo systemctl restart mosquitto

Verify the log is being written:

sudo tail -f /var/log/mosquitto/mosquitto.log

Step 6: Set Up Password Authentication

With allow_anonymous false set, every client must authenticate with a username and password. Mosquitto includes mosquitto_passwd, a built-in utility for managing an encrypted password file.

Create the Password File

The -c flag creates a new password file. Replace mqttuser with your chosen username:

sudo mosquitto_passwd -c /etc/mosquitto/passwd mqttuser

You will be prompted to enter and confirm a password. The utility stores the credentials in bcrypt-hashed format — passwords are never stored in plain text.

To add a second user without overwriting the existing file (omit the -c flag):

sudo mosquitto_passwd /etc/mosquitto/passwd anotheruser

To remove a user:

sudo mosquitto_passwd -D /etc/mosquitto/passwd username

Point Mosquitto to the Password File

Open your custom config file again:

sudo nano /etc/mosquitto/conf.d/default.conf

Update it to reference the password file:

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Restart the service:

sudo systemctl restart mosquitto

Test Authenticated Connections

Open two terminals again and run the authenticated versions of the pub/sub commands.

Terminal 1 — Subscribe with credentials:

mosquitto_sub -h localhost -t "test/topic" -u mqttuser -P yourpassword

Terminal 2 — Publish with credentials:

mosquitto_pub -h localhost -t "test/topic" -m "Authenticated message" -u mqttuser -P yourpassword

The -u flag passes the username and -P passes the password.

Try connecting without credentials to confirm they are required:

mosquitto_pub -h localhost -t "test/topic" -m "No auth test"

You should receive:

Connection Refused: not authorised

That error confirms authentication is correctly enforced.

Step 7: Configure the UFW Firewall

With authentication in place, the next layer is controlling which network traffic reaches your broker at all. UFW (Uncomplicated Firewall) is the standard firewall tool on Debian systems.

Install UFW

sudo apt install ufw -y

Allow SSH Before Enabling UFW

This step is critical. If you enable UFW without allowing SSH first, you will lock yourself out of the server remotely:

sudo ufw allow OpenSSH

Open the MQTT Port

sudo ufw allow 1883/tcp

If you are planning to use TLS (covered in Step 8), also open port 8883:

sudo ufw allow 8883/tcp

Enable UFW and Set It to Start at Boot

sudo ufw enable
sudo systemctl enable ufw

UFW will ask you to confirm before enabling. Type y and press Enter.

Verify the Firewall Rules

sudo ufw status verbose

Expected output:

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW IN    Anywhere
1883/tcp                   ALLOW IN    Anywhere
8883/tcp                   ALLOW IN    Anywhere

Your broker is now protected at both the application level (password auth) and the network level (firewall rules).

Step 8: Enable TLS/SSL Encryption (Recommended for Production)

Passwords protect access, but without TLS, the username, password, and message content all travel in plain text across the network. Anyone running a packet sniffer on the same network segment can read everything.

Generate a Self-Signed Certificate

Create a dedicated directory for your certificates:

sudo mkdir /etc/mosquitto/certs
cd /etc/mosquitto/certs

Generate the Certificate Authority (CA) key and certificate:

sudo openssl genrsa -out ca.key 2048
sudo openssl req -new -x509 -days 1826 -key ca.key -out ca.crt

Generate the server key and Certificate Signing Request (CSR):

sudo openssl genrsa -out server.key 2048
sudo openssl req -new -key server.key -out server.csr

Sign the server certificate with your CA:

sudo openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 1826

When filling out the CSR fields, use different values for the CA and the server certificate — using identical values causes validation issues.

Configure Mosquitto to Use TLS

Open your config file:

sudo nano /etc/mosquitto/conf.d/default.conf

Add a second listener block for TLS on port 8883:

listener 8883
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false

require_certificate false means clients need valid credentials but do not need their own client certificate. Set it to true if you want mutual TLS authentication.

Restart Mosquitto:

sudo systemctl restart mosquitto

Test TLS connectivity with:

mosquitto_sub -h localhost -p 8883 --cafile /etc/mosquitto/certs/ca.crt -t "test/topic" -u mqttuser -P yourpassword

Verifying the Complete Setup

Run this final checklist before declaring the server production-ready:

# Confirm service is active and enabled
sudo systemctl status mosquitto

# Check firewall status
sudo ufw status verbose

# Run a full authenticated pub/sub test
mosquitto_pub -h localhost -p 1883 -t "home/sensor" -m "temp:22.5" -u mqttuser -P yourpassword

Check the log for the last 20 lines to confirm no errors:

sudo tail -n 20 /var/log/mosquitto/mosquitto.log

A clean log with no ERROR or WARNING lines means your broker is healthy and ready for client connections.

Troubleshooting Common Errors

Even a clean install can run into issues. Here are the most common problems and how to fix them.

Error: Connection Refused: not authorised

This happens when allow_anonymous false is set but the client is not passing credentials. Add -u yourusername -P yourpassword to your mosquitto_pub or mosquitto_sub command.

Error: Address already in use

Another process is occupying port 1883. Find the conflicting process:

sudo ss -tlnp | grep 1883

Kill the identified process by its PID or stop the conflicting service before restarting Mosquitto.

Mosquitto Service Fails to Start

A syntax error in the config file is almost always the cause. Check the system journal for the exact line number:

sudo journalctl -u mosquitto -xe

The output will point to the file and directive causing the failure.

mosquitto: command not found

The installation did not complete. Re-run:

sudo apt install mosquitto mosquitto-clients -y

Messages Not Delivered to Subscriber

MQTT topics are case-sensitive. home/Sensor and home/sensor are different topics. Verify the publisher and subscriber use the exact same topic string.

Congratulations! You have successfully installed Mosquitto. Thanks for using this tutorial for installing Eclipse Mosquitto (Message Queuing Telemetry Transport) on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the Mosquitto website.