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).
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
- Download the latest
headscalebinary from GitHub's release page:
- Prepare a directory to hold
headscaleconfiguration 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/bin/nologin \ headscale
- Create an empty SQLite database:
- Create a
(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.
headscale in the background, please follow the steps in the SystemD section before continuing.
headscale 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
headscale in the background with SystemD¶
Deprecated: This part is very outdated and you should use the [pre-packaged Headscale for this](./running-headscale-linux.md
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
[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:
/etc/headscale/config.yaml, override the default
headscaleunix socket with path that is writable by the
headscaleuser or group:
- Reload SystemD to load the new configuration file:
- Enable and start the new
- Verify the headscale service:
headscale is available:
headscale will now run in the background and start at boot.