Running headscale on Linux

Requirements

Ubuntu 20.04 or newer, Debian 11 or newer.

Goal

Get Headscale up and running.

This includes running Headscale with SystemD.

Migrating from manual install

If you are migrating from the old manual install, the best thing would be to remove the files installed by following the guide in reverse.

You should not delete the database (/var/headscale/db.sqlite) and the configuration (/etc/headscale/config.yaml).

Installation

Download the lastest Headscale package for your platform (.deb for Ubuntu and Debian) from Headscale's releases page:

wget --output-document=headscale.deb \
  https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>.deb

Install Headscale:

sudo dpkg --install headscale.deb

Enable Headscale service, this will start Headscale at boot:

sudo systemctl enable headscale

Configure Headscale by editing the configuration file:

nano /etc/headscale/config.yaml

Start Headscale:

sudo systemctl start headscale

Check that Headscale is running as intended:

systemctl status headscale

Using Headscale

Create a user

headscale users create myfirstuser

On a client machine, run the tailscale login command:

tailscale up --login-server <YOUR_HEADSCALE_URL>

headscale --user myfirstuser nodes register --key <YOUR_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 is used to connect a node to headscale during the tailscale command:

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

2.0 KiB Raw Permalink Blame History