Info::NETWORK:HeadScale VPN
KEYWORDS: NETWORK, HEADSCALE
Le 15/09/2026:
Headscale
Version : 1.0 Date : 2026-09-15
Fonctionnement
Exemple de fonctionnement sur tablette: ssh srv18.headscale.pcstreet.org
Le réseau privé de la flotte PCStreet repose sur headscale, une
implémentation auto-hébergée (open-source) du serveur de contrôle
Tailscale. Un seul serveur de contrôle existe ; toutes les autres
machines sont des clients qui le rejoignent avec le paquet
officiel tailscale.
| Rôle | Logiciel | Machine |
|---|---|---|
| Serveur de contrôle (control-plane) | headscale v0.29.3 |
srv18 (192.168.1.18) |
| Client (rejoint le réseau) | tailscale (paquet officiel) |
tous les autres nœuds |
Point de confusion fréquent : on n'installe headscale
qu'une seule fois (le control-plane). Les autres serveurs installent le
client tailscale et se rattachent avec
tailscale up --login-server=https://headscale.pcstreet.org.
Ils ne font "tourner" aucune instance headscale.
Adressage du tailnet
- Plage IPv4 :
100.64.254.0/24(254 adresses). - Pourquoi pas
10.0.254.0/24(demandé initialement) :
la documentation headscale est formelle, les préfixes v4 alloués aux nœuds doivent être un sous-ensemble de la plage CGNAT officielle Tailscale100.64.0.0/10— le client Tailscale a cette plage en dur, en sortir casse le tunnel de façon subtile et non documentée.100.64.254.0/24garde le style ".254" demandé tout en restant dans la plage autorisée.
- IPv6 :
fd7a:115c:a1e0::/48(valeur par défaut headscale,
plage ULA, sans lien avec le plan d'adressage 10.x du LAN).
- MagicDNS activé, domaine de base
ts.pcstreet.org(usage
interne uniquement, aucune résolution publique requise pour ce nom).
- DERP : relais publics Tailscale par défaut (pas de serveur DERP
auto-hébergé — inutile à cette échelle).
Serveur headscale (srv18)
- Paquet officiel
.debtéléchargé depuis les releases
GitHub (pas de dépôt APT pour headscale).
- Config :
/etc/headscale/config.yamlserver_url: https://headscale.pcstreet.orglisten_addr: 127.0.0.1:8080(derrière Apache en reverse
proxy, pas d'exposition directe)
metrics_listen_addr: 127.0.0.1:9099(9090 et 9091 déjà
pris par systemd/prometheus sur srv18)
- base de données SQLite (
/var/lib/headscale/db.sqlite) - utilisateur headscale créé :
pcstreet(ID 1)
- base de données SQLite (
- Service :
systemctl status headscale
Exposition publique et certificat
- Domaine :
headscale.pcstreet.org, enregistrement A
vers l'IPv4 publique de la box (82.67.120.130).
- Redirection de port sur la Freebox :
80et443
(TCP) → 192.168.1.18 (srv18).
- Certificat Let's Encrypt obtenu via
certbot certonly --standalone(même méthode que les autres certs du serveur :authenticator = standalone), avec arrêt/redémarrage d'Apache en pre-hook/post-hook. Renouvellement automatique programmé par certbot (expiration initiale : 2026-12-13). Le port 80 doit rester ouvert en permanence pour que le renouvellement automatique fonctionne (voir Pièges rencontrés).
- Reverse proxy Apache :
/etc/apache2/sites-available/headscale.pcstreet.org.conf
Piège rencontré : upgrade HTTP du protocole Noise/TS2021
headscale utilise le protocole Noise (TS2021) sur l'endpoint
/ts2021, qui négocie une upgrade de connexion HTTP avec
Upgrade: tailscale-control-protocol (pas
websocket). Deux échecs avant la bonne solution :
mod_proxy_wstunnel(ws://) : n'accepte que
l'upgradewebsocketstandard, retombe en connexion normale sans l'en-tête → headscale répond500("no upgrade header in TS2021 request").
- Solution retenue : paramètre
upgrade=anyde
mod_proxy_http(Apache ≥ 2.4.47), qui relaie n'importe quelUpgradetel quel :
ProxyPass / http://127.0.0.1:8080/ upgrade=any ProxyPassReverse / http://127.0.0.1:8080/
C'est la méthode documentée officiellement par headscale pour Apache.
Script client : .pcmakeInstallHeadscale
Emplacement : /root/PCStreet.scripts/.pcmakeInstallHeadscale
Installe le client tailscale (dépôt APT officiel,
signé, adapté au VERSION_CODENAME détecté) sur le serveur
où il est exécuté, et le rattache au réseau headscale de srv18.
N'installe pas headscale (voir Fonctionnement).
Syntaxe
.pcmakeInstallHeadscale <clé_préauth> [nom_noeud] .pcmakeInstallHeadscale --uninstall .pcmakeInstallHeadscale --purge
Argument positionnel
<clé_préauth>- Clé de préauthentification à usage unique, générée sur srv18
(pas sur la machine cible). Voir ci-dessous.
- Exemple :
tskey-auth-xxxxxxxx
[nom_noeud]- Nom sous lequel le nœud apparaît dans le tailnet (
headscale
nodes list). Par défaut :hostnamede la machine.
- Exemple :
.pcmakeInstallHeadscale tskey-auth-xxxx srv09
Options
--uninstall- Arrête
tailscaled, désinstalle le paquet
tailscale. Conserve/var/lib/tailscale(état/clé du nœud), le dépôt APT et la clé GPG.
- Exemple :
.pcmakeInstallHeadscale --uninstall
--purge- Comme
--uninstall, puis supprime aussi
/var/lib/tailscale, le dépôt APT et la clé GPG. Demande confirmation interactive ([y/N]) — ne fonctionne donc pas en SSH non-interactif sans redirection de stdin.
- Exemple :
.pcmakeInstallHeadscale --purge
Générer une clé de préauth
Sur srv18 uniquement, une clé par serveur à rattacher (v0.29.3 attend l'ID utilisateur numérique, pas le nom) :
ssh root@srv18.pcstreet.org headscale users list ssh root@srv18.pcstreet.org headscale preauthkeys create --user 1 --expiration 1h
Bug corrigé (2026-09-15)
La version initiale du script vérifiait la disponibilité du dépôt
Tailscale via curl avant d'installer les
prérequis (curl lui-même) — échec sur tout serveur sans
curl préinstallé (ex. srv243), avec un message d'erreur
trompeur ("Pas de dépôt Tailscale officiel"). Ordre corrigé :
prérequis installés d'abord, vérification du dépôt ensuite.
État du réseau (2026-09-15)
Nœuds rattachés
| ID | Nom | IP tailnet | Machine / rôle |
|---|---|---|---|
| 1 | hal | 100.64.254.1 | HAL (poste principal, LAN) |
| 2 | xps13 | 100.64.254.2 | Laptop Dell XPS13 (LAN) |
| 3 | tablette | 100.64.254.3 | Tablette Surface (nomade) |
| 4 | srv18 | 100.64.254.4 | srv18, héberge aussi headscale lui-même |
| 5 | nbk132x | 100.64.254.5 | Laptop (LAN) |
| 8 | debian-dvt | 100.64.254.8 | VM/conteneur de dev (LAN) — voir note DNS ci-dessous |
| 9 | srv243 | 100.64.254.9 | srv243 = 192.168.1.243 (même machine, hostname "5050") |
| 10 | redmi-note-12-pro-5g | 100.64.254.10 | MI13) |
| 11 | nbk-mj | 100.64.254.11 | Marie José) |
| 12 | srv15 | 100.64.254.12 | système de copies OutBackup) |
| 13 | uk2 | 100.64.254.13 | remplaçant de OVH1) |
| 14 | geekom | 100.64.254.14 | petit dernier) |
Note debian-dvt : rattaché avec succès, mais MagicDNS n'a pas pu
modifier /etc/resolv.conf (permission refusée —
probablement un fichier immuable ou un montage en lecture seule,
typique d'un environnement de dev/conteneur). La connectivité tailnet
fonctionne normalement ; seule la résolution DNS automatique par nom
est indisponible sur cette machine précise.
Nœuds explicitement exclus (décision de sécurité)
| Machine | Raison |
|---|---|
| ovh1.pcstreet.org (mail.apsi.net) | Serveur exposé publiquement sur internet. Rejoint puis retiré à la demande explicite : en cas de compromission d'un serveur public, l'appartenance au tailnet donnerait un accès potentiel à tout le LAN (aucune ACL headscale n'est en place, voir ci-dessous). |
| ovh2.pcstreet.org (backup.apsi.net) | Même raison. |
Client tailscale désinstallé (--uninstall) et
nœuds supprimés côté headscale (headscale nodes delete)
sur ces deux machines.
⚠️ Point ouvert (non traité) : headscale n'a actuellement
aucune politique ACL configurée (policy.mode: file,
path: "") — tout nœud du tailnet peut par défaut joindre
n'importe quel autre nœud. Le retrait d'ovh1/ovh2 règle le cas
immédiat, mais tout futur nœud nomade ou exposé aura le même accès
complet tant qu'aucun fichier de policy ACL n'est écrit.
Serveurs de la flotte non rattachés (injoignables au moment du scan)
srv08, srv09, srv14, srv15, srv16, srv17, srv20, srv222, srv223, nbk11, nbk122, nbk250, 192.168.1.110, 192.168.1.221, 192.168.1.200.
À relancer avec .pcmakeInstallHeadscale quand ces
machines seront allumées et joignables en SSH.
Alias SSH via le tailnet
Sur HAL, xps13, tablette et srv18, un alias <nom>-headscale
a été ajouté pour chaque autre nœud (pas soi-même), utilisable
depuis n'importe laquelle des 4 machines :
| Alias | Cible |
|---|---|
| hal-headscale | 100.64.254.1 |
| xps13-headscale | 100.64.254.2 |
| tablette-headscale | 100.64.254.3 |
| srv18-headscale | 100.64.254.4 |
NB: les DNS srv18.headscale.pcstreet.org, xxx.headscale.pcstreet.org ont été créés
Usage : ssh srv18-headscale (ou tout autre alias) depuis
une des 4 machines équipées.
Piège rencontré : PCStreet-common.cnf casse l'authentification
Les premiers alias ont été ajoutés dans
/etc/ssh/ssh_config.d/ (config système, comme les autres
fichiers <nom>.conf existants) avec
IdentitiesOnly yes + IdentityFile
~/.ssh/id_ed25519. Ça ne fonctionnait pas : connexion
refusée systématiquement, avec bannissement automatique par
fail2ban (jails sshd et recidive) côté
serveur cible.
Cause racine :
/etc/ssh/ssh_config.d/PCStreet-common.cnfajoute
4 clés hôte (ssh_host_ed25519_key,ssh_host_rsa_key, etc.) comme identités pour tous les hôtes — mécanisme volontaire préexistant (trust inter-serveurs basé sur les clés hôte).
- Le fichier principal
/etc/ssh/ssh_configinclut ce
fichier explicitement avant le glob générique (Include .../PCStreet-common.cnfpuisInclude .../*.conf) — renommer notre fichier (00-headscale.conf) pour le faire lire en premier ne change donc rien, l'ordre est câblé en dur.
IdentityFileest cumulatif entre tous les blocs
Host qui matchent (pas de "premier gagne"), donc les 4
clés hôte sont toujours essayées avant la nôtre.
MaxAuthTries 3danssshd_config(srv18,
et probablement les autres serveurs durcis de la flotte) : 4
mauvaises clés suffisent à épuiser la limite avant même d'essayer la
bonne → fail2ban bannit l'IP source après l'échec.
Solution retenue : déplacer les alias dans
~/.ssh/config (config utilisateur, propre à root sur
chaque machine) plutôt que /etc/ssh/ssh_config.d/. Le
commentaire en tête de /etc/ssh/ssh_config le confirme :
l'ordre de priorité est "1. options ligne de commande ; 2. fichier
utilisateur ; 3. fichier système" — le fichier utilisateur est donc
lu (et ses IdentityFile accumulés) avant tout le
système, y compris PCStreet-common.cnf. Notre clé est
alors essayée en premier, l'authentification réussit dès la première
tentative, sans jamais approcher MaxAuthTries.
Aucune modification n'a été faite aux fichiers système partagés
(PCStreet-common.cnf, sshd_config) — la
correction est entièrement locale à chaque ~/.ssh/config.
Débannissement fail2ban (si ça se reproduit)
ssh root@srv18.pcstreet.org fail2ban-client set sshd unbanip <IP_tailnet> ssh root@srv18.pcstreet.org fail2ban-client set recidive unbanip <IP_tailnet>
Le jail recidive bannit pour une durée bien plus longue
que sshd après plusieurs bannissements répétés — penser à
débannir les deux.
Commandes utiles (côté srv18)
- Lister les nœuds
headscale nodes list
- Supprimer un nœud
headscale nodes delete -i <ID>
- Lister les utilisateurs headscale
headscale users list
- Créer une clé de préauth (1h, usage unique)
headscale preauthkeys create --user 1 --expiration 1h
- État du service headscale
systemctl status headscale
- Logs headscale (utile pour diagnostiquer un échec de rattachement)
journalctl -u headscale -f