juanfont.headscale/docs/running-headscale-openbsd.md

Running headscale on OpenBSD

!!! warning "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. 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 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
   

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

2. Verify headscale is running:

   Verify headscale is available:

   curl http://127.0.0.1:9090/metrics