Info::NETWORK:HeadScale VPN

De wiki_pcwiki2
Aller à la navigationAller à la recherche

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
 Tailscale 100.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/24 garde 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 .deb téléchargé depuis les releases
 GitHub (pas de dépôt APT pour headscale).
  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)
  • 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 : 80 et 443
 (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 :

  1. mod_proxy_wstunnel (ws://) : n'accepte que
 l'upgrade websocket standard, retombe en connexion
 normale sans l'en-tête → headscale répond 500 ("no
 upgrade header in TS2021 request").
  1. Solution retenue : paramètre upgrade=any de
 mod_proxy_http (Apache ≥ 2.4.47), qui relaie n'importe
 quel Upgrade tel 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 : hostname de 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 :

  1. /etc/ssh/ssh_config.d/PCStreet-common.cnf ajoute
 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).
  1. Le fichier principal /etc/ssh/ssh_config inclut ce
 fichier explicitement avant le glob générique
 (Include .../PCStreet-common.cnf puis
 Include .../*.conf) — renommer notre fichier
 (00-headscale.conf) pour le faire lire en premier ne
 change donc rien, l'ordre est câblé en dur.
  1. IdentityFile est 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.
  1. MaxAuthTries 3 dans sshd_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