Merge branch 'main' into configurable-mtls

docs/README.md

@@ -10,6 +10,8 @@ please ask on [Discord](https://discord.gg/XcQxk2VHjx) instead of opening an Iss
 ### How-to
 
 - [Running headscale on Linux](running-headscale-linux.md)
+- [Control headscale remotely](remote-cli.md)
+- [Using a Windows client with headscale](windows-client.md)
 
 ### References
 

docs/remote-cli.md

@@ -0,0 +1,100 @@
+# Controlling `headscale` with remote CLI
+
+## Prerequisit
+
+- A workstation to run `headscale` (could be Linux, macOS, other supported platforms)
+- A `headscale` server (version `0.13.0` or newer)
+- Access to create API keys (local access to the `headscale` server)
+- `headscale` _must_ be served over TLS/HTTPS
+  - Remote access does _not_ support unencrypted traffic.
+- Port `50443` must be open in the firewall (or port overriden by `grpc_listen_addr` option)
+
+## Goal
+
+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.
+
+## Create an API key
+
+We need to create an API key to authenticate our remote `headscale` when using it from our workstation.
+
+To create a API key, log into your `headscale` server and generate a key:
+
+```shell
+headscale apikeys create --expiration 90d
+```
+
+Copy the output of the command and save it for later. Please not 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 assosicated with the server:
+
+```shell
+headscale apikeys list
+```
+
+and to expire a key:
+
+```shell
+headscale apikeys expire --prefix "<PREFIX>"
+```
+
+## Download and configure `headscale`
+
+1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
+
+2. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headcale`
+
+3. Make `headscale` executable:
+
+```shell
+chmod +x /usr/local/bin/headscale
+```
+
+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>"
+```
+
+for example:
+
+```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).
+
+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.
+
+5. Test the connection
+
+Let us run the headscale command to verify that we can connect by listing our nodes:
+
+```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.
+
+## Behind a proxy
+
+It is possible to run the gRPC remote endpoint behind a reverse proxy, like Nginx, and have it run on the _same_ port as `headscale`.
+
+While this is _not a supported_ feature, an example on how this can be set up on
+[NixOS is shown here](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91).
+
+## Troubleshooting
+
+Checklist:
+
+- Make sure you have the _same_ `headscale` version on your server and workstation
+- Make sure you use version `0.13.0` or newer.
+- Verify that your TLS certificate is valid and trusted
+  - 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
+  - Set `HEADSCALE_CLI_INSECURE` to 0 in your environement

docs/windows-client.md

@@ -0,0 +1,50 @@
+# Connecting a Windows client
+
+## Goal
+
+This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with `headscale`.
+
+## Add registry keys
+
+To make the Windows client behave as expected and to run well with `headscale`, two registry keys **must** be set:
+
+- `HKLM:\SOFTWARE\Tailscale IPN\UnattendedMode` must be set to `always` as a `string` type, to allow Tailscale to run properly in the background
+- `HKLM:\SOFTWARE\Tailscale IPN\LoginURL` must be set to `<YOUR HEADSCALE URL>` as a `string` type, to ensure Tailscale contacts the correct control server.
+
+![windows-registry](./images/windows-registry.png)
+
+The Tailscale Windows client has been observed to reset its configuration on logout/reboot and these two keys [resolves that issue](https://github.com/tailscale/tailscale/issues/2798).
+
+For a guide on how to edit registry keys, [check out Computer Hope](https://www.computerhope.com/issues/ch001348.htm).
+
+## Installation
+
+Download the [Official Windows Client](https://tailscale.com/download/windows) and install it.
+
+When the installation has finished, start Tailscale and log in (you might have to click the icon in the system tray).
+
+The log in should open a browser Window and direct you to your `headscale` instance.
+
+## Troubleshooting
+
+If you are seeing repeated messages like:
+
+```
+[GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     "/machine/redacted"
+```
+
+in your `headscale` output, turn on `DEBUG` logging and look for:
+
+```
+2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
+```
+
+This typically means that the registry keys above was not set appropriately.
+
+To reset and try again, it is important to do the following:
+
+1. Ensure the registry keys from the previous guide is correctly set.
+2. Shut down the Tailscale service (or the client running in the tray)
+3. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
+4. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
+5. Start Tailscale on the windows machine and retry the login.