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
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 15:02:16 +01:00
1 parent f0a4f6ca67
commit afa16d056e
2 files changed
+35 -10

No files matched your search

+4
View File
@@ -1657,6 +1657,7 @@ The password, or `file:<path>` 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.
| <span id="db_host"></span>`db_host` | 0.30 | use [`database.postgres.host`](#database.postgres.host) |
| <span id="db_name"></span>`db_name` | 0.30 | use [`database.postgres.name`](#database.postgres.name) |
| <span id="db_pass"></span>`db_pass` | 0.30 | use [`database.postgres.pass`](#database.postgres.pass) |
| <span id="db_password_file"></span>`db_password_file` | 0.30 | use [`database.postgres.pass`](#database.postgres.pass): `file:<path>` |
| <span id="db_path"></span>`db_path` | 0.30 | use [`database.sqlite.path`](#database.sqlite.path) |
| <span id="db_port"></span>`db_port` | 0.30 | use [`database.postgres.port`](#database.postgres.port) |
| <span id="db_ssl"></span>`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.
| <span id="derp.server.stun.enabled"></span>`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) |
| <span id="derp_map_path"></span>`derp_map_path` | 0.30 | use [`derp.paths`](#derp.paths) |
| <span id="dns.challenge.provider.setting_path"></span>`dns.challenge.provider.<setting>_path` | 0.30 | use [`dns.challenge.provider.<setting>`](#dns.challenge.provider): `file:<path>` |
| <span id="dns.split"></span>`dns.split` | 0.30 | use [`dns.nameservers.split`](#dns.nameservers.split) |
| <span id="dns.use_username_in_magic_dns"></span>`dns.use_username_in_magic_dns` | 0.24 | remove `dns.use_username_in_magic_dns`; see the CHANGELOG for context |
| <span id="dns_config"></span>`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)) |
| <span id="dns_config.base_domain"></span>`dns_config.base_domain` | 0.30 | use [`dns.base_domain`](#dns.base_domain) |
+31 -10
View File
@@ -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";
};