Skip to content

Running headscale on Linux

Outdated and advanced

This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not want to use this documentation and rather look at the distro specific documentation.

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>

  2. Make headscale executable:

    chmod +x /usr/local/bin/headscale

  3. 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/sbin/nologin \
  headscale

  4. Create a headscale configuration:

    touch /etc/headscale/config.yaml

    (Strongly Recommended) Download a copy of the example configuration from the headscale repository.

  5. 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.

  6. Verify headscale is running: Verify headscale is available:

    curl http://127.0.0.1:9090/metrics

  7. 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 nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>

Register machine using a pre authenticated key

Generate a key using the command line:

headscale preauthkeys create --user myfirstuser --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. Copy headscale's systemd service file to /etc/systemd/system/headscale.service and adjust it to suit your local setup. The following parameters likely need to be modified: ExecStart, WorkingDirectory, ReadWritePaths.

    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

  2. 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

  3. Reload systemd to load the new configuration file:

    systemctl daemon-reload

  4. Enable and start the new headscale service:

    systemctl enable --now headscale

  5. 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.