diff --git a/CHANGELOG.md b/CHANGELOG.md index d552d583f..7ab450413 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docs/ref/derp.md b/docs/ref/derp.md index e9ba711f4..9c47ec592 100644 --- a/docs/ref/derp.md +++ b/docs/ref/derp.md @@ -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" diff --git a/hscontrol/derp/derp.go b/hscontrol/derp/derp.go index 80f7a19fa..a57303b66 100644 --- a/hscontrol/derp/derp.go +++ b/hscontrol/derp/derp.go @@ -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 diff --git a/hscontrol/derp/derp_compat_test.go b/hscontrol/derp/derp_compat_test.go index 5c6e1b594..c9c48259e 100644 --- a/hscontrol/derp/derp_compat_test.go +++ b/hscontrol/derp/derp_compat_test.go @@ -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) diff --git a/hscontrol/derp/derp_test.go b/hscontrol/derp/derp_test.go index 1c2b76a56..57f453726 100644 --- a/hscontrol/derp/derp_test.go +++ b/hscontrol/derp/derp_test.go @@ -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) } diff --git a/hscontrol/policy/v2/types.go b/hscontrol/policy/v2/types.go index a5278af9b..2769b1252 100644 --- a/hscontrol/policy/v2/types.go +++ b/hscontrol/policy/v2/types.go @@ -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} { diff --git a/integration/derp_verify_endpoint_test.go b/integration/derp_verify_endpoint_test.go index 399b3314c..7cb1c8cce 100644 --- a/integration/derp_verify_endpoint_test.go +++ b/integration/derp_verify_endpoint_test.go @@ -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{