Auto-héberger le serveur VPN NetBird sur un VPS

Ce que l’auto-hébergement du serveur VPN NetBird vous apporte

L’auto-hébergement du serveur VPN NetBird place le control plane sur un VPS que vous possédez. Il contient la liste des peers, détermine quelle machine peut accéder à quelle autre et aide deux peers à se trouver derrière un NAT (network address translation). Les tunnels eux-mêmes utilisent toujours WireGuard et sont chiffrés directement entre vos machines. En revanche, aucune entreprise externe ne conserve l’inventaire de vos appareils ni ne gère votre processus de connexion. Il faut bien comprendre ce que cela vous apporte : un control plane hébergé ne détient pas non plus les clés qui chiffrent votre trafic, et ce qu’un serveur de coordination peut réellement faire s’il est compromis est plus limité que ne le pensent la plupart des utilisateurs avant de lire cette analyse.

NetBird se situe entre deux solutions que vous connaissez peut-être déjà. Il s’agit d’un mesh overlay : les peers se connectent entre eux au lieu de faire transiter tout le trafic par une seule gateway. Il est aussi entièrement auto-hébergeable, ce qui le place face à Headscale, le serveur de contrôle Tailscale auto-hébergé. Si vous n’avez utilisé jusqu’ici qu’un tunnel avec une seule gateway, lisez d’abord la différence entre WireGuard classique et un mesh overlay, car c’est ce modèle mental qui permet de comprendre le reste de cette page.

Si vous voulez en réalité qu’un seul serveur soit le point de sortie de tout votre trafic, un mesh est plus complexe que nécessaire. Un VPN WireGuard classique sur un VPS unique ou un exit node Tailscale permettent de le faire avec beaucoup moins de composants à maintenir. Si votre objectif est d’accéder à un réseau privé plutôt que de relier des machines entre elles, un subnet router Tailscale sur un VPS annonce cette plage à un tailnet existant, sans nécessiter toute la stack décrite ci-dessous.

Ce que la stack exécute réellement

La structure a récemment changé, et la plupart des anciens guides décrivent encore l’ancienne. En août 2026, avec la release v0.76.2, le script de démarrage rapide écrit par défaut un fichier Compose contenant trois services.

• netbird-server fournit l’API de gestion, le service de signalisation, le relais avec un listener STUN intégré et un fournisseur d’identité intégré. Dans les anciennes releases, ces composants étaient des conteneurs distincts, et le fournisseur d’identité était une installation Zitadel séparée qu’il fallait d’abord construire.
• dashboard est la console web d’administration.
• traefik assure la terminaison TLS (Transport Layer Security) et demande un certificat à Let’s Encrypt au premier démarrage.

Deux autres services existent, mais restent désactivés tant que vous ne répondez pas oui à une invite. Le service NetBird Proxy publie des services internes sur des noms d’hôte publics. CrowdSec filtre le trafic abusif. Aucun des deux n’est nécessaire pour construire un mesh fonctionnel, et ils consomment tous deux de la mémoire sur une petite machine.

Si vous venez de wg-easy dans un conteneur Docker unique, le nombre de composants augmente nettement. En contrepartie, vous disposez de règles d’accès et de comptes par utilisateur, ainsi que de peers qui se connectent directement entre eux au lieu de passer par une seule gateway.

Ce qu’il vous faut avant de commencer

Un nom de domaine public est obligatoire. Le dashboard, l’API et le relay utilisent tous HTTPS sur le port 443. Traefik obtient son certificat auprès de Let's Encrypt au moyen d’un challenge HTTP. Celui-ci nécessite un nom qui pointe vers ce VPS depuis Internet. Une simple adresse IP ne fonctionne pas dans ce scénario.

Créez un enregistrement A, netbird.example.com, qui pointe vers l’adresse IPv4 publique du VPS, puis attendez sa propagation avant d’exécuter quoi que ce soit.

dig +short netbird.example.com

Cette commande doit afficher l’adresse de votre serveur. Si vous exécutez l’installateur avant la propagation du DNS, la demande de certificat échoue au premier démarrage. Des validations échouées à répétition déclenchent les limites de débit de Let's Encrypt. Vous devrez alors attendre une heure avant de réessayer.

Trois ports doivent être accessibles depuis Internet : TCP 80 pour le challenge du certificat et la redirection vers HTTPS, TCP 443 pour le dashboard, l’API, le trafic de signalisation et le relay, ainsi que UDP 3478 pour STUN.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

Ouvrez-les également dans le pare-feu réseau de votre fournisseur. Dans la plupart des panneaux VPS, il s’agit d’un contrôle distinct. C’est pourquoi un serveur dont le ufw status local semble correct peut malgré tout refuser les connexions.

STUN (session traversal utilities for NAT) permet à un pair de connaître l’adresse et le port publics attribués par son propre NAT. Deux pairs peuvent ainsi tenter d’établir un tunnel direct. Si vous bloquez UDP 3478, les pairs continuent de se connecter via le relay sur TCP 443. Rien ne semble donc cassé. Vous obtenez plutôt Connection type: Relayed sur chaque pair, et tout le trafic traverse votre VPS au lieu de circuler directement entre les pairs.

Côté logiciel, vous avez besoin de Docker avec le plugin Compose v2, ainsi que de jq et curl. Le script vérifie leur présence et s’arrête si l’un d’eux manque. Si Docker vient d’être installé sur ce serveur, commencez par consulter Faire fonctionner Docker Compose sur le VPS.

Installer le serveur NetBird avec le script de démarrage rapide

La commande en une ligne documentée transmet directement la dernière release à un shell :

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

Utilisez plutôt une version figée. latest évolue ; la même commande exécutée à deux semaines d’intervalle produit donc deux installations différentes, sans qu’aucun fichier sur le disque n’indique laquelle a écrit votre configuration. Téléchargez une release taguée, lisez-la, puis exécutez-la.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

Le script demande d’abord le domaine :

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

Il demande ensuite comment le TLS sera géré :

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

Choisissez [0]. Les options 2 à 5 écrivent un fragment de configuration et vous laissent configurer les connexions, ce qui convient à un serveur qui exécute déjà un proxy, mais pas à une installation vierge. L’option 0 demande ensuite une adresse e-mail Let’s Encrypt, utilisée pour les notifications d’expiration.

Lors d’une première installation, répondez non au service NetBird Proxy. Il nécessite deux enregistrements DNS supplémentaires, proxy.netbird.example.com et le wildcard *.proxy.netbird.example.com, et n’apporte rien à un simple mesh. Répondez également non à CrowdSec. Vous pourrez ajouter ces deux composants plus tard.

Le script écrit dans le répertoire courant : docker-compose.yml, config.yaml avec le mode 600, dashboard.env et traefik-dynamic.yaml si vous avez choisi Traefik intégré. Considérez ce répertoire comme un état à conserver, car config.yaml contient la clé qui chiffre les données du store. Sa perte ne se corrige pas par une réinstallation.

docker compose ps
docker compose logs -f netbird-server

Chaque service doit lire running, et le journal du serveur doit se stabiliser au lieu de redémarrer en boucle. Surveillez séparément le certificat :

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) est le protocole utilisé par Traefik pour obtenir le certificat. Les erreurs à ce stade sont presque toujours dues au DNS ou à la fermeture du port 80.

Créer le premier compte administrateur

Ouvrez https://netbird.example.com. Sur une installation neuve, cette adresse affiche une page de configuration plutôt qu’un formulaire de connexion. Saisissez une adresse e-mail, un nom et un mot de passe, puis cliquez sur Create Account. Ce compte devient le premier compte administrateur, puis la page redirige vers le formulaire de connexion.

Ce compte est stocké dans le propre annuaire utilisateurs de NetBird, géré par un identity provider intégré au conteneur netbird-server. Aucun composant externe n’est nécessaire. Il s’agit du principal changement par rapport à la version self-hosted de NetBird d’il y a un an. À l’époque, une installation fonctionnelle nécessitait d’abord de déployer Zitadel ou Keycloak, puis de copier quatre valeurs OIDC (OpenID Connect) dans setup.env. Sans cela, aucun service ne démarrait.

Si votre navigateur affiche un avertissement concernant le certificat au lieu de la page de configuration, le certificat n’a pas été émis. Corrigez ce problème avant de continuer. Le dashboard communique avec l’API via le même nom d’hôte et son comportement devient difficile à diagnostiquer derrière un certificat incorrect.

Rejoindre votre premier pair

Installez le client sur n’importe quelle machine Linux, y compris le VPS lui-même si vous souhaitez l’ajouter au mesh :

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Sur Debian et Ubuntu, ce script configure le dépôt de paquets NetBird, puis installe le client avec apt. Le gestionnaire de paquets en reste donc propriétaire dans les deux cas. Si vous préférez éviter d’envoyer un script vers un shell, enregistrez-le d’abord avec curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh et lisez-le avant d’exécuter sh install.sh. Dans les deux cas, vérifiez ce qui a été installé :

apt-cache policy netbird

netbird est le client en ligne de commande et le daemon. netbird-ui est l’application de zone de notification du bureau. Un serveur headless n’en a pas besoin.

Configurez maintenant le client pour utiliser votre serveur :

sudo netbird up --management-url https://netbird.example.com

Si vous omettez --management-url, le client s’enregistre auprès du service hébergé de NetBird, car c’est la valeur par défaut intégrée au binaire. La commande réussit tout de même, la machine reçoit une adresse, et votre dashboard auto-hébergé reste vide. Cette erreur arrive presque toujours une fois.

La commande affiche une URL à ouvrir dans un navigateur pour terminer la connexion. Ensuite :

netbird status
ip addr show wt0

Lisez quatre lignes avec netbird status : Management: Connected, Signal: Connected, une ligne Relays: indiquant tous les relais disponibles, et une ligne NetBird IP: dans la plage de l’overlay. wt0 est l’interface WireGuard créée par NetBird. Elle doit porter cette même adresse.

Associer une deuxième machine sans intervention avec une clé d’installation

La connexion dans un navigateur ne fonctionne pas pour une machine sans navigateur et sans personne devant elle. Une clé d’installation est un jeton de préauthentification qui enregistre une machine sans étape interactive. Créez-en une dans le tableau de bord, sous Setup Keys.

Il en existe deux types. Une clé à usage unique authentifie exactement une machine, puis elle est consommée. Une clé réutilisable enregistre plusieurs machines, avec éventuellement une limite sur leur nombre. Les deux types ont une date d’expiration et peuvent automatiquement affecter le nouveau pair à un groupe. Les règles d’accès de ce groupe s’appliquent dès que la machine apparaît.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname définit le nom affiché dans le tableau de bord. Sans cette option, le pair prend le nom que la machine utilise elle-même. Une liste de machines dont les entrées portent toutes le nom ubuntu n’aide personne.

Pour les conteneurs et les agents de build à courte durée de vie, définissez la clé comme éphémère lors de sa création. Les pairs enregistrés avec une clé éphémère sont automatiquement supprimés dès qu’ils sont hors ligne depuis plus de 10 minutes. Cela évite de conserver des entrées obsolètes dans la liste des pairs.

Vous devez comprendre une limite avant de vous appuyer sur les clés d’installation : l’expiration ou la suppression d’une clé empêche les nouvelles inscriptions, mais ne déconnecte pas les machines qui l’ont déjà utilisée pour s’enregistrer. Pour supprimer l’accès d’une machine, vous devez supprimer ce pair.

Faut-il encore un fournisseur d’identité séparé ?

Pour une petite installation, non. Le store d’utilisateurs intégré gère les comptes créés depuis le tableau de bord. Cela suffit pour quelques utilisateurs.

Vous avez besoin d’un fournisseur d’identité externe si vous en utilisez déjà un et que vous ne voulez pas gérer une deuxième liste d’utilisateurs. NetBird accepte tout fournisseur compatible avec OIDC. Enregistrez un client OIDC confidentiel auprès de votre fournisseur, puis ajoutez-le dans le tableau de bord NetBird avec quatre valeurs : nom, ID client, secret client et issuer. NetBird vous fournit une URL de redirection à reporter dans le fournisseur. Des intégrations dédiées existent pour Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik et Pocket ID. Les autres fournisseurs se configurent comme OIDC générique. Si vous utilisez déjà Authentik comme solution de single sign-on auto-hébergée, cette méthode conserve une seule liste de comptes au lieu de deux.

La connexion locale reste disponible après l’ajout d’un fournisseur. Chaque fournisseur configuré apparaît sur la page de connexion. Conservez un compte administrateur local avec un mot de passe robuste. En cas de configuration OIDC défectueuse, vous pourrez toujours vous connecter avec ce compte.

NetBird ou Headscale : quel control plane déployer ?

Les deux suppriment la même dépendance : le serveur de contrôle hébergé que vos clients devraient sinon contacter. Ces projets n’ont toutefois pas la même approche.

Headscale réimplémente le serveur de contrôle de Tailscale, et vous continuez à utiliser les clients Tailscale officiels. Il n’existe pas de console web officielle. Vous gérez les utilisateurs et les clés de pré-authentification avec la commande headscale, à partir d’un fichier de configuration. Il existe des interfaces web communautaires, mais elles ne font pas partie du projet. Cette solution convient si vous voulez conserver votre état dans des fichiers et versionner vos modifications.

NetBird fournit le produit complet : son propre client, son propre tableau de bord, un fournisseur d’identité intégré et des règles d’accès que vous modifiez dans un navigateur. Cela ajoute davantage de composants sur votre VPS, mais demande beaucoup moins de travail à un collègue qui n’ouvrira jamais un terminal.

Déployez Headscale si vous utilisez déjà des clients Tailscale ou si vous voulez le control plane le plus minimal possible. Déployez NetBird si plusieurs personnes doivent gérer les pairs et si vous voulez une console et le SSO sans devoir les assembler vous-même. Avant de choisir l’une ou l’autre solution, vérifiez ce que couvre réellement l’offre gratuite de Tailscale, car un groupe de six utilisateurs ou moins avec un nombre illimité d’appareils ne paie rien pour un control plane hébergé et n’a peut-être aucune raison d’en déployer un. Au-delà de cette limite, la facture augmente selon le nombre de personnes et non selon le nombre de machines. Calculez donc le montant facturé par Tailscale à votre groupe afin de le comparer au coût du VPS et au temps que cette stack vous demande.

Quelle est la taille minimale d’un VPS pour l’exécuter ?

Le minimum documenté est de 1 CPU et 2 GB de mémoire. Les notes de NetBird indiquent maintenant un seuil proche de 1 GB de RAM, puisque la gestion des utilisateurs est locale. L’ancienne architecture nécessitait 2 GB à 4 GB lorsqu’un déploiement complet de Zitadel faisait partie de la stack. Prenez 2 GB. Cette marge permet de télécharger les nouvelles images pendant une mise à niveau alors que les anciennes sont encore présentes sur le disque.

Sur une petite machine, trois éléments peuvent être omis sans risque. N’activez pas le service NetBird Proxy. Il sert à publier des services internes sur des noms d’hôte publics et n’a aucun rapport avec la connexion des peers. N’activez pas CrowdSec. Il pourra être ajouté ultérieurement sur une machine exposée, mais il n’est pas nécessaire dès le premier jour. Conservez le stockage SQLite par défaut dans le volume netbird_data. Passez à PostgreSQL uniquement lorsque vous répartissez le déploiement sur plusieurs machines ou lorsque vous rencontrez un réel besoin de concurrence. La migration est documentée et peut être effectuée ultérieurement.

Le relay est le seul composant indispensable. Lorsque le NAT de deux peers attribue un port différent pour chaque destination, ils ne peuvent jamais établir de tunnel direct. Le relay est alors le seul chemin qui permet leur connexion. Le désactiver économise très peu de mémoire et provoque des échecs de connexion difficiles à diagnostiquer.

Lorsqu’une seule machine ne suffit plus, déplacez d’abord les relays. Un relay autonome s’exécute avec NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET et NB_ENABLE_STUN. Le secret partagé doit être identique sur le relay et sur le serveur principal. Sinon, les clients ne peuvent pas s’authentifier auprès du relay.

Modes d’échec et symptômes observables

Le tableau de bord affiche un avertissement concernant un certificat. Traefik n’a pas obtenu de certificat. Exécutez docker compose logs traefik | grep -i acme. Deux causes sont possibles. Soit dig +short netbird.example.com ne renvoie pas encore vers ce VPS, soit le port TCP 80 est fermé quelque part entre Let’s Encrypt et le conteneur, généralement au niveau du firewall réseau du fournisseur plutôt que sur ufw. Corrigez la cause avant de réessayer en boucle, car les validations échouées sont soumises à une limitation de débit et vous ne pourrez plus réessayer pendant une heure.

Le client indique qu’il s’est connecté, mais le tableau de bord est vide. Le client s’est enregistré auprès du service hébergé de NetBird, car --management-url était absent. Exécutez netbird status --detail et lisez la ligne Management:, qui indique le serveur auquel le client communique réellement. Si vous voyez Management: Connected to https://api.netbird.io:443, le client s’est connecté au cloud. Exécutez sudo netbird down, puis sudo netbird up --management-url https://netbird.example.com à nouveau.

Tous les peers affichent Connection type: Relayed. Aucun tunnel direct n’est établi. Tout le trafic passe donc par votre VPS, ce qui ajoute un saut et de la latence. Vérifiez le port UDP 3478 sur le firewall du VPS et sur celui du fournisseur, car STUN permet à un peer de connaître sa propre adresse et son propre port publics. netbird status --detail affiche également Direct: false et les types de candidats ICE (interactive connectivity establishment) pour chaque peer. Vous pouvez ainsi voir jusqu’où la tentative a progressé. Sur certains réseaux, relayed est le seul résultat possible et cela n’indique aucun problème.

Un peer rejoint le réseau, mais ne peut rien atteindre. Le fait d’appartenir au mesh ne signifie pas que deux peers peuvent communiquer. Les règles d’accès déterminent les communications autorisées. Un groupe auquel aucune policy n’est associée ne peut rien atteindre. Vérifiez la policy dans le tableau de bord avant de rechercher un problème de routage ou de firewall.

netbird status signale un problème avec le daemon. Le service n’est pas en cours d’exécution. Utilisez sudo netbird service status et sudo netbird service start. Les journaux du client se trouvent dans /var/log/netbird/client.log. Si vous ne parvenez pas à identifier le problème, netbird debug bundle --anonymize --system-info rassemble les journaux, l’état du service, les routes, la configuration DNS et l’état du firewall dans une seule archive.

Sauvegardes et mises à niveau

Deux éléments portent l’ensemble de l’installation : le répertoire qui contient docker-compose.yml et config.yaml, et le volume Docker qui contient la base de données et les clés de chiffrement. Sauvegardez-les ensemble. config.yaml contient la clé qui chiffre les données stockées. Une copie de la base de données sans cette clé ne permet de rien restaurer de lisible.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose préfixe les noms de volumes avec le répertoire du projet. Le volume documenté sous le nom netbird_data apparaît donc généralement sous le nom netbird_netbird_data. Exécutez d’abord docker volume ls et utilisez le nom qu’il affiche. Sinon, la commande docker run échoue en créant silencieusement un volume vide et en n’archivant rien. Conservez les archives en dehors du VPS. Si vous disposez déjà d’un outil de sauvegarde, restic ou BorgBackup prend en charge la partie externalisée.

La mise à niveau du serveur consiste à télécharger les nouvelles images et à recréer les conteneurs :

docker compose pull
docker compose up -d
docker compose ps

Avant de vous y fier, exécutez docker compose config | grep image:. Tout tag défini sur latest doit être remplacé par une version précise, pour la même raison que celle qui vous a conduit à figer le script d’installation : vous devez savoir ce qui s’exécute et disposer d’une version vers laquelle revenir si une mise à niveau se passe mal. Les clients se mettent à niveau avec le gestionnaire de paquets qui les a installés.

FAQ

Dois-je utiliser mon propre fournisseur d’identité pour auto-héberger NetBird ?

Non. Les versions actuelles incluent un magasin d’utilisateurs intégré. Vous créez donc le premier compte administrateur dans le navigateur à l’adresse https://netbird.example.com, puis vous ajoutez les utilisateurs depuis le dashboard. Un fournisseur OIDC externe est facultatif. Vous pouvez l’ajouter plus tard avec quatre valeurs : nom, ID client, secret client et issuer. Les guides qui vous demandent de déployer Zitadel ou Keycloak avant NetBird décrivent une configuration qui n’est plus nécessaire. En les suivant, vous devez gérer un service supplémentaire.

Pourquoi tous mes peers affichent-ils Connection type: Relayed ?

Les connexions directes ne s’établissent pas. Le trafic passe donc par le relay sur votre VPS. La cause habituelle est le blocage de l’UDP 3478. Il s’agit du port STUN utilisé par les peers pour découvrir leur propre adresse et leur propre port publics. Ouvrez ce port dans le firewall du VPS et dans le firewall réseau distinct de votre fournisseur. Exécutez ensuite netbird status --detail et lisez la ligne Direct:. Sur un réseau dont le NAT attribue un port différent selon la destination, le relay est le seul résultat possible. La configuration n’est alors pas incorrecte.

Mon client s’est connecté, mais le dashboard n’affiche aucun peer. Que s’est-il passé ?

Le client s’est enregistré auprès du service hébergé de NetBird au lieu de votre serveur. Cela se produit lorsque --management-url est absent. netbird status --detail affiche le serveur avec lequel le client communique, sur la ligne Management:. Une valeur telle que https://api.netbird.io:443 le confirme. Exécutez sudo netbird down, puis sudo netbird up --management-url https://netbird.example.com. Le peer apparaît alors dans votre dashboard.

Quelle est la différence entre NetBird auto-hébergé et Headscale ?

Les deux solutions remplacent un serveur de contrôle hébergé par un serveur que vous gérez. Headscale est uniquement un control plane : vous l’administrez avec la commande headscale et un fichier de configuration. Il n’existe pas de console web officielle et Headscale pilote les clients Tailscale officiels. NetBird fournit son propre client, un dashboard d’administration et l’intégration d’un fournisseur d’identité dans la même stack. Headscale est plus léger à exploiter et conserve son état dans des fichiers. NetBird est plus facile à remettre à des utilisateurs qui n’utiliseront pas de terminal.

De quelle taille de VPS un serveur NetBird auto-hébergé a-t-il besoin ?

Le minimum indiqué dans la documentation est de 1 CPU et 2 GB de mémoire. Il faut donc choisir 2 GB. En pratique, le seuil est descendu à environ 1 GB dans les versions récentes, car le fournisseur d’identité est désormais intégré au lieu d’être déployé séparément. Désactivez le proxy et les services CrowdSec facultatifs pendant l’installation. Conservez le magasin SQLite par défaut jusqu’à ce que PostgreSQL soit réellement nécessaire.