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/lib/headscale/db.sqlite) and the configuration (/etc/headscale/config.yaml).

Installation

Download the latest Headscale package for your platform (.deb for Ubuntu and Debian).

HEADSCALE_VERSION="" # See above URL for latest version, e.g. "X.Y.Z" (NOTE: do not add the "v" prefix!)
# Or you can use the following bash one liner
# HEADSCALE_VERSION="$(curl -v https://github.com/juanfont/headscale/releases/latest 2>&1 |grep location | awk -F'/' '{print $NF}' | sed -e 's/v//' | |tr -d '\r')"
HEADSCALE_ARCH="" # Your system architecture, e.g. "amd64"
# Or you can use:
# HEADSCALE_ARCH="$(dpkg --print-architecture)"
wget --output-document=headscale.deb \
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"

Install Headscale:
```
sudo apt 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>

Sample config.yml

A sane config.yml might look like this

---

# Remember to punch a hole in your firewall for this port
server_url: https://headscale.example.com:28000

listen_addr: 0.0.0.0:28000

metrics_listen_addr: 127.0.0.1:9090

grpc_listen_addr: 127.0.0.1:50443

grpc_allow_insecure: false

private_key_path: /var/lib/headscale/private.key

noise:
  private_key_path: /var/lib/headscale/noise_private.key

ip_prefixes:
  - fd7a:115c:a1e0::/48
  - 100.64.0.0/10

derp:
  server:
    enabled: false

    region_id: 999

    region_code: "headscale"
    region_name: "Headscale Embedded DERP"

    stun_listen_addr: "0.0.0.0:3478"

  urls:
    - https://controlplane.tailscale.com/derpmap/default

  paths: []

  auto_update_enabled: true

  update_frequency: 24h

disable_check_updates: false

ephemeral_node_inactivity_timeout: 30m

node_update_check_interval: 10s

db_type: sqlite3

db_path: /var/lib/headscale/db.sqlite



acme_url: https://acme-v02.api.letsencrypt.org/directory

acme_email: "contact@example.com"


tls_letsencrypt_cache_dir: /var/lib/headscale/cache

tls_letsencrypt_challenge_type: HTTP-01
tls_letsencrypt_listen: ":http"

# Provisioned via certbot
tls_cert_path: "/etc/letsencrypt/live/headscale.example.com/fullchain.pem"
tls_key_path: "/etc/letsencrypt/live/headscale.example.com/privkey.pem"

log:
  format: text
  level: info

acl_policy_path: ""

dns_config:
  override_local_dns: true

  nameservers:
    - 9.9.9.9
    - 1.1.1.1



  domains: []


  magic_dns: true

  base_domain: example.com

unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"

logtail:
  enabled: false

randomize_client_port: false

4.2 KiB Raw Blame History