From d66c5e144f82a6198ee701264a585c959c4c985f Mon Sep 17 00:00:00 2001 From: nblock Date: Tue, 3 Sep 2024 13:04:20 +0200 Subject: [PATCH] Update documentation for 0.23 (#2096) * docs/acl: fix path to policy file * docs/exit-node: fixup for 0.23 * Add newlines between commands to improve readability * Use nodes instead on name * Remove query parameter from link to Tailscale docs * docs/remote-cli: fix formatting * Indent blocks below line numbers to restore numbering * Fix minor typos * docs/reverse-proxy: remove version information * Websocket support is always required now * s/see detail/see details * docs/exit-node: add warning to manual documentation * Replace the warning section with a warning admonition * Fix TODO link back to the regular linux documentation * docs/openbsd: fix typos * the database is created on-the-fly * docs/sealos: fix typos * docs/container: various fixes * Remove a stray sentence * Remove "headscale" before serve * Indent line continuation * Replace hardcoded 0.22 with * Fix path in debug image to /ko-app/headscale Fixes: #1822 aa --- docs/acls.md | 2 +- docs/exit-node.md | 24 ++++++++------ docs/remote-cli.md | 46 +++++++++++++------------- docs/reverse-proxy.md | 6 ++-- docs/running-headscale-container.md | 27 ++++++--------- docs/running-headscale-linux-manual.md | 12 ++----- docs/running-headscale-openbsd.md | 12 ++----- docs/running-headscale-sealos.md | 4 +-- 8 files changed, 58 insertions(+), 75 deletions(-) diff --git a/docs/acls.md b/docs/acls.md index 0b9a885..4ab8fb4 100644 --- a/docs/acls.md +++ b/docs/acls.md @@ -52,7 +52,7 @@ a server they can register, the check of the tags is done on headscale server and only valid tags are applied. A tag is valid if the user that is registering it is allowed to do it. -To use ACLs in headscale, you must edit your config.yaml file. In there you will find a `acl_policy_path: ""` parameter. This will need to point to your ACL file. More info on how these policies are written can be found [here](https://tailscale.com/kb/1018/acls/). +To use ACLs in headscale, you must edit your `config.yaml` file. In there you will find a `policy.path` parameter. This will need to point to your ACL file. More info on how these policies are written can be found [here](https://tailscale.com/kb/1018/acls/). Here are the ACL's to implement the same permissions as above: diff --git a/docs/exit-node.md b/docs/exit-node.md index 831652b..797f42f 100644 --- a/docs/exit-node.md +++ b/docs/exit-node.md @@ -21,21 +21,23 @@ To use a node as an exit node, IP forwarding must be enabled on the node. Check ```console $ # list nodes $ headscale routes list -ID | Machine | Prefix | Advertised | Enabled | Primary -1 | | 0.0.0.0/0 | false | false | - -2 | | ::/0 | false | false | - -3 | phobos | 0.0.0.0/0 | true | false | - -4 | phobos | ::/0 | true | false | - +ID | Node | Prefix | Advertised | Enabled | Primary +1 | | 0.0.0.0/0 | false | false | - +2 | | ::/0 | false | false | - +3 | phobos | 0.0.0.0/0 | true | false | - +4 | phobos | ::/0 | true | false | - + $ # enable routes for phobos $ headscale routes enable -r 3 $ headscale routes enable -r 4 + $ # Check node list again. The routes are now enabled. $ headscale routes list -ID | Machine | Prefix | Advertised | Enabled | Primary -1 | | 0.0.0.0/0 | false | false | - -2 | | ::/0 | false | false | - -3 | phobos | 0.0.0.0/0 | true | true | - -4 | phobos | ::/0 | true | true | - +ID | Node | Prefix | Advertised | Enabled | Primary +1 | | 0.0.0.0/0 | false | false | - +2 | | ::/0 | false | false | - +3 | phobos | 0.0.0.0/0 | true | true | - +4 | phobos | ::/0 | true | true | - ``` ## On the client @@ -46,4 +48,4 @@ The exit node can now be used with: $ sudo tailscale set --exit-node phobos ``` -Check the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes/?q=exit#step-3-use-the-exit-node) for how to do it on your device. +Check the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes#use-the-exit-node) for how to do it on your device. diff --git a/docs/remote-cli.md b/docs/remote-cli.md index 3d44eab..1442385 100644 --- a/docs/remote-cli.md +++ b/docs/remote-cli.md @@ -47,40 +47,40 @@ headscale apikeys expire --prefix "" 3. Make `headscale` executable: -```shell -chmod +x /usr/local/bin/headscale -``` + ```shell + chmod +x /usr/local/bin/headscale + ``` -4. Configure the CLI through Environment Variables +4. Configure the CLI through environment variables -```shell -export HEADSCALE_CLI_ADDRESS=":" -export HEADSCALE_CLI_API_KEY="" -``` + ```shell + export HEADSCALE_CLI_ADDRESS=":" + export HEADSCALE_CLI_API_KEY="" + ``` -for example: + for example: -```shell -export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443" -export HEADSCALE_CLI_API_KEY="abcde12345" -``` + ```shell + export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443" + export HEADSCALE_CLI_API_KEY="abcde12345" + ``` -This will tell the `headscale` binary to connect to a remote instance, instead of looking -for a local instance (which is what it does on the server). + This will tell the `headscale` binary to connect to a remote instance, instead of looking + for a local instance (which is what it does on the server). -The API key is needed to make sure that your are allowed to access the server. The key is _not_ -needed when running directly on the server, as the connection is local. + The API key is needed to make sure that you are allowed to access the server. The key is _not_ + needed when running directly on the server, as the connection is local. 5. Test the connection -Let us run the headscale command to verify that we can connect by listing our nodes: + Let us run the headscale command to verify that we can connect by listing our nodes: -```shell -headscale nodes list -``` + ```shell + headscale nodes list + ``` -You should now be able to see a list of your nodes from your workstation, and you can -now control the `headscale` server from your workstation. + You should now be able to see a list of your nodes from your workstation, and you can + now control the `headscale` server from your workstation. ## Behind a proxy diff --git a/docs/reverse-proxy.md b/docs/reverse-proxy.md index 23c61c2..b042b34 100644 --- a/docs/reverse-proxy.md +++ b/docs/reverse-proxy.md @@ -11,9 +11,9 @@ Running headscale behind a reverse proxy is useful when running multiple applica ### WebSockets -The reverse proxy MUST be configured to support WebSockets, as it is needed for clients running Tailscale v1.30+. +The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients. -WebSockets support is required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml). +WebSockets support is also required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml). ### Cloudflare @@ -80,7 +80,7 @@ Sending local reply with details upgrade_failed ### Envoy -You need add a new upgrade_type named `tailscale-control-protocol`. [see detail](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig) +You need to add a new upgrade_type named `tailscale-control-protocol`. [see details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig) ### Istio diff --git a/docs/running-headscale-container.md b/docs/running-headscale-container.md index 8f5cc7f..ef622f4 100644 --- a/docs/running-headscale-container.md +++ b/docs/running-headscale-container.md @@ -22,12 +22,6 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca cd ./headscale ``` -1. Create an empty SQlite datebase in the headscale directory: - - ```shell - touch ./config/db.sqlite - ``` - 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`: @@ -43,7 +37,6 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca ``` Modify the config file to your preferences before launching Docker container. - Here are some settings that you likely want: 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` @@ -59,7 +52,7 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca --publish 127.0.0.1:8080:8080 \ --publish 127.0.0.1:9090:9090 \ headscale/headscale: \ - headscale serve + 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. @@ -74,16 +67,16 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca services: headscale: - image: headscale/headscale:0.22.3 + image: headscale/headscale: 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 + # Please change to the fullpath of the config folder just created + - :/etc/headscale + command: serve ``` 1. Verify `headscale` is running: @@ -109,7 +102,7 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca ```shell docker exec headscale \ - headscale users create myfirstuser + headscale users create myfirstuser ``` ### Register a machine (normal login) @@ -124,7 +117,7 @@ To register a machine when running `headscale` in a container, take the headscal ```shell docker exec headscale \ - headscale --user myfirstuser nodes register --key + headscale --user myfirstuser nodes register --key ``` ### Register machine using a pre authenticated key @@ -152,7 +145,7 @@ To run the debug Docker container, use the exact same commands as above, but rep ### Executing commands in the debug container -The default command in the debug container is to run `headscale`, which is located at `/bin/headscale` inside the container. +The default command in the debug container is to run `headscale`, which is located at `/ko-app/headscale` inside the container. Additionally, the debug container includes a minimalist Busybox shell. @@ -162,10 +155,10 @@ To launch a shell in the container, use: docker run -it headscale/headscale:x.x.x-debug sh ``` -You can also execute commands directly, such as `ls /bin` in this example: +You can also execute commands directly, such as `ls /ko-app` in this example: ``` -docker run headscale/headscale:x.x.x-debug ls /bin +docker run headscale/headscale:x.x.x-debug ls /ko-app ``` Using `docker exec` allows you to run commands in an existing container. diff --git a/docs/running-headscale-linux-manual.md b/docs/running-headscale-linux-manual.md index 3651c89..25d4763 100644 --- a/docs/running-headscale-linux-manual.md +++ b/docs/running-headscale-linux-manual.md @@ -1,9 +1,9 @@ # Running headscale on Linux -## Note: Outdated and "advanced" +!!! warning "Outdated and advanced" -This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not -want to use this documentation and rather look at the distro specific documentation (TODO LINK)[]. + This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not + want to use this documentation and rather look at the [distro specific documentation](./running-headscale-linux.md). ## Goal @@ -45,12 +45,6 @@ describing how to make `headscale` run properly in a server environment. headscale ``` -1. Create an empty SQLite database: - - ```shell - touch /var/lib/headscale/db.sqlite - ``` - 1. Create a `headscale` configuration: ```shell diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index 72c7bf7..f3e0548 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -10,7 +10,7 @@ ## Goal This documentation has the goal of showing a user how-to install and run `headscale` on OpenBSD. -In additional to the "get up and running section", there is an optional [rc.d section](#running-headscale-in-the-background-with-rcd) +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` @@ -77,16 +77,10 @@ describing how to make `headscale` run properly in a server environment. mkdir -p /etc/headscale - # Directory for Database, and other variable data (like certificates) + # Directory for database, and other variable data (like certificates) mkdir -p /var/lib/headscale ``` -1. Create an empty SQLite database: - - ```shell - touch /var/lib/headscale/db.sqlite - ``` - 1. Create a `headscale` configuration: ```shell @@ -135,7 +129,7 @@ tailscale up --login-server YOUR_HEADSCALE_URL Register the machine: ```shell -headscale --user myfirstuser nodes register --key +headscale --user myfirstuser nodes register --key ``` ### Register machine using a pre authenticated key diff --git a/docs/running-headscale-sealos.md b/docs/running-headscale-sealos.md index 01aecb0..1e3fe3a 100644 --- a/docs/running-headscale-sealos.md +++ b/docs/running-headscale-sealos.md @@ -13,7 +13,7 @@ This documentation has the goal of showing a user how-to run `headscale` on Seal ## Running headscale server -1. Click the following prebuilt template(version [0.23.0-alpha2](https://github.com/juanfont/headscale/releases/tag/v0.23.0-alpha2)): +1. Click the following prebuilt template: [![](https://cdn.jsdelivr.net/gh/labring-actions/templates@main/Deploy-on-Sealos.svg)](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dheadscale) @@ -41,7 +41,7 @@ tailscale up --login-server YOUR_HEADSCALE_URL To register a machine when running headscale in [Sealos](https://sealos.io), click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then take the headscale command: ```bash -headscale --user myfirstuser nodes register --key +headscale --user myfirstuser nodes register --key ``` ### Register machine using a pre authenticated key