types: reject empty values serve cannot use

unix_socket, half a TLS keypair, ACME without http_listen or cache_dir.
Document empty postgres settings. Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 16:42:44 +01:00
1 parent a2d8eb42e7
commit 68424bbb4a
4 files changed
+154 -2

No files matched your search

+74 -1
View File
@@ -77,10 +77,20 @@ func TestValidateHintsNameDefaults(t *testing.T) {
cfg.Tuning.NodeStoreBatchSize = 0
cfg.Tuning.NodeStoreBatchTimeout = 0
cfg.Addr = ""
cfg.UnixSocket = ""
cfg.TLS.ACME.Hostname = "headscale.example.com"
cfg.TLS.ACME.HTTPListen = ""
cfg.TLS.ACME.CacheDir = ""
err := Validate(&cfg)
require.ErrorContains(t, err, fmt.Sprintf("(default: %s)", d.Tuning.BatchChangeDelay))
require.ErrorContains(t, err, fmt.Sprintf("(default: %d)", d.Tuning.NodeStoreBatchSize))
require.ErrorContains(t, err, fmt.Sprintf("(default: %s)", d.Tuning.NodeStoreBatchTimeout))
for _, def := range []string{string(d.Addr), d.UnixSocket, string(d.TLS.ACME.HTTPListen), d.TLS.ACME.CacheDir} {
require.ErrorContains(t, err, fmt.Sprintf("%q, or remove it for that default", def))
}
}
// TestValidateGoData: a Config built in Go, which no loader parsed, is
@@ -159,6 +169,69 @@ func TestValidateGoData(t *testing.T) {
c.Database.Sqlite.Path = ""
},
},
{
name: "unix socket empty",
set: func(c *types.Config) { c.UnixSocket = "" },
wantErr: "unix_socket is required",
},
{
name: "certificate without key",
set: func(c *types.Config) { c.TLS.CertPath = "/etc/headscale/cert.pem" },
wantErr: "tls.key_path is required when tls.cert_path is set",
},
{
name: "key without certificate",
set: func(c *types.Config) { c.TLS.KeyPath = "/etc/headscale/key.pem" },
wantErr: "tls.cert_path is required when tls.key_path is set",
},
{
name: "keypair",
set: func(c *types.Config) {
c.TLS.CertPath = "/etc/headscale/cert.pem"
c.TLS.KeyPath = "/etc/headscale/key.pem"
},
},
{
name: "acme http-01 without listener",
set: func(c *types.Config) {
c.TLS.ACME.Hostname = "headscale.example.com"
c.TLS.ACME.HTTPListen = ""
},
wantErr: "tls.acme.http_listen is required when tls.acme.challenge_type is HTTP-01",
},
{
name: "acme tls-alpn-01 without http listener",
set: func(c *types.Config) {
c.TLS.ACME.Hostname = "headscale.example.com"
c.TLS.ACME.ChallengeType = types.TLSALPN01ChallengeType
c.TLS.ACME.HTTPListen = ""
},
},
{
name: "acme without cache dir",
set: func(c *types.Config) {
c.TLS.ACME.Hostname = "headscale.example.com"
c.TLS.ACME.CacheDir = ""
},
wantErr: "tls.acme.cache_dir is required when tls.acme.hostname is set",
},
{
name: "acme off without its settings",
set: func(c *types.Config) {
c.TLS.ACME.HTTPListen = ""
c.TLS.ACME.CacheDir = ""
},
},
{
// The keypair and ACME rule reports it; asking for the other half
// would point the wrong way.
name: "acme next to a certificate",
set: func(c *types.Config) {
c.TLS.ACME.Hostname = "headscale.example.com"
c.TLS.CertPath = "/etc/headscale/cert.pem"
},
wantErr: "tls.acme.hostname and tls.cert_path/tls.key_path are mutually exclusive",
},
{
name: "url",
set: func(c *types.Config) {
@@ -383,7 +456,7 @@ func TestValidateGoData(t *testing.T) {
// 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"} {
for _, key := range []string{"server_url", "listen_addr", "unix_socket", "noise.private_key_path", "database.sqlite.path"} {
t.Run(key, func(t *testing.T) {
cfg := Default()
if key != "server_url" {
+11
View File
@@ -1114,6 +1114,11 @@ func TestNullTakesDefault(t *testing.T) {
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 unix socket",
file: serverURL + "unix_socket:\n",
warns: []string{`unix_socket has no value in $FILE, so it takes its default /var/run/headscale/headscale.sock`},
},
{
name: "required sqlite path",
file: serverURL + "database:\n sqlite:\n path:\n",
@@ -4045,6 +4050,7 @@ dns:
const everyRule = `server_url: headscale.example.com
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 0.0.0.0:8080
unix_socket: ""
trusted_proxies: [0.0.0.0/0]
noise:
private_key_path: ""
@@ -4082,6 +4088,7 @@ tls:
acme:
hostname: example.com
challenge_type: ""
cache_dir: ""
oidc:
issuer: https://idp.example.com
client_id: headscale
@@ -4113,7 +4120,9 @@ oidc:
"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",
"tls.acme.cache_dir is required when tls.acme.hostname is set",
"noise.private_key_path is required",
"unix_socket is required",
"listen_addr and metrics_listen_addr would bind the same TCP socket",
"tls.acme.challenge_type has an unsupported value",
"server_url is missing a scheme",
@@ -4143,8 +4152,10 @@ oidc:
"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",
"tls.acme.cache_dir is required when tls.acme.hostname is set",
"noise.private_key_path is required",
"listen_addr is required",
"unix_socket is required",
"tls.acme.challenge_type has an unsupported value",
"server_url is required",
"node.ephemeral.inactivity_timeout is below the minimum",
+64
View File
@@ -77,6 +77,8 @@ func Validate(c *types.Config) error {
})
}
validateTLS(c, v)
if c.Noise.PrivateKeyPath == "" {
v.Add(&types.ConfigError{
Reason: "noise.private_key_path is required",
@@ -92,6 +94,15 @@ func Validate(c *types.Config) error {
})
}
// Serve would bind an unnamed socket and fail to chmod it; the CLI
// cannot dial one.
if c.UnixSocket == "" {
v.Add(&types.ConfigError{
Reason: "unix_socket is required",
Hint: `set unix_socket, e.g. "/var/run/headscale/headscale.sock", or remove it for that default`,
})
}
validateListenerCollisions(c, v)
// Unset only: validateValues reports an unknown value, here and in the
@@ -389,6 +400,59 @@ func validateDERP(c *types.Config, v *configValidator) {
}
}
// validateTLS records ConfigErrors for TLS settings startup cannot use:
// half a keypair, or ACME without its HTTP-01 listener or a cache
// directory.
func validateTLS(c *types.Config, v *configValidator) {
const see = "https://headscale.net/stable/ref/tls/"
cert, key, acme := c.TLS.CertPath, c.TLS.KeyPath, c.TLS.ACME
// With ACME, Validate reports any keypair path as the wrong strategy.
if acme.Hostname == "" {
switch {
case cert != "" && key == "":
v.Add(&types.ConfigError{
Reason: "tls.key_path is required when tls.cert_path is set",
Current: []types.KV{{Key: "tls.cert_path", Value: cert}, {Key: "tls.key_path", Value: ""}},
Hint: "set tls.key_path to the certificate's PEM private key, or remove tls.cert_path to serve plain HTTP",
See: see,
})
case key != "" && cert == "":
// Without a certificate the key is ignored and headscale serves
// plain HTTP.
v.Add(&types.ConfigError{
Reason: "tls.cert_path is required when tls.key_path is set",
Current: []types.KV{{Key: "tls.cert_path", Value: ""}, {Key: "tls.key_path", Value: key}},
Hint: "set tls.cert_path to the PEM certificate, or remove tls.key_path to serve plain HTTP",
See: see,
})
}
return
}
if acme.ChallengeType == types.HTTP01ChallengeType && acme.HTTPListen == "" {
v.Add(&types.ConfigError{
Reason: "tls.acme.http_listen is required when tls.acme.challenge_type is HTTP-01",
Current: []types.KV{{Key: "tls.acme.challenge_type", Value: string(acme.ChallengeType)}, {Key: "tls.acme.http_listen", Value: ""}},
Hint: `set tls.acme.http_listen, e.g. ":http", or remove it for that default`,
See: see,
})
}
// Empty, certmagic keeps the account and certificate keys in the
// working directory.
if acme.CacheDir == "" {
v.Add(&types.ConfigError{
Reason: "tls.acme.cache_dir is required when tls.acme.hostname is set",
Current: []types.KV{{Key: "tls.acme.hostname", Value: acme.Hostname}, {Key: "tls.acme.cache_dir", Value: ""}},
Hint: `set tls.acme.cache_dir, e.g. "/var/lib/headscale/cache", or remove it for that default`,
See: see,
})
}
}
// keyFile is p as startup opens it, a relative path from the working
// directory (an embedder's Config has no ConfigDir).
func keyFile(p string) string {
+5 -1
View File
@@ -626,7 +626,11 @@ type DatabaseConfig struct {
Sqlite SqliteConfig `koanf:"sqlite"`
// Postgres is PostgreSQL, read only when `database.type` is
// `postgres`.
// `postgres`. An empty `host`, `name`, `user`, `pass` or `ssl` leaves
// that setting to the driver, which reads the `PG*` environment
// variables and falls back to the defaults of libpq, PostgreSQL's
// client library: a local socket, the OS user, and TLS if the server
// offers it.
Postgres PostgresConfig `koanf:"postgres"`
}