Teil 3: Geräte hinzufügen

Der Weg unterscheidet sich zwischen Geräten mit Terminal-Zugriff (Computer, Server) und Mobilgeräten (iOS/Android). Lange Zeit unterstützten die mobilen Tailscale-Apps keine Kombination aus benutzerdefiniertem Server und Preauth-Key, das ist seit einem App-Update (Changelog: "Auth keys can be used for connecting to a custom coordination server") behoben, siehe Weg B.

Weg A: Computer und Server (mit Terminal)

1. Preauthkey erzeugen

docker exec headscale headscale users list

Die ID des gewünschten Users notieren, dann:

docker exec headscale headscale preauthkeys create --user <USER_ID> --expiration 24h --reusable

2. Tailscale installieren und verbinden

Auf dem Zielgerät zunächst die offizielle Tailscale-App installieren, dann:

tailscale up --login-server=https://vpn.example.com --authkey=<KEY>

Auf macOS, falls tailscale nicht im PATH ist:

/Applications/Tailscale.app/Contents/MacOS/Tailscale up --login-server=https://vpn.example.com --authkey=<KEY>

3. Kontrollieren

docker exec headscale headscale nodes list

Weg B: Mobilgeräte (iOS/Android)

Aktueller Weg: Preauthkey, genau wie bei Weg A

1. Preauthkey erzeugen:

docker exec headscale headscale users list
docker exec headscale headscale preauthkeys create --user <USER_ID> --expiration 24h --reusable

2. In der Tailscale-App: 1. Account-Symbol antippen → Add Account… 2. Optionen-Symbol oben rechts → Advanced Login Options 3. "Use a custom coordination server" wählen, https://vpn.example.com eintragen 4. Im selben Menü "Use an auth key" wählen, den Preauthkey einfügen 5. Bestätigen — das Gerät verbindet sich direkt, ganz ohne manuelle Freigabe

3. Kontrollieren:

docker exec headscale headscale nodes list

Ob Android bereits denselben Stand hat, ist nicht sicher (die Ankündigung war iOS-spezifisch). Falls "Advanced Login Options" bei dir fehlt oder die App-Version älter ist, hilft der Fallback-Weg unten.

Fallback: Manuelle Freigabe (ältere App-Versionen)

1. Custom-Server eintragen

iOS/iPadOS: 1. In den iOS-Systemeinstellungen (nicht in der App selbst) zur Tailscale-App scrollen 2. Feld "Alternate Coordination Server URL": https://vpn.example.com 3. Tailscale-App komplett schließen und neu öffnen 4. Regulären "Sign in" wählen (nicht SSO)

Android: 1. App öffnen, oben rechts das Drei-Punkte-Menü mehrfach öffnen/schließen, bis "Change server" erscheint 2. https://vpn.example.com eintragen 3. App neu starten, regulären "Sign in" wählen

2. Registrierung abschließen

Nach dem Sign-in-Tap zeigt das Gerät einen Befehl wie:

headscale auth register --auth-id hskey-authreq-XXXXXXXXXXXX --user USERNAME

Führe ihn so auf dem Server aus (der Username, nicht die ID!):

docker exec headscale headscale auth register --auth-id hskey-authreq-XXXXXXXXXXXX --user mama

3. Gerät sinnvoll umbenennen

Neu registrierte Mobilgeräte tauchen oft mit einem unpraktischen Namen wie localhost auf:

docker exec headscale headscale nodes list
docker exec headscale headscale nodes rename -i <NODE_ID> iphone-mama

Komfort-Skript für den Fallback-Weg

#!/bin/bash
# ~/headscale/hsuserreg.sh
set -euo pipefail

usage() {
    echo "Usage: hsuserreg <auth-id> <device-name> <user>"
    exit 1
}

if [[ $# -lt 3 ]]; then
    usage
fi

AUTH_ID="$1"
DEVICE_NAME="$2"
HS_USER="$3"

docker exec headscale headscale auth register --auth-id "$AUTH_ID" --user "$HS_USER"

NODE_ID=$(docker exec headscale headscale nodes list --output json \
    | jq -r --arg user "$HS_USER" \
    '[.[] | select(.user.name == $user)] | sort_by(.id | tonumber) | last | .id')

docker exec headscale headscale nodes rename -i "$NODE_ID" "$DEVICE_NAME"
docker exec headscale headscale nodes list

chmod +x ~/headscale/hsuserreg.sh
echo "alias hsuserreg='~/headscale/hsuserreg.sh'" >> ~/.bashrc
source ~/.bashrc

Nutzung:

hsuserreg hskey-authreq-XXXXXXXXXXXX iphone-mama mama

Der user-Parameter ist bewusst verpflichtend, ohne Standardwert, damit ein Gerät nicht versehentlich unter deinem eigenen Account landet, falls du ihn vergisst.

Aufräumen: doppelte oder verwaiste Geräte

docker exec headscale headscale nodes list
docker exec -it headscale headscale nodes delete -i <NODE_ID>

Das -it ist wichtig, sonst kann die Ja/Nein-Bestätigung nicht beantwortet werden und der Befehl bricht ab.

Weiter geht's in Teil 4, wie du eigene Dienste erreichbar machst.