Headscale
Headscale setup
Decent guides and docs for setting up headscale:
- https://earvingad.github.io/posts/headscale/
- https://docs.techdox.nz/headscale/#sample-configyaml
- https://headscale.net/setup/install/container/#configure-and-run-headscale
- Ansible Documentation: https://codeberg.org/ansible/headscale/src/branch/main/README.md
If you’re interesting in having DNS names instead of IPs, you can setup a duckdns subdomain using a random uuid as the subdomain name. Alternatively, buy a cheap domain name on Cloudflare (or equivalent) and setup DNS records for your VPN.
User creation
https://docs.techdox.nz/headscale/#post-deployment-configuration
The following commands work if you’ve setup headscale using the docker deployment method:
# [on your main node] create a new user and registration key
# create new user or use the infra user if its for infra
docker exec headscale headscale users create infra
# create a registration key for the user
docker exec -it headscale headscale preauthkeys create --user infra --reusable --expiration 24h
# ----
# [on your new node/device] install tailscale client and register your device
# installing tailscale client on the device (physical, server, etc)
# simplest way but less secure
curl -fsSL https://tailscale.com/install.sh | sh
# use the key to register from the new node
tailscale up --login-server https://<your-sub-name>.duckdns.org:<port>/ --authkey <the previously generated auth key>Commands
# list tailscale peers
tailscale status --peers
# list tailscale nodes from control server
docker exec -it headscale headscale nodes list
# rename / change hostname of node from headscale server
docker exec -it headscale headscale nodes rename cutenode -i 5
# changing the hostname of a node directly (should work but didn't work from the node for me - might need special config)
tailscale up --hostname=anonaddy --login-server=https://<your-sub-name>.duckdns.org:<port>/
### removing a node from the network
# find the node you want to delete
docker exec headscale headscale node list
# expire (logout) the node
docker exec headscale headscale node expire -i 5
# remove the node from the network (--force to remove prompting)
docker exec headscale headscale node delete -i 5 --force
# check that the node has been removed
docker exec headscale headscale node listCommon caveats
TLS Cert issues
If TLS cert expires or isn’t registered yet, you may need to open port 80 during TLS configuration/renewal. Alternatively, use a self-signed certificate.
Magic DNS Issues
Magic DNS can cause issues with local DNS resolvers and what not. I’ve seen it reply for things it shouldn’t have including live public domains. (Try it when doing even light DNS bruteforcing and you’ll soon release something’s not right). Highly recommend disabling if you have workers doing lots of DNS requests:
You can use the following to disable it from a client:
# disable on a client
sudo tailscale up --accept-dns=false --login-server=https://<your-sub-name>.duckdns.org:<port>/It can also be disabled on the headscale server directly via configuration changes.