Skip to content

Configuration options

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. An empty item is an error. [9.9.9.9, 2620:fe::fe]
map Keys you choose, each with a value. A variable holds a JSON object. {corp.example.com: [192.0.2.53]}

Environment variables

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, 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:

export HEADSCALE_PREFIXES_V6='""'
export HEADSCALE_DERP_URLS='[]'
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 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 setting of dns.challenge.provider, where a non-string one, such as acme-dns config, is the JSON in the file.

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.

server_url: https://headscale.example.com
export HEADSCALE_SERVER_URL=https://headscale.example.com
services.headscale.settings.server_url = "https://headscale.example.com";

listen_addr

  • Type: listen address
  • 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 or tls.acme.hostname is set, plain HTTP otherwise. The default listens on every address, IPv4 and IPv6 alike.

listen_addr: 127.0.0.1:8080
export HEADSCALE_LISTEN_ADDR=127.0.0.1:8080
services.headscale.settings.listen_addr = "127.0.0.1:8080";

metrics_listen_addr

The host:port serving /metrics and /debug; keep it private. Empty disables this listener.

metrics_listen_addr: 127.0.0.1:9090
export HEADSCALE_METRICS_LISTEN_ADDR=127.0.0.1:9090
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.

unix_socket: /run/headscale/headscale.sock
export HEADSCALE_UNIX_SOCKET=/run/headscale/headscale.sock
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.

unix_socket_permission: "0660"
export HEADSCALE_UNIX_SOCKET_PERMISSION=0660
services.headscale.settings.unix_socket_permission = "0660";

trusted_proxies

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.

trusted_proxies:
  - 192.0.2.10/32
  - 2001:db8::10/128
export HEADSCALE_TRUSTED_PROXIES='["192.0.2.10/32","2001:db8::10/128"]'
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.

disable_check_updates: true
export HEADSCALE_DISABLE_CHECK_UPDATES=true
services.headscale.settings.disable_check_updates = true;

noise

The Noise protocol (TS2021) clients connect over.

All noise keys and defaults
noise:
  private_key_path: /var/lib/headscale/noise_private.key

noise.private_key_path

  • Type: string
  • 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.

noise:
  private_key_path: /opt/headscale/noise_private.key
export HEADSCALE_NOISE_PRIVATE_KEY_PATH=/opt/headscale/noise_private.key
services.headscale.settings.noise.private_key_path = "/opt/headscale/noise_private.key";

Replaces private_key_path (removed). Replaces noise_private_key_path (removed).

prefixes

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.

All prefixes keys and defaults
prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48
  allocation: sequential

prefixes.v4

  • Type: prefix
  • 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.

prefixes:
  v4: 100.64.0.0/24
export HEADSCALE_PREFIXES_V4=100.64.0.0/24
services.headscale.settings.prefixes.v4 = "100.64.0.0/24";

Replaces ip_prefixes (removed).

prefixes.v6

  • Type: prefix
  • Default: fd7a:115c:a1e0::/48
  • Env: HEADSCALE_PREFIXES_V6

The IPv6 range, e.g. fd7a:115c:a1e0::/48. Empty gives nodes no IPv6 address.

prefixes:
  v6: fd7a:115c:a1e0::/64
export HEADSCALE_PREFIXES_V6=fd7a:115c:a1e0::/64
services.headscale.settings.prefixes.v6 = "fd7a:115c:a1e0::/64";

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.
prefixes:
  allocation: random
export HEADSCALE_PREFIXES_ALLOCATION=random
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.

All policy keys and defaults
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.

policy:
  path: /etc/headscale/policy.hujson
export HEADSCALE_POLICY_PATH=/etc/headscale/policy.hujson
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.
policy:
  mode: database
export HEADSCALE_POLICY_MODE=database
services.headscale.settings.policy.mode = "database";

log

Headscale's own log output. See Debugging.

All log keys and defaults
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.

log:
  level: debug
export HEADSCALE_LOG_LEVEL=debug
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.
log:
  format: json
export HEADSCALE_LOG_FORMAT=json
services.headscale.settings.log.format = "json";

Replaces json_logs (removed).

node

Covers node key expiry, ephemeral nodes and subnet routes.

All node keys and defaults
node:
  expiry: 0s
  ephemeral:
    inactivity_timeout: 30m
  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.

node:
  expiry: 2160h
export HEADSCALE_NODE_EXPIRY=2160h
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.

All node.ephemeral keys and defaults
node:
  ephemeral:
    inactivity_timeout: 30m

node.ephemeral.inactivity_timeout

  • Type: duration
  • 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.

node:
  ephemeral:
    inactivity_timeout: 1h
export HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT=1h
services.headscale.settings.node.ephemeral.inactivity_timeout = "1h";

Replaces ephemeral_node_inactivity_timeout (removed).

node.routes

Covers the routes nodes advertise. See Routes.

All node.routes keys and defaults
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.

All node.routes.ha keys and defaults
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.

node:
  routes:
    ha:
      probe_interval: 30s
export HEADSCALE_NODE_ROUTES_HA_PROBE_INTERVAL=30s
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.

node:
  routes:
    ha:
      probe_timeout: 3s
export HEADSCALE_NODE_ROUTES_HA_PROBE_TIMEOUT=3s
services.headscale.settings.node.routes.ha.probe_timeout = "3s";

preauth_keys

Covers the cleanup of revoked pre-auth keys. See Pre authenticated key.

All preauth_keys keys and defaults
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.

preauth_keys:
  revoked_retention: 720h
export HEADSCALE_PREAUTH_KEYS_REVOKED_RETENTION=720h
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.

All derp keys and defaults
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:
    - https://controlplane.tailscale.com/derpmap/default
  paths: []
  auto_update_enabled: true
  update_frequency: 3h

derp.server

The embedded DERP server, a relay and STUN server run by headscale itself. See Enable embedded DERP.

All derp.server keys and defaults
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://.

derp:
  server:
    enabled: true
export HEADSCALE_DERP_SERVER_ENABLED=true
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; required and positive when derp.server.enabled is true. Tailscale keeps 900-999 for your own regions. It replaces a region with the same ID from the other sources.

derp:
  server:
    region_id: 999
export HEADSCALE_DERP_SERVER_REGION_ID=999
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.

derp:
  server:
    region_code: headscale
export HEADSCALE_DERP_SERVER_REGION_CODE=headscale
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.

derp:
  server:
    region_name: Headscale Embedded DERP
export HEADSCALE_DERP_SERVER_REGION_NAME='Headscale Embedded DERP'
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.

derp:
  server:
    verify_clients: false
export HEADSCALE_DERP_SERVER_VERIFY_CLIENTS=false
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.

derp:
  server:
    stun_listen_addr: 0.0.0.0:3478
export HEADSCALE_DERP_SERVER_STUN_LISTEN_ADDR=0.0.0.0:3478
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.

derp:
  server:
    private_key_path: /var/lib/headscale/derp_server_private.key
export HEADSCALE_DERP_SERVER_PRIVATE_KEY_PATH=/var/lib/headscale/derp_server_private.key
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.

derp:
  server:
    ipv4: 198.51.100.1
export HEADSCALE_DERP_SERVER_IPV4=198.51.100.1
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.

derp:
  server:
    ipv6: 2001:db8::1
export HEADSCALE_DERP_SERVER_IPV6=2001:db8::1
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.

derp:
  server:
    automatically_add_embedded_derp_region: false
export HEADSCALE_DERP_SERVER_AUTOMATICALLY_ADD_EMBEDDED_DERP_REGION=false
services.headscale.settings.derp.server.automatically_add_embedded_derp_region = false;

derp.urls

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.

derp:
  urls:
    - https://derp.example.com/derpmap.json
export HEADSCALE_DERP_URLS='["https://derp.example.com/derpmap.json"]'
services.headscale.settings.derp.urls = [
  "https://derp.example.com/derpmap.json"
];

derp.paths

DERP map files. The extension picks the format: .yaml or .yml, or Tailscale JSON as .json or .hujson, both accepting comments and trailing commas.

derp:
  paths:
    - /etc/headscale/derp.yaml
export HEADSCALE_DERP_PATHS='["/etc/headscale/derp.yaml"]'
services.headscale.settings.derp.paths = [
  "/etc/headscale/derp.yaml"
];

Replaces derp_map_path (removed).

derp.auto_update_enabled

  • Type: boolean
  • Default: true
  • Env: HEADSCALE_DERP_AUTO_UPDATE_ENABLED

Reloads derp.urls and derp.paths every derp.update_frequency.

derp:
  auto_update_enabled: false
export HEADSCALE_DERP_AUTO_UPDATE_ENABLED=false
services.headscale.settings.derp.auto_update_enabled = false;

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.

derp:
  update_frequency: 24h
export HEADSCALE_DERP_UPDATE_FREQUENCY=24h
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.

All database keys and defaults
database:
  type: sqlite
  debug: false
  gorm:
    slow_threshold: 0
    skip_err_record_not_found: false
    parameterized_queries: false
  sqlite:
    path: /var/lib/headscale/db.sqlite
    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
  • Default: sqlite
  • 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.
database:
  type: sqlite
export HEADSCALE_DATABASE_TYPE=sqlite
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.

database:
  debug: true
export HEADSCALE_DATABASE_DEBUG=true
services.headscale.settings.database.debug = true;

database.gorm

Query logging, applied only when database.debug is true.

All database.gorm keys and defaults
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.

database:
  gorm:
    slow_threshold: 1000
export HEADSCALE_DATABASE_GORM_SLOW_THRESHOLD=1000
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.

database:
  gorm:
    skip_err_record_not_found: true
export HEADSCALE_DATABASE_GORM_SKIP_ERR_RECORD_NOT_FOUND=true
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.

database:
  gorm:
    parameterized_queries: true
export HEADSCALE_DATABASE_GORM_PARAMETERIZED_QUERIES=true
services.headscale.settings.database.gorm.parameterized_queries = true;

database.sqlite

SQLite, read only when database.type is sqlite or sqlite3.

All database.sqlite keys and defaults
database:
  sqlite:
    path: /var/lib/headscale/db.sqlite
    write_ahead_log: true
    wal_autocheckpoint: 1000

database.sqlite.path

  • Type: string
  • 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.

database:
  sqlite:
    path: /opt/headscale/db.sqlite
export HEADSCALE_DATABASE_SQLITE_PATH=/opt/headscale/db.sqlite
services.headscale.settings.database.sqlite.path = "/opt/headscale/db.sqlite";

Replaces db_path (removed).

database.sqlite.write_ahead_log

  • Type: boolean
  • Default: true
  • Env: HEADSCALE_DATABASE_SQLITE_WRITE_AHEAD_LOG

Runs SQLite in write-ahead log (WAL) mode, applies database.sqlite.wal_autocheckpoint and compacts the database (VACUUM) on shutdown. False uses SQLite's rollback journal (DELETE) with synchronous=FULL, and converts a database left in WAL mode when headscale opens it.

database:
  sqlite:
    write_ahead_log: false
export HEADSCALE_DATABASE_SQLITE_WRITE_AHEAD_LOG=false
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.

database:
  sqlite:
    wal_autocheckpoint: 2000
export HEADSCALE_DATABASE_SQLITE_WAL_AUTOCHECKPOINT=2000
services.headscale.settings.database.sqlite.wal_autocheckpoint = 2000;

database.postgres

PostgreSQL, read only when database.type is postgres. An empty host, name, user, pass or ssl leaves that setting to the driver, which reads the PG* environment variables and falls back to the defaults of libpq, PostgreSQL's client library: a local socket, the OS user, and TLS if the server offers it.

All database.postgres keys and defaults
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 /).

database:
  postgres:
    host: db.example.com
export HEADSCALE_DATABASE_POSTGRES_HOST=db.example.com
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.

database:
  postgres:
    port: 5432
export HEADSCALE_DATABASE_POSTGRES_PORT=5432
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.

database:
  postgres:
    name: headscale
export HEADSCALE_DATABASE_POSTGRES_NAME=headscale
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.

database:
  postgres:
    user: headscale
export HEADSCALE_DATABASE_POSTGRES_USER=headscale
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.

database:
  postgres:
    pass: file:/run/secrets/postgres_password
export HEADSCALE_DATABASE_POSTGRES_PASS=file:/run/secrets/postgres_password
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, ...).

database:
  postgres:
    ssl: verify-full
export HEADSCALE_DATABASE_POSTGRES_SSL=verify-full
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.

database:
  postgres:
    max_open_conns: 20
export HEADSCALE_DATABASE_POSTGRES_MAX_OPEN_CONNS=20
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.

database:
  postgres:
    max_idle_conns: 5
export HEADSCALE_DATABASE_POSTGRES_MAX_IDLE_CONNS=5
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.

database:
  postgres:
    conn_max_idle_time_secs: 600
export HEADSCALE_DATABASE_POSTGRES_CONN_MAX_IDLE_TIME_SECS=600
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).

All dns keys and defaults
dns:
  magic_dns: true
  base_domain: tailnet.internal
  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.

dns:
  magic_dns: false
export HEADSCALE_DNS_MAGIC_DNS=false
services.headscale.settings.dns.magic_dns = false;

Replaces dns_config.magic_dns (removed).

dns.base_domain

  • Type: string
  • 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 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.

dns:
  base_domain: tailnet.example.com
export HEADSCALE_DNS_BASE_DOMAIN=tailnet.example.com
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; with no global nameserver there is nothing to override with, and clients keep their own. False sends them only as fallback resolvers.

dns:
  override_local_dns: false
export HEADSCALE_DNS_OVERRIDE_LOCAL_DNS=false
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.

All dns.nameservers keys and defaults
dns:
  nameservers:
    global: []
    split: {}

dns.nameservers.global

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.

dns:
  nameservers:
    global:
      - 9.9.9.9
      - 149.112.112.112
      - 2620:fe::fe
      - 2620:fe::9
export HEADSCALE_DNS_NAMESERVERS_GLOBAL='["9.9.9.9","149.112.112.112","2620:fe::fe","2620:fe::9"]'
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

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.

dns:
  nameservers:
    split:
      corp.example.com:
        - 192.0.2.53
      lab.example.net:
        - 198.51.100.53
        - 2001:db8::53
export HEADSCALE_DNS_NAMESERVERS_SPLIT='{"corp.example.com":["192.0.2.53"],"lab.example.net":["198.51.100.53","2001:db8::53"]}'
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

DNS search domains sent to clients. With MagicDNS, dns.base_domain comes first.

dns:
  search_domains:
    - corp.example.com
    - lab.example.net
export HEADSCALE_DNS_SEARCH_DOMAINS='["corp.example.com","lab.example.net"]'
services.headscale.settings.dns.search_domains = [
  "corp.example.com"
  "lab.example.net"
];

Replaces dns_config.domains (removed).

dns.extra_records

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.
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
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"}]'
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.

dns:
  extra_records_path: /var/lib/headscale/extra-records.json
export HEADSCALE_DNS_EXTRA_RECORDS_PATH=/var/lib/headscale/extra-records.json
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.

All dns.certificates keys and defaults
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.

dns:
  certificates:
    enabled: true
export HEADSCALE_DNS_CERTIFICATES_ENABLED=true
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.

dns:
  certificates:
    zone: example.com
export HEADSCALE_DNS_CERTIFICATES_ZONE=example.com
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.

All dns.challenge keys and defaults
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.

dns:
  challenge:
    propagation_timeout: 5m
export HEADSCALE_DNS_CHALLENGE_PROPAGATION_TIMEOUT=5m
services.headscale.settings.dns.challenge.propagation_timeout = "5m";

dns.challenge.resolvers

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.

dns:
  challenge:
    resolvers:
      - 9.9.9.9:53
      - '[2620:fe::fe]:53'
export HEADSCALE_DNS_CHALLENGE_RESOLVERS='["9.9.9.9:53","[2620:fe::fe]:53"]'
services.headscale.settings.dns.challenge.resolvers = [
  "9.9.9.9:53"
  "[2620:fe::fe]:53"
];

dns.challenge.provider

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. Any setting may be file:<path> to read it from a file; a non-string one, such as acme-dns config, is the JSON in it. 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.

dns:
  challenge:
    provider:
      api_token: file:/run/secrets/cloudflare
      name: cloudflare
export HEADSCALE_DNS_CHALLENGE_PROVIDER='{"api_token":"file:/run/secrets/cloudflare","name":"cloudflare"}'
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.

All tls keys and defaults
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.

tls:
  cert_path: /etc/headscale/tls/cert.pem
export HEADSCALE_TLS_CERT_PATH=/etc/headscale/tls/cert.pem
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.

tls:
  key_path: /etc/headscale/tls/key.pem
export HEADSCALE_TLS_KEY_PATH=/etc/headscale/tls/key.pem
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.

All tls.acme keys and defaults
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.

tls:
  acme:
    hostname: headscale.example.com
export HEADSCALE_TLS_ACME_HOSTNAME=headscale.example.com
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.
tls:
  acme:
    challenge_type: TLS-ALPN-01
export HEADSCALE_TLS_ACME_CHALLENGE_TYPE=TLS-ALPN-01
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.

tls:
  acme:
    http_listen: 0.0.0.0:80
export HEADSCALE_TLS_ACME_HTTP_LISTEN=0.0.0.0:80
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.

tls:
  acme:
    url: https://acme-staging-v02.api.letsencrypt.org/directory
export HEADSCALE_TLS_ACME_URL=https://acme-staging-v02.api.letsencrypt.org/directory
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.

tls:
  acme:
    email: admin@example.com
export HEADSCALE_TLS_ACME_EMAIL=admin@example.com
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.

tls:
  acme:
    cache_dir: /var/cache/headscale/acme
export HEADSCALE_TLS_ACME_CACHE_DIR=/var/cache/headscale/acme
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.

All oidc keys and defaults
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.

oidc:
  only_start_if_oidc_is_available: false
export HEADSCALE_OIDC_ONLY_START_IF_OIDC_IS_AVAILABLE=false
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.

oidc:
  issuer: https://idp.example.com/realms/headscale
export HEADSCALE_OIDC_ISSUER=https://idp.example.com/realms/headscale
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.

oidc:
  client_id: headscale
export HEADSCALE_OIDC_CLIENT_ID=headscale
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.

oidc:
  client_secret: file:/run/secrets/oidc_client_secret
export HEADSCALE_OIDC_CLIENT_SECRET=file:/run/secrets/oidc_client_secret
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

The scopes requested; include openid.

oidc:
  scope:
    - openid
    - profile
    - email
    - groups
export HEADSCALE_OIDC_SCOPE='["openid","profile","email","groups"]'
services.headscale.settings.oidc.scope = [
  "openid"
  "profile"
  "email"
  "groups"
];

oidc.extra_params

Sent as is to the provider's authorization endpoint, e.g. domain_hint; names keep their case.

oidc:
  extra_params:
    domain_hint: example.com
    prompt: select_account
export HEADSCALE_OIDC_EXTRA_PARAMS='{"domain_hint":"example.com","prompt":"select_account"}'
services.headscale.settings.oidc.extra_params = {
  domain_hint = "example.com";
  prompt = "select_account";
};

oidc.allowed_domains

Admits only users whose email domain is listed. Empty admits any domain.

oidc:
  allowed_domains:
    - example.com
export HEADSCALE_OIDC_ALLOWED_DOMAINS='["example.com"]'
services.headscale.settings.oidc.allowed_domains = [
  "example.com"
];

oidc.allowed_users

Admits only users whose email address is listed. Empty admits any user.

oidc:
  allowed_users:
    - alice@example.com
export HEADSCALE_OIDC_ALLOWED_USERS='["alice@example.com"]'
services.headscale.settings.oidc.allowed_users = [
  "alice@example.com"
];

oidc.allowed_groups

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.

oidc:
  allowed_groups:
    - headscale-users
export HEADSCALE_OIDC_ALLOWED_GROUPS='["headscale-users"]'
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.

oidc:
  email_verified_required: false
export HEADSCALE_OIDC_EMAIL_VERIFIED_REQUIRED=false
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.

oidc:
  use_expiry_from_token: true
export HEADSCALE_OIDC_USE_EXPIRY_FROM_TOKEN=true
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.

All oidc.pkce keys and defaults
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.

oidc:
  pkce:
    enabled: true
export HEADSCALE_OIDC_PKCE_ENABLED=true
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.
oidc:
  pkce:
    method: plain
export HEADSCALE_OIDC_PKCE_METHOD=plain
services.headscale.settings.oidc.pkce.method = "plain";

logtail

Whether nodes send their logs to Tailscale.

All logtail keys and defaults
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.

logtail:
  enabled: true
export HEADSCALE_LOGTAIL_ENABLED=true
services.headscale.settings.logtail.enabled = true;

taildrop

Taildrop, Tailscale's file sharing between nodes.

All taildrop keys and defaults
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.

taildrop:
  enabled: false
export HEADSCALE_TAILDROP_ENABLED=false
services.headscale.settings.taildrop.enabled = false;

auto_update

The tailnet-wide default for client auto-updates.

All auto_update keys and defaults
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.

auto_update:
  enabled: true
export HEADSCALE_AUTO_UPDATE_ENABLED=true
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.

All cli keys and defaults
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.

cli:
  address: headscale.example.com:443
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.

cli:
  api_key: file:/run/secrets/headscale_api_key
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.

cli:
  timeout: 30s
export HEADSCALE_CLI_TIMEOUT=30s

cli.insecure

  • Type: boolean
  • Default: false
  • Env: HEADSCALE_CLI_INSECURE

Skips TLS certificate verification of cli.address.

cli:
  insecure: true
export HEADSCALE_CLI_INSECURE=true

tuning

Holds performance settings that rarely need changing.

All tuning keys and defaults
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.

tuning:
  batch_change_delay: 500ms
export HEADSCALE_TUNING_BATCH_CHANGE_DELAY=500ms
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.

tuning:
  node_mapsession_buffered_chan_size: 60
export HEADSCALE_TUNING_NODE_MAPSESSION_BUFFERED_CHAN_SIZE=60
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.

tuning:
  batcher_workers: 8
export HEADSCALE_TUNING_BATCHER_WORKERS=8
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.

tuning:
  register_cache_expiration: 30m
export HEADSCALE_TUNING_REGISTER_CACHE_EXPIRATION=30m
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.

tuning:
  register_cache_max_entries: 4096
export HEADSCALE_TUNING_REGISTER_CACHE_MAX_ENTRIES=4096
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.

tuning:
  node_store_batch_size: 200
export HEADSCALE_TUNING_NODE_STORE_BATCH_SIZE=200
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.

tuning:
  node_store_batch_timeout: 1s
export HEADSCALE_TUNING_NODE_STORE_BATCH_TIMEOUT=1s
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