cli: add check config and check all

check config validates only the config; check all adds one
ok/FAIL/skip line per named file.

Fixes #3443
This commit is contained in:
Kristoffer Dalby authored and GitHub committed 2026-11-11 12:06:30 +01:00
1 parent dbd0edfe5b
commit c2e7f2dc0b
7 files changed
+459 -35

No files matched your search

+156
View File
@@ -1,19 +1,38 @@
package cli
import (
"errors"
"fmt"
"io"
"os"
"strings"
"github.com/juanfont/headscale/hscontrol/config"
policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/spf13/cobra"
"github.com/spf13/viper"
)
var errCheckFailed = errors.New("check failed")
func init() {
rootCmd.AddCommand(checkCmd)
checkPolicyCmd.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
mustMarkRequired(checkPolicyCmd, "file")
checkCmd.AddCommand(checkPolicyCmd)
for _, c := range []*cobra.Command{checkConfigCmd, checkAllCmd} {
c.Flags().StringP("file", "f", "", "Path to the config file (default: found as serve finds it: -c, HEADSCALE_CONFIG, /etc/headscale, ~/.headscale, .)")
checkCmd.AddCommand(c)
}
for _, c := range []*cobra.Command{checkDERPMapCmd, checkExtraRecordsCmd} {
c.Flags().StringP("file", "f", "", "Path to the file")
mustMarkRequired(c, "file")
checkCmd.AddCommand(c)
}
}
var checkCmd = &cobra.Command{
@@ -48,3 +67,140 @@ var checkPolicyCmd = &cobra.Command{
return nil
},
}
var checkConfigCmd = &cobra.Command{
Use: "config",
Short: "Check the configuration for errors",
Long: `
Config validates the configuration: its syntax, keys and values. It does
not check the files the configuration names; "headscale check all" does.
Without --file it finds the configuration as "headscale serve" does. Secret
files named by oidc.client_secret_path and the DNS provider *_path settings
are read while the configuration loads.`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
_, src, err := loadCheckedConfig(cmd)
if err != nil {
return err
}
fmt.Fprintf(cmd.OutOrStdout(), "Configuration %s is valid\n", src)
return nil
},
}
var checkAllCmd = &cobra.Command{
Use: "all",
Short: "Check the configuration and every file it names",
Long: `
All checks the configuration, then each file it names, and lists every file
with ok, FAIL (the error below it) or skip. Skip is a key file that startup
creates when it is missing. It exits non-zero when any line is FAIL.
A derp.paths file that fails to parse is FAIL here, although startup only
skips it with a warning.`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
out := cmd.OutOrStdout()
cfg, src, err := loadCheckedConfig(cmd)
if err != nil {
printCheckLine(out, "FAIL", "config", src, len("config"), err)
return fmt.Errorf("%w: config, files not checked", errCheckFailed)
}
files := config.Files(cfg)
width := len("config")
for _, f := range files {
width = max(width, len(f.Key))
}
printCheckLine(out, "ok", "config", src, width, nil)
failed := 0
for _, f := range files {
err := f.Check()
switch {
case err == nil:
printCheckLine(out, "ok", f.Key, f.Path, width, nil)
case f.CreatedAtStartup && errors.Is(err, os.ErrNotExist):
printCheckLine(out, "skip", f.Key, f.Path+" (missing; startup creates it)", width, nil)
default:
failed++
printCheckLine(out, "FAIL", f.Key, f.Path, width, err)
}
}
if failed > 0 {
return fmt.Errorf("%w: %d of %d files", errCheckFailed, failed, len(files))
}
return nil
},
}
var (
checkDERPMapCmd = fileCheckCmd("derp-map",
"Check a DERP map file (derp.paths) for errors", "DERP map is valid", config.CheckDERPMapFile)
checkExtraRecordsCmd = fileCheckCmd("extra-records",
"Check an extra records file (dns.extra_records_path) for errors", "Extra records are valid", config.CheckExtraRecordsFile)
)
// fileCheckCmd checks one file of one kind; it needs no config.
func fileCheckCmd(use, short, valid string, check func(string) error) *cobra.Command {
return &cobra.Command{
Use: use,
Short: short,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
path, _ := cmd.Flags().GetString("file")
err := check(path)
if err != nil {
return err
}
fmt.Fprintln(cmd.OutOrStdout(), valid)
return nil
},
}
}
// loadCheckedConfig loads the server config from --file, or finds it as
// serve does, and names where it came from.
func loadCheckedConfig(cmd *cobra.Command) (*types.Config, string, error) {
path, _ := cmd.Flags().GetString("file")
err := loadConfig(path)
src := viper.ConfigFileUsed()
if src == "" {
src = "(defaults and environment)"
}
if err != nil {
return nil, src, err
}
cfg, err := types.LoadServerConfig()
return cfg, src, err
}
// printCheckLine prints one result; an error goes indented below it.
func printCheckLine(w io.Writer, status, key, path string, width int, err error) {
fmt.Fprintf(w, "%-4s %-*s %s\n", status, width, key, path)
if err != nil {
for l := range strings.SplitSeq(err.Error(), "\n") {
fmt.Fprintf(w, " %s\n", l)
}
}
}
+179
View File
@@ -2,12 +2,15 @@ package cli
import (
"bytes"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
"github.com/spf13/cobra"
"github.com/spf13/viper"
"github.com/stretchr/testify/require"
)
@@ -19,6 +22,8 @@ func TestSkipsInitConfig(t *testing.T) {
}{
{"check policy", []string{"check", "policy", "-f", "p"}, true},
{"check policy with config flag", []string{"-c", "x.yaml", "check", "policy"}, true},
{"check config with config flag", []string{"-c", "x.yaml", "check", "config"}, true},
{"check all with file", []string{"check", "all", "-f", "x.yaml"}, true},
{"check", []string{"check"}, true},
{"help check policy", []string{"help", "check", "policy"}, true},
{"policy get", []string{"policy", "get"}, false},
@@ -108,3 +113,177 @@ func TestCheckPolicy(t *testing.T) {
require.NoError(t, checkPolicyCmd.RunE(cmd, nil))
})
}
// writeServerConfig writes a valid server config with relative key and
// database paths, plus extra, to dir/config.yaml.
func writeServerConfig(t *testing.T, dir, extra string) string {
t.Helper()
p := filepath.Join(dir, "config.yaml")
require.NoError(t, os.WriteFile(p, []byte(`server_url: https://headscale.example.com
noise:
private_key_path: noise.key
prefixes:
v4: 100.64.0.0/10
database:
type: sqlite3
sqlite:
path: headscale.db
dns:
magic_dns: false
override_local_dns: false
`+extra), 0o600))
return p
}
func writeFile(t *testing.T, dir, name, content string) string {
t.Helper()
p := filepath.Join(dir, name)
require.NoError(t, os.WriteFile(p, []byte(content), 0o600))
return p
}
func runCheck(t *testing.T, c *cobra.Command, file string) (string, error) {
t.Helper()
viper.Reset()
t.Cleanup(viper.Reset)
cmd := &cobra.Command{}
cmd.Flags().String("file", file, "")
var buf bytes.Buffer
cmd.SetOut(&buf)
err := c.RunE(cmd, nil)
return buf.String(), err
}
func dirNames(t *testing.T, dir string) []string {
t.Helper()
entries, err := os.ReadDir(dir)
require.NoError(t, err)
names := make([]string, 0, len(entries))
for _, e := range entries {
names = append(names, e.Name())
}
return names
}
const badGroupPolicy = `{"acls":[{"action":"accept","src":["group:missing"],"dst":["*:*"]}]}`
func TestCheckConfig(t *testing.T) {
t.Run("valid creates nothing", func(t *testing.T) {
dir := t.TempDir()
cfg := writeServerConfig(t, dir, "")
out, err := runCheck(t, checkConfigCmd, cfg)
require.NoError(t, err)
require.Equal(t, "Configuration "+cfg+" is valid\n", out)
require.Equal(t, []string{"config.yaml"}, dirNames(t, dir))
})
t.Run("named files are not checked", func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "policy.hujson", badGroupPolicy)
_, err := runCheck(t, checkConfigCmd, writeServerConfig(t, dir, "policy:\n path: policy.hujson\n"))
require.NoError(t, err)
})
t.Run("bad server_url", func(t *testing.T) {
dir := t.TempDir()
cfg := writeFile(t, dir, "config.yaml", "server_url: ftp://x\n")
_, err := runCheck(t, checkConfigCmd, cfg)
require.ErrorContains(t, err, "server_url")
})
t.Run("derp server without key path", func(t *testing.T) {
dir := t.TempDir()
_, err := runCheck(t, checkConfigCmd, writeServerConfig(t, dir,
"derp:\n server:\n enabled: true\n stun_listen_addr: \"0.0.0.0:3478\"\n"))
require.ErrorContains(t, err, "derp.server.private_key_path is required")
})
t.Run("arguments are rejected", func(t *testing.T) {
require.Error(t, checkConfigCmd.Args(checkConfigCmd, []string{"other.yaml"}))
})
}
func TestCheckAll(t *testing.T) {
t.Run("one line per file", func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "policy.hujson", badGroupPolicy)
derpMap := writeFile(t, dir, "derp.yaml", `regions:
900:
regionid: 900
regioncode: test
nodes:
- name: 900a
regionid: 900
hostname: derp.example.com
`)
cfg := writeServerConfig(t, dir, fmt.Sprintf("policy:\n path: policy.hujson\nderp:\n paths: [%q]\n", derpMap))
out, err := runCheck(t, checkAllCmd, cfg)
require.ErrorIs(t, err, errCheckFailed)
require.ErrorContains(t, err, "1 of 3 files")
// Keys are padded to the longest, noise.private_key_path.
line := func(status, key, path string) string {
return fmt.Sprintf("%-4s %-22s %s", status, key, path)
}
lines := strings.Split(out, "\n")
require.Equal(t, line("ok", "config", cfg), lines[0])
require.Equal(t, line("FAIL", "policy.path", filepath.Join(dir, "policy.hujson")), lines[1])
require.True(t, strings.HasPrefix(lines[2], " "), "error indented under its file: %q", lines[2])
require.Contains(t, lines[2], "group:missing")
require.Contains(t, lines, line("ok", "derp.paths", derpMap))
require.Contains(t, lines, line("skip", "noise.private_key_path", filepath.Join(dir, "noise.key")+" (missing; startup creates it)"))
require.Equal(t, []string{"config.yaml", "derp.yaml", "policy.hujson"}, dirNames(t, dir))
})
t.Run("all files valid", func(t *testing.T) {
dir := t.TempDir()
out, err := runCheck(t, checkAllCmd, writeServerConfig(t, dir, ""))
require.NoError(t, err)
require.NotContains(t, out, "FAIL")
})
t.Run("config fails and files are not checked", func(t *testing.T) {
dir := t.TempDir()
cfg := writeFile(t, dir, "config.yaml", "server_url: ftp://x\n")
out, err := runCheck(t, checkAllCmd, cfg)
require.ErrorIs(t, err, errCheckFailed)
require.True(t, strings.HasPrefix(out, "FAIL config "+cfg+"\n"), out)
require.Contains(t, out, "server_url")
})
}
func TestCheckFileCommands(t *testing.T) {
dir := t.TempDir()
out, err := runCheck(t, checkExtraRecordsCmd,
writeFile(t, dir, "r.json", `[{"name":"a.example.com","type":"A","value":"100.64.0.1"}]`))
require.NoError(t, err)
require.Equal(t, "Extra records are valid\n", out)
_, err = runCheck(t, checkExtraRecordsCmd, writeFile(t, dir, "bad.json", "{"))
require.ErrorContains(t, err, "bad.json")
_, err = runCheck(t, checkDERPMapCmd, writeFile(t, dir, "d.yaml", "{}"))
require.ErrorContains(t, err, "d.yaml")
}
-25
View File
@@ -1,25 +0,0 @@
package cli
import (
"fmt"
"github.com/spf13/cobra"
)
func init() {
rootCmd.AddCommand(configTestCmd)
}
var configTestCmd = &cobra.Command{
Use: "configtest",
Short: "Test the configuration.",
Long: "Run a test of the configuration and exit.",
RunE: func(cmd *cobra.Command, args []string) error {
_, err := newHeadscaleServerWithConfig()
if err != nil {
return fmt.Errorf("configuration error: %w", err)
}
return nil
},
}
+11 -8
View File
@@ -53,15 +53,18 @@ func skipsInitConfig(args []string) bool {
return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd)
}
func loadConfig() error {
if cfgFile == "" {
cfgFile = os.Getenv("HEADSCALE_CONFIG")
}
// loadConfig loads path, else the file -c names, else $HEADSCALE_CONFIG,
// else the first config.* in /etc/headscale, ~/.headscale or ".". Without a
// file it loads defaults and environment only.
func loadConfig(path string) error {
for _, p := range []string{path, cfgFile, os.Getenv("HEADSCALE_CONFIG")} {
if p == "" {
continue
}
if cfgFile != "" {
err := types.LoadConfig(cfgFile, true)
err := types.LoadConfig(p, true)
if err != nil {
return fmt.Errorf("loading config file %s: %w", cfgFile, err)
return fmt.Errorf("loading config file %s: %w", p, err)
}
return nil
@@ -83,7 +86,7 @@ func initConfig() {
return
}
err := loadConfig()
err := loadConfig("")
if err != nil {
log.Fatal().Caller().Err(err).Msg("error loading config")
}
+37
View File
@@ -433,3 +433,40 @@ func TestInitConfigSkippedLogLevel(t *testing.T) {
initConfig()
require.Equal(t, zerolog.InfoLevel, zerolog.GlobalLevel(), "log.level's default, as with a config")
}
func TestLoadConfig(t *testing.T) {
dir := t.TempDir()
conf := func(name string) string {
p := filepath.Join(dir, name)
require.NoError(t, os.WriteFile(p, []byte("server_url: https://"+name+"\n"), 0o600))
return p
}
flag, global, env := conf("flag.yaml"), conf("global.yaml"), conf("env.yaml")
tests := []struct {
name string
path, cfgFile, env string
want string
}{
{"path wins", flag, global, env, flag},
{"then -c", "", global, env, global},
{"then HEADSCALE_CONFIG", "", "", env, env},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
viper.Reset()
t.Cleanup(viper.Reset)
t.Setenv("HEADSCALE_CONFIG", tt.env)
old := cfgFile
cfgFile = tt.cfgFile
t.Cleanup(func() { cfgFile = old })
require.NoError(t, loadConfig(tt.path))
require.Equal(t, tt.want, viper.ConfigFileUsed())
})
}
}