diff --git a/cmd/headscale/cli/generate.go b/cmd/headscale/cli/generate.go index 49d42e2f5..7cc8ebbfc 100644 --- a/cmd/headscale/cli/generate.go +++ b/cmd/headscale/cli/generate.go @@ -20,6 +20,8 @@ func init() { 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") + generateConfigCmd.Flags().Bool("minimal", false, "Print only the keys every server must set") + generateConfigCmd.MarkFlagsMutuallyExclusive("minimal", "running") generateCmd.AddCommand(generateConfigCmd) generateNixOSOptionsCmd.Flags().Bool("release", false, "Stamp the version and commit of this binary, which must be a clean build of a known commit") @@ -57,7 +59,8 @@ var generateConfigCmd = &cobra.Command{ 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. +keys marked "Required" before starting headscale. With --minimal, print only +those keys. With --running, print instead the configuration of the running server, without the client-only cli section: literal secrets, DNS provider settings @@ -67,6 +70,7 @@ kept as written.`, RunE: func(cmd *cobra.Command, _ []string) error { noDocs, _ := cmd.Flags().GetBool("no-docs") running, _ := cmd.Flags().GetBool("running") + minimal, _ := cmd.Flags().GetBool("minimal") if running { return printRunningConfig(cmd, !noDocs) @@ -74,7 +78,7 @@ kept as written.`, d := config.Default() - out, err := config.GenerateExample(&d, config.ExampleOptions{Docs: !noDocs}) + out, err := config.GenerateExample(&d, config.ExampleOptions{Docs: !noDocs, Minimal: minimal}) if err != nil { return fmt.Errorf("generating config: %w", err) } diff --git a/cmd/headscale/cli/generate_test.go b/cmd/headscale/cli/generate_test.go index ff909e4bf..335f4e772 100644 --- a/cmd/headscale/cli/generate_test.go +++ b/cmd/headscale/cli/generate_test.go @@ -303,6 +303,10 @@ func TestGenerateConfigCommand(t *testing.T) { {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: "minimal", args: []string{"generate", "config", "--minimal"}, wantStdout: []string{`server_url: ""`}, hideStdout: []string{"listen_addr"}, wantLoaded: true}, + {name: "minimal no docs", args: []string{"generate", "config", "--minimal", "--no-docs"}, wantExact: "server_url: \"\"\n"}, + // Cobra's flag-group error. + {name: "minimal running", args: []string{"-c", ok, "generate", "config", "--minimal", "--running"}, wantErr: true, wantStderr: []string{"none of the others can be"}}, {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}}, diff --git a/hscontrol/config/generate.go b/hscontrol/config/generate.go index 1bb4b3713..81d3862d9 100644 --- a/hscontrol/config/generate.go +++ b/hscontrol/config/generate.go @@ -19,10 +19,14 @@ type ExampleOptions struct { // OmitClientOnly leaves out the keys only the CLI reads, which a // server's configuration has no use for. OmitClientOnly bool + // Minimal keeps only the keys every server must set, under their + // sections. + Minimal bool } const ( exampleHeader = "# Every key: https://headscale.net/stable/ref/configuration-options/\n" + minimalHeader = "# The keys every server must set.\n" + exampleHeader commentWidth = 80 ) @@ -60,6 +64,12 @@ func exampleOf(keys []keyInfo, cfg *types.Config, opts ExampleOptions, root stri continue } + if opts.Minimal && !slices.ContainsFunc(keys, func(l keyInfo) bool { + return l.Required && l.RequiredWhen == "" && (l.Path == k.Path || strings.HasPrefix(l.Path, k.Path+".")) + }) { + continue + } + parent, name := "", k.Path if i := strings.LastIndex(k.Path, "."); i >= 0 { parent, name = k.Path[:i], k.Path[i+1:] @@ -88,7 +98,10 @@ func exampleOf(keys []keyInfo, cfg *types.Config, opts ExampleOptions, root stri var b bytes.Buffer - if opts.Docs && root == "" { + switch { + case opts.Docs && root == "" && opts.Minimal: + b.WriteString(minimalHeader) + case opts.Docs && root == "": b.WriteString(exampleHeader) } diff --git a/hscontrol/config/generate_test.go b/hscontrol/config/generate_test.go index 6ec173f86..a0aea4357 100644 --- a/hscontrol/config/generate_test.go +++ b/hscontrol/config/generate_test.go @@ -346,3 +346,83 @@ func TestGenerateExampleSubtree(t *testing.T) { }) } } + +// TestGenerateExampleMinimal: the minimal example holds only the keys every +// server must set, under their sections; it and the full example, with +// server_url set, load without warnings and validate. +func TestGenerateExampleMinimal(t *testing.T) { + d := Default() + + tests := []struct { + name string + opts ExampleOptions + wantExact string // all of the output, when set + wantPrefix string + wantText string + wantKeys []string // top-level keys and leaves, when set + }{ + {name: "minimal", opts: ExampleOptions{Minimal: true}, wantExact: "server_url: \"\"\n"}, + { + name: "minimal docs", + opts: ExampleOptions{Docs: true, Minimal: true}, + wantPrefix: minimalHeader + "\n", + wantText: "Required. Example: https://headscale.example.com", + wantKeys: []string{"server_url"}, + }, + {name: "full docs", opts: ExampleOptions{Docs: true}, wantPrefix: exampleHeader + "\n"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + out, err := GenerateExample(&d, tt.opts) + require.NoError(t, err) + + text := string(out) + + if tt.wantExact != "" { + assert.Equal(t, tt.wantExact, text) + } + + assert.True(t, strings.HasPrefix(text, tt.wantPrefix), text) + assert.Contains(t, text, tt.wantText) + + if tt.wantKeys != nil { + top, leaves := exampleKeys(t, out) + assert.Equal(t, tt.wantKeys, top) + assert.Equal(t, tt.wantKeys, leaves) + } + + // The leading newline matches a first line too. + require.Contains(t, "\n"+text, "\nserver_url: \"\"\n") + set := strings.Replace("\n"+text, "\nserver_url: \"\"\n", "\nserver_url: https://headscale.example.com\n", 1) + path := filepath.Join(t.TempDir(), "config.yaml") + require.NoError(t, os.WriteFile(path, []byte(set), 0o600)) + + l, err := Load(path, true, nil) + require.NoError(t, err, set) + assert.Empty(t, l.Warnings) + assert.NoError(t, Validate(l.Config)) + }) + } + + t.Run("nested", func(t *testing.T) { + keys, err := schema() + require.NoError(t, err) + + for _, k := range []struct{ path, when string }{ + {path: "noise.private_key_path"}, + {path: "database.sqlite.path", when: "`database.type` is `sqlite`"}, + } { + i := slices.IndexFunc(keys, func(ki keyInfo) bool { return ki.Path == k.path }) + require.GreaterOrEqual(t, i, 0, k.path) + keys[i].Required, keys[i].RequiredWhen = true, k.when + } + + out, err := exampleOf(keys, &d, ExampleOptions{Minimal: true}, "") + require.NoError(t, err) + + top, leaves := exampleKeys(t, out) + assert.Equal(t, []string{"server_url", "noise"}, top) + assert.Equal(t, []string{"server_url", "noise.private_key_path"}, leaves) + }) +}