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
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 15:02:16 +01:00
1 parent 542fe8dd55
commit 2db863d5e6
5 files changed
+123 -15

No files matched your search

+1 -1
View File
@@ -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 = `""` },
+11 -3
View File
@@ -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
+94 -6
View File
@@ -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.
+15 -3
View File
@@ -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" +
+2 -2
View File
@@ -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,
})
}