diff --git a/hscontrol/config/load.go b/hscontrol/config/load.go index aa2c1fb3a..40aa2d63f 100644 --- a/hscontrol/config/load.go +++ b/hscontrol/config/load.go @@ -1340,14 +1340,28 @@ func toObject(s string) (any, error) { return dropNulls(m), nil } -// plainMap is cfg as nested maps of plain values, keyed as in a file: what -// the defaults layer loads and a parser marshals. With redact, a secret -// shows only a file: reference, a URL no userinfo, and every DNS provider -// setting but a scalar name and file: references is hidden: any of them, a -// number included, may be a credential. +// plainMap is [plainFields] nested as in a file, nils left out: what the +// defaults layer loads and a parser marshals. func plainMap(cfg *types.Config, redact bool) map[string]any { out := map[string]any{} + for path, v := range plainFields(cfg, redact) { + if v != nil { + setPath(out, path, v) + } + } + + return out +} + +// plainFields is every leaf of cfg by path, as a parser writes it: nil +// for a nil list or map, "" for a nil prefix. With redact, a secret shows +// only a file: reference, a URL no userinfo, and every DNS provider +// setting but a scalar name and file: references is hidden: any of them, +// a number included, may be a credential. +func plainFields(cfg *types.Config, redact bool) map[string]any { + out := map[string]any{} + if redact { // HTTPURL and Secret values redact themselves, plain strings not. r := cfg.RedactedURLs() @@ -1365,29 +1379,29 @@ func plainMap(cfg *types.Config, redact bool) map[string]any { v = redactProvider(settings) } - if v == nil { - continue - } - - parts := strings.Split(f.Path, ".") - m := out - - for _, p := range parts[:len(parts)-1] { - child, ok := m[p].(map[string]any) - if !ok { - child = map[string]any{} - m[p] = child - } - - m = child - } - - m[parts[len(parts)-1]] = v + out[f.Path] = v } return out } +// setPath sets the dotted path below m to v, adding the maps between. +func setPath(m map[string]any, path string, v any) { + parts := strings.Split(path, ".") + + for _, p := range parts[:len(parts)-1] { + child, ok := m[p].(map[string]any) + if !ok { + child = map[string]any{} + m[p] = child + } + + m = child + } + + m[parts[len(parts)-1]] = v +} + // maxExactJSONInt is the largest integer a float64, as JSON parsers read // numbers, holds exactly. const maxExactJSONInt = 1 << 53 diff --git a/hscontrol/config/schema.go b/hscontrol/config/schema.go new file mode 100644 index 000000000..217a11909 --- /dev/null +++ b/hscontrol/config/schema.go @@ -0,0 +1,437 @@ +package config + +import ( + "bytes" + "cmp" + "encoding/json" + "errors" + "fmt" + "net/netip" + "reflect" + "slices" + "strings" + "time" + + "github.com/juanfont/headscale/hscontrol/types" + "github.com/knadh/koanf/providers/confmap" + "github.com/knadh/koanf/v2" + "tailscale.com/tailcfg" +) + +var ( + errUnknownType = errors.New("no value type for Go type") + errBadExample = errors.New("bad example tag") + errNoMapKey = errors.New("open map without a mapkey tag") + errInvalidDefault = errors.New("a default fails validation") +) + +// keyInfo is what the generators know about one node of +// [types.ConfigTree]. +type keyInfo struct { + types.ConfigField + + Env string // configEnvName(Path); "" for sections + Type typeInfo // zero for sections + // Default is the value in Default(), as plainFields prints it; a nil + // list or map is empty. + Default any + // Example is the example tag as plainFields prints it once loaded; + // !Default for a bool, nil for sections. + Example any + Required bool + // RequiredWhen is the condition under which Required holds, keys + // backticked; "" is always. + RequiredWhen string + MapKey string // the placeholder for an open map's keys + DefaultText string // the default in words, where Default is a stand-in + Replaces []removedKey // the removed keys whose New names Path +} + +// typeInfo is how a key's value is written. +type typeInfo struct { + Label string // "duration", "list of prefixes", "map of `` → list of strings" + Anchor string // the legend row explaining Label + Env string // the encoding of a variable: "" for text, or "JSON object", ... + Nix string // the NixOS option type; "" where a generator builds it + Enum []string +} + +// leafType is a row of the value-type legend. Rows match a Go type +// exactly, then by implementing an interface Type, then by kind. +type leafType struct { + Type reflect.Type + Kinds []reflect.Kind + + Label, Plural string + // Format and Sample explain the type in the legend, in Markdown. + Format, Sample string + // Nix is the NixOS type, or for a list or map its constructor. + Nix string + // Anchor overrides "#type-" + Label. + Anchor string +} + +const nixStr = "lib.types.str" + +var allowedType = reflect.TypeFor[interface{ Allowed() []string }]() + +// leafTypes is the one type table: the page's legend, every key's type +// label and its NixOS type. +var leafTypes = []leafType{ + { + Kinds: []reflect.Kind{reflect.String}, Label: "string", Plural: "strings", + Format: "Text. Quote it where YAML would read another type, as in `\"0x1F\"` or `\"null\"`.", + Sample: "`/var/lib/headscale/db.sqlite`", Nix: nixStr, + }, + { + Kinds: []reflect.Kind{reflect.Bool}, Label: "boolean", Plural: "booleans", + Format: "`true` or `false`.", Sample: "`true`", Nix: "lib.types.bool", + }, + { + Kinds: []reflect.Kind{reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64}, Label: "integer", Plural: "integers", + Format: "A whole number.", Sample: "`1024`", Nix: "lib.types.int", + }, + { + Type: reflect.TypeFor[time.Duration](), Label: "duration", Plural: "durations", + Format: "A number with a unit, `ms`, `s`, `m`, `h`, `d`, `w` or `y`, units combined largest first; `0` needs none.", + Sample: "`1h30m`", Nix: "t.duration", + }, + { + Type: reflect.TypeFor[types.FileMode](), Label: "file mode", Plural: "file modes", + Format: "Octal permission bits, quoted.", Sample: "`\"0770\"`", Nix: "t.fileMode", + }, + { + Type: reflect.TypeFor[types.ListenAddr](), Label: "listen address", Plural: "listen addresses", + Format: "`host:port`. An empty host listens on every address; the port may be `http` or `https`.", + Sample: "`0.0.0.0:8080`", Nix: "t.listenAddr", + }, + { + Type: reflect.TypeFor[types.HTTPURL](), Label: "URL", Plural: "URLs", + Format: "An absolute `http://` or `https://` URL with a host.", Sample: "`https://headscale.example.com`", Nix: "t.httpURL", + }, + { + Type: reflect.TypeFor[netip.Prefix](), Label: "prefix", Plural: "prefixes", + Format: "An IP range in CIDR notation.", Sample: "`100.64.0.0/10`", Nix: "t.prefix", + }, + { + Type: reflect.TypeFor[types.Secret](), Label: "secret", Plural: "secrets", Anchor: "#secrets", + Format: "Text, or `file:` to read it from a file.", Sample: "`file:/run/secrets/oidc_client_secret`", Nix: "t.secretFile", + }, + { + Type: allowedType, Label: "enum", Plural: "enums", + Format: "One of the values listed with the key.", Sample: "`sqlite`", + }, + { + Type: reflect.TypeFor[tailcfg.DNSRecord](), Label: "DNS record", Plural: "DNS records", + Format: "An object with `name`, `type` and `value`.", + Sample: "`{name: grafana.example.com, type: A, value: 100.64.0.3}`", + }, + { + Kinds: []reflect.Kind{reflect.Interface}, Label: "value", Plural: "values", + Format: "Whatever the setting takes: text, a number, a boolean, a list or a map.", + Sample: "`file:/run/secrets/cloudflare`", Nix: "lib.types.anything", + }, + { + Kinds: []reflect.Kind{reflect.Slice}, Label: "list", + Format: "A list. A variable holds it as a JSON array or, unless its values are objects, separated by spaces.", + Sample: "`[9.9.9.9, 2620:fe::fe]`", Nix: "lib.types.listOf", + }, + { + Kinds: []reflect.Kind{reflect.Map}, Label: "map", + Format: "Keys you choose, each with a value. A variable holds a JSON object.", + Sample: "`{corp.example.com: [192.0.2.53]}`", Nix: "lib.types.attrsOf", + }, +} + +// recordField is a field of a dns.extra_records entry. +type recordField struct { + Name, Doc string + // Nix is the NixOS type; with Enum, an enum of those values. + Nix string + Enum []string + // Default is the NixOS default; nil makes the field required. + Default any +} + +// dnsRecordFields document [tailcfg.DNSRecord], whose fields carry no +// docs of ours. +var dnsRecordFields = []recordField{ + {Name: "name", Doc: "The fully qualified domain name, e.g. `grafana.example.com`; the trailing dot is optional.", Nix: nixStr}, + { + Name: "type", Doc: "The record type, `A` or `AAAA`; empty picks it from `value`. Clients ignore other types.", + Enum: []string{"", "A", "AAAA"}, Default: "", + }, + {Name: "value", Doc: "The IP address the name resolves to.", Nix: "t.ip"}, +} + +// schema describes every node of ConfigTree(Default()), in its order. It +// fails on a leaf of a type leafTypes lacks, or whose example does not +// load as written. +func schema() ([]keyInfo, error) { + d := Default() + defaults := plainFields(&d, false) + + required, err := requiredKeys() + if err != nil { + return nil, err + } + + var keys []keyInfo + + for _, f := range types.ConfigTree(&d) { + k := keyInfo{ConfigField: f} + + for _, r := range removedKeys { + if slices.Contains(strings.Fields(r.New), f.Path) { + k.Replaces = append(k.Replaces, r) + } + } + + if !f.Section { + err := k.describeLeaf(defaults[f.Path], required) + if err != nil { + return nil, fmt.Errorf("%s: %w", f.Path, err) + } + } + + keys = append(keys, k) + } + + return keys, nil +} + +func (k *keyInfo) describeLeaf(def any, required map[string]string) error { + var err error + + k.Env = configEnvName(k.Path) + k.MapKey = k.Field.Tag.Get("mapkey") + k.DefaultText = k.Field.Tag.Get("defaulttext") + k.RequiredWhen, k.Required = required[k.Path] + + k.Type, err = typeOf(k.Field.Type) + if err != nil { + return err + } + + if k.Open { + if k.MapKey == "" { + return errNoMapKey + } + + k.Type.Label = strings.Replace(k.Type.Label, "", "<"+k.MapKey+">", 1) + } + + switch { + case def != nil: + k.Default = def + case k.Value.Kind() == reflect.Slice: + k.Default = []any{} + default: + k.Default = map[string]any{} + } + + k.Example, err = loadExample(k.ConfigField, k.Default) + + return err +} + +// loadExample is f's example tag as plainFields prints it once the +// loader has read it, which must be the tag's own JSON; for a bool, !def. +func loadExample(f types.ConfigField, def any) (any, error) { + tag, tagged := f.Field.Tag.Lookup("example") + b, isBool := def.(bool) + + switch { + case isBool && !tagged: + return !b, nil + case isBool || !tagged: + return nil, fmt.Errorf("%w: a bool takes none, every other leaf one", errBadExample) + } + + var v any + + err := json.Unmarshal([]byte(tag), &v) + if err != nil { + return nil, fmt.Errorf("%w: %w", errBadExample, err) + } + + d := Default() + s := &configSource{k: koanf.New("."), envVars: map[string]string{}} + + err = s.k.Load(confmap.Provider(plainMap(&d, false), ""), nil) + if err != nil { + return nil, err + } + + err = s.k.Load(confmap.Provider(nest(f.Path, v), ""), nil) + if err != nil { + return nil, err + } + + cfg, err := s.decode() + if err != nil { + return nil, fmt.Errorf("%w: %w", errBadExample, err) + } + + loaded := plainFields(cfg, false)[f.Path] + + want, err := json.Marshal(v) + if err != nil { + return nil, err + } + + got, err := json.Marshal(loaded) + if err != nil || !bytes.Equal(want, got) { + return nil, fmt.Errorf("%w: loads as %s", errBadExample, got) + } + + return loaded, nil +} + +// typeOf is how a value of Go type t is written. +func typeOf(t reflect.Type) (typeInfo, error) { + for t.Kind() == reflect.Pointer { + t = t.Elem() + } + + row, ok := leafTypeOf(t) + if !ok { + return typeInfo{}, fmt.Errorf("%w %s", errUnknownType, t) + } + + ti := typeInfo{ + Label: row.Label, + Anchor: cmp.Or(row.Anchor, "#type-"+strings.ReplaceAll(row.Label, " ", "-")), + Nix: row.Nix, + } + + switch { + case row.Type == allowedType: + ti.Enum = reflect.Zero(t).Interface().(interface{ Allowed() []string }).Allowed() //nolint:forcetypeassert // matched by Implements + case t.Kind() == reflect.Slice: + elem, ok := leafTypeOf(t.Elem()) + if !ok || elem.Plural == "" { + return typeInfo{}, fmt.Errorf("%w %s", errUnknownType, t) + } + + ti.Label = "list of " + elem.Plural + ti.Nix = nixOf(row.Nix, elem.Nix) + + ti.Env = "space-separated or JSON array" + if e := t.Elem(); e.Kind() == reflect.Struct && !reflect.PointerTo(e).Implements(textUnmarshalerType) { + ti.Env = "JSON array" + } + case t.Kind() == reflect.Map: + elem, err := typeOf(t.Elem()) + if err != nil || t.Key().Kind() != reflect.String { + return typeInfo{}, fmt.Errorf("%w %s", errUnknownType, t) + } + + // describeLeaf names the key. + ti.Label = "map of `` → " + elem.Label + ti.Nix = nixOf(row.Nix, elem.Nix) + ti.Env = "JSON object" + } + + return ti, nil +} + +func leafTypeOf(t reflect.Type) (leafType, bool) { + for _, match := range []func(leafType) bool{ + func(l leafType) bool { return l.Type == t }, + func(l leafType) bool { + return l.Type != nil && l.Type.Kind() == reflect.Interface && t.Implements(l.Type) + }, + func(l leafType) bool { return slices.Contains(l.Kinds, t.Kind()) }, + } { + if i := slices.IndexFunc(leafTypes, match); i >= 0 { + return leafTypes[i], true + } + } + + return leafType{}, false +} + +// nixOf applies the list or map constructor to elem, "" when elem is a +// type a generator builds. +func nixOf(constructor, elem string) string { + switch { + case elem == "": + return "" + case strings.Contains(elem, " "): + return constructor + " (" + elem + ")" + default: + return constructor + " " + elem + } +} + +// requiredKeys are the leaves Validate(Default()) names first in a +// reason, with an empty default, each with the condition of "is required +// when " or "" for always. A reason naming no leaf (the prefix +// rule) is the docs' to explain. +func requiredKeys() (map[string]string, error) { + d := Default() + + empty := map[string]bool{} + + for _, f := range types.ConfigFields(&d) { + v := f.Value + empty[f.Path] = v.IsZero() || ((v.Kind() == reflect.Slice || v.Kind() == reflect.Map) && v.Len() == 0) + } + + required := map[string]string{} + + for _, e := range types.ConfigErrors(Validate(&d)) { + key, rest, _ := strings.Cut(e.Reason, " ") + + isEmpty, leaf := empty[key] + if !leaf { + continue + } + + if !isEmpty { + return nil, fmt.Errorf("%w: %s", errInvalidDefault, e.Reason) + } + + _, when, _ := strings.Cut(rest, "is required when ") + + words := strings.Fields(when) + for i, w := range words { + if _, ok := empty[w]; ok { + words[i] = "`" + w + "`" + } + } + + required[key] = strings.Join(words, " ") + } + + return required, nil +} + +// envValue is v as a variable writes it: a scalar as text, a list or map +// as JSON, keys sorted. Every list is JSON: separated by spaces, an empty +// element is lost and one starting with "[" reads as JSON. +func envValue(v any) string { + switch reflect.ValueOf(v).Kind() { //nolint:exhaustive // scalars print as text + case reflect.Slice, reflect.Map: + var b bytes.Buffer + + enc := json.NewEncoder(&b) + enc.SetEscapeHTML(false) + + err := enc.Encode(v) + if err == nil { + return strings.TrimSuffix(b.String(), "\n") + } + } + + return fmt.Sprint(v) +} + +// nest is v at the dotted path, in nested maps as a file holds it. +func nest(path string, v any) map[string]any { + m := map[string]any{} + setPath(m, path, v) + + return m +} diff --git a/hscontrol/config/schema_test.go b/hscontrol/config/schema_test.go new file mode 100644 index 000000000..22fcd71ab --- /dev/null +++ b/hscontrol/config/schema_test.go @@ -0,0 +1,357 @@ +package config + +import ( + "encoding/json" + "reflect" + "slices" + "strings" + "testing" + "time" + + gocmp "github.com/google/go-cmp/cmp" + hsdns "github.com/juanfont/headscale/hscontrol/dns" + "github.com/juanfont/headscale/hscontrol/types" + "github.com/stretchr/testify/require" + "tailscale.com/tailcfg" +) + +func schemaByPath(t *testing.T) map[string]keyInfo { + t.Helper() + + keys, err := schema() + require.NoError(t, err) + + byPath := make(map[string]keyInfo, len(keys)) + for _, k := range keys { + byPath[k.Path] = k + } + + return byPath +} + +func jsonText(t *testing.T, v any) string { + t.Helper() + + b, err := json.Marshal(v) + require.NoError(t, err) + + return string(b) +} + +func TestSchemaTypes(t *testing.T) { + keys, err := schema() + require.NoError(t, err) + + d := Default() + + tree := types.ConfigTree(&d) + require.Len(t, keys, len(tree)) + + for i, k := range keys { + require.Equal(t, tree[i].Path, k.Path, "ConfigTree order") + + if k.Section { + require.Empty(t, k.Env, k.Path) + require.Equal(t, typeInfo{}, k.Type, k.Path) + require.Nil(t, k.Example, k.Path) + + continue + } + + require.Equal(t, configEnvName(k.Path), k.Env) + } + + byPath := schemaByPath(t) + + tests := []struct { + path string + want typeInfo + def any + mapKey string + defText string + }{ + {path: "node.expiry", want: typeInfo{Label: "duration", Anchor: "#type-duration", Nix: "t.duration"}, def: "0s"}, + {path: "unix_socket_permission", want: typeInfo{Label: "file mode", Anchor: "#type-file-mode", Nix: "t.fileMode"}, def: "0770"}, + { + path: "trusted_proxies", + want: typeInfo{Label: "list of prefixes", Anchor: "#type-list", Env: "space-separated or JSON array", Nix: "lib.types.listOf t.prefix"}, + def: []any{}, + }, + {path: "prefixes.v4", want: typeInfo{Label: "prefix", Anchor: "#type-prefix", Nix: "t.prefix"}, def: ""}, + { + path: "dns.nameservers.split", + want: typeInfo{Label: "map of `` → list of strings", Anchor: "#type-map", Env: "JSON object", Nix: "lib.types.attrsOf (lib.types.listOf lib.types.str)"}, + def: map[string]any{}, + mapKey: "domain", + }, + { + path: "oidc.extra_params", + want: typeInfo{Label: "map of `` → string", Anchor: "#type-map", Env: "JSON object", Nix: "lib.types.attrsOf lib.types.str"}, + def: map[string]any{}, + mapKey: "param", + }, + { + path: "dns.challenge.provider", + want: typeInfo{Label: "map of `` → value", Anchor: "#type-map", Env: "JSON object", Nix: "lib.types.attrsOf lib.types.anything"}, + def: map[string]any{}, + mapKey: "setting", + }, + {path: "database.postgres.pass", want: typeInfo{Label: "secret", Anchor: "#secrets", Nix: "t.secretFile"}, def: ""}, + {path: "database.type", want: typeInfo{Label: "enum", Anchor: "#type-enum", Enum: types.DatabaseType("").Allowed()}, def: ""}, + {path: "dns.extra_records", want: typeInfo{Label: "list of DNS records", Anchor: "#type-list", Env: "JSON array"}, def: []any{}}, + {path: "derp.urls", want: typeInfo{Label: "list of URLs", Anchor: "#type-list", Env: "space-separated or JSON array", Nix: "lib.types.listOf t.httpURL"}, def: []any{}}, + {path: "derp.server.region_id", want: typeInfo{Label: "integer", Anchor: "#type-integer", Nix: "lib.types.int"}, def: 0}, + {path: "listen_addr", want: typeInfo{Label: "listen address", Anchor: "#type-listen-address", Nix: "t.listenAddr"}, def: ""}, + {path: "dns.magic_dns", want: typeInfo{Label: "boolean", Anchor: "#type-boolean", Nix: "lib.types.bool"}, def: true}, + { + path: "tuning.batcher_workers", + want: typeInfo{Label: "integer", Anchor: "#type-integer", Nix: "lib.types.int"}, + def: 0, + defText: "three quarters of the CPU cores, at least one", + }, + } + for _, tt := range tests { + t.Run(tt.path, func(t *testing.T) { + k, ok := byPath[tt.path] + require.True(t, ok) + + if diff := gocmp.Diff(tt.want, k.Type); diff != "" { + t.Errorf("type (-want +got):\n%s", diff) + } + + require.Equal(t, tt.def, k.Default) + require.Equal(t, tt.mapKey, k.MapKey) + require.Equal(t, tt.defText, k.DefaultText) + }) + } + + for _, typ := range []reflect.Type{ + reflect.TypeFor[chan int](), + reflect.TypeFor[uint](), + reflect.TypeFor[map[int]string](), + reflect.TypeFor[[][]string](), + } { + _, err = typeOf(typ) + require.ErrorIs(t, err, errUnknownType, typ.String()) + } +} + +func TestLoadExample(t *testing.T) { + field := func(path string, typ reflect.Type, tag string) types.ConfigField { + return types.ConfigField{Path: path, Field: reflect.StructField{Type: typ, Tag: reflect.StructTag(tag)}} + } + duration := reflect.TypeFor[time.Duration]() + boolean := reflect.TypeFor[bool]() + + tests := []struct { + name string + field types.ConfigField + def any + want any + wantErr bool + }{ + {name: "duration", field: field("node.expiry", duration, `example:"\"5m\""`), def: "0s", want: "5m"}, + {name: "not as printed", field: field("node.expiry", duration, `example:"\"90d\""`), def: "0s", wantErr: true}, + {name: "does not load", field: field("node.expiry", duration, `example:"\"soon\""`), def: "0s", wantErr: true}, + {name: "not JSON", field: field("node.expiry", duration, `example:"5m"`), def: "0s", wantErr: true}, + {name: "untagged", field: field("node.expiry", duration, ""), def: "0s", wantErr: true}, + {name: "bool", field: field("taildrop.enabled", boolean, ""), def: true, want: false}, + {name: "tagged bool", field: field("taildrop.enabled", boolean, `example:"false"`), def: true, wantErr: true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := loadExample(tt.field, tt.def) + if tt.wantErr { + require.ErrorIs(t, err, errBadExample) + + return + } + + require.NoError(t, err) + require.Equal(t, tt.want, got) + }) + } +} + +func TestExamples(t *testing.T) { + keys, err := schema() + require.NoError(t, err) + + empty := writeConfig(t, "") + + yamlParser, err := configParser("config.yaml") + require.NoError(t, err) + + for _, k := range keys { + if k.Section { + continue + } + + t.Run(k.Path, func(t *testing.T) { + tag, tagged := k.Field.Tag.Lookup("example") + if k.Field.Type.Kind() == reflect.Bool { + require.False(t, tagged, "a bool's example is !default") + require.Equal(t, !k.Default.(bool), k.Example) //nolint:forcetypeassert // a bool's default is a bool + + return + } + + require.True(t, tagged, "every other leaf has an example tag") + require.True(t, json.Valid([]byte(tag)), "example is JSON: %s", tag) + + example := jsonText(t, k.Example) + require.JSONEq(t, tag, example) + require.NotEqual(t, jsonText(t, k.Default), example, "example equals the default") + + if k.Field.Type == reflect.TypeFor[types.Secret]() { + require.True(t, strings.HasPrefix(k.Example.(string), "file:/run/secrets/"), k.Example) //nolint:forcetypeassert // a secret is text + } + + if k.Open { + require.Len(t, k.Example, 2, "an open map's example has two entries") + } + + file, err := yamlParser.Marshal(nest(k.Path, k.Example)) + require.NoError(t, err) + + l, err := Load(writeConfig(t, string(file)), true, nil) + require.NoError(t, err) + require.Empty(t, l.Warnings) + require.JSONEq(t, example, jsonText(t, plainFields(l.Config, false)[k.Path]), "file layer:\n%s", file) + + env := k.Env + "=" + envValue(k.Example) + + l, err = Load(empty, true, []string{env}) + require.NoError(t, err) + require.Empty(t, l.Warnings) + require.JSONEq(t, example, jsonText(t, plainFields(l.Config, false)[k.Path]), "env layer: %s", env) + }) + } + + provider, _ := schemaByPath(t)["dns.challenge.provider"].Example.(map[string]any) + require.Contains(t, hsdns.ProviderNames(), provider["name"]) + + for name, v := range provider { + if s, ok := v.(string); ok && name != "name" { + require.True(t, strings.HasPrefix(s, "file:/run/secrets/"), "%s: %s", name, s) + } + } + + _, err = types.DNSChallengeConfig{ProviderSettings: provider}.NewProvider(func(_, value string) (string, error) { + return value, hsdns.ErrSecretUnread + }) + require.NoError(t, err) +} + +func TestRequiredKeys(t *testing.T) { + want := map[string]string{ + "server_url": "", + "noise.private_key_path": "", + "database.type": "", + "dns.base_domain": "`dns.magic_dns` is true", + "dns.nameservers.global": "`dns.override_local_dns` is true", + } + + got, err := requiredKeys() + require.NoError(t, err) + + if diff := gocmp.Diff(want, got); diff != "" { + t.Errorf("requiredKeys (-want +got):\n%s", diff) + } + + for path, k := range schemaByPath(t) { + when, required := want[path] + require.Equal(t, required, k.Required, path) + require.Equal(t, when, k.RequiredWhen, path) + } +} + +func TestEnvValue(t *testing.T) { + lists := []string{"oidc.scope", "dns.challenge.resolvers"} + + tests := []struct { + name string + v any + want string + keys []string + }{ + {name: "list", v: []any{"a", "b"}, want: `["a","b"]`, keys: lists}, + {name: "empty element", v: []any{""}, want: `[""]`, keys: lists}, + {name: "empty and name", v: []any{"", "example.com"}, want: `["","example.com"]`, keys: lists}, + {name: "leading bracket", v: []any{"[prompt]"}, want: `["[prompt]"]`, keys: lists}, + {name: "IPv6 with port", v: []any{"[2001:db8::53]:53"}, want: `["[2001:db8::53]:53"]`, keys: lists}, + {name: "empty list", v: []any{}, want: `[]`, keys: lists}, + {name: "map", v: map[string]any{"b": "y", "a": "x"}, want: `{"a":"x","b":"y"}`, keys: []string{"oidc.extra_params"}}, + {name: "bool", v: true, want: "true", keys: []string{"logtail.enabled"}}, + {name: "int", v: 5, want: "5", keys: []string{"tuning.batcher_workers"}}, + } + + empty := writeConfig(t, "") + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := envValue(tt.v) + require.Equal(t, tt.want, got) + + for _, key := range tt.keys { + l, err := Load(empty, true, []string{configEnvName(key) + "=" + got}) + require.NoError(t, err) + require.Empty(t, l.Warnings) + require.JSONEq(t, jsonText(t, tt.v), jsonText(t, plainFields(l.Config, false)[key]), key) + } + }) + } +} + +func TestDNSRecordFields(t *testing.T) { + var want []string + + for f := range reflect.TypeFor[tailcfg.DNSRecord]().Fields() { + if f.IsExported() { + want = append(want, strings.ToLower(f.Name)) + } + } + + got := make([]string, 0, len(dnsRecordFields)) + + for _, f := range dnsRecordFields { + require.NotEmpty(t, f.Doc, f.Name) + got = append(got, f.Name) + } + + require.Equal(t, want, got) +} + +func TestReplaces(t *testing.T) { + byPath := schemaByPath(t) + + tests := []struct { + path string + want []string + }{ + {path: "tls.cert_path", want: []string{"tls_cert_path"}}, + {path: "prefixes.v4", want: []string{"ip_prefixes"}}, + {path: "prefixes.v6", want: []string{"ip_prefixes"}}, + {path: "dns", want: []string{"dns_config"}}, + {path: "log.format", want: []string{"json_logs"}}, + {path: "noise.private_key_path", want: []string{"private_key_path", "noise_private_key_path"}}, + {path: "server_url"}, + } + for _, tt := range tests { + t.Run(tt.path, func(t *testing.T) { + var got []string + for _, r := range byPath[tt.path].Replaces { + got = append(got, r.Old) + } + + require.Equal(t, tt.want, got) + }) + } + + // Every removed key that names a replacement lands on one. + for _, r := range removedKeys { + for n := range strings.FieldsSeq(r.New) { + require.True(t, slices.ContainsFunc(byPath[n].Replaces, func(x removedKey) bool { return x == r }), "%s → %s", r.Old, n) + } + } +} diff --git a/hscontrol/types/config.go b/hscontrol/types/config.go index d8a558be3..d14ff7497 100644 --- a/hscontrol/types/config.go +++ b/hscontrol/types/config.go @@ -82,7 +82,7 @@ type EphemeralConfig struct { // InactivityTimeout is how long an ephemeral node can be offline // before it is automatically deleted. It must exceed 65s, the client // keepalive plus a margin. - InactivityTimeout time.Duration `koanf:"inactivity_timeout"` + InactivityTimeout time.Duration `example:"\"30m\"" koanf:"inactivity_timeout"` } // HARouteConfig contains configuration for HA subnet router health probing. @@ -94,12 +94,12 @@ type HARouteConfig struct { // ProbeInterval is how often HA subnet routers are probed; a positive // interval must be at least 2s. Zero or negative disables probing, // and with it the `node.routes.ha.probe_timeout` rules. - ProbeInterval time.Duration `koanf:"probe_interval"` + ProbeInterval time.Duration `example:"\"30s\"" koanf:"probe_interval"` // ProbeTimeout is the maximum time to wait for a probe response // before declaring a node unhealthy; at least 1s and less than // `node.routes.ha.probe_interval`. - ProbeTimeout time.Duration `koanf:"probe_timeout"` + ProbeTimeout time.Duration `example:"\"3s\"" koanf:"probe_timeout"` } // RouteConfig contains configuration for route behaviour. @@ -117,7 +117,7 @@ type PreAuthKeysConfig struct { // v2 API's DELETE) is kept retrievable before the background collector // hard-deletes it. Keys still backing a node are kept until the node is // deleted. A zero or negative duration disables the collector. - RevokedRetention time.Duration `koanf:"revoked_retention"` + RevokedRetention time.Duration `example:"\"720h\"" koanf:"revoked_retention"` } // NodeConfig contains configuration for node lifecycle and expiry. @@ -127,7 +127,7 @@ type NodeConfig struct { // expiry the client asks for, `oidc.use_expiry_from_token` and an // admin's `headscale nodes expire` still apply. Tagged nodes never get // this default. Zero or negative disables the default. - Expiry time.Duration `koanf:"expiry"` + Expiry time.Duration `example:"\"2160h\"" koanf:"expiry"` // Ephemeral covers ephemeral nodes, which register with an ephemeral // auth key and are deleted once they have been offline for @@ -147,31 +147,31 @@ type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Confi // `https://` scheme, e.g. `https://headscale.example.com:443`. A // trailing slash is trimmed on load. Its host must not be // `dns.base_domain` or a name below it. - ServerURL string `koanf:"server_url"` + ServerURL string `example:"\"https://headscale.example.com\"" koanf:"server_url"` // Addr is the host:port the server listens on for clients, the API and // the web pages. It serves HTTPS when `tls.cert_path` or // `tls.acme.hostname` is set, plain HTTP otherwise. - Addr ListenAddr `koanf:"listen_addr"` + Addr ListenAddr `example:"\"0.0.0.0:8080\"" koanf:"listen_addr"` // MetricsAddr is the host:port serving `/metrics` and `/debug`; keep // it private. Empty disables this listener. - MetricsAddr ListenAddr `koanf:"metrics_listen_addr"` + MetricsAddr ListenAddr `example:"\"127.0.0.1:9090\"" koanf:"metrics_listen_addr"` // UnixSocket is where the server serves the API without // authentication, for the CLI on the same host. The CLI connects to it // when `cli.address` is empty. - UnixSocket string `koanf:"unix_socket"` + UnixSocket string `example:"\"/run/headscale/headscale.sock\"" koanf:"unix_socket"` // UnixSocketPermission is the file mode of `unix_socket`, in quoted // octal (`"0770"`): unquoted, YAML reads `0770` as the number 504. - UnixSocketPermission FileMode `koanf:"unix_socket_permission"` + UnixSocketPermission FileMode `example:"\"0660\"" koanf:"unix_socket_permission"` // TrustedProxies are the CIDRs of reverse proxies whose // `True-Client-IP`, `X-Real-IP` and `X-Forwarded-For` headers are // honoured. Empty ignores those headers. Set without a proxy in front, // clients can spoof their source IP in logs and the v2 API. - TrustedProxies []netip.Prefix `koanf:"trusted_proxies"` + TrustedProxies []netip.Prefix `example:"[\"192.0.2.10/32\",\"2001:db8::10/128\"]" koanf:"trusted_proxies"` // DisableUpdateCheck skips the check for a newer headscale release // that commands make at start. @@ -267,7 +267,7 @@ type NoiseConfig struct { // PrivateKeyPath is the file holding the Noise private key, which // encrypts traffic between headscale and clients, relative to the // configuration file. A missing file is created with a new key. - PrivateKeyPath string `koanf:"private_key_path"` + PrivateKeyPath string `example:"\"/var/lib/headscale/noise_private.key\"" koanf:"private_key_path"` } // PrefixesConfig are the ranges node IPs are allocated from. At least one @@ -277,14 +277,14 @@ type NoiseConfig struct { type PrefixesConfig struct { // V4 is the IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no // IPv4 address. - V4 *netip.Prefix `koanf:"v4"` + V4 *netip.Prefix `example:"\"100.64.0.0/10\"" koanf:"v4"` // V6 is the IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes // no IPv6 address. - V6 *netip.Prefix `koanf:"v6"` + V6 *netip.Prefix `example:"\"fd7a:115c:a1e0::/48\"" koanf:"v6"` // Allocation is how a new node's addresses are picked. - Allocation IPAllocationStrategy `koanf:"allocation"` + Allocation IPAllocationStrategy `example:"\"random\"" koanf:"allocation"` } // liveDNS is the DNS state of a running server: the tailcfg form, whose @@ -307,7 +307,7 @@ type DNSConfig struct { // BaseDomain is the domain MagicDNS names live under, without a // trailing dot, e.g. `example.com`. The host of `server_url` must not // be this domain or a name below it: clients take the domain over. - BaseDomain string `koanf:"base_domain"` + BaseDomain string `example:"\"tailnet.example.com\"" koanf:"base_domain"` // OverrideLocalDNS makes clients use `dns.nameservers.global` instead // of their local DNS settings, which then requires at least one global @@ -320,18 +320,18 @@ type DNSConfig struct { // SearchDomains are DNS search domains sent to clients. With MagicDNS, // `dns.base_domain` comes first. - SearchDomains []string `koanf:"search_domains"` + SearchDomains []string `example:"[\"corp.example.com\",\"lab.example.net\"]" koanf:"search_domains"` // ExtraRecords are DNS records served to clients, each with a `name`, // `type` and `value`. Clients support `A` and `AAAA`. Mutually // exclusive with `dns.extra_records_path`. See // [Setting extra DNS records](https://headscale.net/stable/ref/dns/#setting-extra-dns-records). - ExtraRecords []tailcfg.DNSRecord `koanf:"extra_records"` + ExtraRecords []tailcfg.DNSRecord `example:"[{\"name\":\"grafana.tailnet.example.com\",\"type\":\"A\",\"value\":\"100.64.0.3\"},{\"name\":\"grafana.tailnet.example.com\",\"type\":\"AAAA\",\"value\":\"fd7a:115c:a1e0::3\"}]" koanf:"extra_records"` // ExtraRecordsPath is a file of extra records, reloaded when it // changes. The extension picks the format: `.json`, `.hujson`, `.yaml` // or `.yml`. Mutually exclusive with `dns.extra_records`. - ExtraRecordsPath string `koanf:"extra_records_path"` + ExtraRecordsPath string `example:"\"/var/lib/headscale/extra-records.json\"" koanf:"extra_records_path"` // Certificates lets nodes get TLS certificates for their MagicDNS // names with `tailscale cert`. The node runs ACME itself; headscale @@ -357,7 +357,7 @@ type CertificatesConfig struct { // Zone is the public DNS zone challenge records are written to, when // `dns.base_domain` sits below the zone apex. It must contain // `dns.base_domain`. Empty uses `dns.base_domain`. - Zone string `koanf:"zone"` + Zone string `example:"\"example.com\"" koanf:"zone"` } // CertificateZone is the zone challenge records are written to: @@ -371,13 +371,13 @@ func (d DNSConfig) CertificateZone() string { type DNSChallengeConfig struct { // PropagationTimeout is how long to wait for a challenge record to // show up on every authoritative nameserver. Zero skips the check. - PropagationTimeout time.Duration `koanf:"propagation_timeout"` + PropagationTimeout time.Duration `example:"\"5m\"" koanf:"propagation_timeout"` // Resolvers are the servers asked for the zone's nameservers, each an // IP or host with an optional port (53 if omitted). Empty uses the // default public resolvers. The system resolver is never used: on a // host running MagicDNS it answers for `dns.base_domain` itself. - Resolvers []string `koanf:"resolvers"` + Resolvers []string `example:"[\"9.9.9.9:53\",\"[2620:fe::fe]:53\"]" koanf:"resolvers"` // ProviderSettings is the DNS provider that writes challenge records: // `name` selects it, the other keys are its settings. Keys are @@ -389,7 +389,7 @@ type DNSChallengeConfig struct { // [DNS-01 challenge provider](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider) // to set a provider up, acme-dns included, and to set it from // environment variables. - ProviderSettings map[string]any `json:"-" koanf:"provider"` + ProviderSettings map[string]any `example:"{\"name\":\"cloudflare\",\"api_token\":\"file:/run/secrets/cloudflare\"}" json:"-" koanf:"provider" mapkey:"setting"` // Provider is a DNS provider set from Go, by an embedder or a test; it // cannot be set from a file. It wins over ProviderSettings. @@ -459,19 +459,19 @@ type Nameservers struct { // Global are the nameservers for names `dns.nameservers.split` does not // cover: IP addresses, or DNS-over-HTTPS URLs such as // `https://dns.nextdns.io/`. - Global []string `koanf:"global"` + Global []string `example:"[\"9.9.9.9\",\"149.112.112.112\",\"2620:fe::fe\",\"2620:fe::9\"]" koanf:"global"` // Split maps a domain to the nameservers that answer for it (split // DNS). Domains are lowercased on load; two that differ only in case // are an error. - Split map[string][]string `koanf:"split"` + Split map[string][]string `example:"{\"corp.example.com\":[\"192.0.2.53\"],\"lab.example.net\":[\"198.51.100.53\",\"2001:db8::53\"]}" koanf:"split" mapkey:"domain"` } // SqliteConfig configures the SQLite database. type SqliteConfig struct { // Path is the database file, relative to the configuration file; // `:memory:` keeps the database in memory. - Path string `koanf:"path"` + Path string `example:"\"/var/lib/headscale/db.sqlite\"" koanf:"path"` // WriteAheadLog applies `database.sqlite.wal_autocheckpoint` and // compacts the database (`VACUUM`) on shutdown. SQLite runs in WAL @@ -482,7 +482,7 @@ type SqliteConfig struct { // WALAutoCheckPoint is the number of WAL frames after which the WAL // is checkpointed automatically; zero disables automatic checkpoints. // Applied only when `database.sqlite.write_ahead_log` is true. - WALAutoCheckPoint int `koanf:"wal_autocheckpoint"` + WALAutoCheckPoint int `example:"2000" koanf:"wal_autocheckpoint"` } // PostgresConfig configures the PostgreSQL database, supported for legacy @@ -490,39 +490,39 @@ type SqliteConfig struct { type PostgresConfig struct { // Host is the server's host name or IP, or the directory of its Unix // socket (a path starting with `/`). - Host string `koanf:"host"` + Host string `example:"\"db.example.com\"" koanf:"host"` // Port is the server's port or, with a Unix socket directory in // `database.postgres.host`, the port in the socket's file name. Zero // uses the driver's default. - Port int `koanf:"port"` + Port int `example:"5432" koanf:"port"` // Name is the database name. - Name string `koanf:"name"` + Name string `example:"\"headscale\"" koanf:"name"` // User is the user to connect as. - User string `koanf:"user"` + User string `example:"\"headscale\"" koanf:"user"` // Pass is the password, or `file:` to read it from a file, read // only when `database.type` is `postgres`. `headscale generate config // --running` and `/debug/config` show a literal password as // `` and a `file:` reference as written. - Pass Secret `json:"-" koanf:"pass"` + Pass Secret `example:"\"file:/run/secrets/postgres_password\"" json:"-" koanf:"pass"` // Ssl is the TLS mode: `true` keeps the driver's default `sslmode`, // `false` disables TLS, any other value is passed as `sslmode` // (`require`, `verify-full`, ...). - Ssl string `koanf:"ssl"` + Ssl string `example:"\"verify-full\"" koanf:"ssl"` // MaxOpenConnections caps open connections to the database. - MaxOpenConnections int `koanf:"max_open_conns"` + MaxOpenConnections int `example:"20" koanf:"max_open_conns"` // MaxIdleConnections caps idle connections kept in the pool. - MaxIdleConnections int `koanf:"max_idle_conns"` + MaxIdleConnections int `example:"5" koanf:"max_idle_conns"` // ConnMaxIdleTimeSecs is how long, in seconds, a connection may stay // idle before it is closed. - ConnMaxIdleTimeSecs int `koanf:"conn_max_idle_time_secs"` + ConnMaxIdleTimeSecs int `example:"600" koanf:"conn_max_idle_time_secs"` } // DSN returns the connection string for this configuration as a @@ -585,7 +585,7 @@ func (cfg PostgresConfig) DSN() string { type GormConfig struct { // SlowThreshold is the query time, in milliseconds, above which a // query is logged as a warning. Zero disables the warning. - SlowThreshold int `koanf:"slow_threshold"` + SlowThreshold int `example:"1000" koanf:"slow_threshold"` // SkipErrRecordNotFound logs a query that finds no record as an // ordinary query, not as an error. @@ -599,7 +599,7 @@ type GormConfig struct { type DatabaseConfig struct { // Type is the database backend. SQLite is recommended; PostgreSQL is // supported for legacy deployments only. - Type DatabaseType `koanf:"type"` + Type DatabaseType `example:"\"sqlite\"" koanf:"type"` // Debug turns on query logging: ordinary queries at log level debug, // shown only when `log.level` is `debug` or `trace`, slow ones at warn @@ -630,11 +630,11 @@ func (d DatabaseConfig) IsSQLite() bool { type TLSConfig struct { // CertPath is the PEM certificate file, relative to the configuration // file. Setting it turns TLS on. - CertPath string `koanf:"cert_path"` + CertPath string `example:"\"/etc/headscale/tls/cert.pem\"" koanf:"cert_path"` // KeyPath is the PEM private key file of `tls.cert_path`, relative to // the configuration file. - KeyPath string `koanf:"key_path"` + KeyPath string `example:"\"/etc/headscale/tls/key.pem\"" koanf:"key_path"` // ACME gets the certificate from an ACME CA such as Let's Encrypt, // and renews it. Setting `tls.acme.hostname` turns it on. @@ -645,26 +645,26 @@ type TLSConfig struct { type ACMEConfig struct { // Hostname is the domain to request a certificate for. Setting it // turns ACME on. - Hostname string `koanf:"hostname"` + Hostname string `example:"\"headscale.example.com\"" koanf:"hostname"` // ChallengeType is how the CA verifies that headscale controls // `tls.acme.hostname`. - ChallengeType ACMEChallenge `koanf:"challenge_type"` + ChallengeType ACMEChallenge `example:"\"TLS-ALPN-01\"" koanf:"challenge_type"` // HTTPListen is the host:port serving HTTP-01 challenges; the port // may be a name, as in `:http` for port 80. Other requests to it are // redirected to `server_url`. - HTTPListen ListenAddr `koanf:"http_listen"` + HTTPListen ListenAddr `example:"\"0.0.0.0:80\"" koanf:"http_listen"` // URL is the CA's ACME directory. Empty uses Let's Encrypt. - URL HTTPURL `koanf:"url"` + URL HTTPURL `example:"\"https://acme-staging-v02.api.letsencrypt.org/directory\"" koanf:"url"` // Email is the contact address registered with the CA. - Email string `koanf:"email"` + Email string `example:"\"admin@example.com\"" koanf:"email"` // CacheDir is where certificates and ACME account data are stored, // relative to the configuration file. - CacheDir string `koanf:"cache_dir"` + CacheDir string `example:"\"/var/cache/headscale/acme\"" koanf:"cache_dir"` } // PKCEConfig configures PKCE (RFC 7636), which protects the OIDC @@ -675,7 +675,7 @@ type PKCEConfig struct { // Method is how the code challenge is derived from the verifier. The // verifier is sent as is in the token exchange. - Method PKCEMethod `koanf:"method"` + Method PKCEMethod `example:"\"plain\"" koanf:"method"` } // OIDCConfig configures login through an OpenID Connect provider. @@ -685,37 +685,37 @@ type OIDCConfig struct { OnlyStartIfOIDCIsAvailable bool `koanf:"only_start_if_oidc_is_available"` // Issuer is the provider's issuer URL. Setting it turns OIDC on. - Issuer HTTPURL `koanf:"issuer"` + Issuer HTTPURL `example:"\"https://idp.example.com/realms/headscale\"" koanf:"issuer"` // ClientID is the client ID from the provider; required when // `oidc.issuer` is set. - ClientID string `koanf:"client_id"` + ClientID string `example:"\"headscale\"" koanf:"client_id"` // ClientSecret is the client secret from the provider, or // `file:` to read it from a file; required when `oidc.issuer` is // set. `headscale generate config --running` and `/debug/config` show a // literal secret as `` and a `file:` reference as written. - ClientSecret Secret `json:"-" koanf:"client_secret"` + ClientSecret Secret `example:"\"file:/run/secrets/oidc_client_secret\"" json:"-" koanf:"client_secret"` // Scope are the scopes requested; include `openid`. - Scope []string `koanf:"scope"` + Scope []string `example:"[\"openid\",\"profile\",\"email\",\"groups\"]" koanf:"scope"` // ExtraParams are sent as is to the provider's authorization endpoint, // e.g. `domain_hint`; names keep their case. - ExtraParams map[string]string `koanf:"extra_params"` + ExtraParams map[string]string `example:"{\"domain_hint\":\"example.com\",\"prompt\":\"select_account\"}" koanf:"extra_params" mapkey:"param"` // AllowedDomains admits only users whose email domain is listed. // Empty admits any domain. - AllowedDomains []string `koanf:"allowed_domains"` + AllowedDomains []string `example:"[\"example.com\"]" koanf:"allowed_domains"` // AllowedUsers admits only users whose email address is listed. Empty // admits any user. - AllowedUsers []string `koanf:"allowed_users"` + AllowedUsers []string `example:"[\"alice@example.com\"]" koanf:"allowed_users"` // AllowedGroups admits only members of at least one listed group, // from the provider's `groups` claim: UserInfo first, the ID token as // fallback. Empty admits any group. - AllowedGroups []string `koanf:"allowed_groups"` + AllowedGroups []string `example:"[\"headscale-users\"]" koanf:"allowed_groups"` // EmailVerifiedRequired trusts an email only when the provider marks // it verified: an unverified one fails `oidc.allowed_domains` and @@ -745,12 +745,12 @@ type DERPConfig struct { // URLs are DERP maps in JSON to fetch. One that fails to load is // logged and skipped; startup fails only when no region remains. - URLs []HTTPURL `koanf:"urls"` + URLs []HTTPURL `example:"[\"https://controlplane.tailscale.com/derpmap/default\"]" koanf:"urls"` // Paths are DERP map files. The extension picks the format: `.yaml` or // `.yml`, or Tailscale JSON as `.json` or `.hujson`, both accepting // comments and trailing commas. - Paths []string `koanf:"paths"` + Paths []string `example:"[\"/etc/headscale/derp.yaml\"]" koanf:"paths"` // AutoUpdate reloads `derp.urls` and `derp.paths` every // `derp.update_frequency`. @@ -758,7 +758,7 @@ type DERPConfig struct { // UpdateFrequency is how often `derp.auto_update_enabled` reloads the // DERP map. Zero disables reloading. - UpdateFrequency time.Duration `koanf:"update_frequency"` + UpdateFrequency time.Duration `example:"\"24h\"" koanf:"update_frequency"` // DERPMap is a DERP map set from Go, by an embedder or a test; it // cannot be set from a file. @@ -773,13 +773,13 @@ type DERPServerConfig struct { // RegionID is the embedded server's region ID. It replaces a region // with the same ID from the other sources. - RegionID tailcfg.DERPRegionID `koanf:"region_id"` + RegionID tailcfg.DERPRegionID `example:"999" koanf:"region_id"` // RegionCode is the region's short code, shown by Tailscale clients. - RegionCode string `koanf:"region_code"` + RegionCode string `example:"\"headscale\"" koanf:"region_code"` // RegionName is the region's name, shown by Tailscale clients. - RegionName string `koanf:"region_name"` + RegionName string `example:"\"Headscale Embedded DERP\"" koanf:"region_name"` // VerifyClients admits only nodes registered with this server. VerifyClients bool `koanf:"verify_clients"` @@ -787,21 +787,21 @@ type DERPServerConfig struct { // STUNAddr is the UDP host:port of the STUN server, which helps // clients with NAT traversal; required when `derp.server.enabled` is // true. - STUNAddr ListenAddr `koanf:"stun_listen_addr"` + STUNAddr ListenAddr `example:"\"0.0.0.0:3478\"" koanf:"stun_listen_addr"` // PrivateKeyPath is the file holding the DERP server's private key, // relative to the configuration file; required when // `derp.server.enabled` is true. A missing file is created with a new // key. It must differ from `noise.private_key_path`. - PrivateKeyPath string `koanf:"private_key_path"` + PrivateKeyPath string `example:"\"/var/lib/headscale/derp_server_private.key\"" koanf:"private_key_path"` // IPv4 is the server's public IPv4 address, published in the DERP map // so clients reach it without DNS. Empty publishes none. - IPv4 string `koanf:"ipv4"` + IPv4 string `example:"\"198.51.100.1\"" koanf:"ipv4"` // IPv6 is the server's public IPv6 address, published in the DERP map // so clients reach it without DNS. Empty publishes none. - IPv6 string `koanf:"ipv6"` + IPv6 string `example:"\"2001:db8::1\"" koanf:"ipv6"` // AutomaticallyAddEmbeddedDerpRegion adds the embedded server's region // to the DERP map. When it is false and `derp.server.enabled` is true, @@ -841,14 +841,14 @@ type AutoUpdateConfig struct { type CLIConfig struct { // Address is the remote server's host:port or URL; `https://` is // assumed without a scheme. Empty uses `unix_socket`. - Address string `koanf:"address"` + Address string `example:"\"headscale.example.com:443\"" koanf:"address"` // APIKey is the API key the CLI sends to `cli.address`, or // `file:` to read it from a file. Read only by the CLI. - APIKey Secret `json:"-" koanf:"api_key"` + APIKey Secret `example:"\"file:/run/secrets/headscale_api_key\"" json:"-" koanf:"api_key"` // Timeout bounds each CLI command's requests to the server. - Timeout time.Duration `koanf:"timeout"` + Timeout time.Duration `example:"\"30s\"" koanf:"timeout"` // Insecure skips TLS certificate verification of `cli.address`. Insecure bool `koanf:"insecure"` @@ -860,11 +860,11 @@ type PolicyConfig struct { // Path is the HuJSON policy file read when `policy.mode` is `file`, // relative to the configuration file. Empty starts without a policy, // which allows all traffic. - Path string `koanf:"path"` + Path string `example:"\"/etc/headscale/policy.hujson\"" koanf:"path"` // Mode is where the policy is kept: in the file `policy.path`, or in // the database, edited through the CLI or API. - Mode PolicyMode `koanf:"mode"` + Mode PolicyMode `example:"\"database\"" koanf:"mode"` } func (p *PolicyConfig) IsEmpty() bool { @@ -874,10 +874,10 @@ func (p *PolicyConfig) IsEmpty() bool { // LogConfig configures headscale's own log output. type LogConfig struct { // Level is the lowest level logged. - Level LogLevel `koanf:"level"` + Level LogLevel `example:"\"debug\"" koanf:"level"` // Format is how log lines are written. - Format LogFormat `koanf:"format"` + Format LogFormat `example:"\"json\"" koanf:"format"` } // Tuning contains advanced performance tuning parameters for Headscale. @@ -888,37 +888,37 @@ type LogConfig struct { type Tuning struct { // BatchChangeDelay is how often queued changes are sent to clients // as one update; must be positive. - BatchChangeDelay time.Duration `koanf:"batch_change_delay"` + BatchChangeDelay time.Duration `example:"\"500ms\"" koanf:"batch_change_delay"` // NodeMapSessionBufferedChanSize is how many map updates are queued // per connected client. - NodeMapSessionBufferedChanSize int `koanf:"node_mapsession_buffered_chan_size"` + NodeMapSessionBufferedChanSize int `example:"60" koanf:"node_mapsession_buffered_chan_size"` // BatcherWorkers is the number of workers building map updates for // connected clients. Zero picks the number from the CPU count. - BatcherWorkers int `koanf:"batcher_workers"` + BatcherWorkers int `defaulttext:"three quarters of the CPU cores, at least one" example:"8" koanf:"batcher_workers"` // RegisterCacheExpiration is how long a pending registration waits // to be completed. Zero uses the default. - RegisterCacheExpiration time.Duration `koanf:"register_cache_expiration"` + RegisterCacheExpiration time.Duration `example:"\"30m\"" koanf:"register_cache_expiration"` // RegisterCacheMaxEntries bounds pending registrations. At capacity, // new registrations are refused without evicting pending ones; SSH // checks have a small reserve beyond it. Zero uses the default. See // [Pending authentication limits](https://headscale.net/stable/ref/registration/#pending-authentication-limits). - RegisterCacheMaxEntries int `koanf:"register_cache_max_entries"` + RegisterCacheMaxEntries int `example:"4096" koanf:"register_cache_max_entries"` // NodeStoreBatchSize is how many node changes are batched before the // in-memory node state, peer relationships included, is rebuilt; must // be positive. Higher values save CPU on bulk changes but delay each // change until its batch is full or `tuning.node_store_batch_timeout` // passes. - NodeStoreBatchSize int `koanf:"node_store_batch_size"` + NodeStoreBatchSize int `example:"200" koanf:"node_store_batch_size"` // NodeStoreBatchTimeout is the longest a partial batch of node changes // waits before the rebuild; must be positive. Lower values answer // single changes faster at the cost of more rebuilds. - NodeStoreBatchTimeout time.Duration `koanf:"node_store_batch_timeout"` + NodeStoreBatchTimeout time.Duration `example:"\"1s\"" koanf:"node_store_batch_timeout"` } // BatcherWorkerCount is BatcherWorkers, or [DefaultBatcherWorkers] when unset.