Merge ff091dd56b into 2345c38e1e

.prettierignore

@@ -1,3 +1,2 @@
 .github/workflows/test-integration-v2*
 docs/about/features.md
-docs/ref/remote-cli.md

docs/ref/remote-cli.md

@@ -1,21 +1,22 @@
 # Controlling headscale with remote CLI
 
-This documentation has the goal of showing a user how-to control a headscale instance
+This documentation has the goal of showing a user how-to set control a headscale instance
 from a remote machine with the `headscale` command line binary.
 
 ## Prerequisite
 
-- A workstation to run `headscale` (any supported platform, e.g. Linux).
+- A workstation to run headscale (could be Linux, macOS, other supported platforms)
-- A headscale server with gRPC enabled.
+- A headscale server (version `0.13.0` or newer)
-- Connections to the gRPC port (default: `50443`) are allowed.
+- Access to create API keys (local access to the headscale server)
-- Remote access requires an encrypted connection via TLS.
+- headscale _must_ be served over TLS/HTTPS
-- An API key to authenticate with the headscale server.
+  - Remote access does _not_ support unencrypted traffic.
+- Port `50443` must be open in the firewall (or port overridden by `grpc_listen_addr` option)
 
 ## Create an API key
 
-We need to create an API key to authenticate with the remote headscale server when using it from our workstation.
+We need to create an API key to authenticate our remote headscale when using it from our workstation.
 
-To create an API key, log into your headscale server and generate a key:
+To create a API key, log into your headscale server and generate a key:
 
 ```shell
 headscale apikeys create --expiration 90d
@@ -24,7 +25,7 @@ headscale apikeys create --expiration 90d
 Copy the output of the command and save it for later. Please note that you can not retrieve a key again,
 if the key is lost, expire the old one, and create a new key.
 
-To list the keys currently associated with the server:
+To list the keys currently assosicated with the server:
 
 ```shell
 headscale apikeys list
@@ -38,8 +39,7 @@ headscale apikeys expire --prefix "<PREFIX>"
 
 ## Download and configure headscale
 
-1.  Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
+1.  Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
-    sure to use the same version as on the server.
 
 1.  Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
 
@@ -49,32 +49,25 @@ headscale apikeys expire --prefix "<PREFIX>"
     chmod +x /usr/local/bin/headscale
     ```
 
-1.  Provide the connection parameters for the remote headscale server either via a minimal YAML configuration file or via
+1.  Configure the CLI through environment variables
-    environment variables:
 
-    === "Minimal YAML configuration file"
+    ```shell
+    export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
+    export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
+    ```
 
-        ```yaml
+    for example:
-        cli:
-            address: <HEADSCALE_ADDRESS>:<PORT>
-            api_key: <API_KEY_FROM_PREVIOUS_STEP>
-        ```
 
-    === "Environment variables"
+    ```shell
+    export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443"
+    export HEADSCALE_CLI_API_KEY="abcde12345"
+    ```
 
-        ```shell
+    This will tell the `headscale` binary to connect to a remote instance, instead of looking
-        export HEADSCALE_CLI_ADDRESS="<HEADSCALE_ADDRESS>:<PORT>"
+    for a local instance (which is what it does on the server).
-        export HEADSCALE_CLI_API_KEY="<API_KEY_FROM_PREVIOUS_STEP>"
-        ```
 
-        !!! bug
+    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.
-            Headscale 0.23.0 requires at least an empty configuration file when environment variables are used to
-            specify connection details. See [issue 2193](https://github.com/juanfont/headscale/issues/2193) for more
-            information.
-
-    This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_ADDRESS>:<PORT>`, instead of
-    connecting to the local instance.
 
 1.  Test the connection
 
@@ -96,10 +89,10 @@ While this is _not a supported_ feature, an example on how this can be set up on
 
 ## Troubleshooting
 
-- Make sure you have the _same_ headscale version on your server and workstation.
+Checklist:
-- Ensure that connections to the gRPC port are allowed.
+
-- Verify that your TLS certificate is valid and trusted.
+- Make sure you have the _same_ headscale version on your server and workstation
-- If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
+- Make sure you use version `0.13.0` or newer.
-    - Add your self-signed certificate to the trust store of your OS _or_
+- Verify that your TLS certificate is valid and trusted
-    - Disable certificate verification by either setting `cli.insecure: true` in the configuration file or by setting
+  - If you do not have access to a trusted certificate (e.g. from Let's Encrypt), add your self signed certificate to the trust store of your OS or
-      `HEADSCALE_CLI_INSECURE=1` via an environment variable. We do **not** recommend to disable certificate validation.
+  - Set `HEADSCALE_CLI_INSECURE` to 0 in your environment