docs: document the policy derpMap

Updates #2918
This commit is contained in:
Kristoffer Dalby committed 2026-11-05 14:11:33 +01:00
1 parent 69e01ca7f8
commit 1a635e7d08
3 files changed
+48

No files matched your search

+1
View File
@@ -208,6 +208,7 @@ the ACME DNS-01 challenge through a built-in DNS provider: `acmedns`,
- `dns.extra_records_path` files may be HuJSON or YAML as well as JSON
- A `derp.paths` region set to `null` removes that region again, as documented
- `derp.paths` files may set `homeparams.regionscore` to make clients prefer or avoid DERP regions [#2932](https://github.com/juanfont/headscale/pull/2932)
- The policy accepts a `derpMap` that adds or removes DERP regions, with the rules and error messages of Tailscale SaaS [#2932](https://github.com/juanfont/headscale/pull/2932)
- Lower CPU use on large tailnets when node tags, owners, IPs or routes change [#3501](https://github.com/juanfont/headscale/pull/3501)
- `headscale nodes backfillips` now sends the new IPs to connected clients [#3501](https://github.com/juanfont/headscale/pull/3501)
- A registration request from a client below the minimum supported version is now rejected before it can log a node out, use a pre-auth key or start a login [#3519](https://github.com/juanfont/headscale/pull/3519)
+32
View File
@@ -155,6 +155,38 @@ loaded DERP maps fetched via URL or to offer your own, custom DERP servers to no
Independent of the custom DERP map, you may choose to [enable the embedded DERP server and have it automatically added
to the custom DERP map](#enable-embedded-derp).
### Customize the DERP map in the policy
The [policy](policy.md#network-wide-policy-options) may hold a `derpMap`, as on Tailscale. It changes the DERP map from
the configuration above, and connected nodes get the change as soon as the policy is updated. Headscale checks it like
Tailscale does:
- A region added in the policy needs a region ID from 900 to 999 and at least one node. Its `RegionID`, and the `RegionID`
of each node, must match the ID it is listed under. A policy region replaces a configured region with the same ID,
such as the embedded DERP server's.
- A node's `HostName` and `CertName` must not be `tailscale.com` or one of its subdomains. Tailscale also rejects the IP
addresses of its own DERP servers; Headscale does not, as that needs Tailscale's current list of servers.
- A region set to `null` is removed. This works for any region ID.
- `OmitDefaultRegions: true` removes every region from the configuration, the embedded DERP server's included, and
needs at least one region added in the policy.
- `HomeParams` is accepted but ignored, as on Tailscale. Set region scores in a `derp.paths` file instead.
```json title="policy.json"
{
"derpMap": {
"Regions": {
"1": null,
"900": {
"RegionID": 900,
"RegionCode": "custom",
"RegionName": "My region",
"Nodes": [{"Name": "900a", "RegionID": 900, "HostName": "derp900.example.com"}]
}
}
}
}
```
### Verify clients
Access to DERP serves can be restricted to nodes that are members of your Tailnet. Relay access is denied for unknown
+15
View File
@@ -246,6 +246,21 @@ fine-grained configuration instead.
}
```
- `derpMap`: Add custom DERP regions or remove regions from the DERP map, like a
[Tailscale policy file](https://tailscale.com/docs/reference/derp-servers/custom-derp-servers). See
[DERP](derp.md#customize-the-derp-map-in-the-policy) for the rules.
```json title="policy.json"
{
// Do not use the New York DERP region
"derpMap": {
"Regions": {
"1": null
}
}
}
```
[^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.