diff --git a/CHANGELOG.md b/CHANGELOG.md index ce9f5cb70..95bbac639 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/docs/ref/derp.md b/docs/ref/derp.md index 166b60818..19031b203 100644 --- a/docs/ref/derp.md +++ b/docs/ref/derp.md @@ -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).