Skip to content

Getting started

This page helps you get started with headscale and provides a few usage examples for the headscale command line tool headscale.

Prerequisites

Getting help

The headscale command line tool provides built-in help. To show available commands along with their arguments and options, run:

# Show help
headscale help

# Show help for a specific command
headscale <COMMAND> --help

# Show help
docker exec -it headscale \
  headscale help

# Show help for a specific command
docker exec -it headscale \
  headscale <COMMAND> --help

Manage headscale from another local user

By default only the user headscale or root will have the necessary permissions to access the unix socket (/var/run/headscale/headscale.sock) that is used to communicate with the service. In order to be able to communicate with the headscale service you have to make sure the unix socket is accessible by the user that runs the commands. In general you can achieve this by any of the following methods:

  • using sudo
  • run the commands as user headscale
  • add your user to the headscale group

To verify you can run the following command using your preferred method:

headscale users list

Manage headscale users

In headscale, a node (also known as machine or device) is always assigned to a headscale user. Such a headscale user may have many nodes assigned to them and can be managed with the headscale users command. Invoke the built-in help for more information: headscale users --help.

Create a headscale user

headscale users create <USER>

docker exec -it headscale \
  headscale users create <USER>

List existing headscale users

headscale users list

docker exec -it headscale \
  headscale users list

Register a node

One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect Android, Apple or Windows devices.

Normal, interactive login

On a client machine, run the tailscale up command and provide the FQDN of your headscale instance as argument:

tailscale up --login-server <YOUR_HEADSCALE_URL>

Usually, a browser window with further instructions is opened and contains the value for <YOUR_MACHINE_KEY>. Approve and register the node on your headscale server:

headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>

docker exec -it headscale \
  headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>

Using a preauthkey

It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see headscale preauthkeys --help for other options):

headscale preauthkeys create --user <USER_ID>

docker exec -it headscale \
  headscale preauthkeys create --user <USER_ID>

The command returns the preauthkey on success which is used to connect a node to the headscale instance via the tailscale up command:

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