From 38722e5eebe401b61cfed89a99773e4a5ece4440 Mon Sep 17 00:00:00 2001
From: Florian Preinstorfer <site-github@nblock.org>
Date: Sat, 5 Sep 2026 08:26:32 +0200
Subject: [PATCH] Document automatic exit node selection and related node
 attributes

- Add "Automatic exit node selection" to route docs
- Add suggest-exit-node and suggest-exit-node-ui as supported nodeAttrs

Fixes: #3444
---
 docs/ref/policy.md |  1 +
 docs/ref/routes.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/docs/ref/policy.md b/docs/ref/policy.md
index f326d7ecb..9d4207c92 100644
--- a/docs/ref/policy.md
+++ b/docs/ref/policy.md
@@ -202,6 +202,7 @@ standard Tailscale IP ranges. This autogroup can only be used as source.
 configuration and attributes. At least the following node attributes are currently supported by Headscale[^2]:
 
 - `drive:access`, `drive:share`: [Taildrive support](https://tailscale.com/docs/features/taildrive).
+- `suggest-exit-node`, `suggest-exit-node-ui`: [Automatic exit node selection](routes.md#automatic-exit-node-selection).
 - `nextdns:<profile>`, `nextdns:no-device-info`: [NextDNS integration](https://tailscale.com/docs/integrations/nextdns).
   Be sure to set NextDNS as global resolver in the [configuration](configuration.md).
 - `magicdns-aaaa`: Respond to AAAA queries on the local [MagicDNS](https://tailscale.com/docs/features/magicdns)
diff --git a/docs/ref/routes.md b/docs/ref/routes.md
index d5c8658e3..eace30cb1 100644
--- a/docs/ref/routes.md
+++ b/docs/ref/routes.md
@@ -283,6 +283,58 @@ $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:exi
 Please see the [official Tailscale documentation](https://tailscale.com/docs/reference/syntax/policy-file#autoapprovers)
 for more information on auto approvers.
 
+### Automatic exit node selection
+
+A Tailscale client can be configured to select one of the available exit nodes automatically. This may be useful when
+there are multiple exit nodes available and clients should use an exit node without requiring a user to manually switch
+between them.
+
+The policy snippet below defines the tag `tag:exit` for exit nodes. Exit nodes with that tag are suggested to clients
+with the [`suggest-exit-node` node attribute](policy.md#node-attributes). Additionally, GUI clients should display the
+"Recommended" exit node selector.
+
+```json title="Automatic exit node selection"
+{
+  "tagOwners": {
+    "tag:exit": ["infra@"]
+  },
+  "nodeAttrs": [
+    {
+      // Suggest exit nodes tagged with tag:exit
+      "target": ["tag:exit"],
+      "attr": ["suggest-exit-node"]
+    },
+    {
+      // Show "recommended" exit node selector in GUIs
+      "target": ["*"],
+      "attr": ["suggest-exit-node-ui"]
+    }
+  ],
+  "grants": [
+    {
+      "src": ["..."],
+      "dst": ["autogroup:internet"],
+      "ip": ["*"]
+    }
+  ]
+}
+```
+
+The Tailscale client can suggest a viable exit node with:
+
+```console
+$ sudo tailscale exit-node suggest
+```
+
+or automatically select one by using `auto:any` as exit node identifier:
+
+```console
+$ sudo tailscale set --exit-node=auto:any
+```
+
+Please see the [official Tailscale documentation](https://tailscale.com/docs/features/exit-nodes/auto-exit-nodes) for
+more information on automatic exit node selection.
+
 ## High availability
 
 Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can