diff --git a/docs/ref/config-example.yaml b/docs/ref/config-example.yaml index e0e07c485..878d8eae7 100644 --- a/docs/ref/config-example.yaml +++ b/docs/ref/config-example.yaml @@ -9,8 +9,8 @@ server_url: "" # The host:port the server listens on for clients, the API and the web pages. It # serves HTTPS when `tls.cert_path` or `tls.acme.hostname` is set, plain HTTP -# otherwise. -listen_addr: "" +# otherwise. The default listens on every address, IPv4 and IPv6 alike. +listen_addr: 0.0.0.0:8080 # The host:port serving `/metrics` and `/debug`; keep it private. Empty disables # this listener. @@ -38,19 +38,18 @@ noise: # 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. Example: /var/lib/headscale/noise_private.key - private_key_path: "" + private_key_path: /var/lib/headscale/noise_private.key -# The IP ranges node addresses are allocated from. Set at least one of +# The IP ranges node addresses are allocated from. Keep at least one of # `prefixes.v4` and `prefixes.v6`. Use the Tailscale ranges, `100.64.0.0/10` and # `fd7a:115c:a1e0::/48`, or ranges inside them: the client assumes them, and # other ranges are unsupported. prefixes: # The IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 address. - v4: "" + v4: 100.64.0.0/10 # The IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no IPv6 # address. - v6: "" + v6: fd7a:115c:a1e0::/48 # How a new node's addresses are picked. # One of: `sequential`, `random`. allocation: sequential @@ -90,7 +89,7 @@ node: ephemeral: # How long an ephemeral node can be offline before it is automatically # deleted. It must exceed 65s, the client keepalive plus a margin. - inactivity_timeout: 2m + inactivity_timeout: 30m # Covers the routes nodes advertise. See # [Routes](https://headscale.net/stable/ref/routes/). routes: @@ -156,14 +155,17 @@ derp: # there yourself. automatically_add_embedded_derp_region: true # DERP maps in JSON to fetch. One that fails to load is logged and skipped; - # startup fails only when no region remains. - urls: [] + # startup fails only when no region remains. The default is Tailscale's map: + # headscale fetches it from Tailscale and clients relay through Tailscale's + # servers. `[]` keeps to your own. + urls: + - https://controlplane.tailscale.com/derpmap/default # DERP map files. The extension picks the format: `.yaml` or `.yml`, or # Tailscale JSON as `.json` or `.hujson`, both accepting comments and trailing # commas. paths: [] # Reloads `derp.urls` and `derp.paths` every `derp.update_frequency`. - auto_update_enabled: false + auto_update_enabled: true # How often `derp.auto_update_enabled` reloads the DERP map. Zero disables # reloading. update_frequency: 3h @@ -175,8 +177,7 @@ database: # The database backend. SQLite is recommended; PostgreSQL is supported for # legacy deployments only. # One of: `sqlite`, `sqlite3`, `postgres`. - # Required. Example: sqlite - type: "" + type: sqlite # Turns on query logging: ordinary queries at log level debug, shown only when # `log.level` is `debug` or `trace`, slow ones at warn and failed ones at # error. Off, no query is logged. `database.gorm` shapes the query log. See @@ -196,7 +197,7 @@ database: sqlite: # The database file, relative to the configuration file; `:memory:` keeps # the database in memory. - path: "" + path: /var/lib/headscale/db.sqlite # Applies `database.sqlite.wal_autocheckpoint` and compacts the database # (`VACUUM`) on shutdown. SQLite runs in WAL mode either way; false keeps # SQLite's default checkpoint of 1000 frames. @@ -243,19 +244,20 @@ dns: magic_dns: true # The domain MagicDNS names live under, without a trailing dot, e.g. # `example.com`. The host of `server_url` must not be this domain or a name - # below it: clients take the domain over. - # Required when `dns.magic_dns` is true. - base_domain: "" + # below it: clients take the domain over. The default is a private-use name, + # so `dns.certificates` needs a public domain you control. + base_domain: tailnet.internal # Makes clients use `dns.nameservers.global` instead of their local DNS - # settings, which then requires at least one global nameserver. False sends - # them only as fallback resolvers. + # settings; with no global nameserver there is nothing to override with, and + # clients keep their own. False sends them only as fallback resolvers. override_local_dns: true # The upstream DNS servers sent to clients. An entry that is neither an IP # address nor a URL is skipped with a warning. nameservers: # The nameservers for names `dns.nameservers.split` does not cover: IP # addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/`. - # Required when `dns.override_local_dns` is true. + # Empty by default, so clients keep their own DNS: headscale points them at + # no resolver you did not list. global: [] # Maps a domain to the nameservers that answer for it (split DNS). Domains # are lowercased on load; two that differ only in case are an error. diff --git a/docs/ref/configuration-options.md b/docs/ref/configuration-options.md index aab1bc346..d6d8deefd 100644 --- a/docs/ref/configuration-options.md +++ b/docs/ref/configuration-options.md @@ -35,7 +35,25 @@ finds its configuration, how to check it, and shows the full example. Every key can also be set with an environment variable: `HEADSCALE_` and the key's path in capitals, with `_` for `.`, e.g. `HEADSCALE_LOG_LEVEL` for `log.level`. Each key below names its variable. A variable wins over the -configuration file, which wins over the default; an empty variable counts as unset. +configuration file, which wins over the default. An empty variable, like a key written with no value in the +file, counts as unset and keeps the default. A variable set to `""` means what `""` means in the configuration +file: it clears a key with a default, as `prefixes.v6: ""` does, and is an error where the file's `""` is one. A +list also clears with `[]`. Quote the value so the quotes reach headscale: + +```shell +export HEADSCALE_PREFIXES_V6='""' +export HEADSCALE_DERP_URLS='[]' +``` + +```yaml title="docker-compose.yaml" +environment: + HEADSCALE_PREFIXES_V6: '""' + HEADSCALE_DERP_URLS: '[]' +``` + +An env file (a Compose `env_file`, a systemd `EnvironmentFile=`) and a systemd `Environment=` strip one level of +quotes, so `KEY=""` there arrives empty and keeps the default: write `KEY='""'` in an env file and +`Environment='KEY=""'` in a unit. A list is a JSON array or, unless its values are objects, its values separated by spaces. A map is a JSON object, which replaces the map in the configuration file instead of merging into it. The examples below write every list @@ -93,27 +111,27 @@ The URL clients connect to, with its `http://` or `https://` scheme, e.g. `https ## `listen_addr` { #listen_addr data-toc-label="listen_addr" } - **Type:** [listen address](#type-listen-address) -- **Default:** `""` +- **Default:** `0.0.0.0:8080` - **Env:** `HEADSCALE_LISTEN_ADDR` -The host:port the server listens on for clients, the API and the web pages. It serves HTTPS when [`tls.cert_path`](#tls.cert_path) or [`tls.acme.hostname`](#tls.acme.hostname) is set, plain HTTP otherwise. +The host:port the server listens on for clients, the API and the web pages. It serves HTTPS when [`tls.cert_path`](#tls.cert_path) or [`tls.acme.hostname`](#tls.acme.hostname) is set, plain HTTP otherwise. The default listens on every address, IPv4 and IPv6 alike. === "YAML" ```yaml - listen_addr: 0.0.0.0:8080 + listen_addr: 127.0.0.1:8080 ``` === "Environment" ```shell - export HEADSCALE_LISTEN_ADDR=0.0.0.0:8080 + export HEADSCALE_LISTEN_ADDR=127.0.0.1:8080 ``` === "NixOS" ```nix - services.headscale.settings.listen_addr = "0.0.0.0:8080"; + services.headscale.settings.listen_addr = "127.0.0.1:8080"; ``` ## `metrics_listen_addr` { #metrics_listen_addr data-toc-label="metrics_listen_addr" } @@ -259,13 +277,13 @@ The Noise protocol (TS2021) clients connect over. ```yaml noise: - private_key_path: "" + private_key_path: /var/lib/headscale/noise_private.key ``` ### `noise.private_key_path` { #noise.private_key_path data-toc-label="private_key_path" } - **Type:** [string](#type-string) -- **Required** +- **Default:** `/var/lib/headscale/noise_private.key` - **Env:** `HEADSCALE_NOISE_PRIVATE_KEY_PATH` 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. @@ -274,19 +292,19 @@ The file holding the Noise private key, which encrypts traffic between headscale ```yaml noise: - private_key_path: /var/lib/headscale/noise_private.key + private_key_path: /opt/headscale/noise_private.key ``` === "Environment" ```shell - export HEADSCALE_NOISE_PRIVATE_KEY_PATH=/var/lib/headscale/noise_private.key + export HEADSCALE_NOISE_PRIVATE_KEY_PATH=/opt/headscale/noise_private.key ``` === "NixOS" ```nix - services.headscale.settings.noise.private_key_path = "/var/lib/headscale/noise_private.key"; + services.headscale.settings.noise.private_key_path = "/opt/headscale/noise_private.key"; ``` Replaces `private_key_path` ([removed](#private_key_path)). @@ -294,21 +312,21 @@ Replaces `noise_private_key_path` ([removed](#noise_private_key_path)). ## `prefixes` { #prefixes data-toc-label="prefixes" } -The IP ranges node addresses are allocated from. Set at least one of [`prefixes.v4`](#prefixes.v4) and [`prefixes.v6`](#prefixes.v6). Use the Tailscale ranges, `100.64.0.0/10` and `fd7a:115c:a1e0::/48`, or ranges inside them: the client assumes them, and other ranges are unsupported. +The IP ranges node addresses are allocated from. Keep at least one of [`prefixes.v4`](#prefixes.v4) and [`prefixes.v6`](#prefixes.v6). Use the Tailscale ranges, `100.64.0.0/10` and `fd7a:115c:a1e0::/48`, or ranges inside them: the client assumes them, and other ranges are unsupported. ??? example "All `prefixes` keys and defaults" ```yaml prefixes: - v4: "" - v6: "" + v4: 100.64.0.0/10 + v6: fd7a:115c:a1e0::/48 allocation: sequential ``` ### `prefixes.v4` { #prefixes.v4 data-toc-label="v4" } - **Type:** [prefix](#type-prefix) -- **Default:** `""` +- **Default:** `100.64.0.0/10` - **Env:** `HEADSCALE_PREFIXES_V4` The IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 address. @@ -317,19 +335,19 @@ The IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 address. ```yaml prefixes: - v4: 100.64.0.0/10 + v4: 100.64.0.0/24 ``` === "Environment" ```shell - export HEADSCALE_PREFIXES_V4=100.64.0.0/10 + export HEADSCALE_PREFIXES_V4=100.64.0.0/24 ``` === "NixOS" ```nix - services.headscale.settings.prefixes.v4 = "100.64.0.0/10"; + services.headscale.settings.prefixes.v4 = "100.64.0.0/24"; ``` Replaces `ip_prefixes` ([removed](#ip_prefixes)). @@ -337,7 +355,7 @@ Replaces `ip_prefixes` ([removed](#ip_prefixes)). ### `prefixes.v6` { #prefixes.v6 data-toc-label="v6" } - **Type:** [prefix](#type-prefix) -- **Default:** `""` +- **Default:** `fd7a:115c:a1e0::/48` - **Env:** `HEADSCALE_PREFIXES_V6` The IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no IPv6 address. @@ -346,19 +364,19 @@ The IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no IPv6 address. ```yaml prefixes: - v6: fd7a:115c:a1e0::/48 + v6: fd7a:115c:a1e0::/64 ``` === "Environment" ```shell - export HEADSCALE_PREFIXES_V6=fd7a:115c:a1e0::/48 + export HEADSCALE_PREFIXES_V6=fd7a:115c:a1e0::/64 ``` === "NixOS" ```nix - services.headscale.settings.prefixes.v6 = "fd7a:115c:a1e0::/48"; + services.headscale.settings.prefixes.v6 = "fd7a:115c:a1e0::/64"; ``` Replaces `ip_prefixes` ([removed](#ip_prefixes)). @@ -553,7 +571,7 @@ Covers node key expiry, ephemeral nodes and subnet routes. node: expiry: 0s ephemeral: - inactivity_timeout: 2m + inactivity_timeout: 30m routes: ha: probe_interval: 10s @@ -598,13 +616,13 @@ Covers ephemeral nodes, which register with an ephemeral auth key and are delete ```yaml node: ephemeral: - inactivity_timeout: 2m + inactivity_timeout: 30m ``` #### `node.ephemeral.inactivity_timeout` { #node.ephemeral.inactivity_timeout data-toc-label="inactivity_timeout" } - **Type:** [duration](#type-duration) -- **Default:** `2m` +- **Default:** `30m` - **Env:** `HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT` How long an ephemeral node can be offline before it is automatically deleted. It must exceed 65s, the client keepalive plus a margin. @@ -614,19 +632,19 @@ How long an ephemeral node can be offline before it is automatically deleted. It ```yaml node: ephemeral: - inactivity_timeout: 30m + inactivity_timeout: 1h ``` === "Environment" ```shell - export HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT=30m + export HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT=1h ``` === "NixOS" ```nix - services.headscale.settings.node.ephemeral.inactivity_timeout = "30m"; + services.headscale.settings.node.ephemeral.inactivity_timeout = "1h"; ``` Replaces `ephemeral_node_inactivity_timeout` ([removed](#ephemeral_node_inactivity_timeout)). @@ -774,9 +792,10 @@ The DERP map: the relay servers clients use when they cannot connect directly, f ipv4: "" ipv6: "" automatically_add_embedded_derp_region: true - urls: [] + urls: + - https://controlplane.tailscale.com/derpmap/default paths: [] - auto_update_enabled: false + auto_update_enabled: true update_frequency: 3h ``` @@ -1084,30 +1103,30 @@ Adds the embedded server's region to the DERP map. When it is false and [`derp.s ### `derp.urls` { #derp.urls data-toc-label="urls" } - **Type:** [list of URLs](#type-list) -- **Default:** `[]` +- **Default:** `['https://controlplane.tailscale.com/derpmap/default']` - **Env:** `HEADSCALE_DERP_URLS` ([space-separated or JSON array](#env)) -DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains. +DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains. The default is Tailscale's map: headscale fetches it from Tailscale and clients relay through Tailscale's servers. `[]` keeps to your own. === "YAML" ```yaml derp: urls: - - https://controlplane.tailscale.com/derpmap/default + - https://derp.example.com/derpmap.json ``` === "Environment" ```shell - export HEADSCALE_DERP_URLS='["https://controlplane.tailscale.com/derpmap/default"]' + export HEADSCALE_DERP_URLS='["https://derp.example.com/derpmap.json"]' ``` === "NixOS" ```nix services.headscale.settings.derp.urls = [ - "https://controlplane.tailscale.com/derpmap/default" + "https://derp.example.com/derpmap.json" ]; ``` @@ -1146,7 +1165,7 @@ Replaces `derp_map_path` ([removed](#derp_map_path)). ### `derp.auto_update_enabled` { #derp.auto_update_enabled data-toc-label="auto_update_enabled" } - **Type:** [boolean](#type-boolean) -- **Default:** `false` +- **Default:** `true` - **Env:** `HEADSCALE_DERP_AUTO_UPDATE_ENABLED` Reloads [`derp.urls`](#derp.urls) and [`derp.paths`](#derp.paths) every [`derp.update_frequency`](#derp.update_frequency). @@ -1155,19 +1174,19 @@ Reloads [`derp.urls`](#derp.urls) and [`derp.paths`](#derp.paths) every [`derp.u ```yaml derp: - auto_update_enabled: true + auto_update_enabled: false ``` === "Environment" ```shell - export HEADSCALE_DERP_AUTO_UPDATE_ENABLED=true + export HEADSCALE_DERP_AUTO_UPDATE_ENABLED=false ``` === "NixOS" ```nix - services.headscale.settings.derp.auto_update_enabled = true; + services.headscale.settings.derp.auto_update_enabled = false; ``` ### `derp.update_frequency` { #derp.update_frequency data-toc-label="update_frequency" } @@ -1205,14 +1224,14 @@ Where headscale stores nodes, users and keys. SQLite is recommended; PostgreSQL ```yaml database: - type: "" + type: sqlite debug: false gorm: slow_threshold: 0 skip_err_record_not_found: false parameterized_queries: false sqlite: - path: "" + path: /var/lib/headscale/db.sqlite write_ahead_log: true wal_autocheckpoint: 1000 postgres: @@ -1230,7 +1249,7 @@ Where headscale stores nodes, users and keys. SQLite is recommended; PostgreSQL ### `database.type` { #database.type data-toc-label="type" } - **Type:** [enum](#type-enum): `sqlite`, `sqlite3`, `postgres` -- **Required** +- **Default:** `sqlite` - **Env:** `HEADSCALE_DATABASE_TYPE` The database backend. SQLite is recommended; PostgreSQL is supported for legacy deployments only. @@ -1396,7 +1415,7 @@ SQLite, read only when [`database.type`](#database.type) is `sqlite` or `sqlite3 ```yaml database: sqlite: - path: "" + path: /var/lib/headscale/db.sqlite write_ahead_log: true wal_autocheckpoint: 1000 ``` @@ -1404,7 +1423,7 @@ SQLite, read only when [`database.type`](#database.type) is `sqlite` or `sqlite3 #### `database.sqlite.path` { #database.sqlite.path data-toc-label="path" } - **Type:** [string](#type-string) -- **Default:** `""` +- **Default:** `/var/lib/headscale/db.sqlite` - **Env:** `HEADSCALE_DATABASE_SQLITE_PATH` The database file, relative to the configuration file; `:memory:` keeps the database in memory. @@ -1414,19 +1433,19 @@ The database file, relative to the configuration file; `:memory:` keeps the data ```yaml database: sqlite: - path: /var/lib/headscale/db.sqlite + path: /opt/headscale/db.sqlite ``` === "Environment" ```shell - export HEADSCALE_DATABASE_SQLITE_PATH=/var/lib/headscale/db.sqlite + export HEADSCALE_DATABASE_SQLITE_PATH=/opt/headscale/db.sqlite ``` === "NixOS" ```nix - services.headscale.settings.database.sqlite.path = "/var/lib/headscale/db.sqlite"; + services.headscale.settings.database.sqlite.path = "/opt/headscale/db.sqlite"; ``` Replaces `db_path` ([removed](#db_path)). @@ -1785,7 +1804,7 @@ Replaces `dns_config` ([removed](#dns_config)). ```yaml dns: magic_dns: true - base_domain: "" + base_domain: tailnet.internal override_local_dns: true nameservers: global: [] @@ -1836,10 +1855,10 @@ Replaces `dns_config.magic_dns` ([removed](#dns_config.magic_dns)). ### `dns.base_domain` { #dns.base_domain data-toc-label="base_domain" } - **Type:** [string](#type-string) -- **Default:** `""`; required when [`dns.magic_dns`](#dns.magic_dns) is true +- **Default:** `tailnet.internal` - **Env:** `HEADSCALE_DNS_BASE_DOMAIN` -The domain MagicDNS names live under, without a trailing dot, e.g. `example.com`. The host of [`server_url`](#server_url) must not be this domain or a name below it: clients take the domain over. +The domain MagicDNS names live under, without a trailing dot, e.g. `example.com`. The host of [`server_url`](#server_url) must not be this domain or a name below it: clients take the domain over. The default is a private-use name, so [`dns.certificates`](#dns.certificates) needs a public domain you control. === "YAML" @@ -1868,7 +1887,7 @@ Replaces `dns_config.base_domain` ([removed](#dns_config.base_domain)). - **Default:** `true` - **Env:** `HEADSCALE_DNS_OVERRIDE_LOCAL_DNS` -Makes clients use [`dns.nameservers.global`](#dns.nameservers.global) instead of their local DNS settings, which then requires at least one global nameserver. False sends them only as fallback resolvers. +Makes clients use [`dns.nameservers.global`](#dns.nameservers.global) instead of their local DNS settings; with no global nameserver there is nothing to override with, and clients keep their own. False sends them only as fallback resolvers. === "YAML" @@ -1907,10 +1926,10 @@ The upstream DNS servers sent to clients. An entry that is neither an IP address #### `dns.nameservers.global` { #dns.nameservers.global data-toc-label="global" } - **Type:** [list of strings](#type-list) -- **Default:** `[]`; required when [`dns.override_local_dns`](#dns.override_local_dns) is true +- **Default:** `[]` - **Env:** `HEADSCALE_DNS_NAMESERVERS_GLOBAL` ([space-separated or JSON array](#env)) -The nameservers for names [`dns.nameservers.split`](#dns.nameservers.split) does not cover: IP addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/`. +The nameservers for names [`dns.nameservers.split`](#dns.nameservers.split) does not cover: IP addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/`. Empty by default, so clients keep their own DNS: headscale points them at no resolver you did not list. === "YAML" diff --git a/nix/options.generated.nix b/nix/options.generated.nix index 6f7e2bfc1..fbe90dbdc 100644 --- a/nix/options.generated.nix +++ b/nix/options.generated.nix @@ -32,11 +32,11 @@ in }; listen_addr = lib.mkOption { type = t.listenAddr; - default = ""; + default = "0.0.0.0:8080"; description = '' - The host:port the server listens on for clients, the API and the web pages. It serves HTTPS when `tls.cert_path` or `tls.acme.hostname` is set, plain HTTP otherwise. + The host:port the server listens on for clients, the API and the web pages. It serves HTTPS when `tls.cert_path` or `tls.acme.hostname` is set, plain HTTP otherwise. The default listens on every address, IPv4 and IPv6 alike. ''; - example = "0.0.0.0:8080"; + example = "127.0.0.1:8080"; }; metrics_listen_addr = lib.mkOption { type = t.listenAddr; @@ -86,32 +86,31 @@ in noise = { private_key_path = lib.mkOption { type = t.stateFile; + default = "/var/lib/headscale/noise_private.key"; 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"; + example = "/opt/headscale/noise_private.key"; }; }; prefixes = { v4 = lib.mkOption { type = t.prefix; - default = ""; + default = "100.64.0.0/10"; description = '' The IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 address. ''; - example = "100.64.0.0/10"; + example = "100.64.0.0/24"; }; v6 = lib.mkOption { type = t.prefix; - default = ""; + default = "fd7a:115c:a1e0::/48"; description = '' The IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no IPv6 address. ''; - example = "fd7a:115c:a1e0::/48"; + example = "fd7a:115c:a1e0::/64"; }; allocation = lib.mkOption { type = lib.types.enum [ @@ -220,11 +219,11 @@ in ephemeral = { inactivity_timeout = lib.mkOption { type = t.duration; - default = "2m"; + default = "30m"; description = '' How long an ephemeral node can be offline before it is automatically deleted. It must exceed 65s, the client keepalive plus a margin. ''; - example = "30m"; + example = "1h"; }; }; routes = { @@ -345,12 +344,14 @@ in }; urls = lib.mkOption { type = lib.types.listOf t.httpURL; - default = [ ]; + default = [ + "https://controlplane.tailscale.com/derpmap/default" + ]; description = '' - DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains. + DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains. The default is Tailscale's map: headscale fetches it from Tailscale and clients relay through Tailscale's servers. `[]` keeps to your own. ''; example = [ - "https://controlplane.tailscale.com/derpmap/default" + "https://derp.example.com/derpmap.json" ]; }; paths = lib.mkOption { @@ -367,11 +368,11 @@ in }; auto_update_enabled = lib.mkOption { type = lib.types.bool; - default = false; + default = true; description = '' Reloads `derp.urls` and `derp.paths` every `derp.update_frequency`. ''; - example = true; + example = false; }; update_frequency = lib.mkOption { type = t.duration; @@ -390,6 +391,7 @@ in "postgres" "" ]; + default = "sqlite"; description = '' The database backend. SQLite is recommended; PostgreSQL is supported for legacy deployments only. @@ -398,8 +400,6 @@ in - `sqlite`: SQLite, in the file `database.sqlite.path`. - `sqlite3`: The same as `sqlite`. - `postgres`: PostgreSQL, at `database.postgres.host`. - - Required. ''; example = "sqlite"; }; @@ -440,13 +440,13 @@ in sqlite = { path = lib.mkOption { type = t.stateFile; - default = ""; + default = "/var/lib/headscale/db.sqlite"; 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"; + example = "/opt/headscale/db.sqlite"; }; write_ahead_log = lib.mkOption { type = lib.types.bool; @@ -553,11 +553,9 @@ in }; base_domain = lib.mkOption { type = lib.types.str; - default = ""; + default = "tailnet.internal"; description = '' - The domain MagicDNS names live under, without a trailing dot, e.g. `example.com`. The host of `server_url` must not be this domain or a name below it: clients take the domain over. - - Required when `dns.magic_dns` is true. + The domain MagicDNS names live under, without a trailing dot, e.g. `example.com`. The host of `server_url` must not be this domain or a name below it: clients take the domain over. The default is a private-use name, so `dns.certificates` needs a public domain you control. ''; example = "tailnet.example.com"; }; @@ -565,7 +563,7 @@ in type = lib.types.bool; default = true; description = '' - Makes clients use `dns.nameservers.global` instead of their local DNS settings, which then requires at least one global nameserver. False sends them only as fallback resolvers. + Makes clients use `dns.nameservers.global` instead of their local DNS settings; with no global nameserver there is nothing to override with, and clients keep their own. False sends them only as fallback resolvers. ''; example = false; }; @@ -574,9 +572,7 @@ in type = lib.types.listOf lib.types.str; default = [ ]; description = '' - The nameservers for names `dns.nameservers.split` does not cover: IP addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/`. - - Required when `dns.override_local_dns` is true. + The nameservers for names `dns.nameservers.split` does not cover: IP addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/`. Empty by default, so clients keep their own DNS: headscale points them at no resolver you did not list. ''; example = [ "9.9.9.9"