From afa16d056e937d208d3aa49342730860a47b3f63 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Sun, 8 Nov 2026 22:56:18 +0000 Subject: [PATCH] nix, docs: regenerate NixOS options and the configuration reference Read-only file options take Nix paths; key and state file options take only absolute paths outside the Nix store; DNS records pass unknown fields; db_password_file and dns.split appear as removed keys. Updates #1926 --- docs/ref/configuration-options.md | 4 +++ nix/options.generated.nix | 41 +++++++++++++++++++++++-------- 2 files changed, 35 insertions(+), 10 deletions(-) diff --git a/docs/ref/configuration-options.md b/docs/ref/configuration-options.md index bf92c80db..aab1bc346 100644 --- a/docs/ref/configuration-options.md +++ b/docs/ref/configuration-options.md @@ -1657,6 +1657,7 @@ The password, or `file:` to read it from a file, read only when [`database ``` Replaces `db_pass` ([removed](#db_pass)). +Replaces `db_password_file` ([removed](#db_password_file)). Replaces `database.postgres.password_file` ([removed](#database.postgres.password_file)). #### `database.postgres.ssl` { #database.postgres.ssl data-toc-label="ssl" } @@ -1984,6 +1985,7 @@ Maps a domain to the nameservers that answer for it (split DNS). Domains are low ``` Replaces `dns_config.restricted_nameservers` ([removed](#dns_config.restricted_nameservers)). +Replaces `dns.split` ([removed](#dns.split)). ### `dns.search_domains` { #dns.search_domains data-toc-label="search_domains" } @@ -3427,6 +3429,7 @@ one logs a warning, each saying what to do instead, as the table does. | `db_host` | 0.30 | use [`database.postgres.host`](#database.postgres.host) | | `db_name` | 0.30 | use [`database.postgres.name`](#database.postgres.name) | | `db_pass` | 0.30 | use [`database.postgres.pass`](#database.postgres.pass) | +| `db_password_file` | 0.30 | use [`database.postgres.pass`](#database.postgres.pass): `file:` | | `db_path` | 0.30 | use [`database.sqlite.path`](#database.sqlite.path) | | `db_port` | 0.30 | use [`database.postgres.port`](#database.postgres.port) | | `db_ssl` | 0.30 | use [`database.postgres.ssl`](#database.postgres.ssl) | @@ -3435,6 +3438,7 @@ one logs a warning, each saying what to do instead, as the table does. | `derp.server.stun.enabled` | 0.30 | remove it: headscale never read it; the embedded DERP server always serves STUN on [`derp.server.stun_listen_addr`](#derp.server.stun_listen_addr) | | `derp_map_path` | 0.30 | use [`derp.paths`](#derp.paths) | | `dns.challenge.provider._path` | 0.30 | use [`dns.challenge.provider.`](#dns.challenge.provider): `file:` | +| `dns.split` | 0.30 | use [`dns.nameservers.split`](#dns.nameservers.split) | | `dns.use_username_in_magic_dns` | 0.24 | remove `dns.use_username_in_magic_dns`; see the CHANGELOG for context | | `dns_config` | 0.30 | move every `dns_config.*` key to dns (nameservers to [`dns.nameservers.global`](#dns.nameservers.global), restricted_nameservers to [`dns.nameservers.split`](#dns.nameservers.split), domains to [`dns.search_domains`](#dns.search_domains)) | | `dns_config.base_domain` | 0.30 | use [`dns.base_domain`](#dns.base_domain) | diff --git a/nix/options.generated.nix b/nix/options.generated.nix index d73e4983d..6f7e2bfc1 100644 --- a/nix/options.generated.nix +++ b/nix/options.generated.nix @@ -47,10 +47,12 @@ in example = "127.0.0.1:9090"; }; unix_socket = lib.mkOption { - type = lib.types.str; + type = t.stateFile; default = "/var/run/headscale/headscale.sock"; description = '' 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. + + On NixOS, paths must be absolute and outside the Nix store. ''; example = "/run/headscale/headscale.sock"; }; @@ -83,11 +85,13 @@ in }; noise = { private_key_path = lib.mkOption { - type = lib.types.str; + type = t.stateFile; description = '' 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. Required. + + On NixOS, paths must be absolute and outside the Nix store. ''; example = "/var/lib/headscale/noise_private.key"; }; @@ -129,10 +133,12 @@ in }; policy = { path = lib.mkOption { - type = lib.types.str; + type = t.readFile; default = ""; description = '' The HuJSON policy file read when `policy.mode` is `file`, relative to the configuration file. Empty starts without a policy, which allows all traffic. + + On NixOS, paths must be absolute. ''; example = "/etc/headscale/policy.hujson"; }; @@ -303,10 +309,12 @@ in example = "0.0.0.0:3478"; }; private_key_path = lib.mkOption { - type = lib.types.str; + type = t.stateFile; default = ""; description = '' 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`. + + On NixOS, paths must be absolute and outside the Nix store. ''; example = "/var/lib/headscale/derp_server_private.key"; }; @@ -346,10 +354,12 @@ in ]; }; paths = lib.mkOption { - type = lib.types.listOf lib.types.str; + type = lib.types.listOf lib.types.path; default = [ ]; description = '' DERP map files. The extension picks the format: `.yaml` or `.yml`, or Tailscale JSON as `.json` or `.hujson`, both accepting comments and trailing commas. + + On NixOS, paths must be absolute. ''; example = [ "/etc/headscale/derp.yaml" @@ -429,10 +439,12 @@ in }; sqlite = { path = lib.mkOption { - type = lib.types.str; + type = t.stateFile; default = ""; description = '' The database file, relative to the configuration file; `:memory:` keeps the database in memory. + + On NixOS, paths must be absolute and outside the Nix store. ''; example = "/var/lib/headscale/db.sqlite"; }; @@ -604,6 +616,7 @@ in extra_records = lib.mkOption { type = lib.types.listOf ( lib.types.submodule { + freeformType = lib.types.attrsOf lib.types.anything; options = { name = lib.mkOption { type = lib.types.str; @@ -652,10 +665,12 @@ in ]; }; extra_records_path = lib.mkOption { - type = lib.types.str; + type = t.readFile; default = ""; description = '' 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`. + + On NixOS, paths must be absolute. ''; example = "/var/lib/headscale/extra-records.json"; }; @@ -717,18 +732,22 @@ in }; tls = { cert_path = lib.mkOption { - type = lib.types.str; + type = t.readFile; default = ""; description = '' The PEM certificate file, relative to the configuration file. Setting it turns TLS on. + + On NixOS, paths must be absolute. ''; example = "/etc/headscale/tls/cert.pem"; }; key_path = lib.mkOption { - type = lib.types.str; + type = t.stateFile; default = ""; description = '' The PEM private key file of `tls.cert_path`, relative to the configuration file. + + On NixOS, paths must be absolute and outside the Nix store. ''; example = "/etc/headscale/tls/key.pem"; }; @@ -785,10 +804,12 @@ in example = "admin@example.com"; }; cache_dir = lib.mkOption { - type = lib.types.str; + type = t.stateFile; default = "/var/lib/headscale/cache"; description = '' Where certificates and ACME account data are stored, relative to the configuration file. + + On NixOS, paths must be absolute and outside the Nix store. ''; example = "/var/cache/headscale/acme"; };