User:Maffblaster/Drafts/Headscale

This article is a stub. Please help out by expanding it - how to get started.

Resources

Home

GitHub

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

Installation

Kernel

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

USE flags

Headscale does not include any USE flags.

Emerge

root #emerge --ask net-vpn/headscale

Configuration

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

Files

• /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.

Usage

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

Service

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

OpenRC

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

systemd

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.

Troubleshooting

Issue 1

When X happens, Y is how to fix it.

Removal

File clean up

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

root #rm /etc/headscale/*

Unmerge

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

See also

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