From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Headscale is a WireGuard-powered, self-hosted implementation of the Tailscale control server.



Ensure the Linux kernel has support for {{Link|WireGuard|section=#Kernel}.

USE flags

Headscale does not include any USE flags.


root #emerge --ask net-vpn/headscale


Headscale will need configuration before it can be used in production.


  • /etc/headscale/config.yaml - Headscale will search the /etc/headscale directory for a config.yaml or config.json file. The configuration file will need to be created from the example file provided in the installation (see below).
  • /etc/conf.d/headscale - OpenRC's service configuration file.
  • /var/lib/headscale - Directory containing keys that are automatically generated with the service runs.

Create the example configuration file:

root #bzcat /usr/share/doc/headscale-*/config-example.yaml.bz2 > /etc/headscale/config.yaml

Edit the configuration file as appropriate for the network situation in which Headscale will be deployed.

Test the configuration file for any changes:

root #headscale configtest

If no output is displayed, no configuration errors have been detected.


Create accounts

Follow upstream's documentation to create user accounts on the Headscale server.

When using the commandline interface, ensure commands are ran as the headscale user:

root #doas -u headscale headscale users create larry

Generate a new private key

Generate a new private keys for the control server and fix permissions:

root #headscale generate private-key > /var/lib/headscale/private.key
root #chown headscale:headscale /var/lib/headscale/private.key
root #chmod 600 /var/lib/headscale/private.key


The headscale service will be running on the server using one of the service managers listed below.


To start to the headscale service now:

root #openrc-service headscale start

To add the service to start on system boot:

root #rc-update add headscale default


To start and enable the service to start on boot:

root #systemctl enable --now headscale

Connecting to the control service

By default, the control server is accessible via Unix socket at /var/run/headscale/headscale.sock

Reverse proxy

Follow upstream's instructions when creating a reverse proxy.


Issue 1

When X happens, Y is how to fix it.


File clean up

Ensure any sensitive configuration files have been removed from the /etc directory:

root #rm /etc/headscale/*


root #emerge --ask --depclean --verbose net-vpn/headscale

See also

  • WireGuard — a modern, simple, and secure VPN that utilizes state-of-the-art cryptography.