config: make the loaded configuration round-trip

Configuration keys now match only as written, in lower case. BREAKING:
Server_URL is an unknown key, where 0.29 and the previous commits
ignored case. Each key has one spelling, the one the dump prints.
Open-map entry names keep their own rule: split DNS domains and
provider settings are lowercased, oidc.extra_params keeps case.

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 15:02:16 +01:00
1 parent f1cbdcfacb
commit 4dbf981679
12 files changed
+799 -47

No files matched your search

+15 -10
View File
@@ -22,10 +22,12 @@ func keyTree(src []byte) *yaml.Node {
}
// keyPosition returns the 1-based position of the key written as path, one
// name per mapping, below n. Keys match case-insensitively, as the loader
// lowercases them.
// name per mapping, below n. Keys match as [keyCase] spells them.
func keyPosition(n *yaml.Node, path []string) (int, int, bool) {
var key *yaml.Node
var (
key *yaml.Node
prefix string
)
for _, want := range path {
if n == nil || n.Kind != yaml.MappingNode {
@@ -36,7 +38,7 @@ func keyPosition(n *yaml.Node, path []string) (int, int, bool) {
// Last duplicate wins, matching the JSON parser's effective value.
for i := len(n.Content) - 2; i >= 0; i -= 2 {
if strings.EqualFold(n.Content[i].Value, want) {
if keyCase(prefix, n.Content[i].Value) == want {
key, n = n.Content[i], n.Content[i+1]
break
@@ -46,6 +48,8 @@ func keyPosition(n *yaml.Node, path []string) (int, int, bool) {
if key == nil {
return 0, 0, false
}
prefix = joinConfigPath(prefix, want)
}
if key == nil {
@@ -56,9 +60,10 @@ func keyPosition(n *yaml.Node, path []string) (int, int, bool) {
}
// dottedPosition returns the 1-based position of the key at the dotted
// path below n, however the file splits it into nested and dotted keys. It
// follows only the keys n has, so the work is bounded by the file.
func dottedPosition(n *yaml.Node, path []string) (int, int, bool) {
// path below n, written below prefix, however the file splits it into
// nested and dotted keys. Keys match as [keyCase] spells them. It follows
// only the keys n has, so the work is bounded by the file.
func dottedPosition(n *yaml.Node, prefix string, path []string) (int, int, bool) {
if n == nil || n.Kind != yaml.MappingNode {
return 0, 0, false
}
@@ -68,7 +73,7 @@ func dottedPosition(n *yaml.Node, path []string) (int, int, bool) {
// Last duplicate wins, matching the JSON parser's effective value; an
// earlier one is shadowed, so its children were never loaded.
for i := len(n.Content) - 2; i >= 0; i -= 2 {
key := strings.ToLower(n.Content[i].Value)
key := keyCase(prefix, n.Content[i].Value)
if seen[key] {
continue
}
@@ -76,7 +81,7 @@ func dottedPosition(n *yaml.Node, path []string) (int, int, bool) {
seen[key] = true
names := strings.Split(key, ".")
if len(names) > len(path) || !slices.EqualFunc(names, path[:len(names)], strings.EqualFold) {
if len(names) > len(path) || !slices.Equal(names, path[:len(names)]) {
continue
}
@@ -84,7 +89,7 @@ func dottedPosition(n *yaml.Node, path []string) (int, int, bool) {
return n.Content[i].Line, n.Content[i].Column, true
}
line, col, ok := dottedPosition(n.Content[i+1], path[len(names):])
line, col, ok := dottedPosition(n.Content[i+1], joinConfigPath(prefix, key), path[len(names):])
if ok {
return line, col, true
}
+6 -2
View File
@@ -17,7 +17,9 @@ func TestKeyPosition(t *testing.T) {
line, col int
ok bool
}{
{"yaml nested", "a: 1\nserver:\n Foo: 2\n", []string{"server", "foo"}, 3, 3, true},
{"yaml nested", "a: 1\nserver:\n Foo: 2\n", []string{"server", "Foo"}, 3, 3, true},
{"case differs", "Log: 1\nlog: 2\n", []string{"Log"}, 1, 1, true},
{"lowercased open map", "dns:\n nameservers:\n split:\n Corp.Example.com: []\n", []string{"dns", "nameservers", "split", "corp.example.com"}, 4, 7, true},
{"json", "{\n \"a\": 1,\n \"b\": {\n \"c\": 2\n }\n}\n", []string{"b", "c"}, 4, 5, true},
{"duplicate parent", `{"dns":{"magic_dns":true},"dns":{"magic_dsn":true}}`, []string{"dns", "magic_dsn"}, 1, 34, true},
{"duplicate leaf", "{\n\"a\": 1,\n\"a\": 2\n}", []string{"a"}, 3, 1, true},
@@ -55,6 +57,8 @@ func TestDottedPosition(t *testing.T) {
{"nested", "dns:\n magic_dsn: true\n", "dns.magic_dsn", 2, 3, true},
{"dotted", "a: 1\ndns.magic_dsn: true\n", "dns.magic_dsn", 2, 1, true},
{"mixed", "dns:\n extra.x: 1\n", "dns.extra.x", 2, 3, true},
{"case differs", "log.level: 1\nLog.level: 2\n", "log.level", 1, 1, true},
{"lowercased open map", "dns.nameservers.split.Corp.Example.com: []\n", "dns.nameservers.split.corp.example.com", 1, 1, true},
// The surviving dns lacks the key; the shadowed one's copy was
// never loaded, so the dotted spelling is the one that set it.
{
@@ -67,7 +71,7 @@ func TestDottedPosition(t *testing.T) {
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
line, col, ok := dottedPosition(keyTree([]byte(tt.src)), strings.Split(tt.path, "."))
line, col, ok := dottedPosition(keyTree([]byte(tt.src)), "", strings.Split(tt.path, "."))
assert.Equal(t, tt.ok, ok)
assert.Equal(t, tt.line, line)
assert.Equal(t, tt.col, col)
+180 -25
View File
@@ -150,26 +150,89 @@ func configParser(file string) (koanf.Parser, error) {
return nil, fmt.Errorf("unsupported config file format %q: use .json, .yaml, .yml or .hujson", filepath.Ext(file)) //nolint:err113
}
// normaliseConfigMap lowercases keys at every depth and drops nulls, so
// lookups are case-insensitive and null means unset.
func normaliseConfigMap(m map[string]any) map[string]any {
out := make(map[string]any, len(m))
// caseSensitiveMaps are the open maps whose keys keep their case: OAuth
// parameter names are case-sensitive. Every other open map's keys are
// lowercased, in files and variables alike: DNS names and DNS provider
// settings ignore case.
var caseSensitiveMaps = []string{"oidc.extra_params"}
for k, v := range m {
if v == nil {
// keyCase spells name, a key written below path ("" for the top), as the
// loader matches it. A configuration key is matched only as written, in
// lower case; an open map's entry name follows that map's rule, also when
// a dotted name reaches into the map.
func keyCase(path, name string) string {
if root := openMapRoot(path); root != "" {
return entryCase(root, name)
}
parts := strings.Split(name, ".")
for i := range len(parts) - 1 {
head := strings.Join(parts[:i+1], ".")
if root := joinConfigPath(path, head); isOpenMapPath(root) {
return head + "." + entryCase(root, strings.Join(parts[i+1:], "."))
}
}
return name
}
func entryCase(root, name string) string {
if slices.Contains(caseSensitiveMaps, root) {
return name
}
return strings.ToLower(name)
}
// normaliseConfigMap spells the keys of m, written below path, by keyCase
// and drops nulls, list elements included, so null means unset. Two keys
// spelled alike are passed to collide, the first kept: neither is meant
// over the other.
func normaliseConfigMap(m map[string]any, path string, collide func(path, a, b string)) map[string]any {
out := make(map[string]any, len(m))
written := make(map[string]string, len(m))
for _, k := range slices.Sorted(maps.Keys(m)) {
if m[k] == nil {
continue
}
out[strings.ToLower(k)] = normaliseConfigValue(v)
key := keyCase(path, k)
if first, ok := written[key]; ok {
collide(path, first, k)
continue
}
written[key] = k
out[key] = normaliseConfigValue(openMapObject(joinConfigPath(path, key), m[k]), joinConfigPath(path, key), collide)
}
return out
}
func normaliseConfigValue(v any) any {
// openMapObject is v, set at path, as a map when path is an open map and v
// a JSON object written as a string, the form a variable takes, so its keys
// follow the map's rule as written ones do. Any other v is returned as is:
// decode reports a string that is not an object.
func openMapObject(path string, v any) any {
s, ok := v.(string)
if !ok || !slices.Contains(openMapKeys(), path) {
return v
}
var m map[string]any
if stdjson.Unmarshal([]byte(s), &m) != nil || m == nil {
return v
}
return m
}
func normaliseConfigValue(v any, path string, collide func(path, a, b string)) any {
switch x := v.(type) {
case map[string]any:
return normaliseConfigMap(x)
return normaliseConfigMap(x, path, collide)
case map[any]any:
// YAML maps with a non-string key.
m := make(map[string]any, len(x))
@@ -177,11 +240,55 @@ func normaliseConfigValue(v any) any {
m[fmt.Sprint(k)] = e
}
return normaliseConfigMap(m)
return normaliseConfigMap(m, path, collide)
case []any:
out := make([]any, len(x))
for i, e := range x {
out[i] = normaliseConfigValue(e)
out := make([]any, 0, len(x))
for _, e := range x {
if e != nil {
out = append(out, normaliseConfigValue(e, path, collide))
}
}
return out
}
return v
}
// caseCollision reports two keys below path that differ only in case where
// case is ignored, naming both but no value, at where.
func caseCollision(path, a, b, where string) error {
in := ""
if path != "" {
in = " in " + path
}
return &types.ConfigError{
Reason: fmt.Sprintf("configuration keys %q and %q%s differ only in case%s", a, b, in, where),
Hint: "keep one: case is ignored there",
}
}
// dropNulls drops null entries and list elements at every depth of a
// variable's JSON, keeping its keys as written: null means unset, as in a
// file.
func dropNulls(v any) any {
switch x := v.(type) {
case map[string]any:
out := make(map[string]any, len(x))
for k, e := range x {
if e != nil {
out[k] = dropNulls(e)
}
}
return out
case []any:
out := make([]any, 0, len(x))
for _, e := range x {
if e != nil {
out = append(out, dropNulls(e))
}
}
return out
@@ -220,14 +327,17 @@ func openMapKeys() []string {
return open
}
func isOpenMapPath(path string) bool {
func isOpenMapPath(path string) bool { return openMapRoot(path) != "" }
// openMapRoot is the open map path is, or is below, or "".
func openMapRoot(path string) string {
for _, o := range openMapKeys() {
if path == o || strings.HasPrefix(path, o+".") {
return true
return o
}
}
return false
return ""
}
// configPathParts splits path into names as expansion nests them: below an
@@ -395,10 +505,13 @@ func (s *configSource) loadFile() error {
return fmt.Errorf("fatal error reading config file %s: %w", s.file, err)
}
m = normaliseConfigMap(m)
var errs []error
m = normaliseConfigMap(m, "", func(path, a, b string) {
errs = append(errs, caseCollision(path, a, b, " ("+s.file+")"))
})
// Checked before expansion, which would otherwise discard shadowed keys.
var errs []error
s.checkKeys(&errs, m)
if len(errs) > 0 {
@@ -599,7 +712,7 @@ func (s *configSource) checkKeys(errs *[]error, m map[string]any) {
// position renders " (file:line:col)" when the key can be located, written
// nested, dotted or mixed, else " (file)".
func (s *configSource) position(path string) string {
line, col, ok := dottedPosition(s.keys, strings.Split(path, "."))
line, col, ok := dottedPosition(s.keys, "", strings.Split(path, "."))
if !ok {
return " (" + s.file + ")"
}
@@ -662,8 +775,11 @@ func (s *configSource) loadEnv(environ []string) error {
}
// A variable for an open map replaces the file's map instead of merging
// into it. Its JSON object is set without the removed forms it holds;
// a value that is not one stays a string, which decode reports.
// into it. Its JSON object is set without the removed forms it holds,
// keys spelled as in a file; a value that is not one stays a string,
// which decode reports.
var errs []error
for _, key := range slices.Sorted(maps.Keys(openLayer)) {
val := openLayer[key]
s.k.Delete(key)
@@ -681,7 +797,9 @@ func (s *configSource) loadEnv(environ []string) error {
s.warnings = append(s.warnings, r.reason("key", p+" in "+name)+"; "+r.hint())
})
v = parsed
v = normaliseConfigMap(parsed, key, func(path, a, b string) {
errs = append(errs, caseCollision(path, a, b, " (env "+name+")"))
})
}
err := s.k.Set(key, v)
@@ -695,7 +813,7 @@ func (s *configSource) loadEnv(environ []string) error {
return err
}
return s.foldProviderEnv(env)
return errors.Join(append(errs, s.foldProviderEnv(env))...)
}
// foldProviderEnv sets HEADSCALE_DNS_CHALLENGE_PROVIDER_NAME, then each
@@ -881,6 +999,10 @@ func (s *configSource) decode() (*types.Config, error) {
return nil, s.decodeErrors(err)
}
if settings := cfg.DNSConfig.Challenge.ProviderSettings; settings != nil {
cfg.DNSConfig.Challenge.ProviderSettings = providerText(settings).(map[string]any) //nolint:forcetypeassert // a map stays a map
}
cfg.ServerURL = strings.TrimRight(cfg.ServerURL, "/")
for i, p := range cfg.TrustedProxies {
cfg.TrustedProxies[i] = p.Masked()
@@ -891,6 +1013,39 @@ func (s *configSource) decode() (*types.Config, error) {
return &cfg, nil
}
// providerText is a DNS provider setting with every number, bool, date and
// time as its text, as a variable writes it: the provider's decoder takes
// text, and text reads back the same from every file format, where a
// number or date may not.
func providerText(v any) any {
switch x := v.(type) {
case map[string]any:
out := make(map[string]any, len(x))
for k, e := range x {
out[k] = providerText(e)
}
return out
case []any:
out := make([]any, len(x))
for i, e := range x {
out[i] = providerText(e)
}
return out
case time.Time:
// From a YAML timestamp. Format has text for every one, where
// MarshalText fails on an offset of 24 hours.
return x.Format(time.RFC3339Nano)
}
if text, ok := util.ScalarText(reflect.ValueOf(v)); ok {
return text
}
return v
}
// configDir is where relative paths in the configuration are resolved: the
// config file's directory, or the working directory without a file.
func (s *configSource) configDir() string {
@@ -1167,7 +1322,7 @@ func toList(s string, elem reflect.Type) (any, error) {
return nil, &types.ConfigError{Reason: "is not a JSON list", Hint: hint, Cause: err}
}
return list, nil
return dropNulls(list), nil
}
func toObject(s string) (any, error) {
@@ -1182,7 +1337,7 @@ func toObject(s string) (any, error) {
}
}
return m, nil
return dropNulls(m), nil
}
// plainMap is cfg as nested maps of plain values, keyed as in a file: what
+153 -9
View File
@@ -127,14 +127,11 @@ func TestConfigSource(t *testing.T) {
},
},
{
name: "keys are case-insensitive",
file: "Server_URL: https://x\ndns:\n Nameservers:\n Split:\n Corp.Example.com: [10.0.0.1]\n",
check: func(t *testing.T, cfg *types.Config) {
t.Helper()
assert.Equal(t, "https://x", cfg.ServerURL)
assert.Equal(t,
map[string][]string{"corp.example.com": {"10.0.0.1"}},
cfg.DNSConfig.Nameservers.Split)
name: "keys match only as written, in lower case",
file: "Server_URL: https://x\nserver_url: https://y\nDNS:\n magic_dns: true\n",
errs: []string{
"unknown configuration key Server_URL (", "config.yaml:1:1)",
"unknown configuration key DNS (", "config.yaml:3:1)",
},
},
{
@@ -174,7 +171,8 @@ func TestConfigSource(t *testing.T) {
check: func(t *testing.T, cfg *types.Config) {
t.Helper()
assert.Equal(t, "cloudflare", cfg.DNSConfig.Challenge.ProviderName())
assert.Equal(t, 1, cfg.DNSConfig.Challenge.ProviderSettings["whatever"])
// Settings are text; the provider converts them to its types.
assert.Equal(t, "1", cfg.DNSConfig.Challenge.ProviderSettings["whatever"])
},
},
{
@@ -3938,3 +3936,149 @@ func TestEnvNames(t *testing.T) {
})
}
}
// FuzzLoad: no file makes Load panic, and one that loads round-trips.
func FuzzLoad(f *testing.F) {
seeds, err := filepath.Glob(filepath.Join(compatDir, "*.yaml"))
require.NoError(f, err)
for _, s := range seeds {
b, err := os.ReadFile(s)
require.NoError(f, err)
f.Add(b)
}
for _, v := range roundTripValues {
if v.file != "" {
f.Add([]byte(v.file))
}
}
f.Fuzz(func(t *testing.T, data []byte) {
path := filepath.Join(t.TempDir(), "config.yaml")
require.NoError(t, os.WriteFile(path, data, 0o600))
l, err := Load(path, true, nil)
if err != nil {
return
}
for _, ext := range fileFormats {
got, err := roundTrip(t, l.Config, ext)
require.NoError(t, err, ext)
if diff := gocmp.Diff(l.Config, got, roundTripOpts); diff != "" {
t.Errorf("%s round trip (-written +loaded):\n%s", ext, diff)
}
}
})
}
// TestMapKeyCase: an open map's keys follow its rule in every format and in
// variables: oidc.extra_params keeps their case, dns.nameservers.split and
// DNS provider settings, nested ones included, are lowercased. The config
// then round-trips exactly.
func TestMapKeyCase(t *testing.T) {
unsetHeadscaleEnv(t)
for name, tt := range map[string]struct {
ext, file string
env []string
}{
"yaml": {ext: ".yaml", file: "oidc:\n extra_params:\n Login_Hint: a\n login_hint: b\n" +
"dns:\n nameservers:\n split:\n Corp.Example.COM: [10.0.0.1]\n" +
" challenge:\n provider:\n Name: acmedns\n Config:\n Laptop.Example.com:\n Password: x\n"},
"yaml dotted": {ext: ".yaml", file: "oidc.extra_params.Login_Hint: a\noidc.extra_params.login_hint: b\n" +
"dns.nameservers.split.Corp.Example.COM: [10.0.0.1]\n" +
"dns.challenge.provider: {Name: acmedns, Config: {Laptop.Example.com: {Password: x}}}\n"},
"json": {ext: ".json", file: `{"oidc": {"extra_params": {"Login_Hint": "a", "login_hint": "b"}},
"dns": {"nameservers": {"split": {"Corp.Example.COM": ["10.0.0.1"]}},
"challenge": {"provider": {"Name": "acmedns", "Config": {"Laptop.Example.com": {"Password": "x"}}}}}}`},
"yaml string objects": {ext: ".yaml", file: "oidc:\n extra_params: '{\"Login_Hint\": \"a\", \"login_hint\": \"b\"}'\n" +
"dns:\n nameservers:\n split: '{\"Corp.Example.COM\": [\"10.0.0.1\"]}'\n" +
" challenge:\n provider: '{\"Name\": \"acmedns\", \"Config\": {\"Laptop.Example.com\": {\"Password\": \"x\"}}}'\n"},
"env": {env: []string{
`HEADSCALE_OIDC_EXTRA_PARAMS={"Login_Hint":"a","login_hint":"b"}`,
`HEADSCALE_DNS_NAMESERVERS_SPLIT={"Corp.Example.COM":["10.0.0.1"]}`,
`HEADSCALE_DNS_CHALLENGE_PROVIDER={"Name":"acmedns","Config":{"Laptop.Example.com":{"Password":"x"}}}`,
}},
} {
t.Run(name, func(t *testing.T) {
path := ""
if tt.file != "" {
path = filepath.Join(t.TempDir(), "config"+tt.ext)
require.NoError(t, os.WriteFile(path, []byte(tt.file), 0o600))
}
l, err := Load(path, path != "", tt.env)
require.NoError(t, err)
cfg := l.Config
assert.Equal(t, map[string]string{"Login_Hint": "a", "login_hint": "b"}, cfg.OIDC.ExtraParams)
assert.Equal(t, map[string][]string{"corp.example.com": {"10.0.0.1"}}, cfg.DNSConfig.Nameservers.Split)
assert.Equal(t, map[string]any{
"name": "acmedns",
"config": map[string]any{"laptop.example.com": map[string]any{"password": "x"}},
}, cfg.DNSConfig.Challenge.ProviderSettings)
for _, ext := range fileFormats {
got, err := roundTrip(t, cfg, ext)
require.NoError(t, err, ext)
if diff := gocmp.Diff(cfg, got, roundTripOpts); diff != "" {
t.Errorf("%s round trip (-written +loaded):\n%s", ext, diff)
}
}
})
}
}
// TestMapKeyCollision: two keys that one spelling makes the same are an
// error naming both, not one picked at random, and showing no value.
func TestMapKeyCollision(t *testing.T) {
for name, tt := range map[string]struct {
file string
env []string
want string
}{
"split string object": {
file: "dns:\n nameservers:\n split: '{\"Corp.example.com\": [\"marker-a\"], \"corp.example.com\": [\"marker-b\"]}'\n",
want: `configuration keys "Corp.example.com" and "corp.example.com" in dns.nameservers.split differ only in case (`,
},
"provider string object": {
file: "dns:\n challenge:\n provider: '{\"API_TOKEN\": \"marker-a\", \"api_token\": \"marker-b\"}'\n",
want: `configuration keys "API_TOKEN" and "api_token" in dns.challenge.provider differ only in case (`,
},
"split": {
file: "dns:\n nameservers:\n split:\n Corp.example.com: [10.0.0.1]\n corp.example.com: [10.0.0.2]\n",
want: `configuration keys "Corp.example.com" and "corp.example.com" in dns.nameservers.split differ only in case (`,
},
"provider setting": {
file: "dns:\n challenge:\n provider:\n API_TOKEN: marker-a\n api_token: marker-b\n",
want: `configuration keys "API_TOKEN" and "api_token" in dns.challenge.provider differ only in case (`,
},
"provider registration": {
file: "dns:\n challenge:\n provider:\n config:\n A.example.com: {password: marker-a}\n a.example.com: {password: marker-b}\n",
want: `configuration keys "A.example.com" and "a.example.com" in dns.challenge.provider.config differ only in case (`,
},
"env split": {
env: []string{`HEADSCALE_DNS_NAMESERVERS_SPLIT={"Corp.example.com":["marker-a"],"corp.example.com":["marker-b"]}`},
want: `configuration keys "Corp.example.com" and "corp.example.com" in dns.nameservers.split differ only in case (env HEADSCALE_DNS_NAMESERVERS_SPLIT)`,
},
"env provider": {
env: []string{`HEADSCALE_DNS_CHALLENGE_PROVIDER={"Name":"marker-a","name":"marker-b"}`},
want: `configuration keys "Name" and "name" in dns.challenge.provider differ only in case (env HEADSCALE_DNS_CHALLENGE_PROVIDER)`,
},
} {
t.Run(name, func(t *testing.T) {
dir := t.TempDir()
if tt.file != "" {
require.NoError(t, os.WriteFile(filepath.Join(dir, "config.yaml"), []byte(tt.file), 0o600))
}
_, err := Load(dir, false, tt.env)
require.ErrorContains(t, err, tt.want)
requireHidden(t, err, "marker")
})
}
}
+222
View File
@@ -4,9 +4,16 @@ import (
"cmp"
"context"
"maps"
"net/netip"
"os"
"path/filepath"
"testing"
gocmp "github.com/google/go-cmp/cmp"
"github.com/google/go-cmp/cmp/cmpopts"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/knadh/koanf/providers/confmap"
"github.com/knadh/koanf/v2"
"github.com/libdns/libdns"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
@@ -16,6 +23,221 @@ import (
// fileFormats are the formats a configuration can be written in.
var fileFormats = []string{".yaml", ".json", ".hujson"}
// roundTrip writes cfg as a file of ext, secrets as written, and loads it
// back without environment.
func roundTrip(tb testing.TB, cfg *types.Config, ext string) (*types.Config, error) {
tb.Helper()
parser, err := configParser(ext)
require.NoError(tb, err)
out, err := parser.Marshal(plainMap(cfg, false))
require.NoError(tb, err)
path := filepath.Join(tb.TempDir(), "config"+ext)
require.NoError(tb, os.WriteFile(path, out, 0o600))
l, err := Load(path, true, nil)
return l.Config, err
}
// roundTripOpts compare a Config with the one its file loads to.
var roundTripOpts = gocmp.Options{
cmpopts.EquateEmpty(),
cmpopts.EquateComparable(netip.Prefix{}),
cmpopts.IgnoreFields(types.Config{}, "ConfigDir"),
cmpopts.IgnoreUnexported(types.Config{}),
}
// TestRoundTrip: a configuration written by Marshal's map, in any format,
// loads back to itself.
func TestRoundTrip(t *testing.T) {
unsetHeadscaleEnv(t)
rows := append([]compatRow{{name: "default"}}, compatRows(t)...)
for _, row := range rows {
t.Run(row.name, func(t *testing.T) {
var cfg *types.Config
if row.name == "default" {
d := Default()
cfg = &d
} else {
l, err := Load(stageCompat(t, row.file, row.envFile), false, os.Environ())
if err != nil {
t.Skipf("does not load: %v", err)
}
cfg = l.Config
}
for _, ext := range fileFormats {
t.Run(ext, func(t *testing.T) {
got, err := roundTrip(t, cfg, ext)
require.NoError(t, err)
if diff := gocmp.Diff(cfg, got, roundTripOpts); diff != "" {
t.Errorf("round trip (-written +loaded):\n%s", diff)
}
})
}
})
}
}
// roundTripValues are inputs at the edges of what a file or variable can
// hold. FuzzLoad seeds from them too.
var roundTripValues = []struct {
name string
file string
env []string
want func(*types.Config) any // what it loads to, compared with wantVal
wantVal any
}{
{
name: "provider integer beyond 64 bits signed",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n api_token: 18446744073709551615\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "api_token": "18446744073709551615"},
},
{
name: "provider integer beyond float precision",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n api_token: 9007199254740993\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "api_token": "9007199254740993"},
},
{
name: "provider scalars",
file: "dns:\n challenge:\n provider:\n name: 1\n a: true\n b: 1.5\n c: [1, false]\n d: {e: 2}\n",
want: providerSettings,
wantVal: map[string]any{
"name": "1", "a": "true", "b": "1.5",
"c": []any{"1", "false"}, "d": map[string]any{"e": "2"},
},
},
{
name: "provider nulls",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n x: [null]\n y: null\n z: {a: null}\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "x": []any{}, "z": map[string]any{}},
},
{
name: "provider nan",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n api_token: .nan\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "api_token": "NaN"},
},
{
name: "provider inf",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n config:\n a: [-.inf]\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "config": map[string]any{"a": []any{"-Inf"}}},
},
// Parsers read unquoted dates and times as time types, which load as
// their text.
{
name: "provider yaml timestamps",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n d: 2026-11-08\n t: 2026-11-08T10:00:00.5+01:00\n l: [2026-11-08]\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "d": "2026-11-08T00:00:00Z", "t": "2026-11-08T10:00:00.5+01:00", "l": []any{"2026-11-08T00:00:00Z"}},
},
{
name: "provider yaml timestamp with a 24 hour offset",
file: "dns:\n challenge:\n provider:\n name: cloudflare\n t: 2026-11-08T10:00:00+24:00\n",
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "t": "2026-11-08T10:00:00+24:00"},
},
{
name: "list null",
file: "dns:\n nameservers:\n global: [null, 1.1.1.1]\n",
want: globalNameservers,
wantVal: []string{"1.1.1.1"},
},
{
name: "env split null",
env: []string{`HEADSCALE_DNS_NAMESERVERS_SPLIT={"a.example.com":null,"b.example.com":["10.0.0.1",null]}`},
want: func(c *types.Config) any { return c.DNSConfig.Nameservers.Split },
wantVal: map[string][]string{"b.example.com": {"10.0.0.1"}},
},
{
name: "env provider null",
env: []string{`HEADSCALE_DNS_CHALLENGE_PROVIDER={"name":"cloudflare","api_token":null,"x":[null,1],"y":{"z":null}}`},
want: providerSettings,
wantVal: map[string]any{"name": "cloudflare", "x": []any{"1"}, "y": map[string]any{}},
},
{
name: "env list null",
env: []string{`HEADSCALE_DNS_NAMESERVERS_GLOBAL=["1.1.1.1",null]`},
want: globalNameservers,
wantVal: []string{"1.1.1.1"},
},
}
func providerSettings(c *types.Config) any { return c.DNSConfig.Challenge.ProviderSettings }
func globalNameservers(c *types.Config) any { return c.DNSConfig.Nameservers.Global }
// TestRoundTripValues: values at the edges load exactly.
func TestRoundTripValues(t *testing.T) {
for _, tt := range roundTripValues {
t.Run(tt.name, func(t *testing.T) {
path := filepath.Join(t.TempDir(), "config.yaml")
require.NoError(t, os.WriteFile(path, []byte(tt.file), 0o600))
l, err := Load(path, true, tt.env)
require.NoError(t, err)
if tt.want != nil {
assert.Equal(t, tt.wantVal, tt.want(l.Config))
}
for _, ext := range fileFormats {
got, err := roundTrip(t, l.Config, ext)
require.NoError(t, err, ext)
if diff := gocmp.Diff(l.Config, got, roundTripOpts); diff != "" {
t.Errorf("%s round trip (-written +loaded):\n%s", ext, diff)
}
}
})
}
}
// TestMarshalNullablePrefix: a nil prefix is written as an explicit unset,
// which wins over a layer below that sets it.
func TestMarshalNullablePrefix(t *testing.T) {
cfg := Default()
require.Nil(t, cfg.Prefixes.V4)
yamlOut, err := Marshal(&cfg, ".yaml")
require.NoError(t, err)
assert.Contains(t, string(yamlOut), `v4: ""`)
for _, ext := range fileFormats {
t.Run(ext, func(t *testing.T) {
out, err := Marshal(&cfg, ext)
require.NoError(t, err)
path := filepath.Join(t.TempDir(), "config"+ext)
require.NoError(t, os.WriteFile(path, out, 0o600))
below := Default()
v4 := netip.MustParsePrefix("100.64.0.0/10")
below.Prefixes.V4 = &v4
s := &configSource{k: koanf.New("."), file: path, envVars: map[string]string{}}
require.NoError(t, s.k.Load(confmap.Provider(plainMap(&below, false), ""), nil))
require.NoError(t, s.loadFile())
got, err := s.decode()
require.NoError(t, err)
assert.Nil(t, got.Prefixes.V4)
})
}
}
// fakeProvider is a Go-only DNS provider.
type fakeProvider struct{ Token string }
@@ -0,0 +1,3 @@
HEADSCALE_DNS_NAMESERVERS_SPLIT={"Corp.example.com":["10.0.0.1"],"corp.example.com":["10.0.0.2"]}
HEADSCALE_DNS_CHALLENGE_PROVIDER={"name":"acmedns","config":{"Laptop.example.com":{"password":"marker-a"},"laptop.example.com":{"password":"marker-b"}}}
HEADSCALE_OIDC_EXTRA_PARAMS={"Domain_Hint":"a","domain_hint":"b"}
+6
View File
@@ -0,0 +1,6 @@
{
"warnings": [
"no config file found, using defaults"
],
"error": "Fatal config error: configuration keys \"Laptop.example.com\" and \"laptop.example.com\" in dns.challenge.provider.config differ only in case (env HEADSCALE_DNS_CHALLENGE_PROVIDER)\n hint: keep one: case is ignored there\n\nFatal config error: configuration keys \"Corp.example.com\" and \"corp.example.com\" in dns.nameservers.split differ only in case (env HEADSCALE_DNS_NAMESERVERS_SPLIT)\n hint: keep one: case is ignored there\n"
}
+12
View File
@@ -0,0 +1,12 @@
HEADSCALE_SERVER_URL=https://hs.example.com
HEADSCALE_NOISE_PRIVATE_KEY_PATH=/var/lib/headscale/noise.key
HEADSCALE_PREFIXES_V4=100.64.0.0/10
HEADSCALE_DATABASE_TYPE=sqlite
HEADSCALE_DATABASE_SQLITE_PATH=/var/lib/headscale/db.sqlite
HEADSCALE_DNS_MAGIC_DNS=false
HEADSCALE_DNS_OVERRIDE_LOCAL_DNS=false
# Map keys as in a file: split domains and DNS provider settings are
# lowercased, OIDC extra params keep their case.
HEADSCALE_DNS_NAMESERVERS_SPLIT={"Corp.Example.COM":["10.0.0.1"]}
HEADSCALE_OIDC_EXTRA_PARAMS={"Domain_Hint":"example.com","domain_hint":"other.example.com"}
HEADSCALE_DNS_CHALLENGE_PROVIDER={"NAME":"cloudflare","API_TOKEN":"marker-api-token"}
+179
View File
@@ -0,0 +1,179 @@
{
"config": {
"ServerURL": "https://hs.example.com",
"Addr": "",
"MetricsAddr": "",
"TrustedProxies": null,
"Node": {
"Expiry": 0,
"Ephemeral": {
"InactivityTimeout": 120000000000
},
"Routes": {
"HA": {
"ProbeInterval": 10000000000,
"ProbeTimeout": 5000000000
}
}
},
"PreAuthKeys": {
"RevokedRetention": 604800000000000
},
"PrefixV4": "100.64.0.0/10",
"PrefixV6": null,
"IPAllocation": "sequential",
"NoisePrivateKeyPath": "/var/lib/headscale/noise.key",
"BaseDomain": "",
"Log": {
"Format": "text",
"Level": "info"
},
"DisableUpdateCheck": false,
"Database": {
"Type": "sqlite3",
"Debug": false,
"Gorm": {
"Debug": false,
"SlowThreshold": 0,
"SkipErrRecordNotFound": false,
"ParameterizedQueries": false
},
"Sqlite": {
"Path": "/var/lib/headscale/db.sqlite",
"WriteAheadLog": true,
"WALAutoCheckPoint": 1000
},
"Postgres": {
"Host": "",
"Port": 0,
"Name": "",
"User": "",
"Ssl": "false",
"MaxOpenConnections": 10,
"MaxIdleConnections": 10,
"ConnMaxIdleTimeSecs": 3600
}
},
"DERP": {
"ServerEnabled": false,
"AutomaticallyAddEmbeddedDerpRegion": true,
"ServerRegionID": 0,
"ServerRegionCode": "",
"ServerRegionName": "",
"ServerPrivateKeyPath": "",
"ServerVerifyClients": true,
"STUNAddr": "",
"URLs": [],
"Paths": null,
"DERPMap": null,
"AutoUpdate": false,
"UpdateFrequency": 10800000000000,
"IPv4": "",
"IPv6": ""
},
"TLS": {
"CertPath": "",
"KeyPath": "",
"ACME": {
"Hostname": "",
"ChallengeType": "HTTP-01",
"HTTPListen": ":http",
"URL": "",
"Email": "",
"CacheDir": "/var/lib/headscale/cache"
}
},
"DNSConfig": {
"MagicDNS": false,
"BaseDomain": "",
"OverrideLocalDNS": false,
"Nameservers": {
"Global": [],
"Split": {
"corp.example.com": [
"10.0.0.1"
]
}
},
"SearchDomains": [],
"ExtraRecords": null,
"ExtraRecordsPath": "",
"Certificates": {
"Enabled": false,
"Zone": ""
}
},
"TailcfgDNSConfig": {
"Routes": {
"corp.example.com": [
{
"Addr": "10.0.0.1"
}
]
}
},
"DNSChallenge": {
"PropagationTimeout": 120000000000,
"Resolvers": [
"1.1.1.1:53",
"8.8.8.8:53"
],
"ProviderName": "cloudflare"
},
"UnixSocket": "/var/run/headscale/headscale.sock",
"UnixSocketPermission": 504,
"OIDC": {
"OnlyStartIfOIDCIsAvailable": true,
"Issuer": "",
"ClientID": "",
"Scope": [
"openid",
"profile",
"email"
],
"ExtraParams": {
"Domain_Hint": "example.com",
"domain_hint": "other.example.com"
},
"AllowedDomains": null,
"AllowedUsers": null,
"AllowedGroups": null,
"EmailVerifiedRequired": true,
"UseExpiryFromToken": false,
"PKCE": {
"Enabled": false,
"Method": "S256"
}
},
"LogTail": {
"Enabled": false
},
"Taildrop": {
"Enabled": true
},
"AutoUpdate": {
"Enabled": false
},
"CLI": {
"Address": "",
"Timeout": 5000000000,
"Insecure": false
},
"Policy": {
"Path": "",
"Mode": "file"
},
"Tuning": {
"BatchChangeDelay": 800000000,
"NodeMapSessionBufferedChanSize": 30,
"BatcherWorkers": 0,
"RegisterCacheExpiration": 0,
"RegisterCacheMaxEntries": 0,
"NodeStoreBatchSize": 100,
"NodeStoreBatchTimeout": 500000000
}
},
"warnings": [
"no config file found, using defaults"
]
}
+1 -1
View File
@@ -195,7 +195,7 @@
"groups"
],
"ExtraParams": {
"login_hint": "file"
"Login_Hint": "file"
},
"AllowedDomains": [
"example.com"
+3
View File
@@ -0,0 +1,3 @@
{
"error": "Fatal config error: configuration keys \"API_TOKEN\" and \"api_token\" in dns.challenge.provider differ only in case ($DIR/config.yaml)\n hint: keep one: case is ignored there\n\nFatal config error: configuration keys \"Corp.example.com\" and \"corp.example.com\" in dns.nameservers.split differ only in case ($DIR/config.yaml)\n hint: keep one: case is ignored there\n\nFatal config error: unknown configuration key Server_URL ($DIR/config.yaml:5:1)\n"
}
@@ -0,0 +1,19 @@
# Keys that differ only in case where case is ignored; extra_params keeps
# case, so its two keys are distinct. Configuration keys match only as
# written, so Server_URL is unknown.
server_url: https://hs.example.com
Server_URL: https://marker-other.example.com
dns:
nameservers:
split:
Corp.example.com: [10.0.0.1]
corp.example.com: [10.0.0.2]
challenge:
provider:
name: cloudflare
API_TOKEN: marker-token-a
api_token: marker-token-b
oidc:
extra_params:
Domain_Hint: a
domain_hint: b