# 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](#running-headscale-in-the-background-with-rcd)
describing how to make `headscale` run properly in a server environment.

## Install `headscale`

1. Install from source

    ```shell
    # 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
    ```

1. Install from source via cross compile

    ```shell
    # 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](https://www.sqlite.org/) database:

    ```shell
    # Directory for configuration

    mkdir -p /etc/headscale

    # Directory for database, and other variable data (like certificates)
    mkdir -p /var/lib/headscale
    ```

1. Create a `headscale` configuration:

    ```shell
    touch /etc/headscale/config.yaml
    ```

**(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.

1. Start the headscale server:

    ```shell
    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](https://github.com/tmux/tmux).

1. Verify `headscale` is running:

    Verify `headscale` is available:

    ```shell
    curl http://127.0.0.1:9090/metrics
    ```