config: generate the configuration reference

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 12:19:28 +01:00
1 parent 63fdd50505
commit b92d27b7db
5 files changed
+1001 -9

No files matched your search

+7
View File
@@ -40,6 +40,13 @@ func exampleYAML(cfg *types.Config, opts ExampleOptions, root string) ([]byte, e
return nil, err
}
return exampleOf(keys, cfg, opts, root)
}
// exampleOf is [exampleYAML] from keys, the result of schema.
func exampleOf(keys []keyInfo, cfg *types.Config, opts ExampleOptions, root string) ([]byte, error) {
var err error
values := plainFields(cfg, opts.Redact)
top := &yaml.Node{Kind: yaml.MappingNode}
mappings := map[string]*yaml.Node{"": top}
+542
View File
@@ -0,0 +1,542 @@
package config
import (
"fmt"
"maps"
"regexp"
"slices"
"strings"
"unicode/utf8"
hsdns "github.com/juanfont/headscale/hscontrol/dns"
"github.com/juanfont/headscale/hscontrol/types"
"go.yaml.in/yaml/v3"
)
// The page's prose, around what the schema generates.
const (
referenceHead = "# Configuration options\n\n" +
"!!! note \"Generated page\"\n\n" +
" This page is generated from the doc comments in `hscontrol/types/config.go` by\n" +
" `go generate ./hscontrol/types/`. Edit the comments there, not this page.\n\n" +
"Every key headscale reads, in the order `headscale generate config` prints them, with its type, default,\n" +
"environment variable and an example for a configuration file, the environment and NixOS. Keys that no longer\n" +
"work are listed under [Removed keys](#removed-keys). [Configuration](configuration.md) explains where headscale\n" +
"finds its configuration, how to check it, and shows the full example.\n\n" +
"## Conventions { #conventions }\n\n" +
"### Value types { #types }\n\n"
referenceEnv = "### Environment variables { #env }\n\n" +
"Every key can also be set with an environment variable: `HEADSCALE_` and the key's path in capitals, with `_` for\n" +
"`.`, e.g. `HEADSCALE_LOG_LEVEL` for `log.level`. Each key below names its variable. A variable wins over the\n" +
"configuration file, which wins over the default; an empty variable counts as unset.\n\n" +
"A list is a JSON array or, unless its values are objects, its values separated by spaces. A map is a JSON object,\n" +
"which replaces the map in the configuration file instead of merging into it. The examples below write every list\n" +
"and map as JSON.\n\n" +
"A `HEADSCALE_` variable that names no key logs a warning, and one for a removed key also says what to do instead.\n" +
"Other software uses the same prefix, so neither stops headscale.\n\n" +
"A DNS provider setting that takes text can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING>`,\n" +
"e.g. `HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN`; see [`dns.challenge.provider`](#dns.challenge.provider).\n\n"
referenceSecrets = "### Secrets { #secrets }\n\n" +
"A secret takes the value itself or `file:<path>`, which reads it from that file. Environment variables in the path\n" +
"are expanded, as in `file:${CREDENTIALS_DIRECTORY}/oidc_client_secret`, and whitespace around the file's contents\n" +
"is trimmed; an empty file is an error. Headscale reads the file only where the secret is used, and\n" +
"`headscale check config` and `headscale check all` never read it. `headscale generate config --running` and\n" +
"`/debug/config` show a literal secret as `<redacted>` and a `file:` reference as written.\n\n"
referenceNixSecret = "On NixOS, keep a secret out of the Nix store: load it as a systemd credential and point the key at it.\n\n" +
"```nix\n" +
"services.headscale.settings.oidc.client_secret = \"file:\\${CREDENTIALS_DIRECTORY}/oidc_client_secret\";\n" +
"systemd.services.headscale.serviceConfig.LoadCredential = [ \"oidc_client_secret:/run/secrets/oidc_client_secret\" ];\n" +
"```\n\n"
referenceRemoved = "## Removed keys { #removed-keys }\n\n" +
"Keys headscale no longer reads. One in the configuration file stops headscale with an error and a variable for\n" +
"one logs a warning, each saying what to do instead, as the table does.\n\n"
secretsDir = "file:/run/secrets/"
)
var (
backtickedKey = regexp.MustCompile("`[a-z0-9_.]+`")
dottedName = regexp.MustCompile(`\b[a-z][a-z0-9_]*(\.([a-z0-9_]+|\*))+`)
shellWord = regexp.MustCompile(`^[A-Za-z0-9@%+=:,./_-]+$`)
)
// reference is the page being written.
type reference struct {
strings.Builder
keys []keyInfo
paths map[string]bool
}
// GenerateReference is the configuration reference page,
// docs/ref/configuration-options.md: the conventions, every node of
// [types.ConfigTree] with its type, default, variable and examples, and
// the removed keys.
func GenerateReference() ([]byte, error) {
keys, err := schema()
if err != nil {
return nil, err
}
r := &reference{keys: keys, paths: map[string]bool{}}
for _, k := range keys {
r.paths[k.Path] = true
}
r.WriteString(referenceHead)
r.types()
r.WriteString(referenceEnv)
r.secrets(keys)
for _, k := range keys {
err := r.key(k)
if err != nil {
return nil, fmt.Errorf("%s: %w", k.Path, err)
}
}
r.removed()
return []byte(strings.TrimSuffix(r.String(), "\n")), nil
}
// types writes the value-type legend; a row a Type line links carries
// the anchor.
func (r *reference) types() {
linked := map[string]bool{}
for _, k := range r.keys {
linked[k.Type.Anchor] = true
}
rows := make([][]string, 0, len(leafTypes))
for _, t := range leafTypes {
label := t.Label
if id := "type-" + strings.ReplaceAll(t.Label, " ", "-"); linked["#"+id] {
label = `<span id="` + id + `"></span>` + label
}
rows = append(rows, []string{label, t.Format, t.Sample})
}
r.table([]string{"Type", "Format", "Example"}, rows)
}
func (r *reference) secrets(keys []keyInfo) {
var names []string
for _, k := range keys {
if k.Field.Type == secretType {
names = append(names, r.link(k.Path))
}
}
r.WriteString(referenceSecrets)
fmt.Fprintf(r, "The secrets are %s and every string setting of %s.\n\n", strings.Join(names, ", "), r.link(providerKey))
r.WriteString(referenceNixSecret)
}
// key writes k's heading and block.
func (r *reference) key(k keyInfo) error {
name := k.Path[strings.LastIndex(k.Path, ".")+1:]
fmt.Fprintf(r, "%s `%s` { #%s data-toc-label=\"%s\" }\n\n", strings.Repeat("#", 2+strings.Count(k.Path, ".")), k.Path, k.Path, name)
if k.Section {
r.paragraph(r.prose(k.Doc, k.Path))
r.replaces(k)
example, err := exampleOf(r.keys, new(Default()), ExampleOptions{}, k.Path)
if err != nil {
return err
}
fmt.Fprintf(r, "??? example \"All `%s` keys and defaults\"\n\n", k.Path)
r.code("yaml", string(example))
return nil
}
err := r.facts(k)
if err != nil {
return err
}
r.paragraph(r.prose(k.Doc, k.Path))
r.details(k)
return r.examples(k)
}
// facts writes k's Type, Default and Env lines.
func (r *reference) facts(k keyInfo) error {
typ := "[" + k.Type.Label + "](" + k.Type.Anchor + ")"
if len(k.Type.Enum) > 0 {
typ += ": `" + strings.Join(k.Type.Enum, "`, `") + "`"
}
def := "- **Required**"
if !k.Required || k.RequiredWhen != "" {
v, err := flowYAML(k.Default)
if err != nil {
return err
}
def = "- **Default:** `" + v + "`"
if k.DefaultText != "" {
def += " (" + k.DefaultText + ")"
}
if k.RequiredWhen != "" {
def += "; required when " + r.prose(k.RequiredWhen, k.Path)
}
}
env := "`" + k.Env + "`"
if k.Type.Env != "" {
env += " ([" + k.Type.Env + "](#env))"
}
fmt.Fprintf(r, "- **Type:** %s\n%s\n- **Env:** %s\n\n", typ, def, env)
return nil
}
// details writes what k's type adds to its doc: the meaning of each enum
// value, the fields of a DNS record and the DNS providers. An open map's
// key case is its doc's to state.
func (r *reference) details(k keyInfo) {
values := make([][]string, 0, len(k.Type.Enum))
for _, v := range k.Type.Enum {
values = append(values, []string{"`" + v + "`", r.prose(types.ConfigValueDoc(k.Field.Type, v), k.Path)})
}
if slices.ContainsFunc(values, func(row []string) bool { return row[1] != "" }) {
r.table([]string{"Value", "Meaning"}, values)
}
if k.Field.Type == recordsType {
fields := make([][]string, 0, len(dnsRecordFields))
for _, f := range dnsRecordFields {
fields = append(fields, []string{"`" + f.Name + "`", "[string](#type-string)", r.prose(f.Doc, k.Path)})
}
r.table([]string{"Field", "Type", "Description"}, fields)
}
if k.Path == providerKey {
names := hsdns.ProviderNames()
providers := make([][]string, 0, len(names))
for _, p := range names {
providers = append(providers, []string{"`" + p + "`", "`" + strings.Join(hsdns.SettingNames(p), "`, `") + "`"})
}
r.table([]string{"Provider", "Settings"}, providers)
// The variable holds text, so an object setting cannot have one.
r.paragraph("Each text setting can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING>`, e.g. " +
"`HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN`, which wins over the same setting in `" + k.Env + "` and in the configuration file. " +
"An object setting, such as the `config` of `acmedns`, goes inside the JSON object of `" + k.Env + "`; " +
"see [Environment variables](dns.md#environment-variables).")
}
}
// examples writes k's example as a file, a variable and, for a key the
// server reads, NixOS settings, then the removed keys it replaces.
func (r *reference) examples(k keyInfo) error {
file, err := yamlText(nest(k.Path, k.Example))
if err != nil {
return err
}
r.WriteString("=== \"YAML\"\n\n")
r.code("yaml", file)
r.WriteString("=== \"Environment\"\n\n")
r.code("shell", envLine(k.Env, k.Example))
if !clientOnly(k.Path) {
var creds []string
nix := "services.headscale.settings." + k.Path + " = " + nixLiteral(credentials(k.Path, k.Example, &creds), 0) + ";\n"
if len(creds) > 0 {
nix += "systemd.services.headscale.serviceConfig.LoadCredential = [ \"" + strings.Join(creds, "\" \"") + "\" ];\n"
}
r.WriteString("=== \"NixOS\"\n\n")
r.code("nix", nix)
}
r.replaces(k)
return nil
}
// credentials is v, the example of the key at path, with each
// file:/run/secrets/ reference, at any map depth, read from the systemd
// credential named for its key instead; it appends each LoadCredential
// entry to creds, in key order.
func credentials(path string, v any, creds *[]string) any {
switch x := v.(type) {
case string:
if !strings.HasPrefix(x, secretsDir) {
return x
}
name := credentialName(path)
*creds = append(*creds, name+":"+strings.TrimPrefix(x, "file:"))
return "file:${CREDENTIALS_DIRECTORY}/" + name
case map[string]any:
out := make(map[string]any, len(x))
for _, key := range slices.Sorted(maps.Keys(x)) {
out[key] = credentials(path+"."+key, x[key], creds)
}
return out
}
return v
}
func (r *reference) replaces(k keyInfo) {
lines := make([]string, 0, len(k.Replaces))
for _, old := range k.Replaces {
lines = append(lines, "Replaces `"+old.Old+"` ([removed](#"+old.Old+")).")
}
r.paragraph(strings.Join(lines, "\n"))
}
// removed writes the removed-keys table: each row's first cell the
// anchor of its key, its last the hint the load error gives.
func (r *reference) removed() {
type row struct {
old string
cells []string
}
rows := make([]row, 0, len(removedKeys)+1)
// The provider's <setting>_path form is matched by name, not listed.
provider, _ := removedProviderPath(providerKey + ".<setting>_path")
for _, k := range append(slices.Clone(removedKeys), provider) {
k.Hint = r.hint(k.Hint)
id := strings.NewReplacer("<", "", ">", "").Replace(k.Old)
rows = append(rows, row{k.Old, []string{`<span id="` + id + `"></span>` + "`" + k.Old + "`", k.Since, k.hintAs(r.keyRef, "%s: `%s`")}})
}
slices.SortFunc(rows, func(a, b row) int { return strings.Compare(a.old, b.old) })
table := make([][]string, 0, len(rows))
for _, row := range rows {
table = append(table, row.cells)
}
r.WriteString(referenceRemoved)
r.table([]string{"Key", "Removed in", "What to do"}, table)
}
// topicPrefix starts the docs links in field comments. YAML and Nix need
// them absolute; the page links its own version instead (Decision 17).
const topicPrefix = "https://headscale.net/stable/ref/"
// relativeTopicLinks rewrites each topicPrefix + "<page>/[#frag]" in doc
// to "<page>.md[#frag]".
func relativeTopicLinks(doc string) string {
var b strings.Builder
for {
before, after, found := strings.Cut(doc, topicPrefix)
b.WriteString(before)
if !found {
return b.String()
}
path := after[:runEnd(after, isPathRune)]
slash := strings.LastIndexByte(path, '/')
if slash <= 0 {
b.WriteString(topicPrefix)
doc = after
continue
}
b.WriteString(path[:slash] + ".md")
doc = after[slash+1:]
if frag, ok := strings.CutPrefix(doc, "#"); ok {
if n := runEnd(frag, isFragRune); n > 0 {
b.WriteString("#" + frag[:n])
doc = frag[n:]
}
}
}
}
// runEnd is the length of s's leading run of runes that keep returns true for.
func runEnd(s string, keep func(rune) bool) int {
if n := strings.IndexFunc(s, func(c rune) bool { return !keep(c) }); n >= 0 {
return n
}
return len(s)
}
func isFragRune(c rune) bool {
return c >= 'a' && c <= 'z' || c >= '0' && c <= '9' || c == '_' || c == '-'
}
func isPathRune(c rune) bool {
return isFragRune(c) || c == '/'
}
// prose is a doc as the page prints it: each backticked key but self
// linked to its heading, each docs link relative.
func (r *reference) prose(doc, self string) string {
doc = relativeTopicLinks(doc)
return backtickedKey.ReplaceAllStringFunc(doc, func(span string) string {
key := strings.Trim(span, "`")
if !r.paths[key] || key == self {
return span
}
return "[" + span + "](#" + key + ")"
})
}
// hint is a removed key's free-text hint as Markdown: each key linked,
// each key pattern such as dns_config.* as code.
func (r *reference) hint(text string) string {
return dottedName.ReplaceAllStringFunc(text, func(name string) string {
switch {
case r.paths[name]:
return r.link(name)
case strings.HasSuffix(name, ".*"):
return "`" + name + "`"
}
return name
})
}
func (r *reference) link(key string) string {
return "[`" + key + "`](#" + key + ")"
}
// keyRef is key as code, linked to its heading or, for a placeholder
// such as dns.challenge.provider.<setting>, to its map's.
func (r *reference) keyRef(key string) string {
target, _, _ := strings.Cut(key, ".<")
if !r.paths[target] {
return "`" + key + "`"
}
return "[`" + key + "`](#" + target + ")"
}
func (r *reference) paragraph(text string) {
if text != "" {
r.WriteString(text + "\n\n")
}
}
// code writes body, which ends in a newline, as a fenced block indented
// into the admonition or tab above it.
func (r *reference) code(lang, body string) {
const indent = " "
r.WriteString(indent + "```" + lang + "\n")
for l := range strings.Lines(body) {
if l != "\n" {
r.WriteString(indent)
}
r.WriteString(l)
}
r.WriteString(indent + "```\n\n")
}
// table writes a table as mdformat does: each cell padded to its
// column's width in runes, | escaped.
func (r *reference) table(header []string, body [][]string) {
rows := append([][]string{header}, body...)
widths := make([]int, len(header))
cells := make([][]string, len(rows))
for i, row := range rows {
for j, c := range row {
c = strings.ReplaceAll(c, "|", `\|`)
cells[i] = append(cells[i], c)
widths[j] = max(widths[j], 3, utf8.RuneCountInString(c))
}
}
line := func(cells []string) {
for j, c := range cells {
r.WriteString("| " + c + strings.Repeat(" ", widths[j]-utf8.RuneCountInString(c)) + " ")
}
r.WriteString("|\n")
}
line(cells[0])
delimiter := make([]string, len(widths))
for j, w := range widths {
delimiter[j] = strings.Repeat("-", w)
}
line(delimiter)
for _, row := range cells[1:] {
line(row)
}
r.WriteString("\n")
}
// yamlText is v as a YAML file indented as GenerateExample indents.
func yamlText(v any) (string, error) {
var b strings.Builder
enc := yaml.NewEncoder(&b)
enc.SetIndent(2)
err := enc.Encode(v)
if err != nil {
return "", err
}
err = enc.Close()
return b.String(), err
}
// envLine is the shell line setting the variable env to v, exported so
// the headscale started next reads it.
func envLine(env string, v any) string {
return "export " + env + "=" + shellQuote(envValue(v)) + "\n"
}
// shellQuote is s as one POSIX shell word: as is when no character is
// special, else single-quoted.
func shellQuote(s string) string {
if shellWord.MatchString(s) {
return s
}
return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
}
+368
View File
@@ -0,0 +1,368 @@
package config
import (
"os"
"os/exec"
"regexp"
"slices"
"strings"
"testing"
"unicode/utf8"
gocmp "github.com/google/go-cmp/cmp"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
var (
refHeading = regexp.MustCompile("(?m)^(#+) `([^`]+)` \\{ #(\\S+) data-toc-label=\"([^\"]+)\" \\}$")
refAnchor = regexp.MustCompile(`\{ #([^ }]+)|<span id="([^"]+)"></span>`)
refLink = regexp.MustCompile(`\]\(#([^)]+)\)`)
refFence = regexp.MustCompile("(?ms)^ *```.*?^ *```$")
refCode = regexp.MustCompile("`[^`]*`")
refBareTag = regexp.MustCompile(`<[A-Za-z/][^>]*>`)
)
func referencePage(t *testing.T) string {
t.Helper()
page, err := GenerateReference()
require.NoError(t, err)
return string(page)
}
// keyBlocks are page's blocks by key path, each from its heading to the
// next heading.
func keyBlocks(page string) map[string]string {
blocks := map[string]string{}
for _, m := range refHeading.FindAllStringSubmatchIndex(page, -1) {
block := page[m[1]:]
if i := strings.Index(block, "\n#"); i >= 0 {
block = block[:i]
}
blocks[page[m[4]:m[5]]] = block
}
return blocks
}
func TestReference(t *testing.T) {
page := referencePage(t)
d := Default()
tree := types.ConfigTree(&d)
t.Run("headings", func(t *testing.T) {
want := make([]string, 0, len(tree))
for _, f := range tree {
leaf := f.Path[strings.LastIndex(f.Path, ".")+1:]
want = append(want, strings.Repeat("#", 2+strings.Count(f.Path, "."))+" "+f.Path+" #"+f.Path+" "+leaf)
}
headings := refHeading.FindAllStringSubmatch(page, -1)
got := make([]string, 0, len(headings))
for _, m := range headings {
got = append(got, m[1]+" "+m[2]+" #"+m[3]+" "+m[4])
}
if diff := gocmp.Diff(want, got); diff != "" {
t.Errorf("headings (-want +got):\n%s", diff)
}
require.Contains(t, page, "#### `dns.nameservers.split` { #dns.nameservers.split data-toc-label=\"split\" }\n")
})
blocks := keyBlocks(page)
for _, f := range tree {
if f.Section {
continue
}
t.Run(f.Path, func(t *testing.T) {
block := blocks[f.Path]
require.Contains(t, block, "\n- **Type:** [")
require.Regexp(t, `\n- \*\*(Default:\*\* |Required\*\*\n)`, block)
require.Contains(t, block, "\n- **Env:** `"+configEnvName(f.Path)+"`")
})
}
t.Run("removed rows", func(t *testing.T) {
_, removed, ok := strings.Cut(page, "\n## Removed keys { #removed-keys }\n")
require.True(t, ok)
for _, r := range removedKeys {
require.Contains(t, removed, "| <span id=\""+r.Old+"\"></span>`"+r.Old+"` ")
}
require.Contains(t, removed, "| <span id=\"dns.challenge.provider.setting_path\"></span>`dns.challenge.provider.<setting>_path` ")
require.Equal(t, len(removedKeys)+1, strings.Count(removed, "<span id="))
// The last cell is the hint the load error gives, keys linked.
for _, row := range []string{
"| use [`log.format`](#log.format): `json` ",
"| use [`prefixes.v4`](#prefixes.v4) and [`prefixes.v6`](#prefixes.v6) ",
"| remove `oidc.user`; see the CHANGELOG for context ",
"| use [`dns.challenge.provider.<setting>`](#dns.challenge.provider): `file:<path>` ",
"| move every `dns_config.*` key to dns (nameservers to [`dns.nameservers.global`](#dns.nameservers.global), ",
} {
require.Contains(t, removed, row)
}
})
t.Run("anchors", func(t *testing.T) {
matches := refAnchor.FindAllStringSubmatch(page, -1)
ids := make([]string, 0, len(matches))
for _, m := range matches {
ids = append(ids, m[1]+m[2])
}
for _, id := range []string{"conventions", "types", "env", "secrets", "removed-keys", "type-file-mode", "type-URL", "type-list", "type-map"} {
require.Contains(t, ids, id)
}
seen := map[string]bool{}
for _, id := range ids {
require.False(t, seen[id], "duplicate anchor %s", id)
seen[id] = true
}
linked := map[string]bool{}
for _, m := range refLink.FindAllStringSubmatch(page, -1) {
assert.True(t, seen[m[1]], "link to missing anchor #%s", m[1])
linked[m[1]] = true
}
for _, id := range ids {
if strings.HasPrefix(id, "type-") {
assert.True(t, linked[id], "legend id %s has no link", id)
}
}
})
t.Run("links", func(t *testing.T) {
require.NotContains(t, page, "https://headscale.net/stable/ref/")
require.Contains(t, page, "(dns.md#dns-01-challenge-provider)")
require.Contains(t, page, "(api.md#remote-control)")
// A key's doc links other keys, not itself.
require.Contains(t, blocks["tls.key_path"], "[`tls.cert_path`](#tls.cert_path)")
require.NotContains(t, blocks["oidc.issuer"], "](#oidc.issuer)")
})
}
func TestRelativeTopicLinks(t *testing.T) {
tests := []struct {
name, doc, want string
}{
{"page", "See https://headscale.net/stable/ref/dns/.", "See dns.md."},
{"fragment", "(https://headscale.net/stable/ref/oidc/#enable-pkce-recommended)", "(oidc.md#enable-pkce-recommended)"},
{"nested page", "https://headscale.net/stable/ref/integration/reverse-proxy/", "integration/reverse-proxy.md"},
{"two links", "https://headscale.net/stable/ref/dns/ and https://headscale.net/stable/ref/api/#remote-control", "dns.md and api.md#remote-control"},
{"empty fragment", "https://headscale.net/stable/ref/dns/#", "dns.md#"},
{"other host", "https://example.com/stable/ref/dns/", "https://example.com/stable/ref/dns/"},
{"prefix only", "https://headscale.net/stable/ref/", "https://headscale.net/stable/ref/"},
{"no link", "plain text", "plain text"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
require.Equal(t, tt.want, relativeTopicLinks(tt.doc))
})
}
}
// TestReferenceKeys pins the parts of a key's block the schema decides.
func TestReferenceKeys(t *testing.T) {
blocks := keyBlocks(referencePage(t))
tests := []struct {
path string
want, hide []string
}{
{path: "server_url", want: []string{"\n- **Required**\n", "\n export HEADSCALE_SERVER_URL=https://headscale.example.com\n"}},
{path: "database.type", want: []string{
"- **Type:** [enum](#type-enum): `sqlite`, `sqlite3`, `postgres`\n",
"- **Required**\n",
"| `postgres` | PostgreSQL, at [`database.postgres.host`](#database.postgres.host). ",
}},
{path: "dns.base_domain", want: []string{"- **Default:** `\"\"`; required when [`dns.magic_dns`](#dns.magic_dns) is true\n"}},
{path: "tuning.batcher_workers", want: []string{"- **Default:** `0` (three quarters of the CPU cores, at least one)\n"}},
{path: "unix_socket_permission", want: []string{"- **Type:** [file mode](#type-file-mode)\n", "- **Default:** `\"0770\"`\n"}},
{path: "dns.nameservers.split", want: []string{
"- **Type:** [map of `<domain>` → list of strings](#type-map)\n",
"- **Env:** `HEADSCALE_DNS_NAMESERVERS_SPLIT` ([JSON object](#env))\n",
" export HEADSCALE_DNS_NAMESERVERS_SPLIT='{\"corp.example.com\":[\"192.0.2.53\"],",
" services.headscale.settings.dns.nameservers.split = {\n \"corp.example.com\" = [\n",
}, hide: []string{"Each `<domain>` key"}},
{path: "database.postgres.pass", want: []string{
"- **Type:** [secret](#secrets)\n",
" services.headscale.settings.database.postgres.pass = \"file:\\${CREDENTIALS_DIRECTORY}/database_postgres_pass\";\n",
" systemd.services.headscale.serviceConfig.LoadCredential = [ \"database_postgres_pass:/run/secrets/postgres_password\" ];\n",
"Replaces `database.postgres.password_file` ([removed](#database.postgres.password_file)).",
}},
{path: "dns.challenge.provider", want: []string{
"| Provider ",
"| `cloudflare` ",
"Each text setting can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING>`",
"An object setting, such as the `config` of `acmedns`, goes inside the JSON object of `HEADSCALE_DNS_CHALLENGE_PROVIDER`",
"(dns.md#environment-variables)",
"api_token = \"file:\\${CREDENTIALS_DIRECTORY}/dns_challenge_provider_api_token\";",
"LoadCredential = [ \"dns_challenge_provider_api_token:/run/secrets/cloudflare\" ];",
}},
{path: "cli", want: []string{"`services.headscale.settings`"}},
{path: "cli.api_key", want: []string{"=== \"Environment\"", "export HEADSCALE_CLI_API_KEY=file:/run/secrets/"}, hide: []string{"=== \"NixOS\"", "CREDENTIALS_DIRECTORY"}},
{path: "dns.extra_records", want: []string{
"- **Env:** `HEADSCALE_DNS_EXTRA_RECORDS` ([JSON array](#env))\n",
"| Field ",
"| `value` | [string](#type-string) | The IP address the name resolves to. ",
}},
{path: "dns", want: []string{
"??? example \"All `dns` keys and defaults\"\n\n ```yaml\n dns:\n magic_dns: true\n",
"Replaces `dns_config` ([removed](#dns_config)).",
}},
{path: "noise.private_key_path", want: []string{
"Replaces `private_key_path` ([removed](#private_key_path)).\nReplaces `noise_private_key_path` ([removed](#noise_private_key_path)).",
}},
{path: "tls.acme.hostname", want: []string{" tls:\n acme:\n hostname: "}},
}
for _, tt := range tests {
t.Run(tt.path, func(t *testing.T) {
for _, w := range tt.want {
require.Contains(t, blocks[tt.path], w)
}
for _, h := range tt.hide {
require.NotContains(t, blocks[tt.path], h)
}
})
}
}
// TestOpenMapDocs: the page prints an open map's key case only through its
// doc, so the doc must state the rule the loader applies.
func TestOpenMapDocs(t *testing.T) {
keys, err := schema()
require.NoError(t, err)
for _, k := range keys {
if !k.Open {
continue
}
t.Run(k.Path, func(t *testing.T) {
if slices.Contains(caseSensitiveMaps, k.Path) {
require.Contains(t, k.Doc, "keep their case")
return
}
require.Contains(t, k.Doc, "lowercased on load")
require.Contains(t, k.Doc, "two that differ only in case are an error")
})
}
}
func TestReferenceEscapes(t *testing.T) {
page := referencePage(t)
d := Default()
example, err := GenerateExample(&d, ExampleOptions{Docs: true})
require.NoError(t, err)
// The macros plugin renders the page and the included example as Jinja.
for name, text := range map[string]string{"page": page, "example": string(example)} {
for _, jinja := range []string{"{{", "{%", "{#"} {
require.NotContains(t, text, jinja, name)
}
}
prose := refCode.ReplaceAllString(refFence.ReplaceAllString(page, ""), "")
prose = regexp.MustCompile(`<span id="[^"]+"></span>`).ReplaceAllString(prose, "")
require.Empty(t, refBareTag.FindAllString(prose, -1))
tables := 0
var width []int
for line := range strings.Lines(page + "\n") {
if !strings.HasPrefix(line, "|") {
if len(width) > 0 {
tables++
require.Len(t, slices.Compact(width), 1, "rows of table %d differ in width", tables)
}
width = nil
continue
}
width = append(width, utf8.RuneCountInString(line))
}
require.GreaterOrEqual(t, tables, 3)
}
// exported runs line in a clean shell and returns what a child it starts
// reads from env.
func exported(t *testing.T, line, env string) string {
t.Helper()
sh, err := exec.LookPath("sh")
if err != nil {
t.Skip("no sh")
}
cmd := exec.CommandContext(t.Context(), sh, "-c", line+`sh -c 'printf %s "$`+env+`"'`)
cmd.Env = []string{"PATH=" + os.Getenv("PATH")}
out, err := cmd.Output()
require.NoError(t, err, line)
return string(out)
}
// TestReferenceEnvTabs: an Environment tab pasted into a shell reaches
// the headscale it starts.
func TestReferenceEnvTabs(t *testing.T) {
blocks := keyBlocks(referencePage(t))
byPath := schemaByPath(t)
for _, path := range []string{"dns.nameservers.global", "dns.nameservers.split", "database.postgres.pass", "dns.challenge.provider"} {
t.Run(path, func(t *testing.T) {
_, tab, ok := strings.Cut(blocks[path], "=== \"Environment\"\n\n ```shell\n ")
require.True(t, ok)
line, _, _ := strings.Cut(tab, "\n")
k := byPath[path]
require.Equal(t, envValue(k.Example), exported(t, line+"\n", k.Env))
})
}
t.Run("quotes", func(t *testing.T) {
v := `it's "q" $HOME`
require.Equal(t, v, exported(t, envLine("HEADSCALE_X", v), "HEADSCALE_X"))
})
}
func TestShellQuote(t *testing.T) {
tests := []struct{ in, want string }{
{in: "abc", want: "abc"},
{in: "file:/run/secrets/x", want: "file:/run/secrets/x"},
{in: "a b", want: "'a b'"},
{in: "file:${X}/y", want: "'file:${X}/y'"},
{in: "it's", want: `'it'\''s'`},
{in: "", want: "''"},
{in: `["a","b"]`, want: `'["a","b"]'`},
}
for _, tt := range tests {
t.Run(tt.in, func(t *testing.T) {
require.Equal(t, tt.want, shellQuote(tt.in))
})
}
}
+33 -5
View File
@@ -1,8 +1,9 @@
// Command files writes the files generated from the configuration schema
// of hscontrol/config: `files <root>` writes nix/options.generated.nix
// below the repository root. It is not part of configgen, which stays
// standard library only so its table regenerates when the committed one
// does not compile.
// of hscontrol/config: `files <root>` writes nix/options.generated.nix,
// docs/ref/configuration-options.md and docs/ref/config-example.yaml below
// the repository root. It is not part of configgen, which stays standard
// library only so its table regenerates when the committed one does not
// compile.
//
// `files -load <file>` prints the file as config.Load reads it, for the
// NixOS options check to compare with the values it was written from.
@@ -17,6 +18,10 @@ import (
"github.com/juanfont/headscale/hscontrol/config"
)
// exampleHeader marks the committed example; generate config output is
// the user's to edit, so it carries none.
const exampleHeader = "# Generated from hscontrol/types/config.go by go generate; do not edit.\n"
func main() {
var err error
@@ -63,5 +68,28 @@ func write(root string) error {
return err
}
return os.WriteFile(filepath.Join(root, "nix", "options.generated.nix"), nix, 0o600)
page, err := config.GenerateReference()
if err != nil {
return err
}
d := config.Default()
example, err := config.GenerateExample(&d, config.ExampleOptions{Docs: true})
if err != nil {
return err
}
for path, b := range map[string][]byte{
"nix/options.generated.nix": nix,
"docs/ref/configuration-options.md": page,
"docs/ref/config-example.yaml": append([]byte(exampleHeader), example...),
} {
err := os.WriteFile(filepath.Join(root, path), b, 0o600)
if err != nil {
return err
}
}
return nil
}
+51 -4
View File
@@ -5,6 +5,7 @@ import (
"io"
"os"
"path/filepath"
"regexp"
"testing"
"github.com/google/go-cmp/cmp"
@@ -14,19 +15,43 @@ import (
"go.yaml.in/yaml/v3"
)
func TestWrite(t *testing.T) {
// generatedFiles are the files write writes, below the repository root.
var generatedFiles = []string{"nix/options.generated.nix", "docs/ref/configuration-options.md", "docs/ref/config-example.yaml"}
// writeTree runs write into a new repository root.
func writeTree(t *testing.T) string {
t.Helper()
root := t.TempDir()
require.NoError(t, os.Mkdir(filepath.Join(root, "nix"), 0o755))
for _, dir := range []string{"nix", "docs/ref"} {
require.NoError(t, os.MkdirAll(filepath.Join(root, dir), 0o755))
}
require.NoError(t, write(root))
want, err := config.GenerateNixOptions(nil)
return root
}
func TestWrite(t *testing.T) {
root := writeTree(t)
nix, err := config.GenerateNixOptions(nil)
require.NoError(t, err)
page, err := config.GenerateReference()
require.NoError(t, err)
d := config.Default()
example, err := config.GenerateExample(&d, config.ExampleOptions{Docs: true})
require.NoError(t, err)
tests := []struct {
path string
want []byte
}{
{path: "nix/options.generated.nix", want: want},
{path: "nix/options.generated.nix", want: nix},
{path: "docs/ref/configuration-options.md", want: page},
{path: "docs/ref/config-example.yaml", want: append([]byte("# Generated from hscontrol/types/config.go by go generate; do not edit.\n"), example...)},
}
for _, tt := range tests {
@@ -41,6 +66,28 @@ func TestWrite(t *testing.T) {
}
}
// TestGeneratedFiles: each file is the same on every run, ends in one
// newline and has no trailing whitespace, so the repository's hooks leave
// it alone.
func TestGeneratedFiles(t *testing.T) {
first, second := writeTree(t), writeTree(t)
trailing := regexp.MustCompile(`(?m)[ \t]$`)
for _, path := range generatedFiles {
t.Run(path, func(t *testing.T) {
a, err := os.ReadFile(filepath.Join(first, path))
require.NoError(t, err)
b, err := os.ReadFile(filepath.Join(second, path))
require.NoError(t, err)
require.Equal(t, a, b)
require.True(t, bytes.HasSuffix(a, []byte("\n")) && !bytes.HasSuffix(a, []byte("\n\n")), "must end in one newline")
require.Empty(t, trailing.FindAll(a, -1), "trailing whitespace")
})
}
}
// TestLoad: load prints a file as config.Load reads it, in canonical form
// and without the cli section; it fails on what Load rejects.
func TestLoad(t *testing.T) {