derp: check derp.paths and derp.urls regions like a policy derpMap

Clients count latency by RegionID, so a key mismatch picks a missing home.

Updates #2918
This commit is contained in:
Kristoffer Dalby committed 2026-11-05 14:11:33 +01:00
1 parent 1a635e7d08
commit 6f2c7fbe7d
7 files changed
+110 -26

No files matched your search

+1
View File
@@ -156,6 +156,7 @@ the ACME DNS-01 challenge through a built-in DNS provider: `acmedns`,
- `dns.extra_records_path` must end in `.json`, `.hujson`, `.yaml` or `.yml`; the extension picks the format
- A `derp.paths` file that decodes to neither regions nor `homeparams` now stops headscale from starting instead of being silently ignored
- A `derp.paths` file with a key `tailcfg.DERPMap` has no field for (e.g. a misspelt `regionscore`) stops headscale from starting instead of the key being ignored, as Tailscale SaaS rejects such a policy `derpMap` [#2932](https://github.com/juanfont/headscale/pull/2932)
- A DERP map from `derp.paths` or `derp.urls` must meet the region rules Tailscale SaaS applies to a policy `derpMap`: each region's `regionid` matches its key, each node's `regionid` matches its region, and a region has at least one node. A `derp.paths` file that breaks one stops headscale from starting; a `derp.urls` map that breaks one fails to load. Clients count latency by `regionid`, so a mismatch made them pick a home region the map did not have [#2932](https://github.com/juanfont/headscale/pull/2932)
- `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
+3 -1
View File
@@ -58,7 +58,9 @@ file](https://github.com/juanfont/headscale/blob/main/derp-example.yaml). The fi
or `.yml`, or the JSON format Tailscale serves DERP maps in as `.json` or `.hujson`. Both JSON extensions are read as
[HuJSON](https://github.com/tailscale/hujson), so comments and trailing commas are allowed. This allows to modify previously
loaded DERP maps fetched via URL or to offer your own, custom DERP servers to nodes. A key that has no field in
[DERPMap](https://pkg.go.dev/tailscale.com/tailcfg#DERPMap) stops headscale from starting.
[DERPMap](https://pkg.go.dev/tailscale.com/tailcfg#DERPMap) stops headscale from starting. So does a region whose
`regionid` differs from its key, a node whose `regionid` differs from its region, or a region without nodes: clients
count latency by `regionid`.
=== "Remove specific DERP regions"
+71 -3
View File
@@ -25,13 +25,68 @@ import (
"tailscale.com/tailcfg"
)
var errEmptyDERPMapFile = errors.New("DERP map file has no regions or homeparams")
var (
errEmptyDERPMapFile = errors.New("DERP map file has no regions or homeparams")
ErrRegionIDKey = errors.New("doesn't match its key")
ErrRegionNoNodes = errors.New("must specify at least one node in DERP Region")
ErrRegionNullNode = errors.New("null node in DERP Region")
ErrNodeRegionID = errors.New("doesn't match its region")
)
// ValidateRegion returns what is wrong with region, stored under id in a DERP
// map. Clients look regions up by key and attribute a node's latency to its
// RegionID, so every map must pass, whatever its source. The wording is
// Tailscale SaaS's for a policy derpMap.
func ValidateRegion(id tailcfg.DERPRegionID, region *tailcfg.DERPRegion) []error {
var errs []error
if region.RegionID != id {
errs = append(errs, fmt.Errorf(
"custom DERP Region %d has RegionID %d that %w", id, region.RegionID, ErrRegionIDKey))
}
if len(region.Nodes) == 0 {
errs = append(errs, fmt.Errorf("%w %d", ErrRegionNoNodes, id))
}
for _, node := range region.Nodes {
if node == nil {
errs = append(errs, fmt.Errorf("%w %d", ErrRegionNullNode, id))
continue
}
if node.RegionID != id {
errs = append(errs, fmt.Errorf(
"custom DERP Region %d has node %q with RegionID %d that %w",
id, node.Name, node.RegionID, ErrNodeRegionID))
}
}
return errs
}
// validateRegions runs [ValidateRegion] on every region of dm. A null region
// only removes one, so it is not checked.
func validateRegions(dm *tailcfg.DERPMap) error {
var errs []error
for _, id := range slices.Sorted(maps.Keys(dm.Regions)) {
if region := dm.Regions[id]; region != nil {
errs = append(errs, ValidateRegion(id, region)...)
}
}
return errors.Join(errs...)
}
// loadDERPMapFromPath reads a DERP map file in the format its extension names
// (see [util.UnmarshalByExtStrict]). An unknown key is an error, as SaaS
// rejects one in a policy derpMap, so a misspelt key cannot silently do
// nothing. A map with neither regions nor HomeParams is an error too;
// HomeParams alone is valid, to score regions from other sources.
// HomeParams alone is valid, to score regions from other sources. Regions
// must pass [ValidateRegion].
func loadDERPMapFromPath(path string) (*tailcfg.DERPMap, error) {
data, err := os.ReadFile(path)
if err != nil {
@@ -47,6 +102,11 @@ func loadDERPMapFromPath(path string) (*tailcfg.DERPMap, error) {
return nil, fmt.Errorf("%w: %s", errEmptyDERPMapFile, path)
}
err = validateRegions(&derpMap)
if err != nil {
return nil, fmt.Errorf("DERP map %s: %w", path, err)
}
return &derpMap, nil
}
@@ -78,8 +138,16 @@ func loadDERPMapFromURL(addr url.URL) (*tailcfg.DERPMap, error) {
var derpMap tailcfg.DERPMap
err = json.Unmarshal(body, &derpMap)
if err != nil {
return nil, err
}
return &derpMap, err
err = validateRegions(&derpMap)
if err != nil {
return nil, fmt.Errorf("DERP map %s: %w", addr.String(), err)
}
return &derpMap, nil
}
// mergeDERPMaps merges a list of [tailcfg.DERPMap] values into a single
+1
View File
@@ -54,6 +54,7 @@ func TestApplyPolicySaaSCompat(t *testing.T) {
}
require.NotEmpty(t, base.Regions)
require.NoError(t, validateRegions(base), "Tailscale's own map must pass the rules every DERP map does")
files, err := filepath.Glob(derpCaptures + "nodeattrs-derpmap-*.hujson")
require.NoError(t, err)
+29
View File
@@ -2,6 +2,9 @@ package derp
import (
"encoding/json"
"net/http"
"net/http/httptest"
"net/url"
"os"
"path/filepath"
"strings"
@@ -446,6 +449,10 @@ homeparams:
{name: "json as yaml decodes to nothing", file: "derp.yaml", content: string(tailcfgJSON), wantErr: true},
{name: "misspelt yaml key", file: "derp.yaml", content: "homeparams: {regionscores: {999: 0.5}}", wantErr: true},
{name: "unknown json key", file: "derp.json", content: `{"HomeParams": {"Bogus": 1}}`, wantErr: true},
{name: "region id not its key", file: "derp.json", content: `{"Regions": {"999": {"RegionID": 998, "Nodes": [{"Name": "a", "RegionID": 999}]}}}`, wantErr: true},
{name: "node in another region", file: "derp.json", content: `{"Regions": {"999": {"RegionID": 999, "Nodes": [{"Name": "a", "RegionID": 998}]}}}`, wantErr: true},
{name: "region without nodes", file: "derp.json", content: `{"Regions": {"999": {"RegionID": 999}}}`, wantErr: true},
{name: "null node", file: "derp.json", content: `{"Regions": {"999": {"RegionID": 999, "Nodes": [null]}}}`, wantErr: true},
{name: "empty", file: "derp.yaml", content: "", wantErr: true},
{name: "no extension", file: "derp", content: yamlMap, wantErr: true},
}
@@ -469,4 +476,26 @@ homeparams:
}
})
}
// A null region removes one and has nothing to check.
path := filepath.Join(t.TempDir(), "drop.json")
require.NoError(t, os.WriteFile(path, []byte(`{"Regions": {"1": null}}`), 0o600))
_, err = loadDERPMapFromPath(path)
require.NoError(t, err)
}
// TestLoadDERPMapFromURLValidates pins that a fetched map meets the region
// rules a derp.paths file does.
func TestLoadDERPMapFromURLValidates(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte(`{"Regions": {"1": {"RegionID": 2, "Nodes": [{"Name": "a", "RegionID": 1}]}}}`))
}))
defer srv.Close()
addr, err := url.Parse(srv.URL)
require.NoError(t, err)
_, err = loadDERPMapFromURL(*addr)
require.ErrorIs(t, err, ErrRegionIDKey)
}
+4 -22
View File
@@ -15,6 +15,7 @@ import (
"time"
"github.com/go-json-experiment/json"
"github.com/juanfont/headscale/hscontrol/derp"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/juanfont/headscale/hscontrol/util"
"github.com/tailscale/hujson"
@@ -196,10 +197,6 @@ var (
ErrHostNotDefined = errors.New("host not defined in policy")
ErrUnknownField = errors.New("unknown field")
ErrDERPRegionIDRange = errors.New("must be in range [900,999]")
ErrDERPRegionIDKey = errors.New("doesn't match its key")
ErrDERPRegionNoNodes = errors.New("must specify at least one node in DERP Region")
ErrDERPRegionNullNode = errors.New("null node in DERP Region")
ErrDERPNodeRegionID = errors.New("doesn't match its region")
ErrDERPTailscaleName = errors.New("cannot use Tailscale hostname or subdomain")
ErrDERPOmitDefaultsNoRegions = errors.New("OmitDefaultRegions specified but no custom DERP regions specified")
ErrProtocolNoSpecificPorts = errors.New("protocol does not support specific ports")
@@ -3493,8 +3490,8 @@ func validateProtocolPortCompatibility(protocol Protocol, destinations []AliasWi
}
// validateDERPMap checks a policy derpMap the way Tailscale SaaS does, with
// its wording: an added region uses an ID in 900-999, has a node, every ID in
// it matches the key it sits under, and no node is on tailscale.com. A null
// its wording: an added region uses an ID in 900-999, passes
// [derp.ValidateRegion] like every DERP map, and no node is on tailscale.com. A null
// region only removes one, so it is not checked. HomeParams are decoded but
// never sent, as on SaaS.
func validateDERPMap(dm *tailcfg.DERPMap) []error {
@@ -3521,28 +3518,13 @@ func validateDERPMap(dm *tailcfg.DERPMap) []error {
continue
}
if region.RegionID != id {
errs = append(errs, fmt.Errorf(
"custom DERP Region %d has RegionID %d that %w", id, region.RegionID, ErrDERPRegionIDKey))
}
if len(region.Nodes) == 0 {
errs = append(errs, fmt.Errorf("%w %d", ErrDERPRegionNoNodes, id))
}
errs = append(errs, derp.ValidateRegion(id, region)...)
for _, node := range region.Nodes {
if node == nil {
errs = append(errs, fmt.Errorf("%w %d", ErrDERPRegionNullNode, id))
continue
}
if node.RegionID != id {
errs = append(errs, fmt.Errorf(
"custom DERP Region %d has node %q with RegionID %d that %w",
id, node.Name, node.RegionID, ErrDERPNodeRegionID))
}
// SaaS keeps custom regions off Tailscale's own servers. It also
// rejects their IPs, which takes a live list of them.
for _, name := range []string{node.HostName, node.CertName} {
+1
View File
@@ -52,6 +52,7 @@ func TestDERPVerifyEndpoint(t *testing.T) {
require.NoError(t, err)
derpRegion := tailcfg.DERPRegion{
RegionID: 900,
RegionCode: "test-derpverify",
RegionName: "TestDerpVerify",
Nodes: []*tailcfg.DERPNode{