mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-20 04:14:32 +09:00
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:
1 parent
a491228b7f
commit
e9a8c5f87a
4 files changed
+50
-55
No files matched your search
@@ -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).")
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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"}},
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user