The source post captures the core pieces needed to make a Tailscale Docker client on ZimaOS register with a self-hosted Headscale control plane: persistent state, a one-time/pre-auth key, the custom Headscale URL, TUN access, and the required container capabilities.
Current Tailscale and Headscale documentation now provide a clearer upstream contract. Tailscale officially supports a custom control server URL, and Headscale documents both interactive registration and pre-auth-key registration. Use those upstream methods to validate the current command/URL rather than relying only on a 2025 screenshot.
Headscale Replaces the Tailscale Coordination Control Plane
Headscale is a self-hosted implementation of the Tailscale control server protocol. Tailscale clients still create encrypted peer-to-peer tunnels, but registration and coordination are handled by the user's Headscale instance instead of the default Tailscale control plane.
Persist the Tailscale State Directory
The source created /DATA/AppData/tailscale/state and mapped it to /var/lib/tailscale. This is important because the node identity/state should survive container recreation and host reboot.
The source also recommended restrictive permissions on the host state directory. That is sensible because the state is part of the node's identity and should not be world-readable.
Use the Headscale URL as the Custom Control Server
Current Tailscale documentation supports custom control servers through:
tailscale login --login-server=<URL>Die eigene Dokumentation von Headscale verwendet dasselbe Modell mit tailscale up --login-server <YOUR_HEADSCALE_URL>.
Siehe die aktuelle Anleitung von Tailscale zu benutzerdefinierten Control-Servern.
Einen Pre-Auth-Schlüssel für die nicht-interaktive Registrierung verwenden
Die Quelle fügte vorübergehend hinzu TS_AUTHKEY, registrierte den Knoten und entfernte die Variable anschließend. Headscale dokumentiert derzeit die Erstellung eines Pre-Auth-Schlüssels und dessen Verwendung mit --authkey für die nicht-interaktive Registrierung.
Verwende die aktuellen Registrierungsmethoden von Headscale.
Lasse keinen wiederverwendbaren Authentifizierungsschlüssel in der App-Definition
Wenn der Schlüssel wiederverwendbar ist oder eine lange Gültigkeitsdauer hat, führt sein Verbleib in der ZimaOS-App-Umgebung zu einer unnötigen Gefährdung. Entferne das Registrierungsgeheimnis, sobald die Identität des Knotens erfolgreich gespeichert wurde und es nicht mehr benötigt wird.
Wenn ein Schlüssel in einem öffentlichen Forum oder Screenshot veröffentlicht wurde, widerrufe ihn und erstelle einen neuen.
Kernel-TUN und Capabilities beeinflussen den Netzwerkmodus
Die Quelle bindet /dev/net/tun und gewährt NET_ADMIN/NET_RAW, also im Gegensatz zu reinem Userspace-Netzwerk im Stil von Kernel-Netzwerken.
Aktuelle Tailscale-Container können auch im Userspace-Modus betrieben werden. Wähle den Modus daher bewusst danach, ob du Subnetz-Routing, Exit-Node-Funktionen oder vollständige Kernel-Netzwerkfunktionen benötigst.
Host-Netzwerk ist leistungsfähig
Die Quelle verwendet das Docker-Host-Netzwerk. Dadurch entfällt die normale Portisolierung des Containers, und Tailscale arbeitet direkt im Netzwerk-Namensraum des Hosts.
Wechsle nicht ohne Verständnis der Auswirkungen vom Host- zum Bridge-Netzwerk oder umgekehrt, da die aktuelle Tailscale-App möglicherweise Routen, Listener und angekündigte Dienste entsprechend speichert.
Die Headscale-URL sollte zuverlässig erreichbar und ordnungsgemäß abgesichert sein
Ein selbst gehosteter Steuerungsserver wird zur kritischen Infrastruktur. Verwende stabiles DNS, eine gültige TLS-Konfiguration sowie Sicherungskopien der Headscale-Datenbank und -Konfiguration. Wenn der Steuerungsserver ausfällt, können bestehende Peers möglicherweise vorübergehend weiter kommunizieren, aber neue Registrierungen und Änderungen an der Koordination sind nicht mehr möglich.
Die Quelle ist eine funktionierende Konfiguration, kein Supportvertrag mit IceWhale
Der Beitrag enthält keine Bestätigung durch IceWhale-Mitarbeiter. Es handelt sich um eine Community-Konfiguration, die gut zu den Konzepten von Tailscale und Headscale passt, aber weiterhin mit dem aktuellen Tailscale-Paket von ZimaOS getestet werden sollte.
FAQ zu Headscale auf ZimaOS
Können Tailscale-Clients einen benutzerdefinierten Headscale-Steuerungsserver verwenden?
Ja. Die aktuelle Tailscale-Dokumentation unterstützt offiziell benutzerdefinierte URLs für den Steuerungsserver.
Sollte TS_AUTHKEY dauerhaft in der App verbleiben?
Nein. Die Quelle entfernte sie nach der Registrierung, und langlebige Registrierungsschlüssel sollten nicht unnötig offenliegen.
Warum sollte /var/lib/tailscale dauerhaft gespeichert werden?
Die Identität und der Status des Knotens bleiben bei der Neuerstellung und dem Neustart des Containers erhalten.
