How To Install Eclipse Mosquitto on Ubuntu 24.04 LTS

Eclipse Mosquitto stands as one of the most reliable open-source MQTT brokers in the IoT ecosystem. This lightweight message broker implements the MQTT protocol versions 3.1, 3.1.1, and 5.0, making it perfect for machine-to-machine communication and Internet of Things applications. Whether you’re building a smart home automation system, collecting sensor data, or developing industrial IoT solutions, Mosquitto delivers the performance and reliability you need. This comprehensive guide walks you through installing, configuring, and securing Eclipse Mosquitto on Ubuntu 24.04 LTS. You’ll learn everything from basic installation to advanced security configurations, complete with troubleshooting tips and best practices. By the end, you’ll have a production-ready MQTT broker running on your Ubuntu system.

Prerequisites

Before diving into the installation process, ensure your system meets these requirements. You’ll need Ubuntu 24.04 LTS installed—either the server or desktop edition works perfectly. Your user account must have sudo privileges to execute administrative commands. A stable internet connection is essential for downloading packages from Ubuntu repositories.

Basic familiarity with the Linux command line makes this process smoother. The system requirements are modest: 512MB of RAM and 1GB of disk space suffice for testing environments, though production deployments may demand more resources. If you plan to secure your broker with SSL/TLS certificates, having a domain name proves helpful. Access your system through a terminal or SSH connection, and consider creating a system backup before proceeding.

Step 1: Update System Packages

Updating your system before installing new software prevents dependency conflicts and ensures you have the latest security patches. Open your terminal and execute these commands:

sudo apt update
sudo apt upgrade -y

The apt update command synchronizes your package lists with Ubuntu’s repositories, downloading information about available packages and their versions. The apt upgrade command installs newer versions of currently installed packages. The -y flag automatically confirms the installation without prompting.

Watch the terminal output for any errors. If kernel updates are installed, the system may prompt you to reboot, though this isn’t always necessary for minor updates.

Step 2: Install Eclipse Mosquitto

Ubuntu 24.04 LTS offers two installation methods for Mosquitto. Each serves different needs.

Method A: Install from Default Ubuntu Repository

The default Ubuntu repository provides the most stable approach. This method delivers tested, officially maintained packages that integrate seamlessly with your system. Execute this command:

sudo apt install mosquitto mosquitto-clients -y

This command installs two essential packages. The mosquitto package contains the broker software that facilitates message exchanges between MQTT clients. The mosquitto-clients package provides command-line utilities like mosquitto_pub and mosquitto_sub for publishing and subscribing to topics, which are invaluable for testing.

Method B: Install from Mosquitto PPA

Need bleeding-edge features or the newest Mosquitto version? The Mosquitto Personal Package Archive (PPA) delivers the latest releases. Add the PPA repository first:

sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa -y
sudo apt update
sudo apt install mosquitto mosquitto-clients -y

The PPA route gives you access to newer features faster, but the default repository remains the recommended choice for most users due to its superior stability and official Ubuntu support.

Step 3: Verify Installation and Service Status

After installation completes, verify that Mosquitto runs correctly. Check the service status with this command:

sudo systemctl status mosquitto

Look for the “active (running)” status in the output. This indicates Mosquitto is running properly. The output displays the process ID, memory usage, and recent log entries. Ubuntu automatically enables Mosquitto to start on boot by default.

Verify the installed version:

mosquitto -h

This command displays help information including the version number. Mosquitto’s main configuration file resides at /etc/mosquitto/mosquitto.conf, while additional configuration files live in /etc/mosquitto/conf.d/.

By default, Mosquitto listens on port 1883 for unencrypted connections and port 8883 for SSL/TLS encrypted connections. Confirm the service listens on the correct port:

sudo ss -tuln | grep 1883

Essential service management commands include:

sudo systemctl start mosquitto    # Start the service
sudo systemctl stop mosquitto     # Stop the service
sudo systemctl restart mosquitto  # Restart the service
sudo systemctl enable mosquitto   # Enable auto-start on boot

Step 4: Configure Mosquitto Basics

Understanding Mosquitto’s configuration structure empowers you to customize its behavior. While the main configuration file exists at /etc/mosquitto/mosquitto.conf, best practice dictates creating custom configurations in separate files within /etc/mosquitto/conf.d/. This approach keeps your custom settings organized and preserves the default configuration.

Create a new configuration file:

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

Add these essential directives:

listener 1883
protocol mqtt
log_dest file /var/log/mosquitto/mosquitto.log
log_type all
max_connections -1
persistence true
persistence_location /var/lib/mosquitto/

Each directive serves a specific purpose. The listener directive specifies which port Mosquitto monitors for connections. The protocol directive sets the protocol type to MQTT. Logging configuration appears in log_dest and log_type, directing all log messages to a file. The max_connections setting with -1 allows unlimited simultaneous connections. The persistence directives enable message storage to disk, ensuring messages survive broker restarts.

Validate your configuration syntax before restarting:

mosquitto -c /etc/mosquitto/conf.d/default.conf -v

No errors? Restart the service:

sudo systemctl restart mosquitto

Monitor the logs for any issues:

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

Step 5: Implement Authentication and Security

Default Mosquitto installations accept anonymous connections—a significant security vulnerability. Production environments must enforce authentication to prevent unauthorized access and protect sensitive data.

Create Password-Protected User Accounts

Generate your first user account with a password:

sudo mosquitto_passwd -c /etc/mosquitto/passwd mqttuser

The -c flag creates a new password file, so use it only for the first user. The system prompts you to enter and confirm a password. Add additional users without the -c flag:

sudo mosquitto_passwd /etc/mosquitto/passwd seconduser

Set appropriate file permissions:

sudo chown mosquitto:mosquitto /etc/mosquitto/passwd

Encrypt Stored Passwords

Hash the passwords for security:

sudo mosquitto_passwd -U /etc/mosquitto/passwd

Verify the hashing worked:

sudo cat /etc/mosquitto/passwd

You should see encrypted password strings, not plaintext.

Configure Authentication Requirements

Edit your configuration file:

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

Add these authentication directives:

allow_anonymous false
password_file /etc/mosquitto/passwd

The allow_anonymous false directive blocks unauthenticated connections. The password_file directive points to your password file. Restart Mosquitto to apply changes:

sudo systemctl restart mosquitto

For environments requiring topic-level permissions, Access Control Lists (ACLs) provide granular control. Create an ACL file at /etc/mosquitto/acl and reference it in your configuration with acl_file /etc/mosquitto/acl.

Step 6: Test Your MQTT Broker

Testing confirms your broker works correctly. Open two terminal windows to perform a publish-subscribe test.

In Terminal 1, subscribe to a test topic:

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

In Terminal 2, publish a message:

mosquitto_pub -t "test/topic" -m "Hello MQTT" -u mqttuser -P yourpassword

The message should appear immediately in Terminal 1. Test authentication by attempting to connect without credentials—the connection should fail, confirming your security works.

Test Remote Connections

From another machine on your network, test remote connectivity:

mosquitto_pub -h 192.168.1.100 -t "test/topic" -m "Remote message" -u mqttuser -P yourpassword

Replace 192.168.1.100 with your Ubuntu server’s IP address.

Understanding MQTT Topics

MQTT topics use a hierarchical structure separated by forward slashes, like home/livingroom/temperature. Wildcards enhance subscription flexibility: the + wildcard matches a single level, while # matches multiple levels. Subscribe to all topics:

mosquitto_sub -t "#" -u mqttuser -P yourpassword

Quality of Service Testing

MQTT supports three Quality of Service levels. QoS 0 delivers at most once, QoS 1 delivers at least once, and QoS 2 delivers exactly once. Test different QoS levels:

mosquitto_pub -t "test/qos" -m "QoS test" -q 1 -u mqttuser -P yourpassword

Step 7: Configure Firewall Rules

Opening firewall ports enables external clients to connect to your MQTT broker. Check Ubuntu’s UFW firewall status:

sudo ufw status

Allow MQTT traffic on standard ports:

sudo ufw allow 1883/tcp
sudo ufw allow 8883/tcp
sudo ufw reload

Port 1883 handles unencrypted MQTT traffic, while port 8883 serves encrypted SSL/TLS connections. For restricted access from specific networks:

sudo ufw allow from 192.168.1.0/24 to any port 1883

Verify your firewall rules:

sudo ufw status numbered

Cloud Provider Considerations

Cloud platforms require additional firewall configuration. AWS uses Security Groups, DigitalOcean and Vultr provide firewall control panels, and Azure employs Network Security Groups. Configure both UFW and your cloud provider’s firewall to ensure connectivity.

Never expose port 1883 to the internet without authentication. For production deployments, always use SSL/TLS encryption.

Step 8: Configure SSL/TLS Encryption

SSL/TLS encryption protects MQTT traffic from eavesdropping, making it essential for production environments handling sensitive data.

Obtain SSL Certificates

For testing or internal use, generate self-signed certificates. For production with a public domain, Let’s Encrypt provides free certificates. Install Certbot:

sudo apt install certbot -y

Generate a certificate for your domain:

sudo certbot certonly --standalone -d mqtt.yourdomain.com

Certbot stores certificates in /etc/letsencrypt/live/mqtt.yourdomain.com/.

Configure Mosquitto for SSL

Edit your configuration:

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

Add SSL directives:

listener 8883
cafile /etc/letsencrypt/live/mqtt.yourdomain.com/chain.pem
certfile /etc/letsencrypt/live/mqtt.yourdomain.com/cert.pem
keyfile /etc/letsencrypt/live/mqtt.yourdomain.com/privkey.pem
require_certificate false

The listener directive on port 8883 handles encrypted connections. Certificate file paths point to Let’s Encrypt certificates. The require_certificate false setting allows clients to connect without client certificates.

Set proper permissions:

sudo chmod 644 /etc/letsencrypt/live/mqtt.yourdomain.com/*
sudo chmod 644 /etc/letsencrypt/archive/mqtt.yourdomain.com/*

Restart Mosquitto:

sudo systemctl restart mosquitto

Test Encrypted Connections

Verify SSL works:

mosquitto_pub -h localhost -p 8883 --cafile /etc/letsencrypt/live/mqtt.yourdomain.com/chain.pem -t "test/ssl" -m "Encrypted message" -u mqttuser -P yourpassword

Let’s Encrypt certificates expire after 90 days. Certbot automatically sets up renewal through a systemd timer, but verify it’s enabled:

sudo systemctl status certbot.timer

Common Troubleshooting Issues

Connection Refused Errors

This common issue has several causes. First, verify Mosquitto runs:

sudo systemctl status mosquitto

Check firewall rules allow connections. Confirm the correct port in your configuration. Review logs for specific errors:

sudo journalctl -u mosquitto -f

Authentication Failures

Verify your password file exists with proper permissions:

ls -l /etc/mosquitto/passwd

Ensure your configuration references the password file correctly. Confirm passwords are hashed:

sudo cat /etc/mosquitto/passwd

Configuration Changes Not Applied

Test configuration syntax:

mosquitto -c /etc/mosquitto/mosquitto.conf -t

This command validates configuration without starting the broker. After configuration changes, always restart the service. The main configuration file includes files from conf.d/, so verify your custom configuration resides in the correct location.

Port Already in Use

Multiple Mosquitto instances or conflicting services can bind to the same port. Identify what’s using port 1883:

sudo lsof -i :1883

Kill conflicting processes if necessary, or configure Mosquitto to use a different port.

SSL Certificate Errors

Double-check certificate paths in your configuration. Verify certificates haven’t expired:

openssl x509 -in /etc/letsencrypt/live/mqtt.yourdomain.com/cert.pem -noout -dates

Confirm the mosquitto user can read certificate files. Permission issues frequently cause SSL failures.

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