Merge 0c1309b7e2 into e7245856c5

* 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

.github/workflows/test-integration.yaml

@@ -108,7 +108,7 @@ jobs:
               --volume $PWD/control_logs:/tmp/control \
               --env HEADSCALE_INTEGRATION_POSTGRES=${{env.USE_POSTGRES}} \
               golang:1 \
-                go run gotest.tools/gotestsum@latest -- ./... \
+                go run gotest.tools/gotestsum@latest -- -race ./... \
                   -failfast \
                   -timeout 120m \
                   -parallel 1 \

.goreleaser.yml

@@ -154,7 +154,7 @@ kos:
       - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}.{{ .Patch }}-debug{{ end }}"
       - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}-debug{{ end }}"
       - "{{ if not .Prerelease }}v{{ .Major }}-debug{{ end }}"
-      - "{{ if not .Prerelease }}stable{{ else }}unstable-debug{{ end }}"
+      - "{{ if not .Prerelease }}stable-debug{{ else }}unstable-debug{{ end }}"
       - "{{ .Tag }}-debug"
       - '{{ trimprefix .Tag "v" }}-debug'
       - "sha-{{ .ShortCommit }}-debug"
@@ -177,7 +177,7 @@ kos:
       - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}.{{ .Patch }}-debug{{ end }}"
       - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}-debug{{ end }}"
       - "{{ if not .Prerelease }}v{{ .Major }}-debug{{ end }}"
-      - "{{ if not .Prerelease }}stable{{ else }}unstable-debug{{ end }}"
+      - "{{ if not .Prerelease }}stable-debug{{ else }}unstable-debug{{ end }}"
       - "{{ .Tag }}-debug"
       - '{{ trimprefix .Tag "v" }}-debug'
       - "sha-{{ .ShortCommit }}-debug"

.prettierignore

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

CHANGELOG.md

@@ -22,6 +22,7 @@
 - Fixed processing of fields in post request in MoveNode rpc [#2179](https://github.com/juanfont/headscale/pull/2179)
 - Added conversion of 'Hostname' to 'givenName' in a node with FQDN rules applied [#2198](https://github.com/juanfont/headscale/pull/2198)
 - Fixed updating of hostname and givenName when it is updated in HostInfo [#2199](https://github.com/juanfont/headscale/pull/2199)
+- Fixed missing `stable-debug` container tag [#2232](https://github.com/juanfont/headscale/pr/2232)
 
 ## 0.23.0 (2024-09-18)
 

Makefile

@@ -22,7 +22,7 @@ build:
 dev: lint test build
 
 test:
-	gotestsum -- -short -coverprofile=coverage.out ./...
+	gotestsum -- -short -race -coverprofile=coverage.out ./...
 
 test_integration:
 	docker run \
@@ -33,7 +33,7 @@ test_integration:
 		-v /var/run/docker.sock:/var/run/docker.sock \
 		-v $$PWD/control_logs:/tmp/control \
 		golang:1 \
-		go run gotest.tools/gotestsum@latest -- -failfast ./... -timeout 120m -parallel 8
+		go run gotest.tools/gotestsum@latest -- -race -failfast ./... -timeout 120m -parallel 8
 
 lint:
 	golangci-lint run --fix --timeout 10m

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 |

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

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 workstation to run `headscale` (any supported platform, e.g. Linux).
-- A headscale server (version `0.13.0` or newer)
+- A headscale server with gRPC enabled.
-- Access to create API keys (local access to the headscale server)
+- Connections to the gRPC port (default: `50443`) are allowed.
-- headscale _must_ be served over TLS/HTTPS
+- Remote access requires an encrypted connection via TLS.
-  - Remote access does _not_ support unencrypted traffic.
+- An API key to authenticate with the headscale server.
-- 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 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
+    === "Minimal YAML configuration file"
-    export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
-    export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
-    ```
 
-    for example:
+        ```yaml
+        cli:
+            address: <HEADSCALE_ADDRESS>:<PORT>
+            api_key: <API_KEY_FROM_PREVIOUS_STEP>
+        ```
 
-    ```shell
+    === "Environment variables"
-    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
+        ```shell
-    for a local instance (which is what it does on the server).
+        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_
+        !!! bug
-    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
 
@@ -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.
-
+- Ensure that connections to the gRPC port are allowed.
-- Make sure you have the _same_ headscale version on your server and workstation
+- Verify that your TLS certificate is valid and trusted.
-- Make sure you use version `0.13.0` or newer.
+- If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
-- Verify that your TLS certificate is valid and trusted
+    - Add your self-signed certificate to the trust store of your OS _or_
-  - 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
+    - Disable certificate verification by either setting `cli.insecure: true` in the configuration file or by setting
-  - Set `HEADSCALE_CLI_INSECURE` to 0 in your environment
+      `HEADSCALE_CLI_INSECURE=1` via an environment variable. We do **not** recommend to disable certificate validation.

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.
 

flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1729850857,
+        "lastModified": 1730958623,
-        "narHash": "sha256-WvLXzNNnnw+qpFOmgaM3JUlNEH+T4s22b5i2oyyCpXE=",
+        "narHash": "sha256-JwQZIGSYnRNOgDDoIgqKITrPVil+RMWHsZH1eE1VGN0=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "41dea55321e5a999b17033296ac05fe8a8b5a257",
+        "rev": "85f7e662eda4fa3a995556527c87b2524b691933",
         "type": "github"
       },
       "original": {

integration/dockertestutil/execute.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"errors"
 	"fmt"
+	"sync"
 	"time"
 
 	"github.com/ory/dockertest/v3"
@@ -25,7 +26,6 @@ type ExecuteCommandOption func(*ExecuteCommandConfig) error
 func ExecuteCommandTimeout(timeout time.Duration) ExecuteCommandOption {
 	return ExecuteCommandOption(func(conf *ExecuteCommandConfig) error {
 		conf.timeout = timeout
-
 		return nil
 	})
 }
@@ -67,6 +67,7 @@ func ExecuteCommand(
 				StdErr: &stderr,
 			},
 		)
+
 		resultChan <- result{exitCode, err}
 	}()
 
@@ -88,7 +89,6 @@ func ExecuteCommand(
 
 		return stdout.String(), stderr.String(), nil
 	case <-time.After(execConfig.timeout):
-
 		return stdout.String(), stderr.String(), ErrDockertestCommandTimeout
 	}
 }

integration/scenario.go

@@ -351,18 +351,22 @@ func (s *Scenario) CreateTailscaleNodesInUser(
 			cert := headscale.GetCert()
 			hostname := headscale.GetHostname()
 
+			s.mu.Lock()
 			opts = append(opts,
 				tsic.WithHeadscaleTLS(cert),
 				tsic.WithHeadscaleName(hostname),
 			)
+			s.mu.Unlock()
 
 			user.createWaitGroup.Go(func() error {
+				s.mu.Lock()
 				tsClient, err := tsic.New(
 					s.pool,
 					version,
 					s.network,
 					opts...,
 				)
+				s.mu.Unlock()
 				if err != nil {
 					return fmt.Errorf(
 						"failed to create tailscale (%s) node: %w",

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