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;
};