From 75a0155f738472f0106bf07118f3df3ebb50d038 Mon Sep 17 00:00:00 2001 From: Jiang Zhu Date: Sun, 5 Jun 2022 15:45:38 +0800 Subject: [PATCH 1/5] 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. From 1de29fd4e66641fc512080db2ddee633336f6695 Mon Sep 17 00:00:00 2001 From: Jiang Zhu Date: Sun, 5 Jun 2022 15:49:24 +0800 Subject: [PATCH 2/5] fix rcd link --- docs/running-headscale-openbsd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index 9e035c76..7c25ed03 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -3,7 +3,7 @@ ## 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) +In additional 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` @@ -97,7 +97,7 @@ 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. +To run `headscale` in the background, please follow the steps in the [rc.d section](#running-headscale-in-the-background-with-rcd) before continuing. 5. Verify `headscale` is running: From c8a14ccabb241b7368ef044a44028cb165afaec6 Mon Sep 17 00:00:00 2001 From: Jiang Zhu Date: Sun, 5 Jun 2022 15:58:55 +0800 Subject: [PATCH 3/5] fix prettier --- docs/running-headscale-openbsd.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index 7c25ed03..9d4d3117 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -7,6 +7,7 @@ In additional to the "get up and running section", there is an optional [rc.d se 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). @@ -14,7 +15,7 @@ describing how to make `headscale` run properly in a server environment. 2. Install from source on OpenBSD 7.1 -``` shell +```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 @@ -39,7 +40,7 @@ cp headscale /usr/local/sbin 3. Install from source via cross compile -``` shell +```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 From 0b4b5308099e2140074a0fb1ae13889a645ee581 Mon Sep 17 00:00:00 2001 From: Jiang Zhu Date: Sat, 11 Jun 2022 16:41:52 +0800 Subject: [PATCH 4/5] remove the hardcoded version(suggested by @kradalby) --- docs/running-headscale-openbsd.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index 9d4d3117..6a307f91 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -27,7 +27,11 @@ git clone https://github.com/juanfont/headscale.git cd headscale # optionally checkout a release -git checkout v0.16.0-beta1 +# 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 relase +latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) + +git checkout $latestTag gmake build From 2be16b581c3857bcae2ca34f13e2b257be058423 Mon Sep 17 00:00:00 2001 From: Jiang Zhu Date: Sat, 11 Jun 2022 17:23:01 +0800 Subject: [PATCH 5/5] 1) fix typo 2) another hard coded version --- docs/running-headscale-openbsd.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index 6a307f91..dcd1c9bb 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -28,7 +28,7 @@ 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 relase +# 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 @@ -54,7 +54,11 @@ git clone https://github.com/juanfont/headscale.git cd headscale # optionally checkout a release -git checkout v0.16.0-beta1 +# 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