Restructure headscale documentation (#2163)
* Setup mkdocs-redirects * Restructure existing documentation * Move client OS support into the documentation * Move existing Client OS support table into its own documentation page * Link from README.md to the rendered documentation * Document minimum Tailscale client version * Reuse CONTRIBUTING.md" in the documentation * Include "CONTRIBUTING.md" from the repository root * Update FAQ and index page and link to the contributing docs * Add configuration reference * Add a getting started page and explain the first steps with headscale * Use the existing "Using headscale" sections and combine them into a single getting started guide with a little bit more explanation. * Explain how to get help from the command line client. * Remove duplicated sections from existing installation guides * Document requirements and assumptions * Document packages provided by the community * Move deb install guide to official releases * Move manual install guide to official releases * Move container documentation to setup section * Move sealos documentation to cloud install page * Move OpenBSD docs to build from source * Simplify DNS documentation * Add sponsor page * Add releases page * Add features page * Add help page * Add upgrading page * Adjust mkdocs nav * Update wording Use the term headscale for the project, Headscale on the beginning of a sentence and `headscale` when refering to the CLI. * Welcome to headscale * Link to existing documentation in the FAQ * Remove the goal header and use the text as opener * Indent code block in OIDC * Make a few pages linter compatible Also update ignored files for prettier * Recommend HTTPS on port 443 Fixes: #2164 * Use hosts in acl documentation thx @efficacy38 for noticing this Ref: #1863 * Use mkdocs-macros to set headscale version once
This commit is contained in:
nblock
GitHub
parent
b3cda08af6
commit
8c7d8ee34f
41 changed files with 865 additions and 940 deletions
14
docs/usage/connect/android.md
Normal file
14
docs/usage/connect/android.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
# Connecting an Android client
|
||||
|
||||
This documentation has the goal of showing how a user can use the official Android [Tailscale](https://tailscale.com) client with headscale.
|
||||
|
||||
## Installation
|
||||
|
||||
Install the official Tailscale Android client from the [Google Play Store](https://play.google.com/store/apps/details?id=com.tailscale.ipn) or [F-Droid](https://f-droid.org/packages/com.tailscale.ipn/).
|
||||
|
||||
## Configuring the headscale URL
|
||||
|
||||
- Open the app and select the settings menu in the upper-right corner
|
||||
- Tap on `Accounts`
|
||||
- In the kebab menu icon (three dots) in the upper-right corner select `Use an alternate server`
|
||||
- Enter your server URL (e.g `https://headscale.example.com`) and follow the instructions
|
||||
49
docs/usage/connect/apple.md
Normal file
49
docs/usage/connect/apple.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
# Connecting an Apple client
|
||||
|
||||
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
|
||||
59
docs/usage/connect/windows.md
Normal file
59
docs/usage/connect/windows.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Connecting a Windows client
|
||||
|
||||
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
|
||||
|
||||
Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g
|
||||
`https://headscale.example.com`):
|
||||
|
||||
```
|
||||
tailscale login --login-server <YOUR_HEADSCALE_URL>
|
||||
```
|
||||
|
||||
Follow the instructions in the opened browser window to finish the configuration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Unattended mode
|
||||
|
||||
By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running
|
||||
all the time, please enable "Unattended mode":
|
||||
|
||||
- Click on the Tailscale tray icon and select `Preferences`
|
||||
- Enable `Run unattended`
|
||||
- Confirm the "Unattended mode" message
|
||||
|
||||
See also [Keep Tailscale running when I'm not logged in to my computer](https://tailscale.com/kb/1088/run-unattended)
|
||||
|
||||
### Failing node registration
|
||||
|
||||
If you are seeing repeated messages like:
|
||||
|
||||
```
|
||||
[GIN] 2022/02/10 - 16:39:34 | 200 | 1.105306ms | 127.0.0.1 | POST "/machine/redacted"
|
||||
```
|
||||
|
||||
in your headscale output, turn on `DEBUG` logging and look for:
|
||||
|
||||
```
|
||||
2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
|
||||
```
|
||||
|
||||
This typically means that the registry keys above was not set appropriately.
|
||||
|
||||
To reset and try again, it is important to do the following:
|
||||
|
||||
1. Shut down the Tailscale service (or the client running in the tray)
|
||||
2. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
|
||||
3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
|
||||
4. Start Tailscale on the Windows machine and retry the login.
|
||||
132
docs/usage/getting-started.md
Normal file
132
docs/usage/getting-started.md
Normal file
|
|
@ -0,0 +1,132 @@
|
|||
# Getting started
|
||||
|
||||
This page helps you get started with headscale and provides a few usage examples for the headscale command line tool
|
||||
`headscale`.
|
||||
|
||||
!!! note "Prerequisites"
|
||||
|
||||
* Headscale is installed and running as system service. Read the [setup section](../setup/requirements.md) for
|
||||
installation instructions.
|
||||
* The configuration file exists and is adjusted to suit your environment, see
|
||||
[Configuration](../ref/configuration.md) for details.
|
||||
* The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more
|
||||
information.
|
||||
|
||||
## Getting help
|
||||
|
||||
The `headscale` command line tool provides built-in help. To show available commands along with their arguments and
|
||||
options, run:
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
# Show help
|
||||
headscale help
|
||||
|
||||
# Show help for a specific command
|
||||
headscale <COMMAND> --help
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
# Show help
|
||||
docker exec -it headscale \
|
||||
headscale help
|
||||
|
||||
# Show help for a specific command
|
||||
docker exec -it headscale \
|
||||
headscale <COMMAND> --help
|
||||
```
|
||||
|
||||
## Manage users
|
||||
|
||||
In headscale, a node (also known as machine or device) is always assigned to a specific user, a
|
||||
[tailnet](https://tailscale.com/kb/1136/tailnet/). Such users can be managed with the `headscale users` command. Invoke
|
||||
the built-in help for more information: `headscale users --help`.
|
||||
|
||||
### Create a user
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale users create <USER>
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale users create <USER>
|
||||
```
|
||||
|
||||
### List existing users
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale users list
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale users list
|
||||
```
|
||||
|
||||
## Register a node
|
||||
|
||||
One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the
|
||||
Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect
|
||||
[Android](connect/android.md), [Apple](connect/apple.md) or [Windows](connect/windows.md) devices.
|
||||
|
||||
### Normal, interactive login
|
||||
|
||||
On a client machine, run the `tailscale up` command and provide the FQDN of your headscale instance as argument:
|
||||
|
||||
```shell
|
||||
tailscale up --login-server <YOUR_HEADSCALE_URL>
|
||||
```
|
||||
|
||||
Usually, a browser window with further instructions is opened and contains the value for `<YOUR_MACHINE_KEY>`. Approve
|
||||
and register the node on your headscale server:
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
|
||||
```
|
||||
|
||||
### Using a preauthkey
|
||||
|
||||
It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the
|
||||
headscale instance. By default, the key is valid for one hour and can only be used once (see `headscale preauthkeys
|
||||
--help` for other options):
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale preauthkeys create --user <USER>
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale preauthkeys create --user <USER>
|
||||
```
|
||||
|
||||
The command returns the preauthkey on success which is used to connect a node to the headscale instance via the
|
||||
`tailscale up` command:
|
||||
|
||||
```shell
|
||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue