mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-19 20:04:32 +09:00
468 lines
21 KiB
YAML
468 lines
21 KiB
YAML
# Generated from hscontrol/types/config.go by go generate; do not edit.
|
|
# Every key: https://headscale.net/stable/ref/configuration-options/
|
|
|
|
# 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.
|
|
# Required. Example: https://headscale.example.com
|
|
server_url: ""
|
|
|
|
# The host:port the server listens on for clients, the API and the web pages. It
|
|
# serves HTTPS when `tls.cert_path` or `tls.acme.hostname` is set, plain HTTP
|
|
# otherwise. The default listens on every address, IPv4 and IPv6 alike.
|
|
listen_addr: 0.0.0.0:8080
|
|
|
|
# The host:port serving `/metrics` and `/debug`; keep it private. Empty disables
|
|
# this listener.
|
|
metrics_listen_addr: ""
|
|
|
|
# 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: /var/run/headscale/headscale.sock
|
|
|
|
# The file mode of `unix_socket`, in quoted octal (`"0770"`): unquoted, YAML
|
|
# reads `0770` as the number 504.
|
|
unix_socket_permission: "0770"
|
|
|
|
# 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: []
|
|
|
|
# Skips the check for a newer headscale release that commands make at start.
|
|
disable_check_updates: false
|
|
|
|
# The Noise protocol (TS2021) clients connect over.
|
|
noise:
|
|
# The file holding the Noise private key, which encrypts traffic between
|
|
# headscale and clients, relative to the configuration file. A missing file is
|
|
# created with a new key.
|
|
private_key_path: /var/lib/headscale/noise_private.key
|
|
|
|
# The IP ranges node addresses are allocated from. Keep at least one of
|
|
# `prefixes.v4` and `prefixes.v6`. Use the Tailscale ranges, `100.64.0.0/10` and
|
|
# `fd7a:115c:a1e0::/48`, or ranges inside them: the client assumes them, and
|
|
# other ranges are unsupported.
|
|
prefixes:
|
|
# The IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 address.
|
|
v4: 100.64.0.0/10
|
|
# The IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no IPv6
|
|
# address.
|
|
v6: fd7a:115c:a1e0::/48
|
|
# How a new node's addresses are picked.
|
|
# One of: `sequential`, `random`.
|
|
allocation: sequential
|
|
|
|
# Where the access control policy is kept: in a file headscale reads, or in the
|
|
# database. See [Policy](https://headscale.net/stable/ref/policy/).
|
|
policy:
|
|
# The HuJSON policy file read when `policy.mode` is `file`, relative to the
|
|
# configuration file. Empty starts without a policy, which allows all traffic.
|
|
path: ""
|
|
# Where the policy is kept: in the file `policy.path`, or in the database,
|
|
# edited through the CLI or API.
|
|
# One of: `file`, `database`.
|
|
mode: file
|
|
|
|
# Headscale's own log output. See
|
|
# [Debugging](https://headscale.net/stable/ref/debug/#application-logging).
|
|
log:
|
|
# The lowest level logged.
|
|
# One of: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`,
|
|
# `disabled`.
|
|
level: info
|
|
# How log lines are written.
|
|
# One of: `text`, `json`.
|
|
format: text
|
|
|
|
# Covers node key expiry, ephemeral nodes and subnet routes.
|
|
node:
|
|
# 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.
|
|
expiry: 0s
|
|
# Covers ephemeral nodes, which register with an ephemeral auth key and are
|
|
# deleted once they have been offline for `node.ephemeral.inactivity_timeout`.
|
|
ephemeral:
|
|
# How long an ephemeral node can be offline before it is automatically
|
|
# deleted. It must exceed 65s, the client keepalive plus a margin.
|
|
inactivity_timeout: 30m
|
|
# Covers the routes nodes advertise. See
|
|
# [Routes](https://headscale.net/stable/ref/routes/).
|
|
routes:
|
|
# 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](https://headscale.net/stable/ref/routes/#high-availability).
|
|
ha:
|
|
# 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.
|
|
probe_interval: 10s
|
|
# 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`.
|
|
probe_timeout: 5s
|
|
|
|
# Covers the cleanup of revoked pre-auth keys. See [Pre authenticated
|
|
# key](https://headscale.net/stable/ref/registration/#pre-authenticated-key).
|
|
preauth_keys:
|
|
# 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.
|
|
revoked_retention: 168h
|
|
|
|
# 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](https://headscale.net/stable/ref/derp/).
|
|
derp:
|
|
# The embedded DERP server, a relay and STUN server run by headscale itself.
|
|
# See [Enable embedded
|
|
# DERP](https://headscale.net/stable/ref/derp/#enable-embedded-derp).
|
|
server:
|
|
# Runs the embedded DERP server. DERP needs TLS, so `server_url` must be
|
|
# `https://`.
|
|
enabled: false
|
|
# The embedded server's region ID; required and positive when
|
|
# `derp.server.enabled` is true. Tailscale keeps 900-999 for your own
|
|
# regions. It replaces a region with the same ID from the other sources.
|
|
region_id: 0
|
|
# The region's short code, shown by Tailscale clients.
|
|
region_code: ""
|
|
# The region's name, shown by Tailscale clients.
|
|
region_name: ""
|
|
# Admits only nodes registered with this server.
|
|
verify_clients: true
|
|
# The UDP host:port of the STUN server, which helps clients with NAT
|
|
# traversal; required when `derp.server.enabled` is true.
|
|
stun_listen_addr: ""
|
|
# 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`.
|
|
private_key_path: ""
|
|
# The server's public IPv4 address, published in the DERP map so clients
|
|
# reach it without DNS. Empty publishes none.
|
|
ipv4: ""
|
|
# The server's public IPv6 address, published in the DERP map so clients
|
|
# reach it without DNS. Empty publishes none.
|
|
ipv6: ""
|
|
# 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.
|
|
automatically_add_embedded_derp_region: true
|
|
# DERP maps in JSON to fetch. One that fails to load is logged and skipped;
|
|
# startup fails only when no region remains. The default is Tailscale's map:
|
|
# headscale fetches it from Tailscale and clients relay through Tailscale's
|
|
# servers. `[]` keeps to your own.
|
|
urls:
|
|
- https://controlplane.tailscale.com/derpmap/default
|
|
# DERP map files. The extension picks the format: `.yaml` or `.yml`, or
|
|
# Tailscale JSON as `.json` or `.hujson`, both accepting comments and trailing
|
|
# commas.
|
|
paths: []
|
|
# Reloads `derp.urls` and `derp.paths` every `derp.update_frequency`.
|
|
auto_update_enabled: true
|
|
# How often `derp.auto_update_enabled` reloads the DERP map. Zero disables
|
|
# reloading.
|
|
update_frequency: 3h
|
|
|
|
# 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.
|
|
database:
|
|
# The database backend. SQLite is recommended; PostgreSQL is supported for
|
|
# legacy deployments only.
|
|
# One of: `sqlite`, `sqlite3`, `postgres`.
|
|
type: sqlite
|
|
# Turns on query logging: ordinary queries at log level debug, shown only when
|
|
# `log.level` is `debug` or `trace`, slow ones at warn and failed ones at
|
|
# error. Off, no query is logged. `database.gorm` shapes the query log. See
|
|
# [Database
|
|
# logging](https://headscale.net/stable/ref/debug/#database-logging).
|
|
debug: false
|
|
# Query logging, applied only when `database.debug` is true.
|
|
gorm:
|
|
# The query time, in milliseconds, above which a query is logged as a
|
|
# warning. Zero disables the warning.
|
|
slow_threshold: 0
|
|
# Logs a query that finds no record as an ordinary query, not as an error.
|
|
skip_err_record_not_found: false
|
|
# Logs queries without their parameter values.
|
|
parameterized_queries: false
|
|
# SQLite, read only when `database.type` is `sqlite` or `sqlite3`.
|
|
sqlite:
|
|
# The database file, relative to the configuration file; `:memory:` keeps
|
|
# the database in memory.
|
|
path: /var/lib/headscale/db.sqlite
|
|
# 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.
|
|
write_ahead_log: true
|
|
# 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.
|
|
wal_autocheckpoint: 1000
|
|
# PostgreSQL, read only when `database.type` is `postgres`. An empty `host`,
|
|
# `name`, `user`, `pass` or `ssl` leaves that setting to the driver, which
|
|
# reads the `PG*` environment variables and falls back to the defaults of
|
|
# libpq, PostgreSQL's client library: a local socket, the OS user, and TLS if
|
|
# the server offers it.
|
|
postgres:
|
|
# The server's host name or IP, or the directory of its Unix socket (a path
|
|
# starting with `/`).
|
|
host: ""
|
|
# 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.
|
|
port: 0
|
|
# The database name.
|
|
name: ""
|
|
# The user to connect as.
|
|
user: ""
|
|
# 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.
|
|
pass: ""
|
|
# The TLS mode: `true` keeps the driver's default `sslmode`, `false`
|
|
# disables TLS, any other value is passed as `sslmode` (`require`,
|
|
# `verify-full`, ...).
|
|
ssl: "false"
|
|
# Caps open connections to the database.
|
|
max_open_conns: 10
|
|
# Caps idle connections kept in the pool.
|
|
max_idle_conns: 10
|
|
# How long, in seconds, a connection may stay idle before it is closed.
|
|
conn_max_idle_time_secs: 3600
|
|
|
|
# The DNS configuration sent to clients, MagicDNS included, and TLS certificates
|
|
# for nodes. Clients apply it only with `--accept-dns`, their default. See
|
|
# [DNS](https://headscale.net/stable/ref/dns/).
|
|
dns:
|
|
# Gives each node a name below `dns.base_domain`, e.g. `laptop.example.com`,
|
|
# resolved by the client. It requires `dns.base_domain`.
|
|
magic_dns: true
|
|
# The domain MagicDNS names live under, without a trailing dot, e.g.
|
|
# `example.com`. The host of `server_url` must not be this domain or a name
|
|
# below it: clients take the domain over. The default is a private-use name,
|
|
# so `dns.certificates` needs a public domain you control.
|
|
base_domain: tailnet.internal
|
|
# Makes clients use `dns.nameservers.global` instead of their local DNS
|
|
# settings; with no global nameserver there is nothing to override with, and
|
|
# clients keep their own. False sends them only as fallback resolvers.
|
|
override_local_dns: true
|
|
# The upstream DNS servers sent to clients. An entry that is neither an IP
|
|
# address nor a URL is skipped with a warning.
|
|
nameservers:
|
|
# The nameservers for names `dns.nameservers.split` does not cover: IP
|
|
# addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/<id>`.
|
|
# Empty by default, so clients keep their own DNS: headscale points them at
|
|
# no resolver you did not list.
|
|
global: []
|
|
# Maps a domain to the nameservers that answer for it (split DNS). Domains
|
|
# are lowercased on load; two that differ only in case are an error.
|
|
split: {}
|
|
# DNS search domains sent to clients. With MagicDNS, `dns.base_domain` comes
|
|
# first.
|
|
search_domains: []
|
|
# 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](https://headscale.net/stable/ref/dns/#setting-extra-dns-records).
|
|
extra_records: []
|
|
# 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`.
|
|
extra_records_path: ""
|
|
# 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`.
|
|
certificates:
|
|
# Lets nodes run `tailscale cert`. It requires `dns.magic_dns`, a lowercase
|
|
# `dns.base_domain` and `dns.challenge.provider`.
|
|
enabled: false
|
|
# 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`.
|
|
zone: ""
|
|
# 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](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider).
|
|
challenge:
|
|
# How long to wait for a challenge record to show up on every authoritative
|
|
# nameserver. Zero skips the check.
|
|
propagation_timeout: 2m
|
|
# 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.
|
|
resolvers:
|
|
- 9.9.9.9:53
|
|
- 149.112.112.112:53
|
|
# 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](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider)
|
|
# to set a provider up, acme-dns included, and to set it from environment
|
|
# variables.
|
|
provider: {}
|
|
|
|
# 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](https://headscale.net/stable/ref/tls/).
|
|
tls:
|
|
# The PEM certificate file, relative to the configuration file. Setting it
|
|
# turns TLS on.
|
|
cert_path: ""
|
|
# The PEM private key file of `tls.cert_path`, relative to the configuration
|
|
# file.
|
|
key_path: ""
|
|
# Gets the certificate from an ACME CA such as Let's Encrypt, and renews it.
|
|
# Setting `tls.acme.hostname` turns it on.
|
|
acme:
|
|
# The domain to request a certificate for. Setting it turns ACME on.
|
|
hostname: ""
|
|
# How the CA verifies that headscale controls `tls.acme.hostname`.
|
|
# One of: `HTTP-01`, `TLS-ALPN-01`, `DNS-01`.
|
|
challenge_type: HTTP-01
|
|
# 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`.
|
|
http_listen: :http
|
|
# The CA's ACME directory. Empty uses Let's Encrypt.
|
|
url: ""
|
|
# The contact address registered with the CA.
|
|
email: ""
|
|
# Where certificates and ACME account data are stored, relative to the
|
|
# configuration file.
|
|
cache_dir: /var/lib/headscale/cache
|
|
|
|
# Login through an OpenID Connect provider. Setting `oidc.issuer` turns it on
|
|
# and requires `oidc.client_id` and `oidc.client_secret`. See [OpenID
|
|
# Connect](https://headscale.net/stable/ref/oidc/).
|
|
oidc:
|
|
# Stops startup when the provider cannot be reached. False starts without
|
|
# OIDC, with CLI-based registration.
|
|
only_start_if_oidc_is_available: true
|
|
# The provider's issuer URL. Setting it turns OIDC on.
|
|
issuer: ""
|
|
# The client ID from the provider; required when `oidc.issuer` is set.
|
|
client_id: ""
|
|
# 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.
|
|
client_secret: ""
|
|
# The scopes requested; include `openid`.
|
|
scope:
|
|
- openid
|
|
- profile
|
|
- email
|
|
# Sent as is to the provider's authorization endpoint, e.g. `domain_hint`;
|
|
# names keep their case.
|
|
extra_params: {}
|
|
# Admits only users whose email domain is listed. Empty admits any domain.
|
|
allowed_domains: []
|
|
# Admits only users whose email address is listed. Empty admits any user.
|
|
allowed_users: []
|
|
# 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.
|
|
allowed_groups: []
|
|
# 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`.
|
|
email_verified_required: true
|
|
# Expires an OIDC-registered node with its token, instead of `node.expiry`.
|
|
# Tokens are often short-lived, forcing frequent logins.
|
|
use_expiry_from_token: false
|
|
# Proof Key for Code Exchange (RFC 7636), which protects the authorization
|
|
# code from interception. See [Enable
|
|
# PKCE](https://headscale.net/stable/ref/oidc/#enable-pkce-recommended).
|
|
pkce:
|
|
# Sends a PKCE challenge with each login.
|
|
enabled: false
|
|
# How the code challenge is derived from the verifier. The verifier is sent
|
|
# as is in the token exchange.
|
|
# One of: `plain`, `S256`.
|
|
method: S256
|
|
|
|
# Whether nodes send their logs to Tailscale.
|
|
logtail:
|
|
# Lets nodes send their logs to Tailscale Inc.; headscale cannot point them at
|
|
# another log server. False tells nodes not to.
|
|
enabled: false
|
|
|
|
# Taildrop, Tailscale's file sharing between nodes.
|
|
taildrop:
|
|
# Gives every node the file-sharing capability. False omits it from the
|
|
# baseline; a policy `nodeAttrs` grant can still give it.
|
|
enabled: true
|
|
|
|
# The tailnet-wide default for client auto-updates.
|
|
auto_update:
|
|
# 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.
|
|
enabled: false
|
|
|
|
# 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](https://headscale.net/stable/ref/api/#remote-control).
|
|
cli:
|
|
# The remote server's host:port or URL; `https://` is assumed without a
|
|
# scheme. Empty uses `unix_socket`.
|
|
address: ""
|
|
# The API key the CLI sends to `cli.address`, or `file:<path>` to read it from
|
|
# a file. Read only by the CLI.
|
|
api_key: ""
|
|
# Bounds each CLI command's requests to the server.
|
|
timeout: 5s
|
|
# Skips TLS certificate verification of `cli.address`.
|
|
insecure: false
|
|
|
|
# Holds performance settings that rarely need changing.
|
|
tuning:
|
|
# How often queued changes are sent to clients as one update; must be
|
|
# positive.
|
|
batch_change_delay: 800ms
|
|
# How many map updates are queued per connected client.
|
|
node_mapsession_buffered_chan_size: 30
|
|
# The number of workers building map updates for connected clients. Zero picks
|
|
# the number from the CPU count.
|
|
# Default: three quarters of the CPU cores, at least one.
|
|
batcher_workers: 0
|
|
# How long a pending registration waits to be completed. Zero uses the
|
|
# default.
|
|
register_cache_expiration: 15m
|
|
# 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](https://headscale.net/stable/ref/registration/#pending-authentication-limits).
|
|
register_cache_max_entries: 1024
|
|
# 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.
|
|
node_store_batch_size: 100
|
|
# 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.
|
|
node_store_batch_timeout: 500ms
|