headscale.md

Headscale

Headscale is an open source, self-hosted implementation of the Tailscale control server.

Dependencies

This service requires the following other services:

• a Traefik reverse-proxy server

Configuration

To enable this service, add the following configuration to your vars.yml file and re-run the installation process:

########################################################################
#                                                                      #
# headscale                                                            #
#                                                                      #
########################################################################

headscale_enabled: true

headscale_hostname: headscale.example.com

########################################################################
#                                                                      #
# /headscale                                                           #
#                                                                      #
########################################################################

URL

In the example configuration above, we configure the service to be hosted at https://headscale.example.com.

The headscale_path_prefix variable can be adjusted to host Headscale under a subpath (e.g. headscale_path_prefix: /headscale) on the given hostname.

Usage

After installation, you would normally:

• first, create some users
• then, connect some devices by the official Tailscale applications, configured to talk to your own Headscale server

Convenience script to call the binary

We provide a /mash/headscale/bin/headscale script on the server, which forwards commands to the headscale binary inside the container (mash-headscale).

Example usage: /mash/headscale/bin/headscale version

Warning

Command arguments which contain spaces may not be forwarded correctly.

Creating users

To create a user, run a command like this:

/usr/bin/env docker exec -it mash-headscale \
headscale users create \
john.doe \
--display-name "John Doe" \
--email "[email protected]"

Warning

We use docker exec here because the convenience script does not handle forwarding arguments with spaces (like --display-name) correctly.

💡 You can list the existing users with a command like this: /mash/headscale/bin/headscale users list

Connecting devices

Here are some quick guides for the various platforms:

• Android devices
• Apple devices
• Windows devices
• Linux: install the tailscale CLI. See the official Setting up Tailscale on Linux documentation, or the Archlinux Tailscale Wiki page (and specifically its Third-party clients section for GUI clients).

All of these platforms would require confirmation after initial login, so consult the Connecting Linux devices with manual confirmation section below for details on how to do it.

Connecting Linux devices with manual confirmation

To connect a Linux device, you can use a tailscale up command like this:

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

💡 You may wish to add additional arguments to this command, such as --hostname, --advertise-exit-node, --advertise-routes, etc. These settings can also be configured later using tailscale set (e.g. tailscale set --hostname=custom-hostname-for-my-device).

Running the tailscale up command will print a URL you need to open in your browser to complete the setup.

The URL would contain a headscale command you need to run. It looks something like this:

headscale nodes register --user USERNAME --key mkey:....

Take this command and:

• replace the headscale prefix with /mash/headscale/bin/headscale
• replace USERNAME with the username of a valid user you created earlier
• run it on the Headscale server

Connecting Linux devices with a preshared key

Instead of following the manual back-and-forth flow as specified in Connecting Linux devices with manual confirmation, you can also use a preshared key to connect your device.

First, generate a preshared key:

/mash/headscale/bin/headscale preauthkeys create --user=john.doe

You can then connect your device with the preshared key:

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

The device will be automatically connected to the Headscale server, without any additional approval steps.