From 2db863d5e6a0c35dbcfd8f7f9e9ca9c17587363e Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Mon, 9 Nov 2026 11:57:55 +0000 Subject: [PATCH] config: clear a key from the environment with "" A HEADSCALE_* value of "" means what key: "" means in a file, errors included, so an env-only setup can clear a defaulted key. An empty variable still counts as unset. Updates #1926 --- hscontrol/config/default_test.go | 2 +- hscontrol/config/load.go | 14 ++++- hscontrol/config/load_test.go | 100 +++++++++++++++++++++++++++++-- hscontrol/config/reference.go | 18 +++++- hscontrol/config/validate.go | 4 +- 5 files changed, 123 insertions(+), 15 deletions(-) diff --git a/hscontrol/config/default_test.go b/hscontrol/config/default_test.go index b5af4a5b2..912c9870c 100644 --- a/hscontrol/config/default_test.go +++ b/hscontrol/config/default_test.go @@ -227,7 +227,7 @@ func TestValidateGoData(t *testing.T) { set: func(c *types.Config) { c.ServerURL = "headscale.example.com" }, wantErr: `server_url: "headscale.example.com"`, }, - // A variable cannot clear a key: `""` in one is the text itself. + // Built in Go, `""` is the text itself, not an empty value. { name: "base domain quotes", set: func(c *types.Config) { c.DNSConfig.BaseDomain = `""` }, diff --git a/hscontrol/config/load.go b/hscontrol/config/load.go index b85b3f885..660f0a244 100644 --- a/hscontrol/config/load.go +++ b/hscontrol/config/load.go @@ -796,9 +796,17 @@ func (s *configSource) loadEnv(environ []string) error { for _, kv := range environ { name, val, _ := strings.Cut(kv, "=") // Empty means unset, so a blank variable never overrides the file. - if val != "" && strings.HasPrefix(name, configEnvPrefix) { - env[name] = val + if val == "" || !strings.HasPrefix(name, configEnvPrefix) { + continue } + + // `""` is the empty value, as in a file: a defaulted key can be + // cleared without one. + if val == `""` { + val = "" + } + + env[name] = val } layer := map[string]any{} @@ -905,7 +913,7 @@ func (s *configSource) foldProviderEnv(env map[string]string) error { folded := false fold := func(setting string) { key := providerKey + "." + setting - if v := env[configEnvName(key)]; v != "" { + if v, ok := env[configEnvName(key)]; ok { settings[setting] = v s.envVars[key] = configEnvName(key) folded = true diff --git a/hscontrol/config/load_test.go b/hscontrol/config/load_test.go index 44affbf7d..2b706a145 100644 --- a/hscontrol/config/load_test.go +++ b/hscontrol/config/load_test.go @@ -13,6 +13,7 @@ import ( "os" "path/filepath" "reflect" + "regexp" "runtime" "slices" "strconv" @@ -868,9 +869,9 @@ func TestDefaultsFitTypes(t *testing.T) { } } -// TestDefaultsCanBeCleared: a key with a default can still be emptied, in -// the file or, for a list, with "[]" in a variable. An empty variable -// counts as unset, so a variable cannot empty a text or a prefix. +// TestDefaultsCanBeCleared: a key with a default can still be emptied with +// "" in the file or in a variable, and a list also with []. An empty +// variable counts as unset. func TestDefaultsCanBeCleared(t *testing.T) { const serverURL = "server_url: https://headscale.example.com\n" @@ -923,9 +924,29 @@ func TestDefaultsCanBeCleared(t *testing.T) { }, }, { - name: "quotes in env are text", - env: []string{"HEADSCALE_DNS_MAGIC_DNS=false", `HEADSCALE_DNS_BASE_DOMAIN=""`}, - wantErr: "dns.base_domain is not a DNS name", + name: "env base domain", + env: []string{"HEADSCALE_DNS_MAGIC_DNS=false", `HEADSCALE_DNS_BASE_DOMAIN=""`}, + check: func(t *testing.T, c *types.Config) { t.Helper(); assert.Empty(t, c.DNSConfig.BaseDomain) }, + }, + { + name: "env prefix v6", + env: []string{`HEADSCALE_PREFIXES_V6=""`}, + check: func(t *testing.T, c *types.Config) { + t.Helper() + assert.Nil(t, c.Prefixes.V6) + require.NotNil(t, c.Prefixes.V4) + assert.Equal(t, *d.Prefixes.V4, *c.Prefixes.V4) + }, + }, + { + name: "env derp urls quotes", + env: []string{`HEADSCALE_DERP_URLS=""`}, + check: func(t *testing.T, c *types.Config) { t.Helper(); assert.Empty(t, c.DERP.URLs) }, + }, + { + name: "env base domain required by magic dns", + env: []string{`HEADSCALE_DNS_BASE_DOMAIN=""`}, + wantErr: "dns.base_domain is required when dns.magic_dns is true", }, } @@ -947,6 +968,73 @@ func TestDefaultsCanBeCleared(t *testing.T) { } } +// TestEnvEmptyLikeFile: a variable set to "" means what `key: ""` means in +// the file, for every kind of key, errors included. +func TestEnvEmptyLikeFile(t *testing.T) { + const serverURL = "server_url: https://headscale.example.com\n" + + // Where a load error says the value came from. + origin := regexp.MustCompile(` \((env [A-Z0-9_]+|/[^)]*)\)$`) + loadReasons := func(err error) []string { + rs := reasons(types.ConfigErrors(err)) + for i, r := range rs { + rs[i] = origin.ReplaceAllString(r, "") + } + + return rs + } + + tests := []struct { + name string + file string + env []string + }{ + {name: "text", file: "dns:\n magic_dns: false\n base_domain: \"\"\n", env: []string{"HEADSCALE_DNS_MAGIC_DNS=false", `HEADSCALE_DNS_BASE_DOMAIN=""`}}, + {name: "prefix", file: "prefixes:\n v6: \"\"\n", env: []string{`HEADSCALE_PREFIXES_V6=""`}}, + {name: "list", file: "derp:\n urls: \"\"\n", env: []string{`HEADSCALE_DERP_URLS=""`}}, + {name: "list of objects", file: "dns:\n extra_records: \"\"\n", env: []string{`HEADSCALE_DNS_EXTRA_RECORDS=""`}}, + {name: "enum", file: "log:\n level: \"\"\n", env: []string{`HEADSCALE_LOG_LEVEL=""`}}, + {name: "integer", file: "database:\n postgres:\n port: \"\"\n", env: []string{`HEADSCALE_DATABASE_POSTGRES_PORT=""`}}, + {name: "boolean", file: "dns:\n magic_dns: \"\"\n", env: []string{`HEADSCALE_DNS_MAGIC_DNS=""`}}, + {name: "duration", file: "node:\n expiry: \"\"\n", env: []string{`HEADSCALE_NODE_EXPIRY=""`}}, + {name: "map", file: "dns:\n nameservers:\n split: \"\"\n", env: []string{`HEADSCALE_DNS_NAMESERVERS_SPLIT=""`}}, + {name: "secret", file: "oidc:\n client_secret: \"\"\n", env: []string{`HEADSCALE_OIDC_CLIENT_SECRET=""`}}, + {name: "dns provider", file: "dns:\n challenge:\n provider: \"\"\n", env: []string{`HEADSCALE_DNS_CHALLENGE_PROVIDER=""`}}, + { + name: "dns provider setting", + file: "dns:\n challenge:\n provider:\n name: cloudflare\n api_token: \"\"\n", + env: []string{"HEADSCALE_DNS_CHALLENGE_PROVIDER_NAME=cloudflare", `HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN=""`}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + fromFile, fileErr := Load(writeConfig(t, serverURL+tt.file), true, nil) + fromEnv, envErr := Load(writeConfig(t, serverURL), true, tt.env) + + if fileErr != nil { + require.Error(t, envErr) + assert.Equal(t, loadReasons(fileErr), loadReasons(envErr)) + + return + } + + require.NoError(t, envErr) + + diff := gocmp.Diff(fromFile.Config, fromEnv.Config, + cmpopts.IgnoreFields(types.Config{}, "ConfigDir"), + cmpopts.IgnoreUnexported(types.Config{}), + cmpopts.EquateComparable(netip.Prefix{}), + ) + if diff != "" { + t.Errorf("file and variable differ (-file +env):\n%s", diff) + } + + assert.Equal(t, reasons(types.ConfigErrors(Validate(fromFile.Config))), reasons(types.ConfigErrors(Validate(fromEnv.Config)))) + }) + } +} + // TestNullTakesDefault: a key written with no value is unset and takes its // default, so where that default is a non-empty text, list or prefix and // no variable sets the key, loading warns. diff --git a/hscontrol/config/reference.go b/hscontrol/config/reference.go index 920279e17..39a66cf7f 100644 --- a/hscontrol/config/reference.go +++ b/hscontrol/config/reference.go @@ -30,9 +30,21 @@ const ( "Every key can also be set with an environment variable: `HEADSCALE_` and the key's path in capitals, with `_` for\n" + "`.`, e.g. `HEADSCALE_LOG_LEVEL` for `log.level`. Each key below names its variable. A variable wins over the\n" + "configuration file, which wins over the default. An empty variable, like a key written with no value in the\n" + - "file, counts as unset and keeps the default. Clear a list with `[]`, as in `HEADSCALE_DERP_URLS='[]'` or\n" + - "`HEADSCALE_DNS_NAMESERVERS_GLOBAL='[]'`; any other key with a default clears only in the configuration file, as\n" + - "in `prefixes.v6: \"\"`.\n\n" + + "file, counts as unset and keeps the default. A variable set to `\"\"` means what `\"\"` means in the configuration\n" + + "file: it clears a key with a default, as `prefixes.v6: \"\"` does, and is an error where the file's `\"\"` is one. A\n" + + "list also clears with `[]`. Quote the value so the quotes reach headscale:\n\n" + + "```shell\n" + + "export HEADSCALE_PREFIXES_V6='\"\"'\n" + + "export HEADSCALE_DERP_URLS='[]'\n" + + "```\n\n" + + "```yaml title=\"docker-compose.yaml\"\n" + + "environment:\n" + + " HEADSCALE_PREFIXES_V6: '\"\"'\n" + + " HEADSCALE_DERP_URLS: '[]'\n" + + "```\n\n" + + "An env file (a Compose `env_file`, a systemd `EnvironmentFile=`) and a systemd `Environment=` strip one level of\n" + + "quotes, so `KEY=\"\"` there arrives empty and keeps the default: write `KEY='\"\"'` in an env file and\n" + + "`Environment='KEY=\"\"'` in a unit.\n\n" + "A list is a JSON array or, unless its values are objects, its values separated by spaces. A map is a JSON object,\n" + "which replaces the map in the configuration file instead of merging into it. The examples below write every list\n" + "and map as JSON.\n\n" + diff --git a/hscontrol/config/validate.go b/hscontrol/config/validate.go index a9f7bd5e8..adf77a8ce 100644 --- a/hscontrol/config/validate.go +++ b/hscontrol/config/validate.go @@ -420,7 +420,7 @@ func validateMagicDNS(c *types.Config, v *configValidator) { } // validateBaseDomain records a ConfigError for a dns.base_domain that is -// not a DNS name, such as `""` in a variable, which is the text itself. +// not a DNS name. func validateBaseDomain(c *types.Config, v *configValidator) { base := strings.TrimSuffix(c.DNSConfig.BaseDomain, ".") if base == "" || dnsname.ValidHostname(base) == nil { @@ -430,7 +430,7 @@ func validateBaseDomain(c *types.Config, v *configValidator) { v.Add(&types.ConfigError{ Reason: "dns.base_domain is not a DNS name", Current: []types.KV{{Key: "dns.base_domain", Value: c.DNSConfig.BaseDomain}}, - Hint: `use letters, digits, "-" and "."; to clear it, write dns.base_domain: "" in the configuration file, as a variable cannot`, + Hint: `use letters, digits, "-" and "."; write "" to clear it`, See: dnsDocsURL, }) }