Headscale als eigenen Tailscale-Control-Server einrichten

Was Headscale ist

Headscale ist eine selbst gehostete Implementierung des Tailscale-Control-Servers. Dadurch läuft der Server, der Ihr privates Netzwerk koordiniert, auf einem VPS, den Sie selbst besitzen. Das Projekt wird von der Community entwickelt und nicht von Tailscale Inc. betrieben. Auf jedem Gerät läuft weiterhin der offizielle tailscale-Client. Mit dem Flag --login-server wird er auf Ihren Server ausgerichtet.

Der Control-Server weiß, welche Geräte zum Netzwerk gehören. Er weist jedem Node eine Adresse aus 100.64.0.0/10 zu, verteilt öffentliche Schlüssel und teilt den Nodes mit, wo sie einander erreichen können. Die Tunnel verwenden weiterhin WireGuard und werden direkt zwischen den Nodes aufgebaut. Der Datenverkehr zwischen zwei Ihrer Geräte läuft nicht über den Headscale-Server. Das ist nur der Fall, wenn kein direkter Pfad aufgebaut werden kann und die Nodes auf ein Relay ausweichen. Wenn Sie diese Koordinationsfunktion selbst betreiben, ändert sich, wer sie kontrolliert, nicht aber, welche Aufgaben sie erfüllen kann. Daher sollten Sie verstehen, was ein Control-Server in diesem Modell erreichen kann und was nicht, bevor Sie den Wechsel allein als Sicherheitsgewinn betrachten.

Headscale stellt pro Instanz ein Tailnet (ein Tailscale-Netzwerk) bereit. Das Projekt beschreibt dieses Modell als geeignet für die private Nutzung oder eine kleine Organisation. Bei drei oder vier Geräten erfordert ein einfaches WireGuard-VPN auf einem eigenen VPS weniger Software und verursacht weniger potenzielle Fehler. Headscale lohnt sich, wenn Sie nicht mehr für jeden neuen Laptop einen [Peer]-Block von Hand schreiben möchten. Die Kosten sind häufig der Grund, aus dem sich Nutzer zunächst mit diesem Thema beschäftigen. Lesen Sie daher was der kostenlose Hosted-Tarif tatsächlich abdeckt, bevor Sie einen Server betreiben. Eine kleine Anzahl privater Geräte passt normalerweise in diesen Tarif. Wenn Sie diese Grenze bereits überschreiten, vergleichen Sie die Summe mit den Kosten der kostenpflichtigen Tarife pro Benutzer und getaggter Ressource. Für Benutzergeräte gibt es keine Mengenbegrenzung. Für getaggte Ressourcen gelten separate Kontingente und Gebühren. Wenn Sie eine selbst gehostete Control Plane wünschen, aber lieber einen eigenen Client und eine Weboberfläche zur Verwaltung von Peers hätten als einen direkten Ersatz für Tailscale, ist NetBird auf einem einzelnen VPS eine prüfenswerte Alternative. Beide übertragen Ihren Datenverkehr über WireGuard. Die Entscheidung hängt daher davon ab, wie Sie Zugriffsregeln formulieren und wie Relays funktionieren. Vor der Installation eines der beiden Produkte sollten Sie NetBird und Tailscale anhand dieser Punkte vergleichen. Einen umfassenderen Vergleich der beiden Modelle finden Sie unter den Unterschieden zwischen WireGuard und Tailscale.

Was Sie vor der Installation benötigen

• Einen VPS mit Ubuntu 24.04, einer öffentlichen IPv4-Adresse und sudo-Zugriff. Wenn der Server neu ist, arbeiten Sie zuerst die ersten zehn Minuten auf einem neuen VPS durch.
• Einen DNS-A-Record, der auf diese Adresse zeigt. In dieser Anleitung wird headscale.example.com verwendet.
• Eine zweite Domain oder Subdomain für MagicDNS. In dieser Anleitung wird tailnet.example.net verwendet. Sie darf nicht mit der Domain aus server_url identisch sein.
• Einen Client, der dem Netzwerk beitreten soll und unter Linux, macOS, Windows, Android oder iOS läuft. Headscale 0.29.6 erfordert die Tailscale-Clientversion 1.80.0 oder neuer.

headscale aus dem offiziellen .deb installieren

Das Projekt veröffentlicht .deb-Pakete auf seiner GitHub-Releases-Seite. Am 27. Oktober 2026 ist die neueste stabile Version 0.29.6, veröffentlicht am 24. Oktober 2026. Prüfen Sie zuerst Ihre Architektur, da der Dateiname sie enthält.

sudo apt update
sudo apt install -y wget
dpkg --print-architecture

Das gibt amd64 auf einem gewöhnlichen x86-VPS und arm64 auf einem Plan im Stil von Ampere oder Graviton aus. Setzen Sie die Antwort in die folgende Variable.

HEADSCALE_VERSION="0.29.6"
HEADSCALE_ARCH="amd64"
wget --output-document=headscale.deb \\
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
sudo apt install -y ./headscale.deb
headscale version

Das ./ vor dem Dateinamen ist erforderlich. Ohne dieses sucht apt in Ihren Paketquellen nach einem Paket namens headscale.deb und schlägt fehl.

Das Paket legt einen headscale-Systembenutzer an, schreibt eine Standard-/etc/headscale/config.yaml, installiert eine systemd-Unit und startet anschließend den Dienst. Daher läuft headscale bereits, wenn apt zurückkehrt, und sudo systemctl is-active headscale gibt active aus. Bei einer frischen Installation aktiviert das Paket die Unit jedoch nicht. Nach einem Reboot wird der Dienst daher erst wieder gestartet, wenn Sie ihn aktivieren. Das erledigt der folgende Neustart-Schritt. Der Dienst läuft außerdem mit der ausgelieferten Konfiguration. Diese setzt server_url auf http://127.0.0.1:8080. Unter dieser Adresse kann kein Client von Ihnen den Server erreichen. Es ist noch nichts erreichbar, da auch die ausgelieferte listen_addr nur auf loopback lauscht. Fügen Sie jedoch keinen Client hinzu, bevor Sie server_url gesetzt und den Dienst neu gestartet haben. Das erledigen die nächsten beiden Schritte.

server_url konfigurieren, bevor ein Client beitritt

Bearbeiten Sie /etc/headscale/config.yaml mit sudo nano /etc/headscale/config.yaml oder wenden Sie dieselben drei Änderungen mit sed an. Bewahren Sie eine Kopie des Originals auf. Die Datei ist lang und ausführlich kommentiert und dient als beste Referenz für die übrigen Einstellungen.

sudo cp /etc/headscale/config.yaml /etc/headscale/config.yaml.orig
sudo sed -i 's|^server_url:.*|server_url: https://headscale.example.com|' /etc/headscale/config.yaml
sudo sed -i 's|^listen_addr:.*|listen_addr: 127.0.0.1:8080|' /etc/headscale/config.yaml
sudo sed -i 's|^  base_domain:.*|  base_domain: tailnet.example.net|' /etc/headscale/config.yaml
sudo grep -E '^(server_url|listen_addr):|^  base_domain:' /etc/headscale/config.yaml

server_url ist die öffentliche Adresse, die headscale beim Erstellen von Registrierungs-URLs verwendet. Clients verwenden die mit --login-server konfigurierte Control-Adresse. Verwenden Sie daher an beiden Stellen denselben öffentlichen Namen mit https://, niemals 127.0.0.1. Laut Dokumentation von headscale ist unverschlüsseltes HTTP oder HTTPS an einem anderen Port als 443 möglich. Für den Produktivbetrieb wird jedoch dringend HTTPS an Port 443 empfohlen. Diese Anleitung setzt das voraus.

listen_addr legt fest, an welcher Adresse der Prozess lauscht. Lassen Sie die Einstellung auf Loopback. Ein Reverse Proxy auf demselben Server übernimmt die TLS-Terminierung (Transport Layer Security) und leitet die Anfragen an den Prozess weiter. Nichts außerhalb des Servers muss daher Port 8080 erreichen können.

base_domain ist das MagicDNS-Suffix. Unter dieser Domain erhalten Ihre Nodes ihre Namen. Es muss sich um einen vollständig qualifizierten Domainnamen ohne abschließenden Punkt handeln. Außerdem muss es eine andere Domain als die in server_url sein, weil die beiden Namensräume sonst kollidieren würden.

Lassen Sie den Datenbankabschnitt unverändert. Standardmäßig wird SQLite unter /var/lib/headscale/db.sqlite verwendet. Das Verzeichnis wurde vom Paket erstellt und wird von ihm verwaltet. Für ein Tailnet dieser Größe ist SQLite ausreichend.

Headscale neu starten und den laufenden Dienst prüfen

sudo systemctl restart headscale
sudo systemctl enable headscale
sudo systemctl is-active headscale
sudo systemctl is-enabled headscale
curl -sS -o /dev/null -w '%{http_code}\\n' http://127.0.0.1:8080/health

is-active gibt active aus, is-enabled gibt enabled aus, und curl gibt 200 aus. Der Neustart lädt Ihre Änderungen. Headscale liest seine Konfiguration beim Start einmal ein. Der vom Paket gestartete Prozess verwendet daher weiterhin die ausgelieferte server_url, bis Sie den Dienst neu starten. sudo systemctl enable --now headscale übernimmt diese Aufgabe nicht: Der Dienst läuft bereits, daher ändert der Start mit --now nichts und der alte Wert bleibt aktiv. Das Starten beim Booten übernimmt enable. Dies geschieht nicht automatisch: Bei einer frischen Installation startet das Paket den Dienst, ohne ihn zu aktivieren. Führen Sie daher einmal sudo systemctl enable headscale aus, wie oben beschrieben.

Wenn is-active etwas anderes als active ausgibt oder curl nicht 200 ausgibt, lesen Sie das Journal mit sudo journalctl -u headscale -n 50 --no-pager. Ein Fehler in dieser Phase betrifft fast immer die Konfigurationsdatei, weil Headscale die gesamte Datei einliest, bevor es einen Socket öffnet. Eine falsche Einrückung oder eine ungültige erforderliche Einstellung beendet den Prozess daher, bevor irgendein Dienst lauscht. Korrigieren Sie die Datei und führen Sie anschließend sudo systemctl restart headscale aus. Jede spätere Änderung an der Konfiguration erfordert denselben Neustart. Clients verbinden sich danach automatisch neu. Wenn systemd-Units neu für Sie sind, erklärt eigene Dienste und Timer mit systemd ausführen die hier verwendeten Befehle.

Prüfen Sie die Statusdateien, solange Sie in der Shell sind:

stat -c '%U %n' /var/lib/headscale/db.sqlite /var/lib/headscale/noise_private.key

Beide Zeilen beginnen mit headscale, dem vom Paket angelegten Benutzer ohne privilegierte Rechte. noise_private.key ist die Serveridentität für seine Clients. Bewahren Sie diese Datei auf. Wenn Sie sie löschen, erzeugt Headscale eine neue Identität, und die Clients müssen den neuen kryptografischen Serverschlüssel abrufen, bevor sie sich erneut verbinden können. Bereits vorhandene Registrierungen bleiben in der Datenbank erhalten.

TLS vor headscale schalten

Clients sollten server_url über HTTPS erreichen. Caddy ist der kürzeste Weg, weil es das Zertifikat selbstständig anfordert und erneuert.

sudo apt install -y caddy

Ersetzen Sie /etc/caddy/Caddyfile durch den Block aus der headscale-Dokumentation:

headscale.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up True-Client-IP {remote_host}
        header_up X-Real-IP {remote_host}
    }
}

sudo caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile
sudo systemctl restart caddy
sudo systemctl is-active caddy

validate gibt adapted config to JSON aus, wenn die Datei syntaktisch korrekt ist. Eine Warnung, dass die Datei nicht formatiert ist, ist rein kosmetisch. Von Ihrem Laptop aus sollte curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health ebenfalls 200 ausgeben. Diese eine Prüfung bestätigt, dass DNS, Firewall, Zertifikat und Proxy zusammen funktionieren.

Hier liegt das Proxy-Detail, das viele einen Abend kostet. Die Tailscale-Steuerungsverbindung verwendet ein HTTP-Upgrade. Sie wird mit POST statt mit GET gestartet, und der Wert des Headers Upgrade lautet tailscale-control-protocol. Caddy leitet dies ohne zusätzliche Konfiguration weiter. nginx tut das nicht. Ein nginx-Frontend muss die Header Upgrade und Connection daher explizit weiterleiten. Die headscale-Dokumentation löst das mit einer Upgrade-Map:

map $http_upgrade $connection_upgrade {
    default keep-alive;
    ''      close;
}

server {
    listen 443 ssl;
    server_name headscale.example.com;
    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_pass http://127.0.0.1:8080;
    }
}

Lassen Sie diese Zeilen weg, funktionieren normale Anfragen weiterhin. Deshalb liefert /health den Status 200 und alles sieht korrekt aus, während die Steuerungsverbindung nie hergestellt wird: Neue Nodes können sich nicht registrieren, und vorhandene Nodes können keine erneute Verbindung herstellen und ihren Online-Status melden. Wenn Sie nginx verwenden, beschreibt Certbot unter Ubuntu 24.04 mit nginx den Teil zur Zertifikatsverwaltung.

Welche Ports in UFW geöffnet werden müssen

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Port 443 überträgt die Steuerverbindung jedes Clients zu headscale. Wenn Sie später das integrierte DERP-Relay aktivieren, benötigt es zusätzlich 3478/udp. Dieser Port wird weiter unten behandelt. Port 80 wird für die HTTP-Challenge von ACME (Automatic Certificate Management Environment) und für die Weiterleitung zu HTTPS verwendet. Caddy kann auch bei geschlossenem Port 80 ein Zertifikat beziehen, weil es die TLS-ALPN-Challenge auf Port 443 verwenden kann. Bei geöffnetem Port 80 stehen jedoch beide Challenges zur Verfügung, und reine http://-Anfragen werden weitergeleitet.

Port 8080 bleibt geschlossen. listen_addr ist 127.0.0.1:8080, daher erreicht der Proxy headscale über das Loopback-Interface. Dafür ist keine Firewall-Regel erforderlich. Wenn Sie Port 8080 in UFW öffnen, wird dadurch nichts nach außen freigegeben, weil dort von außerhalb nichts auf Verbindungen wartet. Es bringt daher keinen Vorteil. Beachten Sie, dass die meisten Provider zusätzlich zu UFW eine zweite Firewall im Control Panel betreiben. Diese ist von UFW getrennt. Ein Port kann daher auf dem Server geöffnet und am Netzwerkrand trotzdem geschlossen sein. UFW-Firewall-Grundlagen auf einem VPS erläutert die Syntax der Regeln ausführlicher.

Benutzer und einen Preauth-Schlüssel erstellen

sudo headscale users create alice
sudo headscale users list

Der Befehl headscale ist ein Client. Er kommuniziert über den Unix-Socket unter /var/run/headscale/headscale.sock mit dem laufenden Daemon. Dieser Socket hat den Modus 0770 und gehört zur Gruppe headscale. Daraus ergeben sich zwei Punkte. Der Befehl schlägt fehl, wenn der Dienst angehalten ist. Das ist ein weiterer Grund für die Reihenfolge in dieser Anleitung. Außerdem benötigen Sie sudo, sofern Sie Ihr eigenes Konto nicht der Gruppe headscale hinzufügen.

users list gibt neben jedem Namen eine ID aus. Sie benötigen diese Nummer, weil der Befehl zum Erstellen des Schlüssels eine numerische Benutzer-ID und keinen Namen erwartet.

sudo headscale preauthkeys create --user 1 --expiration 24h

Der Schlüssel wird nur einmal ausgegeben. Kopieren Sie ihn jetzt. Ein Preauth-Schlüssel kann standardmäßig nur einmal verwendet werden und ist eine Stunde lang gültig. Daher sollten Sie --expiration 24h setzen, solange Sie noch testen. Fügen Sie --reusable für einen Schlüssel hinzu, mit dem mehrere Rechner registriert werden können. Behandeln Sie diesen Schlüssel wie ein Passwort, weil jeder, der ihn besitzt, Ihrem Netzwerk beitreten kann.

Ersten Client mit --login-server verbinden

Auf dem Rechner, den Sie in das Netzwerk aufnehmen möchten:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --login-server https://headscale.example.com --auth-key 'hskey-auth-PASTE-YOUR-KEY-HERE'
tailscale status
tailscale ip -4

tailscale ip -4 gibt die von headscale zugewiesene Adresse aus, zum Beispiel 100.64.0.1. Auf dem Server zeigt sudo headscale nodes list den Node mit seiner ID, seinem Benutzer und seinem Online-Status an.

Verwenden Sie für --login-server die öffentliche HTTPS-Adresse aus server_url. Der Client entfernt abschließende Schrägstriche aus seiner Control-URL. Es gibt keinen exakten Zeichenkettenvergleich, der erfordert, dass Sie einen Schrägstrich weglassen.

Ein Rechner, der zuvor bei Tailscales gehostetem Dienst angemeldet war, behält diese Anmeldung bei. Führen Sie darauf zuerst sudo tailscale logout und anschließend tailscale up mit --login-server aus.

Wenn Sie --auth-key weglassen, gibt der Client stattdessen eine URL aus. Öffnen Sie diese URL. Die Seite zeigt den Bezeichner für diesen Registrierungsversuch an. Diesen genehmigen Sie auf dem Server:

sudo headscale auth register --user alice --auth-id PASTE-THE-ID-FROM-THE-PAGE

Dieses Formular eignet sich besser für Ihren eigenen Laptop. Preauth-Schlüssel sind für alles besser, was per Skript ausgeführt wird, weil niemand den Vorgang überwachen muss. Sobald der VPS selbst ein Node ist, kann er außerdem den Internetverkehr Ihrer anderen Rechner übertragen. Das ist die Einrichtung eines Exit-Nodes. Der Unterschied besteht darin, dass Sie die beworbene Route auf dem Server mit dem Befehl headscale genehmigen und nicht in einer gehosteten Administrationskonsole. Wenn Sie nicht den Internetzugang über diesen VPS benötigen, sondern Zugriff auf ein privates Netzwerk hinter dem VPS, deckt derselbe Genehmigungsschritt die Bekanntgabe dieses Subnetzes an den restlichen Tailnet ab. Eine einzelne Anwendung von einem Node aus zu veröffentlichen, statt ganze Netzwerke darüber zu routen, ist wiederum eine andere Aufgabe. serve und funnel sind die beiden dafür vorgesehenen Verfahren. Beide verwenden jedoch Tailscales eigene Zertifikats- und Ingress-Mechanismen. Betrachten Sie sie daher als Funktionen eines gehosteten Tailnets und nicht als etwas, das headscale bereitstellt.

DERP und Relays für den Datenverkehr bei fehlender Direktverbindung

DERP (designated encrypted relay for packets) ist der Fallback-Pfad. Wenn zwei Nodes keine direkte WireGuard-Verbindung herstellen können, normalerweise weil sich beide hinter einem strikten NAT (network address translation) befinden, senden sie die Pakete stattdessen über einen Relay. Der Relay besitzt keine Schlüssel und kann Ihren Datenverkehr daher nicht lesen. Er sieht jedoch, welche Nodes miteinander kommunizieren und wie viele Daten übertragen werden.

Machen Sie sich klar, was die Standardkonfiguration bewirkt. Headscale wird mit einem Verweis auf https://controlplane.tailscale.com/derpmap/default sowie auto_update_enabled: true und update_frequency: 3h ausgeliefert. Damit gehört Ihre Control Plane Ihnen, während die Relays von Tailscale betrieben werden. Für die meisten Benutzer ist das ein vertretbarer Kompromiss. Wenn das für Sie nicht infrage kommt, betreiben Sie eigene Relays.

Um einen eigenen Relay zu betreiben, setzen Sie enabled: true unter derp.server in config.yaml. Ersetzen Sie ipv4: 198.51.100.1 und ipv6: 2001:db8::1 aus der ausgelieferten Konfiguration durch die öffentlichen Adressen Ihres Relays, oder entfernen Sie beide Einstellungen, um DNS zu verwenden. Starten Sie anschließend headscale neu und öffnen Sie den STUN-Port (session traversal utilities for NAT) mit sudo ufw allow 3478/udp. Diese Adresseinstellungen überschreiben DNS. Wenn einer der Platzhalter stehen bleibt, senden Clients ihre Anfragen an eine nicht erreichbare Adresse. Die Konfigurationsdatei beschreibt die Anforderung eindeutig: server_url muss https verwenden, weil DERP TLS voraussetzt. Wenn Sie die Liste derp.urls leeren, werden die Relays von Tailscale aus der Map entfernt. Stellen Sie vorher sicher, dass ein eingebetteter oder eigener Relay funktioniert. Headscale verweigert den Start mit einer leeren Relay-Map. Eine Map mit ausschließlich einem nicht erreichbaren Relay führt dazu, dass Nodes ohne direkte Verbindung nicht kommunizieren können.

Auf einem Client gibt tailscale netcheck die Latenz zu jeder bekannten Relay-Region aus. tailscale status zeigt bei aktiven Peer-Verbindungen direct mit einer Adresse oder relay mit einem Regionscode an. Bei einem Peer, der auf relay feststeckt, sollten Sie den direkten Pfad prüfen, einschließlich NAT- und Firewall-Regeln. Ein Peer, der direct ist und trotzdem langsam bleibt, erfordert eine andere Analyse. Die übliche Ursache ist dort MTU und nicht der Tunnel selbst.

Warum wird ein Node als offline angezeigt?

Der Proxy verwirft das Upgrade. Das typische Anzeichen ist, dass /health den Statuscode 200 zurückgibt, während neue Registrierungen fehlschlagen oder vorhandene Nodes keine Verbindung mehr herstellen können. Die Steuerverbindung ist ein POST mit Upgrade: tailscale-control-protocol. Ein Proxy, der dieses Header-Feld nicht weiterleitet, blockiert sowohl die Registrierung als auch den Kanal, der den Status des Nodes meldet. Vergleichen Sie Ihre nginx-Konfiguration mit den oben aufgeführten Upgrade-Zeilen, oder wechseln Sie zu Caddy, um den Proxy als Ursache auszuschließen.

Die öffentliche Steueradresse wurde geändert. Nodes stellen weiterhin eine Verbindung zu der mit --login-server konfigurierten Adresse her. Eine Änderung von server_url aktualisiert diese Client-Einstellung nicht. Wenn die alte Adresse Ihren Server nicht mehr erreicht, führen Sie sudo tailscale up --login-server https://headscale.example.com --force-reauth auf jedem Node aus.

Der Client läuft nicht. Führen Sie auf dem Node sudo systemctl is-active tailscaled und sudo journalctl -u tailscaled -n 50 --no-pager aus. Ein Client, der Ihre Domain nicht auflösen oder erreichen kann, protokolliert seine erneuten Verbindungsversuche dort.

Der Schlüssel ist abgelaufen. Dies wird im nächsten Abschnitt behandelt.

Um die Serverseite während des Tests zu überwachen, führen Sie sudo journalctl -u headscale -f auf dem VPS aus und starten Sie tailscaled auf dem Client neu. Prüfen Sie auch das Client-Journal: Dass eine Anfrage headscale erreicht, führt bei der standardmäßigen Protokollierungsstufe nicht zwangsläufig zu einem Logeintrag. Ausbleibende Server-Logs allein belegen daher keinen Fehler bei DNS, Firewall oder Proxy.

Ablauf von Schlüsseln und der Node, der Wochen später nicht mehr funktioniert

Es gibt zwei verschiedene Ablaufzeiten. Wenn Sie sie verwechseln, kostet die Fehlersuche unnötig Zeit.

Preauth-Schlüssel laufen absichtlich schnell ab. Die Standardeinstellung beträgt eine Stunde und eine Verwendung. Wenn tailscale up den Schlüssel ablehnt, erstellen Sie auf dem Server einen neuen, statt etwas auf dem Client zu ändern.

Node-Schlüssel gelten langfristig. Der Abschnitt node von config.yaml setzt expiry: 0. 0 bedeutet, dass standardmäßig keine Ablaufzeit festgelegt ist. Eine explizite Ablaufzeit für den Client oder eine OIDC-Ablaufzeit kann dennoch gelten. Mit Tags versehene Nodes sind von der automatischen Ablaufzeit ausgenommen. Ein Administrator kann sie jedoch ausdrücklich ablaufen lassen. Setzen Sie expiry: 180d, wenn Sie für Registrierungen ohne Tags eine Standardlaufzeit von 180 Tagen festlegen möchten. Eine vom Client angeforderte Ablaufzeit hat jedoch Vorrang, und OIDC kann die Standardeinstellung überschreiben. Eine Änderung dieser Einstellung wirkt sich nicht rückwirkend auf bestehende Registrierungen aus. Bei einem Node mit Ablaufzeit ist vor Ablauf eine erneute Authentifizierung mit sudo tailscale up --login-server https://headscale.example.com --force-reauth erforderlich. Ein Headless-Server, bei dem niemand eine erneute Authentifizierung durchführt, verliert nach Ablauf seiner Registrierung die Netzwerkverbindung.

Führen Sie diesen Vorgang manuell aus, wenn jemand einen Laptop verliert. sudo headscale nodes list liefert die ID. Danach meldet sudo headscale nodes expire -i 3 diesen Node ab, und sudo headscale nodes delete -i 3 entfernt ihn vollständig aus dem Netzwerk.

Backups und Upgrades

/var/lib/headscale und /etc/headscale bilden zusammen den gesamten Serverzustand. Stoppen Sie den Dienst, bevor Sie die Dateien kopieren. SQLite kann noch Schreibvorgänge ausführen, und eine während des Betriebs kopierte Datenbank kann inkonsistent sein.

sudo systemctl stop headscale
sudo tar czf /root/headscale-state.tgz -C /var/lib headscale
sudo tar czf /root/headscale-config.tgz -C /etc headscale
sudo systemctl start headscale
sudo chmod 600 /root/headscale-*.tgz

Kopieren Sie beide Dateien vom Server auf ein anderes System. Sie enthalten die privaten Schlüssel und sämtliche Registrierungen. Behandeln Sie sie daher genauso sorgfältig wie den Server selbst. restic-Backups von einem VPS beschreibt, wie Sie dies regelmäßig und verschlüsselt durchführen.

Bei Upgrades wiederholen Sie die Installation: Laden Sie das neue .deb und sudo apt install ./headscale.deb herunter. Starten Sie den Dienst anschließend neu und führen Sie die Prüfungen is-active und /health erneut aus. Seit Version 0.29 ist der Upgrade-Pfad strikt. Das Überspringen einer Minor-Version wird blockiert. Auch ein Downgrade auf eine ältere Minor-Version ist nicht möglich. Aktualisieren Sie jeweils um eine Minor-Version. Erstellen Sie vor jedem Schritt ein Backup und lesen Sie zuerst die Release Notes der jeweiligen Version. In dieser Version wurde das Verhalten der ACL-Richtlinie geändert, und mehrere Konfigurationsschlüssel wurden verschoben. Version 0.29.6 enthält außerdem Sicherheitsupdates für die Zertifikatsprüfung und Abhängigkeiten. Bestehende Installationen von 0.29 sollten daher auf dieses Patch-Release aktualisiert werden.

FAQ

Läuft headscale direkt nach der Installation des .deb bereits?

Ja. Das Paket startet den Dienst unmittelbar nach der Installation mit der mitgelieferten /etc/headscale/config.yaml, die nur auf Loopback lauscht und server_url auf http://127.0.0.1:8080 setzt. Bei einer frischen Installation aktiviert es den Dienst nicht, daher startet er beim Booten erst, wenn Sie sudo systemctl enable headscale ausführen. Die mitgelieferte Adresse ist für Clients unbrauchbar. Bearbeiten Sie daher server_url, listen_addr und base_domain, führen Sie anschließend sudo systemctl restart headscale aus und bestätigen Sie das Ergebnis mit sudo systemctl is-active headscale. Der Wert muss restart sein: headscale liest die Datei nur beim Start ein. enable --now für einen bereits laufenden Dienst aktiviert ihn zwar für den Bootvorgang, startet ihn aber nicht neu, sodass die alten Werte weiterhin aktiv sind. Wenn der Dienst nach dem Neustart fehlschlägt, nennt sudo journalctl -u headscale -n 50 --no-pager das Problem. In diesem Stadium handelt es sich fast immer um einen YAML-Fehler, weil headscale die gesamte Datei parst, bevor es einen Port bindet.

Muss ich den normalen Tailscale-Client weiterhin auf meinen Rechnern installieren?

Ja. Headscale ersetzt nur den Control Server. Jeder Node führt den offiziellen Client von Tailscale aus, und Sie verweisen ihn mit sudo tailscale up --login-server https://headscale.example.com auf Ihren Server. Dieses Flag ist im Standard-Client vorhanden. Sie müssen daher nichts patchen oder neu kompilieren.

Läuft mein Netzwerkverkehr über den headscale-Server?

Normalerweise nicht. Headscale koordiniert das Netzwerk und verteilt Schlüssel sowie Adressen. Der Datenpfad verläuft dagegen direkt über WireGuard zwischen Ihren Nodes. Der Traffic nimmt nur dann einen Umweg, wenn zwei Nodes einander nicht direkt erreichen können und auf ein DERP-Relay ausweichen. Mit der mitgelieferten Konfiguration sind das die öffentlichen Relays von Tailscale. Führen Sie auf einem Node tailscale status aus, um zu prüfen, ob ein bestimmter Peer direct oder über ein relay erreichbar ist.

Warum bleibt mein Node offline, nachdem er registriert wurde?

Bei einem Node, der in headscale nodes list erscheint, aber nie online geht, muss die Control-Verbindung einschließlich des Reverse Proxys geprüft werden. Diese Verbindung ist ein HTTP-Upgrade, das als POST mit dem Header Upgrade: tailscale-control-protocol gesendet wird. nginx verwirft es, wenn Sie die Header Upgrade und Connection nicht ausdrücklich mit proxy_set_header weiterleiten. Die obige Konfiguration erledigt das über ihren map $http_upgrade $connection_upgrade-Block. Wenn diese Header verworfen werden, können sich auch neue Nodes nicht registrieren. Caddy leitet die Verbindung ohne zusätzliche Konfiguration weiter. Damit lässt sich schnell prüfen, ob der Proxy die Ursache ist.

Benötige ich für headscale einen Domainnamen und TLS?

Für dieses Setup: ja. Verwenden Sie einen Domainnamen und HTTPS. Zertifikate können auch nackte IP-Adressen abdecken. Die Konfigurationsdatei legt jedoch fest, dass DERP TLS erfordert. Ein Domainname in Verbindung mit Caddy ist in etwa fünf Minuten eingerichtet und stellt einen HTTPS-Endpunkt bereit, der sich selbst erneuert. Reines HTTP ist möglich. Die Dokumentation von headscale empfiehlt für den Produktivbetrieb jedoch ausdrücklich HTTPS auf Port 443 und weist darauf hin, dass der Tailscale-Client in bestimmten Situationen HTTPS auf Port 443 voraussetzt.