docs: document DERP region scores

Updates #2918
This commit is contained in:
Kristoffer Dalby committed 2026-11-05 14:11:33 +01:00
1 parent 6f2f97ca17
commit 00f9373246
2 files changed
+25 -1

No files matched your search

+2 -1
View File
@@ -154,7 +154,7 @@ the ACME DNS-01 challenge through a built-in DNS provider: `acmedns`,
- `derp.paths` files must end in `.yaml`, `.yml`, `.json` or `.hujson`; the extension picks the format
- `dns.extra_records_path` must end in `.json`, `.hujson`, `.yaml` or `.yml`; the extension picks the format
- A `derp.paths` file that decodes to no regions now stops headscale from starting instead of being silently ignored
- A `derp.paths` file that decodes to neither regions nor `homeparams` now stops headscale from starting instead of being silently ignored
- `unix_socket_permission` must be a quoted octal string no higher than `"0777"`, e.g. `"0770"`; an unquoted number or an invalid value now stops headscale from starting instead of silently using `0700` [#3540](https://github.com/juanfont/headscale/pull/3540)
- `tls_cert_path`, `tls_key_path`, `tls_letsencrypt_*`, `acme_url` and `acme_email` are deprecated in favour of `tls.cert_path`, `tls.key_path` and `tls.acme.*` [#3554](https://github.com/juanfont/headscale/pull/3554)
- The old keys continue to work, with a warning, but will be removed in a future release
@@ -206,6 +206,7 @@ the ACME DNS-01 challenge through a built-in DNS provider: `acmedns`,
- `derp.paths` files may be Tailscale JSON or HuJSON DERP maps as well as YAML
- `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)
- 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)
+23
View File
@@ -128,6 +128,29 @@ loaded DERP maps fetched via URL or to offer your own, custom DERP servers to no
- /etc/headscale/derp.yaml
```
=== "Prefer or avoid DERP regions"
Each client picks its home DERP region by latency. A region score multiplies the latency a client measures for a
region before it compares regions: a score below 1 makes a region more attractive, a score above 1 less attractive.
Regions without a score count as 1, scores of 0 or below are ignored. See
[DERPHomeParams](https://pkg.go.dev/tailscale.com/tailcfg#DERPHomeParams).
The following sample `derp.yaml` prefers the embedded DERP server (region ID 999) and avoids New York (region ID 1).
The file may hold scores alone, the regions come from other sources:
```yaml title="derp.yaml"
homeparams:
regionscore:
999: 0.5
1: 2
```
The same in a `.json` or `.hujson` file is `{"HomeParams": {"RegionScore": {"999": 0.5, "1": 2}}}`.
A score biases the choice, it does not pin it: a client keeps its home region unless another one is clearly faster
after scaling. Connected clients keep a score that is removed from the file until they reconnect; set it to `1`
instead to reset it.
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).