From 75a0155f738472f0106bf07118f3df3ebb50d038 Mon Sep 17 00:00:00 2001 From: Jiang Zhu Date: Sun, 5 Jun 2022 15:45:38 +0800 Subject: [PATCH] add openbsd doc --- docs/README.md | 1 + docs/running-headscale-openbsd.md | 197 ++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 docs/running-headscale-openbsd.md diff --git a/docs/README.md b/docs/README.md index 459a6c21..9f8e681a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,6 +27,7 @@ written by community members. It is _not_ verified by `headscale` developers. **It might be outdated and it might miss necessary steps**. - [Running headscale in a container](running-headscale-container.md) +- [Running headscale on OpenBSD](running-headscale-openbsd.md) ## Misc diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md new file mode 100644 index 00000000..9e035c76 --- /dev/null +++ b/docs/running-headscale-openbsd.md @@ -0,0 +1,197 @@ +# Running headscale on OpenBSD + +## 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](#running-headscale-in-the-background-with-rc.d) +describing how to make `headscale` run properly in a server environment. + +## Install `headscale` +1. Install from ports (Not Recommend) + + As of OpenBSD 7.1, there's a headscale in ports collection, however, it's severely outdated(v0.12.4). + You can install it via `pkg_add headscale`. + +2. Install from source on OpenBSD 7.1 + +``` shell +# Install prerequistes +# 1. go v1.18+: headscale newer than 0.15 needs go 1.18+ to compile +# 2. gmake: Makefile in the headscale repo is written in GNU make syntax +pkg_add -D snap go +pkg_add gmake + +git clone https://github.com/juanfont/headscale.git + +cd headscale + +# optionally checkout a release +git checkout v0.16.0-beta1 + +gmake build + +# 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 + +``` shell +# Install prerequistes +# 1. go v1.18+: headscale newer than 0.15 needs go 1.18+ 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 +git checkout v0.16.0-beta1 + +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 +``` + +2. Create an empty SQLite database: + +```shell +touch /var/lib/headscale/db.sqlite +``` + +3. Create a `headscale` configuration: + +```shell +touch /etc/headscale/config.yaml +``` + +It is **strongly recommended** to copy and modify the [example configuration](../config-example.yaml) +from the [headscale repository](../) + +4. 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). + +To run `headscale` in the background, please follow the steps in the [rc.d section](#running-headscale-in-the-background-with-rc.d) before continuing. + +5. Verify `headscale` is running: + +Verify `headscale` is available: + +```shell +curl http://127.0.0.1:9090/metrics +``` + +6. Create a namespace ([tailnet](https://tailscale.com/kb/1136/tailnet/)): + +```shell +headscale namespaces create myfirstnamespace +``` + +### Register a machine (normal login) + +On a client machine, execute the `tailscale` login command: + +```shell +tailscale up --login-server YOUR_HEADSCALE_URL +``` + +Register the machine: + +```shell +headscale --namespace myfirstnamespace nodes register --key +``` + +### Register machine using a pre authenticated key + +Generate a key using the command line: + +```shell +headscale --namespace myfirstnamespace preauthkeys create --reusable --expiration 24h +``` + +This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command: + +```shell +tailscale up --login-server --authkey +``` + +## Running `headscale` in the background with rc.d + +This section demonstrates how to run `headscale` as a service in the background with [rc.d](https://man.openbsd.org/rc.d). + +1. Create a rc.d service at `/etc/rc.d/headscale` containing: + +```shell +#!/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: + +```shell +chmod a+x /etc/rc.d/headscale +``` + +3. Start `headscale` service: + +```shell +rcctl start headscale +``` + +4. Make `headscale` service start at boot: + +```shell +rcctl enable headscale +``` + +5. Verify the headscale service: + +```shell +rcctl check headscale +``` + +Verify `headscale` is available: + +```shell +curl http://127.0.0.1:9090/metrics +``` + +`headscale` will now run in the background and start at boot.