Read-only file options take Nix paths; key and state file options take only absolute paths outside the Nix store; DNS records pass unknown fields; db_password_file and dns.split appear as removed keys. Updates #1926
107 KiB
Generated
Configuration options
!!! note "Generated page"
This page is generated from the doc comments in `hscontrol/types/config.go` by
`go generate ./hscontrol/types/`. Edit the comments there, not this page.
Every key headscale reads, in the order headscale generate config prints them, with its type, default,
environment variable and an example for a configuration file, the environment and NixOS. Keys that no longer
work are listed under Removed keys. Configuration explains where headscale
finds its configuration, how to check it, and shows the full example.
Conventions
Value 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:<path> 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]} |
Environment variables
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.
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 and map as JSON.
A HEADSCALE_ variable that names no key logs a warning, and one for a removed key also says what to do instead.
Other software uses the same prefix, so neither stops headscale.
A DNS provider setting that takes text can also be set on its own as HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING>,
e.g. HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN; see dns.challenge.provider.
Secrets
A secret takes the value itself or file:<path>, which reads it from that file. Environment variables in the path
are expanded, as in file:${CREDENTIALS_DIRECTORY}/oidc_client_secret, and whitespace around the file's contents
is trimmed; an empty file is an error. Headscale reads the file only where the secret is used, and
headscale check config and headscale check all never read it. headscale generate config --running and
/debug/config show a literal secret as <redacted> and a file: reference as written.
The secrets are database.postgres.pass, oidc.client_secret, cli.api_key and every string setting of dns.challenge.provider.
On NixOS, keep a secret out of the Nix store: load it as a systemd credential and point the key at it.
services.headscale.settings.oidc.client_secret = "file:\${CREDENTIALS_DIRECTORY}/oidc_client_secret";
systemd.services.headscale.serviceConfig.LoadCredential = [ "oidc_client_secret:/run/secrets/oidc_client_secret" ];
server_url
- Type: string
- Required
- Env:
HEADSCALE_SERVER_URL
The URL clients connect to, with its http:// or https:// scheme, e.g. https://headscale.example.com:443. A trailing slash is trimmed on load. Its host must not be dns.base_domain or a name below it.
=== "YAML"
```yaml
server_url: https://headscale.example.com
```
=== "Environment"
```shell
export HEADSCALE_SERVER_URL=https://headscale.example.com
```
=== "NixOS"
```nix
services.headscale.settings.server_url = "https://headscale.example.com";
```
listen_addr
- Type: listen address
- Default:
"" - 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 or tls.acme.hostname is set, plain HTTP otherwise.
=== "YAML"
```yaml
listen_addr: 0.0.0.0:8080
```
=== "Environment"
```shell
export HEADSCALE_LISTEN_ADDR=0.0.0.0:8080
```
=== "NixOS"
```nix
services.headscale.settings.listen_addr = "0.0.0.0:8080";
```
metrics_listen_addr
- Type: listen address
- Default:
"" - Env:
HEADSCALE_METRICS_LISTEN_ADDR
The host:port serving /metrics and /debug; keep it private. Empty disables this listener.
=== "YAML"
```yaml
metrics_listen_addr: 127.0.0.1:9090
```
=== "Environment"
```shell
export HEADSCALE_METRICS_LISTEN_ADDR=127.0.0.1:9090
```
=== "NixOS"
```nix
services.headscale.settings.metrics_listen_addr = "127.0.0.1:9090";
```
unix_socket
- Type: string
- Default:
/var/run/headscale/headscale.sock - Env:
HEADSCALE_UNIX_SOCKET
Where the server serves the API without authentication, for the CLI on the same host. The CLI connects to it when cli.address is empty.
=== "YAML"
```yaml
unix_socket: /run/headscale/headscale.sock
```
=== "Environment"
```shell
export HEADSCALE_UNIX_SOCKET=/run/headscale/headscale.sock
```
=== "NixOS"
```nix
services.headscale.settings.unix_socket = "/run/headscale/headscale.sock";
```
unix_socket_permission
- Type: file mode
- Default:
"0770" - Env:
HEADSCALE_UNIX_SOCKET_PERMISSION
The file mode of unix_socket, in quoted octal ("0770"): unquoted, YAML reads 0770 as the number 504.
=== "YAML"
```yaml
unix_socket_permission: "0660"
```
=== "Environment"
```shell
export HEADSCALE_UNIX_SOCKET_PERMISSION=0660
```
=== "NixOS"
```nix
services.headscale.settings.unix_socket_permission = "0660";
```
trusted_proxies
- Type: list of prefixes
- Default:
[] - Env:
HEADSCALE_TRUSTED_PROXIES(space-separated or JSON array)
The CIDRs of reverse proxies whose True-Client-IP, X-Real-IP and X-Forwarded-For headers are honoured. Empty ignores those headers. Set without a proxy in front, clients can spoof their source IP in logs and the v2 API.
=== "YAML"
```yaml
trusted_proxies:
- 192.0.2.10/32
- 2001:db8::10/128
```
=== "Environment"
```shell
export HEADSCALE_TRUSTED_PROXIES='["192.0.2.10/32","2001:db8::10/128"]'
```
=== "NixOS"
```nix
services.headscale.settings.trusted_proxies = [
"192.0.2.10/32"
"2001:db8::10/128"
];
```
disable_check_updates
- Type: boolean
- Default:
false - Env:
HEADSCALE_DISABLE_CHECK_UPDATES
Skips the check for a newer headscale release that commands make at start.
=== "YAML"
```yaml
disable_check_updates: true
```
=== "Environment"
```shell
export HEADSCALE_DISABLE_CHECK_UPDATES=true
```
=== "NixOS"
```nix
services.headscale.settings.disable_check_updates = true;
```
noise
The Noise protocol (TS2021) clients connect over.
??? example "All noise keys and defaults"
```yaml
noise:
private_key_path: ""
```
noise.private_key_path
- Type: string
- Required
- 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.
=== "YAML"
```yaml
noise:
private_key_path: /var/lib/headscale/noise_private.key
```
=== "Environment"
```shell
export HEADSCALE_NOISE_PRIVATE_KEY_PATH=/var/lib/headscale/noise_private.key
```
=== "NixOS"
```nix
services.headscale.settings.noise.private_key_path = "/var/lib/headscale/noise_private.key";
```
Replaces private_key_path (removed).
Replaces noise_private_key_path (removed).
prefixes
The IP ranges node addresses are allocated from. Set 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.
??? example "All prefixes keys and defaults"
```yaml
prefixes:
v4: ""
v6: ""
allocation: sequential
```
prefixes.v4
- Type: prefix
- Default:
"" - Env:
HEADSCALE_PREFIXES_V4
The IPv4 range, e.g. 100.64.0.0/10. Empty gives nodes no IPv4 address.
=== "YAML"
```yaml
prefixes:
v4: 100.64.0.0/10
```
=== "Environment"
```shell
export HEADSCALE_PREFIXES_V4=100.64.0.0/10
```
=== "NixOS"
```nix
services.headscale.settings.prefixes.v4 = "100.64.0.0/10";
```
Replaces ip_prefixes (removed).
prefixes.v6
- Type: prefix
- Default:
"" - Env:
HEADSCALE_PREFIXES_V6
The IPv6 range, e.g. fd7a:115c:a1e0::/48. Empty gives nodes no IPv6 address.
=== "YAML"
```yaml
prefixes:
v6: fd7a:115c:a1e0::/48
```
=== "Environment"
```shell
export HEADSCALE_PREFIXES_V6=fd7a:115c:a1e0::/48
```
=== "NixOS"
```nix
services.headscale.settings.prefixes.v6 = "fd7a:115c:a1e0::/48";
```
Replaces ip_prefixes (removed).
prefixes.allocation
- Type: enum:
sequential,random - Default:
sequential - Env:
HEADSCALE_PREFIXES_ALLOCATION
How a new node's addresses are picked.
| Value | Meaning |
|---|---|
sequential |
Takes the next free address after the last one handed out, and wraps around to reuse freed addresses. |
random |
Picks a free address at random. |
=== "YAML"
```yaml
prefixes:
allocation: random
```
=== "Environment"
```shell
export HEADSCALE_PREFIXES_ALLOCATION=random
```
=== "NixOS"
```nix
services.headscale.settings.prefixes.allocation = "random";
```
policy
Where the access control policy is kept: in a file headscale reads, or in the database. See Policy.
??? example "All policy keys and defaults"
```yaml
policy:
path: ""
mode: file
```
policy.path
- Type: string
- Default:
"" - Env:
HEADSCALE_POLICY_PATH
The HuJSON policy file read when policy.mode is file, relative to the configuration file. Empty starts without a policy, which allows all traffic.
=== "YAML"
```yaml
policy:
path: /etc/headscale/policy.hujson
```
=== "Environment"
```shell
export HEADSCALE_POLICY_PATH=/etc/headscale/policy.hujson
```
=== "NixOS"
```nix
services.headscale.settings.policy.path = "/etc/headscale/policy.hujson";
```
Replaces acl_policy_path (removed).
policy.mode
- Type: enum:
file,database - Default:
file - Env:
HEADSCALE_POLICY_MODE
Where the policy is kept: in the file policy.path, or in the database, edited through the CLI or API.
| Value | Meaning |
|---|---|
file |
Reads the policy from policy.path. Send headscale SIGHUP to reload it after an edit. |
database |
Keeps the policy in the database, set with headscale policy set or the API. policy.path is not read. |
=== "YAML"
```yaml
policy:
mode: database
```
=== "Environment"
```shell
export HEADSCALE_POLICY_MODE=database
```
=== "NixOS"
```nix
services.headscale.settings.policy.mode = "database";
```
log
Headscale's own log output. See Debugging.
??? example "All log keys and defaults"
```yaml
log:
level: info
format: text
```
log.level
- Type: enum:
trace,debug,info,warn,error,fatal,panic,disabled - Default:
info - Env:
HEADSCALE_LOG_LEVEL
The lowest level logged.
=== "YAML"
```yaml
log:
level: debug
```
=== "Environment"
```shell
export HEADSCALE_LOG_LEVEL=debug
```
=== "NixOS"
```nix
services.headscale.settings.log.level = "debug";
```
Replaces log_level (removed).
log.format
- Type: enum:
text,json - Default:
text - Env:
HEADSCALE_LOG_FORMAT
How log lines are written.
| Value | Meaning |
|---|---|
text |
Writes human-readable lines, coloured when stderr is a terminal and NO_COLOR is unset. |
json |
Writes one JSON object per line, for log collectors. |
=== "YAML"
```yaml
log:
format: json
```
=== "Environment"
```shell
export HEADSCALE_LOG_FORMAT=json
```
=== "NixOS"
```nix
services.headscale.settings.log.format = "json";
```
Replaces json_logs (removed).
node
Covers node key expiry, ephemeral nodes and subnet routes.
??? example "All node keys and defaults"
```yaml
node:
expiry: 0s
ephemeral:
inactivity_timeout: 2m
routes:
ha:
probe_interval: 10s
probe_timeout: 5s
```
node.expiry
- Type: duration
- Default:
0s - Env:
HEADSCALE_NODE_EXPIRY
The key expiry given to a non-tagged node that registers without one, whatever the method (auth key, CLI, web, OIDC). An expiry the client asks for, oidc.use_expiry_from_token and an admin's headscale nodes expire still apply. Tagged nodes never get this default. Zero or negative disables the default.
=== "YAML"
```yaml
node:
expiry: 2160h
```
=== "Environment"
```shell
export HEADSCALE_NODE_EXPIRY=2160h
```
=== "NixOS"
```nix
services.headscale.settings.node.expiry = "2160h";
```
Replaces oidc.expiry (removed).
node.ephemeral
Covers ephemeral nodes, which register with an ephemeral auth key and are deleted once they have been offline for node.ephemeral.inactivity_timeout.
??? example "All node.ephemeral keys and defaults"
```yaml
node:
ephemeral:
inactivity_timeout: 2m
```
node.ephemeral.inactivity_timeout
- Type: duration
- Default:
2m - 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.
=== "YAML"
```yaml
node:
ephemeral:
inactivity_timeout: 30m
```
=== "Environment"
```shell
export HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT=30m
```
=== "NixOS"
```nix
services.headscale.settings.node.ephemeral.inactivity_timeout = "30m";
```
Replaces ephemeral_node_inactivity_timeout (removed).
node.routes
Covers the routes nodes advertise. See Routes.
??? example "All node.routes keys and defaults"
```yaml
node:
routes:
ha:
probe_interval: 10s
probe_timeout: 5s
```
node.routes.ha
Health probing of HA subnet routers. When two or more nodes advertise the same route, headscale pings each over Noise and moves the route away from one that does not answer in time. See High availability.
??? example "All node.routes.ha keys and defaults"
```yaml
node:
routes:
ha:
probe_interval: 10s
probe_timeout: 5s
```
node.routes.ha.probe_interval
- Type: duration
- Default:
10s - Env:
HEADSCALE_NODE_ROUTES_HA_PROBE_INTERVAL
How often HA subnet routers are probed; a positive interval must be at least 2s. Zero or negative disables probing, and with it the node.routes.ha.probe_timeout rules.
=== "YAML"
```yaml
node:
routes:
ha:
probe_interval: 30s
```
=== "Environment"
```shell
export HEADSCALE_NODE_ROUTES_HA_PROBE_INTERVAL=30s
```
=== "NixOS"
```nix
services.headscale.settings.node.routes.ha.probe_interval = "30s";
```
node.routes.ha.probe_timeout
- Type: duration
- Default:
5s - Env:
HEADSCALE_NODE_ROUTES_HA_PROBE_TIMEOUT
The maximum time to wait for a probe response before declaring a node unhealthy; at least 1s and less than node.routes.ha.probe_interval.
=== "YAML"
```yaml
node:
routes:
ha:
probe_timeout: 3s
```
=== "Environment"
```shell
export HEADSCALE_NODE_ROUTES_HA_PROBE_TIMEOUT=3s
```
=== "NixOS"
```nix
services.headscale.settings.node.routes.ha.probe_timeout = "3s";
```
preauth_keys
Covers the cleanup of revoked pre-auth keys. See Pre authenticated key.
??? example "All preauth_keys keys and defaults"
```yaml
preauth_keys:
revoked_retention: 168h
```
preauth_keys.revoked_retention
- Type: duration
- Default:
168h - Env:
HEADSCALE_PREAUTH_KEYS_REVOKED_RETENTION
How long a soft-revoked pre-auth key (revoked via the v2 API's DELETE) is kept retrievable before the background collector hard-deletes it. Keys still backing a node are kept until the node is deleted. A zero or negative duration disables the collector.
=== "YAML"
```yaml
preauth_keys:
revoked_retention: 720h
```
=== "Environment"
```shell
export HEADSCALE_PREAUTH_KEYS_REVOKED_RETENTION=720h
```
=== "NixOS"
```nix
services.headscale.settings.preauth_keys.revoked_retention = "720h";
```
derp
The DERP map: the relay servers clients use when they cannot connect directly, from derp.urls, derp.paths and the embedded server in derp.server. A region replaces an earlier one with the same ID. See DERP.
??? example "All derp keys and defaults"
```yaml
derp:
server:
enabled: false
region_id: 0
region_code: ""
region_name: ""
verify_clients: true
stun_listen_addr: ""
private_key_path: ""
ipv4: ""
ipv6: ""
automatically_add_embedded_derp_region: true
urls: []
paths: []
auto_update_enabled: false
update_frequency: 3h
```
derp.server
The embedded DERP server, a relay and STUN server run by headscale itself. See Enable embedded DERP.
??? example "All derp.server keys and defaults"
```yaml
derp:
server:
enabled: false
region_id: 0
region_code: ""
region_name: ""
verify_clients: true
stun_listen_addr: ""
private_key_path: ""
ipv4: ""
ipv6: ""
automatically_add_embedded_derp_region: true
```
derp.server.enabled
- Type: boolean
- Default:
false - Env:
HEADSCALE_DERP_SERVER_ENABLED
Runs the embedded DERP server. DERP needs TLS, so server_url must be https://.
=== "YAML"
```yaml
derp:
server:
enabled: true
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_ENABLED=true
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.enabled = true;
```
derp.server.region_id
- Type: integer
- 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.
=== "YAML"
```yaml
derp:
server:
region_id: 999
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_REGION_ID=999
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.region_id = 999;
```
derp.server.region_code
- Type: string
- Default:
"" - Env:
HEADSCALE_DERP_SERVER_REGION_CODE
The region's short code, shown by Tailscale clients.
=== "YAML"
```yaml
derp:
server:
region_code: headscale
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_REGION_CODE=headscale
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.region_code = "headscale";
```
derp.server.region_name
- Type: string
- Default:
"" - Env:
HEADSCALE_DERP_SERVER_REGION_NAME
The region's name, shown by Tailscale clients.
=== "YAML"
```yaml
derp:
server:
region_name: Headscale Embedded DERP
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_REGION_NAME='Headscale Embedded DERP'
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.region_name = "Headscale Embedded DERP";
```
derp.server.verify_clients
- Type: boolean
- Default:
true - Env:
HEADSCALE_DERP_SERVER_VERIFY_CLIENTS
Admits only nodes registered with this server.
=== "YAML"
```yaml
derp:
server:
verify_clients: false
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_VERIFY_CLIENTS=false
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.verify_clients = false;
```
derp.server.stun_listen_addr
- Type: listen address
- Default:
"" - Env:
HEADSCALE_DERP_SERVER_STUN_LISTEN_ADDR
The UDP host:port of the STUN server, which helps clients with NAT traversal; required when derp.server.enabled is true.
=== "YAML"
```yaml
derp:
server:
stun_listen_addr: 0.0.0.0:3478
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_STUN_LISTEN_ADDR=0.0.0.0:3478
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.stun_listen_addr = "0.0.0.0:3478";
```
derp.server.private_key_path
- Type: string
- Default:
"" - Env:
HEADSCALE_DERP_SERVER_PRIVATE_KEY_PATH
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.
=== "YAML"
```yaml
derp:
server:
private_key_path: /var/lib/headscale/derp_server_private.key
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_PRIVATE_KEY_PATH=/var/lib/headscale/derp_server_private.key
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.private_key_path = "/var/lib/headscale/derp_server_private.key";
```
derp.server.ipv4
- Type: string
- Default:
"" - Env:
HEADSCALE_DERP_SERVER_IPV4
The server's public IPv4 address, published in the DERP map so clients reach it without DNS. Empty publishes none.
=== "YAML"
```yaml
derp:
server:
ipv4: 198.51.100.1
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_IPV4=198.51.100.1
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.ipv4 = "198.51.100.1";
```
derp.server.ipv6
- Type: string
- Default:
"" - Env:
HEADSCALE_DERP_SERVER_IPV6
The server's public IPv6 address, published in the DERP map so clients reach it without DNS. Empty publishes none.
=== "YAML"
```yaml
derp:
server:
ipv6: 2001:db8::1
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_IPV6=2001:db8::1
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.ipv6 = "2001:db8::1";
```
derp.server.automatically_add_embedded_derp_region
- Type: boolean
- Default:
true - Env:
HEADSCALE_DERP_SERVER_AUTOMATICALLY_ADD_EMBEDDED_DERP_REGION
Adds the embedded server's region to the DERP map. When it is false and derp.server.enabled is true, derp.paths is required: write the region there yourself.
=== "YAML"
```yaml
derp:
server:
automatically_add_embedded_derp_region: false
```
=== "Environment"
```shell
export HEADSCALE_DERP_SERVER_AUTOMATICALLY_ADD_EMBEDDED_DERP_REGION=false
```
=== "NixOS"
```nix
services.headscale.settings.derp.server.automatically_add_embedded_derp_region = false;
```
derp.urls
- Type: list of URLs
- Default:
[] - Env:
HEADSCALE_DERP_URLS(space-separated or JSON array)
DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains.
=== "YAML"
```yaml
derp:
urls:
- https://controlplane.tailscale.com/derpmap/default
```
=== "Environment"
```shell
export HEADSCALE_DERP_URLS='["https://controlplane.tailscale.com/derpmap/default"]'
```
=== "NixOS"
```nix
services.headscale.settings.derp.urls = [
"https://controlplane.tailscale.com/derpmap/default"
];
```
derp.paths
- Type: list of strings
- Default:
[] - Env:
HEADSCALE_DERP_PATHS(space-separated or JSON array)
DERP map files. The extension picks the format: .yaml or .yml, or Tailscale JSON as .json or .hujson, both accepting comments and trailing commas.
=== "YAML"
```yaml
derp:
paths:
- /etc/headscale/derp.yaml
```
=== "Environment"
```shell
export HEADSCALE_DERP_PATHS='["/etc/headscale/derp.yaml"]'
```
=== "NixOS"
```nix
services.headscale.settings.derp.paths = [
"/etc/headscale/derp.yaml"
];
```
Replaces derp_map_path (removed).
derp.auto_update_enabled
- Type: boolean
- Default:
false - Env:
HEADSCALE_DERP_AUTO_UPDATE_ENABLED
Reloads derp.urls and derp.paths every derp.update_frequency.
=== "YAML"
```yaml
derp:
auto_update_enabled: true
```
=== "Environment"
```shell
export HEADSCALE_DERP_AUTO_UPDATE_ENABLED=true
```
=== "NixOS"
```nix
services.headscale.settings.derp.auto_update_enabled = true;
```
derp.update_frequency
- Type: duration
- Default:
3h - Env:
HEADSCALE_DERP_UPDATE_FREQUENCY
How often derp.auto_update_enabled reloads the DERP map. Zero disables reloading.
=== "YAML"
```yaml
derp:
update_frequency: 24h
```
=== "Environment"
```shell
export HEADSCALE_DERP_UPDATE_FREQUENCY=24h
```
=== "NixOS"
```nix
services.headscale.settings.derp.update_frequency = "24h";
```
database
Where headscale stores nodes, users and keys. SQLite is recommended; PostgreSQL is supported for legacy deployments only. database.sqlite is read only for SQLite, database.postgres only for PostgreSQL.
??? example "All database keys and defaults"
```yaml
database:
type: ""
debug: false
gorm:
slow_threshold: 0
skip_err_record_not_found: false
parameterized_queries: false
sqlite:
path: ""
write_ahead_log: true
wal_autocheckpoint: 1000
postgres:
host: ""
port: 0
name: ""
user: ""
pass: ""
ssl: "false"
max_open_conns: 10
max_idle_conns: 10
conn_max_idle_time_secs: 3600
```
database.type
- Type: enum:
sqlite,sqlite3,postgres - Required
- Env:
HEADSCALE_DATABASE_TYPE
The database backend. SQLite is recommended; PostgreSQL is supported for legacy deployments only.
| Value | Meaning |
|---|---|
sqlite |
SQLite, in the file database.sqlite.path. |
sqlite3 |
The same as sqlite. |
postgres |
PostgreSQL, at database.postgres.host. |
=== "YAML"
```yaml
database:
type: sqlite
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_TYPE=sqlite
```
=== "NixOS"
```nix
services.headscale.settings.database.type = "sqlite";
```
Replaces db_type (removed).
database.debug
- Type: boolean
- Default:
false - Env:
HEADSCALE_DATABASE_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.
=== "YAML"
```yaml
database:
debug: true
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_DEBUG=true
```
=== "NixOS"
```nix
services.headscale.settings.database.debug = true;
```
database.gorm
Query logging, applied only when database.debug is true.
??? example "All database.gorm keys and defaults"
```yaml
database:
gorm:
slow_threshold: 0
skip_err_record_not_found: false
parameterized_queries: false
```
database.gorm.slow_threshold
- Type: integer
- Default:
0 - Env:
HEADSCALE_DATABASE_GORM_SLOW_THRESHOLD
The query time, in milliseconds, above which a query is logged as a warning. Zero disables the warning.
=== "YAML"
```yaml
database:
gorm:
slow_threshold: 1000
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_GORM_SLOW_THRESHOLD=1000
```
=== "NixOS"
```nix
services.headscale.settings.database.gorm.slow_threshold = 1000;
```
database.gorm.skip_err_record_not_found
- Type: boolean
- Default:
false - Env:
HEADSCALE_DATABASE_GORM_SKIP_ERR_RECORD_NOT_FOUND
Logs a query that finds no record as an ordinary query, not as an error.
=== "YAML"
```yaml
database:
gorm:
skip_err_record_not_found: true
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_GORM_SKIP_ERR_RECORD_NOT_FOUND=true
```
=== "NixOS"
```nix
services.headscale.settings.database.gorm.skip_err_record_not_found = true;
```
database.gorm.parameterized_queries
- Type: boolean
- Default:
false - Env:
HEADSCALE_DATABASE_GORM_PARAMETERIZED_QUERIES
Logs queries without their parameter values.
=== "YAML"
```yaml
database:
gorm:
parameterized_queries: true
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_GORM_PARAMETERIZED_QUERIES=true
```
=== "NixOS"
```nix
services.headscale.settings.database.gorm.parameterized_queries = true;
```
database.sqlite
SQLite, read only when database.type is sqlite or sqlite3.
??? example "All database.sqlite keys and defaults"
```yaml
database:
sqlite:
path: ""
write_ahead_log: true
wal_autocheckpoint: 1000
```
database.sqlite.path
- Type: string
- Default:
"" - Env:
HEADSCALE_DATABASE_SQLITE_PATH
The database file, relative to the configuration file; :memory: keeps the database in memory.
=== "YAML"
```yaml
database:
sqlite:
path: /var/lib/headscale/db.sqlite
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_SQLITE_PATH=/var/lib/headscale/db.sqlite
```
=== "NixOS"
```nix
services.headscale.settings.database.sqlite.path = "/var/lib/headscale/db.sqlite";
```
Replaces db_path (removed).
database.sqlite.write_ahead_log
- Type: boolean
- Default:
true - Env:
HEADSCALE_DATABASE_SQLITE_WRITE_AHEAD_LOG
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.
=== "YAML"
```yaml
database:
sqlite:
write_ahead_log: false
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_SQLITE_WRITE_AHEAD_LOG=false
```
=== "NixOS"
```nix
services.headscale.settings.database.sqlite.write_ahead_log = false;
```
database.sqlite.wal_autocheckpoint
- Type: integer
- Default:
1000 - Env:
HEADSCALE_DATABASE_SQLITE_WAL_AUTOCHECKPOINT
The number of WAL frames after which the WAL is checkpointed automatically; zero disables automatic checkpoints. Applied only when database.sqlite.write_ahead_log is true.
=== "YAML"
```yaml
database:
sqlite:
wal_autocheckpoint: 2000
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_SQLITE_WAL_AUTOCHECKPOINT=2000
```
=== "NixOS"
```nix
services.headscale.settings.database.sqlite.wal_autocheckpoint = 2000;
```
database.postgres
PostgreSQL, read only when database.type is postgres.
??? example "All database.postgres keys and defaults"
```yaml
database:
postgres:
host: ""
port: 0
name: ""
user: ""
pass: ""
ssl: "false"
max_open_conns: 10
max_idle_conns: 10
conn_max_idle_time_secs: 3600
```
database.postgres.host
- Type: string
- Default:
"" - Env:
HEADSCALE_DATABASE_POSTGRES_HOST
The server's host name or IP, or the directory of its Unix socket (a path starting with /).
=== "YAML"
```yaml
database:
postgres:
host: db.example.com
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_HOST=db.example.com
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.host = "db.example.com";
```
Replaces db_host (removed).
database.postgres.port
- Type: integer
- Default:
0 - Env:
HEADSCALE_DATABASE_POSTGRES_PORT
The server's port or, with a Unix socket directory in database.postgres.host, the port in the socket's file name. Zero uses the driver's default.
=== "YAML"
```yaml
database:
postgres:
port: 5432
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_PORT=5432
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.port = 5432;
```
Replaces db_port (removed).
database.postgres.name
- Type: string
- Default:
"" - Env:
HEADSCALE_DATABASE_POSTGRES_NAME
The database name.
=== "YAML"
```yaml
database:
postgres:
name: headscale
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_NAME=headscale
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.name = "headscale";
```
Replaces db_name (removed).
database.postgres.user
- Type: string
- Default:
"" - Env:
HEADSCALE_DATABASE_POSTGRES_USER
The user to connect as.
=== "YAML"
```yaml
database:
postgres:
user: headscale
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_USER=headscale
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.user = "headscale";
```
Replaces db_user (removed).
database.postgres.pass
- Type: secret
- Default:
"" - Env:
HEADSCALE_DATABASE_POSTGRES_PASS
The password, or file:<path> to read it from a file, read only when database.type is postgres. headscale generate config --running and /debug/config show a literal password as <redacted> and a file: reference as written.
=== "YAML"
```yaml
database:
postgres:
pass: file:/run/secrets/postgres_password
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_PASS=file:/run/secrets/postgres_password
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.pass = "file:\${CREDENTIALS_DIRECTORY}/database_postgres_pass";
systemd.services.headscale.serviceConfig.LoadCredential = [ "database_postgres_pass:/run/secrets/postgres_password" ];
```
Replaces db_pass (removed).
Replaces db_password_file (removed).
Replaces database.postgres.password_file (removed).
database.postgres.ssl
- Type: string
- Default:
"false" - Env:
HEADSCALE_DATABASE_POSTGRES_SSL
The TLS mode: true keeps the driver's default sslmode, false disables TLS, any other value is passed as sslmode (require, verify-full, ...).
=== "YAML"
```yaml
database:
postgres:
ssl: verify-full
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_SSL=verify-full
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.ssl = "verify-full";
```
Replaces db_ssl (removed).
database.postgres.max_open_conns
- Type: integer
- Default:
10 - Env:
HEADSCALE_DATABASE_POSTGRES_MAX_OPEN_CONNS
Caps open connections to the database.
=== "YAML"
```yaml
database:
postgres:
max_open_conns: 20
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_MAX_OPEN_CONNS=20
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.max_open_conns = 20;
```
database.postgres.max_idle_conns
- Type: integer
- Default:
10 - Env:
HEADSCALE_DATABASE_POSTGRES_MAX_IDLE_CONNS
Caps idle connections kept in the pool.
=== "YAML"
```yaml
database:
postgres:
max_idle_conns: 5
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_MAX_IDLE_CONNS=5
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.max_idle_conns = 5;
```
database.postgres.conn_max_idle_time_secs
- Type: integer
- Default:
3600 - Env:
HEADSCALE_DATABASE_POSTGRES_CONN_MAX_IDLE_TIME_SECS
How long, in seconds, a connection may stay idle before it is closed.
=== "YAML"
```yaml
database:
postgres:
conn_max_idle_time_secs: 600
```
=== "Environment"
```shell
export HEADSCALE_DATABASE_POSTGRES_CONN_MAX_IDLE_TIME_SECS=600
```
=== "NixOS"
```nix
services.headscale.settings.database.postgres.conn_max_idle_time_secs = 600;
```
dns
The DNS configuration sent to clients, MagicDNS included, and TLS certificates for nodes. Clients apply it only with --accept-dns, their default. See DNS.
Replaces dns_config (removed).
??? example "All dns keys and defaults"
```yaml
dns:
magic_dns: true
base_domain: ""
override_local_dns: true
nameservers:
global: []
split: {}
search_domains: []
extra_records: []
extra_records_path: ""
certificates:
enabled: false
zone: ""
challenge:
propagation_timeout: 2m
resolvers:
- 9.9.9.9:53
- 149.112.112.112:53
provider: {}
```
dns.magic_dns
- Type: boolean
- Default:
true - Env:
HEADSCALE_DNS_MAGIC_DNS
Gives each node a name below dns.base_domain, e.g. laptop.example.com, resolved by the client. It requires dns.base_domain.
=== "YAML"
```yaml
dns:
magic_dns: false
```
=== "Environment"
```shell
export HEADSCALE_DNS_MAGIC_DNS=false
```
=== "NixOS"
```nix
services.headscale.settings.dns.magic_dns = false;
```
Replaces dns_config.magic_dns (removed).
dns.base_domain
- Type: string
- Default:
""; required whendns.magic_dnsis true - Env:
HEADSCALE_DNS_BASE_DOMAIN
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.
=== "YAML"
```yaml
dns:
base_domain: tailnet.example.com
```
=== "Environment"
```shell
export HEADSCALE_DNS_BASE_DOMAIN=tailnet.example.com
```
=== "NixOS"
```nix
services.headscale.settings.dns.base_domain = "tailnet.example.com";
```
Replaces dns_config.base_domain (removed).
dns.override_local_dns
- Type: boolean
- Default:
true - Env:
HEADSCALE_DNS_OVERRIDE_LOCAL_DNS
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.
=== "YAML"
```yaml
dns:
override_local_dns: false
```
=== "Environment"
```shell
export HEADSCALE_DNS_OVERRIDE_LOCAL_DNS=false
```
=== "NixOS"
```nix
services.headscale.settings.dns.override_local_dns = false;
```
Replaces dns_config.override_local_dns (removed).
dns.nameservers
The upstream DNS servers sent to clients. An entry that is neither an IP address nor a URL is skipped with a warning.
??? example "All dns.nameservers keys and defaults"
```yaml
dns:
nameservers:
global: []
split: {}
```
dns.nameservers.global
- Type: list of strings
- Default:
[]; required whendns.override_local_dnsis true - Env:
HEADSCALE_DNS_NAMESERVERS_GLOBAL(space-separated or JSON array)
The nameservers for names dns.nameservers.split does not cover: IP addresses, or DNS-over-HTTPS URLs such as https://dns.nextdns.io/<id>.
=== "YAML"
```yaml
dns:
nameservers:
global:
- 9.9.9.9
- 149.112.112.112
- 2620:fe::fe
- 2620:fe::9
```
=== "Environment"
```shell
export HEADSCALE_DNS_NAMESERVERS_GLOBAL='["9.9.9.9","149.112.112.112","2620:fe::fe","2620:fe::9"]'
```
=== "NixOS"
```nix
services.headscale.settings.dns.nameservers.global = [
"9.9.9.9"
"149.112.112.112"
"2620:fe::fe"
"2620:fe::9"
];
```
Replaces dns_config.nameservers (removed).
dns.nameservers.split
- Type: map of
<domain>→ list of strings - Default:
{} - Env:
HEADSCALE_DNS_NAMESERVERS_SPLIT(JSON object)
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.
=== "YAML"
```yaml
dns:
nameservers:
split:
corp.example.com:
- 192.0.2.53
lab.example.net:
- 198.51.100.53
- 2001:db8::53
```
=== "Environment"
```shell
export HEADSCALE_DNS_NAMESERVERS_SPLIT='{"corp.example.com":["192.0.2.53"],"lab.example.net":["198.51.100.53","2001:db8::53"]}'
```
=== "NixOS"
```nix
services.headscale.settings.dns.nameservers.split = {
"corp.example.com" = [
"192.0.2.53"
];
"lab.example.net" = [
"198.51.100.53"
"2001:db8::53"
];
};
```
Replaces dns_config.restricted_nameservers (removed).
Replaces dns.split (removed).
dns.search_domains
- Type: list of strings
- Default:
[] - Env:
HEADSCALE_DNS_SEARCH_DOMAINS(space-separated or JSON array)
DNS search domains sent to clients. With MagicDNS, dns.base_domain comes first.
=== "YAML"
```yaml
dns:
search_domains:
- corp.example.com
- lab.example.net
```
=== "Environment"
```shell
export HEADSCALE_DNS_SEARCH_DOMAINS='["corp.example.com","lab.example.net"]'
```
=== "NixOS"
```nix
services.headscale.settings.dns.search_domains = [
"corp.example.com"
"lab.example.net"
];
```
Replaces dns_config.domains (removed).
dns.extra_records
- Type: list of DNS records
- Default:
[] - Env:
HEADSCALE_DNS_EXTRA_RECORDS(JSON array)
DNS records served to clients, each with a name, type and value. Clients support A and AAAA. Mutually exclusive with dns.extra_records_path. See Setting extra DNS records.
| Field | Type | Description |
|---|---|---|
name |
string | The fully qualified domain name, e.g. grafana.example.com; the trailing dot is optional. |
type |
string | The record type, A or AAAA; empty picks it from value. Clients ignore other types. |
value |
string | The IP address the name resolves to. |
=== "YAML"
```yaml
dns:
extra_records:
- name: grafana.tailnet.example.com
type: A
value: 100.64.0.3
- name: grafana.tailnet.example.com
type: AAAA
value: fd7a:115c:a1e0::3
```
=== "Environment"
```shell
export HEADSCALE_DNS_EXTRA_RECORDS='[{"name":"grafana.tailnet.example.com","type":"A","value":"100.64.0.3"},{"name":"grafana.tailnet.example.com","type":"AAAA","value":"fd7a:115c:a1e0::3"}]'
```
=== "NixOS"
```nix
services.headscale.settings.dns.extra_records = [
{
name = "grafana.tailnet.example.com";
type = "A";
value = "100.64.0.3";
}
{
name = "grafana.tailnet.example.com";
type = "AAAA";
value = "fd7a:115c:a1e0::3";
}
];
```
Replaces dns_config.extra_records (removed).
dns.extra_records_path
- Type: string
- Default:
"" - Env:
HEADSCALE_DNS_EXTRA_RECORDS_PATH
A file of extra records, reloaded when it changes. The extension picks the format: .json, .hujson, .yaml or .yml. Mutually exclusive with dns.extra_records.
=== "YAML"
```yaml
dns:
extra_records_path: /var/lib/headscale/extra-records.json
```
=== "Environment"
```shell
export HEADSCALE_DNS_EXTRA_RECORDS_PATH=/var/lib/headscale/extra-records.json
```
=== "NixOS"
```nix
services.headscale.settings.dns.extra_records_path = "/var/lib/headscale/extra-records.json";
```
dns.certificates
Lets nodes get TLS certificates for their MagicDNS names with tailscale cert. The node runs ACME itself; headscale publishes its DNS-01 challenge through dns.challenge.provider.
??? example "All dns.certificates keys and defaults"
```yaml
dns:
certificates:
enabled: false
zone: ""
```
dns.certificates.enabled
- Type: boolean
- Default:
false - Env:
HEADSCALE_DNS_CERTIFICATES_ENABLED
Lets nodes run tailscale cert. It requires dns.magic_dns, a lowercase dns.base_domain and dns.challenge.provider.
=== "YAML"
```yaml
dns:
certificates:
enabled: true
```
=== "Environment"
```shell
export HEADSCALE_DNS_CERTIFICATES_ENABLED=true
```
=== "NixOS"
```nix
services.headscale.settings.dns.certificates.enabled = true;
```
dns.certificates.zone
- Type: string
- Default:
"" - Env:
HEADSCALE_DNS_CERTIFICATES_ZONE
The public DNS zone challenge records are written to, when dns.base_domain sits below the zone apex. It must contain dns.base_domain. Empty uses dns.base_domain.
=== "YAML"
```yaml
dns:
certificates:
zone: example.com
```
=== "Environment"
```shell
export HEADSCALE_DNS_CERTIFICATES_ZONE=example.com
```
=== "NixOS"
```nix
services.headscale.settings.dns.certificates.zone = "example.com";
```
dns.challenge
The DNS provider answering ACME DNS-01 challenges, for node certificates and for headscale's own certificate when tls.acme.challenge_type is DNS-01. See DNS-01 challenge provider.
??? example "All dns.challenge keys and defaults"
```yaml
dns:
challenge:
propagation_timeout: 2m
resolvers:
- 9.9.9.9:53
- 149.112.112.112:53
provider: {}
```
dns.challenge.propagation_timeout
- Type: duration
- Default:
2m - Env:
HEADSCALE_DNS_CHALLENGE_PROPAGATION_TIMEOUT
How long to wait for a challenge record to show up on every authoritative nameserver. Zero skips the check.
=== "YAML"
```yaml
dns:
challenge:
propagation_timeout: 5m
```
=== "Environment"
```shell
export HEADSCALE_DNS_CHALLENGE_PROPAGATION_TIMEOUT=5m
```
=== "NixOS"
```nix
services.headscale.settings.dns.challenge.propagation_timeout = "5m";
```
dns.challenge.resolvers
- Type: list of strings
- Default:
['9.9.9.9:53', '149.112.112.112:53'] - Env:
HEADSCALE_DNS_CHALLENGE_RESOLVERS(space-separated or JSON array)
The servers asked for the zone's nameservers, each an IP or host with an optional port (53 if omitted). Empty uses the default public resolvers. The system resolver is never used: on a host running MagicDNS it answers for dns.base_domain itself.
=== "YAML"
```yaml
dns:
challenge:
resolvers:
- 9.9.9.9:53
- '[2620:fe::fe]:53'
```
=== "Environment"
```shell
export HEADSCALE_DNS_CHALLENGE_RESOLVERS='["9.9.9.9:53","[2620:fe::fe]:53"]'
```
=== "NixOS"
```nix
services.headscale.settings.dns.challenge.resolvers = [
"9.9.9.9:53"
"[2620:fe::fe]:53"
];
```
dns.challenge.provider
- Type: map of
<setting>→ value - Default:
{} - Env:
HEADSCALE_DNS_CHALLENGE_PROVIDER(JSON object)
The DNS provider that writes challenge records: name selects it, the other keys are its settings. Keys are lowercased on load, at every depth; two that differ only in case are an error. A string setting may be file:<path> to read it from a file. headscale generate config --running and /debug/config show name and file: references; every other setting is <redacted>, as any may be a credential. See DNS-01 challenge provider to set a provider up, acme-dns included, and to set it from environment variables.
| Provider | Settings |
|---|---|
acmedns |
config, password, server_url, subdomain, username |
cloudflare |
api_token, zone_token |
gigahost |
api_key |
hetzner |
api_token |
powerdns |
api_token, debug, server_id, server_url |
rfc2136 |
key, key_alg, key_name, server |
Each text setting can also be set on its own as HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING>, e.g. HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN, which wins over the same setting in HEADSCALE_DNS_CHALLENGE_PROVIDER and in the configuration file. An object setting, such as the config of acmedns, goes inside the JSON object of HEADSCALE_DNS_CHALLENGE_PROVIDER; see Environment variables.
=== "YAML"
```yaml
dns:
challenge:
provider:
api_token: file:/run/secrets/cloudflare
name: cloudflare
```
=== "Environment"
```shell
export HEADSCALE_DNS_CHALLENGE_PROVIDER='{"api_token":"file:/run/secrets/cloudflare","name":"cloudflare"}'
```
=== "NixOS"
```nix
services.headscale.settings.dns.challenge.provider = {
api_token = "file:\${CREDENTIALS_DIRECTORY}/dns_challenge_provider_api_token";
name = "cloudflare";
};
systemd.services.headscale.serviceConfig.LoadCredential = [ "dns_challenge_provider_api_token:/run/secrets/cloudflare" ];
```
tls
Headscale's own HTTPS certificate on listen_addr: from the files tls.cert_path and tls.key_path, or from ACME in tls.acme, not both. Without either, the server speaks plain HTTP. See TLS.
??? example "All tls keys and defaults"
```yaml
tls:
cert_path: ""
key_path: ""
acme:
hostname: ""
challenge_type: HTTP-01
http_listen: :http
url: ""
email: ""
cache_dir: /var/lib/headscale/cache
```
tls.cert_path
- Type: string
- Default:
"" - Env:
HEADSCALE_TLS_CERT_PATH
The PEM certificate file, relative to the configuration file. Setting it turns TLS on.
=== "YAML"
```yaml
tls:
cert_path: /etc/headscale/tls/cert.pem
```
=== "Environment"
```shell
export HEADSCALE_TLS_CERT_PATH=/etc/headscale/tls/cert.pem
```
=== "NixOS"
```nix
services.headscale.settings.tls.cert_path = "/etc/headscale/tls/cert.pem";
```
Replaces tls_cert_path (removed).
tls.key_path
- Type: string
- Default:
"" - Env:
HEADSCALE_TLS_KEY_PATH
The PEM private key file of tls.cert_path, relative to the configuration file.
=== "YAML"
```yaml
tls:
key_path: /etc/headscale/tls/key.pem
```
=== "Environment"
```shell
export HEADSCALE_TLS_KEY_PATH=/etc/headscale/tls/key.pem
```
=== "NixOS"
```nix
services.headscale.settings.tls.key_path = "/etc/headscale/tls/key.pem";
```
Replaces tls_key_path (removed).
tls.acme
Gets the certificate from an ACME CA such as Let's Encrypt, and renews it. Setting tls.acme.hostname turns it on.
??? example "All tls.acme keys and defaults"
```yaml
tls:
acme:
hostname: ""
challenge_type: HTTP-01
http_listen: :http
url: ""
email: ""
cache_dir: /var/lib/headscale/cache
```
tls.acme.hostname
- Type: string
- Default:
"" - Env:
HEADSCALE_TLS_ACME_HOSTNAME
The domain to request a certificate for. Setting it turns ACME on.
=== "YAML"
```yaml
tls:
acme:
hostname: headscale.example.com
```
=== "Environment"
```shell
export HEADSCALE_TLS_ACME_HOSTNAME=headscale.example.com
```
=== "NixOS"
```nix
services.headscale.settings.tls.acme.hostname = "headscale.example.com";
```
Replaces tls_letsencrypt_hostname (removed).
tls.acme.challenge_type
- Type: enum:
HTTP-01,TLS-ALPN-01,DNS-01 - Default:
HTTP-01 - Env:
HEADSCALE_TLS_ACME_CHALLENGE_TYPE
How the CA verifies that headscale controls tls.acme.hostname.
| Value | Meaning |
|---|---|
HTTP-01 |
Has the CA fetch a token over HTTP on port 80, answered on tls.acme.http_listen. TLS-ALPN-01 on listen_addr stays enabled too. |
TLS-ALPN-01 |
Has the CA check a special certificate on port 443, answered on listen_addr, which must be reachable there. |
DNS-01 |
Has the CA look up a TXT record, which headscale writes through dns.challenge.provider. It needs no open port. |
=== "YAML"
```yaml
tls:
acme:
challenge_type: TLS-ALPN-01
```
=== "Environment"
```shell
export HEADSCALE_TLS_ACME_CHALLENGE_TYPE=TLS-ALPN-01
```
=== "NixOS"
```nix
services.headscale.settings.tls.acme.challenge_type = "TLS-ALPN-01";
```
Replaces tls_letsencrypt_challenge_type (removed).
tls.acme.http_listen
- Type: listen address
- Default:
:http - Env:
HEADSCALE_TLS_ACME_HTTP_LISTEN
The host:port serving HTTP-01 challenges; the port may be a name, as in :http for port 80. Other requests to it are redirected to server_url.
=== "YAML"
```yaml
tls:
acme:
http_listen: 0.0.0.0:80
```
=== "Environment"
```shell
export HEADSCALE_TLS_ACME_HTTP_LISTEN=0.0.0.0:80
```
=== "NixOS"
```nix
services.headscale.settings.tls.acme.http_listen = "0.0.0.0:80";
```
Replaces tls_letsencrypt_listen (removed).
tls.acme.url
- Type: URL
- Default:
"" - Env:
HEADSCALE_TLS_ACME_URL
The CA's ACME directory. Empty uses Let's Encrypt.
=== "YAML"
```yaml
tls:
acme:
url: https://acme-staging-v02.api.letsencrypt.org/directory
```
=== "Environment"
```shell
export HEADSCALE_TLS_ACME_URL=https://acme-staging-v02.api.letsencrypt.org/directory
```
=== "NixOS"
```nix
services.headscale.settings.tls.acme.url = "https://acme-staging-v02.api.letsencrypt.org/directory";
```
Replaces acme_url (removed).
tls.acme.email
- Type: string
- Default:
"" - Env:
HEADSCALE_TLS_ACME_EMAIL
The contact address registered with the CA.
=== "YAML"
```yaml
tls:
acme:
email: admin@example.com
```
=== "Environment"
```shell
export HEADSCALE_TLS_ACME_EMAIL=admin@example.com
```
=== "NixOS"
```nix
services.headscale.settings.tls.acme.email = "admin@example.com";
```
Replaces acme_email (removed).
tls.acme.cache_dir
- Type: string
- Default:
/var/lib/headscale/cache - Env:
HEADSCALE_TLS_ACME_CACHE_DIR
Where certificates and ACME account data are stored, relative to the configuration file.
=== "YAML"
```yaml
tls:
acme:
cache_dir: /var/cache/headscale/acme
```
=== "Environment"
```shell
export HEADSCALE_TLS_ACME_CACHE_DIR=/var/cache/headscale/acme
```
=== "NixOS"
```nix
services.headscale.settings.tls.acme.cache_dir = "/var/cache/headscale/acme";
```
Replaces tls_letsencrypt_cache_dir (removed).
oidc
Login through an OpenID Connect provider. Setting oidc.issuer turns it on and requires oidc.client_id and oidc.client_secret. See OpenID Connect.
??? example "All oidc keys and defaults"
```yaml
oidc:
only_start_if_oidc_is_available: true
issuer: ""
client_id: ""
client_secret: ""
scope:
- openid
- profile
- email
extra_params: {}
allowed_domains: []
allowed_users: []
allowed_groups: []
email_verified_required: true
use_expiry_from_token: false
pkce:
enabled: false
method: S256
```
oidc.only_start_if_oidc_is_available
- Type: boolean
- Default:
true - Env:
HEADSCALE_OIDC_ONLY_START_IF_OIDC_IS_AVAILABLE
Stops startup when the provider cannot be reached. False starts without OIDC, with CLI-based registration.
=== "YAML"
```yaml
oidc:
only_start_if_oidc_is_available: false
```
=== "Environment"
```shell
export HEADSCALE_OIDC_ONLY_START_IF_OIDC_IS_AVAILABLE=false
```
=== "NixOS"
```nix
services.headscale.settings.oidc.only_start_if_oidc_is_available = false;
```
oidc.issuer
- Type: URL
- Default:
"" - Env:
HEADSCALE_OIDC_ISSUER
The provider's issuer URL. Setting it turns OIDC on.
=== "YAML"
```yaml
oidc:
issuer: https://idp.example.com/realms/headscale
```
=== "Environment"
```shell
export HEADSCALE_OIDC_ISSUER=https://idp.example.com/realms/headscale
```
=== "NixOS"
```nix
services.headscale.settings.oidc.issuer = "https://idp.example.com/realms/headscale";
```
oidc.client_id
- Type: string
- Default:
"" - Env:
HEADSCALE_OIDC_CLIENT_ID
The client ID from the provider; required when oidc.issuer is set.
=== "YAML"
```yaml
oidc:
client_id: headscale
```
=== "Environment"
```shell
export HEADSCALE_OIDC_CLIENT_ID=headscale
```
=== "NixOS"
```nix
services.headscale.settings.oidc.client_id = "headscale";
```
oidc.client_secret
- Type: secret
- Default:
"" - Env:
HEADSCALE_OIDC_CLIENT_SECRET
The client secret from the provider, or file:<path> to read it from a file; required when oidc.issuer is set. headscale generate config --running and /debug/config show a literal secret as <redacted> and a file: reference as written.
=== "YAML"
```yaml
oidc:
client_secret: file:/run/secrets/oidc_client_secret
```
=== "Environment"
```shell
export HEADSCALE_OIDC_CLIENT_SECRET=file:/run/secrets/oidc_client_secret
```
=== "NixOS"
```nix
services.headscale.settings.oidc.client_secret = "file:\${CREDENTIALS_DIRECTORY}/oidc_client_secret";
systemd.services.headscale.serviceConfig.LoadCredential = [ "oidc_client_secret:/run/secrets/oidc_client_secret" ];
```
Replaces oidc.client_secret_path (removed).
oidc.scope
- Type: list of strings
- Default:
[openid, profile, email] - Env:
HEADSCALE_OIDC_SCOPE(space-separated or JSON array)
The scopes requested; include openid.
=== "YAML"
```yaml
oidc:
scope:
- openid
- profile
- email
- groups
```
=== "Environment"
```shell
export HEADSCALE_OIDC_SCOPE='["openid","profile","email","groups"]'
```
=== "NixOS"
```nix
services.headscale.settings.oidc.scope = [
"openid"
"profile"
"email"
"groups"
];
```
oidc.extra_params
- Type: map of
<param>→ string - Default:
{} - Env:
HEADSCALE_OIDC_EXTRA_PARAMS(JSON object)
Sent as is to the provider's authorization endpoint, e.g. domain_hint; names keep their case.
=== "YAML"
```yaml
oidc:
extra_params:
domain_hint: example.com
prompt: select_account
```
=== "Environment"
```shell
export HEADSCALE_OIDC_EXTRA_PARAMS='{"domain_hint":"example.com","prompt":"select_account"}'
```
=== "NixOS"
```nix
services.headscale.settings.oidc.extra_params = {
domain_hint = "example.com";
prompt = "select_account";
};
```
oidc.allowed_domains
- Type: list of strings
- Default:
[] - Env:
HEADSCALE_OIDC_ALLOWED_DOMAINS(space-separated or JSON array)
Admits only users whose email domain is listed. Empty admits any domain.
=== "YAML"
```yaml
oidc:
allowed_domains:
- example.com
```
=== "Environment"
```shell
export HEADSCALE_OIDC_ALLOWED_DOMAINS='["example.com"]'
```
=== "NixOS"
```nix
services.headscale.settings.oidc.allowed_domains = [
"example.com"
];
```
oidc.allowed_users
- Type: list of strings
- Default:
[] - Env:
HEADSCALE_OIDC_ALLOWED_USERS(space-separated or JSON array)
Admits only users whose email address is listed. Empty admits any user.
=== "YAML"
```yaml
oidc:
allowed_users:
- alice@example.com
```
=== "Environment"
```shell
export HEADSCALE_OIDC_ALLOWED_USERS='["alice@example.com"]'
```
=== "NixOS"
```nix
services.headscale.settings.oidc.allowed_users = [
"alice@example.com"
];
```
oidc.allowed_groups
- Type: list of strings
- Default:
[] - Env:
HEADSCALE_OIDC_ALLOWED_GROUPS(space-separated or JSON array)
Admits only members of at least one listed group, from the provider's groups claim: UserInfo first, the ID token as fallback. Empty admits any group.
=== "YAML"
```yaml
oidc:
allowed_groups:
- headscale-users
```
=== "Environment"
```shell
export HEADSCALE_OIDC_ALLOWED_GROUPS='["headscale-users"]'
```
=== "NixOS"
```nix
services.headscale.settings.oidc.allowed_groups = [
"headscale-users"
];
```
oidc.email_verified_required
- Type: boolean
- Default:
true - Env:
HEADSCALE_OIDC_EMAIL_VERIFIED_REQUIRED
Trusts an email only when the provider marks it verified: an unverified one fails oidc.allowed_domains and oidc.allowed_users and is not copied to the user. Turn it off for a provider that does not send email_verified.
=== "YAML"
```yaml
oidc:
email_verified_required: false
```
=== "Environment"
```shell
export HEADSCALE_OIDC_EMAIL_VERIFIED_REQUIRED=false
```
=== "NixOS"
```nix
services.headscale.settings.oidc.email_verified_required = false;
```
oidc.use_expiry_from_token
- Type: boolean
- Default:
false - Env:
HEADSCALE_OIDC_USE_EXPIRY_FROM_TOKEN
Expires an OIDC-registered node with its token, instead of node.expiry. Tokens are often short-lived, forcing frequent logins.
=== "YAML"
```yaml
oidc:
use_expiry_from_token: true
```
=== "Environment"
```shell
export HEADSCALE_OIDC_USE_EXPIRY_FROM_TOKEN=true
```
=== "NixOS"
```nix
services.headscale.settings.oidc.use_expiry_from_token = true;
```
oidc.pkce
Proof Key for Code Exchange (RFC 7636), which protects the authorization code from interception. See Enable PKCE.
??? example "All oidc.pkce keys and defaults"
```yaml
oidc:
pkce:
enabled: false
method: S256
```
oidc.pkce.enabled
- Type: boolean
- Default:
false - Env:
HEADSCALE_OIDC_PKCE_ENABLED
Sends a PKCE challenge with each login.
=== "YAML"
```yaml
oidc:
pkce:
enabled: true
```
=== "Environment"
```shell
export HEADSCALE_OIDC_PKCE_ENABLED=true
```
=== "NixOS"
```nix
services.headscale.settings.oidc.pkce.enabled = true;
```
oidc.pkce.method
- Type: enum:
plain,S256 - Default:
S256 - Env:
HEADSCALE_OIDC_PKCE_METHOD
How the code challenge is derived from the verifier. The verifier is sent as is in the token exchange.
| Value | Meaning |
|---|---|
plain |
Sends the verifier itself as the challenge. Use it only with a provider that does not support S256. |
S256 |
Sends the base64url SHA-256 of the verifier as the challenge. Recommended. |
=== "YAML"
```yaml
oidc:
pkce:
method: plain
```
=== "Environment"
```shell
export HEADSCALE_OIDC_PKCE_METHOD=plain
```
=== "NixOS"
```nix
services.headscale.settings.oidc.pkce.method = "plain";
```
logtail
Whether nodes send their logs to Tailscale.
??? example "All logtail keys and defaults"
```yaml
logtail:
enabled: false
```
logtail.enabled
- Type: boolean
- Default:
false - Env:
HEADSCALE_LOGTAIL_ENABLED
Lets nodes send their logs to Tailscale Inc.; headscale cannot point them at another log server. False tells nodes not to.
=== "YAML"
```yaml
logtail:
enabled: true
```
=== "Environment"
```shell
export HEADSCALE_LOGTAIL_ENABLED=true
```
=== "NixOS"
```nix
services.headscale.settings.logtail.enabled = true;
```
taildrop
Taildrop, Tailscale's file sharing between nodes.
??? example "All taildrop keys and defaults"
```yaml
taildrop:
enabled: true
```
taildrop.enabled
- Type: boolean
- Default:
true - Env:
HEADSCALE_TAILDROP_ENABLED
Gives every node the file-sharing capability. False omits it from the baseline; a policy nodeAttrs grant can still give it.
=== "YAML"
```yaml
taildrop:
enabled: false
```
=== "Environment"
```shell
export HEADSCALE_TAILDROP_ENABLED=false
```
=== "NixOS"
```nix
services.headscale.settings.taildrop.enabled = false;
```
auto_update
The tailnet-wide default for client auto-updates.
??? example "All auto_update keys and defaults"
```yaml
auto_update:
enabled: false
```
auto_update.enabled
- Type: boolean
- Default:
false - Env:
HEADSCALE_AUTO_UPDATE_ENABLED
Makes auto-update the default for clients that have not chosen locally. Clients store the default they first see, so a later change reaches only new clients.
=== "YAML"
```yaml
auto_update:
enabled: true
```
=== "Environment"
```shell
export HEADSCALE_AUTO_UPDATE_ENABLED=true
```
=== "NixOS"
```nix
services.headscale.settings.auto_update.enabled = true;
```
cli
How the headscale CLI reaches the server: the local unix_socket without authentication, or a remote cli.address with cli.api_key. The CLI reads these keys from its own configuration, such as ~/.config/headscale/config.yaml, or from HEADSCALE_CLI_* variables; the server does not read them, so on NixOS they do not belong in services.headscale.settings. See Remote control.
??? example "All cli keys and defaults"
```yaml
cli:
address: ""
api_key: ""
timeout: 5s
insecure: false
```
cli.address
- Type: string
- Default:
"" - Env:
HEADSCALE_CLI_ADDRESS
The remote server's host:port or URL; https:// is assumed without a scheme. Empty uses unix_socket.
=== "YAML"
```yaml
cli:
address: headscale.example.com:443
```
=== "Environment"
```shell
export HEADSCALE_CLI_ADDRESS=headscale.example.com:443
```
cli.api_key
- Type: secret
- Default:
"" - Env:
HEADSCALE_CLI_API_KEY
The API key the CLI sends to cli.address, or file:<path> to read it from a file. Read only by the CLI.
=== "YAML"
```yaml
cli:
api_key: file:/run/secrets/headscale_api_key
```
=== "Environment"
```shell
export HEADSCALE_CLI_API_KEY=file:/run/secrets/headscale_api_key
```
cli.timeout
- Type: duration
- Default:
5s - Env:
HEADSCALE_CLI_TIMEOUT
Bounds each CLI command's requests to the server.
=== "YAML"
```yaml
cli:
timeout: 30s
```
=== "Environment"
```shell
export HEADSCALE_CLI_TIMEOUT=30s
```
cli.insecure
- Type: boolean
- Default:
false - Env:
HEADSCALE_CLI_INSECURE
Skips TLS certificate verification of cli.address.
=== "YAML"
```yaml
cli:
insecure: true
```
=== "Environment"
```shell
export HEADSCALE_CLI_INSECURE=true
```
tuning
Holds performance settings that rarely need changing.
??? example "All tuning keys and defaults"
```yaml
tuning:
batch_change_delay: 800ms
node_mapsession_buffered_chan_size: 30
batcher_workers: 0
register_cache_expiration: 15m
register_cache_max_entries: 1024
node_store_batch_size: 100
node_store_batch_timeout: 500ms
```
tuning.batch_change_delay
- Type: duration
- Default:
800ms - Env:
HEADSCALE_TUNING_BATCH_CHANGE_DELAY
How often queued changes are sent to clients as one update; must be positive.
=== "YAML"
```yaml
tuning:
batch_change_delay: 500ms
```
=== "Environment"
```shell
export HEADSCALE_TUNING_BATCH_CHANGE_DELAY=500ms
```
=== "NixOS"
```nix
services.headscale.settings.tuning.batch_change_delay = "500ms";
```
tuning.node_mapsession_buffered_chan_size
- Type: integer
- Default:
30 - Env:
HEADSCALE_TUNING_NODE_MAPSESSION_BUFFERED_CHAN_SIZE
How many map updates are queued per connected client.
=== "YAML"
```yaml
tuning:
node_mapsession_buffered_chan_size: 60
```
=== "Environment"
```shell
export HEADSCALE_TUNING_NODE_MAPSESSION_BUFFERED_CHAN_SIZE=60
```
=== "NixOS"
```nix
services.headscale.settings.tuning.node_mapsession_buffered_chan_size = 60;
```
tuning.batcher_workers
- Type: integer
- Default:
0(three quarters of the CPU cores, at least one) - Env:
HEADSCALE_TUNING_BATCHER_WORKERS
The number of workers building map updates for connected clients. Zero picks the number from the CPU count.
=== "YAML"
```yaml
tuning:
batcher_workers: 8
```
=== "Environment"
```shell
export HEADSCALE_TUNING_BATCHER_WORKERS=8
```
=== "NixOS"
```nix
services.headscale.settings.tuning.batcher_workers = 8;
```
tuning.register_cache_expiration
- Type: duration
- Default:
15m - Env:
HEADSCALE_TUNING_REGISTER_CACHE_EXPIRATION
How long a pending registration waits to be completed. Zero uses the default.
=== "YAML"
```yaml
tuning:
register_cache_expiration: 30m
```
=== "Environment"
```shell
export HEADSCALE_TUNING_REGISTER_CACHE_EXPIRATION=30m
```
=== "NixOS"
```nix
services.headscale.settings.tuning.register_cache_expiration = "30m";
```
tuning.register_cache_max_entries
- Type: integer
- Default:
1024 - Env:
HEADSCALE_TUNING_REGISTER_CACHE_MAX_ENTRIES
Bounds pending registrations. At capacity, new registrations are refused without evicting pending ones; SSH checks have a small reserve beyond it. Zero uses the default. See Pending authentication limits.
=== "YAML"
```yaml
tuning:
register_cache_max_entries: 4096
```
=== "Environment"
```shell
export HEADSCALE_TUNING_REGISTER_CACHE_MAX_ENTRIES=4096
```
=== "NixOS"
```nix
services.headscale.settings.tuning.register_cache_max_entries = 4096;
```
tuning.node_store_batch_size
- Type: integer
- Default:
100 - Env:
HEADSCALE_TUNING_NODE_STORE_BATCH_SIZE
How many node changes are batched before the in-memory node state, peer relationships included, is rebuilt; must be positive. Higher values save CPU on bulk changes but delay each change until its batch is full or tuning.node_store_batch_timeout passes.
=== "YAML"
```yaml
tuning:
node_store_batch_size: 200
```
=== "Environment"
```shell
export HEADSCALE_TUNING_NODE_STORE_BATCH_SIZE=200
```
=== "NixOS"
```nix
services.headscale.settings.tuning.node_store_batch_size = 200;
```
tuning.node_store_batch_timeout
- Type: duration
- Default:
500ms - Env:
HEADSCALE_TUNING_NODE_STORE_BATCH_TIMEOUT
The longest a partial batch of node changes waits before the rebuild; must be positive. Lower values answer single changes faster at the cost of more rebuilds.
=== "YAML"
```yaml
tuning:
node_store_batch_timeout: 1s
```
=== "Environment"
```shell
export HEADSCALE_TUNING_NODE_STORE_BATCH_TIMEOUT=1s
```
=== "NixOS"
```nix
services.headscale.settings.tuning.node_store_batch_timeout = "1s";
```
Removed keys
Keys headscale no longer reads. One in the configuration file stops headscale with an error and a variable for one logs a warning, each saying what to do instead, as the table does.
| Key | Removed in | What to do |
|---|---|---|
acl_policy_path |
0.30 | use policy.path |
acme_email |
0.30 | use tls.acme.email |
acme_url |
0.30 | use tls.acme.url |
changes_check_interval |
0.30 | remove changes_check_interval; see the CHANGELOG for context |
database.gorm.prepare_stmt |
0.30 | remove database.gorm.prepare_stmt; see the CHANGELOG for context |
database.postgres.password_file |
0.30 | use database.postgres.pass: file:<path> |
db_host |
0.30 | use database.postgres.host |
db_name |
0.30 | use database.postgres.name |
db_pass |
0.30 | use database.postgres.pass |
db_password_file |
0.30 | use database.postgres.pass: file:<path> |
db_path |
0.30 | use database.sqlite.path |
db_port |
0.30 | use database.postgres.port |
db_ssl |
0.30 | use database.postgres.ssl |
db_type |
0.30 | use database.type |
db_user |
0.30 | use database.postgres.user |
derp.server.stun.enabled |
0.30 | remove it: headscale never read it; the embedded DERP server always serves STUN on derp.server.stun_listen_addr |
derp_map_path |
0.30 | use derp.paths |
dns.challenge.provider.<setting>_path |
0.30 | use dns.challenge.provider.<setting>: file:<path> |
dns.split |
0.30 | use dns.nameservers.split |
dns.use_username_in_magic_dns |
0.24 | remove dns.use_username_in_magic_dns; see the CHANGELOG for context |
dns_config |
0.30 | move every dns_config.* key to dns (nameservers to dns.nameservers.global, restricted_nameservers to dns.nameservers.split, domains to dns.search_domains) |
dns_config.base_domain |
0.30 | use dns.base_domain |
dns_config.domains |
0.30 | use dns.search_domains |
dns_config.extra_records |
0.30 | use dns.extra_records |
dns_config.magic_dns |
0.30 | use dns.magic_dns |
dns_config.nameservers |
0.30 | use dns.nameservers.global |
dns_config.override_local_dns |
0.30 | use dns.override_local_dns |
dns_config.restricted_nameservers |
0.30 | use dns.nameservers.split |
dns_config.use_username_in_magic_dns |
0.24 | remove dns_config.use_username_in_magic_dns; see the CHANGELOG for context |
ephemeral_node_inactivity_timeout |
0.30 | use node.ephemeral.inactivity_timeout |
grpc_allow_insecure |
0.30 | remove grpc_allow_insecure; see the CHANGELOG for context |
grpc_listen_addr |
0.30 | remove grpc_listen_addr; see the CHANGELOG for context |
ip_prefixes |
0.23 | use prefixes.v4 and prefixes.v6 |
json_logs |
0.30 | use log.format: json |
log_level |
0.17 | use log.level |
metrics_enabled |
0.30 | remove metrics_enabled; see the CHANGELOG for context |
node_update_check_interval |
0.30 | remove node_update_check_interval; see the CHANGELOG for context |
noise_private_key_path |
0.30 | use noise.private_key_path |
oidc.client_secret_path |
0.30 | use oidc.client_secret: file:<path> |
oidc.domain_map |
0.13 | remove oidc.domain_map; see the CHANGELOG for context |
oidc.expiry |
0.29 | use node.expiry |
oidc.map_legacy_users |
0.26 | remove oidc.map_legacy_users; see the CHANGELOG for context |
oidc.namespace |
0.30 | remove oidc.namespace; see the CHANGELOG for context |
oidc.strip_email_domain |
0.26 | remove oidc.strip_email_domain; see the CHANGELOG for context |
oidc.user |
0.30 | remove oidc.user; see the CHANGELOG for context |
private_key_path |
0.23 | use noise.private_key_path |
randomize_client_port |
0.29 | set "randomizeClientPort": true at the top level of the policy file, or grant the cap per node via a "nodeAttrs" entry |
tls_cert_path |
0.30 | use tls.cert_path |
tls_client_auth_mode |
0.30 | remove tls_client_auth_mode; see the CHANGELOG for context |
tls_key_path |
0.30 | use tls.key_path |
tls_letsencrypt_cache_dir |
0.30 | use tls.acme.cache_dir |
tls_letsencrypt_challenge_type |
0.30 | use tls.acme.challenge_type |
tls_letsencrypt_hostname |
0.30 | use tls.acme.hostname |
tls_letsencrypt_listen |
0.30 | use tls.acme.http_listen |
tuning.notifier_send_timeout |
0.30 | remove it: it had no effect |