Files
headscale/hscontrol/config/reference.go
T
Kristoffer Dalby 2db863d5e6 config: clear a key from the environment with ""
A HEADSCALE_* value of "" means what key: "" means in a file, errors
included, so an env-only setup can clear a defaulted key. An empty
variable still counts as unset.

Updates #1926
2026-11-11 15:02:16 +01:00

558 lines
17 KiB
Go

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, like a key written with no value in the\n" +
"file, counts as unset and keeps the default. A variable set to `\"\"` means what `\"\"` means in the configuration\n" +
"file: it clears a key with a default, as `prefixes.v6: \"\"` does, and is an error where the file's `\"\"` is one. A\n" +
"list also clears with `[]`. Quote the value so the quotes reach headscale:\n\n" +
"```shell\n" +
"export HEADSCALE_PREFIXES_V6='\"\"'\n" +
"export HEADSCALE_DERP_URLS='[]'\n" +
"```\n\n" +
"```yaml title=\"docker-compose.yaml\"\n" +
"environment:\n" +
" HEADSCALE_PREFIXES_V6: '\"\"'\n" +
" HEADSCALE_DERP_URLS: '[]'\n" +
"```\n\n" +
"An env file (a Compose `env_file`, a systemd `EnvironmentFile=`) and a systemd `Environment=` strip one level of\n" +
"quotes, so `KEY=\"\"` there arrives empty and keeps the default: write `KEY='\"\"'` in an env file and\n" +
"`Environment='KEY=\"\"'` in a unit.\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, "'", `'\''`) + "'"
}