From c3ef90a7f7b9e742ce55100db8a9af44f8540c7d Mon Sep 17 00:00:00 2001 From: nblock Date: Wed, 11 Sep 2024 18:43:59 +0200 Subject: [PATCH] Update documentation for Apple (#2117) * Rename docs/ios-client.md to docs/apple-client.md. Add instructions for macOS; those are copied from the /apple endpoint and slightly modified. Fix doc links in the README. * Move infoboxes for /apple and /windows under the "Goal" section to the top. Those should be seen by users first as they contain *their* specific headscale URL. * Swap order of macOS and iOS to move "Profiles" further down. * Remove apple configuration profiles * Remove Tailscale versions hints * Mention /apple and /windows in the README along with their docs See: #2096 --- README.md | 18 ++--- docs/apple-client.md | 51 +++++++++++++ docs/iOS-client.md | 30 -------- docs/windows-client.md | 10 +-- hscontrol/templates/apple.html | 129 ++++++++++++--------------------- integration/scenario_test.go | 2 +- mkdocs.yml | 2 +- 7 files changed, 112 insertions(+), 130 deletions(-) create mode 100644 docs/apple-client.md delete mode 100644 docs/iOS-client.md diff --git a/README.md b/README.md index 03802e27..ff44e8e4 100644 --- a/README.md +++ b/README.md @@ -62,15 +62,15 @@ buttons available in the repo. ## Client OS support -| OS | Supports headscale | -| ------- | --------------------------------------------------------- | -| Linux | Yes | -| OpenBSD | Yes | -| FreeBSD | Yes | -| macOS | Yes (see `/apple` on your headscale for more information) | -| Windows | Yes [docs](./docs/windows-client.md) | -| Android | Yes [docs](./docs/android-client.md) | -| iOS | Yes [docs](./docs/iOS-client.md) | +| OS | Supports headscale | +| ------- | -------------------------------------------------------------------------------------------------- | +| Linux | Yes | +| OpenBSD | Yes | +| FreeBSD | Yes | +| Windows | Yes (see [docs](./docs/windows-client.md) and `/windows` on your headscale for more information) | +| Android | Yes (see [docs](./docs/android-client.md)) | +| macOS | Yes (see [docs](./docs/apple-client.md#macos) and `/apple` on your headscale for more information) | +| iOS | Yes (see [docs](./docs/apple-client.md#ios) and `/apple` on your headscale for more information) | ## Running headscale diff --git a/docs/apple-client.md b/docs/apple-client.md new file mode 100644 index 00000000..29ad4b45 --- /dev/null +++ b/docs/apple-client.md @@ -0,0 +1,51 @@ +# Connecting an Apple client + +## Goal + +This documentation has the goal of showing how a user can use the official iOS and macOS [Tailscale](https://tailscale.com) clients with `headscale`. + +!!! info "Instructions on your headscale instance" + + An endpoint with information on how to connect your Apple device + is also available at `/apple` on your running instance. + +## iOS + +### Installation + +Install the official Tailscale iOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037). + +### Configuring the headscale URL + +- Open Tailscale and make sure you are _not_ logged in to any account +- Open Settings on the iOS device +- Scroll down to the `third party apps` section, under `Game Center` or `TV Provider` +- Find Tailscale and select it + - If the iOS device was previously logged into Tailscale, switch the `Reset Keychain` toggle to `on` +- Enter the URL of your headscale instance (e.g `https://headscale.example.com`) under `Alternate Coordination Server URL` +- Restart the app by closing it from the iOS app switcher, open the app and select the regular sign in option + _(non-SSO)_. It should open up to the headscale authentication page. +- Enter your credentials and log in. Headscale should now be working on your iOS device. + +## macOS + +### Installation + +Choose one of the available [Tailscale clients for macOS](https://tailscale.com/kb/1065/macos-variants) and install it. + +### Configuring the headscale URL + +#### Command line + +Use Tailscale's login command to connect with your headscale instance (e.g `https://headscale.example.com`): + +``` +tailscale login --login-server +``` + +#### GUI + +- ALT + Click the Tailscale icon in the menu and hover over the Debug menu +- 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 diff --git a/docs/iOS-client.md b/docs/iOS-client.md deleted file mode 100644 index 761dfcf0..00000000 --- a/docs/iOS-client.md +++ /dev/null @@ -1,30 +0,0 @@ -# Connecting an iOS client - -## Goal - -This documentation has the goal of showing how a user can use the official iOS [Tailscale](https://tailscale.com) client with `headscale`. - -## Installation - -Install the official Tailscale iOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037). - -Ensure that the installed version is at least 1.38.1, as that is the first release to support alternate control servers. - -## Configuring the headscale URL - -!!! info "Apple devices" - - An endpoint with information on how to connect your Apple devices - (currently macOS only) is available at `/apple` on your running instance. - -Ensure that the tailscale app is logged out before proceeding. - -Go to iOS settings, scroll down past game center and tv provider to the tailscale app and select it. The headscale URL can be entered into the _"ALTERNATE COORDINATION SERVER URL"_ box. - -> **Note** -> -> If the app was previously logged into tailscale, toggle on the _Reset Keychain_ switch. - -Restart the app by closing it from the iOS app switcher, open the app and select the regular _Sign in_ option (non-SSO), and it should open up to the headscale authentication page. - -Enter your credentials and log in. Headscale should now be working on your iOS device. diff --git a/docs/windows-client.md b/docs/windows-client.md index ff4834b4..66c47279 100644 --- a/docs/windows-client.md +++ b/docs/windows-client.md @@ -4,17 +4,17 @@ This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with `headscale`. +!!! info "Instructions on your headscale instance" + + An endpoint with information on how to connect your Windows device + is also available at `/windows` on your running instance. + ## Installation Download the [Official Windows Client](https://tailscale.com/download/windows) and install it. ## Configuring the headscale URL -!!! info "Instructions on your headscale instance" - - An endpoint with information on how to connect your Windows device - is also available at `/windows` on your running instance. - Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g `https://headscale.example.com`): diff --git a/hscontrol/templates/apple.html b/hscontrol/templates/apple.html index 4064dced..9582594a 100644 --- a/hscontrol/templates/apple.html +++ b/hscontrol/templates/apple.html @@ -25,17 +25,48 @@ +

headscale: iOS configuration

+

GUI

+
    +
  1. + Install the official Tailscale iOS client from the + App store +
    2. +
  2. + Open Tailscale and make sure you are not logged in to any account +
    3. +
  3. Open Settings on the iOS device
    4. +
  4. + Scroll down to the "third party apps" section, under "Game Center" or + "TV Provider" +
    5. +
  5. + Find Tailscale and select it +
      +
    • + If the iOS device was previously logged into Tailscale, switch the + "Reset Keychain" toggle to "on" +
      • +
    +
    6. +
  6. Enter "{{.URL}}" under "Alternate Coordination Server URL"
    7. +
  7. + Restart the app by closing it from the iOS app switcher, open the app + and select the regular sign in option (non-SSO). It should open + up to the headscale authentication page. +
    8. +
  8. + Enter your credentials and log in. Headscale should now be working on + your iOS device +
    9. +

headscale: macOS configuration

-

Recent Tailscale versions (1.34.0 and higher)

-

- Tailscale added Fast User Switching in version 1.34 and you can now use - the new login command to connect to one or more headscale (and Tailscale) - servers. The previously used profiles does not have an effect anymore. -

-

Command line

+

Command line

Use Tailscale's login command to add your profile:

tailscale login --login-server {{.URL}}
-

GUI

+

GUI

  1. ALT + Click the Tailscale icon in the menu and hover over the Debug menu @@ -46,44 +77,7 @@
  2. Follow the login procedure in the browser
-

Apple configuration profiles (1.32.0 and lower)

-

- This page provides - configuration profiles - for the official Tailscale clients for -

- -

- The profiles will configure Tailscale.app to use {{.URL}} as - its control server. -

-

Caution

-

- You should always download and inspect the profile before installing it: -

-

Profiles

-

macOS

Headscale can be set to the default server by installing a Headscale configuration profile: @@ -121,50 +115,17 @@

Restart Tailscale.app and log in.

-

headscale: iOS configuration

-

Recent Tailscale versions (1.38.1 and higher)

+

Caution

- Tailscale 1.38.1 on - iOS - added a configuration option to allow user to set an "Alternate - Coordination server". This can be used to connect to your headscale - server. + You should always download and inspect the profile before installing it:

-

GUI

-
    +
    • - Install the official Tailscale iOS client from the - App store + for app store client: curl {{.URL}}/apple/macos-app-store
    • - Open Tailscale and make sure you are not logged in to any account + for standalone client: curl {{.URL}}/apple/macos-standalone
      • -
    • Open Settings on the iOS device
      • -
    • - Scroll down to the "third party apps" section, under "Game Center" or - "TV Provider" -
      • -
    • - Find Tailscale and select it -
        -
      • - If the iOS device was previously logged into Tailscale, switch the - "Reset Keychain" toggle to "on" -
        • -
      -
      • -
    • Enter "{{.URL}}" under "Alternate Coordination Server URL"
      • -
    • - Restart the app by closing it from the iOS app switcher, open the app - and select the regular sign in option (non-SSO). It should open - up to the headscale authentication page. -
      • -
    • - Enter your credentials and log in. Headscale should now be working on - your iOS device -
      • -
+ diff --git a/integration/scenario_test.go b/integration/scenario_test.go index ea941ed7..9db4c3a0 100644 --- a/integration/scenario_test.go +++ b/integration/scenario_test.go @@ -7,7 +7,7 @@ import ( ) // This file is intended to "test the test framework", by proxy it will also test -// some Headcsale/Tailscale stuff, but mostly in very simple ways. +// some Headscale/Tailscale stuff, but mostly in very simple ways. func IntegrationSkip(t *testing.T) { t.Helper() diff --git a/mkdocs.yml b/mkdocs.yml index b88cfcc4..fe5c0d64 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -139,5 +139,5 @@ nav: - Remote CLI: remote-cli.md - Usage: - Android: android-client.md + - Apple: apple-client.md - Windows: windows-client.md - - iOS: iOS-client.md