config: require listen_addr and the sqlite path

Empty values serve cannot use; empty server_url reads "is required".

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 15:02:16 +01:00
1 parent 2db863d5e6
commit f5f86e69d0
4 files changed
+206 -35

No files matched your search

+22
View File
@@ -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()
+75 -1
View File
@@ -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) {
+70 -21
View File
@@ -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 {
+39 -13
View File
@@ -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