From e9a8c5f87af08685d962b21671a7af52d0f0b774 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Tue, 17 Nov 2026 11:17:13 +0000 Subject: [PATCH] types, config: reword the option docs Shorter reference prose, review wording on the options and a gigahost provider example. Updates #1926 --- hscontrol/config/reference.go | 61 +++++++++++++----------------- hscontrol/config/reference_test.go | 7 ++-- hscontrol/config/schema.go | 2 +- hscontrol/types/config.go | 35 +++++++++-------- 4 files changed, 50 insertions(+), 55 deletions(-) diff --git a/hscontrol/config/reference.go b/hscontrol/config/reference.go index 52835ca57..9a0403bfe 100644 --- a/hscontrol/config/reference.go +++ b/hscontrol/config/reference.go @@ -19,48 +19,38 @@ const ( "!!! 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" + + "This reference contains all Headscale configuration options, in the order `headscale generate config` prints them,\n" + + "each with its type, default, environment variable and an example for a configuration file, the environment and NixOS.\n\n" + + "Removed keys 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" + + "Every key can also be set with an environment variable: `HEADSCALE_` followed by the key in capitals, e.g.\n" + + "`HEADSCALE_LOG_LEVEL` for `log.level`. Each key below names its variable.\n\n" + + "- An environment variable takes precedence over the configuration file, which takes precedence over the default.\n" + + "- An empty variable counts as unset and keeps the default.\n" + + "- A list is a JSON array or its values separated by spaces. A map is a JSON object and replaces the map in the\n" + + " configuration file.\n" + + "- An unknown or removed `HEADSCALE_` variable logs a warning, it does not stop Headscale.\n" + + "- The settings of a DNS provider have variables of their own, see\n" + + " [`dns.challenge.provider`](#dns.challenge.provider).\n\n" + + "To clear a key that has a default, set its variable to `\"\"`, or to `[]` for a list. Quote the value so the quotes reach\n" + + "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_`,\n" + - "e.g. `HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN`; see [`dns.challenge.provider`](#dns.challenge.provider).\n\n" + "```\n\n" referenceSecrets = "### Secrets { #secrets }\n\n" + - "A secret takes the value itself or `file:`, 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 `` and a `file:` reference as written.\n\n" + "A secret takes the value itself or `file:` to read it from a file, e.g.\n" + + "`file:${CREDENTIALS_DIRECTORY}/oidc_client_secret`.\n\n" + + "- Environment variables in the path are expanded.\n" + + "- Whitespace around the content of the file is trimmed, an empty file is an error.\n" + + "- `headscale generate config --running` and `/debug/config` show a literal secret as ``.\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" + + referenceNixSecret = "On NixOS, load the secret as a systemd credential to keep it out of the Nix store:\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" + @@ -254,11 +244,12 @@ func (r *reference) details(k keyInfo) { } r.table([]string{"Provider", "Settings"}, providers) - // The variable holds text, so an object setting cannot have one. + // A variable holds text, so an object setting takes a file there. r.paragraph("Each text setting can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_`, 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).") + "`HEADSCALE_DNS_CHALLENGE_PROVIDER_API_KEY`, 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 + "`, " + + "or in a JSON file that its own variable names with `file:`. " + + "See [Environment variables](dns.md#environment-variables).") } } diff --git a/hscontrol/config/reference_test.go b/hscontrol/config/reference_test.go index 6bedd397f..d124247de 100644 --- a/hscontrol/config/reference_test.go +++ b/hscontrol/config/reference_test.go @@ -210,10 +210,11 @@ func TestReferenceKeys(t *testing.T) { "| Provider ", "| `cloudflare` ", "Each text setting can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_`", - "An object setting, such as the `config` of `acmedns`, goes inside the JSON object of `HEADSCALE_DNS_CHALLENGE_PROVIDER`", + "An object setting, such as the `config` of `acmedns`, goes inside the JSON object of `HEADSCALE_DNS_CHALLENGE_PROVIDER`, " + + "or in a JSON file that its own variable names with `file:`.", "(dns.md#environment-variables)", - "api_token = \"file:\\${CREDENTIALS_DIRECTORY}/dns_challenge_provider_api_token\";", - "LoadCredential = [ \"dns_challenge_provider_api_token:/run/secrets/cloudflare\" ];", + "api_key = \"file:\\${CREDENTIALS_DIRECTORY}/dns_challenge_provider_api_key\";", + "LoadCredential = [ \"dns_challenge_provider_api_key:/run/secrets/gigahost\" ];", }}, {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"}}, diff --git a/hscontrol/config/schema.go b/hscontrol/config/schema.go index d4ad53d4d..1116ea520 100644 --- a/hscontrol/config/schema.go +++ b/hscontrol/config/schema.go @@ -142,7 +142,7 @@ var leafTypes = []leafType{ { 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", + Sample: "`file:/run/secrets/gigahost`", Nix: "lib.types.anything", }, { Kinds: []reflect.Kind{reflect.Slice}, Label: "list", diff --git a/hscontrol/types/config.go b/hscontrol/types/config.go index b4cda6b28..92c34fd52 100644 --- a/hscontrol/types/config.go +++ b/hscontrol/types/config.go @@ -118,10 +118,10 @@ type RouteConfig struct { // PreAuthKeysConfig contains configuration for pre-auth key lifecycle. type PreAuthKeysConfig struct { - // RevokedRetention is how long a soft-revoked pre-auth key (revoked via the - // 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 is how long a revoked pre-auth key 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 `example:"\"720h\"" koanf:"revoked_retention"` } @@ -149,9 +149,10 @@ type NodeConfig struct { // except 0. type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Config value is redacted too // ServerURL is the URL clients connect to, with its `http://` or - // `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. + // `https://` scheme, e.g. `https://headscale.example.com:443`. A trailing + // slash is trimmed on load. The hostname cannot be the same as + // `dns.base_domain` or any sub-domain that would cause the Headscale + // instance to have a `server_url` inside the MagicDNS namespace. ServerURL string `example:"\"https://headscale.example.com\"" koanf:"server_url"` // Addr is the host:port the server listens on for clients, the API and @@ -173,10 +174,10 @@ type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Confi // octal (`"0770"`): unquoted, YAML reads `0770` as the number 504. 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 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 `ip:publicAddress` posture attribute. 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 @@ -281,12 +282,14 @@ type NoiseConfig struct { // or subsets of them: the client assumes them, and breaks in subtle ways // outside them. type PrefixesConfig struct { - // V4 is the IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no - // IPv4 address. + // V4 is the IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 + // address. Use a prefix inside `100.64.0.0/10`. A range outside it is not + // supported and logs a warning. V4 *netip.Prefix `example:"\"100.64.0.0/24\"" koanf:"v4"` - // V6 is the IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes - // no IPv6 address. + // V6 is the IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no + // IPv6 address. Use a prefix inside `fd7a:115c:a1e0::/48`. A range outside + // it is not supported and logs a warning. V6 *netip.Prefix `example:"\"fd7a:115c:a1e0::/64\"" koanf:"v6"` // Allocation is how a new node's addresses are picked. @@ -399,7 +402,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 `example:"{\"name\":\"cloudflare\",\"api_token\":\"file:/run/secrets/cloudflare\"}" json:"-" koanf:"provider" mapkey:"setting"` + ProviderSettings map[string]any `example:"{\"name\":\"gigahost\",\"api_key\":\"file:/run/secrets/gigahost\"}" 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.