Headscale

• Website
• GitHub Open source control server software
• Docs
  • ACLs use case example
  • Setting custom DNS records
• Helm charts
  • gabe565 chart Artifacthub
  • gabe565 chart GitHub
• Container images
• FR: Support for WireGuard only peers

Setup

If Headscale is installed in Kubernetes, configure a shell alias:

alias headscale="kubectl -n headscale exec -it deployment/headscale -c headscale -- headscale"

If the Headscale user varac doesn't exist yet, create it (only once):

headscale user create --display-name varac --email <email adr> varac
headscale user list

Register new node

Request node registration from a device:

sudo tailscale login --login-server https://$HEADSCALE_DOMAIN

Then follow the link from the browser to register the node in headscale:

headscale nodes register --user varac --key nodekey:$NODEKEY

Using a pre-auth key (deprecated)

Generate a preauth-key:

headscale --user $NODEUSER preauthkeys create --reusable --expiration 360d

Login using a preauth-key:

sudo tailscale up --login-server https://$HEADSCALE_DOMAIN \
  --authkey $(gopass show --password token/$HEADSCALE_DOMAIN/preauth-key/varac)

Ansible role

• artis3n-tailscale
• State file on each machine: ~/.local/state/artis3n-tailscale

Bootstrap new machine

Getting started: Using a preauthkey

Before configuring a device, ensure the user varac is created (see above).

Create a preauthent key:

headscale --user varac preauthkeys create --reusable --expiration 3y

Or create a preauthkey using a tag:

headscale --user varac preauthkeys create --reusable --expiration 3y --tags tag:oas2

Then store token in Vaultwarden (token/hs.k.varac.net/varac/preauth-key/ANSIBLE_INVENTORY_HOSTNAME), add the device to the vpn inventory group and run ansible:

ansible-playbook -l zancas -t tailscale site.yml

Finally, accept the additional routes in the headscale UI.