Running headscale on OpenBSD¶
This page is not actively maintained by the headscale authors and is written by community members. It is not verified by
It might be outdated and it might miss necessary steps.
This documentation has the goal of showing a user how-to install and run
headscale on OpenBSD 7.1. In additional to the "get up and running section", there is an optional rc.d section describing how to make
headscale run properly in a server environment.
- Install from ports (Not Recommend)
As of OpenBSD 7.2, there's a headscale in ports collection, however, it's severely outdated(v0.12.4). You can install it via
- Install from source on OpenBSD 7.2
# Install prerequistes pkg_add go git clone https://github.com/juanfont/headscale.git cd headscale # optionally checkout a release # option a. you can find offical relase at https://github.com/juanfont/headscale/releases/latest # option b. get latest tag, this may be a beta release latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) git checkout $latestTag go build -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$latestTag" github.com/juanfont/headscale # make it executable chmod a+x headscale # copy it to /usr/local/sbin cp headscale /usr/local/sbin
- Install from source via cross compile
# Install prerequistes # 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile # 2. gmake: Makefile in the headscale repo is written in GNU make syntax git clone https://github.com/juanfont/headscale.git cd headscale # optionally checkout a release # option a. you can find offical relase at https://github.com/juanfont/headscale/releases/latest # option b. get latest tag, this may be a beta release latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) git checkout $latestTag make build GOOS=openbsd # copy headscale to openbsd machine and put it in /usr/local/sbin
Configure and run
- Prepare a directory to hold
headscaleconfiguration and the SQLite database:
- 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.
To continue the tutorial, open a new terminal and let it run in the background. Alternatively use terminal emulators like tmux.
headscale in the background, please follow the steps in the rc.d 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 rc.d¶
This section demonstrates how to run
headscale as a service in the background with rc.d.
- Create a rc.d service at
/etc/rc.d/headscaleneeds execute permission:
headscaleservice start at boot:
- Verify the headscale service:
headscale is available:
headscale will now run in the background and start at boot.