License¶
Headscale is released under the BSD-3-Clause License.
All relevant legal information can be found in the LICENSE file in the repository of the project.
Prerequisites¶
If you want to use Headscale with your own domain you need to add it first.
Installation¶
Download the latest Headscale binary from the official GitHub releases page. Replace 0.29.7 with the latest version:
[isabell@stardust ~]$ wget -O ~/bin/headscale \
https://github.com/juanfont/headscale/releases/download/v0.29.7/headscale_0.29.7_linux_amd64
[isabell@stardust ~]$ chmod +x ~/bin/headscale
By default, Headscale loads the configuration from $HOME/.headscale/config.yaml, so we continue with creating the directory:
[isabell@stardust ~]$ mkdir -p ~/.headscale
Then download the example configuration file:
[isabell@stardust ~]$ wget -O ~/.headscale/config.yaml \
https://github.com/juanfont/headscale/raw/v0.29.7/config-example.yaml
Configuration¶
Configure Headscale for the Uberspace web backend¶
Edit ~/.headscale/config.yaml and adjust the following values. Replace isabell with your username and isabell.uber.space with your domain.
Warning
Review the rest of the configuration and adjust it to suit your environment. At minimum, set server_url, listen_addr, private_key_path, unix_socket, and database.sqlite.
Note
Uberspace's web backend handles HTTPS. Leave tls_cert_path and tls_key_path empty in the Headscale configuration. See Headscale's TLS documentation for more information.
For a minimal setup, set these values:
server_url: "https://isabell.uber.space:443"
listen_addr: "0.0.0.0:8080"
tls_cert_path: ""
tls_key_path: ""
unix_socket: "/home/isabell/.headscale/headscale.sock"
noise:
private_key_path: "private.key"
database:
type: sqlite
sqlite:
path: "db.sqlite"
Generate a private key for WireGuard:
[isabell@moondust ~]$ headscale generate private-key > ~/.headscale/private.key
Note
For further configuration options, see Headscale's configuration documentation.
Validate the configuration:
[isabell@moondust ~]$ headscale configtest
If the command reports no errors, test the daemon by running headscale serve in a terminal. Stop it with Ctrl+C after confirming that it starts without errors.
Set up the service¶
Create and start a systemd service for Headscale:
[isabell@moondust ~]$ uberspace service add headscale "$HOME/bin/headscale serve" --workdir "$HOME/.headscale"
Check the service status and logs if it does not start:
[isabell@moondust ~]$ systemctl --user status headscale
[isabell@moondust ~]$ journalctl --user -u headscale
Configure the Uberspace web backend¶
Connect the web backend to the running Headscale service on port 8080:
[isabell@moondust ~]$ uberspace web backend add isabell.uber.space port 8080
The Uberspace web backend handles HTTPS and proxies requests, including WebSockets, to Headscale.
Usage¶
Once Headscale is running, create a user:
[isabell@moondust ~]$ headscale users create <USER>
Create a preauth key for device registration. Get the <USER-ID> with headscale users list:
[isabell@moondust ~]$ headscale preauthkeys create --user <USER-ID>
Install the Tailscale client on your device, then use the preauth key there:
[localuser@localhost ~]$ tailscale up --login-server https://isabell.uber.space --authkey <PREAUTHKEY>
For more commands, run headscale help or see the official documentation.
Updates¶
Note
Check the release page regularly.
Follow Headscale's upgrade instructions, including release-specific configuration changes, and do not skip minor versions. Stop the service and back up its configuration, keys and database before replacing the running binary:
[isabell@moondust ~]$ systemctl --user stop headscale
[isabell@moondust ~]$ cp -a ~/.headscale ~/.headscale.backup-$(date +%Y%m%d%H%M%S)
Download the new binary using the installation command above, validate the configuration, then start the service:
[isabell@moondust ~]$ headscale configtest
[isabell@moondust ~]$ systemctl --user start headscale