Cosa vede davvero il server Headscale?

I metadati: quali dispositivi esistono, le loro chiavi pubbliche, i loro indirizzi e quando sono stati online l'ultima volta. Il traffico vero e proprio passa direttamente tra i dispositivi tramite WireGuard (o attraverso un relay se non riescono a raggiungersi) ed è cifrato end-to-end. Ospitarlo in proprio significa che quei metadati stanno sul tuo server invece che su quello di qualcun altro.

Servono client speciali?

No. Usi le normali app Tailscale su Linux, macOS, Windows, iOS e Android e le punti all'URL del tuo server. Su Linux basta un flag: --login-server.

Headscale è minuscolo: Nano-IP ($8/mese) regge senza problemi una famiglia o un piccolo team. Serve un IP dedicato perché i dispositivi devono raggiungere il server di controllo in HTTPS; un piano NAT non accetta la 443 in entrata.

E se due dispositivi non riescono a collegarsi direttamente?

Ripiegano su un relay (DERP). Di default Headscale usa i relay pubblici di Tailscale, che vedono solo pacchetti cifrati. Puoi invece attivare il relay integrato di Headscale; richiede la UDP 3478 aperta e usa la banda del tuo VPS per il traffico inoltrato.

VPS per Headscale: controllo Tailscale self-hosted

Q: Cosa manca rispetto al servizio Tailscale in hosting?

Non c'è un pannello web ufficiale: gestisci utenti e chiavi da riga di comando (esistono interfacce della community). Alcune funzioni più recenti del servizio in hosting arrivano su Headscale più tardi o mai. Per una rete personale o di un piccolo team il nucleo (mesh, ACL, MagicDNS, exit node) funziona bene.

Fai girare Headscale su un piccolo VPS e tieni sotto il tuo controllo il server di coordinamento della mesh VPN. Installazione, primo utente, dispositivi e limiti.

Una mesh VPN è uno di quegli strumenti che semplificano tutto senza farsi notare: portatile, server di casa, telefono e VPS si vedono tra loro su indirizzi privati, ovunque si trovino. Il problema delle mesh VPN in hosting è il server di coordinamento: un'azienda custodisce la mappa di ogni dispositivo che possiedi. Headscale è un sostituto open source di quel server di controllo. Fallo girare su un piccolo VPS, continua a usare le normali app client, e la mappa è tua.

Come si incastra tutto

Headscale (sul tuo VPS) assegna gli indirizzi, distribuisce le chiavi pubbliche e applica le tue ACL.
I client sono le app Tailscale standard, puntate al tuo server.
Il traffico va da dispositivo a dispositivo tramite WireGuard. Il server di controllo non lo trasporta mai.

Quest'ultimo punto spiega perché basta un piano minuscolo: il VPS risponde solo a piccole richieste di coordinamento.

Cosa ti serve

Nano-IP ($8/mese): 2 vCPU e 1 GB di RAM sono molto più di quanto usi Headscale.
Un IPv4 dedicato e un dominio, per esempio hs.example.com. I dispositivi parlano con il server di controllo in HTTPS, quindi il VPS deve accettare la 443 in entrata; i piani NAT non lo fanno (dettagli).

Installazione (Debian 12 / Ubuntu 24.04)

Scarica il .deb attuale dalla pagina delle release di Headscale su GitHub, sostituendo la versione con l'ultima:

HS_VER=0.26.1
wget -O headscale.deb \
  "https://github.com/juanfont/headscale/releases/download/v${HS_VER}/headscale_${HS_VER}_linux_amd64.deb"
apt install -y ./headscale.deb caddy

Modifica /etc/headscale/config.yaml; le due righe che contano:

server_url: https://hs.example.com
listen_addr: 127.0.0.1:8080

Metti Caddy davanti per l'HTTPS:

cat > /etc/caddy/Caddyfile <<'EOF'
hs.example.com {
    reverse_proxy 127.0.0.1:8080
}
EOF
systemctl enable --now headscale
systemctl reload caddy

Aggiungi un utente e un dispositivo

headscale users create alice
headscale users list            # note the user's ID
headscale preauthkeys create --user 1 --expiration 24h

Le release più vecchie vogliono il nome utente invece dell'ID in --user; headscale preauthkeys create --help ti dice quale si aspetta la tua.

Su un dispositivo Linux:

tailscale up --login-server https://hs.example.com --authkey YOUR_KEY

Su telefoni e desktop, l'app Tailscale permette di impostare nelle opzioni un server di controllo personalizzato. Esegui headscale nodes list sul VPS e il tuo dispositivo dovrebbe comparire.

Relay e attraversamento del NAT

La maggior parte dei dispositivi si collega direttamente. Quando due non ci riescono (reti mobili restrittive, doppio NAT), il traffico passa da un relay DERP. Di serie Headscale usa i relay pubblici di Tailscale, che vedono solo pacchetti cifrati. Se non vuoi niente di esterno nel percorso, attiva il relay integrato in config.yaml (derp.server.enabled: true) e apri la UDP 3478. Il traffico inoltrato a quel punto pesa sulla banda del tuo VPS.

Limiti onesti

Non c'è una dashboard web ufficiale: utenti, chiavi e rotte sono comandi da CLI (niente di grave dopo averlo fatto due volte). Le funzioni più recenti del servizio in hosting arrivano su Headscale più tardi, se arrivano. E il server di controllo ora è una tua responsabilità: se è giù, le connessioni esistenti continuano a funzionare, ma i nuovi dispositivi non possono entrare e le chiavi non si rinnovano. Fanne il backup: tutto lo stato è in /var/lib/headscale.

Per un home lab, una famiglia o un piccolo team che vuole togliere la mappa dei dispositivi dai server di terzi, è uno dei migliori usi di un VPS da $8.

Correlati

Ospitare in proprio una VPN WireGuard: WireGuard puro, se ti serve un solo tunnel
VPS per una VPN
VPS per l'accesso remoto a Home Assistant