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 <VERSION>
* Fix path in debug image to /ko-app/headscale

Fixes: #1822

aa

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:
 

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.

docs/remote-cli.md

@@ -47,40 +47,40 @@ headscale apikeys expire --prefix "<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="<HEADSCALE ADDRESS>:<PORT>"
-export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
-```
+    ```shell
+    export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
+    export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
+    ```
 
-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
 

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
 

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:<VERSION> \
-      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:<VERSION>
           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 <CONFIG_PATH> to the fullpath of the config folder just created
+            - <CONFIG_PATH>:/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 <YOU_+MACHINE_KEY>
+  headscale --user myfirstuser nodes register --key <YOUR_MACHINE_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.

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

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 <YOU_+MACHINE_KEY>
+headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
 ```
 
 ### Register machine using a pre authenticated key

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 <YOU_+MACHINE_KEY>
+headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
 ```
 
 ### Register machine using a pre authenticated key