config, cli, packaging, nix: stop restarting headscale on a configuration error

serve exits 78 (EX_CONFIG) when the configuration file it loaded is
wrong: format, syntax, keys or values. No file, an unreadable one, the
database and ports still exit 1, so systemd keeps retrying what can
heal. The deb unit and the NixOS module set RestartPreventExitStatus=78.
A parse error gives a position and fixed words, never the file's text.

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 12:19:29 +01:00
1 parent 73ef19c0ab
commit eff078ffa2
10 files changed
+205 -7

No files matched your search

+11 -2
View File
@@ -112,7 +112,10 @@ func initConfig() {
if err != nil {
// No log.format applies: main's console logger, on stderr.
logWarnings(l.Warnings)
log.Fatal().Caller().Err(err).Msg("error loading config")
log.WithLevel(zerolog.FatalLevel).Caller().Err(err).Msg("error loading config")
cmd, _, _ := rootCmd.Find(os.Args[1:])
os.Exit(exitCode(cmd, l.File, err))
}
loaded = l
@@ -201,6 +204,12 @@ func Execute() {
if err != nil {
outputFormat, _ := cmd.Flags().GetString("output")
printError(err, outputFormat)
os.Exit(1)
var file string
if loaded != nil {
file = loaded.File
}
os.Exit(exitCode(cmd, file, err))
}
}
+18
View File
@@ -42,6 +42,24 @@ var serveCmd = &cobra.Command{
},
}
// exitConfig is EX_CONFIG from sysexits.h. serve exits with it when its
// configuration is the cause, which a restart with the same inputs cannot
// fix, so the systemd units set RestartPreventExitStatus to it.
const exitConfig = 78
// exitCode is how cmd exits on err, file being the configuration file it
// loaded: exitConfig when serve stops on what that configuration says; 1
// otherwise. Without a file, the one expected may be on a mount not yet up,
// and a database, a port or a file the configuration names may yet become
// available, so systemd keeps retrying those.
func exitCode(cmd *cobra.Command, file string, err error) int {
if cmd == serveCmd && file != "" && errors.Is(err, types.ErrConfig) {
return exitConfig
}
return 1
}
// logNoConfigFile says when the server runs without a file. The loader does
// not warn: client commands need no file unless they use an API key.
func logNoConfigFile(l *config.Loaded) {
+70
View File
@@ -6,6 +6,9 @@ import (
"errors"
"fmt"
"net"
"os"
"os/exec"
"path/filepath"
"strings"
"syscall"
"testing"
@@ -172,3 +175,70 @@ func TestLogNoConfigFile(t *testing.T) {
})
}
}
// TestServeExitCode: serve exits with exitConfig only when the configuration
// file it loaded is the cause, so systemd stops restarting it; a failure that
// can heal, no file at all, and every other command exit with 1.
func TestServeExitCode(t *testing.T) {
dir := t.TempDir()
notADir := writeFile(t, dir, "file", "")
const valid = "server_url: https://headscale.example.com\ndisable_check_updates: true\n"
tests := []struct {
name string
file string // the config file's name, config.yaml when ""
config string // written to file; "" passes a path that does not exist
search bool // no -c: the file is searched for, in ~/.headscale
args []string
want int
stderr string
}{
{name: "rejected value", config: "server_url: ftp://headscale.example.com\ndisable_check_updates: true\n", args: []string{"serve"}, want: exitConfig, stderr: "server_url"},
{name: "unknown key", config: valid + "bogus_key: 1\n", args: []string{"serve"}, want: exitConfig, stderr: "unknown configuration key bogus_key"},
{name: "syntax error", config: valid + "derp: [\n", args: []string{"serve"}, want: exitConfig, stderr: "yaml: line 3"},
{name: "missing file", args: []string{"serve"}, want: 1, stderr: "error loading config"},
{name: "no file found", search: true, args: []string{"serve"}, want: 1, stderr: "server_url is required"},
{name: "old format found", file: "config.toml", config: "server_url = \"https://headscale.example.com\"\n", search: true, args: []string{"serve"}, want: exitConfig, stderr: "unsupported config file format"},
{name: "unwritable noise key", config: valid + "noise:\n private_key_path: " + notADir + "/noise.key\n", args: []string{"serve"}, want: 1, stderr: "Noise"},
{name: "other command", config: valid + "bogus_key: 1\n", args: []string{"users", "list"}, want: 1, stderr: "unknown configuration key bogus_key"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
home, dir, name := t.TempDir(), t.TempDir(), tt.file
if name == "" {
name = "config.yaml"
}
if tt.search {
dir = filepath.Join(home, ".headscale")
require.NoError(t, os.Mkdir(dir, 0o700))
}
path := filepath.Join(dir, "absent", name)
if tt.config != "" {
path = writeFile(t, dir, name, tt.config)
}
args := append([]string{"-c", path}, tt.args...)
if tt.search {
// The search always looks in /etc/headscale; a host config there
// would be found, or serve would start on it.
if found, _ := filepath.Glob("/etc/headscale/config.*"); len(found) > 0 {
t.Skipf("the search would find %v", found)
}
args = tt.args
}
env := []string{"HOME=" + home, "XDG_CONFIG_DIRS=" + t.TempDir(), "HEADSCALE_DISABLE_CHECK_UPDATES=true"}
_, stderr, err := runHeadscale(t, env, args...)
exitErr, ok := errors.AsType[*exec.ExitError](err)
require.True(t, ok, "want exit %d, got %v; stderr:\n%s", tt.want, err, stderr)
assert.Equal(t, tt.want, exitErr.ExitCode(), stderr)
assert.Contains(t, stderr, tt.stderr)
})
}
}