Pourquoi auto-héberger le serveur de contrôle
Tailscale est un logiciel exceptionnel — les performances de WireGuard, des clients multiplateformes, un magic DNS qui fonctionne du premier coup. Le plan de contrôle (le serveur de coordination qui distribue les clés et les ACL) est la partie qui tourne dans le cloud de Tailscale. Headscale réimplémente ce serveur de coordination en Go open source pour que vous puissiez le faire tourner sur votre propre infrastructure.
Au-delà de la limite de 3 utilisateurs de l’offre gratuite, la principale raison de l’auto-héberger est la résidence des données : le plan de contrôle sait quelles machines sont sur votre réseau, leurs IP et vos politiques d’ACL. Faire tourner Headscale signifie que ces informations restent sur votre VPS — et non dans le cloud de quelqu’un d’autre.
Ce que Headscale auto-hébergé vous apporte
- Utilisateurs et appareils illimités : pas de plafond à 3 utilisateurs, pas de tarification par siège — votre réseau maillé grandit avec votre équipe.
- Les clients Tailscale officiels partout : Linux, macOS, Windows, iOS, Android — aucun fork maison ni client alternatif requis.
- Tunnels WireGuard pair à pair : Headscale ne gère que l’échange de clés et la distribution des ACL ; tout le trafic réel circule directement en WireGuard entre les pairs.
- Magic DNS : résolvez chaque nœud de votre réseau maillé par son nom d’hôte (machine.headnet.local) sans modifier votre DNS public.
- Listes de contrôle d’accès HuJSON : le même format de politique d’ACL que Tailscale — définissez quels utilisateurs et quels appareils peuvent accéder à quels services.
- Prise en charge des relais DERP : utilisez la carte DERP publique de Tailscale pour la traversée de NAT, ou déployez votre propre relais privé.
- API REST et CLI headscale : créez des namespaces, émettez des clés de pré-authentification et gérez les pairs par programmation.
- Moins de 50 Mo de RAM au repos — tourne confortablement sur un VPS de 1 Go aux côtés d’autres charges de travail.
Prérequis
Un VPS avec au moins 1 vCPU et 512 Mo de RAM sous Ubuntu 22.04, avec Docker et Docker Compose v2 installés. Un nom de domaine pointant vers le VPS est requis — les clients Tailscale se connectent au serveur de contrôle par URL, et le HTTPS (via un reverse proxy comme Caddy ou Nginx avec Let’s Encrypt) est fortement recommandé. Le port 8080 doit être joignable depuis Internet (ou uniquement depuis vos appareils si vous préférez un plan de contrôle purement interne).
Déployer Headscale avec Docker Compose
Rédiger le fichier Compose
Créez /opt/headscale/compose.yaml. La stack ne compte qu’un seul service : headscale/headscale:0.29.2. Headscale stocke tout — clés, base de données, enregistrements des nœuds — dans des volumes Docker nommés, montés sur /etc/headscale (config) et /var/lib/headscale (données). Aucun service externe de base de données ou de cache n’est nécessaire ; SQLite est intégré.
Générer la configuration
Headscale lit sa configuration depuis /etc/headscale/config.yaml. Le seul champ obligatoire est server_url — l’URL HTTPS à laquelle vos clients Tailscale se connecteront (par exemple https://vpn.votre-domaine.com). Définissez listen_addr: 0.0.0.0:8080 et database.type: sqlite3 avec un chemin sous /var/lib/headscale. Les chemins des clés privées (private_key_path, noise.private_key_path) sont générés automatiquement par Headscale au premier démarrage s’ils n’existent pas. Sur ServOrbit, le job de provisioning écrit config.yaml à partir de votre domaine automatiquement.
Démarrer le conteneur et vérifier
Lancez docker compose up -d. Headscale génère automatiquement sa clé privée WireGuard et sa clé noise, puis se met à écouter sur le port 8080. Vérifiez l’endpoint de santé : curl -s http://localhost:8080/health doit renvoyer {"status":"pass"}. La CLI headscale est disponible dans le conteneur : docker exec headscale headscale version pour confirmer la version en cours d’exécution.
Créer un utilisateur et générer une clé d’authentification
Tailscale organise les appareils en « utilisateurs » (auparavant appelés namespaces). Créez-en un : docker exec headscale headscale users create myteam. Générez ensuite une clé de pré-authentification pour enregistrer les appareils : docker exec headscale headscale preauthkeys create --user myteam --reusable --expiration 24h. Copiez la clé affichée — vous l’utiliserez pour enregistrer chaque appareil.
Enregistrer un appareil
Sur n’importe quel appareil disposant du client Tailscale officiel, pointez-le vers votre instance Headscale : tailscale up --login-server https://vpn.votre-domaine.com --authkey <votre-clé-preauth>. L’appareil apparaît dans la liste des nœuds de Headscale en quelques secondes : docker exec headscale headscale nodes list. Répétez pour chaque appareil. Une fois enregistrés, les appareils peuvent communiquer entre eux par leur IP de maillage (100.x.x.x) ou par leur nom d’hôte magic DNS.
Définir les politiques de contrôle d’accès
Créez /etc/headscale/acls.hujson et référencez-le dans config.yaml via acls_path. Headscale utilise le même format d’ACL HuJSON que Tailscale Cloud : définissez des groupes d’utilisateurs, étiquetez les appareils comme serveurs ou postes de travail, et écrivez des règles précisant quels groupes peuvent atteindre quels ports. Une politique minimale autorise tous les utilisateurs à atteindre tous les nœuds ; resserrez-la en restreignant l’accès aux services sensibles (bases de données, panneaux d’administration) à des groupes d’utilisateurs spécifiques.
Se connecter la première fois
Headscale n'a pas d'interface web ni de compte : c'est le serveur de contrôle de votre réseau privé, piloté en ligne de commande. En SSH : docker exec -it headscale headscale users create monuser, puis headscale preauthkeys create --user monuser --reusable --expiration 24h, et raccordez vos machines avec tailscale up --login-server https://<votre-domaine> --authkey <clé>.
Associer Headscale à Authelia pour un accès réseau protégé par MFA
Headscale gère le contrôle d’accès au niveau réseau (quelles IP peuvent communiquer avec quels pairs), mais il n’applique pas d’authentification au niveau applicatif. Associez-le à Authelia sur le même VPS : faites passer vos services internes (accessibles uniquement via le maillage) par la couche forward-auth d’Authelia. Les utilisateurs doivent valider un MFA pour accéder aux services, même une fois sur le maillage — de la défense en profondeur pour les charges sensibles.
Headscale vs Tailscale Cloud
Tailscale Cloud reste la voie la plus simple pour les petites équipes : aucun serveur à maintenir, des mises à jour automatiques, une facturation intégrée. Headscale prend tout son sens lorsque vous avez plus de 3 utilisateurs et voulez éviter les coûts par siège, lorsque la résidence des données impose de garder la topologie de votre réseau hors des serveurs tiers, ou lorsque vous voulez une auditabilité complète de vos logs de coordination. Les clients sont identiques — passer de Tailscale Cloud à Headscale revient à relancer tailscale up --login-server sur chaque appareil, rien de plus.
