Il post originale illustra gli elementi fondamentali necessari per fare in modo che un client Docker di Tailscale su ZimaOS si registri presso un piano di controllo Headscale self-hosted: stato persistente, una chiave monouso o di pre-autenticazione, l'URL personalizzato di Headscale, accesso TUN e le funzionalità richieste dal container.
La documentazione attuale di Tailscale e Headscale fornisce ora un contratto upstream più chiaro. Tailscale supporta ufficialmente un URL di server di controllo personalizzato e Headscale documenta sia la registrazione interattiva sia quella tramite chiave di pre-autenticazione. Usa questi metodi upstream per verificare il comando e l'URL attuali invece di affidarti soltanto a uno screenshot del 2025.
Headscale sostituisce il piano di controllo del coordinamento di Tailscale
Headscale è un'implementazione self-hosted del protocollo del server di controllo di Tailscale. I client Tailscale continuano a creare tunnel peer-to-peer crittografati, ma la registrazione e il coordinamento sono gestiti dall'istanza Headscale dell'utente anziché dal piano di controllo Tailscale predefinito.
Rendere persistente la directory dello stato di Tailscale
Il testo originale ha creato /DATA/AppData/tailscale/state e l'ha associata a /var/lib/tailscale. Questo è importante perché l'identità e lo stato del nodo devono sopravvivere alla ricreazione del container e al riavvio dell'host.
Il testo originale raccomandava inoltre permessi restrittivi sulla directory dello stato nell'host. È una scelta sensata, perché lo stato fa parte dell'identità del nodo e non dovrebbe essere leggibile da tutti.
Usa l'URL di Headscale come server di controllo personalizzato
La documentazione attuale di Tailscale supporta i server di controllo personalizzati tramite:
tailscale login --login-server=<URL>La documentazione di Headscale utilizza lo stesso modello con tailscale up --login-server <YOUR_HEADSCALE_URL>.
Vedi le indicazioni attuali di Tailscale sui server di controllo personalizzati.
Usare una chiave di pre-autenticazione per la registrazione non interattiva
Il testo originale ha aggiunto temporaneamente TS_AUTHKEY, ha registrato il nodo e poi ha rimosso la variabile. Attualmente Headscale documenta la creazione di una chiave di pre-autenticazione e il suo utilizzo con --authkey per la registrazione non interattiva.
Usa gli attuali metodi di registrazione di Headscale.
Non lasciare una chiave di autenticazione riutilizzabile nella definizione dell'app
Se la chiave è riutilizzabile o ha una lunga durata, lasciarla nell'ambiente dell'app ZimaOS crea un'esposizione non necessaria. Dopo che l'identità del nodo è stata memorizzata correttamente, rimuovi il segreto di registrazione quando non è più necessario.
Se una chiave è stata incollata in un forum pubblico o mostrata in uno screenshot, revocala e creane una nuova.
TUN del kernel e le capability influenzano la modalità di rete
La fonte mappa /dev/net/tun e concede NET_ADMIN/NET_RAW, ovvero lo stile di rete tramite kernel anziché la pura rete userspace.
Gli attuali container Tailscale possono operare anche in modalità userspace, quindi scegli deliberatamente la modalità in base alla necessità di routing delle subnet, comportamento da exit node o rete completa tramite kernel.
La rete dell'host è potente
La fonte usa la rete dell'host Docker. Ciò rimuove il normale isolamento delle porte del container e fa operare Tailscale direttamente nello spazio dei nomi di rete dell'host.
Non passare dalla modalità host alla modalità bridge, o viceversa, senza comprendere come l'app Tailscale attuale memorizza le route, i listener e i servizi pubblicizzati.
L'URL di Headscale deve essere raggiungibile in modo affidabile e adeguatamente protetto
Un server di controllo autogestito diventa un'infrastruttura critica. Usa un DNS stabile, una configurazione TLS valida e backup del database e della configurazione di Headscale. Se il server di controllo scompare, i peer esistenti potrebbero continuare a comunicare temporaneamente, ma le nuove registrazioni e le modifiche al coordinamento non saranno disponibili.
La fonte è una configurazione funzionante, non un contratto di supporto IceWhale
Il post non contiene una conferma da parte dello staff di IceWhale. Si tratta di una configurazione della community che si allinea bene ai concetti upstream di Tailscale/Headscale, ma deve comunque essere testata con il pacchetto Tailscale attuale di ZimaOS.
Domande frequenti su Headscale su ZimaOS
I client Tailscale possono usare un server di controllo Headscale personalizzato?
Sì. La documentazione attuale di Tailscale supporta ufficialmente gli URL dei server di controllo personalizzati.
TS_AUTHKEY deve rimanere nell'app per sempre?
No. Il codice sorgente lo rimuove dopo la registrazione e i segreti di registrazione a lunga durata non devono rimanere esposti inutilmente.
Perché rendere persistente /var/lib/tailscale?
Mantiene l'identità e lo stato Tailscale del nodo durante la ricreazione e il riavvio del container.
