cli: add generate config, replacing dumpConfig

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 15:02:16 +01:00
1 parent f7f1d91d0f
commit 6602227d3e
8 files changed
+499 -88

No files matched your search

-2
View File
@@ -45,8 +45,6 @@ control_logs/
result
.direnv/
integration_test/etc/config.dump.yaml
# OpenAPI spec is served live from the code and emitted on demand, not committed
/openapi/v1/headscale.yaml
+6
View File
@@ -30,6 +30,12 @@ func TestSkipsInitConfig(t *testing.T) {
{"check all with file", []string{"check", "all", "-f", "x.yaml"}, true},
{"check", []string{"check"}, true},
{"help check policy", []string{"help", "check", "policy"}, true},
{"generate config", []string{"generate", "config"}, true},
{"generate config running", []string{"generate", "config", "--running"}, true},
{"generate config with config flag", []string{"-c", "x.yaml", "generate", "config"}, true},
{"gen config", []string{"gen", "config"}, true},
{"help generate config", []string{"help", "generate", "config"}, true},
{"generate private-key", []string{"generate", "private-key"}, false},
{"policy get", []string{"policy", "get"}, false},
{"help nodes", []string{"help", "nodes"}, false},
{"nodes list", []string{"nodes", "list"}, false},
-32
View File
@@ -1,32 +0,0 @@
package cli
import (
"fmt"
"os"
"github.com/juanfont/headscale/hscontrol/config"
"github.com/spf13/cobra"
)
func init() {
rootCmd.AddCommand(dumpConfigCmd)
}
var dumpConfigCmd = &cobra.Command{
Use: "dumpConfig",
Short: "dump current config to /etc/headscale/config.dump.yaml, integration test only",
Hidden: true,
RunE: func(cmd *cobra.Command, args []string) error {
out, err := config.Marshal(loaded.Config, ".yaml")
if err != nil {
return fmt.Errorf("dumping config: %w", err)
}
err = os.WriteFile("/etc/headscale/config.dump.yaml", out, 0o600)
if err != nil {
return fmt.Errorf("dumping config: %w", err)
}
return nil
},
}
+73
View File
@@ -1,8 +1,13 @@
package cli
import (
"context"
"fmt"
"net/http"
clientv1 "github.com/juanfont/headscale/gen/client/v1"
"github.com/juanfont/headscale/hscontrol/config"
"github.com/spf13/cobra"
"tailscale.com/types/key"
)
@@ -10,6 +15,10 @@ import (
func init() {
rootCmd.AddCommand(generateCmd)
generateCmd.AddCommand(generatePrivateKeyCmd)
generateConfigCmd.Flags().Bool("no-docs", false, "Leave out the documentation comments")
generateConfigCmd.Flags().Bool("running", false, "Print the running server's configuration, secrets redacted, instead of the defaults")
generateCmd.AddCommand(generateConfigCmd)
}
var generateCmd = &cobra.Command{
@@ -35,3 +44,67 @@ var generatePrivateKeyCmd = &cobra.Command{
string(machineKeyStr))
},
}
var generateConfigCmd = &cobra.Command{
Use: "config",
Short: "Print a configuration file with every key",
Long: `Print a YAML configuration with every key, its default and its
documentation as comments, e.g. for "> /etc/headscale/config.yaml". Set the
keys marked "Required" before starting headscale.
With --running, print instead the configuration of the running server,
without the client-only cli section: literal secrets, DNS provider settings
other than its name, and URL credentials are redacted, "file:" references
kept as written.`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
noDocs, _ := cmd.Flags().GetBool("no-docs")
running, _ := cmd.Flags().GetBool("running")
if running {
return printRunningConfig(cmd, !noDocs)
}
d := config.Default()
out, err := config.GenerateExample(&d, config.ExampleOptions{Docs: !noDocs})
if err != nil {
return fmt.Errorf("generating config: %w", err)
}
_, err = cmd.OutOrStdout().Write(out)
return err
},
}
// printRunningConfig writes the running server's configuration, as the
// server renders it, to stdout. generate config skips initConfig, so this
// loads the CLI's own settings to reach the server.
func printRunningConfig(cmd *cobra.Command, docs bool) error {
// Its log settings stay unapplied: a warning may explain which server
// answers, whatever log.level says.
l, err := loadConfig("")
logWarnings(l.Warnings)
if err != nil {
return err
}
loaded = l
return withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
resp, err := client.GetConfigWithResponse(ctx, &clientv1.GetConfigParams{Docs: &docs})
if err != nil {
return fmt.Errorf("asking the server for its configuration: %w", err)
}
if resp.StatusCode() != http.StatusOK {
return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
}
_, err = cmd.OutOrStdout().Write(resp.Body)
return err
})
}
+365
View File
@@ -0,0 +1,365 @@
package cli
import (
"encoding/json"
"fmt"
"maps"
"net"
"net/http"
"net/http/httptest"
"net/netip"
"os"
"path/filepath"
"reflect"
"regexp"
"strings"
"testing"
"github.com/google/go-cmp/cmp"
"github.com/google/go-cmp/cmp/cmpopts"
apiv1 "github.com/juanfont/headscale/hscontrol/api/v1"
"github.com/juanfont/headscale/hscontrol/config"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"gopkg.in/yaml.v3"
)
// serveConfig serves handler on a unix socket at sock, as the server's
// API would.
func serveConfig(t *testing.T, sock string, handler http.HandlerFunc) {
t.Helper()
var lc net.ListenConfig
ln, err := lc.Listen(t.Context(), "unix", sock)
require.NoError(t, err)
srv := httptest.NewUnstartedServer(handler)
srv.Listener.Close()
srv.Listener = ln
srv.Start()
t.Cleanup(srv.Close)
}
// TestGenerateConfigRunningRoundTrip: a server holding every key away from
// its default prints, through the real v1 API, generated client and CLI, a
// file that loads back to the same typed values, but for the cli section,
// which is left out, and credentials, which are redacted: literal secrets
// and DNS provider settings, and URL userinfo. Values compare as loaded,
// not rendered, so a renderer that drops or reorders cannot hide it.
func TestGenerateConfigRunningRoundTrip(t *testing.T) {
d := config.Default()
defaults := typedLeaves(&d)
redacted := types.Secret("literal").Redacted()
opts := cmp.Options{cmpopts.EquateComparable(netip.Prefix{})}
const userinfo = "marker-user:marker-pass@"
// Every leaf at its example, every bool at !default. Secrets and the
// provider's credential are file: references, URLs have no userinfo.
written := map[string]any{}
for _, f := range types.ConfigFields(&d) {
var v any
if f.Field.Type.Kind() == reflect.Bool {
v = !f.Value.Bool()
} else {
tag, ok := f.Field.Tag.Lookup("example")
require.True(t, ok, "%s: no example", f.Path)
require.NoError(t, json.Unmarshal([]byte(tag), &v), f.Path)
}
written[f.Path] = v
}
// literal is written with a credential in every place one can hide.
literal := maps.Clone(written)
markers := []string{"marker-user", "marker-pass"}
secretPaths, providerPaths, urlPaths := map[string]bool{}, map[string]bool{}, map[string]bool{}
for _, f := range types.ConfigFields(&d) {
switch v := written[f.Path]; {
case f.Field.Type == reflect.TypeFor[types.Secret]():
literal[f.Path] = "marker-secret-" + f.Path
markers = append(markers, "marker-secret-"+f.Path)
secretPaths[f.Path] = true
case f.Field.Type == reflect.TypeFor[map[string]any]():
settings := maps.Clone(v.(map[string]any))
settings["marker_token"] = "marker-provider-token"
settings["marker_zone"] = 987654321
literal[f.Path] = settings
markers = append(markers, "marker-provider-token", "987654321")
providerPaths[f.Path] = true
case strings.Contains(fmt.Sprint(v), "://"):
literal[f.Path] = withUserinfo(v, userinfo)
urlPaths[f.Path] = true
}
}
writtenCfg := loadLeaves(t, written)
want := typedLeaves(writtenCfg)
for path, v := range want {
assert.False(t, cmp.Equal(defaults[path], v, opts), "%s: example is the default", path)
}
// A dropped list element must show: the example lists two proxies.
require.Len(t, writtenCfg.TrustedProxies, 2)
dir, err := os.MkdirTemp("", "hs") // short: a socket path is limited
require.NoError(t, err)
t.Cleanup(func() { os.RemoveAll(dir) })
for _, tt := range []struct {
name string
cfg *types.Config
redact bool
}{
{name: "as written", cfg: writtenCfg},
{name: "literal credentials", cfg: loadLeaves(t, literal), redact: true},
} {
sock := filepath.Join(dir, strings.ReplaceAll(tt.name, " ", "-")+".sock")
mux, _ := apiv1.Handler(apiv1.Backend{Cfg: tt.cfg})
serveConfig(t, sock, apiv1.WithLocalTrust(mux).ServeHTTP)
cliConfig := writeFile(t, dir, filepath.Base(sock)+".yaml", "unix_socket: "+sock+"\n")
for _, docs := range []bool{true, false} {
t.Run(fmt.Sprintf("%s, docs %t", tt.name, docs), func(t *testing.T) {
args := []string{"-c", cliConfig, "generate", "config", "--running"}
if !docs {
args = append(args, "--no-docs")
}
stdout, stderr, err := runHeadscale(t, nil, args...)
require.NoError(t, err, stderr)
assert.Equal(t, docs, regexp.MustCompile(`(?m)^\s*#`).MatchString(stdout), "documentation comments")
var doc map[string]any
require.NoError(t, yaml.Unmarshal([]byte(stdout), &doc), stdout)
assert.NotContains(t, doc, "cli")
if tt.redact {
for _, m := range markers {
assert.NotContains(t, stdout, m)
}
}
got := typedLeaves(loadFile(t, writeFile(t, t.TempDir(), "running.yaml", stdout)))
for _, f := range types.ConfigFields(tt.cfg) {
expect := f.Value.Interface()
switch {
case strings.HasPrefix(f.Path, "cli."):
expect = defaults[f.Path] // left out, so loaded as the default
case tt.redact && secretPaths[f.Path]:
expect = types.Secret(redacted)
case tt.redact && providerPaths[f.Path]:
settings := maps.Clone(want[f.Path].(map[string]any))
settings["marker_token"], settings["marker_zone"] = redacted, redacted
expect = settings
case tt.redact && urlPaths[f.Path]:
expect = want[f.Path] // userinfo stripped
}
if diff := cmp.Diff(expect, got[f.Path], opts); diff != "" {
t.Errorf("%s (-want +got):\n%s", f.Path, diff)
}
}
})
}
}
}
// withUserinfo is v, a URL or a list of them, with userinfo added to each.
func withUserinfo(v any, userinfo string) any {
switch x := v.(type) {
case string:
return strings.Replace(x, "://", "://"+userinfo, 1)
case []any:
out := make([]any, len(x))
for i, e := range x {
out[i] = withUserinfo(e, userinfo)
}
return out
}
return v
}
// loadLeaves loads a file that sets each dotted path of leaves to its value.
func loadLeaves(t *testing.T, leaves map[string]any) *types.Config {
t.Helper()
nested := map[string]any{}
for path, v := range leaves {
m := nested
parts := strings.Split(path, ".")
for _, p := range parts[:len(parts)-1] {
if m[p] == nil {
m[p] = map[string]any{}
}
m = m[p].(map[string]any)
}
m[parts[len(parts)-1]] = v
}
b, err := json.Marshal(nested)
require.NoError(t, err)
return loadFile(t, writeFile(t, t.TempDir(), "config.json", string(b)))
}
// loadFile is path as config.Load reads it, which must be without warnings.
func loadFile(t *testing.T, path string) *types.Config {
t.Helper()
l, err := config.Load(path, true, nil)
require.NoError(t, err)
require.Empty(t, l.Warnings)
return l.Config
}
// typedLeaves is every leaf of cfg by dotted path, as cfg holds it.
func typedLeaves(cfg *types.Config) map[string]any {
leaves := map[string]any{}
for _, f := range types.ConfigFields(cfg) {
leaves[f.Path] = f.Value.Interface()
}
return leaves
}
// TestGenerateConfigCommand: generate config prints the example and only
// it, whatever config and variables are around; --running prints what the
// server answers, as it answers it, and nothing when it fails, with its own
// load warnings on stderr whatever its log settings.
func TestGenerateConfigCommand(t *testing.T) {
const (
running = "# Documented.\nserver_url: https://running.example.com\n"
runningNoDocs = "server_url: https://running.example.com\n"
)
home := t.TempDir()
require.NoError(t, os.Mkdir(filepath.Join(home, ".headscale"), 0o700))
writeFile(t, filepath.Join(home, ".headscale"), "config.yaml", "bogus_key: 1\n")
dir := t.TempDir()
broken := writeFile(t, dir, "broken.yaml", "bogus_key: 1\n")
serveConfig(t, filepath.Join(dir, "ok.sock"), func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/api/v1/config" {
http.NotFound(w, r)
return
}
w.Header().Set("Content-Type", "application/yaml")
if r.URL.Query().Get("docs") == "false" {
_, _ = w.Write([]byte(runningNoDocs))
} else {
_, _ = w.Write([]byte(running))
}
})
serveConfig(t, filepath.Join(dir, "failing.sock"), func(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/problem+json")
w.WriteHeader(http.StatusInternalServerError)
_, _ = w.Write([]byte(`{"status":500,"title":"Internal Server Error","detail":"rendering configuration"}`))
})
socket := func(name string) string {
return writeFile(t, dir, name+".yaml", "unix_socket: "+filepath.Join(dir, name+".sock")+"\ncli:\n timeout: 1s\n")
}
ok, failing, absent := socket("ok"), socket("failing"), socket("absent")
logging := func(name, setting string) string {
return writeFile(t, dir, name+".yaml", "unix_socket: "+filepath.Join(dir, "ok.sock")+"\nlog:\n "+setting+"\n")
}
env := []string{"HOME=" + home, "HEADSCALE_BOGUS=1"}
// The console form: log.format: json does not apply.
const warning = "WRN unknown environment variable HEADSCALE_BOGUS"
tests := []struct {
name string
args []string
wantErr bool
wantStdout []string
hideStdout []string
wantExact string // all of stdout, when set
wantStderr []string // nil when stderr must be empty
wantLoaded bool // stdout loads to Default()
}{
{name: "example", args: []string{"generate", "config"}, wantStdout: []string{"# Every key"}, wantLoaded: true},
{name: "alias", args: []string{"gen", "config"}, wantLoaded: true},
{name: "no docs", args: []string{"generate", "config", "--no-docs"}, hideStdout: []string{"#"}, wantLoaded: true},
{name: "running", args: []string{"-c", ok, "generate", "config", "--running"}, wantExact: running, wantStderr: []string{warning}},
{name: "running no docs", args: []string{"-c", ok, "generate", "config", "--running", "--no-docs"}, wantExact: runningNoDocs, wantStderr: []string{warning}},
{name: "running log level error", args: []string{"-c", logging("error", "level: error"), "generate", "config", "--running"}, wantExact: running, wantStderr: []string{warning}},
{name: "running log level disabled", args: []string{"-c", logging("disabled", "level: disabled"), "generate", "config", "--running"}, wantExact: running, wantStderr: []string{warning}},
{name: "running log format json", args: []string{"-c", logging("json", "format: json"), "generate", "config", "--running"}, wantExact: running, wantStderr: []string{warning}},
{name: "running server error", args: []string{"-c", failing, "generate", "config", "--running"}, wantErr: true, wantStderr: []string{warning, "rendering configuration"}},
{name: "running without a server", args: []string{"-c", absent, "generate", "config", "--running"}, wantErr: true, wantStderr: []string{warning, "asking the server for its configuration"}},
{name: "running broken", args: []string{"-c", broken, "generate", "config", "--running"}, wantErr: true, wantStderr: []string{warning, "bogus_key"}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
stdout, stderr, err := runHeadscale(t, env, tt.args...)
if tt.wantErr {
require.Error(t, err)
assert.Empty(t, stdout)
} else {
require.NoError(t, err, stderr)
var doc map[string]any
require.NoError(t, yaml.Unmarshal([]byte(stdout), &doc), stdout)
assert.NotContains(t, stdout, "HEADSCALE_BOGUS")
}
if tt.wantStderr == nil {
assert.Empty(t, stderr)
}
for _, s := range tt.wantStderr {
assert.Contains(t, stderr, s)
}
for _, s := range tt.wantStdout {
assert.Contains(t, stdout, s)
}
for _, s := range tt.hideStdout {
assert.NotContains(t, stdout, s)
}
if tt.wantExact != "" {
assert.Equal(t, tt.wantExact, stdout)
}
if tt.wantLoaded {
path := writeFile(t, t.TempDir(), "config.yaml", stdout)
l, err := config.Load(path, true, nil)
require.NoError(t, err)
want := config.Default()
if diff := cmp.Diff(&want, l.Config,
cmpopts.EquateEmpty(),
cmpopts.EquateComparable(netip.Prefix{}),
cmpopts.IgnoreFields(types.Config{}, "ConfigDir"),
cmpopts.IgnoreUnexported(types.Config{}),
); diff != "" {
t.Errorf("stdout loads as (-default +loaded):\n%s", diff)
}
}
})
}
}
+9 -6
View File
@@ -20,8 +20,10 @@ import (
var (
cfgFile string = ""
// loaded is what initConfig loaded; nil for the commands that skip it:
// check, version, mockoidc and completion.
// loaded is what initConfig loaded, or generate config --running, which
// skips initConfig and loads it itself; nil for the other commands that
// skip initConfig: check, generate config, version, mockoidc and
// completion.
loaded *config.Loaded
)
@@ -48,9 +50,10 @@ func init() {
})
}
// skipsInitConfig reports whether args select the check command group, which
// must work without a loadable config. Find runs lazily because init order
// across files is not guaranteed to have registered every command.
// skipsInitConfig reports whether args select the check command group or
// generate config, which must work without a loadable config. Find runs
// lazily because init order across files is not guaranteed to have
// registered every command.
func skipsInitConfig(args []string) bool {
cmd, rest, err := rootCmd.Find(args)
// `help check …` must work wherever `check …` does.
@@ -58,7 +61,7 @@ func skipsInitConfig(args []string) bool {
cmd, _, err = rootCmd.Find(rest)
}
return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd)
return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd || cmd == generateConfigCmd)
}
// loadConfig loads path, else the file -c names, else $HEADSCALE_CONFIG,
+34 -48
View File
@@ -1,73 +1,59 @@
package main
import (
"net/netip"
"os"
"path/filepath"
"testing"
"github.com/google/go-cmp/cmp"
"github.com/google/go-cmp/cmp/cmpopts"
"github.com/juanfont/headscale/hscontrol/config"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// writeExample writes the generated example as config.yaml in a new
// directory, which it returns.
func writeExample(t *testing.T) string {
t.Helper()
d := config.Default()
out, err := config.GenerateExample(&d, config.ExampleOptions{Docs: true})
require.NoError(t, err)
dir := t.TempDir()
require.NoError(t, os.WriteFile(filepath.Join(dir, "config.yaml"), out, 0o600))
return dir
}
func TestConfigFileLoading(t *testing.T) {
tmpDir := t.TempDir()
path, err := os.Getwd()
l, err := config.Load(filepath.Join(writeExample(t), "config.yaml"), true, nil)
require.NoError(t, err)
cfgFile := filepath.Join(tmpDir, "config.yaml")
// Symlink the example config file
err = os.Symlink(
filepath.Clean(path+"/../../config-example.yaml"),
cfgFile,
)
require.NoError(t, err)
// Load example config, it should load without validation errors
l, err := config.Load(cfgFile, true, os.Environ())
require.NoError(t, err)
assertExampleConfig(t, l.Config)
assertDefaultConfig(t, l.Config)
}
func TestConfigLoading(t *testing.T) {
tmpDir := t.TempDir()
path, err := os.Getwd()
l, err := config.Load(writeExample(t), false, nil)
require.NoError(t, err)
// Symlink the example config file
err = os.Symlink(
filepath.Clean(path+"/../../config-example.yaml"),
filepath.Join(tmpDir, "config.yaml"),
)
require.NoError(t, err)
// Load example config, it should load without validation errors
l, err := config.Load(tmpDir, false, os.Environ())
require.NoError(t, err)
assertExampleConfig(t, l.Config)
assertDefaultConfig(t, l.Config)
}
// assertExampleConfig checks the loaded config-example.yaml was interpreted
// correctly.
func assertExampleConfig(t *testing.T, cfg *types.Config) {
// assertDefaultConfig checks the example loaded as the defaults it prints.
func assertDefaultConfig(t *testing.T, cfg *types.Config) {
t.Helper()
require.NoError(t, config.Validate(cfg))
assert.Equal(t, "http://127.0.0.1:8080", cfg.ServerURL)
assert.Equal(t, types.ListenAddr("127.0.0.1:8080"), cfg.Addr)
assert.Equal(t, types.ListenAddr("127.0.0.1:9090"), cfg.MetricsAddr)
assert.True(t, cfg.Database.IsSQLite(), cfg.Database.Type)
assert.Equal(t, "/var/lib/headscale/db.sqlite", cfg.SQLitePath())
assert.Empty(t, cfg.TLS.ACME.Hostname)
assert.Equal(t, types.ListenAddr(":http"), cfg.TLS.ACME.HTTPListen)
assert.Equal(t, types.HTTP01ChallengeType, cfg.TLS.ACME.ChallengeType)
assert.Equal(t, types.FileMode(0o770), cfg.UnixSocketPermission)
assert.False(t, cfg.LogTail.Enabled)
want := config.Default()
if diff := cmp.Diff(&want, cfg,
cmpopts.EquateEmpty(),
cmpopts.EquateComparable(netip.Prefix{}),
cmpopts.IgnoreFields(types.Config{}, "ConfigDir"),
cmpopts.IgnoreUnexported(types.Config{}),
); diff != "" {
t.Errorf("example loads as (-default +loaded):\n%s", diff)
}
}
+12
View File
@@ -9,6 +9,7 @@ import (
clientv1 "github.com/juanfont/headscale/gen/client/v1"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"go.yaml.in/yaml/v3"
)
// TestAPIV1GeneratedClient smoke-tests the generated client against the Huma
@@ -47,4 +48,15 @@ func TestAPIV1GeneratedClient(t *testing.T) {
require.NotNil(t, listed.JSON200)
require.Len(t, listed.JSON200.Users, 1)
assert.Equal(t, "alice", listed.JSON200.Users[0].Name)
docs := false
cfg, err := client.GetConfigWithResponse(ctx, &clientv1.GetConfigParams{Docs: &docs})
require.NoError(t, err)
require.Equal(t, http.StatusOK, cfg.StatusCode())
var doc map[string]any
require.NoError(t, yaml.Unmarshal(cfg.Body, &doc), string(cfg.Body))
assert.Contains(t, doc, "server_url")
assert.NotContains(t, doc, "cli")
assert.NotRegexp(t, `(?m)^\s*#`, string(cfg.Body))
}