WireGuard P2P, Headscale, Netbird : trois angles différents
WireGuard statique (voir notre guide WireGuard P2P) exige de distribuer une paire de clés par tunnel et d'éditer /etc/wireguard/wg0.conf à chaque nouvel homologue. Efficace pour deux ou trois serveurs fixes — ingérable à l'échelle d'un parc d'agence.
Headscale réimplémente le serveur de coordination Tailscale : vous gardez les clients Tailscale officiels et obtenez un réseau plat illimité en utilisateurs. Un seul réseau par instance, sans isolation native entre clients différents. C'est le bon choix pour une équipe unique qui veut rester dans l'écosystème Tailscale.
Netbird prend le parti inverse : il apporte son propre client, son propre plan de contrôle (Management + Signal + relay) et une notion de réseau nommé avec règles d'accès granulaires. Une instance unique peut héberger plusieurs réseaux entièrement isolés — ce qui en fait l'outil naturel pour une agence qui gère des parcs clients séparés. L'interface web est incluse d'emblée.
Architecture Netbird : quatre composants
Un déploiement Netbird auto-hébergé repose sur quatre composants, tous fournis dans le même dépôt (netbirdio/netbird) :
Management Server — le cerveau du plan de contrôle. Il distribue les clés WireGuard, applique les règles d'accès et expose l'API REST que l'interface web interroge. Stockage SQLite par défaut, MySQL ou PostgreSQL en option.
Signal Server — le serveur de signalisation pair à pair. Il facilite l'échange de descripteurs de connexion ICE entre les nœuds au moment de l'établissement du tunnel WireGuard. Aucun trafic applicatif ne le traverse.
COTURN — le serveur relay STUN/TURN. Il sert de relais lorsqu'une connexion directe entre deux pairs est impossible (double NAT, réseau d'entreprise restrictif). Le trafic ne passe par COTURN que lorsque la tentative directe échoue.
Dashboard — l'interface web (SPA React) qui consomme l'API Management. Elle permet de créer des réseaux, d'ajouter des peers, de définir des règles d'accès et de générer des clés d'enrôlement sans toucher à la ligne de commande.
Tous les flux entre clients passent en WireGuard chiffré bout en bout — Management et Signal ne voient que les métadonnées d'enrôlement, jamais le trafic applicatif.
Prérequis
VPS dédié au plan de contrôle. Prévoyez un VPS distinct de vos nœuds clients : 2 vCPU, 2 Go de RAM minimum. Un VPS {{vps.start.name}} convient pour démarrer.
Ports à ouvrir sur le VPS de contrôle :
443 (TCP) — Management et Dashboard derrière un reverse proxy HTTPS.3478 (UDP) — COTURN STUN/TURN.49152-65535 (UDP) — plage dynamique COTURN pour les sessions relay.
Les nœuds clients n'ont aucun port entrant à ouvrir : le client Netbird établit des connexions sortantes vers le plan de contrôle.
Logiciels requis sur le VPS de contrôle : Docker Engine 24+ et Docker Compose v2, un nom de domaine pointant vers l'IP du VPS, et un certificat TLS (Let's Encrypt via le script fourni ou votre reverse proxy habituel).
Sur chaque nœud client : le binaire netbird (paquet Debian/RPM ou binaire statique), accès root ou sudo.
Déployer le plan de contrôle et raccorder trois nœuds
Cloner le dépôt et lancer le script de démarrage
Sur le VPS de contrôle, récupérez le script officiel de Netbird et laissez-le générer la stack Docker Compose complète :
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh -o getting-started.sh
bash getting-started.shLe script vous demande votre domaine (ex. netbird.votre-domaine.com), génère docker-compose.yml, config.yaml, dashboard.env et la configuration COTURN, puis lance la stack. À la fin il affiche l'URL de l'interface web et un premier Setup Key — conservez-le.
Vérifier que les quatre services répondent
Une fois le script terminé, confirmez que les conteneurs sont bien debout :
docker compose psVous devez voir quatre services running : netbird-management, netbird-signal, netbird-coturn et netbird-dashboard. Testez le Management depuis le VPS lui-même :
curl -s https://netbird.votre-domaine.com/api/v1/peers \
-H 'Authorization: Token <votre-PAT>'Une réponse JSON vide [] confirme que le service répond et qu'aucun pair n'est encore enrôlé.
Créer un réseau et un Setup Key dans l'interface web
Ouvrez https://netbird.votre-domaine.com dans un navigateur. Connectez-vous avec le compte créé pendant le setup (ou via le fournisseur OIDC configuré).
Dans le menu Setup Keys, cliquez Create Setup Key. Donnez-lui un nom (vps-client-a), choisissez le type Reusable (pour enrôler plusieurs machines avec la même clé) et une durée d'expiration. Copiez la clé — vous en aurez besoin sur chaque nœud.
Enrôler le nœud 1
Sur le premier VPS client, installez le client Netbird :
curl -fsSL https://pkgs.netbird.io/install.sh | bashPuis raccordez-le au plan de contrôle en pointant vers votre instance :
netbird up \
--management-url https://netbird.votre-domaine.com \
--setup-key <VOTRE_SETUP_KEY>Confirmez la connexion :
netbird statusVous devez lire Status: Connected et une IP mesh dans la plage 100.64.x.x attribuée par votre serveur.
Enrôler les nœuds 2 et 3
Répétez exactement la même procédure sur les deux autres VPS clients. Même commande curl pour installer le client, même commande netbird up avec le même --management-url et la même --setup-key (si elle est de type Reusable).
Une fois les trois nœuds enrôlés, vérifiez depuis le nœud 1 que les pairs sont visibles :
netbird status --detailLa sortie liste chaque pair avec son IP mesh, son état (Connected ou Connecting) et sa latence.
Tester la connectivité mesh sans port public ouvert
Avant de tester, vérifiez l'état du pare-feu sur le nœud 1 — aucun port entrant ne doit être ouvert vers les autres nœuds :
sudo ufw status numberedSeul le port SSH (22) doit apparaître. Maintenant, pinguez le nœud 2 via son IP mesh (visible dans netbird status --detail, ex. 100.64.0.2) :
ping -c 3 100.64.0.2Le ping traverse le tunnel WireGuard établi entre les pairs. Si les deux nœuds sont derrière un NAT strict, COTURN assure le relay — le ping fonctionne dans les deux cas sans aucune règle UFW supplémentaire.
Vérifier les connexions directes vs relay
Pour distinguer une connexion directe d'un passage par COTURN :
netbird status --detailLa colonne Connection type affiche P2P pour une connexion directe ou Relayed lorsque COTURN intervient. P2P est l'état nominal entre deux VPS avec des IPv4 publiques directes. Relayed indique que Netbird a dû passer par le serveur COTURN — vérifiez alors que les ports UDP 3478 et la plage 49152-65535 sont bien accessibles depuis les nœuds.
Isolation multi-clients : peers groups et règles d'accès
La force de Netbird face à Headscale est sa notion de réseau isolé par groupe. Par défaut, tous les peers enrôlés avec la même Setup Key rejoignent un groupe commun. Pour isoler les serveurs d'un client A des serveurs d'un client B :
1. Créez un groupe par client dans l'interface web (Networks → Groups → Add Group). Nommez-les client-a, client-b.
2. Assignez chaque peer à son groupe. Dans la fiche du peer, section Assigned Groups, ajoutez le groupe correspondant et retirez le groupe All si vous ne voulez pas de communication inter-groupes.
3. Définissez les règles d'accès (Access Control → Policies). Une politique client-a-interne autorise le trafic entre peers du groupe client-a. Aucune règle n'est créée entre client-a et client-b : les deux réseaux sont hermétiques.
Vous pouvez aussi définir des Network Routes : un peer joue le rôle de routeur pour un sous-réseau privé (ex. 192.168.10.0/24) et expose ce réseau aux autres peers du groupe, sans que ceux-ci aient besoin d'un client Netbird installé sur chaque machine du sous-réseau.
Opérations courantes
Renouveler ou révoquer une Setup Key. Dans l'interface web, Setup Keys → votre clé → Revoke. Les peers déjà enrôlés conservent leur connexion ; les nouvelles tentatives d'enrôlement avec cette clé seront refusées. Créez une nouvelle clé pour les prochains enrôlements.
Révoquer un peer. Peers → sélectionnez le peer → Delete. Le nœud est immédiatement retiré du mesh. Côté client, netbird status passe à Disconnected et les tunnels WireGuard vers ce pair sont détruits.
Accès API pour l'automatisation. Netbird expose une API REST documentée. Générez un Personal Access Token (Settings → Access Tokens) et pilotez l'ensemble depuis vos scripts Ansible ou vos pipelines CI :
curl -s https://netbird.votre-domaine.com/api/v1/peers \
-H 'Authorization: Token <PAT>'Monitoring. Le Management Server expose des métriques Prometheus sur /metrics. Branchez Grafana sur cet endpoint pour suivre le nombre de peers connectés, les sessions COTURN actives et la latence de signalisation.
Durcissement : 2FA sur le Dashboard et sauvegarde de la base Management
Le Dashboard Netbird supporte OIDC (Keycloak, Authentik, Azure AD) — activez-le pour imposer la MFA à tous les administrateurs du plan de contrôle. Sans SSO, le compte local reste protégé par mot de passe uniquement.
La base de données SQLite du Management Server est le seul état persistant de votre réseau : perdre ce fichier signifie réenrôler tous vos pairs. Montez un volume Docker nommé (netbird_management) et sauvegardez-le quotidiennement :
docker run --rm \
-v netbird_management:/data \
-v /opt/backups:/backup \
alpine tar czf /backup/netbird-$(date +%Y%m%d).tar.gz /dataRotation des sauvegardes à 7 jours minimum.
Dépannage
COTURN inaccessible — les peers restent en Relayed ou ne se connectent jamais.
Vérifiez que les ports UDP 3478 et la plage 49152-65535 sont ouverts dans le pare-feu du VPS de contrôle (ufw status). Testez depuis un nœud client : nc -u -z netbird.votre-domaine.com 3478. Absence de réponse = trafic filtré. Sur certains hébergeurs, les plages UDP larges sont bloquées par défaut — ouvrez-les explicitement.
Peer bloqué en Connecting.
Cela indique une communication Management/Signal réussie (le peer s'est enrôlé) mais une impossibilité de former le tunnel WireGuard. Causes fréquentes : l'IP publique du VPS de contrôle est mal renseignée dans config.yaml (champ --turn-external-ip de COTURN), ou les ports UDP de la plage dynamique sont fermés. Relancez le script getting-started.sh avec --external-ip explicite si le VPS est derrière un NAT.
Résolution DNS échoue entre peers.
Netbird intègre un résolveur DNS qui distribue les noms <hostname>.netbird.cloud à chaque pair. Si ping nœud2.netbird.cloud échoue alors que ping 100.64.0.2 fonctionne, vérifiez que le service netbird est bien en cours d'exécution sur le peer (systemctl status netbird) et que son DNS est actif : resolvectl status | grep netbird.
Double NAT — aucune connexion directe, COTURN surcharge.
Si les deux pairs sont derrière un NAT strict (typiquement : VPS cloud derrière un load balancer hébergeur), les connexions directes WireGuard sont impossibles et tout le trafic passe par COTURN. Solution : assurez-vous que le VPS de contrôle a une IPv4 publique directe et que --turn-external-ip pointe vers cette IP. Pour les nœuds clients derrière NAT strict, rien à faire — COTURN est précisément conçu pour ce cas.
Mise à jour de la stack — nœuds temporairement déconnectés.
Une mise à jour du Management Server déconnecte les peers pendant quelques secondes, le temps du redémarrage du conteneur. Planifiez les mises à jour hors fenêtre de trafic, ou activez l'option restart: always sur tous les conteneurs pour minimiser le temps d'arrêt.
Ce que le mesh change pour la gestion de parc
Un réseau mesh Netbird auto-hébergé remplace trois couches que vous maintieniez à la main : la distribution de clés WireGuard, les règles UFW inter-serveurs et la documentation des accès croisés. Chaque nouveau VPS client s'enrôle en une commande ; chaque révocation est instantanée et centrale.
L'isolation par groupe vous permet de grandir sans risque de collision : les serveurs de deux clients différents ne peuvent pas se voir, même s'ils tournent sur la même infrastructure. Et le plan de contrôle reste sous votre maîtrise — aucune dépendance à un SaaS tiers, aucune limite de seats, aucun abonnement par nœud.
Pour aller plus loin, couchez le provisionnement des nœuds dans Ansible (voir notre guide Ansible) : l'installation du client et la commande netbird up deviennent des tâches idempotentes dans un rôle réutilisable.
