Headscale Tailscale Self Hosted Controller

Zuletzt aktualisiert: 05.04.2026 um 19:42 Uhr

Headscale – Self-Hosted Tailscale Control Server einrichten

Was ist Tailscale?

Tailscale ist eine WireGuard-basierte Mesh-VPN Lösung, die es einfach macht, Geräte sicher miteinander zu verbinden. Tailscale bietet eine cloudbasierte Lösung, aber auch eine selbst gehostete Alternative: Headscale.

Was ist Headscale?

Headscale ist ein Open-Source, selbst gehosteter Control Server für Tailscale Clients. Mit Headscale können Sie ein privates Mesh-VPN-Netzwerk vollständig selbst verwalten, ohne sich auf den Tailscale Cloud Service verlassen zu müssen.

Architektur:

Headscale Server: Zentraler Control Server koordiniert Verbindungen
Tailscale Clients: Auf Ihren Geräten installierte VPN-Clients
Peer-to-Peer Verbindungen: Nachdem Koordination stattgefunden hat, verbinden sich Clients direkt (Wireguard)
DERP Relay: Fallback für Clients, die sich nicht direkt erreichen können

💡 Tipp: Headscale ist vollständig kompatibel mit offiziellen Tailscale Clients. Sie können auch Tailscale Cloud und Headscale mixed verwenden (verschiedene Geräte mit unterschiedlichen Control Servern).

Systemanforderungen

Komponente	Minimum	Empfohlen
Betriebssystem	Ubuntu 20.04	Ubuntu 22.04 LTS oder Debian 12
CPU	1 Kern	2+ Kerne
RAM	256 MB	1-2 GB
Speicher	100 MB	1 GB
Netzwerk	1 Mbps	10 Mbps+

Installation auf Ubuntu/Debian

Schritt 1: System aktualisieren

apt update
apt upgrade -y
apt install -y wget curl

Schritt 2: Headscale Binary herunterladen

Holen Sie sich die neueste Version von GitHub:

wget https://github.com/juanfont/headscale/releases/download/v0.22.3/headscale_0.22.3_linux_amd64
chmod +x headscale_0.22.3_linux_amd64
sudo mv headscale_0.22.3_linux_amd64 /usr/local/bin/headscale

Schritt 3: Systembenutzer und Verzeichnisse erstellen

sudo useradd --system --create-home headscale
sudo mkdir -p /etc/headscale
sudo mkdir -p /var/lib/headscale
sudo chown -R headscale:headscale /var/lib/headscale

Schritt 4: Konfigurationsdatei erstellen

Erstellen Sie /etc/headscale/config.yaml:

server:
  listen_addr: 0.0.0.0
  listen_port: 8080
  grpc_listen_addr: 0.0.0.0
  grpc_listen_port: 50443

serve_tls:
  cert_file: ""
  key_file: ""

# Öffentliche URL wo Clients sich verbinden
server_url: https://headscale.example.com

# Datenbankpfad
db:
  type: sqlite3
  sqlite:
    path: /var/lib/headscale/db.sqlite3

# IP-Adressen für Clients
ip_prefixes:
  - fd7a:115c:a1e0::/48
  - 100.64.0.0/10

# DERP Server (für Relay bei NAT Problemen)
derp:
  server:
    enabled: false
    region_id: 999
    region_code: "headscale"
    region_name: "Headscale Derp Server"
    stun_listen_addr: "0.0.0.0:3478"
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  paths: []

# Authentication Policy
policy:
  mode: file
  path: /etc/headscale/acl.hujson

# Logging
log:
  level: info
  format: text

Schritt 5: Access Control List (ACL) erstellen

Erstellen Sie /etc/headscale/acl.hujson für Netzwerkrichtlinien:

// Headscale ACL Policy
{
  "groups": {
    "group:home": ["user1@headscale"],
    "group:work": ["user2@headscale", "user3@headscale"],
  },

  "hosts": {
    "router": "100.64.1.1",
    "server": "100.64.1.2",
    "laptop": "100.64.1.3",
  },

  "acls": [
    // Alle Geräte im Home-Netzwerk können miteinander kommunizieren
    {
      "action": "accept",
      "src": ["group:home"],
      "dst": ["group:home:*"],
    },
    // Work-Gruppe kann mit Work-Servern sprechen
    {
      "action": "accept",
      "src": ["group:work"],
      "dst": ["host:server:*"],
    },
  ],
}

Schritt 6: Systemd Service erstellen

Erstellen Sie /etc/systemd/system/headscale.service:

[Unit]
Description=Headscale VPN Control Server
After=network.target

[Service]
Type=simple
User=headscale
Group=headscale
ExecStart=/usr/local/bin/headscale serve
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Schritt 7: Service aktivieren und starten

sudo systemctl daemon-reload
sudo systemctl enable headscale
sudo systemctl start headscale

# Status prüfen
sudo systemctl status headscale

# Logs anschauen
sudo journalctl -u headscale -f

Nginx Reverse Proxy Setup

Headscale hinter Nginx mit HTTPS:

server {
    listen 80;
    server_name headscale.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name headscale.example.com;

    ssl_certificate /etc/letsencrypt/live/headscale.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/headscale.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        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_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /grpc {
        if ($request_method = 'OPTIONS') {
            return 200;
        }
        proxy_pass http://localhost:50443;
        proxy_http_version 2.0;
        proxy_set_header Host $host;
    }
}

Nginx aktivieren und SSL einrichten:

ln -s /etc/nginx/sites-available/headscale /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

certbot certonly --nginx -d headscale.example.com

⚠️ Wichtig: Ändern Sie die server_url in der config.yaml zu Ihrer Domain mit HTTPS. Dies ist entscheidend für die Client-Verbindung.

Benutzer und Authentifizierung

Benutzer erstellen

sudo headscale users create user1
sudo headscale users create user2
sudo headscale users create user3

Benutzer auflisten

sudo headscale users list

Authentifizierungsschlüssel generieren

Für jeden Benutzer müssen Sie einen Auth-Schlüssel generieren:

sudo headscale preauthkeys create --user user1 --reusable

# Ausgabe:
# Preauthkey: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
# Created:    2024-04-05T10:30:00Z
# Expiration: 2024-05-05T10:30:00Z
# Reusable:   true
# Used:       false
# Used by:

Tailscale Clients verbinden

Linux Client verbinden

# Tailscale installieren (Ubuntu/Debian)
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/focal.noarmor.gpg | sudo apt-key add -
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/focal.tailscale-keyfile.list | \
    sudo tee /etc/apt/sources.list.d/tailscale.list
sudo apt-get update
sudo apt-get install tailscale

# Mit Headscale verbinden
sudo tailscale up --login-server https://headscale.example.com --authkey 0123456789abcdef...

# Status prüfen
sudo tailscale status

# IP-Adresse anzeigen
ip addr show tailscale0

Windows/macOS Client

Installieren Sie Tailscale vom offiziellen Store
Öffnen Sie die App
Klicken Sie auf "Use another login server"
Geben Sie ein: https://headscale.example.com
Authentifizieren Sie mit dem Authkey

Android/iOS Mobile

Installieren Sie "Tailscale" aus Google Play oder App Store
Öffnen Sie die App und tippen Sie Connect
Wählen Sie "Custom login server"
Geben Sie https://headscale.example.com ein

Nodes (angebundene Geräte) verwalten

Nodes auflisten

sudo headscale nodes list

# Zeigt:
# ID | Name                       | User   | IP Address | Last Seen
# 1  | laptop-linux               | user1  | 100.64.1.2 | 2 hours ago
# 2  | iphone-12-pro              | user2  | 100.64.1.3 | now
# 3  | desktop-windows            | user1  | 100.64.1.4 | 30 minutes ago

Node Details anzeigen

sudo headscale nodes info 1

Node löschen (abmelden)

sudo headscale nodes delete 1

Routen und Exit Nodes

Exit Node konfigurieren

Ein Exit Node leitet den gesamten Traffic über eine zentrale Stelle (z.B. für VPN-Funktionalität):

# Node 1 als Exit Node aktivieren
sudo headscale routes enable --id 1

# Auf Client: gesamten Traffic über Node 1 leiten
sudo tailscale set --exit-node 100.64.1.2

Routen auflisten

sudo headscale routes list

DERP Server (für NAT Traversal)

DERP Relay sind notwendig, wenn Clients sich nicht direkt erreichen können (NAT/Firewall):

Öffentliche DERP Server nutzen

Standardmäßig nutzt Headscale Tailscale's öffentliche DERP-Server. Dies ist in den meisten Fällen ausreichend.

Eigene DERP Server einrichten (optional)

# /etc/headscale/config.yaml

derp:
  server:
    enabled: true
    region_id: 999
    region_code: "custom"
    stun_listen_addr: "0.0.0.0:3478"
  urls:
    - https://controlplane.tailscale.com/derpmap/default
    - file:///etc/headscale/derp.json  # Custom DERP

Headscale CLI Befehle

Befehl	Beschreibung
headscale users create NAME	Neuen Benutzer erstellen
headscale users list	Alle Benutzer auflisten
headscale preauthkeys create	Authentifizierungsschlüssel generieren
headscale nodes list	Verbundene Geräte auflisten
headscale nodes delete ID	Gerät löschen/abmelden
headscale routes list	Verfügbare Routen anzeigen

Troubleshooting

Clients können sich nicht verbinden

Überprüfen Sie:

Server URL ist korrekt in config.yaml
HTTPS Zertifikat ist gültig
Firewall erlaubt Verbindungen zu Port 443 und 50443
Headscale Service läuft: systemctl status headscale

Clients sehen sich gegenseitig nicht