From a71a933705ad0171709ae6bf0c6bc4402c30ca2f Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Mon, 4 Nov 2024 10:12:50 -0600 Subject: [PATCH 01/11] add nblock to doc owners (#2207) Signed-off-by: Kristoffer Dalby --- .github/CODEOWNERS | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index fa1c06da..4eb9c2d2 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,10 +1,10 @@ * @juanfont @kradalby -*.md @ohdearaugustin -*.yml @ohdearaugustin -*.yaml @ohdearaugustin -Dockerfile* @ohdearaugustin -.goreleaser.yaml @ohdearaugustin -/docs/ @ohdearaugustin -/.github/workflows/ @ohdearaugustin -/.github/renovate.json @ohdearaugustin +*.md @ohdearaugustin @nblock +*.yml @ohdearaugustin @nblock +*.yaml @ohdearaugustin @nblock +Dockerfile* @ohdearaugustin @nblock +.goreleaser.yaml @ohdearaugustin @nblock +/docs/ @ohdearaugustin @nblock +/.github/workflows/ @ohdearaugustin @nblock +/.github/renovate.json @ohdearaugustin @nblock From 9a46c5763c5a9ddeb324d400cb6edbbbaed26221 Mon Sep 17 00:00:00 2001 From: nblock Date: Wed, 6 Nov 2024 15:59:38 +0100 Subject: [PATCH 02/11] Handle /derp/latency-check (#2227) According to https://github.com/tailscale/tailscale/commit/15fc6cd96637e8a0e697ff2157c1608ada8e4a39 the routes `/derp/probe` and `/derp/latency-check` are the same and different versions of the tailscale client use one or the other endpoint. Also handle /derp/latency-check Fixes: #2211 --- hscontrol/app.go | 1 + hscontrol/metrics.go | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/hscontrol/app.go b/hscontrol/app.go index 5c85b064..737e8098 100644 --- a/hscontrol/app.go +++ b/hscontrol/app.go @@ -460,6 +460,7 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *mux.Router { if h.cfg.DERP.ServerEnabled { router.HandleFunc("/derp", h.DERPServer.DERPHandler) router.HandleFunc("/derp/probe", derpServer.DERPProbeHandler) + router.HandleFunc("/derp/latency-check", derpServer.DERPProbeHandler) router.HandleFunc("/bootstrap-dns", derpServer.DERPBootstrapDNSHandler(h.DERPMap)) } diff --git a/hscontrol/metrics.go b/hscontrol/metrics.go index 0be59eec..cb01838c 100644 --- a/hscontrol/metrics.go +++ b/hscontrol/metrics.go @@ -78,7 +78,7 @@ func prometheusMiddleware(next http.Handler) http.Handler { // Ignore streaming and noise sessions // it has its own router further down. - if path == "/ts2021" || path == "/machine/map" || path == "/derp" || path == "/derp/probe" || path == "/bootstrap-dns" { + if path == "/ts2021" || path == "/machine/map" || path == "/derp" || path == "/derp/probe" || path == "/derp/latency-check" || path == "/bootstrap-dns" { next.ServeHTTP(w, r) return } From 0089ceaf1dc781fb07939ca4dc3cd28efc333b31 Mon Sep 17 00:00:00 2001 From: Philip Henning Date: Thu, 7 Nov 2024 15:56:18 +0100 Subject: [PATCH 03/11] Feature tvos documentation (#2226) * Add usage documentation for tvOS * lint and format * Change admonition to mkdocs flavoured style * fix typos * Update hscontrol/templates/apple.go Co-authored-by: Kristoffer Dalby * change outer quoting for where quoting in-text is used --------- Co-authored-by: Kristoffer Dalby --- docs/about/clients.md | 1 + docs/usage/connect/apple.md | 20 ++++ hscontrol/templates/apple.go | 183 ++++++++++++++++++++++++++++------- 3 files changed, 169 insertions(+), 35 deletions(-) diff --git a/docs/about/clients.md b/docs/about/clients.md index eafb2946..cb8e4b6d 100644 --- a/docs/about/clients.md +++ b/docs/about/clients.md @@ -13,3 +13,4 @@ headscale. | Android | Yes (see [docs](../usage/connect/android.md)) | | macOS | Yes (see [docs](../usage/connect/apple.md#macos) and `/apple` on your headscale for more information) | | iOS | Yes (see [docs](../usage/connect/apple.md#ios) and `/apple` on your headscale for more information) | +| tvOS | Yes (see [docs](../usage/connect/apple.md#tvos) and `/apple` on your headscale for more information) | diff --git a/docs/usage/connect/apple.md b/docs/usage/connect/apple.md index 7597c717..5ebecb15 100644 --- a/docs/usage/connect/apple.md +++ b/docs/usage/connect/apple.md @@ -47,3 +47,23 @@ tailscale login --login-server - Under `Custom Login Server`, select `Add Account...` - Enter the URL of your headscale instance (e.g `https://headscale.example.com`) and press `Add Account` - Follow the login procedure in the browser + +## tvOS + +### Installation + +Install the official Tailscale tvOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037). + +!!! danger + + **Don't** open the Tailscale App after installation! + +### Configuring the headscale URL + +- Go Settings (the apple tvOS settings) > Apps > Tailscale +- Under `ALTERNATE COORDINATION SERVER URL`, select `URL` +- Enter the URL of your headscale instance (e.g `https://headscale.example.com`) and press `OK` +- Return to the tvOS Home screen +- Open Tailscale +- Click the button `Install VPN configuration` and confirm the appearing popup by clicking the `Allow` button +- Scan the QR code and follow the login procedure diff --git a/hscontrol/templates/apple.go b/hscontrol/templates/apple.go index 93f0034d..8b289d22 100644 --- a/hscontrol/templates/apple.go +++ b/hscontrol/templates/apple.go @@ -17,9 +17,13 @@ func Apple(url string) *elem.Element { headerOne("headscale: iOS configuration"), headerTwo("GUI"), elem.Ol(nil, - elem.Li(nil, + elem.Li( + nil, elem.Text("Install the official Tailscale iOS client from the "), - elem.A(attrs.Props{attrs.Href: "https://apps.apple.com/app/tailscale/id1470499037"}, + elem.A( + attrs.Props{ + attrs.Href: "https://apps.apple.com/app/tailscale/id1470499037", + }, elem.Text("App store"), ), ), @@ -31,27 +35,47 @@ func Apple(url string) *elem.Element { elem.Li(nil, elem.Text("Open Settings on the iOS device"), ), - elem.Li(nil, - elem.Text(`Scroll down to the "third party apps" section, under "Game Center" or "TV Provider"`), + elem.Li( + nil, + elem.Text( + `Scroll down to the "third party apps" section, under "Game Center" or "TV Provider"`, + ), ), elem.Li(nil, elem.Text("Find Tailscale and select it"), elem.Ul(nil, - elem.Li(nil, - elem.Text(`If the iOS device was previously logged into Tailscale, switch the "Reset Keychain" toggle to "on"`), + elem.Li( + nil, + elem.Text( + `If the iOS device was previously logged into Tailscale, switch the "Reset Keychain" toggle to "on"`, + ), ), ), ), - elem.Li(nil, - elem.Text(fmt.Sprintf(`Enter "%s" under "Alternate Coordination Server URL"`,url)), + elem.Li( + nil, + elem.Text( + fmt.Sprintf( + `Enter "%s" under "Alternate Coordination Server URL"`, + url, + ), + ), ), - elem.Li(nil, - elem.Text("Restart the app by closing it from the iOS app switcher, open the app and select the regular sign in option "), + elem.Li( + nil, + elem.Text( + "Restart the app by closing it from the iOS app switcher, open the app and select the regular sign in option ", + ), elem.I(nil, elem.Text("(non-SSO)")), - elem.Text(". It should open up to the headscale authentication page."), + elem.Text( + ". It should open up to the headscale authentication page.", + ), ), - elem.Li(nil, - elem.Text("Enter your credentials and log in. Headscale should now be working on your iOS device"), + elem.Li( + nil, + elem.Text( + "Enter your credentials and log in. Headscale should now be working on your iOS device", + ), ), ), headerOne("headscale: macOS configuration"), @@ -61,39 +85,63 @@ func Apple(url string) *elem.Element { ), elem.Pre(nil, elem.Code(nil, - elem.Text(fmt.Sprintf("tailscale login --login-server %s",url)), + elem.Text(fmt.Sprintf("tailscale login --login-server %s", url)), ), ), headerTwo("GUI"), elem.Ol(nil, - elem.Li(nil, - elem.Text("ALT + Click the Tailscale icon in the menu and hover over the Debug menu"), + elem.Li( + nil, + elem.Text( + "ALT + Click the Tailscale icon in the menu and hover over the Debug menu", + ), ), elem.Li(nil, elem.Text(`Under "Custom Login Server", select "Add Account..."`), ), - elem.Li(nil, - elem.Text(fmt.Sprintf(`Enter "%s" of the headscale instance and press "Add Account"`,url)), + elem.Li( + nil, + elem.Text( + fmt.Sprintf( + `Enter "%s" of the headscale instance and press "Add Account"`, + url, + ), + ), ), elem.Li(nil, elem.Text(`Follow the login procedure in the browser`), ), ), headerTwo("Profiles"), - elem.P(nil, - elem.Text("Headscale can be set to the default server by installing a Headscale configuration profile:"), + elem.P( + nil, + elem.Text( + "Headscale can be set to the default server by installing a Headscale configuration profile:", + ), ), - elem.P(nil, - elem.A(attrs.Props{attrs.Href: "/apple/macos-app-store", attrs.Download: "headscale_macos.mobileconfig"}, + elem.P( + nil, + elem.A( + attrs.Props{ + attrs.Href: "/apple/macos-app-store", + attrs.Download: "headscale_macos.mobileconfig", + }, elem.Text("macOS AppStore profile "), ), - elem.A(attrs.Props{attrs.Href: "/apple/macos-standalone", attrs.Download: "headscale_macos.mobileconfig"}, + elem.A( + attrs.Props{ + attrs.Href: "/apple/macos-standalone", + attrs.Download: "headscale_macos.mobileconfig", + }, elem.Text("macOS Standalone profile"), ), ), elem.Ol(nil, - elem.Li(nil, - elem.Text("Download the profile, then open it. When it has been opened, there should be a notification that a profile can be installed"), + elem.Li( + nil, + elem.Text( + "Download the profile, then open it. When it has been opened, there should be a notification that a profile can be installed", + ), ), elem.Li(nil, elem.Text(`Open System Preferences and go to "Profiles"`), @@ -106,20 +154,35 @@ func Apple(url string) *elem.Element { ), ), elem.P(nil, elem.Text("Or")), - elem.P(nil, - elem.Text("Use your terminal to configure the default setting for Tailscale by issuing:"), + elem.P( + nil, + elem.Text( + "Use your terminal to configure the default setting for Tailscale by issuing:", + ), ), elem.Ul(nil, elem.Li(nil, elem.Text(`for app store client:`), - elem.Code(nil, - elem.Text(fmt.Sprintf(`defaults write io.tailscale.ipn.macos ControlURL %s`,url)), + elem.Code( + nil, + elem.Text( + fmt.Sprintf( + `defaults write io.tailscale.ipn.macos ControlURL %s`, + url, + ), + ), ), ), elem.Li(nil, elem.Text(`for standalone client:`), - elem.Code(nil, - elem.Text(fmt.Sprintf(`defaults write io.tailscale.ipn.macsys ControlURL %s`,url)), + elem.Code( + nil, + elem.Text( + fmt.Sprintf( + `defaults write io.tailscale.ipn.macsys ControlURL %s`, + url, + ), + ), ), ), ), @@ -127,23 +190,73 @@ func Apple(url string) *elem.Element { elem.Text("Restart Tailscale.app and log in."), ), headerThree("Caution"), - elem.P(nil, - elem.Text("You should always download and inspect the profile before installing it:"), + elem.P( + nil, + elem.Text( + "You should always download and inspect the profile before installing it:", + ), ), elem.Ul(nil, elem.Li(nil, elem.Text(`for app store client: `), elem.Code(nil, - elem.Text(fmt.Sprintf(`curl %s/apple/macos-app-store`,url)), + elem.Text(fmt.Sprintf(`curl %s/apple/macos-app-store`, url)), ), ), elem.Li(nil, elem.Text(`for standalone client: `), elem.Code(nil, - elem.Text(fmt.Sprintf(`curl %s/apple/macos-standalone`,url)), + elem.Text(fmt.Sprintf(`curl %s/apple/macos-standalone`, url)), ), ), ), + headerOne("headscale: tvOS configuration"), + headerTwo("GUI"), + elem.Ol(nil, + elem.Li( + nil, + elem.Text("Install the official Tailscale tvOS client from the "), + elem.A( + attrs.Props{ + attrs.Href: "https://apps.apple.com/app/tailscale/id1470499037", + }, + elem.Text("App store"), + ), + ), + elem.Li( + nil, + elem.Text( + "Open Settings (the Apple tvOS settings) > Apps > Tailscale", + ), + ), + elem.Li( + nil, + elem.Text( + fmt.Sprintf( + `Enter "%s" under "ALTERNATE COORDINATION SERVER URL"`, + url, + ), + ), + ), + elem.Li(nil, + elem.Text("Return to the tvOS Home screen"), + ), + elem.Li(nil, + elem.Text("Open Tailscale"), + ), + elem.Li(nil, + elem.Text(`Select "Install VPN configuration"`), + ), + elem.Li(nil, + elem.Text(`Select "Allow"`), + ), + elem.Li(nil, + elem.Text("Scan the QR code and follow the login procedure"), + ), + elem.Li(nil, + elem.Text("Headscale should now be working on your tvOS device"), + ), + ), ), ) } From 4e44d57bf79b4f3998be47ac4c85361cbd62a70d Mon Sep 17 00:00:00 2001 From: docgalaxyblock Date: Mon, 11 Nov 2024 07:06:44 +0100 Subject: [PATCH 04/11] fix: missing stable-debug tag (#2232) Fixes #2171 --- .goreleaser.yml | 4 ++-- CHANGELOG.md | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.goreleaser.yml b/.goreleaser.yml index 4aabde4b..51f8000f 100644 --- a/.goreleaser.yml +++ b/.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" diff --git a/CHANGELOG.md b/CHANGELOG.md index 465adc87..3d435d04 100644 --- a/CHANGELOG.md +++ b/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) From 8cfaa6bdac4b1fb44e867c0a33005b1da9b35eba Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 12 Nov 2024 13:27:49 +0000 Subject: [PATCH 05/11] flake.lock: Update (#2222) --- flake.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/flake.lock b/flake.lock index 56382fbf..d6fa2722 100644 --- 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": { From 2345c38e1e138f8ccc1e69234e7a342244044bab Mon Sep 17 00:00:00 2001 From: nblock Date: Tue, 12 Nov 2024 16:53:30 +0100 Subject: [PATCH 06/11] Add a page for third-party tools (#2217) * 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 --- docs/ref/integration/tools.md | 12 ++++++++++++ docs/ref/integration/web-ui.md | 20 +++++++++++--------- docs/setup/install/community.md | 2 +- mkdocs.yml | 1 + 4 files changed, 25 insertions(+), 10 deletions(-) create mode 100644 docs/ref/integration/tools.md diff --git a/docs/ref/integration/tools.md b/docs/ref/integration/tools.md new file mode 100644 index 00000000..9e8b7176 --- /dev/null +++ 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 | diff --git a/docs/ref/integration/web-ui.md b/docs/ref/integration/web-ui.md index cf06a77d..9f6077e0 100644 --- 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). diff --git a/docs/setup/install/community.md b/docs/setup/install/community.md index f9d7cc18..8fb71803 100644 --- 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: . The site provides detailed setup and installation instructions. diff --git a/mkdocs.yml b/mkdocs.yml index d01c94cc..352c8d39 100644 --- 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 From e7245856c53a638532b494d36985a944c6d942a8 Mon Sep 17 00:00:00 2001 From: nblock Date: Wed, 13 Nov 2024 18:35:42 +0100 Subject: [PATCH 07/11] 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 --- .prettierignore | 1 + docs/ref/remote-cli.md | 71 +++++++++++++++++++++++------------------- 2 files changed, 40 insertions(+), 32 deletions(-) diff --git a/.prettierignore b/.prettierignore index 4b873f49..37333d8d 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1,3 @@ .github/workflows/test-integration-v2* docs/about/features.md +docs/ref/remote-cli.md diff --git a/docs/ref/remote-cli.md b/docs/ref/remote-cli.md index 041d46c4..d50359c2 100644 --- 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 "" ## 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 "" 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=":" - export HEADSCALE_CLI_API_KEY="" - ``` + === "Minimal YAML configuration file" - for example: + ```yaml + cli: + address: : + api_key: + ``` - ```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=":" + export HEADSCALE_CLI_API_KEY="" + ``` - 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 `:`, 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. From a7874af3d0ba48913fa7e5fbffbb38b537bae7b3 Mon Sep 17 00:00:00 2001 From: nblock Date: Sat, 16 Nov 2024 07:06:15 +0100 Subject: [PATCH 08/11] Use discord server invite link (#2235) Replace channel links with links to discord invite link and remove channel list. Fixes: #1521 --- CODE_OF_CONDUCT.md | 2 +- README.md | 2 +- docs/about/faq.md | 10 ++++++---- docs/about/help.md | 8 +------- docs/about/releases.md | 3 +-- docs/index.md | 2 +- docs/ref/integration/web-ui.md | 2 +- 7 files changed, 12 insertions(+), 17 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 14844982..722a543e 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -62,7 +62,7 @@ event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement -at our Discord channel. All complaints +on our [Discord server](https://discord.gg/c84AZQhmpx). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and diff --git a/README.md b/README.md index 2994bd2d..62222e6a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ An open source, self-hosted implementation of the Tailscale control server. -Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat. +Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat. **Note:** Always select the same GitHub tag as the released version you use to ensure you have the correct example configuration and documentation. diff --git a/docs/about/faq.md b/docs/about/faq.md index 139e0117..e6d45df6 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -41,13 +41,15 @@ In addition to that, you may use packages provided by the community or from dist [installation guide using community packages](../setup/install/community.md). For convenience, we also [build Docker images with headscale](../setup/install/container.md). But **please be aware that -we don't officially support deploying headscale using Docker**. We have a [Discord -channel](https://discord.com/channels/896711691637780480/1070619770942148618) where you can ask for Docker-specific help -to the community. +we don't officially support deploying headscale using Docker**. On our [Discord server](https://discord.gg/c84AZQhmpx) +we have a "docker-issues" channel where you can ask for Docker-specific help to the community. ## Why is my reverse proxy not working with headscale? -We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have [community documentation](../ref/integration/reverse-proxy.md) on how to configure various reverse proxies, and a dedicated [Discord channel](https://discord.com/channels/896711691637780480/1070619818346164324) where you can ask for help to the community. +We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have +[community documentation](../ref/integration/reverse-proxy.md) on how to configure various reverse proxies, and a +dedicated "reverse-proxy-issues" channel on our [Discord server](https://discord.gg/c84AZQhmpx) where you can ask for +help to the community. ## Can I use headscale and tailscale on the same machine? diff --git a/docs/about/help.md b/docs/about/help.md index 71f47071..ec4adf6b 100644 --- a/docs/about/help.md +++ b/docs/about/help.md @@ -1,11 +1,5 @@ # Getting help -Join our Discord server for announcements and community support: - -- [announcements](https://discord.com/channels/896711691637780480/896711692120129538) -- [general](https://discord.com/channels/896711691637780480/896711692120129540) -- [docker-issues](https://discord.com/channels/896711691637780480/1070619770942148618) -- [reverse-proxy-issues](https://discord.com/channels/896711691637780480/1070619818346164324) -- [web-interfaces](https://discord.com/channels/896711691637780480/1105842846386356294) +Join our [Discord server](https://discord.gg/c84AZQhmpx) for announcements and community support. Please report bugs via [GitHub issues](https://github.com/juanfont/headscale/issues) diff --git a/docs/about/releases.md b/docs/about/releases.md index 718c0f53..ba632b95 100644 --- a/docs/about/releases.md +++ b/docs/about/releases.md @@ -6,5 +6,4 @@ code archives. Container images are available on [Docker Hub](https://hub.docker An Atom/RSS feed of headscale releases is available [here](https://github.com/juanfont/headscale/releases.atom). -Join the ["announcements" channel on Discord](https://discord.com/channels/896711691637780480/896711692120129538) for -news about headscale. +See the "announcements" channel on our [Discord server](https://discord.gg/c84AZQhmpx) for news about headscale. diff --git a/docs/index.md b/docs/index.md index 36c87a00..6f6ba188 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,7 @@ Headscale is an open source, self-hosted implementation of the Tailscale control This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md). -Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat and community support. +Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat and community support. ## Design goal diff --git a/docs/ref/integration/web-ui.md b/docs/ref/integration/web-ui.md index 9f6077e0..de86e5d7 100644 --- a/docs/ref/integration/web-ui.md +++ b/docs/ref/integration/web-ui.md @@ -16,4 +16,4 @@ Headscale doesn't provide a built-in web interface but users may pick one from t | 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). +You can ask for support on our [Discord server](https://discord.gg/c84AZQhmpx) in the "web-interfaces" channel. From 93ba21ede53b6f48c5f35fb50c3d04939cd20ce9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 17 Nov 2024 19:38:50 +0000 Subject: [PATCH 09/11] flake.lock: Update (#2239) --- flake.lock | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/flake.lock b/flake.lock index d6fa2722..9a85828e 100644 --- a/flake.lock +++ b/flake.lock @@ -5,11 +5,11 @@ "systems": "systems" }, "locked": { - "lastModified": 1726560853, - "narHash": "sha256-X6rJYSESBVr3hBoH0WbKE5KvhPU5bloyZ2L4K60/fPQ=", + "lastModified": 1731533236, + "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", "owner": "numtide", "repo": "flake-utils", - "rev": "c1dfcf08411b08f6b8615f7d8971a2bfa81d5e8a", + "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", "type": "github" }, "original": { @@ -20,11 +20,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1730958623, - "narHash": "sha256-JwQZIGSYnRNOgDDoIgqKITrPVil+RMWHsZH1eE1VGN0=", + "lastModified": 1731763621, + "narHash": "sha256-ddcX4lQL0X05AYkrkV2LMFgGdRvgap7Ho8kgon3iWZk=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "85f7e662eda4fa3a995556527c87b2524b691933", + "rev": "c69a9bffbecde46b4b939465422ddc59493d3e4d", "type": "github" }, "original": { From 29119bb7f4ef82fe4332f1c8d284ecb04e375078 Mon Sep 17 00:00:00 2001 From: nblock Date: Mon, 18 Nov 2024 05:46:58 +0100 Subject: [PATCH 10/11] Misc doc fixes (#2240) * Link back to node registration docs * adjust wording in apple docs * Mention client specific page to check if headscale works Ref: #2238 --- docs/ref/acls.md | 10 +++++----- docs/usage/connect/apple.md | 2 +- docs/usage/getting-started.md | 2 ++ 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/ref/acls.md b/docs/ref/acls.md index a621da5d..d7ceb629 100644 --- a/docs/ref/acls.md +++ b/docs/ref/acls.md @@ -45,11 +45,11 @@ headscale server. ACLs have to be written in [huJSON](https://github.com/tailscale/hujson). -When registering the servers we will need to add the flag -`--advertise-tags=tag:,tag:`, and the user that is -registering the server should be allowed to do it. Since anyone can add tags to -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 +When [registering the servers](../usage/getting-started.md#register-a-node) we +will need to add the flag `--advertise-tags=tag:,tag:`, and the user +that is registering the server should be allowed to do it. Since anyone can add +tags to 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 `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/). diff --git a/docs/usage/connect/apple.md b/docs/usage/connect/apple.md index 5ebecb15..a9aec72f 100644 --- a/docs/usage/connect/apple.md +++ b/docs/usage/connect/apple.md @@ -60,7 +60,7 @@ Install the official Tailscale tvOS client from the [App Store](https://apps.app ### Configuring the headscale URL -- Go Settings (the apple tvOS settings) > Apps > Tailscale +- Open Settings (the Apple tvOS settings) > Apps > Tailscale - Under `ALTERNATE COORDINATION SERVER URL`, select `URL` - Enter the URL of your headscale instance (e.g `https://headscale.example.com`) and press `OK` - Return to the tvOS Home screen diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md index d344156b..671cceb3 100644 --- a/docs/usage/getting-started.md +++ b/docs/usage/getting-started.md @@ -9,6 +9,8 @@ This page helps you get started with headscale and provides a few usage examples installation instructions. * The configuration file exists and is adjusted to suit your environment, see [Configuration](../ref/configuration.md) for details. + * Headscale is reachable from the Internet. Verify this by opening client specific setup instructions in your + browser, e.g. https://headscale.example.com/windows * The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more information. From 6275399327b2a00422aeb9399ea825c6258adcb6 Mon Sep 17 00:00:00 2001 From: Nathan Sweet Date: Mon, 18 Nov 2024 07:12:12 +0100 Subject: [PATCH 11/11] Update tls.md to mention using the full cert chain (#2243) --- docs/ref/tls.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ref/tls.md b/docs/ref/tls.md index 173399e4..23bc82a4 100644 --- a/docs/ref/tls.md +++ b/docs/ref/tls.md @@ -9,6 +9,8 @@ tls_cert_path: "" tls_key_path: "" ``` +The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it. + ## Let's Encrypt / ACME To get a certificate automatically via [Let's Encrypt](https://letsencrypt.org/), set `tls_letsencrypt_hostname` to the desired certificate hostname. This name must resolve to the IP address(es) headscale is reachable on (i.e., it must correspond to the `server_url` configuration parameter). The certificate and Let's Encrypt account credentials will be stored in the directory configured in `tls_letsencrypt_cache_dir`. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.