Running headscale on OpenBSD¶
Community documentation
This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale
developers.
It might be outdated and it might miss necessary steps.
Goal¶
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 headscale
¶
- 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 pkg_add headscale
.
- 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 headscale
¶
- Prepare a directory to hold
headscale
configuration 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
- Create an empty SQLite database:
- Create a
headscale
configuration:
(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.
To run headscale
in the background, please follow the steps in the rc.d section before continuing.
- Verify
headscale
is running:
Verify 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 tailscale
command:
Running 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/headscale
containing:
#!/bin/ksh
daemon="/usr/local/sbin/headscale"
daemon_logger="daemon.info"
daemon_user="root"
daemon_flags="serve"
daemon_timeout=60
. /etc/rc.d/rc.subr
rc_bg=YES
rc_reload=NO
rc_cmd $1
/etc/rc.d/headscale
needs execute permission:
- Start
headscale
service:
- Make
headscale
service start at boot:
- Verify the headscale service:
Verify headscale
is available:
headscale
will now run in the background and start at boot.