Headscale: Eigenen Tailscale-Steuerungsserver betreiben

Was headscale ist

Headscale ist eine selbst gehostete Implementierung des Tailscale-Steuerungsservers. Dadurch ist der Server, der Ihr privates Netzwerk koordiniert, ein VPS in Ihrem Besitz. Das Projekt wird von der Community entwickelt und nicht von Tailscale Inc. betrieben. Auf jedem Rechner läuft weiterhin der offizielle tailscale-Client. Sie geben mit einem einzigen Flag den Server vor: --login-server.

Der Steuerungsserver kennt die Mitglieder des Netzwerks. Er weist jedem Knoten eine Adresse aus 100.64.0.0/10 zu, verteilt öffentliche Schlüssel und teilt den Knoten mit, wie sie einander erreichen. Die Tunnel verwenden weiterhin WireGuard und werden direkt zwischen den Knoten aufgebaut. Der Datenverkehr zwischen zwei Ihrer Rechner läuft nicht über den headscale-Server, sofern kein direkter Pfad aufgebaut werden kann und die Knoten auf ein Relay ausweichen müssen. Wenn Sie diese Koordinationsfunktion selbst betreiben, ändert sich, wer sie ausübt, nicht aber, was sie leisten kann. Deshalb sollten Sie verstehen, was ein Steuerungsserver in diesem Modell erreichen kann und was nicht, bevor Sie die Umstellung allein als Sicherheitsgewinn betrachten.

Jede headscale-Instanz stellt ein Tailnet (ein Tailscale-Netzwerk) bereit. Das Projekt beschreibt dieses Modell als geeignet für den persönlichen Gebrauch oder eine kleine Organisation. Bei drei oder vier Rechnern ist ein einfaches WireGuard-VPN auf einem VPS in Ihrem Besitz mit weniger Software verbunden und bietet weniger Fehlerquellen. Headscale lohnt sich, wenn Sie nicht mehr für jeden neuen Laptop von Hand einen [Peer]-Block schreiben möchten. Die Kosten sind oft der Grund, aus dem sich Nutzer zunächst damit beschäftigen. Daher sollten Sie zuerst lesen, was der kostenlose Hosted-Tarif tatsächlich abdeckt, bevor Sie einen Server betreiben. Einige private Rechner passen normalerweise in diesen Tarif. Wenn Sie diese Grenze bereits überschreiten, vergleichen Sie die Kosten mit den Preisen der kostenpflichtigen Tarife, die pro Benutzer und nicht pro Gerät berechnet werden, denn ein Haushalt mit einem gemeinsamen Konto kann auch dann günstig bleiben, wenn die Anzahl der Geräte nicht mehr entscheidend ist. Wenn Sie eine selbst gehostete Steuerungsebene möchten, aber lieber einen eigenen Client und eine Weboberfläche zur Verwaltung von Peers hätten, statt Tailscale direkt zu ersetzen, ist NetBird auf einem einzelnen VPS eine Alternative, die Sie prüfen sollten. 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 in server_url identisch sein.
• Einen Client, der dem Netzwerk beitreten soll und unter Linux, macOS, Windows, Android oder iOS läuft.

Offizielles .deb-Paket von headscale installieren

Das Projekt veröffentlicht .deb-Pakete auf seiner GitHub-Releases-Seite. Im Juli 2026 ist 0.29.3 die aktuelle Version. Prüfen Sie zuerst Ihre Architektur, da sie im Dateinamen enthalten ist.

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

Auf einem gewöhnlichen x86-VPS gibt der Befehl amd64 aus. Bei einem Tarif mit Ampere- oder Graviton-Prozessor gibt er arm64 aus. Übernehmen Sie die Ausgabe in die Variable unten.

HEADSCALE_VERSION="0.29.3"
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 vorangestellte ./ vor dem Dateinamen ist erforderlich. Ohne diese Angabe sucht apt in Ihren Paketquellen nach einem Paket namens headscale.deb und schlägt fehl.

Das Paket legt den Systembenutzer headscale an, schreibt eine Standardkonfiguration nach /etc/headscale/config.yaml und installiert eine systemd-Unit. Es startet den Dienst nicht. Das ist die richtige Reihenfolge. Die mitgelieferte Konfiguration verweist server_url auf http://127.0.0.1:8080. Keine Ihrer Clients kann diese Adresse erreichen. Ein jetzt gestarteter Dienst wäre daher falsch konfiguriert, selbst wenn er starten würde. Wenn Sie an dieser Stelle sudo systemctl is-active headscale ausführen, gibt der Befehl inactive aus. Das ist erwartetes Verhalten und kein Fehler.

Konfigurieren Sie server_url, bevor Sie den Dienst starten

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 damit die 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 Adresse, die headscale in jede Clientregistrierung schreibt. Clients verbinden sich danach dauerhaft mit genau dieser Zeichenfolge. Daher muss hier der öffentliche Name mit vorangestelltem https:// stehen, niemals 127.0.0.1.

listen_addr ist die Adresse, an die der Prozess gebunden wird. Belassen Sie sie auf dem Loopback-Interface. Ein Reverse Proxy auf demselben Server übernimmt die TLS-Terminierung (Transport Layer Security) und leitet die Anfragen dorthin weiter. Kein System außerhalb des Servers muss daher Port 8080 erreichen können.

base_domain ist das MagicDNS-Suffix, also die Domain, unter der Ihre Nodes Namen erhalten. Es muss sich um einen vollständig qualifizierten Domainnamen ohne abschließenden Punkt handeln. Außerdem muss es sich von der Domain in server_url unterscheiden, da 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, in einem Verzeichnis, das vom Paket erstellt wurde und dessen Eigentümer es ist. Für ein Tailnet dieser Größe ist SQLite ausreichend.

Headscale starten und den laufenden Dienst überprüfen

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

is-active gibt active aus, und curl gibt 200 aus. enable --now erledigt beide Aufgaben: Der Befehl startet den Dienst und aktiviert ihn für den Start nach einem Reboot.

Wenn is-active failed ausgibt, lesen Sie das Journal mit sudo journalctl -u headscale -n 50 --no-pager. Ein Fehler in dieser Phase wird fast immer durch die Konfigurationsdatei verursacht, weil Headscale die gesamte Datei einliest, bevor es einen Socket öffnet. Eine falsche Einrückung oder ein unbekannter Schlüssel beendet den Prozess daher, bevor ein Prozess auf einem Port 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 selbstständig erneut. Wenn systemd-Units für Sie neu sind, erklärt Eigene Dienste und Timer mit systemd ausführen die hier verwendeten Befehle.

Prüfen Sie in der Shell auch die Zustandsdateien:

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 Identität des Servers gegenüber seinen Clients. Bewahren Sie diese Datei auf. Wenn Sie sie löschen, erzeugt Headscale eine neue Identität, und jeder Node muss sich erneut registrieren.

TLS vor headscale schalten

Clients müssen server_url über HTTPS erreichen. Caddy ist der kürzeste Weg, weil es das Zertifikat selbst 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 lediglich 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 ist ein HTTP-Upgrade. Sie wird mit POST statt mit GET gestartet, und der Wert des Headers Upgrade ist tailscale-control-protocol. Caddy leitet dies ohne zusätzliche Konfiguration weiter. nginx tut das nicht. Ein nginx-Frontend benötigt daher die Upgrade-Zuordnung:

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;
    }
}

Wenn Sie diese Zeilen weglassen, funktionieren normale Anfragen weiterhin. Deshalb gibt /health 200 zurück und alles sieht korrekt aus. Die langlebige Steuerungsverbindung wird jedoch nie hergestellt. Ihre Nodes registrieren sich und bleiben anschließend offline. Wenn Sie nginx verwenden, behandelt Certbot unter Ubuntu 24.04 mit nginx den Teil mit dem Zertifikat.

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 gesamte Kommunikation mit den Clients. Port 80 wird nur für die HTTP-Challenge von ACME (automatische Zertifikatsverwaltung) und die Weiterleitung auf HTTPS benötigt. Außerdem kann Caddy ohne diesen Port kein Zertifikat beziehen.

Port 8080 bleibt geschlossen. listen_addr ist 127.0.0.1:8080, daher erreicht der Proxy headscale über die Loopback-Schnittstelle, und es ist keine Firewall-Regel erforderlich. Wenn Sie Port 8080 im Internet öffnen, erhalten Clients einen unverschlüsselten Steuerkanal, ohne dass dies einen Vorteil bringt. Beachten Sie, dass die meisten Provider zusätzlich zu UFW eine zweite Firewall in ihrem Control Panel betreiben. Daher kann ein Port auf dem Server geöffnet und am Netzwerkübergang trotzdem geschlossen sein. Grundlagen der UFW-Firewall auf einem VPS erläutert die Syntax der Regeln ausführlicher.

Einen Benutzer und einen Preauth-Schlüssel anlegen

sudo headscale users create alice
sudo headscale users list

Der Befehl headscale ist ein Client. Er kommuniziert über den Unix-Socket /var/run/headscale/headscale.sock mit dem laufenden Daemon. Dieser Socket hat den Modus 0770 und gehört der 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 Zahl, weil der Schlüsselbefehl 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 nur einmal verwendet werden und ist eine Stunde lang gültig, sofern Sie nichts anderes angeben. Daher lohnt es sich, --expiration 24h bereits während des Tests zu setzen. Fügen Sie --reusable für einen Schlüssel hinzu, mit dem mehrere Rechner registriert werden. Behandeln Sie diesen Schlüssel wie ein Passwort, da jeder, der ihn besitzt, Ihrem Netzwerk beitreten kann.

Verbinden Sie den ersten Client mit --login-server

Auf dem Rechner, den Sie verbinden 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, etwa 100.64.0.1. Wechseln Sie anschließend zurück zum Server. sudo headscale nodes list zeigt den Node mit seiner ID, seinem Benutzer und seinem Online-Status.

Der Wert von --login-server muss exakt mit server_url übereinstimmen, einschließlich des Schemas und ohne abschließenden Schrägstrich. Die Werte werden als Zeichenketten verglichen. Bei einer Abweichung registriert sich der Client bei einer Adresse und wird anschließend angewiesen, mit einer anderen Adresse zu kommunizieren.

Ein Rechner, der zuvor beim gehosteten Tailscale-Dienst angemeldet war, behält diese Anmeldung. 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 Verfahren eignet sich besser für den 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 auch den Internetverkehr Ihrer anderen Rechner übertragen. Das ist die Konfiguration als Exit Node. Der einzige Unterschied besteht darin, dass Sie die beworbene Route auf dem Server mit dem Befehl headscale genehmigen und nicht in einer gehosteten Administrationskonsole. Wenn Sie statt eines Zugangs zum Internet den Zugriff auf ein privates Netzwerk hinter diesem VPS benötigen, gilt derselbe Genehmigungsschritt auch für die Bekanntgabe dieses Subnetzes an den restlichen Tailnet. Eine einzelne Anwendung von einem Node zu veröffentlichen, anstatt ganze Netzwerke darüber zu routen, ist wieder eine andere Aufgabe. Dafür gibt es serve und funnel, wobei beide auf Tailscales eigener Zertifikats- und Ingress-Mechanik aufbauen. Betrachten Sie sie daher als Funktionen für ein gehostetes Tailnet und nicht als etwas, das headscale bereitstellt.

DERP und welche Relays den Datenverkehr bei einem fehlenden direkten Pfad weiterleiten

DERP (designated encrypted relay for packets) ist der Fallback-Pfad. Wenn zwei Knoten keine direkte WireGuard-Verbindung herstellen können, meist weil beide hinter einem strikten NAT (network address translation) liegen, senden sie die Pakete stattdessen über ein Relay. Das Relay besitzt keine Schlüssel und kann Ihren Datenverkehr daher nicht lesen. Es erkennt jedoch, welche Knoten 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. Dadurch gehört die Steuerungsebene Ihnen, während die Relays von Tailscale betrieben werden. Für die meisten Nutzer ist das ein vertretbarer Kompromiss. Wenn das für Sie nicht infrage kommt, betreiben Sie eigene Relays.

Um ein eigenes Relay zu betreiben, setzen Sie enabled: true unter derp.server in config.yaml, starten Sie headscale neu und öffnen Sie den STUN-Port (session traversal utilities for NAT) mit sudo ufw allow 3478/udp. Die Konfigurationsdatei nennt die Voraussetzung eindeutig: server_url muss https verwenden, weil DERP TLS erfordert. Wenn Sie die Liste derp.urls leeren, werden die Relays von Tailscale aus der Zuordnung entfernt. Wenn dann kein funktionierendes eingebettetes Relay vorhanden ist, können sich Knotenpaare, die keine direkte Verbindung herstellen können, überhaupt nicht verbinden.

Von einem Client aus gibt tailscale netcheck die Latenz zu jeder bekannten Relay-Region aus. tailscale status kennzeichnet jeden Peer entweder als direct mit einer Adresse oder als relay mit einem Regionscode. Ein Peer, der auf relay festhängt, weist auf ein NAT-Problem hin, nicht auf ein headscale-Problem. Ein Peer, der direct ist und weiterhin eine hohe Latenz aufweist, erfordert eine andere Untersuchung. Die übliche Ursache ist dort die MTU und nicht der Tunnel selbst.

Warum wird ein Node als offline angezeigt?

Der Proxy verwirft das Upgrade. Das ist der häufigste Fall. Alles andere wirkt dabei normal: /health liefert 200, headscale nodes list zeigt den Node an, und der Node wird nie online angezeigt. Die Steuerungsverbindung ist ein POST mit Upgrade: tailscale-control-protocol. Ein Proxy, der diese Anfrage nicht weiterleitet, unterbricht den einzigen Kanal, der den Status des Nodes meldet. Vergleichen Sie Ihre nginx-Konfiguration mit dem obigen map-Block. Alternativ können Sie auf Caddy wechseln, um den Proxy als Ursache auszuschließen.

server_url wurde geändert, nachdem die Nodes registriert wurden. Nodes verbinden sich weiterhin mit dem Wert, den sie bei der Registrierung erhalten haben. Wenn Sie den Wert geändert haben, 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 Wiederholungsversuche dort.

Der Schlüssel ist abgelaufen. Das 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. Ein Node, der headscale erreicht, erzeugt sofort Logzeilen. Wenn keine Ausgabe erscheint, trifft die Anfrage nicht ein. Prüfen Sie daher zuerst DNS, die Firewall und den Proxy, bevor Sie headscale untersuchen.

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

Es gibt zwei voneinander getrennte Abläufe. Wenn Sie sie verwechseln, verlieren Sie Zeit.

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

Node-Schlüssel sind der langfristig gültige Teil. Der Abschnitt node von config.yaml setzt expiry: 0, und 0 bedeutet, dass standardmäßig kein Ablauf festgelegt ist: Ein registrierter Knoten bleibt gültig, bis Sie ihn ablaufen lassen. Getaggte Knoten laufen unabhängig davon nie ab. Setzen Sie expiry: 180d, wenn Registrierungen nach einer bestimmten Zeit ablaufen sollen, und machen Sie sich klar, was das bedeutet: Jeder nicht getaggte Knoten benötigt dann nach diesem Zeitplan sudo tailscale up --login-server https://headscale.example.com --force-reauth, und ein Headless-Server, bei dem sich niemand erneut authentifiziert, verliert dadurch selbstständig seine Netzwerkanbindung.

Führen Sie das manuell durch, wenn jemand einen Laptop verliert. sudo headscale nodes list liefert Ihnen die ID. Anschließend meldet sudo headscale nodes expire -i 3 diesen Knoten 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. 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. Sichern 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.

Upgrades folgen erneut der Installationsprozedur: 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 0.29 ist der Upgradepfad strikt. Das Überspringen einer Minor-Version ist nicht möglich. Auch ein Downgrade auf eine ältere Minor-Version wird blockiert. Aktualisieren Sie jeweils um eine Minor-Version, erstellen Sie vor jedem Schritt ein Backup und lesen Sie zuerst die Release Notes dieser Version. In derselben Release-Version wurde das Verhalten der ACL-Richtlinie geändert und mehrere Konfigurationsschlüssel wurden verschoben.

FAQ

Warum startet headscale direkt nach der Installation des .deb nicht?

Das Paket installiert die Unit, lässt den Dienst jedoch gestoppt. Außerdem ist /etc/headscale/config.yaml eine Vorlage und keine funktionsfähige Konfiguration. Bearbeiten Sie zuerst server_url, listen_addr und base_domain. Führen Sie anschließend sudo systemctl enable --now headscale aus und prüfen Sie das Ergebnis mit sudo systemctl is-active headscale. Wenn der Start weiterhin fehlschlägt, nennt sudo journalctl -u headscale -n 50 --no-pager die Ursache. In diesem Stadium handelt es sich fast immer um einen YAML-Fehler, weil headscale die gesamte Datei einliest, bevor es einen Port bindet.

Muss ich den normalen Tailscale-Client weiterhin auf meinen Geräten installieren?

Ja. headscale ersetzt nur den Control-Server. Auf jedem Node läuft der offizielle Client von Tailscale. Mit sudo tailscale up --login-server https://headscale.example.com weisen Sie ihn auf Ihren Server hin. Dieses Flag ist im Standard-Client vorhanden. Sie müssen daher nichts patchen oder neu bauen.

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

Normalerweise nicht. headscale koordiniert das Netzwerk und verteilt Schlüssel sowie Adressen. Der Datenpfad verläuft über WireGuard direkt zwischen Ihren Nodes. Der Datenverkehr 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 dies die öffentlichen Relays von Tailscale. Führen Sie auf einem Node tailscale status aus, um zu sehen, ob ein bestimmter Peer direct oder auf einem relay ist.

Warum bleibt mein Node offline, nachdem er sich registriert hat?

Ein Node, der in headscale nodes list erscheint, aber nie online geht, hat normalerweise seine Control-Verbindung am Reverse Proxy verloren. Dabei handelt es sich um ein HTTP-Upgrade, das als POST mit dem Header Upgrade: tailscale-control-protocol gesendet wird. nginx verwirft diese Verbindung, wenn Sie nicht den Block map $http_upgrade $connection_upgrade und die zugehörigen proxy_set_header-Zeilen ergänzen. 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?

In der Praxis: ja. Clients verbinden sich mit der Zeichenfolge, die Sie in server_url eintragen. Zertifikate werden für Namen und nicht für reine IP-Adressen ausgestellt. Außerdem weist die Konfigurationsdatei darauf hin, dass DERP TLS erfordert. Eine Domain zusammen mit Caddy ist in etwa fünf Minuten eingerichtet und stellt einen HTTPS-Endpunkt bereit, der sich selbst erneuert. Wenn Sie den Control-Server über unverschlüsseltes HTTP betreiben, wird die gesamte Kommunikation jedes Clients mit dem Server unverschlüsselt über das Internet übertragen.