types, config: reword the option docs

Shorter reference prose, review wording on the options and a
gigahost provider example.

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-17 11:17:13 +00:00
1 parent a491228b7f
commit e9a8c5f87a
4 files changed
+50 -55

No files matched your search

+26 -35
View File
@@ -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_<SETTING>`,\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:<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"
"A secret takes the value itself or `file:<path>` 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 `<redacted>`.\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_<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).")
"`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:<path>`. " +
"See [Environment variables](dns.md#environment-variables).")
}
}
+4 -3
View File
@@ -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_<SETTING>`",
"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:<path>`.",
"(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"}},
+1 -1
View File
@@ -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",
+19 -16
View File
@@ -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.