175 lines
8.9 KiB
Markdown
175 lines
8.9 KiB
Markdown
---
|
|
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](https://headscale.net/) |
|
|
| **GitHub** | [juanfont/headscale](https://github.com/juanfont/headscale) |
|
|
| **License** | Apache-2.0 |
|
|
| **Langage** | Go |
|
|
| **Étoiles GitHub** | 39 729 ⭐ |
|
|
| **Dernière MAJ** | 2026-06-07 |
|
|
| **Catégorie** | [[cat-vpn|VPN & Réseau privé]] |
|
|
|
|
## 📝 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é)
|
|
|
|
```yaml
|
|
# 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)
|
|
|
|
```bash
|
|
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 :
|
|
```bash
|
|
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
|
|
|
|
- [Site officiel Headscale](https://headscale.net/)
|
|
- [GitHub juanfont/headscale](https://github.com/juanfont/headscale)
|
|
- [Documentation](https://headscale.net/kb/)
|
|
- [Comparatif Headscale vs Tailscale](https://headscale.net/comparison/)
|
|
|
|
## Pages Liées
|
|
- [[cat-vpn]] — Catégorie VPN & Réseau privé
|
|
- [[app-tailscale]] — Le client officiel utilisé avec Headscale
|
|
- [[app-netbird]] — Concurrent open source
|
|
- [[app-wireguard]] — Le protocole sous-jacent
|
|
- [[app-traefik]] — Reverse proxy / HTTPS
|
|
- [[app-authentik]] — SSO OIDC
|
|
- [[securisation-home-lab]] — Bonnes pratiques globales
|
|
- [[glossaire-homelab]] — Définitions réseau
|
|
- [[comparatif-vpn-mesh]] — Comparatif global mesh VPN
|