Headscale zelf hosten op een dedicated server: stap voor stap

Eerst het antwoord: wat je bouwt

Eén kleine server met Headscale (de open source-implementatie van de coordinatieserver van Tailscale), met de officiële Tailscale-apps op elk apparaat die daarnaar wijzen in plaats van naar de cloud van Tailscale. Dezelfde WireGuard-mesh, dezelfde clients, dezelfde NAT-traversal; de control plane (sleutels, peerlijsten, ACL's) draait op jouw hardware, zonder kosten per gebruiker. De opzet duurt ruwweg een half uur en vraagt om:

• Een kleine always-on Linux-machine met een publiek IP: de footprint van Headscale is minimaal; elke bescheiden server of VPS-slice is ruim voldoende.
• Een DNS-naam die ernaar wijst (headscale.example.com, vervang die overal door je eigen naam).
• Poorten: 443 (of de poort die je zelf kiest) voor clients; 80 als je de standaard Let's Encrypt-flow gebruikt; 3478/udp als je de ingebouwde relay inschakelt.

Het is de moeite waard om te herhalen uit onze vergelijking van mesh-VPN's (waar deze optie de plek "Tailscale-UX, self-hosted controle" won): Headscale is bewust beperkt tot een enkel tailnet, één netwerk, één team of organisatie. Het is het self-host-antwoord voor persoonlijke infrastructuur en kleine organisaties, geen multi-tenant kloon van Tailscale voor bedrijven. Op die schaal is het uitstekend.

Stap 1: installeren

Het aanbevolen pad van het project is de officiële .deb-packages (Ubuntu 22.04+/Debian 12+), die de headscale-gebruiker, het configuratieskelet en de systemd-unit voor je klaarzetten. Haal de actuele release op (v0.29.x op het moment van schrijven, check de releases):

wget https://github.com/juanfont/headscale/releases/download/v0.29.2/headscale_0.29.2_linux_amd64.deb
apt install ./headscale_0.29.2_linux_amd64.deb

(Er bestaan Docker-images, maar het project ondersteunt Docker-deployment expliciet niet officieel; op je eigen server is het package zowel eenvoudiger als het ondersteunde pad.)

Stap 2: configureren

Alles staat in /etc/headscale/config.yaml. De minimale werkende delta ten opzichte van het meegeleverde voorbeeld:

server_url: https://headscale.example.com:443
listen_addr: 0.0.0.0:443

# TLS, the simple way: built-in Let's Encrypt
tls_letsencrypt_hostname: headscale.example.com

Drie beslissingen die het waard zijn om bewust te nemen:

• TLS: de ingebouwde Let's Encrypt-integratie is de optie met de minste bewegende delen. De standaard HTTP-01-challenge vereist dat poort 80 bereikbaar is; TLS-ALPN-01 valideert als alternatief rechtstreeks op 443. Een reverse proxy (nginx/Caddy) ervoor werkt ook en komt vaak voor, maar let op de eerlijke kanttekening in de docs dat de reverse-proxy-instructies door de community worden onderhouden, dat WebSocket-upgrades geconfigureerd moeten worden, en dat proxyen via Cloudflare expliciet niet wordt ondersteund. Minder lagen, minder verrassingen: directe TLS is hier de aanbeveling.
• Database: SQLite is de standaard en op deze schaal het juiste antwoord, één bestand op /var/lib/headscale/db.sqlite.
• DNS: de sectie dns: geeft je mesh MagicDNS-namen (in de stijl van base_domain: ts.example.com); stel dit nu in, want later hernoemen is vervelend.

Daarna:

systemctl enable --now headscale
headscale users create jesse

Stap 3: clients verbinden

Installeer op elk apparaat de normale Tailscale-app en wijs die naar je server:

tailscale up --login-server https://headscale.example.com

Het commando toont een URL; als je die bezoekt krijg je de node-key, die je server-side goedkeurt (headscale nodes register --user jesse --key <key>). Voor onbeheerde machines (servers die tot de mesh toetreden) sla je de interactieve stap over met een pre-auth key:

headscale preauthkeys create --user jesse --expiration 1h
tailscale up --login-server https://headscale.example.com --authkey <key>

Headscale ondersteunt de laatste tien Tailscale-clientreleases op Linux, Windows, macOS, iOS en Android (mobiele en desktopplatforms hebben een kleine extra stap nodig om een custom server in te stellen; de docs behandelen elk platform, en je server serveert zelfs hulppagina's op /windows en /apple). Zodra twee apparaten verbonden zijn, draai je tailscale status en ping je ertussen: je hebt een mesh.

Voor SSO in plaats van CLI-gebruikersbeheer is de OIDC-ondersteuning van Headscale solide: wijs naar Authentik, Keycloak, Entra ID of Google (schakel PKCE in, zoals de docs aanbevelen) en apparaatregistratie wordt een browser-login.

Stap 4: ACL's

Standaard bereikt elke node elke node, prima voor één persoon, niet voor een netwerk met servers van verschillende gevoeligheid. Policy is een HuJSON-bestand (JSON met comments), hetzelfde formaat als bij Tailscale:

// /etc/headscale/policy.hujson
{
  "tagOwners": { "tag:server": ["jesse@"] },
  "acls": [
    // everyone reaches web things on servers
    { "action": "accept", "src": ["*"], "dst": ["tag:server:80,443"] },
    // only jesse reaches SSH anywhere
    { "action": "accept", "src": ["jesse@"], "dst": ["*:22"] }
  ]
}

Verwijs ernaar via policy.path in de config en herlaad de service om wijzigingen door te voeren. Kanttekeningen bij de huidige staat van het project: de policy-engine is v2 (groups, tags, autogroups zoals autogroup:internet voor exit-node-besturing), de nieuwere grants-syntax is de richting waar het project heen gaat, en één eerlijk gat: OIDC-groups kunnen nog niet in policyregels gebruikt worden. Default-deny-denken geldt hier precies als bij elke firewall: schrijf de accepts die je bedoelt, niets anders.

Stap 5: je eigen DERP-relay (optioneel, de moeite waard)

Wanneer twee peers geen directe verbinding kunnen opzetten (harde NAT aan beide kanten, UDP geblokkeerd), valt het verkeer terug op een DERP-relay. Standaard is dat de publieke relay-fleet van Tailscale: functioneel, maar het enige moment waarop jouw self-hosted mesh stilzwijgend op andermans infrastructuur leunt, tegen de latency van welke node van hen dan ook het dichtstbij ligt. Headscale heeft een ingebouwde DERP-server; door die in te schakelen blijft gerelayd verkeer op je eigen machine:

derp:
  server:
    enabled: true
    stun_listen_addr: "0.0.0.0:3478"

Open 3478/udp rechtstreeks naar de server (STUN kan niet via een reverse proxy). De pakketten die via de relay lopen, zijn nog steeds end-to-end WireGuard-versleuteld (DERP stuurt alleen ciphertext door; het kan niets lezen), dus de winst hier zit in latency en zelfredzaamheid, niet in vertrouwelijkheid. Op een netwerk met goede peering is het verschil merkbaar: je worst-case pad is dan een sprong via je eigen server met lage latency, in plaats van een omweg via een verre publieke relay.

Headscale beheren

• Back-ups: de volledige staat bestaat uit drie dingen: /var/lib/headscale/ (database + noise key), /etc/headscale/ (config + policy). Maak er een snapshot of file-backup van; herstellen op een verse machine is kopiëren en starten.
• Upgrades: lees de changelog (het project is eerlijk over breaking changes: v0.26 verving de policy-engine; v0.29 wijzigde de wildcard-semantiek), installeer dan de nieuwe .deb en herstart. Clients verbinden automatisch opnieuw.
• Resources: het project publiceert geen sizing-cijfers en hoeft dat ook niet; het coördineert probleemloos honderden apparaten op minimale hardware. De ene schaal-opmerking van de maintainers: de kosten zitten in CPU-gebonden herberekening van de map wanneer de topologie verandert, dus het is het aantal en de wisseling van verbindingen dat telt, niet het verkeer; data stroomt peer-to-peer en nooit via de coordinatieserver (behalve DERP-fallback, hierboven).
• Zichtbaarheid: er is bewust geen meegeleverde web-UI; de CLI dekt het beheer, en third-party UI's (headscale-admin, Headplane en dergelijke) bestaan als community-projecten; behandel ze ook zo, en let op dat sommige de policy in database-modus vereisen.

De eerlijke beperkingen

Kies Headscale met de ogen open voor wat het niet is. Eén tailnet: geen multi-tenancy, by design en volgens de FAQ. Community-run: het is een onafhankelijke open source-herimplementatie (historisch met een Tailscale-medewerker die in persoonlijke hoedanigheid bijdroeg), geen vendor-product met een SLA; nieuwe Tailscale-features komen pas als ze opnieuw zijn geïmplementeerd, niet op launch day. Jij bent de beheerder: TLS-vernieuwingen, upgrades, back-ups en de pager om 3 uur 's nachts zijn voor jouw rekening. Lees je die trade-offs als kosten in plaats van als het hele punt, dan is Tailscale's gratis hosted tier (of NetBird, volgens onze vergelijking) het beter passende gereedschap. Lees je ze als soevereiniteit, ga dan door; dit is een van de meest lonende self-host-projecten die er zijn: hoog nut, minimaal operationeel oppervlak.

Veelgestelde vragen

Is Headscale klaar voor productiegebruik?

Voor het beoogde toepassingsgebied (het tailnet van één organisatie, beheerd door iemand die comfortabel met één Linux-service overweg kan) ja: het project is volwassen, wordt actief uitgebracht en wordt precies daarvoor breed ingezet. De kanttekeningen gaan over scope, niet over kwaliteit: geen multi-tenancy, geen vendor-supportcontract, en af en toe breaking changes tussen minor versies, wat een beheerder verwacht die de changelogs leest. Zet het in voor een vloot van je eigen servers en apparaten en het is solide; rek het op richting "product voor klanten" en je zit buiten het ontwerp.

Waarom verbinden mijn apparaten wel, maar loopt het verkeer traag via de server?

Ze zijn teruggevallen op DERP-relaying, meestal te zien in tailscale status als een relay-tag in plaats van een direct adres. Directe WireGuard-paden raken je Headscale-server nooit, dus "alles loopt via de server" betekent dat NAT-traversal is mislukt (harde NAT, geblokkeerde UDP) en dat pakketten via de relay rijden. Oplossingen in volgorde: zorg dat UDP aan geen van beide kanten geblokkeerd is, schakel de ingebouwde DERP in (zodat de fallback in elk geval jouw snelle relay is), en controleer bij permanent gerelayde paren of één kant een directe poort open kan krijgen; een dedicated server met open UDP is een ideale, altijd-directe ankernode.

Kan ik mijn mesh gebruiken om bij het private/management-netwerk van mijn servers te komen?

Ja. Dit is precies het beheerdersscenario dat het vergelijkingsartikel uitlichtte. Draai één node binnen het private segment als subnet-router (tailscale up --advertise-routes=10.0.0.0/24 ..., goedkeuren met headscale nodes approve-routes), en geautoriseerde mesh-leden bereiken het hele segment (IPMI, interne services) zonder dat iets daarvan een publieke listener heeft. Zet de route achter een strakke ACL en behandel de subnet-router-node met bastion-grade zorg; die is nu de brug naar je meest gevoelige netwerk.

Hoe verhoudt dit zich tot gewoon WireGuard draaien?

Headscale is onder de motorkap WireGuard; wat je toevoegt is de control plane: automatische sleuteldistributie, NAT-traversal, MagicDNS, ACL's en mobiele apps die niet-experts kunnen gebruiken. Voor twee statische servers blijft kaal WireGuard eenvoudiger. Het omslagpunt komt met roamende apparaten, groeiende aantallen peers, of mensen die een app met een schakelaar verdienen; op dat moment levert Headscale de productervaring, met behoud van de eigenschap van kaal WireGuard die er echt toe deed: de infrastructuur van niemand anders in je control path.

Uitrollen op Serverside

Een Headscale-host wil precies wat een kleine dedicated server of cloud-instance hier levert: een always-on machine met een stabiel publiek IP op een goed gepeerd netwerk (ASN 55285, waar je ingebouwde DERP-relay zijn latency-voordeel ook echt waarmaakt) achter always-on DDoS-mitigatie, want de ene publieke listener van je coordinatieserver verdient bescherming. Grotere meshes die subnet-routers naar private netwerken verankeren, passen van nature bij de dedicated lijn.

Aansluitend leesvoer: de mesh-VPN-beslissing die deze gids uitwerkt, firewallregels voor de host eronder, en de hardeningschecklist om te doorlopen voordat je hier iets van doet.