Headscale

Clients registrieren sich bei der eigenen Headscale-Adresse. Der Dienst verwaltet die Geräteinformationen und stellt die für Verbindungen benötigten Angaben bereit. Die Steuerung ist dabei vom Nutzdatenweg zu unterscheiden. Direkter Datenverkehr zwischen zwei Geräten muss nicht durch den Headscale-Server laufen.

Headscale implementiert Teile des Tailscale-Steuerungsprotokolls, ist aber ein eigenständiges Projekt. Ein neuer Menüpunkt oder eine neue Funktion im Tailscale-Client ist deshalb kein Beleg, dass sie mit der eingesetzten Headscale-Version funktioniert. Die Projekt-Dokumentation und die Kompatibilitätsangaben der jeweiligen Veröffentlichung sind maßgeblich.

Für die Administration gibt es eine Kommandozeile und eine API. Die Dokumentation verweist außerdem auf Weboberflächen aus anderen Projekten. Solche Oberflächen bringen einen eigenen Wartungsstand und zusätzliche Zugriffsrechte mit. Sie sollten nicht ungeprüft als Bestandteil des Headscale-Kerns behandelt werden.

Geräte können über die dokumentierten Registrierungsverfahren aufgenommen werden. Für eine browsergestützte Benutzeranmeldung lässt sich OpenID Connect anbinden. Die Konfiguration kann den Zugang beispielsweise auf erlaubte Domains, Benutzer oder Gruppen begrenzen.

Eine am Identitätsanbieter zugelassene Gruppe ist nicht automatisch eine identische Gruppe in der Netzrichtlinie. Headscale dokumentiert Einschränkungen bei der Verwendung von OIDC-Gruppen in ACLs. Identitätsprüfung und Freigabe bestimmter Geräte oder Ports müssen deshalb getrennt getestet werden.

Vorab festlegen, wie persönliche Geräte, Server und kurzlebige Systeme registriert werden. Wiederverwendbare Registrierungsschlüssel sparsam vergeben und sicher aufbewahren. Zum Abnahmetest gehören ein abgelehnter Benutzer, ein verlorenes Gerät und der Entzug einer bislang erlaubten Verbindung.

Die geprüfte Dokumentation unterstützt ACLs und Grants in einer huJSON-Richtlinie. Sie empfiehlt Grants für neue Regeln. Device-Posture-Bedingungen und IP-Sets gehören dagegen zu den dokumentierten Einschränkungen. Eine bestehende Tailscale-Policy daher nicht ohne Prüfung übernehmen.

Besonders wichtig ist der Ausgangszustand: Ohne geladene Policy erlaubt Headscale Verkehr zwischen den Knoten. Auch eine Policy ohne ACL- oder Grants-Abschnitt ist kein pauschales Verbot. Eine explizit leere Grants-Liste blockiert hingegen Verbindungen. Diese Ausgangslage muss vor der Aufnahme produktiver Geräte bewusst gewählt werden.

Bei einer Datei als Policy-Quelle muss Headscale Änderungen neu laden. Das Ergebnis anschließend in den Logs und mit einem erlaubten sowie einem unerlaubten Zugriff kontrollieren. Den administrativen Rückweg vorher sichern, damit eine fehlerhafte Regel die Fehlerbehebung nicht ebenfalls sperrt.

Wenn keine direkte Verbindung zustande kommt, helfen DERP-Relays beim Transport verschlüsselter Pakete. Headscale enthält einen optionalen DERP-Server. Seine Aktivierung entfernt jedoch nicht automatisch die öffentlichen Tailscale-Relays aus der angebotenen Liste.

Wer nur eigene Relays verwenden will, muss die DERP-Konfiguration entsprechend anpassen. Ein einzelnes eigenes Relay kann dabei zum Ausfallpunkt werden. Erreichbarkeit aus Mobilfunk-, Hotel- und Unternehmensnetzen sowie die Last beim indirekten Betrieb gezielt testen.

Für den Gesamtbetrieb außerdem DNS, Identitätsanbieter und Softwarebezug erfassen. Eine selbst betriebene Steuerung kann weiterhin externe Dienste nutzen. Ob das erwünscht ist, lässt sich erst anhand der tatsächlichen Konfiguration beurteilen.

Subnet Router können vorhandene Geräte ohne eigenen Client anbinden. Exit Nodes stellen einen Internet-Ausgang bereit. In beiden Fällen sind die angebotenen Routen, ihre Genehmigung und die erlaubten Zugriffe verschiedene Dinge. Die Freigabe eines Netzes muss zur Routingtabelle und zur Firewall am Standort passen.

Bei mehreren Standorten überlappende Adressen früh erkennen. Auch IPv6, DNS-Suchdomänen und interne Resolver brauchen eine konsistente Planung. Für die Fehlersuche eine konkrete Verbindung verfolgen: aufgelöste Zieladresse, ausgewählte Route, Richtlinie, Relay oder Direktverbindung und schließlich der Zielport.

Die Veröffentlichung 0.29.3 nennt Tailscale 1.80.0 als mindestens unterstützte Clientversion. Das ist keine Empfehlung, auf dieser alten Untergrenze zu bleiben. Aktuelle Clients in einem Pilotbestand prüfen, bevor automatische Updates die gesamte Umgebung verändern.

Vor Headscale-Upgrades den vorgesehenen Upgrade-Pfad lesen und Datenbank, Konfiguration, Schlüssel und Policy sichern. Datenbankschemaänderungen können einen einfachen Rücktausch der Binärdatei verhindern. Ein Rückfallplan braucht daher einen zusammenpassenden gesicherten Stand und einen erprobten Wiederanlauf.

Das Projekt steht unter BSD-3-Clause. Die offene Lizenz ersetzt keinen Supportvertrag. Für einen geschäftskritischen Zugang müssen Zuständigkeit, erreichbare Unterstützung und Ersatzwege unabhängig davon festgelegt sein.

Geprüft am 20. September 2026. Versionsbezug: Headscale 0.29.3. Die Prüfung umfasst Dokumentation und Release-Angaben, keinen Interoperabilitätstest.