From 45670717e33b3e134351df3ae6772a9340fed646 Mon Sep 17 00:00:00 2001 From: Florian Preinstorfer Date: Tue, 20 Jan 2026 21:05:10 +0100 Subject: [PATCH] Add a page to describe supported registration methods --- docs/about/features.md | 6 +- docs/ref/acls.md | 4 +- docs/ref/registration.md | 141 ++++++++++++++++++++++++++++++++++ docs/usage/connect/android.md | 6 +- docs/usage/getting-started.md | 18 ++--- mkdocs.yml | 1 + 6 files changed, 159 insertions(+), 17 deletions(-) create mode 100644 docs/ref/registration.md diff --git a/docs/about/features.md b/docs/about/features.md index 83197d64..afc81792 100644 --- a/docs/about/features.md +++ b/docs/about/features.md @@ -5,9 +5,9 @@ to provide self-hosters and hobbyists with an open-source server they can use fo provides on overview of Headscale's feature and compatibility with the Tailscale control server: - [x] Full "base" support of Tailscale's features -- [x] Node registration - - [x] Interactive - - [x] Pre authenticated key +- [x] [Node registration](../ref/registration.md) + - [x] [Web authentication](../ref/registration.md#web-authentication) + - [x] [Pre authenticated key](../ref/registration.md#pre-authenticated-key) - [x] [DNS](../ref/dns.md) - [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns) - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers) diff --git a/docs/ref/acls.md b/docs/ref/acls.md index fff66715..503aa3ac 100644 --- a/docs/ref/acls.md +++ b/docs/ref/acls.md @@ -222,7 +222,7 @@ Allows access to the internet through [exit nodes](routes.md#exit-node). Can onl ### `autogroup:member` -Includes all untagged devices. +Includes all [personal (untagged) devices](registration.md/#identity-model). ```json { @@ -234,7 +234,7 @@ Includes all untagged devices. ### `autogroup:tagged` -Includes all devices that have at least one tag. +Includes all devices that [have at least one tag](registration.md/#identity-model). ```json { diff --git a/docs/ref/registration.md b/docs/ref/registration.md new file mode 100644 index 00000000..b8345577 --- /dev/null +++ b/docs/ref/registration.md @@ -0,0 +1,141 @@ +# Registration methods + +Headscale supports multiple ways to register a node. The preferred registration method depends on the identity of a node +and your use case. + +## Identity model + +Tailscale's identity model distinguishes between personal and tagged nodes: + +- A personal node (or user-owned node) is owned by a human and typically refers to end-user devices such as laptops, + workstations or mobile phones. End-user devices are managed by a single user. +- A tagged node (or service-based node or non-human node) provides services to the network. Common examples include web- + and database servers. Those nodes are typically managed by a team of users. Some additional restrictions apply for + tagged nodes, e.g. a tagged node is not allowed to [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh) into a + personal node. + +Headscale implements Tailscale's identity model and distinguishes between personal and tagged nodes where a personal +node is owned by a Headscale user and a tagged node is owned by a tag. Tagged devices are grouped under the special user +`tagged-devices`. + +## Registration methods + +There are two main ways to register new nodes, [web authentication](#web-authentication) and [registration with a pre +authenticated key](#pre-authenticated-key). Both methods can be used to register personal and tagged nodes. + +### Web authentication + +Web authentication is the default method to register a new node. It's interactive, where the client initiates the +registration and the Headscale administrator needs to approve the new node before it is allowed to join the network. A +node can be approved with: + +- Headscale CLI (described in this documentation) +- [Headscale API](api.md) +- Or delegated to an identity provider via [OpenID Connect](oidc.md) + +Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new user: + +```shell +headscale users create +``` + +=== "Personal devices" + + Run `tailscale up` to login your personal device: + + ```shell + tailscale up --login-server + ``` + + Usually, a browser window with further instructions is opened. This page explains how to complete the registration + on your Headscale server and it also prints the registration key required to approve the node: + + ```shell + headscale nodes register --user --key + ``` + + Congrations, the registration of your personal node is complete and it should be listed as "online" in the output of + `headscale nodes list`. The "User" column displays `` as the owner of the node. + +=== "Tagged devices" + + Your Headscale user needs to be authorized to register tagged devices. This authorization is specified in the + [`tagOwners`](https://tailscale.com/kb/1337/policy-syntax#tag-owners) section of the [ACL](acls.md). A simple + example looks like this: + + ```json title="The user alice can register nodes tagged with tag:server" + { + "tagOwners": { + "tag:server": ["alice@"] + }, + // more rules + } + ``` + + Run `tailscale up` and provide at least one tag to login a tagged device: + + ```shell + tailscale up --login-server --advertise-tags tag: + ``` + + Usually, a browser window with further instructions is opened. This page explains how to complete the registration + on your Headscale server and it also prints the registration key required to approve the node: + + ```shell + headscale nodes register --user --key + ``` + + Headscale checks that `` is allowed to register a node with the specified tag(s) and then transfers ownership + of the new node to the special user `tagged-devices`. The registration of a tagged node is complete and it should be + listed as "online" in the output of `headscale nodes list`. The "User" column displays `tagged-devices` as the owner + of the node. See the "Tags" column for the list of assigned tags. + +### Pre authenticated key + +Registration with a pre authenticated key (or auth key) is a non-interactive way to register a new node. The Headscale +administrator creates a preauthkey upfront and this preauthkey can then be used to register a node non-interactively. +Its best suited for automation. + +=== "Personal devices" + + A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user: + + ```shell + headscale users create + ``` + + Use the `headscale user list` command to learn its `` and create a new pre authenticated key for your user: + + ```shell + headscale preauthkeys create --user + ``` + + The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use + this auth key to register a node non-interactively: + + ```shell + tailscale up --login-server --authkey + ``` + + Congrations, the registration of your personal node is complete and it should be listed as "online" in the output of + `headscale nodes list`. The "User" column displays `` as the owner of the node. + +=== "Tagged devices" + + Create a new pre authenticated key and provide at least one tag: + + ```shell + headscale preauthkeys create --tags tag: + ``` + + The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use + this auth key to register a node non-interactively. You don't need to provide the `--advertise-tags` parameter as + the tags are automatically read from the pre authenticated key: + + ```shell + tailscale up --login-server --authkey + ``` + + The registration of a tagged node is complete and it should be listed as "online" in the output of `headscale nodes + list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of + assigned tags. diff --git a/docs/usage/connect/android.md b/docs/usage/connect/android.md index b6fa3a66..1a5f3c7c 100644 --- a/docs/usage/connect/android.md +++ b/docs/usage/connect/android.md @@ -6,7 +6,7 @@ This documentation has the goal of showing how a user can use the official Andro 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/). -## Connect via normal, interactive login +## Connect via web authentication - Open the app and select the settings menu in the upper-right corner - Tap on `Accounts` @@ -15,7 +15,7 @@ Install the official Tailscale Android client from the [Google Play Store](https - The client connects automatically as soon as the node registration is complete on headscale. Until then, nothing is visible in the server logs. -## Connect using a preauthkey +## Connect using a pre authenticated key - Open the app and select the settings menu in the upper-right corner - Tap on `Accounts` @@ -24,5 +24,5 @@ Install the official Tailscale Android client from the [Google Play Store](https - Open 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 auth key` -- Enter your [preauthkey generated from headscale](../getting-started.md#using-a-preauthkey) +- Enter your [preauthkey generated from headscale](../../ref/registration.md#pre-authenticated-key) - If needed, tap `Log in` on the main screen. You should now be connected to your headscale. diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md index 290651a7..7ab50cad 100644 --- a/docs/usage/getting-started.md +++ b/docs/usage/getting-started.md @@ -60,10 +60,9 @@ options, run: ## Manage headscale users -In headscale, a node (also known as machine or device) is always assigned to a -headscale user. Such a headscale user may have many nodes assigned to them and -can be managed with the `headscale users` command. Invoke the built-in help for -more information: `headscale users --help`. +In headscale, a node (also known as machine or device) is [typically assigned to a headscale +user](../ref/registration.md#identity-model). Such a headscale user may have many nodes assigned to them and can be +managed with the `headscale users` command. Invoke the built-in help for more information: `headscale users --help`. ### Create a headscale user @@ -97,11 +96,12 @@ more information: `headscale users --help`. ## Register a node -One has to register a node first to use headscale as coordination server 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. +One has to [register a node](../ref/registration.md) first to use headscale as coordination server 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. Read +[registration methods](../registration.md) for an overview of available registration methods. -### Normal, interactive login +### [Web authentication](../ref/registration.md#web-authentication) On a client machine, run the `tailscale up` command and provide the FQDN of your headscale instance as argument: @@ -125,7 +125,7 @@ your headscale server and it also prints the registration key required to approv headscale nodes register --user --key ``` -### Using a preauthkey +### [Pre authenticated key](../ref/registration.md#pre-authenticated-key) 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 diff --git a/mkdocs.yml b/mkdocs.yml index da44369a..d1d9bdc1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -183,6 +183,7 @@ nav: - Windows: usage/connect/windows.md - Reference: - Configuration: ref/configuration.md + - Registration methods: ref/registration.md - OpenID Connect: ref/oidc.md - Routes: ref/routes.md - TLS: ref/tls.md