From 934a1f12b86875422f4e5798f83cdf49fad8ec16 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Tue, 10 Nov 2026 05:03:23 +0000 Subject: [PATCH] docs: regenerate configuration reference Updates #1926 --- docs/ref/config-example.yaml | 11 ++++++-- docs/ref/configuration-options.md | 36 ++++++++++++------------ hscontrol/types/config_docs_generated.go | 4 +-- nix/options.generated.nix | 2 +- 4 files changed, 29 insertions(+), 24 deletions(-) diff --git a/docs/ref/config-example.yaml b/docs/ref/config-example.yaml index 878d8eae7..e61d0d76b 100644 --- a/docs/ref/config-example.yaml +++ b/docs/ref/config-example.yaml @@ -127,8 +127,9 @@ derp: # Runs the embedded DERP server. DERP needs TLS, so `server_url` must be # `https://`. enabled: false - # The embedded server's region ID. It replaces a region with the same ID - # from the other sources. + # The embedded server's region ID; required and positive when + # `derp.server.enabled` is true. Tailscale keeps 900-999 for your own + # regions. It replaces a region with the same ID from the other sources. region_id: 0 # The region's short code, shown by Tailscale clients. region_code: "" @@ -206,7 +207,11 @@ database: # automatically; zero disables automatic checkpoints. Applied only when # `database.sqlite.write_ahead_log` is true. wal_autocheckpoint: 1000 - # PostgreSQL, read only when `database.type` is `postgres`. + # PostgreSQL, read only when `database.type` is `postgres`. An empty `host`, + # `name`, `user`, `pass` or `ssl` leaves that setting to the driver, which + # reads the `PG*` environment variables and falls back to the defaults of + # libpq, PostgreSQL's client library: a local socket, the OS user, and TLS if + # the server offers it. postgres: # The server's host name or IP, or the directory of its Unix socket (a path # starting with `/`). diff --git a/docs/ref/configuration-options.md b/docs/ref/configuration-options.md index d6d8deefd..623566ec1 100644 --- a/docs/ref/configuration-options.md +++ b/docs/ref/configuration-options.md @@ -14,22 +14,22 @@ finds its configuration, how to check it, and shows the full example. ### Value types { #types } -| Type | Format | Example | -| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| string | Text. Quote it where YAML would read another type, as in `"0x1F"` or `"null"`. | `/var/lib/headscale/db.sqlite` | -| boolean | `true` or `false`. | `true` | -| integer | A whole number. | `1024` | -| duration | A number with a unit, `ms`, `s`, `m`, `h`, `d`, `w` or `y`, units combined largest first; `0` needs none. | `1h30m` | -| file mode | Octal permission bits, quoted. | `"0770"` | -| listen address | `host:port`. An empty host listens on every address; the port may be `http` or `https`. | `0.0.0.0:8080` | -| URL | An absolute `http://` or `https://` URL with a host. | `https://headscale.example.com` | -| prefix | An IP range in CIDR notation. | `100.64.0.0/10` | -| secret | Text, or `file:` to read it from a file. | `file:/run/secrets/oidc_client_secret` | -| enum | One of the values listed with the key. | `sqlite` | -| DNS record | An object with `name`, `type` and `value`. | `{name: grafana.example.com, type: A, value: 100.64.0.3}` | -| value | Whatever the setting takes: text, a number, a boolean, a list or a map. | `file:/run/secrets/cloudflare` | -| list | A list. A variable holds it as a JSON array or, unless its values are objects, separated by spaces. | `[9.9.9.9, 2620:fe::fe]` | -| map | Keys you choose, each with a value. A variable holds a JSON object. | `{corp.example.com: [192.0.2.53]}` | +| Type | Format | Example | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | +| string | Text. Quote it where YAML would read another type, as in `"0x1F"` or `"null"`. | `/var/lib/headscale/db.sqlite` | +| boolean | `true` or `false`. | `true` | +| integer | A whole number. | `1024` | +| duration | A number with a unit, `ms`, `s`, `m`, `h`, `d`, `w` or `y`, units combined largest first; `0` needs none. | `1h30m` | +| file mode | Octal permission bits, quoted. | `"0770"` | +| listen address | `host:port`. An empty host listens on every address; the port may be `http` or `https`. | `0.0.0.0:8080` | +| URL | An absolute `http://` or `https://` URL with a host. | `https://headscale.example.com` | +| prefix | An IP range in CIDR notation. | `100.64.0.0/10` | +| secret | Text, or `file:` to read it from a file. | `file:/run/secrets/oidc_client_secret` | +| enum | One of the values listed with the key. | `sqlite` | +| DNS record | An object with `name`, `type` and `value`. | `{name: grafana.example.com, type: A, value: 100.64.0.3}` | +| value | Whatever the setting takes: text, a number, a boolean, a list or a map. | `file:/run/secrets/cloudflare` | +| list | A list. A variable holds it as a JSON array or, unless its values are objects, separated by spaces. An empty item is an error. | `[9.9.9.9, 2620:fe::fe]` | +| map | Keys you choose, each with a value. A variable holds a JSON object. | `{corp.example.com: [192.0.2.53]}` | ### Environment variables { #env } @@ -854,7 +854,7 @@ Runs the embedded DERP server. DERP needs TLS, so [`server_url`](#server_url) mu - **Default:** `0` - **Env:** `HEADSCALE_DERP_SERVER_REGION_ID` -The embedded server's region ID. It replaces a region with the same ID from the other sources. +The embedded server's region ID; required and positive when [`derp.server.enabled`](#derp.server.enabled) is true. Tailscale keeps 900-999 for your own regions. It replaces a region with the same ID from the other sources. === "YAML" @@ -1508,7 +1508,7 @@ The number of WAL frames after which the WAL is checkpointed automatically; zero ### `database.postgres` { #database.postgres data-toc-label="postgres" } -PostgreSQL, read only when [`database.type`](#database.type) is `postgres`. +PostgreSQL, read only when [`database.type`](#database.type) is `postgres`. An empty `host`, `name`, `user`, `pass` or `ssl` leaves that setting to the driver, which reads the `PG*` environment variables and falls back to the defaults of libpq, PostgreSQL's client library: a local socket, the OS user, and TLS if the server offers it. ??? example "All `database.postgres` keys and defaults" diff --git a/hscontrol/types/config_docs_generated.go b/hscontrol/types/config_docs_generated.go index 865f47b53..84405ceb7 100644 --- a/hscontrol/types/config_docs_generated.go +++ b/hscontrol/types/config_docs_generated.go @@ -50,7 +50,7 @@ var configFieldDocs = map[string]string{ "DERPServerConfig.IPv6": "The server's public IPv6 address, published in the DERP map so clients reach it without DNS. Empty publishes none.", "DERPServerConfig.PrivateKeyPath": "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`.", "DERPServerConfig.RegionCode": "The region's short code, shown by Tailscale clients.", - "DERPServerConfig.RegionID": "The embedded server's region ID. It replaces a region with the same ID from the other sources.", + "DERPServerConfig.RegionID": "The embedded server's region ID; required and positive when `derp.server.enabled` is true. Tailscale keeps 900-999 for your own regions. It replaces a region with the same ID from the other sources.", "DERPServerConfig.RegionName": "The region's name, shown by Tailscale clients.", "DERPServerConfig.STUNAddr": "The UDP host:port of the STUN server, which helps clients with NAT traversal; required when `derp.server.enabled` is true.", "DERPServerConfig.VerifyClients": "Admits only nodes registered with this server.", @@ -68,7 +68,7 @@ var configFieldDocs = map[string]string{ "DNSConfig.SearchDomains": "DNS search domains sent to clients. With MagicDNS, `dns.base_domain` comes first.", "DatabaseConfig.Debug": "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 [Database logging](https://headscale.net/stable/ref/debug/#database-logging).", "DatabaseConfig.Gorm": "Query logging, applied only when `database.debug` is true.", - "DatabaseConfig.Postgres": "PostgreSQL, read only when `database.type` is `postgres`.", + "DatabaseConfig.Postgres": "PostgreSQL, read only when `database.type` is `postgres`. An empty `host`, `name`, `user`, `pass` or `ssl` leaves that setting to the driver, which reads the `PG*` environment variables and falls back to the defaults of libpq, PostgreSQL's client library: a local socket, the OS user, and TLS if the server offers it.", "DatabaseConfig.Sqlite": "SQLite, read only when `database.type` is `sqlite` or `sqlite3`.", "DatabaseConfig.Type": "The database backend. SQLite is recommended; PostgreSQL is supported for legacy deployments only.", "EphemeralConfig.InactivityTimeout": "How long an ephemeral node can be offline before it is automatically deleted. It must exceed 65s, the client keepalive plus a margin.", diff --git a/nix/options.generated.nix b/nix/options.generated.nix index fbe90dbdc..74d6a5e96 100644 --- a/nix/options.generated.nix +++ b/nix/options.generated.nix @@ -271,7 +271,7 @@ in type = lib.types.int; default = 0; description = '' - The embedded server's region ID. It replaces a region with the same ID from the other sources. + The embedded server's region ID; required and positive when `derp.server.enabled` is true. Tailscale keeps 900-999 for your own regions. It replaces a region with the same ID from the other sources. ''; example = 999; };