derp: reject unknown keys in derp.paths files

SaaS rejects them in a policy derpMap; a misspelt key silently did nothing.

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

No files matched your search

+1
View File
@@ -155,6 +155,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 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)
- `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
+2 -1
View File
@@ -57,7 +57,8 @@ The DERP map offered to clients can be customized with a [dedicated YAML-configu
file](https://github.com/juanfont/headscale/blob/main/derp-example.yaml). The file extension picks the format: `.yaml`
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.
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.
=== "Remove specific DERP regions"
+12 -5
View File
@@ -13,6 +13,7 @@ import (
"math/rand"
"net/http"
"net/url"
"os"
"reflect"
"slices"
"sync"
@@ -24,14 +25,20 @@ import (
"tailscale.com/tailcfg"
)
var errEmptyDERPMapFile = errors.New("DERP map file has no regions or homeparams (YAML keys are lowercased Go field names, e.g. regionid)")
var errEmptyDERPMapFile = errors.New("DERP map file has no regions or homeparams")
// loadDERPMapFromPath reads a DERP map file in the format its extension names
// (see [util.UnmarshalByExt]). A map with neither regions nor HomeParams is an
// error: unknown keys decode to nothing, e.g. YAML written with JSON's field
// names. HomeParams alone is valid, to score regions from other sources.
// (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.
func loadDERPMapFromPath(path string) (*tailcfg.DERPMap, error) {
derpMap, err := util.ReadFileByExt[tailcfg.DERPMap](path)
data, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("reading DERP map: %w", err)
}
derpMap, err := util.UnmarshalByExtStrict[tailcfg.DERPMap](path, data)
if err != nil {
return nil, fmt.Errorf("reading DERP map: %w", err)
}
+2
View File
@@ -444,6 +444,8 @@ homeparams:
{name: "tailcfg hujson", file: "derp.hujson", content: "// test map\n" + string(tailcfgJSON)},
{name: "tailcfg json with unterminated comment", file: "derp.json", content: string(tailcfgJSON) + " /*", wantErr: true},
{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: "empty", file: "derp.yaml", content: "", wantErr: true},
{name: "no extension", file: "derp", content: yamlMap, wantErr: true},
}
+25 -2
View File
@@ -1,9 +1,11 @@
package util
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"io"
"io/fs"
"os"
"path/filepath"
@@ -40,6 +42,16 @@ var ErrUnknownFileFormat = errors.New("unknown file format, want .json, .hujson,
// JSON syntax, so sniffing cannot tell the two apart. YAML keys are the
// lowercased Go field names.
func UnmarshalByExt[T any](name string, data []byte) (T, error) {
return unmarshalByExt[T](name, data, false)
}
// UnmarshalByExtStrict is [UnmarshalByExt] that fails on a key T has no
// field for, so a misspelt key is an error rather than silently dropped.
func UnmarshalByExtStrict[T any](name string, data []byte) (T, error) {
return unmarshalByExt[T](name, data, true)
}
func unmarshalByExt[T any](name string, data []byte, strict bool) (T, error) {
var (
v T
err error
@@ -49,10 +61,21 @@ func UnmarshalByExt[T any](name string, data []byte) (T, error) {
case ".json", ".hujson":
data, err = hujson.Standardize(data)
if err == nil {
err = json.Unmarshal(data, &v)
dec := json.NewDecoder(bytes.NewReader(data))
if strict {
dec.DisallowUnknownFields()
}
err = dec.Decode(&v)
}
case ".yaml", ".yml":
err = yaml.Unmarshal(data, &v)
dec := yaml.NewDecoder(bytes.NewReader(data))
dec.KnownFields(strict)
err = dec.Decode(&v)
if errors.Is(err, io.EOF) {
err = nil // an empty document, as yaml.Unmarshal reads it
}
default:
return v, fmt.Errorf("%s: %w", name, ErrUnknownFileFormat)
}
+14 -1
View File
@@ -908,6 +908,7 @@ func TestUnmarshalByExt(t *testing.T) {
file string
data string
want rec
strict bool
wantFormat bool // want ErrUnknownFileFormat
wantErr bool
}{
@@ -925,11 +926,23 @@ func TestUnmarshalByExt(t *testing.T) {
{name: "json with wrong value type", file: "x.json", data: `{"name": "a", "port": "1"}`, wantErr: true},
{name: "unknown extension", file: "x.txt", data: `{"name": "a", "port": 1}`, wantFormat: true},
{name: "no extension", file: "x", data: `{"name": "a", "port": 1}`, wantFormat: true},
{name: "json unknown key is ignored", file: "x.json", data: `{"name": "a", "port": 1, "bogus": 2}`, want: a1},
{name: "yaml unknown key is ignored", file: "x.yaml", data: "name: a\nport: 1\nbogus: 2\n", want: a1},
{name: "strict json unknown key", file: "x.json", data: `{"name": "a", "port": 1, "bogus": 2}`, strict: true, wantErr: true},
{name: "strict yaml unknown key", file: "x.yaml", data: "name: a\nport: 1\nbogus: 2\n", strict: true, wantErr: true},
{name: "strict json", file: "x.json", data: `{"name": "a", "port": 1}`, strict: true, want: a1},
{name: "strict yaml", file: "x.yaml", data: "name: a\nport: 1\n", strict: true, want: a1},
{name: "empty yaml", file: "x.yaml", data: "", want: rec{}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := UnmarshalByExt[rec](tt.file, []byte(tt.data))
unmarshal := UnmarshalByExt[rec]
if tt.strict {
unmarshal = UnmarshalByExtStrict[rec]
}
got, err := unmarshal(tt.file, []byte(tt.data))
if tt.wantFormat {
if !errors.Is(err, ErrUnknownFileFormat) {
t.Fatalf("UnmarshalByExt(%q) error = %v, want %v", tt.file, err, ErrUnknownFileFormat)