NetBird : VPN mesh WireGuard auto-hébergé et souverain

NetBird est un VPN mesh WireGuard open source (licence BSD-3) qui, contrairement à Headscale, fournit sa propre stack complète : agents, control plane, interface web et relais. Vous l'hébergez de bout en bout, sans dépendre d'aucun service tiers. Ce guide montre comment déployer le serveur (combined setup avec TLS automatique), enrôler des machines par paquet signé, accéder en SSH via le mesh, garder un accès de secours, et comprendre le plan d'adressage. Le tout testé sur une VM cloud réelle. Pour administrateurs et profils DevSecOps soucieux de souveraineté.

Ce que vous allez apprendre

• Déployer un serveur NetBird auto-hébergé avec TLS Let's Encrypt automatique.
• Enrôler des machines proprement (dépôt de paquets signé, pas de script piped).
• Vérifier le mesh et accéder en SSH à un serveur via le tunnel.
• Garder un accès de secours pour ne pas vous verrouiller dehors.
• Personnaliser le plan d'adressage (CIDR au choix, hors CGNAT).

Prérequis

NetBird en self-hosted impose une contrainte ferme : le serveur doit être joignable depuis Internet pour émettre son certificat.

• une VM publique (1 vCPU / 2 Go suffisent d'après la doc) sous Linux ;
• un nom de domaine qui résout vers l'IP publique de la VM (ex. netbird.exemple.fr) ;
• les ports ouverts : TCP 80 et 443 (dashboard, API, relais, Let's Encrypt) et UDP 3478 (STUN/TURN, ne passe pas par le reverse proxy) ;
• Docker avec le plugin compose v2, plus jq et curl.

Le port 3478/UDP est obligatoire

Le STUN/TURN (Coturn) écoute en UDP 3478 et ne peut pas transiter par un reverse proxy HTTP. Sans ce port ouvert, seuls les pairs d'un même réseau local pourraient communiquer. Pensez à l'autoriser dans votre pare-feu ou Security Group cloud, en plus du 80 et du 443.

Qu'est-ce que NetBird ?

NetBird crée un réseau maillé où chaque machine (un peer) reçoit une IP privée stable et parle aux autres en pair-à-pair chiffré par WireGuard, sans ouvrir de port entrant sur chaque machine. La traversée des NAT se fait par hole punching (via le service Signal et le STUN), avec repli sur un relais quand la connexion directe échoue.

Le combined setup (recommandé pour débuter) regroupe tout dans un conteneur unifié netbird-server :

• Management : le control plane (inventaire, ACL, configuration) ;
• Signal : l'échange des informations de connexion entre pairs ;
• Relay et Coturn : le relayage chiffré et le STUN/TURN ;
• un fournisseur d'identité (IdP) embarqué pour les comptes.

Un conteneur Traefik gère le TLS, un conteneur dashboard sert l'interface web.

NetBird, Tailscale ou Headscale ?

Les trois reposent sur WireGuard, mais ne se positionnent pas pareil.

	Tailscale	Headscale	NetBird
Control plane	SaaS propriétaire	self-host (BSD-3)	self-host (BSD-3)
Clients	Tailscale	clients Tailscale	agents NetBird propres
Interface web	oui (SaaS)	non (CLI)	oui, intégrée
Relais	DERP Tailscale	DERP Tailscale	relais maison

Glissez pour voir

Là où Headscale réutilise les clients Tailscale (et reste dépendant de leur écosystème), NetBird apporte une stack 100 % indépendante avec son interface de gestion et son SSO intégré. C'est l'option la plus souveraine quand on veut tout garder en interne. Pour le control plane qui garde l'écosystème Tailscale, voir le guide Tailscale et Headscale.

Déployer le serveur NetBird

Le script officiel getting-started.sh génère les secrets, écrit le docker-compose.yml et démarre la pile. On le télécharge et on l'inspecte avant de l'exécuter (jamais en curl | bash à l'aveugle).

1. Créer l'enregistrement DNS : un A de netbird.exemple.fr vers l'IP publique de la VM. Vérifiez la propagation :

   dig +short netbird.exemple.fr

2. Récupérer et lire le script :

   curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh -o getting-started.sh
   less getting-started.sh   # on inspecte avant d'exécuter

3. Lancer le déploiement en lui passant le domaine :

   export NETBIRD_DOMAIN=netbird.exemple.fr
   bash getting-started.sh

   Le script pose deux questions : le reverse proxy (choisissez 0 Traefik, qui gère le TLS Let's Encrypt automatiquement) et un email pour Let's Encrypt.

L'email Let's Encrypt est devenu une formalité

Le script réclame un email pour Let's Encrypt, mais sachez que Let's Encrypt a cessé d'envoyer les notifications d'expiration le 4 juin 2025. Vous ne recevrez donc aucune alerte avant expiration : le renouvellement repose entièrement sur l'automatisation de Traefik. L'email ne sert plus qu'à un éventuel contact exceptionnel.

Vérifier le déploiement

Trois conteneurs doivent tourner, et le dashboard doit répondre en HTTPS avec un certificat valide.

docker ps --format "{{.Names}}  {{.Status}}"
# netbird-traefik    Up ...
# netbird-dashboard  Up ...
# netbird-server     Up ...

Testez l'accès et le certificat depuis l'extérieur :

curl -sS -o /dev/null -w "HTTP %{http_code}\n" https://netbird.exemple.fr/
# HTTP 200

Ouvrez ensuite https://netbird.exemple.fr dans un navigateur : l'IdP embarqué vous fait créer le compte administrateur au premier accès.

Enrôler une machine (peer)

L'erreur classique serait d'installer le client par un script piped. On utilise le dépôt de paquets signé (clé GPG vérifiée), seule méthode propre qui installe aussi le service systemd.

Debian / Ubuntu

# clé GPG signée (import de clé, pas un script exécuté)
curl -sSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/netbird-archive-keyring.gpg

# dépôt signé
echo 'deb [signed-by=/usr/share/keyrings/netbird-archive-keyring.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list

sudo apt-get update
sudo apt-get install netbird

RHEL / Fedora

sudo tee /etc/yum.repos.d/netbird.repo <<'EOF'
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
sudo dnf install netbird

Le binaire seul ne suffit pas

Installer NetBird via un simple téléchargeur de binaires (par exemple un gestionnaire de versions) pose le binaire mais pas le service : netbird up échoue alors avec config error: --config is required, car il ne trouve pas le daemon. Le paquet du dépôt installe et démarre le service systemd, ce qui résout le problème.

Créez ensuite une clé d'enrôlement dans le dashboard : Settings → Setup Keys → Create Setup Key, type Reusable.

Connectez la machine à votre management :

sudo netbird up --management-url https://netbird.exemple.fr --setup-key <VOTRE_CLE>

Vérifier le mesh

Sur chaque machine, netbird status confirme l'état des connexions :

sudo netbird status --detail

Vous y lisez l'IP NetBird de la machine (dans 100.x), l'état Management: Connected, et la liste des pairs avec leur statut. Un Peers count: 1/1 Connected signale que le tunnel est établi. Validez le transit avec un test applicatif entre deux pairs (un service qui écoute d'un côté, une connexion de l'autre via l'IP NetBird).

Accéder en SSH à un serveur via le mesh

C'est le cas d'usage roi : joindre un serveur sans exposer son port 22 sur Internet. Une fois le serveur enrôlé comme peer, son sshd répond aussi sur l'interface NetBird (wt0). Depuis une autre machine du réseau :

ssh utilisateur@<IP-NetBird-du-serveur>

Le trafic passe par le tunnel chiffré : le serveur voit la connexion arriver depuis l'IP NetBird du client, route via wt0. Vous pouvez alors fermer le port 22 public, à condition de garder un accès de secours (voir ci-dessous).

Sécurité : toujours un accès de secours

Ne faites jamais du mesh votre unique porte d'entrée, surtout sur du cloud. Si NetBird tombe (service en panne, ACL mal configurée qui vous coupe, clé révoquée, mise à jour ratée), vous vous verrouillez dehors.

Gardez un chemin de reprise indépendant du mesh :

• un SSH out-of-band en liste blanche : port 22 ouvert uniquement à votre IP d'administration ou un bastion, jamais au monde entier. Il ne dépend pas de NetBird ;
• l'accès console du fournisseur cloud, filet ultime si SSH et NetBird tombent (vous coupez le réseau par erreur).

L'anti-pattern « zero-trust » serait de fermer le 22 public et de tout faire passer par NetBird : un incident sur le mesh devient alors un blocage total. Le bon compromis : 22 fermé au monde mais ouvert à votre IP en secours, NetBird pour l'usage courant.

Choisir son plan d'adressage : un vrai atout de NetBird

Par défaut, NetBird attribue à chaque réseau un sous-réseau /16 tiré dans 100.64.0.0/10, le bloc CGNAT (RFC 6598) ; vos machines reçoivent donc des adresses comme 100.98.x.x.

Mais contrairement à Tailscale et Headscale, vous n'êtes pas prisonnier de ce range. Dans Settings → Networks → Network Range, vous saisissez votre propre CIDR (par exemple 10.9.1.0/24) : les IP des peers sont réallouées au changement. Vous pouvez aussi définir un DNS Domain interne personnalisé dans la même page.

Solution	Plan d'adressage	Personnalisable ?
Tailscale	100.64.0.0/10 (CGNAT)	non, client hardcodé
Headscale	sous-ensemble du CGNAT	non, réutilise le client Tailscale
NetBird	CGNAT par défaut, tout CIDR au choix	oui (Settings → Networks)

Glissez pour voir

Là où le client Tailscale impose le CGNAT (et donc Headscale aussi, puisqu'il réutilise ce client), NetBird gère sa propre stack et accepte n'importe quel CIDR privé. Si votre infrastructure utilise déjà du 100.64.x, ou si vous voulez aligner le mesh sur votre plan d'adressage maison, NetBird est le seul des trois à le permettre. C'est un argument décisif côté souveraineté de l'adressage.

Ce réglage est aussi disponible via l'API (PUT /api/accounts/{id}, champ network_range), pratique pour l'industrialiser en IaC. Voir la référence API NetBird.

À retenir

• NetBird est un VPN mesh WireGuard BSD-3, à stack complète et auto-hébergeable de bout en bout.
• Le serveur exige une VM publique, un domaine, et les ports 80/443 TCP + 3478 UDP.
• Le combined setup (getting-started.sh, reverse proxy Traefik) gère le TLS Let's Encrypt seul.
• Enrôlez les machines par dépôt de paquets signé (jamais curl | sh, le binaire seul ne pose pas le service).
• Une setup key (Settings → Setup Keys, Reusable) puis netbird up --management-url … --setup-key ….
• Le SSH via le mesh évite d'exposer le port 22, mais gardez toujours un accès de secours out-of-band.
• Le plan d'adressage est personnalisable (Settings → Networks → Network Range, tout CIDR), un atout face à Tailscale et Headscale verrouillés sur le CGNAT.

FAQ : questions fréquentes sur NetBird

Qu'est-ce que NetBird ?

NetBird est un VPN mesh WireGuard open source (BSD-3) entièrement auto-hébergeable. Contrairement à Headscale qui réutilise les clients Tailscale, il fournit sa propre stack : agents, control plane, interface web et relais. Les machines communiquent en pair-à-pair chiffré.

Quelle différence entre NetBird et Tailscale ?

Tailscale repose sur un control plane SaaS propriétaire et ses propres clients. NetBird est entièrement open source (BSD-3) et auto-hébergeable, avec ses propres agents, son interface web et ses relais. NetBird vise la souveraineté complète ; Tailscale la simplicité du service managé.

Comment installer le client NetBird proprement ?

Via le dépôt de paquets signé : on importe la clé GPG, on ajoute le dépôt apt ou dnf, puis on installe le paquet netbird. Cette méthode pose aussi le service systemd, contrairement à un simple binaire. On évite le curl piped vers un shell. Ensuite on connecte la machine avec netbird up.

Quels ports ouvrir pour héberger NetBird ?

Pour un serveur NetBird self-hosted en combined setup : TCP 80 (Let's Encrypt et redirection), TCP 443 (dashboard, API, signal, relais) et UDP 3478 (Coturn STUN/TURN). Le port 3478 en UDP est obligatoire et ne peut pas passer par un reverse proxy HTTP.

Peut-on choisir le plan d'adressage IP de NetBird ?

Oui. Par défaut NetBird utilise un /16 dans 100.64.0.0/10 (CGNAT), mais on peut définir sa propre plage dans Settings, Networks, Network Range, au format CIDR (ex 10.9.1.0/24), hors CGNAT. Un avantage face à Tailscale et Headscale, verrouillés sur le CGNAT.

NetBird est-il open source ?

Oui, NetBird est open source sous licence BSD-3, une licence permissive qui autorise l'usage commercial sans restriction. Tout le code (agents, management, signal, relay, dashboard) est sur GitHub et auto-hébergeable. Une offre cloud managée existe, mais le self-host reste complet.

Prochaines étapes

Tailscale et Headscale Le control plane souverain qui garde l'écosystème Tailscale.

Teleport : accès aux infrastructures Accès zero-trust à SSH, Kubernetes et bases de données avec audit.

Sécuriser les accès La vue d'ensemble des outils d'accès zero-trust et PAM.

×

📖 Voir la documentation →