Skip to content

Running headscale on Linux

Goal

This documentation has the goal of showing a user how-to set up and run headscale on Linux. In additional to the "get up and running section", there is an optional SystemD section describing how to make headscale run properly in a server environment.

Configure and run headscale

  1. Download the latest headscale binary from GitHub's release page:
wget --output-document=/usr/local/bin/headscale \
   https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
  1. Make headscale executable:
chmod +x /usr/local/bin/headscale
  1. Prepare a directory to hold headscale configuration and the SQLite database:
# Directory for configuration

mkdir -p /etc/headscale

# Directory for Database, and other variable data (like certificates)
mkdir -p /var/lib/headscale
# or if you create a headscale user:
useradd \
    --create-home \
    --home-dir /var/lib/headscale/ \
    --system \
    --user-group \
    --shell /usr/bin/nologin \
    headscale
  1. Create an empty SQLite database:
touch /var/lib/headscale/db.sqlite
  1. Create a headscale configuration:
touch /etc/headscale/config.yaml

(Strongly Recommended) Download a copy of the [example configuration]config-example.yaml from the headscale repository.

  1. Start the headscale server:
headscale serve

This command will start headscale in the current terminal session.

To continue the tutorial, open a new terminal and let it run in the background. Alternatively use terminal emulators like tmux or screen.

To run headscale in the background, please follow the steps in the SystemD section before continuing.

  1. Verify headscale is running:

Verify headscale is available:

curl http://127.0.0.1:9090/metrics
  1. Create a user (tailnet):
headscale users create myfirstuser

Register a machine (normal login)

On a client machine, execute the tailscale login command:

tailscale up --login-server YOUR_HEADSCALE_URL

Register the machine:

headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY>

Register machine using a pre authenticated key

Generate a key using the command line:

headscale --user myfirstuser preauthkeys create --reusable --expiration 24h

This will return a pre-authenticated key that can be used to connect a node to headscale during the tailscale command:

tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>

Running headscale in the background with SystemD

This section demonstrates how to run headscale as a service in the background with SystemD. This should work on most modern Linux distributions.

  1. Create a SystemD service configuration at /etc/systemd/system/headscale.service containing:
[Unit]
Description=headscale controller
After=syslog.target
After=network.target

[Service]
Type=simple
User=headscale
Group=headscale
ExecStart=/usr/local/bin/headscale serve
Restart=always
RestartSec=5

# Optional security enhancements
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
WorkingDirectory=/var/lib/headscale
ReadWritePaths=/var/lib/headscale /var/run/headscale
AmbientCapabilities=CAP_NET_BIND_SERVICE
RuntimeDirectory=headscale

[Install]
WantedBy=multi-user.target

Note that when running as the headscale user ensure that, either you add your current user to the headscale group:

usermod -a -G headscale current_user

or run all headscale commands as the headscale user:

su - headscale
  1. In /etc/headscale/config.yaml, override the default headscale unix socket with path that is writable by the headscale user or group:
unix_socket: /var/run/headscale/headscale.sock
  1. Reload SystemD to load the new configuration file:
systemctl daemon-reload
  1. Enable and start the new headscale service:
systemctl enable --now headscale
  1. Verify the headscale service:
systemctl status headscale

Verify headscale is available:

curl http://127.0.0.1:9090/metrics

headscale will now run in the background and start at boot.