From f5f86e69d0b742282fa02fc81bfebc8558f947ec Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Mon, 9 Nov 2026 06:35:01 +0000 Subject: [PATCH] config: require listen_addr and the sqlite path Empty values serve cannot use; empty server_url reads "is required". Updates #1926 --- cmd/headscale/cli/check_test.go | 22 ++++++++ hscontrol/config/default_test.go | 76 +++++++++++++++++++++++++- hscontrol/config/load_test.go | 91 ++++++++++++++++++++++++-------- hscontrol/config/validate.go | 52 +++++++++++++----- 4 files changed, 206 insertions(+), 35 deletions(-) diff --git a/cmd/headscale/cli/check_test.go b/cmd/headscale/cli/check_test.go index 9969cbd9c..33ac07f65 100644 --- a/cmd/headscale/cli/check_test.go +++ b/cmd/headscale/cli/check_test.go @@ -232,6 +232,28 @@ func TestCheckConfig(t *testing.T) { require.ErrorContains(t, err, "server_url") }) + // Each problem once: an empty server_url is not also missing a scheme. + for _, tt := range []struct{ name, file, want string }{ + {name: "empty file", file: "# empty\n", want: "server_url is required"}, + { + name: "empty listen_addr", + file: "server_url: https://headscale.example.com\nlisten_addr: \"\"\n", + want: "listen_addr is required", + }, + { + name: "empty sqlite path", + file: "server_url: https://headscale.example.com\ndatabase:\n sqlite:\n path: \"\"\n", + want: "database.sqlite.path is required when database.type is sqlite", + }, + } { + t.Run(tt.name, func(t *testing.T) { + _, err := runCheck(t, checkConfigCmd, writeFile(t, t.TempDir(), "config.yaml", tt.file)) + require.ErrorContains(t, err, tt.want) + require.NotContains(t, err.Error(), "missing a scheme") + require.Equal(t, 1, strings.Count(err.Error(), "Fatal config error"), err.Error()) + }) + } + t.Run("derp server without key path", func(t *testing.T) { dir := t.TempDir() diff --git a/hscontrol/config/default_test.go b/hscontrol/config/default_test.go index 912c9870c..9dfd4c19b 100644 --- a/hscontrol/config/default_test.go +++ b/hscontrol/config/default_test.go @@ -5,6 +5,7 @@ import ( "net/netip" "os" "path/filepath" + "strings" "testing" "time" @@ -87,7 +88,7 @@ func TestValidateHintsNameDefaults(t *testing.T) { func TestValidateGoData(t *testing.T) { t.Run("default needs the operator's values", func(t *testing.T) { d := Default() - assert.Equal(t, []string{"server_url is missing a scheme"}, reasons(types.ConfigErrors(Validate(&d)))) + assert.Equal(t, []string{"server_url is required"}, reasons(types.ConfigErrors(Validate(&d)))) }) t.Run("zero config", func(t *testing.T) { @@ -121,6 +122,43 @@ func TestValidateGoData(t *testing.T) { set: func(c *types.Config) { c.Addr = "nowhere" }, wantErr: "listen_addr is not a host:port address", }, + { + name: "listen address empty", + set: func(c *types.Config) { c.Addr = "" }, + wantErr: "listen_addr is required", + }, + { + name: "listen address blank", + set: func(c *types.Config) { c.Addr = " " }, + wantErr: "listen_addr is not a host:port address", + }, + { + name: "listen address random port", + set: func(c *types.Config) { c.Addr = ":0" }, + }, + { + name: "sqlite path empty", + set: func(c *types.Config) { + c.Database.Type = types.DatabaseSqliteShort + c.Database.Sqlite.Path = "" + }, + wantErr: "database.sqlite.path is required when database.type is sqlite", + }, + { + name: "sqlite3 path empty", + set: func(c *types.Config) { + c.Database.Type = types.DatabaseSqlite + c.Database.Sqlite.Path = "" + }, + wantErr: "database.sqlite.path is required when database.type is sqlite", + }, + { + name: "postgres without sqlite path", + set: func(c *types.Config) { + c.Database.Type = types.DatabasePostgres + c.Database.Sqlite.Path = "" + }, + }, { name: "url", set: func(c *types.Config) { @@ -341,6 +379,42 @@ func TestValidateGoData(t *testing.T) { } } +// TestRequiredWhenBlank: each key serve cannot run without, blanked, gets +// one reason in the form requiredKeys reads, so a key whose default goes +// away shows up as required. +func TestRequiredWhenBlank(t *testing.T) { + for _, key := range []string{"server_url", "listen_addr", "noise.private_key_path", "database.sqlite.path"} { + t.Run(key, func(t *testing.T) { + cfg := Default() + if key != "server_url" { + cfg.ServerURL = "https://headscale.example.com" + } + + blanked := false + + for _, f := range types.ConfigFields(&cfg) { + if f.Path == key { + f.Value.SetZero() + + blanked = true + } + } + + require.True(t, blanked, "no leaf %s", key) + + var got []string + + for _, r := range reasons(types.ConfigErrors(Validate(&cfg))) { + if strings.HasPrefix(r, key+" is required") { + got = append(got, r) + } + } + + assert.Len(t, got, 1, "reasons naming %s as required: %v", key, got) + }) + } +} + // sharedKeys enables the embedded DERP server with these noise and DERP key // paths, relative ones resolved against /etc/headscale. func sharedKeys(noise, derp string) func(*types.Config) { diff --git a/hscontrol/config/load_test.go b/hscontrol/config/load_test.go index 2b706a145..a5d346591 100644 --- a/hscontrol/config/load_test.go +++ b/hscontrol/config/load_test.go @@ -1076,6 +1076,21 @@ func TestNullTakesDefault(t *testing.T) { file: serverURL + "noise:\n private_key_path:\n", warns: []string{`noise.private_key_path has no value in $FILE, so it takes its default /var/lib/headscale/noise_private.key`}, }, + { + name: "required listen address", + file: serverURL + "listen_addr:\n", + warns: []string{`listen_addr has no value in $FILE, so it takes its default 0.0.0.0:8080`}, + }, + { + name: "required sqlite path", + file: serverURL + "database:\n sqlite:\n path:\n", + warns: []string{`database.sqlite.path has no value in $FILE, so it takes its default /var/lib/headscale/db.sqlite`}, + }, + { + name: "sqlite path unused by postgres", + file: serverURL + "database:\n type: postgres\n sqlite:\n path:\n", + warns: []string{`database.sqlite.path has no value in $FILE, so it takes its default /var/lib/headscale/db.sqlite`}, + }, { name: "json null", file: `{"server_url": "https://headscale.example.com", "dns": {"magic_dns": false, "base_domain": null}}`, @@ -1669,7 +1684,7 @@ noise: assert.Contains( t, err.Error(), - "Fatal config error: server_url is missing a scheme", + "Fatal config error: server_url is required", ) // Check configuration validation errors (2) @@ -3990,25 +4005,9 @@ dns: override_local_dns: false ` - tests := []struct { - name string - file string - want []string // reasons, in order - }{ - {name: "valid", file: valid}, - { - // What the NixOS module writes: an explicit empty default. - name: "empty extra records next to a path", - file: valid + " extra_records: []\n extra_records_path: /var/lib/headscale/records.json\n", - }, - { - name: "extra records next to a path", - file: valid + " extra_records: [{name: a.example.com, type: A, value: 100.64.0.1}]\n extra_records_path: /var/lib/headscale/records.json\n", - want: []string{"dns.extra_records and dns.extra_records_path are mutually exclusive"}, - }, - { - name: "every rule, in order", - file: `server_url: headscale.example.com + // Breaks every rule once; a rule whose empty value has its own reason + // is broken by a set value here. + const everyRule = `server_url: headscale.example.com listen_addr: 0.0.0.0:8080 metrics_listen_addr: 0.0.0.0:8080 trusted_proxies: [0.0.0.0/0] @@ -4054,7 +4053,27 @@ oidc: client_secret: secret pkce: method: "" -`, +` + + tests := []struct { + name string + file string + want []string // reasons, in order + }{ + {name: "valid", file: valid}, + { + // What the NixOS module writes: an explicit empty default. + name: "empty extra records next to a path", + file: valid + " extra_records: []\n extra_records_path: /var/lib/headscale/records.json\n", + }, + { + name: "extra records next to a path", + file: valid + " extra_records: [{name: a.example.com, type: A, value: 100.64.0.1}]\n extra_records_path: /var/lib/headscale/records.json\n", + want: []string{"dns.extra_records and dns.extra_records_path are mutually exclusive"}, + }, + { + name: "every rule, in order", + file: everyRule, want: []string{ "OIDC configuration is invalid", "dns.extra_records and dns.extra_records_path are mutually exclusive", @@ -4077,6 +4096,36 @@ oidc: "dns.challenge.provider is invalid", }, }, + { + // Emptied, these keys give their required reason in place of the + // rule their set value broke. + name: "every rule, in order, required values empty", + file: strings.NewReplacer( + "server_url: headscale.example.com\nlisten_addr: 0.0.0.0:8080\n", "server_url: \"\"\nlisten_addr: \"\"\n", + "database:\n type: \"\"\n", "database:\n type: sqlite\n sqlite:\n path: \"\"\n", + ).Replace(everyRule), + want: []string{ + "OIDC configuration is invalid", + "dns.extra_records and dns.extra_records_path are mutually exclusive", + "tls.acme.hostname and tls.cert_path/tls.key_path are mutually exclusive", + "noise.private_key_path is required", + "listen_addr is required", + "tls.acme.challenge_type has an unsupported value", + "server_url is required", + "node.ephemeral.inactivity_timeout is below the minimum", + "node.routes.ha.probe_interval is below the minimum", + "node.routes.ha.probe_timeout must be less than node.routes.ha.probe_interval", + "tuning.node_store_batch_size must be positive", + "derp.server.stun_listen_addr is required when the embedded DERP server is enabled", + "database.sqlite.path is required when database.type is sqlite", + "policy.mode has an unsupported value", + "dns.base_domain is required when dns.magic_dns is true", + "trusted_proxies contains an invalid CIDR", + "no IP prefix configured for the tailnet", + "prefixes.allocation has an unsupported value", + "dns.challenge.provider is invalid", + }, + }, } for _, tt := range tests { diff --git a/hscontrol/config/validate.go b/hscontrol/config/validate.go index adf77a8ce..13cad066b 100644 --- a/hscontrol/config/validate.go +++ b/hscontrol/config/validate.go @@ -85,6 +85,13 @@ func Validate(c *types.Config) error { }) } + if c.Addr == "" { + v.Add(&types.ConfigError{ + Reason: "listen_addr is required", + Hint: `set listen_addr, e.g. "0.0.0.0:8080", or remove it for that default; ":0" picks a random port`, + }) + } + validateListenerCollisions(c, v) // Unset only: validateValues reports an unknown value, here and in the @@ -101,7 +108,13 @@ func Validate(c *types.Config) error { // Shown without userinfo, which may be a credential. serverURL := types.HTTPURL(c.ServerURL).Redacted() - if !strings.HasPrefix(c.ServerURL, "http://") && !strings.HasPrefix(c.ServerURL, "https://") { + switch { + case c.ServerURL == "": + v.Add(&types.ConfigError{ + Reason: "server_url is required", + Hint: "set server_url to the URL clients connect to, e.g. https://headscale.example.com", + }) + case !strings.HasPrefix(c.ServerURL, "http://") && !strings.HasPrefix(c.ServerURL, "https://"): // Without an @ it holds no userinfo; shown, the common mistake // (headscale.example.com) is plain to see. shown := c.ServerURL @@ -387,20 +400,33 @@ func keyFile(p string) string { return abs } -// validateDatabase records a ConfigError when database.type is unset. +// validateDatabase records a ConfigError when database.type is unset, or +// is sqlite without a path to open. func validateDatabase(c *types.Config, v *configValidator) { - t := c.Database.Type - if t != "" { - return - } + const see = "https://headscale.net/stable/ref/database/" - v.Add(&types.ConfigError{ - Reason: "database.type has an unsupported value", - Current: []types.KV{{Key: "database.type", Value: string(t)}}, - Allowed: t.Allowed(), - Hint: "pick one of the allowed values; sqlite is the default for single-host deployments", - See: "https://headscale.net/stable/ref/database/", - }) + t := c.Database.Type + + switch { + case t == "": + v.Add(&types.ConfigError{ + Reason: "database.type has an unsupported value", + Current: []types.KV{{Key: "database.type", Value: string(t)}}, + Allowed: t.Allowed(), + Hint: "pick one of the allowed values; sqlite is the default for single-host deployments", + See: see, + }) + case c.Database.IsSQLite() && c.Database.Sqlite.Path == "": + v.Add(&types.ConfigError{ + Reason: "database.sqlite.path is required when database.type is sqlite", + Current: []types.KV{ + {Key: "database.type", Value: string(t)}, + {Key: "database.sqlite.path", Value: ""}, + }, + Hint: `set database.sqlite.path, e.g. "/var/lib/headscale/db.sqlite"`, + See: see, + }) + } } // validateMagicDNS records a ConfigError when MagicDNS is enabled without a