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
This commit is contained in:
nblock 2024-09-11 18:43:59 +02:00 committed by GitHub
parent 064c46f2a5
commit c3ef90a7f7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 112 additions and 130 deletions

View file

@ -62,15 +62,15 @@ buttons available in the repo.
## Client OS support ## Client OS support
| OS | Supports headscale | | OS | Supports headscale |
| ------- | --------------------------------------------------------- | | ------- | -------------------------------------------------------------------------------------------------- |
| Linux | Yes | | Linux | Yes |
| OpenBSD | Yes | | OpenBSD | Yes |
| FreeBSD | Yes | | FreeBSD | Yes |
| macOS | Yes (see `/apple` on your headscale for more information) | | Windows | Yes (see [docs](./docs/windows-client.md) and `/windows` on your headscale for more information) |
| Windows | Yes [docs](./docs/windows-client.md) | | Android | Yes (see [docs](./docs/android-client.md)) |
| Android | Yes [docs](./docs/android-client.md) | | macOS | Yes (see [docs](./docs/apple-client.md#macos) and `/apple` on your headscale for more information) |
| iOS | Yes [docs](./docs/iOS-client.md) | | iOS | Yes (see [docs](./docs/apple-client.md#ios) and `/apple` on your headscale for more information) |
## Running headscale ## Running headscale

51
docs/apple-client.md Normal file
View file

@ -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 <YOUR_HEADSCALE_URL>
```
#### 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

View file

@ -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.

View file

@ -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`. 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 ## Installation
Download the [Official Windows Client](https://tailscale.com/download/windows) and install it. Download the [Official Windows Client](https://tailscale.com/download/windows) and install it.
## Configuring the headscale URL ## 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 Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g
`https://headscale.example.com`): `https://headscale.example.com`):

View file

@ -25,17 +25,48 @@
</head> </head>
<body> <body>
<h1>headscale: iOS configuration</h1>
<h2>GUI</h2>
<ol>
<li>
Install the official Tailscale iOS client from the
<a href="https://apps.apple.com/app/tailscale/id1470499037"
>App store</a
>
</li>
<li>
Open Tailscale and make sure you are <i>not</i> logged in to any account
</li>
<li>Open Settings on the iOS device</li>
<li>
Scroll down to the "third party apps" section, under "Game Center" or
"TV Provider"
</li>
<li>
Find Tailscale and select it
<ul>
<li>
If the iOS device was previously logged into Tailscale, switch the
"Reset Keychain" toggle to "on"
</li>
</ul>
</li>
<li>Enter "{{.URL}}" under "Alternate Coordination Server URL"</li>
<li>
Restart the app by closing it from the iOS app switcher, open the app
and select the regular sign in option <i>(non-SSO)</i>. It should open
up to the headscale authentication page.
</li>
<li>
Enter your credentials and log in. Headscale should now be working on
your iOS device
</li>
</ol>
<h1>headscale: macOS configuration</h1> <h1>headscale: macOS configuration</h1>
<h2>Recent Tailscale versions (1.34.0 and higher)</h2> <h2>Command line</h2>
<p>
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.
</p>
<h3>Command line</h3>
<p>Use Tailscale's login command to add your profile:</p> <p>Use Tailscale's login command to add your profile:</p>
<pre><code>tailscale login --login-server {{.URL}}</code></pre> <pre><code>tailscale login --login-server {{.URL}}</code></pre>
<h3>GUI</h3> <h2>GUI</h2>
<ol> <ol>
<li> <li>
ALT + Click the Tailscale icon in the menu and hover over the Debug menu ALT + Click the Tailscale icon in the menu and hover over the Debug menu
@ -46,44 +77,7 @@
</li> </li>
<li>Follow the login procedure in the browser</li> <li>Follow the login procedure in the browser</li>
</ol> </ol>
<h2>Apple configuration profiles (1.32.0 and lower)</h2>
<p>
This page provides
<a href="https://support.apple.com/guide/mdm/mdm-overview-mdmbf9e668/web"
>configuration profiles</a
>
for the official Tailscale clients for
</p>
<ul>
<li>
<a href="https://apps.apple.com/app/tailscale/id1475387142"
>macOS - AppStore Client</a
>.
</li>
<li>
<a href="https://pkgs.tailscale.com/stable/#macos"
>macOS - Standalone Client</a
>.
</li>
</ul>
<p>
The profiles will configure Tailscale.app to use <code>{{.URL}}</code> as
its control server.
</p>
<h3>Caution</h3>
<p>
You should always download and inspect the profile before installing it:
</p>
<ul>
<li>
for app store client: <code>curl {{.URL}}/apple/macos-app-store</code>
</li>
<li>
for standalone client: <code>curl {{.URL}}/apple/macos-standalone</code>
</li>
</ul>
<h2>Profiles</h2> <h2>Profiles</h2>
<h3>macOS</h3>
<p> <p>
Headscale can be set to the default server by installing a Headscale Headscale can be set to the default server by installing a Headscale
configuration profile: configuration profile:
@ -121,50 +115,17 @@
</li> </li>
</ul> </ul>
<p>Restart Tailscale.app and log in.</p> <p>Restart Tailscale.app and log in.</p>
<h1>headscale: iOS configuration</h1> <h3>Caution</h3>
<h2>Recent Tailscale versions (1.38.1 and higher)</h2>
<p> <p>
Tailscale 1.38.1 on You should always download and inspect the profile before installing it:
<a href="https://apps.apple.com/app/tailscale/id1470499037">iOS</a>
added a configuration option to allow user to set an "Alternate
Coordination server". This can be used to connect to your headscale
server.
</p> </p>
<h3>GUI</h3> <ul>
<ol>
<li> <li>
Install the official Tailscale iOS client from the for app store client: <code>curl {{.URL}}/apple/macos-app-store</code>
<a href="https://apps.apple.com/app/tailscale/id1470499037"
>App store</a
>
</li> </li>
<li> <li>
Open Tailscale and make sure you are <i>not</i> logged in to any account for standalone client: <code>curl {{.URL}}/apple/macos-standalone</code>
</li> </li>
<li>Open Settings on the iOS device</li> </ul>
<li>
Scroll down to the "third party apps" section, under "Game Center" or
"TV Provider"
</li>
<li>
Find Tailscale and select it
<ul>
<li>
If the iOS device was previously logged into Tailscale, switch the
"Reset Keychain" toggle to "on"
</li>
</ul>
</li>
<li>Enter "{{.URL}}" under "Alternate Coordination Server URL"</li>
<li>
Restart the app by closing it from the iOS app switcher, open the app
and select the regular sign in option <i>(non-SSO)</i>. It should open
up to the headscale authentication page.
</li>
<li>
Enter your credentials and log in. Headscale should now be working on
your iOS device
</li>
</ol>
</body> </body>
</html> </html>

View file

@ -7,7 +7,7 @@ import (
) )
// This file is intended to "test the test framework", by proxy it will also test // 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) { func IntegrationSkip(t *testing.T) {
t.Helper() t.Helper()

View file

@ -139,5 +139,5 @@ nav:
- Remote CLI: remote-cli.md - Remote CLI: remote-cli.md
- Usage: - Usage:
- Android: android-client.md - Android: android-client.md
- Apple: apple-client.md
- Windows: windows-client.md - Windows: windows-client.md
- iOS: iOS-client.md