diff --git a/.prettierignore b/.prettierignore index 146ae4dd..d455d02c 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1 +1,6 @@ .github/workflows/test-integration-v2* +docs/dns-records.md +docs/running-headscale-container.md +docs/running-headscale-linux-manual.md +docs/running-headscale-linux.md +docs/running-headscale-openbsd.md diff --git a/docs/dns-records.md b/docs/dns-records.md index c5a07fe9..d049c554 100644 --- a/docs/dns-records.md +++ b/docs/dns-records.md @@ -18,23 +18,25 @@ An example use case is to serve apps on the same host via a reverse proxy like N 1. Change the `config.yaml` to contain the desired records like so: -```yaml -dns_config: - ... - extra_records: - - name: "prometheus.myvpn.example.com" - type: "A" - value: "100.64.0.3" + ```yaml + dns_config: + ... + extra_records: + - name: "prometheus.myvpn.example.com" + type: "A" + value: "100.64.0.3" - - name: "grafana.myvpn.example.com" - type: "A" - value: "100.64.0.3" - ... -``` + - name: "grafana.myvpn.example.com" + type: "A" + value: "100.64.0.3" + ... + ``` -2. Restart your headscale instance. +1. Restart your headscale instance. -Beware of the limitations listed later on! + !!! warning + + Beware of the limitations listed later on! ### 2. Verify that the records are set diff --git a/docs/running-headscale-container.md b/docs/running-headscale-container.md index 6a582ba9..73c1107e 100644 --- a/docs/running-headscale-container.md +++ b/docs/running-headscale-container.md @@ -17,127 +17,124 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca 1. Prepare a directory on the host Docker node in your directory of choice, used to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database: -```shell -mkdir -p ./headscale/config -cd ./headscale -``` + ```shell + mkdir -p ./headscale/config + cd ./headscale + ``` -2. Create an empty SQlite datebase in the headscale directory: +1. Create an empty SQlite datebase in the headscale directory: -```shell -touch ./config/db.sqlite -``` + ```shell + touch ./config/db.sqlite + ``` -3. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. +1. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. -Using wget: + - Using `wget`: -```shell -wget -O ./config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -``` + ```shell + wget -O ./config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml + ``` -Using curl: + - Using `curl`: -```shell -curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml -``` + ```shell + curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml + ``` -**(Advanced)** If you would like to hand craft a config file **instead** of downloading the example config file, create a blank `headscale` configuration in the headscale directory to edit: + - **(Advanced)** If you would like to hand craft a config file **instead** of downloading the example config file, create a blank `headscale` configuration in the headscale directory to edit: -```shell -touch ./config/config.yaml -``` + ```shell + touch ./config/config.yaml + ``` -Modify the config file to your preferences before launching Docker container. -Here are some settings that you likely want: + Modify the config file to your preferences before launching Docker container. + Here are some settings that you likely want: -```yaml -# Change to your hostname or host IP -server_url: http://your-host-name:8080 -# Listen to 0.0.0.0 so it's accessible outside the container -metrics_listen_addr: 0.0.0.0:9090 -# The default /var/lib/headscale path is not writable in the container -noise: - private_key_path: /etc/headscale/noise_private.key -# The default /var/lib/headscale path is not writable in the container -derp: - private_key_path: /etc/headscale/private.key -# The default /var/run/headscale path is not writable in the container -unix_socket: /etc/headscale/headscale.sock -# The default /var/lib/headscale path is not writable in the container -database.type: sqlite3 -database.sqlite.path: /etc/headscale/db.sqlite -``` + ```yaml + # Change to your hostname or host IP + server_url: http://your-host-name:8080 + # Listen to 0.0.0.0 so it's accessible outside the container + metrics_listen_addr: 0.0.0.0:9090 + # The default /var/lib/headscale path is not writable in the container + noise: + private_key_path: /etc/headscale/noise_private.key + # The default /var/lib/headscale path is not writable in the container + derp: + private_key_path: /etc/headscale/private.key + # The default /var/run/headscale path is not writable in the container + unix_socket: /etc/headscale/headscale.sock + # The default /var/lib/headscale path is not writable in the container + database.type: sqlite3 + database.sqlite.path: /etc/headscale/db.sqlite + ``` -Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding -`--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale` -in the next step. + Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding + `--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale` + in the next step. -4. Start the headscale server while working in the host headscale directory: +1. Start the headscale server while working in the host headscale directory: -```shell -docker run \ - --name headscale \ - --detach \ - --volume $(pwd)/config:/etc/headscale/ \ - --publish 127.0.0.1:8080:8080 \ - --publish 127.0.0.1:9090:9090 \ - headscale/headscale: \ - headscale serve + ```shell + docker run \ + --name headscale \ + --detach \ + --volume $(pwd)/config:/etc/headscale/ \ + --publish 127.0.0.1:8080:8080 \ + --publish 127.0.0.1:9090:9090 \ + headscale/headscale: \ + headscale serve + ``` -``` + Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally. -Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally. + This command will mount `config/` under `/etc/headscale`, forward port 8080 out of the container so the + `headscale` instance becomes available and then detach so headscale runs in the background. -This command will mount `config/` under `/etc/headscale`, forward port 8080 out of the container so the -`headscale` instance becomes available and then detach so headscale runs in the background. + Example `docker-compose.yaml` -Example `docker-compose.yaml` + ```yaml + version: "3.7" + + services: + headscale: + image: headscale/headscale:0.22.3 + restart: unless-stopped + container_name: headscale + ports: + - "127.0.0.1:8080:8080" + - "127.0.0.1:9090:9090" + volumes: + # pls change [config_path] to the fullpath of the config folder just created + - [config_path]:/etc/headscale + command: headscale serve + ``` -```yaml -version: "3.7" +1. Verify `headscale` is running: + Follow the container logs: -services: - headscale: - image: headscale/headscale:0.22.3 - restart: unless-stopped - container_name: headscale - ports: - - "127.0.0.1:8080:8080" - - "127.0.0.1:9090:9090" - volumes: - # pls change [config_path] to the fullpath of the config folder just created - - [config_path]:/etc/headscale - command: headscale serve + ```shell + docker logs --follow headscale + ``` -``` + Verify running containers: -5. Verify `headscale` is running: + ```shell + docker ps + ``` -Follow the container logs: + Verify `headscale` is available: -```shell -docker logs --follow headscale -``` + ```shell + curl http://127.0.0.1:9090/metrics + ``` -Verify running containers: +1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): -```shell -docker ps -``` - -Verify `headscale` is available: - -```shell -curl http://127.0.0.1:9090/metrics -``` - -6. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): - -```shell -docker exec headscale \ - headscale users create myfirstuser -``` + ```shell + docker exec headscale \ + headscale users create myfirstuser + ``` ### Register a machine (normal login) diff --git a/docs/running-headscale-linux-manual.md b/docs/running-headscale-linux-manual.md index 20e88d54..4108208f 100644 --- a/docs/running-headscale-linux-manual.md +++ b/docs/running-headscale-linux-manual.md @@ -15,78 +15,77 @@ describing how to make `headscale` run properly in a server environment. 1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases): -```shell -wget --output-document=/usr/local/bin/headscale \ - https://github.com/juanfont/headscale/releases/download/v/headscale__linux_ -``` + ```shell + wget --output-document=/usr/local/bin/headscale \ + https://github.com/juanfont/headscale/releases/download/v/headscale__linux_ + ``` -2. Make `headscale` executable: +1. Make `headscale` executable: -```shell -chmod +x /usr/local/bin/headscale -``` + ```shell + chmod +x /usr/local/bin/headscale + ``` -3. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database: +1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database: -```shell -# Directory for configuration + ```shell + # Directory for configuration -mkdir -p /etc/headscale + mkdir -p /etc/headscale -# Directory for Database, and other variable data (like certificates) -mkdir -p /var/lib/headscale -# or if you create a headscale user: -useradd \ - --create-home \ - --home-dir /var/lib/headscale/ \ - --system \ - --user-group \ - --shell /usr/sbin/nologin \ - headscale -``` + # Directory for Database, and other variable data (like certificates) + mkdir -p /var/lib/headscale + # or if you create a headscale user: + useradd \ + --create-home \ + --home-dir /var/lib/headscale/ \ + --system \ + --user-group \ + --shell /usr/sbin/nologin \ + headscale + ``` -4. Create an empty SQLite database: +1. Create an empty SQLite database: -```shell -touch /var/lib/headscale/db.sqlite -``` + ```shell + touch /var/lib/headscale/db.sqlite + ``` -5. Create a `headscale` configuration: +1. Create a `headscale` configuration: -```shell -touch /etc/headscale/config.yaml -``` + ```shell + touch /etc/headscale/config.yaml + ``` -**(Strongly Recommended)** Download a copy of the [example configuration][config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. + **(Strongly Recommended)** Download a copy of the [example configuration][config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. -6. Start the headscale server: +1. Start the headscale server: -```shell -headscale serve -``` + ```shell + headscale serve + ``` -This command will start `headscale` in the current terminal session. + 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) or [screen](https://www.gnu.org/software/screen/). + 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) or [screen](https://www.gnu.org/software/screen/). -To run `headscale` in the background, please follow the steps in the [SystemD section](#running-headscale-in-the-background-with-systemd) before continuing. + To run `headscale` in the background, please follow the steps in the [SystemD section](#running-headscale-in-the-background-with-systemd) before continuing. -7. Verify `headscale` is running: +1. Verify `headscale` is running: + Verify `headscale` is available: -Verify `headscale` is available: + ```shell + curl http://127.0.0.1:9090/metrics + ``` -```shell -curl http://127.0.0.1:9090/metrics -``` +1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): -8. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): - -```shell -headscale users create myfirstuser -``` + ```shell + headscale users create myfirstuser + ``` ### Register a machine (normal login) @@ -118,81 +117,81 @@ tailscale up --login-server --authkey ## Running `headscale` in the background with SystemD -:warning: **Deprecated**: This part is very outdated and you should use the [pre-packaged Headscale for this](./running-headscale-linux.md +:warning: **Deprecated**: This part is very outdated and you should use the [pre-packaged Headscale for this](./running-headscale-linux.md) This section demonstrates how to run `headscale` as a service in the background with [SystemD](https://www.freedesktop.org/wiki/Software/systemd/). This should work on most modern Linux distributions. 1. Create a SystemD service configuration at `/etc/systemd/system/headscale.service` containing: -```systemd -[Unit] -Description=headscale controller -After=syslog.target -After=network.target + ```systemd + [Unit] + Description=headscale controller + After=syslog.target + After=network.target -[Service] -Type=simple -User=headscale -Group=headscale -ExecStart=/usr/local/bin/headscale serve -Restart=always -RestartSec=5 + [Service] + Type=simple + User=headscale + Group=headscale + ExecStart=/usr/local/bin/headscale serve + Restart=always + RestartSec=5 -# Optional security enhancements -NoNewPrivileges=yes -PrivateTmp=yes -ProtectSystem=strict -ProtectHome=yes -WorkingDirectory=/var/lib/headscale -ReadWritePaths=/var/lib/headscale /var/run/headscale -AmbientCapabilities=CAP_NET_BIND_SERVICE -RuntimeDirectory=headscale + # Optional security enhancements + NoNewPrivileges=yes + PrivateTmp=yes + ProtectSystem=strict + ProtectHome=yes + WorkingDirectory=/var/lib/headscale + ReadWritePaths=/var/lib/headscale /var/run/headscale + AmbientCapabilities=CAP_NET_BIND_SERVICE + RuntimeDirectory=headscale -[Install] -WantedBy=multi-user.target -``` + [Install] + WantedBy=multi-user.target + ``` -Note that when running as the headscale user ensure that, either you add your current user to the headscale group: + Note that when running as the headscale user ensure that, either you add your current user to the headscale group: -```shell -usermod -a -G headscale current_user -``` + ```shell + usermod -a -G headscale current_user + ``` -or run all headscale commands as the headscale user: + or run all headscale commands as the headscale user: -```shell -su - headscale -``` + ```shell + su - headscale + ``` -2. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with path that is writable by the `headscale` user or group: +1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with path that is writable by the `headscale` user or group: -```yaml -unix_socket: /var/run/headscale/headscale.sock -``` + ```yaml + unix_socket: /var/run/headscale/headscale.sock + ``` -3. Reload SystemD to load the new configuration file: +1. Reload SystemD to load the new configuration file: -```shell -systemctl daemon-reload -``` + ```shell + systemctl daemon-reload + ``` -4. Enable and start the new `headscale` service: +1. Enable and start the new `headscale` service: -```shell -systemctl enable --now headscale -``` + ```shell + systemctl enable --now headscale + ``` -5. Verify the headscale service: +1. Verify the headscale service: -```shell -systemctl status headscale -``` + ```shell + systemctl status headscale + ``` -Verify `headscale` is available: + Verify `headscale` is available: -```shell -curl http://127.0.0.1:9090/metrics -``` + ```shell + curl http://127.0.0.1:9090/metrics + ``` `headscale` will now run in the background and start at boot. diff --git a/docs/running-headscale-linux.md b/docs/running-headscale-linux.md index 282cd5ee..aa92cb2b 100644 --- a/docs/running-headscale-linux.md +++ b/docs/running-headscale-linux.md @@ -22,40 +22,40 @@ configuration (`/etc/headscale/config.yaml`). 1. Download the lastest Headscale package for your platform (`.deb` for Ubuntu and Debian) from [Headscale's releases page](https://github.com/juanfont/headscale/releases): -```shell -wget --output-document=headscale.deb \ - https://github.com/juanfont/headscale/releases/download/v/headscale__linux_.deb -``` + ```shell + wget --output-document=headscale.deb \ + https://github.com/juanfont/headscale/releases/download/v/headscale__linux_.deb + ``` -2. Install Headscale: +1. Install Headscale: -```shell -sudo dpkg --install headscale.deb -``` + ```shell + sudo dpkg --install headscale.deb + ``` -3. Enable Headscale service, this will start Headscale at boot: +1. Enable Headscale service, this will start Headscale at boot: -```shell -sudo systemctl enable headscale -``` + ```shell + sudo systemctl enable headscale + ``` -4. Configure Headscale by editing the configuration file: +1. Configure Headscale by editing the configuration file: -```shell -nano /etc/headscale/config.yaml -``` + ```shell + nano /etc/headscale/config.yaml + ``` -5. Start Headscale: +1. Start Headscale: -```shell -sudo systemctl start headscale -``` + ```shell + sudo systemctl start headscale + ``` -6. Check that Headscale is running as intended: +1. Check that Headscale is running as intended: -```shell -systemctl status headscale -``` + ```shell + systemctl status headscale + ``` ## Using Headscale diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index b76c9135..29e340fc 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -15,115 +15,116 @@ describing how to make `headscale` run properly in a server environment. ## Install `headscale` -1. Install from ports (Not Recommend) +1. Install from ports (not recommended) - As of OpenBSD 7.2, there's a headscale in ports collection, however, it's severely outdated(v0.12.4). - You can install it via `pkg_add headscale`. + !!! info -2. Install from source on OpenBSD 7.2 + As of OpenBSD 7.2, there's a headscale in ports collection, however, it's severely outdated(v0.12.4). You can install it via `pkg_add headscale`. -```shell -# Install prerequistes -pkg_add go +1. Install from source on OpenBSD 7.2 -git clone https://github.com/juanfont/headscale.git + ```shell + # Install prerequistes + pkg_add go -cd headscale + git clone https://github.com/juanfont/headscale.git -# 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 release -latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) + cd headscale -git checkout $latestTag + # 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 release + latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) -go build -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$latestTag" github.com/juanfont/headscale + git checkout $latestTag -# make it executable -chmod a+x headscale + go build -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$latestTag" github.com/juanfont/headscale -# copy it to /usr/local/sbin -cp headscale /usr/local/sbin -``` + # make it executable + chmod a+x headscale -3. Install from source via cross compile + # copy it to /usr/local/sbin + cp headscale /usr/local/sbin + ``` -```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 +1. Install from source via cross compile -git clone https://github.com/juanfont/headscale.git + ```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 -cd headscale + git clone https://github.com/juanfont/headscale.git -# 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 release -latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) + cd headscale -git checkout $latestTag + # 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 release + latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) -make build GOOS=openbsd + git checkout $latestTag -# copy headscale to openbsd machine and put it in /usr/local/sbin -``` + 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 + ```shell + # Directory for configuration -mkdir -p /etc/headscale + mkdir -p /etc/headscale -# Directory for Database, and other variable data (like certificates) -mkdir -p /var/lib/headscale -``` + # Directory for Database, and other variable data (like certificates) + mkdir -p /var/lib/headscale + ``` -2. Create an empty SQLite database: +1. Create an empty SQLite database: -```shell -touch /var/lib/headscale/db.sqlite -``` + ```shell + touch /var/lib/headscale/db.sqlite + ``` -3. Create a `headscale` configuration: +1. Create a `headscale` configuration: -```shell -touch /etc/headscale/config.yaml -``` + ```shell + touch /etc/headscale/config.yaml + ``` **(Strongly Recommended)** Download a copy of the [example configuration][config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. -4. Start the headscale server: +1. Start the headscale server: -```shell -headscale serve -``` + ```shell + headscale serve + ``` -This command will start `headscale` in the current terminal session. + 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 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-rcd) 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: +1. Verify `headscale` is running: -Verify `headscale` is available: + Verify `headscale` is available: -```shell -curl http://127.0.0.1:9090/metrics -``` + ```shell + curl http://127.0.0.1:9090/metrics + ``` -6. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): +1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): -```shell -headscale users create myfirstuser -``` + ```shell + headscale users create myfirstuser + ``` ### Register a machine (normal login) @@ -159,51 +160,51 @@ This section demonstrates how to run `headscale` as a service in the background 1. Create a rc.d service at `/etc/rc.d/headscale` containing: -```shell -#!/bin/ksh + ```shell + #!/bin/ksh -daemon="/usr/local/sbin/headscale" -daemon_logger="daemon.info" -daemon_user="root" -daemon_flags="serve" -daemon_timeout=60 + daemon="/usr/local/sbin/headscale" + daemon_logger="daemon.info" + daemon_user="root" + daemon_flags="serve" + daemon_timeout=60 -. /etc/rc.d/rc.subr + . /etc/rc.d/rc.subr -rc_bg=YES -rc_reload=NO + rc_bg=YES + rc_reload=NO -rc_cmd $1 -``` + rc_cmd $1 + ``` -2. `/etc/rc.d/headscale` needs execute permission: +1. `/etc/rc.d/headscale` needs execute permission: -```shell -chmod a+x /etc/rc.d/headscale -``` + ```shell + chmod a+x /etc/rc.d/headscale + ``` -3. Start `headscale` service: +1. Start `headscale` service: -```shell -rcctl start headscale -``` + ```shell + rcctl start headscale + ``` -4. Make `headscale` service start at boot: +1. Make `headscale` service start at boot: -```shell -rcctl enable headscale -``` + ```shell + rcctl enable headscale + ``` -5. Verify the headscale service: +1. Verify the headscale service: -```shell -rcctl check headscale -``` + ```shell + rcctl check headscale + ``` -Verify `headscale` is available: + Verify `headscale` is available: -```shell -curl http://127.0.0.1:9090/metrics -``` + ```shell + curl http://127.0.0.1:9090/metrics + ``` -`headscale` will now run in the background and start at boot. + `headscale` will now run in the background and start at boot.