Héberger un courtier MQTT Meshtastic privé avec Mosquitto

Notre guide MQTT Meshtastic (en anglais) couvre les concepts : ce que le module MQTT relie, ce qui fuit à travers lui, et pourquoi le courtier public par défaut place les métadonnées de votre mesh dans un bassin partagé. Cette page est le compagnon auto-hébergement — la construction concrète du courtier. Le public visé est quelqu’un à l’aise pour flasher une radio mais nouveau dans l’exploitation d’un serveur, alors chaque étape est détaillée. Une fois terminé, le pont internet de votre mesh se termine sur du matériel que vous contrôlez : pas de courtier partagé, pas d’identifiants partagés, pas de tiers qui lit votre arbre de topics. C’est le même instinct que faire tourner votre propre nœud Bitcoin — la pile de souveraineté fonctionne parce que chacune de ses couches vous appartient.

Sources : les champs du module Meshtastic sont cités avec leurs numéros de champ littéraux depuis meshtastic/protobufs → module_config.proto (MQTTConfig) et channel.proto; la disposition des topics est citée de meshtastic/firmware → src/mqtt/MQTT.h; les directives Mosquitto viennent des pages man mosquitto.conf(5) et mosquitto_passwd(1) sur mosquitto.org — le tout en date du 2026-07-22. Les chaînes citées restent en anglais parce que ce sont des citations littérales de ces sources.

Ce qu’il vous faut

• Une machine toujours allumée. Un Raspberry Pi, un serveur maison ou un petit VPS — tout ce qui fait tourner Linux et reste en ligne. MQTT est un protocole de publication/abonnement léger; la charge d’un mesh de loisir sur le courtier est minuscule.
• Mosquitto. Le courtier MQTT open-source du projet Eclipse Mosquitto. Sur Debian ou Ubuntu (y compris Raspberry Pi OS) :

  sudo apt install mosquitto mosquitto-clients
  sudo systemctl enable mosquitto

  mosquitto-clients vous donne mosquitto_sub et mosquitto_pub pour les tests.
• Au moins un nœud Meshtastic avec accès internet (Wi-Fi, Ethernet, ou le proxy du téléphone) pour servir de passerelle entre le LoRa et votre courtier.

Étape 1 Un mosquitto.conf minimal et verrouillé

Créez /etc/mosquitto/conf.d/mesh.conf :

# /etc/mosquitto/conf.d/mesh.conf
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl

Quatre directives, chacune avec un seul rôle — toutes tirées de la page man mosquitto.conf(5) :

• listener 1883 — « Listen for incoming network connection on the specified port. » 1883 est le port MQTT par défaut de Mosquitto. Sans listener explicite, les versions actuelles de Mosquitto n’acceptent que les connexions de la machine locale — en définir un est ce qui ouvre le courtier à vos nœuds passerelles, et c’est exactement pourquoi les trois lignes suivantes doivent l’accompagner.
• allow_anonymous false — « determines whether clients that connect without providing a username are allowed to connect. » La page man note qu’il vaut déjà false par défaut quand des listeners sont définis; nous l’énonçons explicitement pour que l’intention survive aux modifications de configuration.
• password_file — « If defined, the contents of the file are used to control client access to the broker »; avec allow_anonymous false, « only users defined in this file will be able to connect. »
• acl_file — « If defined, the contents of the file are used to control client access to topics on the broker. » Point crucial : « If this parameter is defined then only the topics listed will have access » — le fichier ACL refuse par défaut.

La documentation actuelle de Mosquitto suggère les greffons plus récents mosquitto_password_file et mosquitto_acl_file comme voie d’avenir pour le contrôle par listener; les directives classiques password_file / acl_file ci-dessus fonctionnent toujours et restent la configuration correcte la plus simple pour un courtier privé à un seul listener.

Étape 2 Créez les utilisateurs avec mosquitto_passwd

# first user — -c CREATES the file (and OVERWRITES it if it exists)
sudo mosquitto_passwd -c /etc/mosquitto/passwd meshgate

# additional users — no -c, or you wipe the file
sudo mosquitto_passwd /etc/mosquitto/passwd dashboard

# remove a user
sudo mosquitto_passwd -D /etc/mosquitto/passwd dashboard

Chaque commande demande le mot de passe interactivement. La page man déconseille l’option par lot -b pour l’usage courant parce que « the password will be visible on the command line and in command history. » Les mots de passe sont stockés hachés (Mosquitto utilise argon2id par défaut dans ses versions actuelles), et les noms d’utilisateur ne doivent pas contenir de deux-points. Un nom d’utilisateur par nœud passerelle est une base saine — si un appareil est perdu, vous révoquez ce seul identifiant.

Étape 3 Limitez l’ACL à votre topic racine

Meshtastic publie tout sous un topic racine — root (champ 8 de MQTTConfig), dont le commentaire de schéma dit : « The root topic to use for MQTT messages. Default is ‘msh’. This is useful if you want to use a single MQTT server for multiple meshtastic networks and separate them via ACLs » — ce qui est précisément ce que fait ce fichier. Créez /etc/mosquitto/acl :

# /etc/mosquitto/acl
# gateway nodes: full access to the mesh namespace, nothing else
user meshgate
topic readwrite msh/#

# read-only consumer (dashboard, logger)
user dashboard
topic read msh/#

Parce qu’un fichier ACL défini refuse par défaut, ces utilisateurs ne peuvent toucher que msh/# — un identifiant compromis ne peut pas errer dans d’autres arbres de topics. Les types d’accès sont read, write, readwrite et deny, et les topics acceptent les jokers habituels + et #. Deux meshes distincts sur un même courtier? Donnez à chacun son propre root sur les nœuds (disons msh-north et msh-south) et son propre bloc user + topic readwrite msh-north/# ici. La page man prend aussi en charge des règles pattern avec substitution %u (nom d’utilisateur) pour les installations multilocataires plus grandes. Puis redémarrez :

sudo systemctl restart mosquitto

Étape 4 Optionnel : TLS sur le port 8883

Sur un réseau local de confiance, le port 1883 en clair avec mots de passe et ACL est un départ raisonnable. Dès que le courtier est joignable par internet, ajoutez TLS. Selon la page man, certfile et keyfile « must be present to enable certificate based TLS encryption » sur un listener :

# append to /etc/mosquitto/conf.d/mesh.conf
listener 8883
certfile /etc/mosquitto/certs/fullchain.pem
keyfile /etc/mosquitto/certs/privkey.pem

8883 est le port conventionnel de MQTT sur TLS. La paire de certificats peut venir de Let’s Encrypt ou de votre propre autorité; cafile n’est nécessaire que si vous voulez en plus que le courtier vérifie les certificats clients. Les nœuds qui se connectent à ce listener activent tls_enabled (ci-dessous).

Étape 5 Pointez vos nœuds vers le courtier

Voici les réglages du module MQTT de Meshtastic, avec leurs numéros de champ littéraux depuis module_config.proto → MQTTConfig. Réglez-les depuis l’app ou le CLI Meshtastic sur chaque nœud passerelle (la colonne des citations reste en anglais — ce sont les commentaires littéraux du schéma) :

Champ (nº)	Type	Ce que dit le schéma (en anglais)	Réglage courtier privé
enabled (1)	bool	Turns the module on; the node “will normally attempt to gateway any channels that are marked as is_uplink_enabled or is_downlink_enabled.”	true sur les nœuds passerelles seulement.
address (2)	string	“The server to use for our MQTT global message gateway feature. If not set, the default server will be used” — i.e. the public broker.	Le nom d’hôte ou l’IP de votre courtier. Le laisser vide est ce qui envoie le trafic vers mqtt.meshtastic.org.
username (3)	string	“MQTT username to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty.”	L’utilisateur mosquitto_passwd de ce nœud.
password (4)	string	Same honouring rule as username.	Le mot de passe de cet utilisateur.
encryption_enabled (5)	bool	“Whether to send encrypted or decrypted packets to MQTT. This parameter is only honoured if you also set server.”	true — gardez les charges utiles des canaux chiffrées au repos sur votre courtier.
json_enabled (6)	bool	“Deprecated: JSON packet support on MQTT was removed, and this field is ignored.”	Laissez désactivé — voir la note JSON plus bas.
tls_enabled (7)	bool	“If true, we attempt to establish a secure connection using TLS.”	true si vous avez monté le listener 8883; désactivé pour du 1883 en clair sur le réseau local.
root (8)	string	“The root topic to use for MQTT messages. Default is ‘msh’.”	Laissez msh, ou choisissez une racine personnalisée qui correspond à votre ACL.
proxy_to_client_enabled (9)	bool	“If true, we can use the connected phone / client to proxy messages to MQTT instead of a direct connection.”	Utile quand le nœud lui-même n’a ni Wi-Fi ni Ethernet — l’app du téléphone porte la connexion au courtier.
map_reporting_enabled (10)	bool	“If true, we will periodically report unencrypted information about our node to a map via MQTT.”	Désactivé est le défaut privé — ce rapport est non chiffré par conception.
map_report_settings (11)	message	MapReportSettings: publish_interval_secs (1), position_precision (2, “default of 32 is full precision”), should_report_location (3).	Pertinent seulement si vous activez le rapport de carte sur votre propre courtier; gardez position_precision grossier.

Étape 6 Activez uplink/downlink par canal

Le module seul ne relie rien. Chaque canal porte deux interrupteurs dans channel.proto → ChannelSettings : uplink_enabled (champ 5 — les messages du mesh sortent par tout nœud passerelle) et downlink_enabled (champ 6 — « messages seen on the internet will be forwarded to the local mesh »). Les deux sont désactivés par défaut. N’activez-les que sur les canaux que vous voulez vraiment relier — un canal avec les deux désactivés ne touche jamais votre courtier.

Vérifiez que ça fonctionne

Depuis toute machine qui peut joindre le courtier, abonnez-vous avec un utilisateur autorisé et regardez les paquets arriver :

mosquitto_sub -h your.broker.example -u dashboard -P 'the-password' -t 'msh/#' -v

Envoyez un message texte sur un canal avec uplink activé et vous devriez voir des topics apparaître. La disposition est définie dans meshtastic/firmware → src/mqtt/MQTT.h : les paquets protobuf chiffrés publient sous /2/e/ (« msh/2/e/CHANNELID/NODEID » dans le commentaire de la source) et les rapports de carte sous /2/map/, chacun préfixé par votre topic racine. Les charges utiles sur le chemin /2/e/ sont des protobufs MeshPacket bruts — notre référence des champs MeshPacket documente chaque champ si vous voulez les décoder. Deux tests négatifs utiles : se connecter sans identifiants (doit être refusé) et s’abonner à un topic hors de msh/# avec un utilisateur restreint (doit rester silencieux).

Note JSON. En date du 2026-07-22, le schéma protobuf marque json_enabled obsolète — « JSON packet support on MQTT was removed, and this field is ignored » — alors que la source du micrologiciel contient toujours un chemin de topic /2/json/. Considérez la sortie JSON comme en voie de disparition : bâtissez vos intégrations sur le chemin protobuf /2/e/, pas sur les topics JSON.

Pourquoi c’est le défaut souverain

Le courtier public est une belle commodité communautaire, mais chaque paquet que vous y montez atterrit dans l’arbre de topics de quelqu’un d’autre, lisible sous des identifiants partagés. Un courtier Mosquitto privé inverse cela : votre passerelle, vos identifiants, votre ACL, votre disque. Jumelez-le au Store & Forward pour l’historique de messages hors ligne et vous avez un pont internet et un répondeur qui vivent tous deux sur du matériel qui vous appartient — l’équivalent, côté mesh, de faire tourner votre propre nœud au lieu de faire confiance à celui de quelqu’un d’autre. Pour ce que le pont expose et quand l’utiliser tout court, lisez le guide des concepts MQTT (en anglais); pour le côté radio, voir le chiffrement Meshtastic (en anglais) et le pôle mesh.

Pages reliées

Meshtastic via MQTT : concepts et compromis (en anglais — le compagnon de cette page) · Référence Store & Forward · Référence MeshPacket & Data · Rôles des nœuds Meshtastic (en anglais) · Régions et canaux LoRa (en anglais) · Balise Bitcoin via Meshtastic.

Crédit : Meshtastic et son module MQTT sont l’œuvre du projet Meshtastic (GPL-3.0), avec le schéma du module dans meshtastic/protobufs. Mosquitto est le courtier open-source du projet Eclipse Mosquitto; les directives ci-dessus viennent de ses pages man officielles. Cette page s’appuie sur les deux.