Merge 137f0e3e12 into e7245856c5

Refresh remote CLI documentation (#2216 )
* Document to either use a minimal configuration file or environment variables to connect with a remote headscale instance. * Document a workaround specific for headscale 0.23.0. * Remove reference to ancient headscale version. * Use `cli.insecure: true` or `HEADSCALE_CLI_INSECURE=1` to skip certificate verification. * Style and typo fixes Ref: #2193
2024-11-29 18:33:05 +00:00 · 2024-11-13 16:07:56 -08:00 · 2024-11-13 18:35:42 +01:00 · 2024-11-12 16:53:30 +01:00 · 2024-11-12 13:27:49 +00:00 · 2024-11-04 10:05:21 -06:00
10 changed files with 77 additions and 53 deletions
--- a/.prettierignore
+++ b/.prettierignore
@ -1,2 +1,3 @@
 .github/workflows/test-integration-v2*
 docs/about/features.md
+docs/ref/remote-cli.md
--- a/Dockerfile.integration
+++ b/Dockerfile.integration
--- a/docs/ref/integration/tools.md
+++ b/docs/ref/integration/tools.md
@ -0,0 +1,12 @@
+# Tools related to headscale
+
+!!! warning "Community contributions"
+
+    This page contains community contributions. The projects listed here are not
+    maintained by the headscale authors and are written by community members.
+
+This page collects third-party tools and scripts related to headscale.
+
+| Name              | Repository Link                                                 | Description                                       |
+| ----------------- | --------------------------------------------------------------- | ------------------------------------------------- |
+| tailscale-manager | [Github](https://github.com/singlestore-labs/tailscale-manager) | Dynamically manage Tailscale route advertisements |
--- a/docs/ref/integration/web-ui.md
+++ b/docs/ref/integration/web-ui.md
@ -1,17 +1,19 @@
-# Headscale web interface
+# Web interfaces for headscale

 !!! warning "Community contributions"

    This page contains community contributions. The projects listed here are not
    maintained by the headscale authors and are written by community members.

-| Name            | Repository Link                                         | Description                                                                         | Status |
-| --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------ |
-| headscale-webui | [Github](https://github.com/ifargle/headscale-webui)    | A simple headscale web UI for small-scale deployments.                              | Alpha  |
-| headscale-ui    | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server           | Alpha  |
-| HeadscaleUi     | [GitHub](https://github.com/simcu/headscale-ui)         | A static headscale admin ui, no backend enviroment required                         | Alpha  |
-| Headplane       | [GitHub](https://github.com/tale/headplane)             | An advanced Tailscale inspired frontend for headscale                               | Alpha  |
-| headscale-admin | [Github](https://github.com/GoodiesHQ/headscale-admin)  | Headscale-Admin is meant to be a simple, modern web interface for headscale         | Beta   |
-| ouroboros       | [Github](https://github.com/yellowsink/ouroboros)       | Ouroboros is designed for users to manage their own devices, rather than for admins | Stable |
+Headscale doesn't provide a built-in web interface but users may pick one from the available options.
+
+| Name            | Repository Link                                         | Description                                                                         |
+| --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| headscale-webui | [Github](https://github.com/ifargle/headscale-webui)    | A simple headscale web UI for small-scale deployments.                              |
+| headscale-ui    | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server           |
+| HeadscaleUi     | [GitHub](https://github.com/simcu/headscale-ui)         | A static headscale admin ui, no backend enviroment required                         |
+| Headplane       | [GitHub](https://github.com/tale/headplane)             | An advanced Tailscale inspired frontend for headscale                               |
+| headscale-admin | [Github](https://github.com/GoodiesHQ/headscale-admin)  | Headscale-Admin is meant to be a simple, modern web interface for headscale         |
+| ouroboros       | [Github](https://github.com/yellowsink/ouroboros)       | Ouroboros is designed for users to manage their own devices, rather than for admins |

 You can ask for support on our dedicated [Discord channel](https://discord.com/channels/896711691637780480/1105842846386356294).
--- a/docs/ref/remote-cli.md
+++ b/docs/ref/remote-cli.md
@ -1,22 +1,21 @@
 # Controlling headscale with remote CLI

-This documentation has the goal of showing a user how-to set control a headscale instance
+This documentation has the goal of showing a user how-to control a headscale instance
 from a remote machine with the `headscale` command line binary.

 ## Prerequisite

- 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 overridden by `grpc_listen_addr` option)
+- A workstation to run `headscale` (any supported platform, e.g. Linux).
+- A headscale server with gRPC enabled.
+- Connections to the gRPC port (default: `50443`) are allowed.
+- Remote access requires an encrypted connection via TLS.
+- An API key to authenticate with the headscale server.

 ## Create an API key

-We need to create an API key to authenticate our remote headscale when using it from our workstation.
+We need to create an API key to authenticate with the remote headscale server when using it from our workstation.

-To create a API key, log into your headscale server and generate a key:
+To create an API key, log into your headscale server and generate a key:

 ```shell
 headscale apikeys create --expiration 90d
@ -25,7 +24,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 assosicated with the server:
+To list the keys currently associated with the server:

 ```shell
 headscale apikeys list
@ -39,7 +38,8 @@ 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):
+1.  Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
+    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,25 +49,32 @@ headscale apikeys expire --prefix "<PREFIX>"
    chmod +x /usr/local/bin/headscale
    ```

-1.  Configure the CLI through environment variables
+1.  Provide the connection parameters for the remote headscale server either via a minimal YAML configuration file or via
+    environment variables:

-    ```shell
-    export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
-    export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
-    ```
+    === "Minimal YAML configuration file"

-    for example:
+        ```yaml
+        cli:
+            address: <HEADSCALE_ADDRESS>:<PORT>
+            api_key: <API_KEY_FROM_PREVIOUS_STEP>
+        ```

-    ```shell
-    export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443"
-    export HEADSCALE_CLI_API_KEY="abcde12345"
-    ```
+    === "Environment variables"

-    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).
+        ```shell
+        export HEADSCALE_CLI_ADDRESS="<HEADSCALE_ADDRESS>:<PORT>"
+        export HEADSCALE_CLI_API_KEY="<API_KEY_FROM_PREVIOUS_STEP>"
+        ```

-    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.
+        !!! bug
+
+            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

@ -89,10 +96,10 @@ While this is _not a supported_ feature, an example on how this can be set up on

 ## 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 environment
+- Make sure you have the _same_ headscale version on your server and workstation.
+- Ensure that connections to the gRPC port are allowed.
+- Verify that your TLS certificate is valid and trusted.
+- If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
+    - Add your self-signed certificate to the trust store of your OS _or_
+    - Disable certificate verification by either setting `cli.insecure: true` in the configuration file or by setting
+      `HEADSCALE_CLI_INSECURE=1` via an environment variable. We do **not** recommend to disable certificate validation.
--- a/docs/setup/install/community.md
+++ b/docs/setup/install/community.md
@ -28,7 +28,7 @@ development version.

 ## Fedora, RHEL, CentOS

-A 3rd-party repository for various RPM based distributions is available at:
+A third-party repository for various RPM based distributions is available at:
 <https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/>. The site provides detailed setup and installation
 instructions.

--- a/flake.lock
+++ b/flake.lock
@ -20,11 +20,11 @@
    },
    "nixpkgs": {
      "locked": {
-        "lastModified": 1729850857,
-        "narHash": "sha256-WvLXzNNnnw+qpFOmgaM3JUlNEH+T4s22b5i2oyyCpXE=",
+        "lastModified": 1730958623,
+        "narHash": "sha256-JwQZIGSYnRNOgDDoIgqKITrPVil+RMWHsZH1eE1VGN0=",
        "owner": "NixOS",
        "repo": "nixpkgs",
-        "rev": "41dea55321e5a999b17033296ac05fe8a8b5a257",
+        "rev": "85f7e662eda4fa3a995556527c87b2524b691933",
        "type": "github"
      },
      "original": {
--- a/integration/auth_oidc_test.go
+++ b/integration/auth_oidc_test.go
@ -223,7 +223,7 @@ func (s *AuthOIDCScenario) runMockOIDC(accessTTL time.Duration) (*types.OIDCConf
 	}

 	headscaleBuildOptions := &dockertest.BuildOptions{
-		Dockerfile: "Dockerfile.debug",
+		Dockerfile: hsic.IntegrationTestDockerFileName,
 		ContextDir: dockerContextPath,
 	}

--- a/integration/hsic/hsic.go
+++ b/integration/hsic/hsic.go
@ -35,12 +35,13 @@ import (
 )

 const (
-	hsicHashLength       = 6
-	dockerContextPath    = "../."
-	aclPolicyPath        = "/etc/headscale/acl.hujson"
-	tlsCertPath          = "/etc/headscale/tls.cert"
-	tlsKeyPath           = "/etc/headscale/tls.key"
-	headscaleDefaultPort = 8080
+	hsicHashLength                = 6
+	dockerContextPath             = "../."
+	aclPolicyPath                 = "/etc/headscale/acl.hujson"
+	tlsCertPath                   = "/etc/headscale/tls.cert"
+	tlsKeyPath                    = "/etc/headscale/tls.key"
+	headscaleDefaultPort          = 8080
+	IntegrationTestDockerFileName = "Dockerfile.integration"
 )

 var errHeadscaleStatusCodeNotOk = errors.New("headscale status code not ok")
@ -260,7 +261,7 @@ func New(
 	}

 	headscaleBuildOptions := &dockertest.BuildOptions{
-		Dockerfile: "Dockerfile.debug",
+		Dockerfile: IntegrationTestDockerFileName,
 		ContextDir: dockerContextPath,
 	}

--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -183,3 +183,4 @@ nav:
      - Integration:
          - Reverse proxy: ref/integration/reverse-proxy.md
          - Web UI: ref/integration/web-ui.md
+          - Tools: ref/integration/tools.md
Author	SHA1	Message	Date
Kristoffer Dalby	ec57399ebb	Merge `137f0e3e12` into `e7245856c5`	2024-11-13 16:07:56 -08:00
nblock	e7245856c5	Refresh remote CLI documentation (#2216 ) Some checks failed Build documentation / deploy (push) Has been cancelled Details Build / build (push) Has been cancelled Details Build documentation / build (push) Has been cancelled Details Tests / test (push) Has been cancelled Details * Document to either use a minimal configuration file or environment variables to connect with a remote headscale instance. * Document a workaround specific for headscale 0.23.0. * Remove reference to ancient headscale version. * Use `cli.insecure: true` or `HEADSCALE_CLI_INSECURE=1` to skip certificate verification. * Style and typo fixes Ref: #2193	2024-11-13 18:35:42 +01:00
nblock	2345c38e1e	Add a page for third-party tools (#2217 ) Some checks are pending Build / build (push) Waiting to run Details Build documentation / build (push) Waiting to run Details Build documentation / deploy (push) Blocked by required conditions Details Tests / test (push) Waiting to run Details * Remove status from web-ui docs Rename the title to indicate that there multiple web interfaces available. Do not track the status of each web interface here as their status is subject to change over time. * Add page for third-party tools and scripts	2024-11-12 16:53:30 +01:00
github-actions[bot]	8cfaa6bdac	flake.lock: Update (#2222 )	2024-11-12 13:27:49 +00:00
Kristoffer Dalby	137f0e3e12	rename dockerfile to integration to avoid confusion Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>	2024-11-04 10:05:21 -06:00