Migrer de Tailscale vers Headscale : le seuil de rentabilité

Pourquoi reconsidérer son réseau mesh en 2026

• Contrôle total des données : aucune liste de vos machines, adresses IP internes, noms de nœuds ou journaux de connexion ne transite par un serveur tiers.
• Pas de limite de nœuds ni d'utilisateurs imposée par le logiciel : Headscale est borné uniquement par les ressources de votre VPS.
• Compatibilité totale avec les clients Tailscale officiels : le drapeau --login-server suffit à pointer vers votre control plane.
• MagicDNS sur votre propre domaine : chaque nœud est joignable par son nom court sur le suffixe que vous choisissez.
• OIDC optionnel : délégation d'authentification à Keycloak, Authelia ou tout fournisseur OIDC compatible.
• Pérennité opérationnelle : votre réseau mesh ne dépend plus d'une décision tarifaire ou d'une indisponibilité externe.
• Maintenance raisonnable : une mise à jour de paquet toutes les quelques semaines, une sauvegarde SQLite planifiable en une ligne de cron.

Analyse financière : le seuil de rentabilité

Tailscale Standard vs Headscale sur VPS

Faites défiler le tableau

Prérequis techniques chiffrés

• VPS sous Debian 11/12 ou Ubuntu 22.04/24.04 — 1 vCPU, 512 Mo RAM minimum (Headscale tourne en moins de 64 Mo idle ; 1 Go recommandé pour laisser de la marge au système).
• Port TCP 443 ouvert côté entrant : les clients s'y connectent pour l'enregistrement et la récupération de configuration via HTTPS.
• Port UDP 3478 ouvert : utilisé pour la négociation STUN (détection des adresses candidates pour les connexions directes).
• Port UDP 41641 ouvert : port de signalisation WireGuard que les clients Tailscale utilisent pour contacter le coordinateur.
• Un nom de domaine ou sous-domaine pointant vers le VPS : requis pour un certificat TLS valide. Let's Encrypt fonctionne via certbot ou via le module nginx intégré.
• SQLite intégré : Headscale n'a besoin d'aucune base de données externe — une seule base SQLite dans /var/lib/headscale/ suffit pour des centaines de nœuds.

Installer Headscale sur un VPS ServOrbit

1. 01

   Mettre à jour le système et installer les dépendances

   Connectez-vous en SSH à votre VPS et mettez à jour les paquets :

   apt update && apt upgrade -y

   Installez nginx et certbot pour le reverse proxy HTTPS :

   apt install -y nginx certbot python3-certbot-nginx

2. 02

   Télécharger et installer le paquet Headscale

   Headscale v0.29.4 (septembre 2026) distribue des paquets .deb pour amd64 et arm64. Téléchargez et installez le paquet :

   curl -Lo /tmp/headscale.deb https://github.com/juanfont/headscale/releases/download/v0.29.4/headscale_0.29.4_linux_amd64.deb

   dpkg -i /tmp/headscale.deb

   Vérifiez l'installation : headscale version doit retourner 0.29.4. Sur ARM64, remplacez linux_amd64 par linux_arm64.

3. 03

   Configurer Headscale

   Le paquet crée l'utilisateur système headscale et le dossier /etc/headscale/. Éditez la configuration minimale :

   nano /etc/headscale/config.yaml

   Définissez au minimum : server_url: https://headscale.votre-domaine.com, listen_addr: 0.0.0.0:8080, db_type: sqlite3, db_path: /var/lib/headscale/db.sqlite, et dans dns_config : magic_dns: true, base_domain: votre-domaine.com. Créez le dossier de données : mkdir -p /var/lib/headscale && chown headscale:headscale /var/lib/headscale.

4. 04

   Activer et démarrer le service

   Le paquet installe l'unité systemd automatiquement :

   systemctl enable --now headscale

   Vérifiez l'état : systemctl status headscale. La sortie doit afficher Active: active (running). En cas d'erreur, consultez les journaux : journalctl -u headscale -f. L'erreur la plus fréquente au premier démarrage est un server_url mal formé — il doit commencer par https://.

5. 05

   Mettre en place le reverse proxy HTTPS

   Obtenez un certificat Let's Encrypt et configurez nginx :

   certbot --nginx -d headscale.votre-domaine.com

   Dans le vhost nginx généré, ajoutez dans le bloc location / :

   proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;

   Rechargez nginx : systemctl reload nginx. Vérifiez que https://headscale.votre-domaine.com/health retourne {"status":"pass"}.

6. 06

   Créer un premier utilisateur et une pré-clé d'authentification

   Headscale organise les nœuds par utilisateurs. Créez votre premier utilisateur :

   headscale users create mon-equipe

   Générez une pré-clé d'authentification (preauthkey) pour enregistrer vos machines sans validation manuelle :

   headscale preauthkeys create --user mon-equipe --expiration 24h

   Copiez la clé retournée — vous en aurez besoin à l'étape de migration des clients. L'option --reusable permet de réutiliser la même clé pour plusieurs machines.

7. 07

   Ouvrir les ports nécessaires dans le pare-feu

   Si votre VPS utilise ufw, ouvrez les ports requis :

   ufw allow 443/tcp
ufw allow 3478/udp
ufw allow 41641/udp

   Si vous utilisez iptables directement ou un panel de sécurité (CSF, Imunify360), ajoutez ces ports dans la liste des ports entrants autorisés. Vérifiez depuis une machine externe que les ports UDP sont bien joignables avant de migrer vos clients.

Migrer ses clients depuis Tailscale en 3 étapes

1. 08

   Déconnecter le client du réseau Tailscale existant

   Sur chaque machine à migrer, commencez par déconnecter le client du réseau Tailscale :

   tailscale logout

   Sur macOS et Windows, utilisez le menu de la barre d'état system : clic droit sur l'icône Tailscale → Log out. Sur iOS et Android, allez dans les paramètres de l'application → Log out. Cette étape révoque l'authentification sur l'ancien réseau mais ne désinstalle pas le client.

2. 09

   Reconnecter le client vers votre serveur Headscale

   Reconnectez le client en pointant vers votre nouveau serveur Headscale. Sur Linux :

   tailscale up --login-server https://headscale.votre-domaine.com --authkey VOTRE_PREAUTHKEY

   Sur macOS, depuis le terminal :

   tailscale up --login-server https://headscale.votre-domaine.com --authkey VOTRE_PREAUTHKEY

   Si vous ne passez pas de preauthkey, le client affiche une URL d'authentification à valider côté serveur avec : headscale nodes register --user mon-equipe --key <NODE_KEY>. Vérifiez l'enregistrement : headscale nodes list doit afficher le nœud avec le statut online.

3. 10

   Vérifier la connectivité entre les nœuds migrés

   Depuis un nœud migré, vérifiez que les autres nœuds sont visibles :

   tailscale status

   La liste doit afficher tous les nœuds enregistrés sur votre serveur Headscale avec leur IP mesh (100.64.x.x). Testez la connectivité directe avec un ping : ping 100.64.0.2. Un statut active (direct) confirme que la connexion WireGuard est établie sans relais. Si vous avez activé MagicDNS, testez la résolution : ping nom-du-noeud.votre-domaine.com.

4. 11

   Migrer les nœuds restants et fermer le compte Tailscale

   Répétez les deux étapes précédentes pour chaque machine. Migrez d'abord les machines de développement ou de test pour valider le process, puis les machines de production. Une fois tous les nœuds migrés et vérifiés, vous pouvez fermer votre compte Tailscale ou rétrograder sur le plan Personal si vous avez encore des usages personnels (six utilisateurs max, gratuit). Conservez la preauthkey utilisée ou générez-en une nouvelle pour les prochains nœuds à enregistrer.

Configuration des ACLs et des DNS internes

• Éditez le fichier de politique : headscale policy set --policy-file /etc/headscale/policy.hujson
• Définissez des groupes d'utilisateurs (groups) et des ACLs par port pour segmenter les accès entre les environnements dev, staging et prod.
• Activez les DNS split pour résoudre les noms internes : dans dns_config, définissez nameservers avec vos serveurs DNS internes et search_domains pour les suffixes de recherche.
• Exportez et versionez votre fichier de politique dans un dépôt Git privé — cela facilite les audits et les retours arrière.
• Testez les changements de politique sur un nœud de test avant de les appliquer à l'ensemble du réseau : headscale policy check.

Dépannage des problèmes fréquents

• Nœud affiche offline dans headscale nodes list : vérifiez que les ports UDP 3478 et 41641 sont bien ouverts côté VPS. Testez depuis une machine externe avec nc -vzu headscale.votre-domaine.com 41641.
• Connexion en relay au lieu de direct : les connexions indirectes via DERP passent quand les deux nœuds ne peuvent pas s'atteindre directement (NAT strict, pare-feu). Vérifiez tailscale netcheck sur les deux nœuds pour identifier les contraintes réseau.
• MagicDNS ne résout pas les noms : vérifiez que magic_dns: true et base_domain sont bien définis dans la configuration Headscale, et que le client a bien récupéré la nouvelle configuration DNS après la reconnexion (tailscale status --self).
• Certificat TLS invalide au démarrage : le server_url dans config.yaml doit correspondre exactement au domaine du certificat. Une URL en http:// alors que nginx attend https:// déclenche des erreurs de redirection en boucle.
• Clients macOS ou Windows ne voient pas l'option --login-server dans l'interface graphique : utilisez toujours le terminal pour la migration. L'interface graphique Tailscale ne permet pas de changer de serveur de coordination ; seule la ligne de commande le permet.

Ce que Headscale ne remplace pas