Installer le broker MQTT Mosquitto (Ubuntu, Debian, Windows, macOS)

Eclipse Mosquitto est le broker MQTT open source le plus utilisé : léger, rapide et disponible sur pratiquement tous les systèmes d’exploitation. Ce tutoriel montre comment installer Mosquitto sur Ubuntu, Debian, Windows et macOS, le faire tourner comme service en arrière-plan, le vérifier avec les clients en ligne de commande et éviter le piège le plus courant de Mosquitto 2.x — le broker qui refuse silencieusement les connexions distantes.

Vous découvrez MQTT ? Lisez d’abord qu’est-ce que MQTT ; si vous préférez ne rien installer sur l’hôte, consultez exécuter Mosquitto dans Docker.

Installer Mosquitto sur Ubuntu et Debian

Mosquitto est présent dans les dépôts par défaut d’Ubuntu et de Debian. Le broker et les clients CLI sont des paquets séparés : installez les deux.

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Les paquets des distributions peuvent avoir du retard sur les versions upstream. Si vous avez besoin de la version la plus récente sur Ubuntu, le projet Mosquitto publie un PPA :

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

Vérifiez la version installée :

mosquitto -h | head -n 1

Exécuter Mosquitto comme service systemd

Le paquet Debian enregistre une unité systemd mosquitto et la démarre généralement aussitôt. Utilisez les commandes habituelles pour la gérer :

sudo systemctl enable --now mosquitto   # start now and at boot
sudo systemctl status mosquitto         # is it running?
sudo systemctl restart mosquitto        # after editing the config
journalctl -u mosquitto -f              # follow the logs

Le fichier de configuration principal est /etc/mosquitto/mosquitto.conf. Il inclut tous les fichiers *.conf de /etc/mosquitto/conf.d/, l’endroit le plus propre pour vos propres réglages.

Installer Mosquitto sur Windows

1. Téléchargez l’installeur Windows (.exe 64 bits) depuis la page de téléchargement officielle mosquitto.org/download.
2. Lancez-le. Laissez le composant Service coché si vous voulez que Mosquitto tourne comme service Windows. Le chemin d’installation par défaut est C:\Program Files\mosquitto.
3. Ajoutez ce dossier à votre PATH pour que mosquitto_pub et mosquitto_sub fonctionnent depuis n’importe quel terminal.

Démarrez le service depuis un PowerShell ou une invite de commandes administrateur :

net start mosquitto
# or run in the foreground with verbose logging:
cd "C:\Program Files\mosquitto"
.\mosquitto.exe -c mosquitto.conf -v

Installer Mosquitto sur macOS

Avec Homebrew, une seule ligne suffit, et le gestionnaire de services de Homebrew le maintient en arrière-plan :

brew install mosquitto
brew services start mosquitto     # run as a background service
brew services info mosquitto      # check status

Le fichier de configuration se trouve sous le préfixe de Homebrew : /opt/homebrew/etc/mosquitto/mosquitto.conf sur Apple Silicon ou /usr/local/etc/mosquitto/mosquitto.conf sur les Mac Intel. Les clients sont inclus dans la même formule.

Vérifier l’installation avec mosquitto_sub et mosquitto_pub

Ouvrez deux terminaux sur la machine qui héberge le broker. Abonnez-vous dans le premier :

mosquitto_sub -h localhost -t 'test/#' -v

Publiez depuis le second :

mosquitto_pub -h localhost -t 'test/hello' -m 'Mosquitto works'

Le terminal 1 doit afficher test/hello Mosquitto works. Pour l’ensemble des options, gardez sous la main notre aide-mémoire mosquitto_pub et mosquitto_sub.

Le piège du « local only mode » de Mosquitto 2.x

Le test en localhost fonctionne, mais un client sur une autre machine obtient connection refused. C’est voulu. Depuis la version 2.0, si mosquitto.conf ne définit aucun listener, Mosquitto n’écoute que sur l’interface de loopback et journalise un message de ce type :

Starting in local only mode. Connections will only be possible from clients running on this machine.
Create a configuration file which defines a listener to allow remote access.

Mosquitto 2.x applique aussi allow_anonymous false par défaut dès que vous définissez un listener. Ouvrir le port ne suffit donc pas — vous devez aussi décider comment les clients s’authentifient. Créez un petit fichier de configuration :

listener 1883
allow_anonymous true

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Redémarrez le broker (sudo systemctl restart mosquitto) et le port devient joignable depuis le réseau. La création du fichier de mots de passe ainsi que l’ajout d’ACL et de TLS sont détaillés pas à pas dans sécuriser Mosquitto. Pour construire une configuration sans mémoriser les directives, utilisez le générateur de mosquitto.conf.

Facultatif : activer les WebSockets

Les clients navigateur ne peuvent pas utiliser TCP brut. Pour tester votre broker depuis une page web, ajoutez un second listener avec le protocole WebSockets (voir MQTT sur WebSockets et les ports MQTT) :

listener 9001
protocol websockets

Notez qu’une page servie en HTTPS ne peut ouvrir que des connexions wss:// : pour un client navigateur sur le web public, il vous faudra donc aussi TLS sur ce listener. Avant d’en arriver là, vous pouvez vous faire la main avec MQTT sur un broker de test public, directement dans le navigateur :

Essayez-le dans le client MQTT en ligne

Où Mosquitto range ses fichiers

Quelle que soit la plateforme, lancez mosquitto -c <path-to-conf> -v dans un terminal quand quelque chose ne démarre pas : les erreurs de configuration s’affichent directement au lieu d’être cachées dans un journal de service. Arrêtez d’abord le service, sinon l’instance au premier plan échouera parce que le port est déjà occupé.

Dépanner une nouvelle installation

Pour les autres codes CONNACK et les timeouts, consultez le guide des erreurs de connexion MQTT.

Et ensuite ?

• Verrouillez-le avec mots de passe, ACL et TLS : authentification Mosquitto.
• Vous préférez les conteneurs ? Exécutez Mosquitto dans Docker.
• Comparez Mosquitto aux autres brokers dans notre annuaire de brokers.

Questions fréquentes