NetBird : un VPN mesh open source et auto-hébergé pour accéder à son réseau à distance

Accéder à tout votre homelab depuis n'importe où, même en 5G, sans ouvrir un seul port sur votre box : c'est la promesse de NetBird, un VPN maillé open source basé sur WireGuard. Dans le même esprit que Tailscale, il crée un réseau privé entre vos appareils, avec une différence de taille : tout est open source, y compris le serveur qui orchestre le réseau. Vous pouvez donc l'héberger vous-même, sans dépendre d'un service tiers.

Dans ce tutoriel, je vous propose d'installer un serveur NetBird auto-hébergé sur un VPS avec Docker, puis de déployer le client NetBird sur plusieurs machines. L'une d'elles, un conteneur LXC sur Proxmox VE, servira de passerelle vers le réseau local : elle donnera accès à un serveur web et à l'interface d'administration de Proxmox, sans installer d'agent sur ces machines. Par la suite, nous verrons comment verrouiller les accès avec des règles zero trust, comment fonctionne le Control Center, puis comment publier un service sur Internet avec le reverse proxy intégré à NetBird. Pour finir, nous verrons comment mettre à jour NetBird et comment il se positionne face à Tailscale.

NetBird, qu'est-ce que c'est ?

NetBird est une plateforme open source qui permet de créer un réseau privé virtuel entre des appareils, quel que soit l'endroit où ils se trouvent : un PC portable en déplacement, un smartphone, un serveur dans le cloud ou une machine de votre homelab. Chaque appareil rejoint un réseau commun et peut communiquer avec les autres, via un tunnel chiffré, comme s'ils étaient sur le même réseau local.

Le projet est développé par la société NetBird, basée à Berlin. Le code est écrit en Go et publié sur GitHub sous deux licences : la licence BSD-3-Clause pour l'essentiel du dépôt, notamment le client, et la licence AGPLv3 pour les composants serveur (management, signal et relay). L'édition communautaire est gratuite et complète pour un usage homelab ou une petite structure. Certaines fonctions avancées, comme la synchronisation des utilisateurs depuis un fournisseur d'identité (avec du SCIM, par exemple) ou le journal des flux réseau, nécessitent une licence commerciale. NetBird propose aussi une offre managée, NetBird Cloud, si vous ne souhaitez pas héberger le serveur de contrôle.

Voici quelques liens utiles :

• Site officiel : netbird.io

• Documentation : docs.netbird.io

• Dépôt GitHub : github.com/netbirdio/netbird

Pour ce tutoriel, j'ai utilisé NetBird 0.81.5 (dashboard v2.95.0), la version récupérée par le script d'installation au moment de mes tests. La version 0.82.0 est sortie depuis : nous verrons à la fin de l'article comment mettre à jour l'installation.

Un réseau maillé basé sur WireGuard

NetBird s'appuie sur WireGuard, un protocole VPN moderne, léger et performant, intégré au noyau Linux. Si vous avez déjà monté un serveur VPN WireGuard sur Debian, vous savez que la gestion des clés et des pairs devient vite fastidieuse quand le nombre d'appareils augmente. C'est ce que NetBird automatise.

Sur chaque appareil, vous installez un agent NetBird. Il crée une interface WireGuard (nommée wt0 sous Linux) et l'appareil obtient une adresse IP dans le réseau NetBird. Dans NetBird, chaque appareil connecté s'appelle un peer (un pair). Les peers communiquent ensuite directement entre eux, en pair-à-pair : c'est ce qu'on appelle un réseau maillé, ou VPN mesh. Il n'y a pas de concentrateur VPN central par lequel tout le trafic doit transiter, comme avec un VPN classique.

Les adresses attribuées aux peers appartiennent à la plage 100.64.0.0/10, réservée au CGNAT. NetBird y choisit un sous-réseau (100.69.0.0/16 sur mon instance) afin de limiter les conflits avec les plages privées utilisées sur vos réseaux locaux.

Le rôle du serveur NetBird

Si les données ne transitent pas par lui, à quoi sert le serveur ? À coordonner le réseau. Il regroupe plusieurs briques :

• Management : il connaît la liste des peers, leur attribue une adresse IP, distribue les clés publiques WireGuard et les règles d'accès.

• Signal : il met deux peers en relation pour qu'ils négocient une connexion directe. Les messages échangés sont chiffrés et il ne transporte pas les données.

• STUN : il aide chaque peer à découvrir son adresse publique, pour traverser le NAT de votre box.

• Relay : il sert de relais quand la connexion directe est impossible, par exemple quand les deux peers sont derrière un CGNAT ou un NAT très restrictif. Le trafic reste chiffré de bout en bout par WireGuard : le relais transporte les paquets sans pouvoir les lire.

• Dashboard : c'est l'interface web d'administration, accompagnée d'un fournisseur d'identité intégré pour l'authentification des utilisateurs.

Dans les versions récentes de NetBird, les briques Management, Signal, Relay et STUN sont regroupées dans un seul conteneur, nommé netbird-server. Retenez une chose : le serveur orchestre, mais vos données ne passent pas par lui, sauf en dernier recours via le relais.

Source : NetBird

Peers et routing peers

Il existe deux façons d'utiliser un peer NetBird :

• Le peer classique : c'est un terminal client, comme votre smartphone ou votre PC portable, qui se connecte à d'autres ressources. Il n'est joignable que sur sa propre adresse NetBird.

• Le routing peer : c'est un peer qui sert de passerelle vers un réseau dont les machines n'ont pas l'agent NetBird. Il fait le lien entre le réseau NetBird et un réseau classique (un LAN, un VLAN, un VPC dans le cloud).

Le routing peer est la pièce maîtresse d'un accès distant à un homelab. Sans lui, chaque machine à joindre devrait avoir son propre agent, ce qui est impossible pour un switch, une imprimante ou une caméra, et fastidieux pour des dizaines de serveurs. Avec un seul agent bien placé, vous pouvez accéder à votre Proxmox, à votre NAS ou à un serveur web, tout en contrôlant précisément qui accède à quoi.

Prérequis : où héberger le serveur NetBird ?

Pourquoi un VPS ?

Le serveur NetBird doit être joignable par tous vos appareils, où qu'ils soient. Il lui faut donc une adresse IP publique et un nom de domaine. Pour cette démonstration, j'utilise un VPS sous Debian 13. Un petit VPS suffit largement : la documentation recommande au minimum 1 vCPU et 2 Go de RAM.

Il faut aussi garder en tête que le serveur doit être disponible en permanence. S'il ne répond plus, les peers ne peuvent plus s'authentifier ni établir de nouvelles connexions, et vous perdez l'accès à distance à vos ressources. Un VPS dans le cloud se prête bien à ce rôle, car il ne dépend pas de votre connexion personnelle. Héberger le serveur à la maison, sur une VM, reste possible, mais vous devrez ouvrir des ports sur votre box. Je pense que le VPS est vraiment la meilleure option, et vu la configuration demandée, ça ne coûtera que quelques euros par mois.

Créer l'enregistrement DNS

Avant de lancer l'installation, il faut créer un enregistrement DNS de type A qui pointe vers l'adresse IP publique du VPS. Dans mon cas, il s'agit de remote.it-connectlab.fr.

C'est important de le faire en premier : le script d'installation demande un certificat TLS à Let's Encrypt, et pour cela, le nom doit déjà résoudre vers le serveur. Vous pouvez le vérifier avec la commande dig +short remote.it-connectlab.fr, qui doit retourner l'adresse IP du VPS.

Si vous comptez utiliser le reverse proxy intégré de NetBird, prévoyez aussi un enregistrement wildcard (*.remote.it-connectlab.fr). Nous y reviendrons dans la dernière partie.

Ouvrir les ports sur le pare-feu

Que vous filtriez les flux directement sur le VPS ou au niveau du pare-feu de votre hébergeur, voici les ports à autoriser en entrée. Cette liste correspond aux ports publiés par la stack générée par le script d'installation sur mon serveur :

Port

Protocole

Rôle

443

TCP

Dashboard, API, signalisation et relais (WebSocket)

80

TCP

Validation des certificats Let's Encrypt et redirection vers HTTPS

3478

UDP

STUN, pour la traversée du NAT

51820

UDP

Optionnel : connexions pair-à-pair du reverse proxy NetBird

Note : sur les déploiements plus anciens (architecture multi-conteneurs) ou avec des relais externes, la documentation mentionne d'autres ports, comme 443/UDP pour le relais en QUIC. Fiez-vous au récapitulatif affiché à la fin de votre installation, qui liste les ports réellement utilisés.

Installer Docker sur Debian 13

Le script d'installation de NetBird déploie une stack Docker Compose. Docker est donc indispensable. Si vous lancez le script sans Docker, il s'arrête immédiatement avec ce message :

Docker is not installed or not in PATH. Please follow the steps from the official guide: https://docs.docker.com/engine/install/

Commençons par mettre à jour le système et par installer les deux outils dont le script a besoin : curl et jq.

# Mettre à jour le système
sudo apt-get update && sudo apt-get upgrade -y

# Installer les prérequis du script NetBird
sudo apt-get install -y ca-certificates curl jq

Ensuite, installons Docker Engine et le plugin Compose à partir du dépôt officiel de Docker. Le nom de code de Debian (trixie pour Debian 13) est détecté automatiquement.

# Ajouter la clé GPG de Docker
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Ajouter le dépôt Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Installer le moteur Docker et le plugin Compose
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Pour éviter de préfixer chaque commande Docker par sudo, j'ajoute mon compte au groupe docker, puis je vérifie que Docker Compose est bien disponible.

# Ajouter le compte courant au groupe docker
sudo usermod -aG docker $USER
newgrp docker

# Vérifier la version de Docker Compose
docker compose version

Pour plus de détails sur l'installation de Docker, vous pouvez consulter ce tutoriel : installation pas à pas de Docker sur Debian 13.

Installer le serveur NetBird avec le script officiel

Lancer le script d'installation

Je crée un dossier dédié à la stack NetBird dans /opt/docker-compose/, comme pour toutes mes stacks Docker. Le script génère ses fichiers dans le répertoire courant, il faut donc se placer dans ce dossier avant de le lancer.

# Créer le dossier de la stack
sudo mkdir -p /opt/docker-compose/netbird
sudo chown $USER:$USER /opt/docker-compose/netbird
cd /opt/docker-compose/netbird

Définissez ensuite le nom de domaine dans la variable d'environnement NETBIRD_DOMAIN. Si vous ne le faites pas, le script vous le demandera, mais je préfère le fixer dès le départ. Puis, lancez le script d'installation officiel : il récupère la dernière version de NetBird et génère toute la configuration Docker Compose.

# Nom de domaine du serveur NetBird (sans https:// ni port)
export NETBIRD_DOMAIN=remote.it-connectlab.fr

# Lancer le script d'installation officiel
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Même si le script automatise l'essentiel, il pose plusieurs questions :

• Which reverse proxy will you use? : le choix par défaut [0] Traefik intègre Traefik à la stack, avec la gestion automatique des certificats TLS. C'est l'option que je retiens (notamment car j'ai l'habitude d'utiliser ce reverse proxy). Le script sait aussi s'adapter à un Traefik existant, à Nginx, à Nginx Proxy Manager ou à Caddy. Si vous débutez avec cet outil, je vous recommande la lecture de ce tutoriel : débuter avec Traefik.

• Email address : l'adresse e-mail utilisée pour les notifications de Let's Encrypt.

• Enable proxy? : il s'agit du reverse proxy intégré à NetBird, qui permet de publier des services internes sur Internet. Je l'active (y), car nous l'utiliserons dans la dernière partie.

• Enable CrowdSec? : le script propose d'ajouter un conteneur CrowdSec à la stack. Le reverse proxy pourra alors vérifier la réputation des adresses IP des clients et bloquer les adresses malveillantes. CrowdSec est un outil français et open source, que vous connaissez peut-être si vous avez lu notre guide pour bien débuter avec CrowdSec. Je vous encourage à l'activer (y).

Quelques instants plus tard, l'installation est terminée. Le script affiche un récapitulatif avec l'adresse du dashboard, les ports ouverts et des informations sur le reverse proxy et sur CrowdSec. Prenez le temps de le lire : il indique notamment l'enregistrement DNS wildcard à créer pour le reverse proxy.

Vérifier la stack Docker

Le dossier contient désormais les fichiers générés par le script, et la commande docker compose ps permet de vérifier que tous les conteneurs sont démarrés.

ls -l
docker compose ps

Voici le rôle de chaque élément :

• docker-compose.yml : la définition de la stack, avec cinq conteneurs : netbird-server (Management, Signal, Relay et STUN), netbird-dashboard, netbird-traefik, netbird-proxy et netbird-crowdsec.

• config.yaml : la configuration du serveur NetBird. Ses droits sont limités à son propriétaire (600), car il contient des secrets.

• dashboard.env et proxy.env : les variables d'environnement du dashboard et du reverse proxy.

• traefik-dynamic.yaml : la configuration dynamique de Traefik.

• crowdsec/ : la configuration et les données de CrowdSec.

N'hésitez pas à ouvrir ces fichiers, rien que par curiosité, pour comprendre comment fonctionne cette stack.

Première connexion au dashboard

Ouvrez un navigateur et saisissez l'adresse de votre serveur NetBird en HTTPS (https://remote.it-connectlab.fr). La connexion est sécurisée par un certificat Let's Encrypt valide. Lors de la première connexion, NetBird vous demande de créer le compte administrateur de la plateforme. Ce compte est local : il s'appuie sur le fournisseur d'identité intégré à NetBird. Il sera possible de brancher un fournisseur d'identité externe (SSO) par la suite.

Une fois connecté, un assistant vous propose deux scénarios : un réseau pair-à-pair entre vos appareils, ou un accès distant à votre réseau local. Vous pouvez suivre l'assistant, mais ici, nous allons tout configurer manuellement : cliquez sur Skip to Dashboard.

Vous arrivez alors sur le tableau de bord de NetBird, pour l'instant vide. Le menu de gauche donne accès aux différentes sections : Control Center, Peers, Access Control (règles, groupes et posture checks), Network Routing (réseaux et routes), Reverse Proxy, DNS, Team, Activity et Settings.

Créer un réseau et un routing peer

Networks plutôt que Routes

Dans la section Network Routing, vous trouverez deux entrées : Networks et Routes. Si vous ouvrez Routes, un bandeau indique que NetBird recommande désormais d'utiliser Networks. C'est l'approche moderne pour l'accès distant : un réseau regroupe des ressources (une IP, un sous-réseau ou un nom de domaine) et les routing peers qui y donnent accès. Surtout, l'accès y est refusé par défaut, tant qu'une règle ne l'autorise pas. Les routes classiques restent utiles pour un cas précis : les exit nodes, qui permettent de faire sortir tout le trafic Internet d'un appareil par un autre peer.

Créer le réseau HomeLab

Cliquez sur Network Routing puis Networks, et ajoutez un nouveau réseau. Je le nomme HomeLab, car il va donner accès à distance à des ressources de mon réseau local : un serveur web de démonstration et mon serveur Proxmox VE.

Le réseau apparaît ensuite dans la liste, sans ressource ni routing peer pour le moment.

Une fois le réseau créé, NetBird propose d'y ajouter des ressources et un routing peer. Commençons par le routing peer : sans lui, les ressources ne seraient pas joignables. En cliquant sur Add dans la colonne Routing Peers, NetBird demande de sélectionner un peer. Comme nous n'en avons aucun, cliquez sur Install NetBird.

Générer une setup key

NetBird génère alors une setup key et affiche les commandes d'installation pour Linux, Windows, macOS et Docker. La setup key permet à une machine de s'enregistrer auprès du serveur sans connexion interactive, ce qui est adapté à un serveur ou à un conteneur. Celle-ci est à usage unique et valable 24 heures.

Client Linux ou client Docker ?

Pour un routing peer, faut-il installer le client NetBird nativement ou avec Docker ? Tout dépend de la machine :

• Sur une machine dédiée à ce rôle (VM, conteneur LXC, Raspberry Pi), installez le client natif. C'est mon choix ici : le conteneur LXC sert déjà d'unité d'isolation, et ajouter Docker par-dessus compliquerait la mise en place sans rien apporter. Le client natif s'exécute comme un service systemd et agit directement sur l'interface réseau qui donne accès au LAN. Ce conteneur très léger ne servira qu'à ça.

• Sur une machine qui exécute déjà d'autres services (un NAS, un hôte Docker), l'option Docker permet de garder le client isolé du reste.

Les deux options sont bonnes, tout dépend du contexte.

Déployer le routing peer dans un conteneur LXC sur Proxmox VE

Pour héberger le routing peer, j'utilise un conteneur LXC sur mon serveur Proxmox VE. C'est très léger : un cœur de CPU et 512 Mo de RAM suffisent. Je fais tout en ligne de commande, en SSH sur l'hôte Proxmox. Si vous découvrez les conteneurs LXC, consultez ce tutoriel : bien débuter avec les conteneurs LXC sur Proxmox VE.

Créer le conteneur LXC

J'utilise le template Debian 13 fourni par Proxmox. S'il n'est pas encore présent sur votre serveur, récupérez-le avec pveam :

# Mettre à jour la liste des templates et chercher Debian 13
pveam update
pveam available --section system | grep debian-13

# Télécharger le template sur le stockage local
pveam download local debian-13-standard_13.6-1_amd64.tar.zst

Ensuite, créez le conteneur avec la commande pct create :

pct create 200 local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst \
  --hostname netbird-router \
  --cores 1 --memory 512 --swap 512 \
  --rootfs nvme-data:4 \
  --net0 name=eth0,bridge=vmbr1,ip=dhcp \
  --features nesting=1 \
  --unprivileged 1 \
  --onboot 1 \
  --password

Quelques explications sur les options :

• 200 : l'identifiant du conteneur dans Proxmox VE.

• --hostname netbird-router : le nom du conteneur, qui sera aussi le nom du peer dans NetBird.

• --cores 1 --memory 512 --swap 512 : un cœur, 512 Mo de RAM et 512 Mo de swap.

• --rootfs nvme-data:4 : un disque de 4 Go sur le stockage nvme-data (adaptez ce nom à votre serveur).

• --net0 name=eth0,bridge=vmbr1,ip=dhcp : une carte réseau connectée au bridge vmbr1, avec une adresse IP obtenue en DHCP. Pour un routing peer, une IP fixe ou une réservation DHCP est préférable.

• --features nesting=1 : sans cette option, Proxmox affiche l'avertissement WARN: Systemd 257 detected. You may need to enable nesting. avec le template Debian 13. Il est donc recommandé de l'activer.

• --unprivileged 1 : un conteneur non privilégié, plus sûr.

• --onboot 1 : démarrage automatique du conteneur avec l'hôte.

• --password : le mot de passe root du conteneur, demandé de façon interactive. Choisissez un mot de passe robuste.

Placer le conteneur sur le bon réseau

Le routing peer doit pouvoir joindre en IP les ressources qu'il va exposer. Le plus simple est de le placer directement dans le réseau concerné. Dans mon cas, le bridge vmbr1 repose sur un agrégat de liens (LACP), et le trafic non taggé arrive dans le VLAN 140 de mon lab, celui du serveur web de démonstration. Si vous voulez placer le conteneur dans un VLAN précis, ajoutez l'option tag=<ID> à la carte réseau.

Le routing peer peut aussi atteindre une ressource située sur un autre VLAN, à condition que le routage inter-VLAN le permette. C'est d'ailleurs le cas de mon serveur Proxmox, que nous ajouterons plus loin. L'idée étant de vous montrer que NetBird peut s'avérer très flexible.

Autoriser l'accès au périphérique TUN

NetBird a besoin du périphérique /dev/net/tun pour créer son interface WireGuard. Cependant, un conteneur LXC non privilégié n'y a pas accès par défaut. Il faut donc ajouter deux lignes à la configuration du conteneur, sur l'hôte Proxmox :

# Accès au périphérique TUN pour le conteneur 200
# - cgroup2.devices.allow : autorise le périphérique caractère 10:200 (/dev/net/tun)
# - mount.entry : monte le /dev/net/tun de l'hôte dans le conteneur
cat >> /etc/pve/lxc/200.conf <<'EOF'
lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file
EOF

Démarrez ensuite le conteneur et vérifiez que le périphérique est bien présent :

pct start 200
pct exec 200 -- ls -l /dev/net/tun

La sortie doit ressembler à ceci :

crw-rw-rw- 1 nobody nogroup 10, 200 Oct 27 14:30 /dev/net/tun

Le propriétaire nobody nogroup est normal dans un conteneur non privilégié : sur l'hôte, le périphérique appartient à root, mais cet utilisateur n'a pas de correspondance dans l'espace de noms du conteneur. Le compte root du conteneur dispose de la capacité CAP_NET_ADMIN dans son propre espace de noms réseau. Il peut donc créer l'interface WireGuard.

Pour obtenir un shell dans le conteneur, utilisez la commande pct enter 200.

Installer le client NetBird dans le conteneur

Dans le conteneur, commencez par installer les mises à jour, ce qui permet au passage de vérifier qu'il accède bien à Internet. Installez ensuite curl et le paquet ca-certificates, nécessaires au script d'installation de NetBird.

# Mises à jour et prérequis
apt update && apt upgrade -y
apt install -y curl ca-certificates

Retournez sur l'interface de NetBird pour copier les deux commandes affichées dans l'onglet Linux. La première installe le client NetBird. La seconde enregistre le peer auprès de votre serveur, grâce à l'URL du serveur et à la setup key.

# Installer le client NetBird
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Enregistrer le peer auprès du serveur NetBird
netbird up --management-url https://remote.it-connectlab.fr --setup-key <VOTRE_SETUP_KEY>

La commande retourne Connected. Vous pouvez aussi vérifier l'état de la connexion avec netbird status.

Dans la section Peers du dashboard, le peer netbird-router apparaît avec son adresse IP dans le réseau NetBird, son système (Debian 13) et la version de l'agent.

Activer le routing peer sur le réseau

Retournez dans Network Routing, puis Networks, et ajoutez un routing peer au réseau HomeLab. Cette fois, sélectionnez netbird-router dans la liste, puis cliquez sur Continue.

L'onglet Advanced Settings contient trois paramètres :

• Enable Routing Peer : active ou désactive le routing peer.

• Masquerade : le routing peer remplace l'adresse source des paquets par sa propre adresse IP sur le LAN. Les machines du réseau local répondent donc au routing peer, sans avoir besoin de connaître le réseau NetBird. Avec cette option, inutile d'ajouter une route retour vers 100.64.0.0/10 sur votre passerelle. Laissez-la activée.

• Metric : la priorité du routing peer (9999 par défaut). Plus la valeur est basse, plus la priorité est élevée. C'est utile si vous déclarez plusieurs routing peers sur le même réseau pour assurer la haute disponibilité.

Cliquez sur Add Routing Peer. Le réseau HomeLab dispose désormais d'une passerelle vers le réseau local.

Et sur un NAS ou un hôte Docker ?

Si vous déployez le client NetBird avec Docker, par exemple sur un NAS Synology, vous risquez de rencontrer le même obstacle : le conteneur a besoin du périphérique /dev/net/tun. Dans les journaux, cela se traduit par une erreur du type couldn't access device /dev/net/tun. La documentation de NetBird recommande d'exécuter le conteneur en mode réseau host, avec les capacités NET_ADMIN, SYS_ADMIN et SYS_RESOURCE, et le périphérique /dev/net/tun, ce qui suppose que le module tun soit chargé sur l'hôte.

Si vous désirez un guide d'installation d'un routing peer NetBird sur un NAS Synology, dites-le moi en commentaire.

Connecter des clients Windows et Linux

Pour accéder aux ressources, il nous faut maintenant des clients distants. Pour simuler un accès depuis l'extérieur, j'utilise deux machines virtuelles, une sous Windows et une sous Linux Mint, connectées au partage de connexion 5G de mon smartphone.

Installer le client NetBird sous Windows

Dans la section Peers, cliquez sur Add Peer puis sur User Device. NetBird affiche les instructions pour Linux, Windows, macOS, iOS et Android. Dans l'onglet Windows, téléchargez l'installeur, puis installez-le sur la machine.

Au premier lancement, le client NetBird vous demande où se connecter. Choisissez Auto-hébergé et saisissez l'adresse de votre serveur NetBird (https://remote.it-connectlab.fr), puis cliquez sur Continuer.

Il faut ensuite cliquer sur le bouton de connexion. Le client ouvre le navigateur pour vous authentifier auprès du serveur NetBird : un appareil ne rejoint pas le réseau sans authentification. Connectez-vous avec un compte NetBird (ici, le compte administrateur). Le client indique alors qu'il est connecté, avec le nom de la machine et son adresse IP dans le réseau NetBird.

Installer le client NetBird sous Linux

Sous Linux, le principe est le même avec les commandes de l'onglet Linux. Cette fois, il n'y a pas de setup key : l'enregistrement passe par une authentification de l'utilisateur dans le navigateur, ce qui convient à un poste de travail.

# Installer le client NetBird
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Enregistrer la machine (authentification dans le navigateur)
netbird up --management-url https://remote.it-connectlab.fr

La seconde commande ouvre automatiquement une page d'authentification dans le navigateur. Si ce n'est pas le cas, elle affiche l'URL à ouvrir.

Une fois authentifié, la page Login Successful confirme l'enregistrement de la machine.

Vérifier la connectivité entre les peers

La section Peers affiche désormais trois peers : les deux clients et le routing peer. Les postes utilisateurs sont rattachés au compte qui les a enregistrés.

Note : chaque client NetBird dispose de sa propre fiche dans l'inventaire des pairs, afin d'éditer son nom mais aussi sa configuration (expiration de la session, accès SSH, version de l'agent, etc.).

Depuis la machine Windows, je peux déjà joindre le peer netbird-router sur son adresse NetBird, alors que les deux machines ne sont pas sur le même réseau :

ping 100.69.14.240

Pour savoir si la connexion entre deux peers est directe ou passe par le relais, utilisez la commande netbird status -d sur un client : pour chaque peer, elle indique le type de connexion (P2P ou Relayed).

Donner accès à une ressource du réseau local

Pouvoir joindre le routing peer, c'est bien, mais cela ne donne encore accès à rien. Si j'essaie d'ouvrir mon serveur web de démonstration (http://192.168.140.11) depuis la machine Windows, la page ne se charge pas. Il faut déclarer une ressource et une règle d'accès.

Ajouter une ressource

Dans le réseau HomeLab, cliquez sur Add dans la colonne Resources. Donnez un nom à la ressource (demo web) et indiquez son adresse. Il peut s'agir de l'adresse IP d'une machine, d'un sous-réseau au format CIDR ou d'un nom de domaine. Ici, je saisis l'adresse IP du serveur web. Une description et un groupe de ressources sont facultatifs (mais cette notion est importante car elle facilite grandement la gestion des accès sur un ensemble de ressources).

Créer une règle d'accès

L'étape suivante est la création d'une règle d'accès (Access Control Policy). C'est un point central de NetBird : il permet de définir précisément qui a accès à quoi, en descendant jusqu'au protocole et au port. Une règle se compose de :

• Une source : un peer ou un groupe de peers. Ici, je sélectionne Windows-Demo.

• Une destination : la ressource demo web.

• Un protocole : TCP, car mon serveur web est uniquement accessible en HTTP.

• Des ports : uniquement le port 80. Même si le serveur web accepte des connexions SSH, elles ne seront pas autorisées par cette règle.

Pour la source, le plus pratique est de travailler avec des groupes, que vous pouvez gérer dans Access Control, section Groups. Par exemple, un groupe PC-Perso rassemblant vos postes personnels permet de créer une seule règle pour l'ensemble de ces machines, plutôt qu'une règle par appareil.

Ajouter des posture checks

L'onglet Posture Checks permet d'ajouter des conditions supplémentaires à respecter pour que l'accès soit autorisé. NetBird propose plusieurs types de vérifications :

• NetBird Client Version : une version minimale du client NetBird.

• Country & Region : la localisation de l'appareil (pays ou région).

• Peer Network Range : la plage réseau dans laquelle se trouve le peer.

• Operating System : le système d'exploitation et sa version.

• Process : la présence d'un processus en cours d'exécution sur l'appareil.

• Certificate : la présence d'un certificat émis par votre propre autorité de certification.

Par exemple, la vérification Country & Region permet de n'autoriser l'accès que depuis la France. Pour accéder à la ressource, il faudra alors disposer du client NetBird, être enregistré sur votre serveur, être autorisé par la règle et se trouver en France. C'est une brique intéressante dans une approche zero trust.

Terminez par l'onglet Name & Description pour nommer la règle (demo web Access), puis ajoutez-la.

Tester l'accès à la ressource

De retour sur la machine Windows, je relance la requête vers le serveur web : cette fois, la page s'affiche. Le trafic passe par le tunnel WireGuard jusqu'au routing peer, qui le transmet au serveur web sur le réseau local.

Ajouter une seconde ressource : le serveur Proxmox VE

Sur le même principe, j'ajoute une seconde ressource : mon serveur Proxmox VE, prox-01. Son adresse IP (192.168.110.3) se trouve sur un autre VLAN que celui du routing peer. Quand vous saisissez une adresse IP seule, NetBird la considère comme un hôte unique et ajoute le masque /32. Pour déclarer un sous-réseau complet, indiquez son masque, par exemple 192.168.110.0/24.

Il faut créer une nouvelle règle d'accès, car le port n'est pas le même : l'interface web de Proxmox VE écoute sur le port 8006 en TCP.

Depuis la machine Windows, l'interface de Proxmox VE est maintenant accessible à distance sur https://192.168.110.3:8006, le tout via NetBird.

Le réseau HomeLab compte désormais deux ressources, deux règles d'accès et un routing peer.

Deux remarques sur l'accès à une ressource située sur un autre VLAN :

• Le pare-feu inter-VLAN doit autoriser le routing peer : avec la masquerade, le serveur Proxmox voit les connexions arriver depuis l'adresse IP du routing peer sur le LAN, et non depuis les adresses des clients NetBird. La règle de votre pare-feu doit donc autoriser cette adresse vers la ressource et le port concernés.

• Le contrôle d'accès par utilisateur repose sur NetBird : tous les clients passent par la même adresse IP source, celle du routing peer. Côté pare-feu, limitez la règle au strict nécessaire (une IP et un port), et confiez le filtrage par utilisateur aux règles NetBird.

Si vous exposez un réseau sensible comme celui de vos hyperviseurs, déclarez des ressources en /32 sur les seuls ports utiles, réservées à un groupe d'administrateurs restreint.

Utiliser un nom de domaine comme ressource

Une ressource peut aussi être un nom de domaine (proxmox.lab.local) ou un wildcard (*.lab.local). Dans ce cas, la résolution du nom est effectuée par défaut par le routing peer, et non par le client. Quelques prérequis et limites sont à connaître :

• Le routing peer doit savoir résoudre le nom : il doit utiliser un serveur DNS qui connaît l'enregistrement. Si ce n'est pas le cas, vous pouvez distribuer un serveur DNS au groupe du routing peer depuis la section DNS, Nameservers.

• La gestion DNS de NetBird doit rester active sur le client : c'est elle qui intercepte les requêtes destinées au domaine et les transmet au routing peer.

• Un réseau dédié est recommandé : la documentation conseille de ne pas mélanger des ressources de type domaine et des ressources IP dans un même réseau.

Le Control Center et la règle Default

Visualiser les accès

Le Control Center offre une vue globale des accès. Vous pouvez vous placer du point de vue d'un peer, d'un utilisateur, d'un groupe ou d'un réseau. Par exemple, en sélectionnant un peer, vous voyez à quelles ressources il a accès, via quelle règle et sur quel protocole et quel port. C'est très pratique pour repérer une règle trop permissive. La vue est mise à jour en fonction de votre configuration, et un mode Draft (en bêta) permet de préparer des modifications avant de les appliquer.

Désactiver la règle Default

Dans le Control Center, vous remarquerez une règle nommée Default, qui relie le groupe All au groupe All dans les deux sens, sur tous les protocoles. Elle est créée par défaut et autorise chaque peer à communiquer sans limite avec tous les autres peers. Concrètement, la machine Windows peut accéder à tous les ports de la machine Linux et du routing peer : si un service SSH ou un accès bureau à distance y est actif, il est utilisable. Et chaque nouveau peer enregistré obtient automatiquement le même accès.

C'est pratique pour un premier test, et cela facilite la mise en œuvre de NetBird, mais c'est contraire à l'approche zero trust. Je vous recommande de désactiver cette règle dans Access Control, section Policies, dès que vos règles explicites sont en place.

Après la désactivation, il faut bien faire la distinction entre deux types de trafic pour un routing peer :

• Le trafic qui le traverse : les paquets que le routing peer relaie vers les ressources du réseau local. Ils relèvent des règles de ressources, et la désactivation de la règle Default n'a aucun impact sur eux. L'accès au serveur web et à Proxmox continue de fonctionner.

• Le trafic qui lui est destiné : les paquets adressés au routing peer lui-même, pour une connexion SSH par exemple. Ils relèvent des règles entre peers. C'est uniquement cet accès que vous perdez.

Si vous avez besoin d'un accès SSH au routing peer, créez une règle dédiée, par exemple du groupe des administrateurs vers le groupe routing-peers, en TCP sur le port 22.

Tour d'horizon des autres paramètres de NetBird

La gestion du DNS

Par défaut, le réseau NetBird dispose d'un nom de domaine interne (netbird.selfhosted sur mon instance), personnalisable dans Settings, section Networks. Chaque peer est joignable via un nom de la forme <nom-du-peer>.netbird.selfhosted.

La section DNS permet aussi de distribuer des serveurs DNS à vos clients (Nameservers). NetBird propose des modèles pour Google DNS, Cloudflare DNS et Quad9, ou un serveur personnalisé, comme le DNS interne de votre réseau local (de quoi pointer vers votre serveur Technitium DNS, par exemple). La section Zones permet de gérer des zones DNS directement dans NetBird. C'est une partie intéressante si vous voulez aller plus loin que l'accès par adresse IP.

Utilisateurs et fournisseurs d'identité

La section Team permet de gérer les utilisateurs : création de comptes, invitations, rôles et groupes. La partie Service Users sert à créer des comptes dédiés à l'API de NetBird, pour l'automatisation. La synchronisation des utilisateurs depuis un fournisseur d'identité (Google Workspace, Entra ID en API ou en SCIM, Okta, JumpCloud) est en revanche réservée à la licence Enterprise.

Pour l'authentification unique (SSO), rendez-vous dans Settings, section Identity Providers. NetBird prend en charge un fournisseur OIDC générique, ainsi que Google, Microsoft Entra, Okta, Zitadel, Pocket ID, Authentik, ou encore Keycloak. Plusieurs de ces solutions sont très répandues dans les homelabs, n'est-ce pas ?

Le journal d'audit

Dans la section Activity, la partie Audit Events retrace toutes les actions effectuées sur la plateforme : qui a fait quoi, et à quelle heure (création d'une règle, d'une ressource, modification de la règle Default, etc.). La partie Traffic Events, qui journalise les flux réseau, est réservée à la licence Enterprise.

Authentification et MFA

Dans Settings, section Authentication, vous pouvez notamment :

• Exiger l'approbation des nouveaux utilisateurs (User Approval Required).

• Activer l'authentification multifacteur pour les comptes locaux (Enable Local MFA). Je vous recommande de l'activer, c'est la base !

• Définir la durée de session des peers (Peer Session Expiration), au-delà de laquelle une nouvelle authentification est demandée.

Les paramètres réseau

La section Networks des paramètres permet de modifier le domaine DNS interne, la plage d'adresses IPv4 du réseau NetBird (100.69.0.0/16 ici), la plage IPv6 et les groupes concernés par l'IPv6. On y trouve aussi l'option Enable Routing Peer DNS Resolution, qui délègue la résolution des ressources de type domaine aux routing peers.

Publier un service avec le reverse proxy intégré

Le principe

Avec l'agent NetBird, vous pouvez accéder à toutes vos ressources via des tunnels chiffrés. L'inconvénient, c'est qu'il faut l'agent. Le reverse proxy intégré à NetBird (basé sur Traefik) répond à un autre besoin : publier sur Internet une ressource interne, accessible depuis un simple navigateur, sans l'agent. Par exemple, un site en cours de développement à montrer à quelqu'un, ou une application à laquelle vous voulez accéder depuis n'importe quel appareil.

Cette fonctionnalité est encore en bêta (ça fait des mois que c'est le cas), mais elle fonctionne bien. Gardez simplement en tête qu'un service publié de cette façon est exposé sur Internet : il faut le protéger, et c'est justement ce que permettent les options de NetBird.

On va faire le test avec le serveur Web de démo utilisé précédemment.

Créer l'enregistrement DNS wildcard

Par défaut, un service publié utilise un sous-domaine du domaine de NetBird, par exemple demo-web.remote.it-connectlab.fr. Ce nom doit exister dans le DNS, sinon le certificat TLS ne pourra pas être émis. Le plus simple est de créer un enregistrement wildcard de type CNAME, comme le suggère le récapitulatif de l'installation :

*.remote.it-connectlab.fr    CNAME    remote.it-connectlab.fr

Ainsi, chaque service publié pointera automatiquement vers le VPS, sans toucher à nouveau au DNS.

Créer le service

Dans la section Reverse Proxy, ouvrez Services et cliquez sur Add Service. Saisissez le sous-domaine à utiliser (demo-web). Vous pouvez aussi utiliser votre propre nom de domaine via la section Custom Domains.

Choisissez ensuite le type de service :

• HTTPS Service : le reverse proxy gère le HTTPS et le certificat. Le serveur qui se trouve derrière peut rester en HTTP. C'est l'option que je retiens.

• TLS Passthrough : le reverse proxy laisse passer le flux TLS, et c'est le serveur de destination qui gère le HTTPS et son certificat.

• TCP Service et UDP Service : pour publier un service de niveau 4, comme une base de données ou un serveur de jeu.

Ajoutez ensuite une cible (Add Target). Elle peut correspondre à un peer ou à une ressource existante. Je sélectionne la ressource demo web : NetBird reprend automatiquement son adresse IP et je précise le port 80. Les options facultatives permettent d'ajuster le chemin, le délai d'expiration des requêtes ou d'ajouter des en-têtes HTTP.

Protéger le service par une authentification

L'onglet Authentication permet de protéger l'accès au service. Plusieurs méthodes sont proposées :

• NetBird-Only Access : le service n'est accessible qu'aux peers connectés appartenant à certains groupes.

• SSO : l'utilisateur doit s'authentifier auprès du fournisseur d'identité.

• Password : un mot de passe à saisir avant d'accéder au service. C'est la méthode que j'utilise pour cette démonstration.

• PIN Code : un code PIN, tout simplement.

• HTTP Headers : un en-tête à présenter (Basic Auth, Bearer token ou en-tête personnalisé). C'est utile pour une API ou un webhook appelé par une autre application.

Activer CrowdSec et filtrer les accès

L'onglet Access Control permet d'activer la vérification de réputation CrowdSec pour ce service. En mode Enforce, les adresses IP malveillantes connues de CrowdSec sont bloquées. Le mode Observe se contente de journaliser, sans bloquer. Vous pouvez aussi ajouter des règles pour autoriser ou bloquer le trafic selon le pays, l'adresse IP ou un bloc CIDR. Les règles de blocage sont toujours prioritaires sur les règles d'autorisation. Dans mon cas, j'active CrowdSec en mode Enforce et je n'autorise que les connexions depuis la France.

Si vous souhaitez approfondir le sujet, consultez notre tutoriel sur l'intégration de CrowdSec avec Traefik.

Enfin, l'onglet Advanced Settings contient deux options : Pass Host Header pour transmettre l'en-tête Host d'origine au serveur de destination, et Rewrite Redirects pour réécrire les redirections renvoyées par le serveur. Elles sont à activer au cas par cas, selon l'application publiée.

Tester le service publié

Une fois le service ajouté, son statut affiche Issuing certificate... le temps que le certificat soit obtenu auprès de Let's Encrypt.

Depuis n'importe quel navigateur, l'adresse https://demo-web.remote.it-connectlab.fr affiche une page d'authentification. Après avoir saisi le mot de passe, j'accède au serveur web, cette fois sans l'agent NetBird !

La section Access Logs du reverse proxy liste toutes les requêtes reçues, avec la méthode, l'URL, le code de réponse et l'utilisateur authentifié. On constate rapidement que le service est sondé depuis l'étranger : ces requêtes, provenant notamment de Suisse et des États-Unis, ont été bloquées par la règle qui n'autorise que la France.

NetBird évolue rapidement.... Pensez donc à mettre à jour votre serveur et vos clients régulièrement.

Mettre à jour le serveur

Le dashboard signale la disponibilité d'une nouvelle version par un bouton Update available, en bas du menu de gauche, à côté des versions du Management et du Dashboard.

Avant de mettre à jour, je vous recommande de :

• Sauvegarder la stack : le dossier /opt/docker-compose/netbird (dont docker-compose.yml, config.yaml et les fichiers .env), la configuration de Traefik et de CrowdSec, ainsi que les volumes Docker (données de NetBird et certificats).

• Lire les notes de version : celles du serveur NetBird et celles du dashboard, pour repérer d'éventuels changements bloquants.

Ensuite, depuis le dossier de la stack, téléchargez les nouvelles images et recréez les conteneurs NetBird. Si le reverse proxy est activé, mettez-le à jour en même temps que le serveur (jamais avant).

cd /opt/docker-compose/netbird

# Télécharger les nouvelles images
docker compose pull netbird-server dashboard proxy

# Recréer les conteneurs
docker compose up -d --force-recreate netbird-server dashboard proxy

Sans le reverse proxy, retirez simplement proxy de ces deux commandes. Par défaut, les images NetBird utilisent le tag latest. Si vous avez fixé des versions précises dans le fichier docker-compose.yml, modifiez-les avant de lancer docker compose pull.

Traefik et CrowdSec ne sont pas mis à jour par cette procédure, car leurs images utilisent des versions fixes. Le mieux, c'est de regarder dans la documentation quelles sont les versions validées avant de modifier le fichier Docker Compose.

Mettre à jour les clients

Pour les clients Windows et macOS (installeur PKG), NetBird propose les mises à jour automatiques. Elles se configurent dans Settings, section Clients : vous pouvez choisir la dernière version ou une version précise, et forcer l'installation en arrière-plan.

Sous Linux, les mises à jour automatiques ne sont pas prises en charge. Sur Debian et Ubuntu, le script install.sh installe le client depuis le dépôt APT de NetBird (on le voit dans sa sortie). La mise à jour passe donc par le gestionnaire de paquets :

sudo apt-get update
sudo apt-get install netbird

Pour une installation réalisée sans gestionnaire de paquets, la documentation indique d'arrêter le client avec netbird down, de relancer le script d'installation avec l'option --update, puis de relancer le client avec netbird up.

NetBird ou Tailscale : quelles différences ?

Si vous connaissez Tailscale, que nous avions présenté dans notre guide complet sur Tailscale, vous avez sûrement remarqué les nombreux points communs avec NetBird. Les deux solutions reposent sur WireGuard, créent un réseau maillé et proposent des règles d'accès, des passerelles vers des réseaux locaux et des exit nodes. La différence principale tient au serveur de coordination.

Critère

NetBird

Tailscale

Headscale

Protocole

WireGuard

WireGuard

WireGuard (clients Tailscale)

Serveur de coordination

Open source (AGPLv3), auto-hébergeable ou en offre managée

Propriétaire, hébergé par Tailscale

Open source, implémentation alternative du serveur Tailscale

Interface web d'administration

Oui, incluse

Oui, en ligne

Non officielle (projets tiers)

Fournisseur d'identité

Intégré, avec prise en charge des IdP OIDC

Comptes des fournisseurs d'identité pris en charge

IdP OIDC

Publication de services sur Internet

Reverse proxy intégré

Tailscale Funnel

Non

Tailscale reste la solution la plus simple à prendre en main, avec un écosystème très mature, mais le serveur qui gère votre réseau n'est pas entre vos mains. Headscale permet de l'auto-héberger, comme nous l'avons vu dans notre tutoriel sur Headscale, mais il s'agit d'un projet communautaire qui ne couvre pas toutes les fonctionnalités de Tailscale et ne propose pas d'interface officielle. NetBird se distingue par un ensemble complet et auto-hébergeable, interface d'administration comprise, avec un éditeur qui développe officiellement cette version.

Conclusion

NetBird coche beaucoup de cases pour l'accès distant à un homelab (ou à un réseau professionnel) : un réseau maillé basé sur WireGuard, un contrôle d'accès fin par groupe, par protocole et par port, la vérification de la posture de sécurité, et une interface d'administration complète. Le tout est open source et auto-hébergeable de bout en bout, ce qui le distingue de Tailscale. L'installation du serveur avec le script officiel est rapide, et le routing peer dans un conteneur LXC permet d'accéder à tout un réseau local avec une empreinte minimale. Le reverse proxy intégré complète l'ensemble pour publier un service sur Internet de façon sécurisée.

Je vous recommande de travailler par groupe, que ce soit pour les ressources ou pour les paires, afin de faciliter la maintenance de votre installation NetBird. En disant cela, je pense notamment à la gestion des règles d'accès, ce sera plus facile en travaillant sur des groupes, et surtout ça limite les écarts de configuration.

Pour aller plus loin, voici quelques ressources :

• La documentation officielle de NetBird

• Le fonctionnement des routing peers

• La documentation du reverse proxy de NetBird

Et vous, utilisez-vous NetBird, Tailscale ou un VPN plus classique pour accéder à votre réseau à distance ?

Ajouter IT-Connect à mes
sources préférées

Cofondateur d'IT-Connect et Microsoft MVP "Cloud and Datacenter Management". Mon obsession depuis près de 15 ans ? Rendre l'administration système et la cybersécurité accessibles, que vous soyez junior ou confirmé. Plus qu'un métier, l'IT est pour moi une véritable passion. J’accompagne au quotidien les sysadmins et les professionnels de l’IT dans leur montée en compétences et leur veille technique.