vellis/wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
wiki/Catalogue-Self-Hosted/apps/app-headscale.md
T
vellis bda02d587f Initial vault setup
2026-06-09 18:40:21 +02:00

8.9 KiB
Raw Permalink Blame History

title: Headscale created: 2026-06-07 updated: 2026-06-07 type: app tags: [catalogue, vpn, mesh, tailscale, zerotrust, nat-traversal, go, wireguard, coordination-server] confidence: high contested: false sources: [https://selfh.st/apps/?tag=VPN, https://github.com/juanfont/headscale]

🔐 Headscale

L'implémentation open source du serveur de coordination Tailscale — auto-hébergez votre mesh VPN WireGuard sans dépendre du cloud de Tailscale Inc.

📋 Informations Générales

Champ Valeur
Site web headscale.net
GitHub juanfont/headscale
License Apache-2.0
Langage Go
Étoiles GitHub 39 729 ⭐
Dernière MAJ 2026-06-07
Catégorie [[cat-vpn

📝 Description

Headscale est un serveur de coordination open source compatible avec le client officiel Tailscale. Là où Tailscale propose un service managé (control plane + coordination), Headscale réimplémente la partie serveur en Go pour vous permettre de garder le contrôle total sur l'infrastructure de votre mesh VPN. Concrètement, vos machines (serveurs, laptops, téléphones) exécutent le client Tailscale officiel et se connectent à votre instance Headscale au lieu du serveur de Tailscale Inc.

C'est l'une des pierres angulaires du mouvement "self-sovereign networking" : vous obtenez la simplicité d'usage de Tailscale (NAT traversal magique, MagicDNS, ACLs, partage de nœuds entre utilisateurs) sans confier vos métadonnées réseau à un tiers. Le projet, démarré en 2021 par Juan Font, est désormais largement utilisé en production par des homelabbers, des associations et même des entreprises.

  • ✅ 100% compatible avec le client Tailscale officiel (CLI, GUI macOS/Windows/Linux/iOS/Android)
  • ✅ NAT traversal : Hole punching STUN + relais DERP (vous pouvez aussi héberger vos propres DERP)
  • ✅ MagicDNS : résolution automatique des noms de pairs
  • ✅ ACLs (JSON) et Tailnet Lock (vérification des clés)
  • ✅ Multi-tenants (plusieurs "users"/namespaces)
  • ✅ PreAuth keys : enrollement simplifié (QR code, clé à usage unique)
  • ✅ Exit nodes : partager une connexion internet via le mesh
  • ✅ Subnets : router des sous-réseaux entiers à travers un pair
  • ✅ OpenID Connect / OIDC : intégration SSO (Keycloak, Authentik, Google…)
  • ✅ Binaire Go unique ou image Docker officielle
  • ✅ API REST + CLI headscale

Public cible : homelabbers avancés, équipes infra qui refusent le SaaS Tailscale, organisations avec contraintes de souveraineté (santé, finance, administration). Pour un usage basique solo, Tailscale gratuit (100 devices, 3 users) est souvent plus simple — Headscale prend tout son sens quand on veut échapper à la dépendance au cloud ou quand on dépasse les limites gratuites.

Vs Tailscale SaaS : Headscale offre les mêmes protocoles (WireGuard + Noise + DERP), mais l'écosystème de fonctionnalités Tailscale (Taildrop, SSH Tailscale, Funnel public) peut être en retard de quelques versions. Le client reste exactement le même.

🚀 Installation

Option 1 : Docker Compose (recommandé)

# docker-compose.yml
version: '3.8'
services:
  headscale:
    image: headscale/headscale:latest
    container_name: headscale
    restart: unless-stopped
    command: serve
    ports:
      - "443:443"      # API HTTPS
      - "80:80"        # Let's Encrypt challenge
      - "51820:51820/udp"  # WireGuard (optionnel en mode userspace)
    volumes:
      - ./config:/etc/headscale
      - ./data:/var/lib/headscale
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.headscale.rule=Host(`headscale.example.com`)"
      - "traefik.http.routers.headscale.entrypoints=websecure"
      - "traefik.http.routers.headscale.tls.certresolver=letsencrypt"
      - "traefik.http.services.headscale.loadbalancer.server.port=443"

  derp:
    image: ghcr.io/tailscale/derper:latest
    container_name: derper
    restart: unless-stopped
    command: /derper --hostname=derp.example.com --verify-clients=false
    ports:
      - "51820:51820/udp"  # Réutilisation du port WireGuard pour STUN
      - "443:443"          # Relay HTTPS
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.derp.rule=Host(`derp.example.com`)"
      - "traefik.http.routers.derp.tls.certresolver=letsencrypt"

💡 Le serveur DERP (relais) ci-dessus est optionnel mais recommandé : il améliore drastiquement le NAT traversal et la latence en cas de hole-punching impossible.

Option 2 : Binaire natif (Debian/Ubuntu)

curl -fsSL https://github.com/juanfont/headscale/releases/latest/download/headscale_linux_amd64 -o /usr/local/bin/headscale
chmod +x /usr/local/bin/headscale
# Générer la config
headscale generate private-key
sudo mkdir -p /etc/headscale
curl -fsSL https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o /etc/headscale/config.yaml
# Systemd unit
sudo systemctl enable --now headscale

⚙️ Configuration Initiale

  1. Créer un namespace utilisateur : headscale users create velli
  2. Générer une PreAuth Key : headscale preauthkeys create -u velli -e 24h --reusable --tags=tag:server
  3. Enregistrer un client sur la machine cliente : 
    tailscale up --login-server https://headscale.example.com --authkey=<PREAUTH_KEY>
  4. (Optionnel) Activer MagicDNS dans config.yaml (magic_dns: enabled: true)
  5. (Optionnel) Configurer les ACLs dans /etc/headscale/acl.yaml puis recharger
  6. Vérifier : headscale nodes list doit lister le pair nouvellement enregistré

🔄 Alternatives

Open Source

  • app-tailscale (SaaS officiel — gratuit jusqu'à 100 devices)
  • app-netbird — Concurrent direct, panel web intégré, plus jeune
  • app-zerotier + app-ztnet — Mesh global, philosophie différente (L2 Ethernet-like)
  • app-wg-easy — WireGuard "classique" site-à-site, sans mesh
  • Innernet — WireGuard mesh par tonic (sponsor Tailscale)

Propriétaires

  • Tailscale (freemium : 100 devices / 3 users, puis 5$/user/mois)
  • Cloudflare Tunnel (zero-trust + WARP, gratuit avec limits)
  • Zscaler Private Access (entreprise)
  • Palo Alto Prisma Access

Comparaison Headscale vs alternatives

Critère Headscale Tailscale SaaS NetBird ZeroTier
Self-hosted control plane ✅ ❌ ✅ ❌ (ZTnet = partiel)
License Apache-2.0 Propriétaire Apache-2.0 BSL (gros clients)
Protocol base WireGuard WireGuard WireGuard Propre (L2)
NAT traversal STUN + DERP STUN + DERP (rapide) STUN + ICE Propre
OIDC/SSO ✅ ✅ ✅ ❌
ACLs ✅ (avancées) ✅ (très fines) ✅ Basiques
MagicDNS ✅ ✅ ✅ ❌
UI web ❌ (CLI only) ✅ ✅ ❌

Verdict : si vous aimez Tailscale mais voulez maîtriser vos métadonnées réseau, Headscale est aujourd'hui le choix le plus mature. NetBird est son challenger le plus crédible grâce à son panel web.

🔐 Sécurité

  • ✅ WireGuard : cryptographie moderne (Curve25519 pour l'échange de clés, ChaCha20-Poly1305 pour le chiffrement, BLAKE2s pour le hachage) — l'IP publique des pairs peut fuiter via le serveur de coordination (utiliser Tailnet Lock pour mitiger)
  • ✅ Clés privées WireGuard : générées localement sur chaque machine, JAMAIS transmises au serveur de coordination (qui n'est qu'un "annuaire" — il ne voit pas le trafic)
  • ✅ OIDC : connecter Headscale à app-authentik ou Keycloak pour SSO + MFA obligatoire sur l'admin
  • ✅ ACLs strictes : principe du moindre privilège dans acl.yaml, auditer régulièrement
  • ✅ Logs d'audit : Headscale logge tous les enregistrements/départs de pairs, exporter vers app-loki ou Wazuh
  • ⚠️ Sauvegarder la clé privée du serveur (private_key.pem) et la clé Noise dans app-vaultwarden ou un coffre-fort — leur perte = perte du contrôle du tailnet
  • ⚠️ Activer Tailnet Lock en production pour empêcher un attaquant d'enregistrer un faux pair

📚 Ressources

Pages Liées

Reference in New Issue View Git Blame Copy Permalink