Running headscale on OpenBSD¶

Goal¶

This documentation has the goal of showing a user how-to install and run headscale on OpenBSD. In addition 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¶

1. Install from ports

   You can install headscale from ports by running pkg_add headscale.

2. Install from source

   # Install prerequistes
   pkg_add go
   
   git clone https://github.com/juanfont/headscale.git
   
   cd headscale
   
   # optionally checkout a release
   # option a. you can find official release 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
   

3. 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 official release 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¶

1. 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
   

2. Create a headscale configuration:

   touch /etc/headscale/config.yaml
   

(Strongly Recommended) Download a copy of the example configuration from the headscale repository.

1. Start the headscale server:

   headscale serve
   

   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.

2. Verify headscale is running:

   Verify headscale is available:

   curl http://127.0.0.1:9090/metrics
   

3. Create a user (tailnet):

   headscale users create myfirstuser
   

Register a machine (normal login)¶

On a client machine, execute the tailscale login command:

tailscale up --login-server YOUR_HEADSCALE_URL

Register the machine:

headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>

Register machine using a pre authenticated key¶

Generate a key using the command line:

headscale preauthkeys create --user myfirstuser --reusable --expiration 24h

This will return a pre-authenticated key that can be used to connect a node to headscale during the tailscale command:

tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>

Running headscale in the background with rc.d¶

This section demonstrates how to run headscale as a service in the background with rc.d.

1. 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
   

2. /etc/rc.d/headscale needs execute permission:

   chmod a+x /etc/rc.d/headscale
   

3. Start headscale service:

   rcctl start headscale
   

4. Make headscale service start at boot:

   rcctl enable headscale
   

5. Verify the headscale service:

   rcctl check headscale
   

   Verify headscale is available:

   curl http://127.0.0.1:9090/metrics
   

   headscale will now run in the background and start at boot.