Running headscale on Linux¶
Note: 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 (TODO LINK)[].
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
¶
-
Download the latest
headscale
binary from GitHub's release page: -
Make
headscale
executable: -
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
-
Create an empty SQLite database:
-
Create a
headscale
configuration:(Strongly Recommended) Download a copy of the [example configuration]config-example.yaml from the headscale repository.
-
Start the headscale server:
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. -
Verify
headscale
is running: Verifyheadscale
is available: -
Create a user (tailnet):
Register a machine (normal login)¶
On a client machine, execute the tailscale
login command:
Register the machine:
Register machine using a pre authenticated key¶
Generate a key using the command line:
This will return a pre-authenticated key that can be used to connect a node to headscale
during the tailscale
command:
Running headscale
in the background with SystemD¶
Deprecated: This part is very outdated and you should use the pre-packaged Headscale for this
This section demonstrates how to run headscale
as a service in the background with SystemD. This should work on most modern Linux distributions.
-
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:
or run all headscale commands as the headscale user:
-
In
/etc/headscale/config.yaml
, override the defaultheadscale
unix socket with path that is writable by theheadscale
user or group: -
Reload SystemD to load the new configuration file:
-
Enable and start the new
headscale
service: -
Verify the headscale service:
Verify
headscale
is available:
headscale
will now run in the background and start at boot.