mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-20 12:24:32 +09:00
nix, docs: regenerate NixOS options and the configuration reference
Updates #1926
This commit is contained in:
1 parent
cac78c856b
commit
c2023823b2
3 files changed
+119
-102
No files matched your search
Generated
+22
-20
@@ -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/<id>`.
|
||||
# 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.
|
||||
|
||||
Generated
+72
-53
@@ -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/<id>`.
|
||||
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/<id>`. Empty by default, so clients keep their own DNS: headscale points them at no resolver you did not list.
|
||||
|
||||
=== "YAML"
|
||||
|
||||
|
||||
Generated
+25
-29
@@ -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/<id>`.
|
||||
|
||||
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/<id>`. Empty by default, so clients keep their own DNS: headscale points them at no resolver you did not list.
|
||||
'';
|
||||
example = [
|
||||
"9.9.9.9"
|
||||
|
||||
Reference in new issue
Block a user