NetBird : construire un réseau privé peer-to-peer avec WireGuard et Zero Trust

Overview

NetBird est un projet open source (licence BSD-3 / AGPLv3) écrit en Go, qui combine un agent client, un service de Management, un Signal service et un Relay service pour créer un réseau privé mesh. Chaque machine devient un peer du réseau et se connecte aux autres via des tunnels WireGuard chiffrés point-à-point, sans passer par un concentrateur VPN central (README GitHub: https://github.com/netbirdio/netbird).

Le projet compte plus de 26 000 étoiles sur GitHub, 339 releases, et une communauté active. La version stable la plus récente est la v0.73.2 (juin 2026). Il est soutenu par le programme StartUpSecure du ministère fédéral allemand de la Recherche, en collaboration avec le CISPA Helmholtz Center for Information Security (README GitHub).

Objectif

L’objectif de NetBird est de remplacer les VPN d’entreprise traditionnels (OpenVPN, IPsec, concentrateurs SSL) par un maillage pair-à-pair qui :

• supprime le goulot d’étranglement du serveur central (tout le trafic passe directement entre les machines)
• élimine la gestion manuelle des clés et des configurations firewall
• applique un contrôle d’accès Zero Trust basé sur l’identité, les groupes et les règles
• s’intègre aux fournisseurs d’identité (SSO OIDC, MFA)
• fonctionne sur n’importe quelle infrastructure (cloud, on-premise, edge, homelab)

Le tout sans exposer de ports sur Internet et sans configuration réseau complexe.

Liens utiles

• Depot principal GitHub
• Site officiel
• Documentation officielle
• Releases et changelog
• Guide d’auto-hebergement rapide (5 min)
• Architecture et fonctionnement
• Documentation API
• Forum communautaire
• Slack NetBird
• WireGuard (protocole sous-jacent)
• Pion ICE (WebRTC)
• Rosenpass (chiffrement post-quantique)
• Terraform provider NetBird
• Ansible collection NetBird
• NetBird Cloud (version managed)

Installation

L’installation de NetBird se fait de deux manières : via le cloud managé (SaaS) ou en auto-hébergement complet.

Client (agent)

Le client s’installe sur chaque machine qui doit rejoindre le réseau. La page d’installation officielle est accessible sur https://app.netbird.io/install. NetBird supporte Linux, macOS, Windows, Android, iOS, FreeBSD, pfSense, OPNsense, MikroTik RouterOS, OpenWRT, Synology, TrueNAS, Proxmox, Raspberry Pi, et les containers Docker (docs: https://docs.netbird.io/get-started).

Exemple d’installation sur Linux :

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/install.sh | sh

Auto-hebergement du control plane

Prérequis (docs: https://docs.netbird.io/selfhosted/selfhosted-quickstart) :

• VM Linux (1 CPU, 2 Go RAM minimum)
• Domaine public pointant vers la VM
• Ports TCP 80, 443 et UDP 3478 ouverts
• Docker avec docker-compose plugin

Installation :

export NETBIRD_DOMAIN=netbird.example.com
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Le script déploie automatiquement les services Management, Signal, Relay, ainsi qu’un reverse proxy Traefik avec certificats Let’s Encrypt. Un assistant de premier démarrage est accessible sur https://netbird.example.com pour créer le compte admin.

Version Cloud (SaaS)

Il suffit de créer un compte sur https://app.netbird.io, d’installer l’agent sur chaque machine, et de s’authentifier via Google, Microsoft, GitHub ou email.

Notions et concepts

WireGuard

WireGuard est un protocole VPN moderne, intégré au noyau Linux, qui utilise la cryptographie la plus récente (Curve25519, ChaCha20, Poly1305). NetBird s’appuie sur WireGuard pour le chiffrement du trafic entre les peers. Chaque client génère une paire de clés : la clé privée ne quitte jamais la machine (docs: https://docs.netbird.io/about-netbird/how-netbird-works).

Mesh VPN / Overlay Network

Contrairement aux VPN hub-and-spoke où tout le trafic passe par un serveur central, NetBird crée un maillage : chaque machine se connecte directement aux autres via des tunnels WireGuard. Il n’y a pas de point de défaillance unique ni de goulot d’étranglement (Source: KX Cloudingenium – https://kx.cloudingenium.com/en/netbird-self-hosted-wireguard-mesh-vpn-zero-config/).

Management Service

Le service central qui maintient l’état du réseau : attribution des IP, distribution des clés publiques, synchronisation des changements, logs d’activité. Il expose une interface Web (dashboard) et une API REST. Chaque peer maintient un canal de contrôle permanent avec le Management (docs: https://docs.netbird.io/about-netbird/how-netbird-works).

Signal Service

Service léger de signalisation qui permet aux peers d’échanger leurs candidats de connexion (adresses IP:port) avant d’établir un tunnel direct. Les messages sont chiffrés de bout en bout. Une fois la connexion établie, Signal n’intervient plus (docs: https://docs.netbird.io/about-netbird/how-netbird-works).

Relay Service (fallback TURN/WebSocket)

Lorsque la traversée NAT échoue (double NAT, CGNAT mobile), NetBird bascule automatiquement sur un relay. Le trafic relayé reste chiffré par WireGuard, le relay ne peut pas le déchiffrer. Depuis la v0.29.0, un relay WebSocket natif remplace progressivement Coturn (docs: https://docs.netbird.io/about-netbird/how-netbird-works).

NAT Traversal

NetBird utilise ICE (Interactive Connectivity Establishment) via la bibliothèque Pion ICE, avec des serveurs STUN pour découvrir les adresses publiques des peers. La traversée NAT est entièrement automatique et ne nécessite aucune configuration manuelle (docs: https://docs.netbird.io/about-netbird/understanding-nat-and-connectivity).

Access Control (Zero Trust)

Les accès sont définis par des règles basées sur l’identité, les groupes, les tags et les vérifications de conformité (posture checks). Par défaut, aucun accès n’est autorisé : tout doit être explicitement défini. Les accès SSH peuvent également être centralisés via des politiques (docs: https://docs.netbird.io/how-to/manage-network-access).

Private DNS

NetBird attribue automatiquement un FQDN à chaque peer (format <name>.netbird.cloud) et gère les zones DNS personnalisées, les serveurs de noms privés, et les alias DNS pour les réseaux routés (docs: https://docs.netbird.io/how-to/manage-dns-in-your-network).

Commandes

Ces commandes sont extraites de la documentation officielle et du README du projet.

Client CLI

# Afficher le statut de la connexion NetBird
netbird status

# Se connecter au management (interactif ou avec setup key)
netbird up
netbird up --setup-key <key>

# Se déconnecter
netbird down

# Afficher les peers accessibles
netbird status --detail

# Lancer avec un profil specifique
netbird up --profile mon-profil

Auto-hebergement (Docker)

# Lancer l'installation guidee
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

# Gerer les services
docker compose ps
docker compose logs -f
docker compose pull
docker compose up -d

API (extrait de la documentation : https://docs.netbird.io/api)

# Lister les peers
curl -H "Authorization: Token <PAT>" https://<votre-domaine>/api/peers

# Creer une regle d'acces
curl -X POST -H "Authorization: Token <PAT>" \
  -H "Content-Type: application/json" \
  https://<votre-domaine>/api/rules \
  -d '{"name": "acces-dev", "enabled": true, "source": ["grp-dev"], "destination": ["grp-serveurs"]}'

Demo

Cette demo suit le workflow d’auto-hebergement décrit dans la documentation officielle (https://docs.netbird.io/selfhosted/selfhosted-quickstart) puis l’ajout de deux machines clientes.

1. Preparation du serveur de management

Provisionner une VM Linux (Debian/Ubuntu) avec 1 CPU et 2 Go RAM. Ouvrir les ports TCP 80/443 et UDP 3478. Pointer un domaine (ex: netbird.mondomaine.fr) vers l’IP publique de la VM.

2. Lancement de l’installation

export NETBIRD_DOMAIN=netbird.mondomaine.fr
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Le script demande de choisir un reverse proxy. Selectionner l’option [0] (Traefik, recommandé). Il propose ensuite d’activer le proxy NetBird : répondre y pour exposer des services internes plus tard.

Le script genere les fichiers suivants dans le repertoire courant :

• docker-compose.yml
• config.yaml
• dashboard.env
• proxy.env (si proxy active)

3. Premier acces au dashboard

Ouvrir https://netbird.mondomaine.fr. Le premier acces redirige vers /setup pour creer le compte administrateur (email, nom, mot de passe). Apres validation, le dashboard affiche la liste des peers (vide pour l’instant), les parametres reseau, et les regles d’acces.

4. Ajout des machines clientes

Installer l’agent NetBird sur deux machines :

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/install.sh | sh

Lancer la connexion :

sudo netbird up --setup-key <cle_generee_dans_le_dashboard>

L’agent genere ses cles WireGuard, s’enregistre aupres du Management, recoit une IP privee (plage 100.64.0.0/10), et apparait dans le dashboard.

5. Verification du maillage

Depuis la machine A :

netbird status

La sortie affiche la liste des peers, leurs IP, leur etat de connexion. Si les peers sont en Connected, le tunnel WireGuard est etabli directement entre les machines.

Verifier la connectivite :

ping 100.64.x.y

6. Ajout d’une regle d’acces

Dans le dashboard, creer :

• un groupe dev contenant les deux machines
• une regle d’acces qui autorise tout le trafic entre les membres de dev

La regle est poussee automatiquement vers les agents, qui l’appliquent via nftables (ou l’equivalent sur macOS/Windows).

7. Passage en mode relay (fallback)

Si les deux machines sont derriere un double NAT qui empeche la connexion directe (ex: reseau mobile), le trafic bascule automatiquement par le Relay service. Le tunnel reste chiffre de bout en bout. Le dashboard indique alors Relay comme type de connexion.

8. Sortie et exploration

Le dashboard expose en temps reel :

• la liste complete des peers avec leur OS et version
• les logs d’evenements (connexion, deconnexion, changements de regles)
• les statistiques de trafic pour chaque peer
• les verifications de conformite (posture checks : OS a jour, firewall actif, antivirus)

Conclusion

NetBird est un projet open source mature qui simplifie radicalement la creation de reseaux prives securises. Il combine la puissance de WireGuard avec une orchestration Zero Trust, un auto-hebergement possible en 5 minutes, et une compatibilite tres large (du Raspberry Pi au serveur cloud). Son architecture mesh elimine les points de defaillance uniques des VPN traditionnels tout en offrant un controle d’acces granulaire. La version cloud permet un demarrage immediat, tandis que la version auto-hebergee conserve la maitrise totale des donnees et de l’infrastructure. Les sources utilisees pour cet article sont le README GitHub, la documentation officielle, le site produit, et des analyses complementaires (KX Cloudingenium, Infralovers).