docs: regenerate configuration reference

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 16:42:44 +01:00
1 parent 2cf95feec6
commit 934a1f12b8
4 files changed
+29 -24

No files matched your search

+8 -3
View File
@@ -127,8 +127,9 @@ derp:
# Runs the embedded DERP server. DERP needs TLS, so `server_url` must be # Runs the embedded DERP server. DERP needs TLS, so `server_url` must be
# `https://`. # `https://`.
enabled: false enabled: false
# The embedded server's region ID. It replaces a region with the same ID # The embedded server's region ID; required and positive when
# from the other sources. # `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 region_id: 0
# The region's short code, shown by Tailscale clients. # The region's short code, shown by Tailscale clients.
region_code: "" region_code: ""
@@ -206,7 +207,11 @@ database:
# automatically; zero disables automatic checkpoints. Applied only when # automatically; zero disables automatic checkpoints. Applied only when
# `database.sqlite.write_ahead_log` is true. # `database.sqlite.write_ahead_log` is true.
wal_autocheckpoint: 1000 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: postgres:
# The server's host name or IP, or the directory of its Unix socket (a path # The server's host name or IP, or the directory of its Unix socket (a path
# starting with `/`). # starting with `/`).
+18 -18
View File
@@ -14,22 +14,22 @@ finds its configuration, how to check it, and shows the full example.
### Value types { #types } ### Value types { #types }
| Type | Format | Example | | Type | Format | Example |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| <span id="type-string"></span>string | Text. Quote it where YAML would read another type, as in `"0x1F"` or `"null"`. | `/var/lib/headscale/db.sqlite` | | <span id="type-string"></span>string | Text. Quote it where YAML would read another type, as in `"0x1F"` or `"null"`. | `/var/lib/headscale/db.sqlite` |
| <span id="type-boolean"></span>boolean | `true` or `false`. | `true` | | <span id="type-boolean"></span>boolean | `true` or `false`. | `true` |
| <span id="type-integer"></span>integer | A whole number. | `1024` | | <span id="type-integer"></span>integer | A whole number. | `1024` |
| <span id="type-duration"></span>duration | A number with a unit, `ms`, `s`, `m`, `h`, `d`, `w` or `y`, units combined largest first; `0` needs none. | `1h30m` | | <span id="type-duration"></span>duration | A number with a unit, `ms`, `s`, `m`, `h`, `d`, `w` or `y`, units combined largest first; `0` needs none. | `1h30m` |
| <span id="type-file-mode"></span>file mode | Octal permission bits, quoted. | `"0770"` | | <span id="type-file-mode"></span>file mode | Octal permission bits, quoted. | `"0770"` |
| <span id="type-listen-address"></span>listen address | `host:port`. An empty host listens on every address; the port may be `http` or `https`. | `0.0.0.0:8080` | | <span id="type-listen-address"></span>listen address | `host:port`. An empty host listens on every address; the port may be `http` or `https`. | `0.0.0.0:8080` |
| <span id="type-URL"></span>URL | An absolute `http://` or `https://` URL with a host. | `https://headscale.example.com` | | <span id="type-URL"></span>URL | An absolute `http://` or `https://` URL with a host. | `https://headscale.example.com` |
| <span id="type-prefix"></span>prefix | An IP range in CIDR notation. | `100.64.0.0/10` | | <span id="type-prefix"></span>prefix | An IP range in CIDR notation. | `100.64.0.0/10` |
| secret | Text, or `file:<path>` to read it from a file. | `file:/run/secrets/oidc_client_secret` | | secret | Text, or `file:<path>` to read it from a file. | `file:/run/secrets/oidc_client_secret` |
| <span id="type-enum"></span>enum | One of the values listed with the key. | `sqlite` | | <span id="type-enum"></span>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}` | | 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` | | value | Whatever the setting takes: text, a number, a boolean, a list or a map. | `file:/run/secrets/cloudflare` |
| <span id="type-list"></span>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]` | | <span id="type-list"></span>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]` |
| <span id="type-map"></span>map | Keys you choose, each with a value. A variable holds a JSON object. | `{corp.example.com: [192.0.2.53]}` | | <span id="type-map"></span>map | Keys you choose, each with a value. A variable holds a JSON object. | `{corp.example.com: [192.0.2.53]}` |
### Environment variables { #env } ### Environment variables { #env }
@@ -854,7 +854,7 @@ Runs the embedded DERP server. DERP needs TLS, so [`server_url`](#server_url) mu
- **Default:** `0` - **Default:** `0`
- **Env:** `HEADSCALE_DERP_SERVER_REGION_ID` - **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" === "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" } ### `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" ??? example "All `database.postgres` keys and defaults"
+2 -2
View File
@@ -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.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.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.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.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.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.", "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.", "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.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.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.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.", "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.", "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.",
+1 -1
View File
@@ -271,7 +271,7 @@ in
type = lib.types.int; type = lib.types.int;
default = 0; default = 0;
description = '' 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; example = 999;
}; };