Héberger Headscale sur un VPS : serveur de contrôle Tailscale

Pourquoi auto-héberger le serveur de contrôle

Ce que Headscale auto-hébergé vous apporte

• Utilisateurs et appareils sans plafond : aucune limite imposé par le logiciel, pas de tarification par siège — votre réseau maillé grandit avec votre équipe, borné seulement par les ressources du VPS.
• 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 (poste.mesh.votre-domaine.com) sans modifier votre DNS public.
• Politiques HuJSON : le même format de fichier de politique que Tailscale, avec les ACL et les Grants — 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 activez le serveur DERP intégré à Headscale pour garder aussi les relais chez vous.
• API et CLI headscale : créez des utilisateurs, émettez des clés de pré-authentification et gérez les nœuds par programmation.
• Enregistrement sans compte tailscale.com : vos collaborateurs rejoignent le réseau avec une clé que vous générez, ou via le fournisseur OpenID Connect que vous utilisez déjà (Keycloak, Authelia, Google Workspace…).
• Sous-réseaux, exit nodes, Taildrop et Tailscale SSH : les fonctions de base de Tailscale sont prises en charge par le serveur.
• 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

Les ports à ouvrir sur le VPS

• TCP 443 : obligatoire. C’est par HTTPS que les clients s’enregistrent et reçoivent la carte du réseau ; c’est le seul port indispensable au serveur de coordination.
• TCP 80 : uniquement pour la validation Let’s Encrypt HTTP-01 et la redirection vers HTTPS.
• UDP 3478 : uniquement si vous activez le serveur DERP intégré, qui en a besoin pour STUN. Avec la carte DERP publique de Tailscale, inutile de l’ouvrir.
• TCP 8080 (Headscale), 9090 (métriques) et 50443 (gRPC) : à laisser sur 127.0.0.1. Le reverse proxy parle à 8080 en local ; n’exposez jamais l’interface d’administration gRPC sans en avoir besoin.

Déployer Headscale avec Docker Compose

1. 01

   Rédiger le fichier Compose

   La stack ne compte qu’un seul service : l’image officielle docker.io/headscale/headscale:0.29.7, dernière version stable au 7 novembre 2026, lancée avec la commande serve. Headscale garde tout — clés, base de données, enregistrements des nœuds — dans deux dossiers de l’hôte : la configuration, montée en lecture seule sur /etc/headscale, et les données, sur /var/lib/headscale. Aucun service externe de base de données ou de cache n’est nécessaire ; SQLite est intégré.

   mkdir -p /opt/headscale/config /opt/headscale/lib
   cat > /opt/headscale/compose.yaml <<'EOF'
   services:
     headscale:
       image: docker.io/headscale/headscale:0.29.7
       container_name: headscale
       restart: unless-stopped
       read_only: true
       tmpfs:
         - /var/run/headscale
       ports:
         - "127.0.0.1:8080:8080"
       volumes:
         - /opt/headscale/config:/etc/headscale:ro
         - /opt/headscale/lib:/var/lib/headscale
       command: serve
       healthcheck:
         test: ["CMD", "headscale", "health"]
   EOF

   Le port n’est publié que sur 127.0.0.1 : c’est le reverse proxy qui fera face à Internet.

2. 02

   Générer la configuration

   Partez du fichier d’exemple de la version exacte que vous déployez, puis ne modifiez que les clés ci-dessous. server_url est l’URL HTTPS à laquelle vos clients Tailscale se connecteront ; listen_addr doit écouter sur 0.0.0.0 à l’intérieur du conteneur. La base se déclare sous database (type: sqlite). Seule la clé noise reste à indiquer : Headscale la génère au premier démarrage si le fichier n’existe pas.

   curl -Lo /opt/headscale/config/config.yaml \
     https://raw.githubusercontent.com/juanfont/headscale/v0.29.7/config-example.yaml

   server_url: https://vpn.votre-domaine.com
   listen_addr: 0.0.0.0:8080
   noise:
     private_key_path: /var/lib/headscale/noise_private.key
   database:
     type: sqlite
     sqlite:
       path: /var/lib/headscale/db.sqlite
   dns:
     magic_dns: true
     base_domain: mesh.votre-domaine.com

   Sur ServOrbit, le job de provisioning écrit config.yaml à partir de votre domaine automatiquement.

3. 03

   Démarrer le conteneur et vérifier

   Lancez docker compose up -d depuis /opt/headscale. Headscale génère sa clé noise, puis se met à écouter sur le port 8080. Vérifiez l’endpoint de santé : curl -s http://127.0.0.1:8080/health doit renvoyer {"status":"pass"}. L’image est construite sur une base distroless, sans shell, mais la CLI headscale s’appelle directement : docker exec headscale headscale version confirme la version en cours d’exécution, et docker logs --follow headscale affiche les journaux.

4. 04

   Créer un utilisateur et générer une clé d’authentification

   Headscale organise les appareils en « utilisateurs » (auparavant appelés namespaces). Créez-en un, puis relevez son identifiant numérique : l’option --user de preauthkeys create attend cet ID, pas le nom.

   docker exec headscale headscale users create myteam
   docker exec headscale headscale users list
   docker exec headscale headscale preauthkeys create --user 1 --reusable --expiration 24h

   Sans --reusable, la clé ne sert qu’une fois, et sans --expiration elle expire au bout d’une heure. Copiez la clé affichée — vous l’utiliserez pour enregistrer chaque appareil.

5. 05

   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. Sans clé, le client ouvre une page qui affiche un identifiant d’authentification ; approuvez-le côté serveur avec docker exec headscale headscale auth register --user myteam --auth-id <AUTH_ID>. Une fois enregistrés, les appareils communiquent par leur IP de maillage (100.64.x.y) ou par leur nom d’hôte magic DNS.

6. 06

   Définir les politiques de contrôle d’accès

   Tant qu’aucune politique n’est chargée, Headscale laisse passer tout le trafic entre les nœuds — acceptable pour une petite équipe de confiance, pas dès que postes de développeurs, prestataires et serveurs de production cohabitent. Créez /opt/headscale/config/policy.hujson et déclarez-le dans config.yaml sous policy.path: /etc/headscale/policy.hujson. Headscale utilise le même format HuJSON que Tailscale : 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. Le projet recommande les Grants plutôt que les ACL, que Tailscale considère comme historiques. Validez le fichier avec headscale policy check --file <fichier>, puis rechargez : la politique n’est relue qu’au rechargement (docker kill --signal=HUP headscale, ou systemctl reload headscale en natif). Versionnez ce fichier dans un dépôt Git privé pour garder l’historique des accès.

7. 07

   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 la clé avec preauthkeys create --user <ID> --reusable --expiration 24h, et raccordez vos machines avec tailscale up --login-server https://<votre-domaine> --authkey <clé>. Les applications graphiques savent aussi viser un serveur personnalisé : sur macOS, Option + clic sur l’icône Tailscale, menu Debug, puis Custom Login Server ; sur iOS, Use custom coordination server dans le menu de connexion ; sur Android, Use an alternate server ; sur Windows, tailscale login --login-server dans PowerShell.

Sans Docker : le paquet .deb officiel

Installer Headscale avec le paquet .deb

1. 08

   Télécharger et installer le paquet

   Récupérez le paquet de la version voulue sur la page des releases GitHub, pour votre architecture (amd64 ou arm64), et installez-le avec apt, qui résout les dépendances :

   HEADSCALE_VERSION="0.29.7"
   HEADSCALE_ARCH="amd64"
   wget --output-document=headscale.deb \
     "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
   sudo apt install ./headscale.deb

   Vérifiez ensuite : headscale version doit afficher 0.29.7.

2. 09

   Adapter la configuration

   Le paquet dépose la configuration dans /etc/headscale/config.yaml et un exemple à jour dans /usr/share/doc/headscale/examples/config-example.yaml. Modifiez les mêmes clés que pour Docker (server_url, database, dns.base_domain), mais gardez listen_addr: 127.0.0.1:8080 : le service tourne sur l’hôte, seul le reverse proxy doit l’atteindre. Les données vivent dans /var/lib/headscale.

3. 10

   Redémarrer et vérifier le service

   Relancez le service pour qu’il relise la configuration, puis contrôlez son état et ses journaux :

   sudo systemctl restart headscale
   sudo systemctl status headscale
   sudo journalctl -u headscale -f

   La sortie doit afficher Active: active (running). Au premier démarrage, les erreurs les plus fréquentes sont une server_url sans schéma https:// et un domaine MagicDNS identique à celui du serveur.

4. 11

   Utiliser la CLI sans être root

   La CLI parle au service par le socket Unix /var/run/headscale/headscale.sock, accessible par défaut au seul utilisateur headscale et à root. Passez par sudo, exécutez les commandes en tant qu’utilisateur headscale, ou ajoutez votre compte au groupe headscale. Vérifiez l’accès avec headscale users list.

Exposer Headscale en HTTPS derrière Nginx

map $http_upgrade $connection_upgrade {
  default keep-alive;
  ''      close;
}

server {
  listen 80;
  server_name vpn.votre-domaine.com;
  location = /generate_204 { return 204; }
  location / { return 301 https://$server_name$request_uri; }
}

server {
  listen 443 ssl;
  http2 on;
  server_name vpn.votre-domaine.com;
  ssl_certificate     /etc/letsencrypt/live/vpn.votre-domaine.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vpn.votre-domaine.com/privkey.pem;

  location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_pass http://127.0.0.1:8080;
  }
}

trusted_proxies:
  - 127.0.0.1/32
  - ::1/128

Vérifier que les nœuds se voient

Contrôler le maillage depuis un client

1. 12

   Lire l’état du réseau

   Sur un nœud enregistré, lancez tailscale status. La commande liste les pairs avec leur IP de maillage, leur nom et le type de liaison : direct signifie que le tunnel WireGuard est établi sans intermédiaire, relay qu’il passe par un relais DERP — fonctionnel, mais avec une latence plus élevée.

2. 13

   Tester la connectivité

   Relevez l’IP d’un pair dans tailscale status, puis ping 100.64.0.2, ou mieux tailscale ping <nom-du-nœud>, qui indique si la réponse arrive en direct ou par un relais. Si le pair est listé mais ne répond pas, tailscale netcheck mesure la latence vers chaque région DERP et signale un UDP sortant filtré.

3. 14

   Tester la résolution MagicDNS

   Avec dns.magic_dns: true, chaque nœud répond à son nom court et à son nom complet : ping nom-du-noeud ou ping nom-du-noeud.mesh.votre-domaine.com. Aucun enregistrement DNS public n’est nécessaire pour ces noms internes. Si la résolution échoue, tailscale dns status montre la configuration DNS que le client a reçue du serveur.

Cas d’usage : SSH entre VPS sans exposer le port 22

Restreindre SSH au réseau maillé

1. 15

   Repérer l’interface et l’adresse de maillage

   Sur chaque VPS, le client Tailscale crée l’interface tailscale0. tailscale ip -4 affiche l’adresse de maillage de la machine ; notez celle du serveur de production, par exemple 100.64.0.3.

2. 16

   N’autoriser SSH que par tailscale0

   Sur le VPS de production, autorisez SSH sur l’interface de maillage avant de le refuser ailleurs — UFW applique la première règle qui correspond :

   ufw allow in on tailscale0 to any port 22 proto tcp
   ufw deny 22/tcp
   ufw enable
   ufw status verbose

   Le port 22 n’est plus joignable depuis Internet, mais reste ouvert à tous les nœuds du maillage autorisés par votre politique.

3. 17

   Se connecter par le maillage

   Depuis le VPS de développement ou votre poste enregistré, connectez-vous par l’IP ou le nom MagicDNS : ssh [email protected] ou ssh [email protected]. Tout transite dans le tunnel chiffré ; restreignez ensuite dans la politique Headscale quels groupes peuvent atteindre le port 22 de ce serveur.

Migrer une équipe déjà sur Tailscale

Basculer les clients vers Headscale

1. 18

   Reprendre la politique d’accès

   Copiez le fichier de politique de votre tailnet depuis l’éditeur Access controls de la console Tailscale et repartez-en : le format HuJSON est le même. Contrôlez-le avec headscale policy check avant la bascule — certaines fonctions, comme les IP sets, ne sont pas prises en charge, et seul un sous-ensemble des autogroups existe.

2. 19

   Déconnecter puis reconnecter chaque client

   Sur Linux ou en ligne de commande, enchaînez la déconnexion et la reconnexion avec une clé de pré-authentification :

   tailscale logout
   tailscale up --login-server https://vpn.votre-domaine.com --authkey <PREAUTHKEY>

   Sur macOS, iOS, Android et Windows, déconnectez le compte dans l’application, puis ajoutez le serveur personnalisé comme décrit plus haut.

3. 20

   Commencer par les machines de test

   Basculez d’abord un poste et un serveur de test, vérifiez tailscale status et la résolution des noms, puis les machines de développement et, en dernier, la production. Tant que des machines restent de l’autre côté, les deux réseaux ne se voient pas : planifiez la bascule d’un service et de ses clients dans la même fenêtre.

4. 21

   Fermer ou rétrograder le compte Tailscale

   Une fois tous les nœuds migrés et vérifiés, fermez le tailnet ou repassez sur le plan Personal si vous gardez un usage personnel. Générez une nouvelle clé de pré-authentification pour les prochains enregistrements plutôt que de garder indéfiniment celle de la migration.

Headscale vs Tailscale Cloud

Tailscale Personal, Tailscale Standard et Headscale

Faites défiler le tableau

Ce que Headscale ne remplace pas

Sauvegardes et mises à jour

• Sauvegardez avant chaque mise à jour : Headscale applique ses migrations de base au démarrage de la nouvelle version. Arrêtez le service, copiez la configuration et les données, puis relancez : cd /opt/headscale && docker compose stop, cp -aR /opt/headscale /opt/headscale.backup-$(date +%Y%m%d%H%M%S), docker compose up -d.
• Le dossier de données contient db.sqlite et noise_private.key : perdre cette clé change l’identité du serveur et oblige tous les nœuds à se réenregistrer. Copiez-le aussi hors du VPS, par exemple vers un stockage objet.
• Montez de version en version : le projet impose de passer par chaque version mineure stable (par exemple 0.27 puis 0.28 puis 0.29), toujours dans son dernier correctif, sans en sauter.
• Lisez la note de version sur GitHub avant chaque mise à jour : elle signale les changements cassants de configuration. Comparez ensuite votre config.yaml au fichier d’exemple de la nouvelle version.

Dépannage : les erreurs les plus fréquentes

• Le client n’arrive pas à s’enregistrer : vérifiez que https://vpn.votre-domaine.com/health répond depuis l’extérieur, que server_url correspond exactement au domaine du certificat, et que le proxy relaie bien les en-têtes Upgrade et Connection.
• Connexions en relay au lieu de direct : un NAT strict ou un pare-feu bloque l’UDP entre les deux nœuds. Lancez tailscale netcheck des deux côtés pour voir ce qui est filtré ; le trafic passe quand même, par les relais DERP.
• Nœud listé offline : le client a joint le serveur mais ne maintient pas la session. Vérifiez systemctl status tailscaled et journalctl -u tailscaled sur le nœud ; un pare-feu local qui coupe les connexions sortantes est la cause la plus courante.
• Headscale refuse de démarrer après une mise à jour : une clé de configuration a été renommée ou retirée. Le journal la nomme ; reportez-vous au fichier d’exemple de la version installée.
• MagicDNS ne résout pas : contrôlez que dns.magic_dns est à true et que dns.base_domain diffère du domaine de server_url, puis reconnectez le client pour qu’il récupère la nouvelle configuration DNS.