diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ad6f20e9..d552d583f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/docs/ref/derp.md b/docs/ref/derp.md index 901629db3..e9ba711f4 100644 --- a/docs/ref/derp.md +++ b/docs/ref/derp.md @@ -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 diff --git a/docs/ref/policy.md b/docs/ref/policy.md index 55d336f62..72020f336 100644 --- a/docs/ref/policy.md +++ b/docs/ref/policy.md @@ -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.