From f3f84a5a63ba69e31caee6bb5a4467dbbb47a63b Mon Sep 17 00:00:00 2001
From: Florian Preinstorfer <site-github@nblock.org>
Date: Fri, 15 May 2026 17:36:47 +0200
Subject: [PATCH] Add docs for policy-wide options and node attributes

---
 docs/about/features.md |  1 +
 docs/ref/policy.md     | 49 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/about/features.md b/docs/about/features.md
index eedf5813..e92327c8 100644
--- a/docs/about/features.md
+++ b/docs/about/features.md
@@ -33,6 +33,7 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
       routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit
       nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers)
     - [x] [Tailscale SSH](https://tailscale.com/docs/features/tailscale-ssh)
+    - [x] [Node attributes](../ref/policy.md#node-attributes)
     - [x] [Tests](https://tailscale.com/docs/reference/syntax/policy-file#tests) and
       [sshTests](https://tailscale.com/docs/reference/syntax/policy-file#ssh-tests)
 - [x] [Node registration using Single-Sign-On (OpenID Connect)](../ref/oidc.md) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
diff --git a/docs/ref/policy.md b/docs/ref/policy.md
index 10248e76..3529a81e 100644
--- a/docs/ref/policy.md
+++ b/docs/ref/policy.md
@@ -196,5 +196,54 @@ Used in Tailscale SSH rules to allow access to any user except root. Can only be
 This autogroup resolves to all IP addresses (`0.0.0.0/0` and `::/0`) which also includes all IP addresses outside the
 standard Tailscale IP ranges. This autogroup can only be used as source.
 
+## Node Attributes
+
+[Node attributes](https://tailscale.com/docs/reference/syntax/policy-file#node-attributes) allow for device-specific
+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).
+- `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)
+  resolver at 100.100.100.100.
+- `disable-ipv4`: Selectively disable IPv4 for specfic nodes. This is may be useful to workaround [CGNat
+  conflicts](https://tailscale.com/docs/reference/troubleshooting/network-configuration/cgnat-conflicts).
+- `randomize-client-port`: Allocate a [random port for WireGuard
+  traffic](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport) instead of the static default
+  port 41641.
+- `disable-captive-portal-detection`: [Disable automatic captive portal
+  detection](https://tailscale.com/docs/integrations/captive-portals#disable-captive-portal-detection).
+
+```json title="policy.json"
+{
+  "nodeAttrs": [
+    {
+      // Enable MagicDNS AAAA records for all nodes
+      "target": ["*"]
+      "attr": ["magicdns-aaaa"]
+    }
+  ]
+}
+```
+
+## Network-wide policy options
+
+The following options are applied for the entire tailnet. Consider [node attributes](#node-attributes) for a more
+fine-grained configuration instead.
+
+- `randomizeClientPort`: Allocate a [random port for WireGuard
+  traffic](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport) instead of the static default
+  port 41641.
+
+```json title="policy.json"
+{
+  // Use a random WireGuard port for the entire tailnet
+  "randomizeClientPort": true
+}
+```
+
 [^1]: Headscale also allows to store the policy in the database. This is typically only required in case a [web
     interface](integration/web-ui.md) is used.
+
+[^2]: Other key-only node attributes can be used as well. Find them in the client source code with `grep -E '^\s+NodeAttr\w+' tailcfg/tailcfg.go` or by using [GitHub code search (requires
+    login)](https://github.com/search?q=repo%3Atailscale%2Ftailscale%20language%3Ago%20path%3Atailcfg%2Ftailcfg.go%20symbol%3A%2FNodeAttr%5Cw%2B%2F&type=code).