Keine öffentliche IP am eigenen Internet-Anschluss?
Headscale verbindet Geräte hinter CGNAT, ohne dass ein Port am Router geöffnet werden muss.
Headscale ist ein selbst gehosteter Koordinationsserver für Tailscale-Clients und verbindet Geräte zu einem privaten WireGuard-Netz, ohne dass am Heimrouter ein Port geöffnet werden muss. Ein kostenloser Google-VPS mit 1 GB Trafficvolumen dient dabei als Vermittlungsstelle, die Nutzdaten nehmen einen anderen Weg. Am Beispiel einer Nextcloud auf Proxmox hinter CGNAT zeige ich, wie alles zusammenspielt und wie der Server leicht mit Docker aufgesetzt wird.
Das Problem mit CGNAT
Beim Carrier-Grade NAT teilen sich mehrere Anschlüsse eine öffentliche IPv4-Adresse. Man erkennt es leicht, wenn die Fritzbox eine Internet-IP aus einem privaten Netzbereich zugewiesen bekam (z.B. 10.x.y.z). Verbindungen von außen ins Heimnetz kommen deshalb nicht an, und ein Port-Forwarding im Router läuft ins Leere. Die Nextcloud im Keller ist damit vom Smartphone unterwegs nicht erreichbar, obwohl sie sich zu Hause bestens fühlt.
Die übliche Lösung für ein solches Problem führt über einen Tunneldienst eines Drittanbieters. Einen Tunnel in mein privates Netz zuhause möchte ich aber nicht einem fremden Drittanbieter ermöglichen. Daher geht es hier um eine komplett selbst betriebene Variante: Ein kleiner Server im Internet vermittelt lediglich, alles andere bleibt in eigener Hand.
Wer macht was
Headscale ist eine Open-Source-Implementierung des Tailscale-Koordinationsservers. Auf den Geräten kommen die ganz normalen Tailscale-Clients zum Einsatz, die lediglich auf den eigenen Server zeigen.
Als Bild taugt eine Rezeption im Bürogebäude. Sie weiß, wer zur Firma gehört, vergibt Besucherausweise (Schlüssel) und Zimmernummern (IP-Adressen) und kann jedem verraten, wo die Kollegen gerade sitzen. Kartons schleppt sie nicht, und in die Pakete schaut sie auch nicht.
Im Beispiel verteilen sich die Rollen so:
| Gerät | Aufgabe |
|---|---|
| Google-VPS | Headscale und Caddy (Reverse Proxy mit automatischem TLS) in Docker |
| Nextcloud-Rechner zu Hause | Tailscale-Client, Ziel der Verbindungen |
| Smartphone und Laptop | Tailscale-Clients |
Der Weg der Nutzdaten
Es gibt zwei getrennte Kanäle. Der Steuerkanal ist eine ausgehende HTTPS-Verbindung jedes Geräts zum Headscale-Server. Das Tailscale Control Protocol wird dabei per WebSocket getunnelt. Ausgehende Verbindungen sind hinter CGNAT kein Problem. Sobald ein Gerät im Internet surfen kann, funktioniert es. Über diesen Kanal melden Geräte ihre Schlüssel und erreichbaren Adressen, und sie erhalten die Liste aller Geräte im Netz.
Der Datenkanal ist ein WireGuard-Tunnel zwischen den Geräten selbst, wie ihn auch eine Fritzbox selbst anbieten kann, könnte man sie aus dem Internet erreichen:
Der Verbindungsaufbau läuft nach einem festen Muster ab, das in der Tailscale-Dokumentation beschrieben ist: Jede Verbindung startet zunächst über einen DERP-Relay (Designated Encrypted Relay for Packets). Parallel versuchen beide Seiten ein NAT-Traversal. Dabei schicken sie sich gleichzeitig UDP-Pakete zu, sodass die NAT-Geräte auf beiden Seiten Durchlässe für die jeweilige Gegenstelle öffnen. Das Prinzip erklärt Tailscale ausführlich im Beitrag How NAT traversal works. Gelingt der Trick, laufen die Daten direkt zwischen den Geräten. Gelingt er nicht, bleibt die Verbindung über den Relay bestehen.
Vielleicht kann ich es als Ablauf so am Besten beschreiben:
| Schritt | Smartphone (Tailscale-Client) | Headscale-VPS | Nextcloud-Server hinter CGNAT-FRITZ!Box |
|---|---|---|---|
| 1. Grundzustand |
Hat private IP im Mobilfunknetz, z. B.
10.x.x.x; sitzt hinter CGNAT des Mobilfunkanbieters.
|
Hat eine öffentliche IPv4- und/oder IPv6-Adresse, z. B.
198.51.100.10.
|
Hat private LAN-IP, z. B. 192.168.178.50;
die FRITZ!Box sitzt hinter CGNAT und besitzt keine direkt
erreichbare öffentliche IPv4-Adresse.
|
| 2. Registrierung | Smartphone meldet sich per HTTPS bei Headscale an und erhält Node-Key, Tailscale-IP sowie die Liste der anderen Nodes. | Prüft die Authentifizierung und verteilt Netzkonfiguration, Public Keys und ggf. ACLs. |
Nextcloud-Server meldet sich ebenfalls bei Headscale an und
erhält seine Tailscale-IP, z. B. 100.64.0.2.
|
| 3. STUN/Endpoint-Ermittlung | Smartphone sendet STUN über UDP/3478 an den konfigurierten STUN-/DERP-Dienst. |
Der STUN-Dienst sieht den öffentlichen Endpoint des Smartphones,
etwa Mobilfunk-CGNAT-IP:Port, und antwortet damit.
|
Nextcloud-Server sendet STUN über UDP/3478. Die FRITZ!Box erstellt
einen temporären NAT-Eintrag; der STUN-Dienst sieht den Endpoint
des Provider-CGNAT, etwa CGNAT-IP:Port.
|
| 4. NAT-Zustände |
Das Mobilfunk-CGNAT speichert temporär:
Smartphone-LAN:Port ↔ CGNAT-IP:Port.
|
– |
Die FRITZ!Box speichert:
Nextcloud-LAN:Port ↔ FRITZ!Box-WAN:Port;
das Provider-CGNAT speichert zusätzlich:
FRITZ!Box-WAN:Port ↔ CGNAT-IP:Port.
|
| 5. Kandidaten austauschen | Smartphone übermittelt seine Kandidaten an Headscale. | Leitet Kandidaten, Public Keys und Verbindungsdaten zwischen Smartphone und Nextcloud-Server weiter. | Nextcloud-Server übermittelt seine Kandidaten, einschließlich des STUN-ermittelten Endpunkts hinter CGNAT. |
| 6. UDP-Hole-Punching | Smartphone sendet UDP-Probes an den bekannten Endpoint des Nextcloud-Servers. | – | Nextcloud-Server sendet UDP-Probes an den bekannten Endpoint des Smartphones. |
| 7. CGNAT-Hürde | Das Mobilfunk-CGNAT muss die Antwort des Nextcloud-Servers als Teil der ausgehenden UDP-Sitzung akzeptieren. | – | Hier können zwei NATs scheitern: FRITZ!Box und Provider-CGNAT. Das CGNAT muss das Probe des Smartphones als Antwort auf die ausgehende UDP-Sitzung des Nextcloud-Servers zulassen. |
| 8. Direkter UDP-Pfad | Wenn beide CGNATs kooperativ genug sind, entsteht ein direkter UDP-Pfad. | Der Headscale-Server ist danach nicht mehr am Datenpfad beteiligt. | Wenn beide CGNATs kooperativ genug sind, entsteht ebenfalls ein direkter UDP-Pfad. |
| 9. WireGuard-Handshake | Smartphone und Nextcloud-Server führen den WireGuard-Handshake direkt durch. | Keine Beteiligung am Datenverkehr. | Nextcloud-Server und Smartphone verschlüsseln den Datenverkehr Ende-zu-Ende per WireGuard. |
| 10. Zugriff |
Smartphone erreicht Nextcloud über dessen Tailscale-IP, etwa
https://100.64.0.2 oder einen im Tailnet
konfigurierten DNS-Namen.
|
– | Nextcloud-Server empfängt die Anfrage über die Tailscale-Schnittstelle; kein Port Forwarding in der FRITZ!Box und keine öffentliche Erreichbarkeit aus dem Internet nötig. |
| 11. Fallback über DERP | Falls UDP-Hole-Punching scheitert, sendet das Smartphone verschlüsselte WireGuard-Pakete an den DERP-Server. | Der eingebettete oder konfigurierte DERP-Server empfängt und leitet die verschlüsselten Pakete an den Nextcloud-Server weiter. | Der Nextcloud-Server empfängt über DERP und antwortet ebenfalls über DERP. |
| 12. Sicherheit | Der Smartphone-Nutzer sieht nur die Tailscale-IP bzw. den DNS-Namen des Nextcloud-Servers. | Sieht bei DERP nur verschlüsselte WireGuard-Frames, nicht den Klartext der Nextcloud-Kommunikation. | Nextcloud bleibt vom öffentlichen Internet aus unerreichbar; Zugriff besteht nur für Geräte im Tailnet. |
Ein Haken: Sitzen beide Seiten hinter einem Hard NAT, ist keine direkte Verbindung möglich. Ein CGNAT-Anschluss zu Hause ist ein typischer Kandidat. Ob es klappt, hängt also auch vom Netz des Smartphones oder Laptops ab, und das lässt sich nur ausprobieren. Ein Relay funktioniert in jedem Fall, ist dann aber meist langsamer.
Entscheidend für den kostenlosen 1-GB-Tarif: Der VPS ist in diesem Aufbau nur Rezeption und kein Lastwagen. Die Standardkonfiguration von Headscale verwendet die öffentliche DERP-Liste von Tailscale und hat den eingebetteten DERP-Server abgeschaltet. Relayed Nutzdaten laufen damit nie über den VPS. Würde der eingebettete DERP-Server aktiviert, müsste jede Nextcloud-Synchronisation im Relay-Fall durch das kleine Datenkontingent des VPS.
Der Preis dafür: Falls ein Relay nötig ist, nutzt es Infrastruktur von Tailscale. Die Pakete bleiben Ende-zu-Ende verschlüsselt, aber die Relays können sehen, welche IP-Adressen miteinander sprechen.
Voraussetzungen
- Ein Google-VPS mit öffentlicher IPv4, eingerichtet wie im Artikel Kostenlosen Server bei Google einrichten beschrieben. Dort ist auch das Limit von 1 GB ausgehendem Traffic pro Monat erwähnt.
- Freigegebene Ports TCP 80 und 443. Die Instanz aus dem Artikel trägt dafür die Tags
http-serverundhttps-server. Der Admin-Port 81 des nginx-proxy-manager wird bewusst nicht freigegeben. - Ein A-Record
hs.meister-security.deauf die IPv4 des VPS. Diebase_domainfür DNS muss sich laut Beispielkonfiguration von der Server-Domain unterscheiden. Dafür dientts.meister-security.de, ein Name, der nur innerhalb des Tailnets aufgelöst wird und keinen DNS-Eintrag braucht. Die lokale Domainmeister.lanbleibt außen vor, damit sich beide Namensräume nicht in die Quere kommen. - Docker mit Compose-Plugin auf dem VPS. Die Installation klappt mit dem offiziellen Skript:
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
# Danach einmal ab- und wieder anmelden
Headscale mit Docker aufsetzen
Das folgende Skript legt die Verzeichnisse an, lädt die offizielle Beispielkonfiguration der gepinnten Version und passt vier Werte an. Neben Server-URL und Listen-Adresse wird override_local_dns auf false gesetzt. Andernfalls würde Headscale allen Clients standardmäßig die DNS-Server von Cloudflare aufzwingen, und das passt schlecht zu einem Selbsthosting-Projekt.
#!/usr/bin/env bash
# Headscale-Vorbereitung - M. Meister
# Legt Verzeichnisse an und erzeugt die config.yaml aus der offiziellen Beispieldatei.
HS_VERSION="0.29.5"
HS_DOMAIN="${1:?Aufruf: ./prepare.sh hs.meister-security.de ts.meister-security.de}"
BASE_DOMAIN="${2:?Aufruf: ./prepare.sh hs.meister-security.de ts.meister-security.de}"
mkdir -p headscale/{config,lib} npm/{data,letsencrypt}
curl -fsSL "https://raw.githubusercontent.com/juanfont/headscale/v${HS_VERSION}/config-example.yaml" \
-o headscale/config/config.yaml
sed -i -E \
-e "s|^server_url:.*|server_url: https://${HS_DOMAIN}|" \
-e "s|^listen_addr:.*|listen_addr: 0.0.0.0:8080|" \
-e "s|^( +)base_domain:.*|\1base_domain: ${BASE_DOMAIN}|" \
-e "s|^( +)override_local_dns:.*|\1override_local_dns: false|" \
headscale/config/config.yaml
# Kontrolle der geänderten Zeilen
grep -nE '^(server_url|listen_addr):|base_domain:|override_local_dns:' headscale/config/config.yaml
Ausführen und die Ausgabe prüfen:
chmod +x prepare.sh
./prepare.sh hs.meister-security.de ts.meister-security.de
Erwartet werden vier Treffer mit den eigenen Domains. Alle Daten liegen anschließend portabel unter dem Verzeichnis der Compose-Datei, ganz ohne Docker-Volumes. Damit lässt sich der komplette Stack bei Bedarf einfach auf einen anderen Host umziehen.
Die docker-compose.yml richtet sich nach der offiziellen Container-Anleitung: schreibgeschütztes Dateisystem, Konfiguration nur lesbar. Headscale veröffentlicht keinen Port nach außen und ist nur für den nginx-proxy-manager im gemeinsamen Docker-Netz erreichbar. Dessen Admin-Oberfläche lauscht ausschließlich auf 127.0.0.1.
# docker-compose.yml - M. Meister
services:
headscale:
image: docker.io/headscale/headscale:0.29.5
container_name: headscale
restart: unless-stopped
read_only: true
tmpfs:
- /var/run/headscale
volumes:
- ./headscale/config:/etc/headscale:ro
- ./headscale/lib:/var/lib/headscale
command: serve
healthcheck:
test: ["CMD", "headscale", "health"]
networks:
- proxy
npm:
image: docker.io/jc21/nginx-proxy-manager:latest
container_name: npm
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "127.0.0.1:81:81"
volumes:
- ./npm/data:/data
- ./npm/letsencrypt:/etc/letsencrypt
depends_on:
- headscale
networks:
- proxy
networks:
proxy:
Läuft auf dem VPS bereits ein nginx-proxy-manager, entfällt der Block npm. Der Headscale-Container wird dann in dessen Docker-Netz gehängt, indem proxy als externes Netz mit dem tatsächlichen Namen des vorhandenen Netzes deklariert wird.
Starten und prüfen:
docker compose up -d
docker compose ps
docker logs --tail 30 headscale
Die Admin-Oberfläche des nginx-proxy-manager ist nur lokal auf dem VPS erreichbar. Vom Arbeitsrechner aus genügt ein SSH-Tunnel:
ssh -L 8081:127.0.0.1:81 <BENUTZER>@<VPS-IP>
Danach ist die Oberfläche im Browser unter http://127.0.0.1:8081 erreichbar. Beim allerersten Start muss dort ein Admin-Konto angelegt werden.
Proxy Host im nginx-proxy-manager einrichten
Unter Hosts und Proxy Hosts wird mit Add Proxy Host ein neuer Eintrag angelegt. Die Werte im Reiter Details:
Domain Names:hs.meister-security.deScheme:httpForward Hostname / IP:headscaleForward Port:8080Websockets Support: aktiviert
Der WebSocket-Schalter ist der wichtigste Punkt. Tailscale-Clients sprechen ein eigenes Protokoll, das per WebSocket-Upgrade läuft. Ohne diese Option melden sich die Geräte nie an.
Im Reiter SSL wird Request a new SSL Certificate gewählt, dazu Force SSL und HTTP/2 Support aktiviert, die Let's-Encrypt-Bedingungen akzeptiert und gespeichert. Das funktioniert nur, wenn der A-Record bereits auf den VPS zeigt und Port 80 von außen erreichbar ist.
Ob alles passt, zeigt der Health-Endpunkt:
curl -i https://hs.meister-security.de/health
Ein HTTP 200 bedeutet, dass der Koordinationsserver einsatzbereit ist.
Benutzer und Schlüssel anlegen
Headscale ordnet jedes Gerät einem Benutzer zu. Alle Kommandos laufen im Container:
docker exec -it headscale headscale users create zuhause
docker exec -it headscale headscale users list
In der Ausgabe von users list steht die numerische ID des Benutzers, meist 1. Sie wird für den Preauth-Key benötigt. Standardmäßig ist ein solcher Schlüssel eine Stunde gültig und nur einmal verwendbar:
docker exec -it headscale headscale preauthkeys create --user 1
Der ausgegebene Schlüssel wird im nächsten Schritt gebraucht.
Den Nextcloud-Rechner anbinden
Auf der VM oder dem LXC, in dem Nextcloud läuft, wird der Tailscale-Client installiert und per Preauth-Key bei Headscale angemeldet:
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up \
--login-server https://hs.meister-security.de \
--authkey <PREAUTH_KEY> \
--hostname nextcloud
tailscale ip -4
Die letzte Zeile liefert die Tailscale-IP, zum Beispiel 100.64.0.1. Sie stammt aus dem Bereich 100.64.0.0/10, der in der Konfiguration unter prefixes steht.
Läuft Nextcloud in einem unprivilegierten LXC auf Proxmox, fehlt diesem zunächst das TUN-Device. Die Tailscale-Dokumentation zu LXC nennt dafür zwei Befehle auf dem Proxmox-Host, danach wird der Container neu gestartet. Die Installation von Tailscale folgt erst anschließend:
pct set <CTID> --dev0 /dev/net/tun
pct set <CTID> --features keyctl=1,nesting=1
Nextcloud akzeptiert nur Zugriffe über bekannte Adressen. Im Heimnetz ist dort vermutlich schon ein Name wie nextcloud.meister.lan eingetragen. Für den Zugriff über das Tailnet kommen die Tailscale-IP und der MagicDNS-Name hinzu. Dieser setzt sich aus Hostname und base_domain zusammen, hier also nextcloud.ts.meister-security.de. Zuerst werden die vorhandenen Einträge angezeigt, dann kommen die neuen mit den nächsten freien Indizes dazu (hier 3 und 4, bitte anpassen):
sudo -u www-data php occ config:system:get trusted_domains
sudo -u www-data php occ config:system:set trusted_domains 3 --value=100.64.0.1
sudo -u www-data php occ config:system:set trusted_domains 4 --value=nextcloud.ts.meister-security.de
Läuft Nextcloud in Docker, wird vor php occ ein docker exec -u www-data <container> gesetzt.
Smartphone und Laptop anbinden
Beim Smartphone kommt der offizielle Tailscale-Client aus dem Play Store oder von F-Droid zum Einsatz. In der Headscale-Doku für Android steht der Weg: Einstellungen öffnen, Accounts wählen, im Menü mit den drei Punkten Use an alternate server antippen und die Server-URL https://hs.meister-security.de eintragen.
Anschließend öffnet sich eine Webseite, die eine Auth-ID anzeigt. Freigegeben wird das Gerät auf dem VPS:
docker exec -it headscale headscale auth register --user zuhause --auth-id <AUTH_ID>
Auf einem Linux-Laptop läuft es genauso. Der Client wird installiert, die Anmeldung gestartet und die angezeigte Auth-ID freigegeben:
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --login-server https://hs.meister-security.de
Für Windows und macOS stehen die Schritte in der Doku für Windows und Apple.
MagicDNS statt IP-Adressen
Jedes Gerät im Tailnet bekommt von Headscale eine IP-Adresse aus dem Bereich 100.64.0.0/10. Auswendig lernen muss diese IPs niemand, denn dafür gibt es MagicDNS. Die Funktion vergibt jedem Gerät automatisch einen Namen, der sich aus Hostname und base_domain zusammensetzt, so steht es in der Beispielkonfiguration. Aus --hostname nextcloud und base_domain: ts.meister-security.de wird nextcloud.ts.meister-security.de.
Diese Namen gibt es nur innerhalb des Tailnets. Im öffentlichen DNS ist dafür kein Eintrag nötig. Die base_domain muss sich von der Domain des Headscale-Servers unterscheiden und sollte nicht mit dem lokalen Heimnetz-Namensraum meister.lan kollidieren, deshalb die eigene Subdomain.
Falls ein Name auf einem Client nicht aufgelöst wird, ist die Tailscale-IP der sichere Weg. Ich habe die MagicDNS-Auflösung mit override_local_dns: false nicht selbst getestet.
Verbindung und Datenweg prüfen
Ob eine Verbindung direkt oder über einen Relay läuft, zeigt der Client selbst. Auf dem Laptop:
tailscale status
tailscale ping nextcloud
Das Wort direct in der Statuszeile bedeutet eine direkte Verbindung, relay steht für einen DERP-Umweg. Die Ausgaben sehen nach dem Format der Tailscale-Beispiele etwa so aus, die konkreten Werte unterscheiden sich:
100.64.0.1 nextcloud zuhause linux active; direct 203.0.113.7:41641
100.64.0.1 nextcloud zuhause linux active; relay "fra"
Beim tailscale ping laufen die ersten Pakete meist noch über den DERP-Server. Sobald das NAT-Traversal geklappt hat, wechselt die Anzeige auf die direkte Adresse. Bleibt es bei DERP, endet die Ausgabe mit direct connection not established. Das ist kein Fehler, sondern der beschriebene Hard-NAT-Fall. Danach reicht es, im Browser oder in der Nextcloud-App die Adresse http://100.64.0.1 aufzurufen. Die Strecke ist ohnehin per WireGuard verschlüsselt. Die App darf trotzdem einen Hinweis zur fehlenden TLS-Verschlüsselung anzeigen.
Stolpersteine
- Der Preauth-Key läuft nach einer Stunde ab. Für weitere Geräte wird ein neuer erzeugt.
- Die Tailscale-Clients müssen mindestens Version 1.80.0 haben, das nennen die Release Notes zu 0.29.4 als Mindestversion.
- Das Verzeichnis
headscale/libenthält die SQLite-Datenbank und den Noise-Schlüssel. Es gehört in jedes Backup, sonst müssen alle Geräte neu angemeldet werden. (Den Fehler mache ich nicht nochmal 😏) - Updates erfolgen über die gepinnte Version in der
docker-compose.yml, nach Lektüre der Upgrade-Anleitung.
Fazit
Headscale übernimmt auf dem Gratis-VPS nur die Koordination, die eigentlichen Daten fließen per WireGuard direkt zwischen den Geräten oder verschlüsselt über einen DERP-Relay. Weil der eingebettete DERP-Server abgeschaltet bleibt, bleibt das 1-GB-Limit des VPS unangetastet. Hinter CGNAT bleibt eine direkte Verbindung Glückssache, ein funktionierender Relay-Weg ist aber immer vorhanden.