2tap2b
homelabprojectsarchivetags

Headscale / Headplane upgraden

16 Apr 2026
5 min read
headscale headplane vpn
Inhaltsverzeichnis

Wie ich Headscale und Headplane zusammen installiert habe, habe ich sehr ausführlich hier beschrieben. Nun ist die Anleitung knapp ein Jahr alt und es wird mal Zeit, den ganzen Stack auf die neueste Version zu bringen. Aktuell ist das bei Headscale v0.28 und Headplane v0.6.2.

Aufgrund von immer wiederkehrenden Breaking Changes ist diese Anleitung auch wirklich nur mit diesen Versionen kompatibel. Insbesondere hat sich geändert:

  • Policy Format v2 ist erforderlich
  • SSH Policy-Syntax wurde geändert
  • API Keys haben ein neues Format
  • Headplane benötigt zusätzliche Konfiguration

Wir machen erstmal ein Backup der aktuellen Config, um ggf. ein Rollback zu machen.

1. Vorbereitung & Backup

1.1 Backup erstellen

Immer zuerst ein Backup erstellen! Dies ist besonders wichtig, da das Upgrade Breaking Changes enthält.

# Container stoppen
docker compose -f /opt/containers/headscale/compose.yaml down

# Backup-Ordner mit Zeitstempel erstellen
BACKUP_DIR="/opt/containers/headscale-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Gesamtes Headscale-Verzeichnis sichern
cp -r /opt/containers/headscale/* "$BACKUP_DIR/"

# Backup als tar.gz komprimieren (optional)
tar -czf "${BACKUP_DIR}.tar.gz" -C /opt/containers "$(basename $BACKUP_DIR)"

echo "✓ Backup erstellt in: $BACKUP_DIR"

1.2 Aktuelle Konfiguration dokumentieren

Notiere dir wichtige Informationen aus deinem aktuellen Setup:

  • Server URL
  • OIDC Client ID und Secret
  • Anzahl der verbundenen Nodes
# Anzahl der Nodes vor dem Upgrade anzeigen (optional)
docker exec headscale headscale nodes list

2. Headscale auf v0.28.0 upgraden

2.1 Docker Compose aktualisieren

Bearbeite die compose.yaml:

nano /opt/containers/headscale/compose.yaml

Ändere die Headscale Image-Version:

  headscale:
    image: headscale/headscale:0.28.0  # vorher: 0.25.1
    container_name: headscale
    restart: unless-stopped
    command: serve

Füge das Headplane Docker Integration Label hinzu:

    labels:
      # Required label for Headplane Docker integration
      - "me.tale.headplane.target=headscale"
      
      # Traefik configuration
      - "traefik.enable=true"
      # ... restliche Labels

2.2 Headscale Konfiguration anpassen

Bearbeite die Headscale-Konfiguration:

nano /opt/containers/headscale/headscale-config/config.yaml

Wichtige Änderungen für v0.28:

  1. OIDC E-Mail-Verifizierung (empfohlen):
oidc:
  # ... bestehende OIDC-Einstellungen
  email_verified_required: true  # Neu hinzufügen
  1. DERP Update-Frequenz anpassen (optional):
derp:
  update_frequency: 3h  # vorher: 24h (empfohlen für v0.28)
  1. Policy-Modus auf database setzen (falls noch nicht geschehen):
policy:
  mode: database  # Wichtig für Headplane UI

3. Policy auf v2 migrieren

3.1 Policy-Datei aktualisieren

Die SSH-Policy-Syntax hat sich in v0.28 geändert. Der * Wildcard ist nicht mehr erlaubt.

nano /opt/containers/headscale/headscale-config/policy.json

Alte SSH-Policy (v0.25):

{
  "ssh": [
    {
      "action": "accept",
      "src": ["*"],
      "dst": ["*"],
      "users": ["*"]
    }
  ]
}

Neue SSH-Policy (v0.28 mit Autogroups):

{
  "acls": [
    {
      "action": "accept",
      "src": ["*"],
      "dst": ["*:*"]
    }
  ],
  "ssh": [
    {
      "action": "accept",
      "src": ["autogroup:member"],
      "dst": ["autogroup:self"],
      "users": ["autogroup:nonroot", "root"]
    },
    {
      "action": "accept",
      "src": ["autogroup:member"],
      "dst": ["autogroup:tagged"],
      "users": ["autogroup:nonroot", "root"]
    },
    {
      "action": "accept",
      "src": ["autogroup:tagged"],
      "dst": ["autogroup:tagged"],
      "users": ["autogroup:nonroot", "root"]
    }
  ]
}

Erklärung der neuen Autogroups:

  • autogroup:member = Alle User-owned Geräte
  • autogroup:tagged = Alle getaggten Geräte
  • autogroup:self = Das eigene Gerät
  • autogroup:nonroot = Alle non-root User auf dem Zielsystem

3.2 Container starten und Policy in Datenbank migrieren

Die Policy-Änderung in der Datei reicht nicht aus - sie muss auch in die Datenbank migriert werden!

# Container starten
docker compose -f /opt/containers/headscale/compose.yaml up -d headscale

# Warten bis Headscale bereit ist
sleep 5

# Policy aus Datei in Datenbank übertragen (kritisch!)
docker run --rm \
  -v /opt/containers/headscale/headscale-data:/var/lib/headscale \
  -v /opt/containers/headscale/headscale-config:/etc/headscale \
  headscale/headscale:0.28.0 \
  policy set --bypass-grpc-and-access-database-directly

# Logs überprüfen
docker logs headscale --tail 50

⚠️ Wichtig: Der --bypass-grpc-and-access-database-directly Parameter ist notwendig, da die Policy direkt in der SQLite-Datenbank aktualisiert werden muss.

4. Headplane auf v0.6.2 upgraden

4.1 Headplane Image-Version aktualisieren

Bearbeite die compose.yaml:

nano /opt/containers/headscale/compose.yaml
  headplane:
    image: ghcr.io/tale/headplane:0.6.2  # vorher: 0.5.10
    container_name: headplane
    restart: unless-stopped

4.2 Headplane-Konfiguration anpassen

Bearbeite die Headplane-Konfiguration:

nano /opt/containers/headscale/config.yaml

Wichtige Änderungen für v0.6.2:

  1. Base URL hinzufügen (neu erforderlich):
server:
  base_url: "https://hs.DEINE-DOMAIN.de"  # Deine Headscale-URL
  bind: "0.0.0.0:3000"
  cookie_secret: "DEIN_BESTEHENDER_SECRET"
  1. API Key auf v0.28-Format aktualisieren:

Erstelle einen neuen API Key mit längerer Gültigkeit:

docker exec headscale headscale apikeys create --expiration 999d

Kopiere den generierten Key (beginnt mit hskey-api-...) und trage ihn ein:

headscale:
  url: "https://hs.DEINE-DOMAIN.de"
  api_key: "hskey-api-DEIN_NEUER_KEY_HIER"
  1. Docker Integration konfigurieren:
  docker:
    enabled: true
    socket_path: "/var/run/docker.sock"
    container_label: "me.tale.headplane.target=headscale"  # Wichtig!
  1. Veraltete Einstellungen entfernen (optional):
oidc:
  # user_storage_file: "/var/lib/headplane/users.json"  # Diese Zeile ENTFERNEN (deprecated)

5. Services starten und verifizieren

5.1 Alle Container starten

# Alle Container neu starten
docker compose -f /opt/containers/headscale/compose.yaml down
docker compose -f /opt/containers/headscale/compose.yaml up -d

# Warten bis Services bereit sind

5.2 Logs überprüfen

# Headscale Logs
docker logs headscale --tail 50

# Headplane Logs
docker logs headplane --tail 50

Hier sollten keine Errors oder Fatals auftauchen.

5.3 Nodes überprüfen

# Alle Nodes anzeigen
docker exec headscale headscale nodes list

Somit sollte euer Headscale / Headplane Stack up-to-date sein.