mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-19 11:57:07 +09:00
1 parent
e9abc6ae35
commit
d835c9c6bf
3 files changed
+560
-156
No files matched your search
+12
-8
@@ -149,8 +149,9 @@ node:
|
||||
#
|
||||
# If a client explicitly requests a specific expiry, the client value is used.
|
||||
#
|
||||
# Setting the value to "0" means no default expiry (nodes never expire unless
|
||||
# explicitly expired via `headscale nodes expire`).
|
||||
# Setting the value to "0" means no default expiry: a node expires only when
|
||||
# its client asks for an expiry, oidc.use_expiry_from_token sets one, or an
|
||||
# admin runs `headscale nodes expire`.
|
||||
#
|
||||
# Tailscale SaaS uses 180d; set to a positive duration to match that behaviour.
|
||||
#
|
||||
@@ -190,9 +191,9 @@ database:
|
||||
# Enable debug mode. This setting requires the log.level to be set to "debug" or "trace".
|
||||
debug: false
|
||||
|
||||
# GORM configuration settings.
|
||||
# Query logging settings; they apply only when database.debug is true.
|
||||
gorm:
|
||||
# Enable parameterized queries.
|
||||
# Log queries without their parameter values.
|
||||
parameterized_queries: true
|
||||
|
||||
# Skip logging "record not found" errors.
|
||||
@@ -205,7 +206,9 @@ database:
|
||||
sqlite:
|
||||
path: /var/lib/headscale/db.sqlite
|
||||
|
||||
# Enable WAL mode for SQLite. This is recommended for production environments.
|
||||
# SQLite runs in WAL mode whether or not this is set. true applies
|
||||
# wal_autocheckpoint below (false keeps 1000) and compacts the database
|
||||
# (VACUUM) on shutdown.
|
||||
# https://www.sqlite.org/wal.html
|
||||
write_ahead_log: true
|
||||
|
||||
@@ -218,7 +221,8 @@ database:
|
||||
# Please note that using Postgres is highly discouraged as it is only supported for legacy reasons.
|
||||
# See database.type for more information.
|
||||
# postgres:
|
||||
# # If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank.
|
||||
# # To connect over a Unix socket, set 'host' to the socket's directory; 'port' then picks the
|
||||
# # socket file (.s.PGSQL.<port>), and leaving it out uses the driver's default port.
|
||||
# host: localhost
|
||||
# port: 5432
|
||||
# name: headscale
|
||||
@@ -229,8 +233,8 @@ database:
|
||||
# max_idle_conns: 10
|
||||
# conn_max_idle_time_secs: 3600
|
||||
|
||||
# # If other 'sslmode' is required instead of 'require(true)' and 'disabled(false)', set the 'sslmode' you need
|
||||
# # in the 'ssl' field. Refers to https://www.postgresql.org/docs/current/libpq-ssl.html Table 34.1.
|
||||
# # 'true' keeps the driver's default sslmode (prefer), 'false' disables TLS. Any other value is used as the
|
||||
# # sslmode. Refers to https://www.postgresql.org/docs/current/libpq-ssl.html Table 34.1.
|
||||
# ssl: false
|
||||
|
||||
### TLS configuration
|
||||
|
||||
+474
-148
@@ -65,23 +65,31 @@ const (
|
||||
// EphemeralConfig contains configuration for ephemeral node lifecycle.
|
||||
type EphemeralConfig struct {
|
||||
// InactivityTimeout is how long an ephemeral node can be offline
|
||||
// before it is automatically deleted.
|
||||
// before it is automatically deleted. It must exceed 65s, the client
|
||||
// keepalive plus a margin.
|
||||
InactivityTimeout time.Duration `koanf:"inactivity_timeout"`
|
||||
}
|
||||
|
||||
// HARouteConfig contains configuration for HA subnet router health probing.
|
||||
// When two or more nodes advertise the same route, each is pinged over
|
||||
// Noise. One that does not answer in time is marked unhealthy and, if
|
||||
// primary, hands that role to the next healthy node; it does not take it
|
||||
// back when it recovers.
|
||||
type HARouteConfig struct {
|
||||
// ProbeInterval is how often HA subnet routers are probed.
|
||||
// A zero or negative duration disables probing.
|
||||
// ProbeInterval is how often HA subnet routers are probed; a positive
|
||||
// interval must be at least 2s. Zero or negative disables probing,
|
||||
// and with it the [HARouteConfig.ProbeTimeout] rules.
|
||||
ProbeInterval time.Duration `koanf:"probe_interval"`
|
||||
|
||||
// ProbeTimeout is the maximum time to wait for a probe response
|
||||
// before declaring a node unhealthy. Must be less than [HARouteConfig.ProbeInterval].
|
||||
// before declaring a node unhealthy; at least 1s and less than
|
||||
// [HARouteConfig.ProbeInterval].
|
||||
ProbeTimeout time.Duration `koanf:"probe_timeout"`
|
||||
}
|
||||
|
||||
// RouteConfig contains configuration for route behaviour.
|
||||
type RouteConfig struct {
|
||||
// HA configures health probing of HA subnet routers.
|
||||
HA HARouteConfig `koanf:"ha"`
|
||||
}
|
||||
|
||||
@@ -96,10 +104,11 @@ type PreAuthKeysConfig struct {
|
||||
|
||||
// NodeConfig contains configuration for node lifecycle and expiry.
|
||||
type NodeConfig struct {
|
||||
// Expiry is the default key expiry duration for non-tagged nodes.
|
||||
// Applies to all registration methods (auth key, CLI, web, OIDC).
|
||||
// Tagged nodes are exempt and never expire.
|
||||
// A zero/negative duration means no default expiry (nodes never expire).
|
||||
// Expiry is 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 time.Duration `koanf:"expiry"`
|
||||
|
||||
// Ephemeral contains configuration for ephemeral node lifecycle.
|
||||
@@ -110,33 +119,97 @@ type NodeConfig struct {
|
||||
}
|
||||
|
||||
// Config is the Headscale configuration, nested like the configuration
|
||||
// file; koanf tags name the keys.
|
||||
// file; koanf tags name the keys. A duration needs a unit (30s, 3h, 90d),
|
||||
// except 0.
|
||||
type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Config value is redacted too
|
||||
ServerURL string `koanf:"server_url"`
|
||||
Addr ListenAddr `koanf:"listen_addr"`
|
||||
MetricsAddr ListenAddr `koanf:"metrics_listen_addr"`
|
||||
UnixSocket string `koanf:"unix_socket"`
|
||||
UnixSocketPermission FileMode `koanf:"unix_socket_permission"`
|
||||
TrustedProxies []netip.Prefix `koanf:"trusted_proxies"`
|
||||
DisableUpdateCheck bool `koanf:"disable_check_updates"`
|
||||
Noise NoiseConfig `koanf:"noise"`
|
||||
Prefixes PrefixesConfig `koanf:"prefixes"`
|
||||
Policy PolicyConfig `koanf:"policy"`
|
||||
Log LogConfig `koanf:"log"`
|
||||
Node NodeConfig `koanf:"node"`
|
||||
PreAuthKeys PreAuthKeysConfig `koanf:"preauth_keys"`
|
||||
DERP DERPConfig `koanf:"derp"`
|
||||
Database DatabaseConfig `koanf:"database"`
|
||||
DNSConfig DNSConfig `koanf:"dns"`
|
||||
TLS TLSConfig `koanf:"tls"`
|
||||
OIDC OIDCConfig `koanf:"oidc"`
|
||||
LogTail LogTailConfig `koanf:"logtail"`
|
||||
Taildrop TaildropConfig `koanf:"taildrop"`
|
||||
AutoUpdate AutoUpdateConfig `koanf:"auto_update"`
|
||||
CLI CLIConfig `koanf:"cli"`
|
||||
Tuning Tuning `koanf:"tuning"`
|
||||
// ServerURL is 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.
|
||||
ServerURL string `koanf:"server_url"`
|
||||
|
||||
// ConfigDir is where [Config.AbsPath] resolves relative paths.
|
||||
// Addr is the host:port the server listens on for clients, the API and
|
||||
// the web pages, with TLS when [Config.TLS] sets it up.
|
||||
Addr ListenAddr `koanf:"listen_addr"`
|
||||
|
||||
// MetricsAddr is the host:port serving /metrics and /debug; keep it
|
||||
// private. Empty disables this listener.
|
||||
MetricsAddr ListenAddr `koanf:"metrics_listen_addr"`
|
||||
|
||||
// UnixSocket is 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.
|
||||
UnixSocket string `koanf:"unix_socket"`
|
||||
|
||||
// UnixSocketPermission is the file mode of [Config.UnixSocket], in
|
||||
// quoted octal ("0770"): unquoted, YAML reads 0770 as the number 504.
|
||||
UnixSocketPermission FileMode `koanf:"unix_socket_permission"`
|
||||
|
||||
// TrustedProxies are 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.
|
||||
TrustedProxies []netip.Prefix `koanf:"trusted_proxies"`
|
||||
|
||||
// DisableUpdateCheck skips the check for a newer headscale release
|
||||
// that commands make at start.
|
||||
DisableUpdateCheck bool `koanf:"disable_check_updates"`
|
||||
|
||||
// Noise configures the Noise (TS2021) protocol clients connect over.
|
||||
Noise NoiseConfig `koanf:"noise"`
|
||||
|
||||
// Prefixes are the ranges node IPs are allocated from.
|
||||
Prefixes PrefixesConfig `koanf:"prefixes"`
|
||||
|
||||
// Policy is where the access control policy is stored.
|
||||
Policy PolicyConfig `koanf:"policy"`
|
||||
|
||||
// Log configures headscale's own log output.
|
||||
Log LogConfig `koanf:"log"`
|
||||
|
||||
// Node configures node expiry, ephemeral nodes and HA routes.
|
||||
Node NodeConfig `koanf:"node"`
|
||||
|
||||
// PreAuthKeys configures the cleanup of revoked pre-auth keys.
|
||||
PreAuthKeys PreAuthKeysConfig `koanf:"preauth_keys"`
|
||||
|
||||
// DERP configures the relay servers clients are given, and the
|
||||
// embedded one.
|
||||
DERP DERPConfig `koanf:"derp"`
|
||||
|
||||
// Database selects and configures the database.
|
||||
Database DatabaseConfig `koanf:"database"`
|
||||
|
||||
// DNSConfig is the DNS configuration sent to clients, and node
|
||||
// certificates. Clients apply it only with --accept-dns, their default.
|
||||
DNSConfig DNSConfig `koanf:"dns"`
|
||||
|
||||
// TLS configures HTTPS on [Config.Addr]: a certificate from files or
|
||||
// from ACME. Unset, the server speaks plain HTTP.
|
||||
TLS TLSConfig `koanf:"tls"`
|
||||
|
||||
// OIDC configures login through an OpenID Connect provider. It is on
|
||||
// when oidc.issuer is set.
|
||||
OIDC OIDCConfig `koanf:"oidc"`
|
||||
|
||||
// LogTail controls whether nodes send their logs to Tailscale.
|
||||
LogTail LogTailConfig `koanf:"logtail"`
|
||||
|
||||
// Taildrop controls file sharing between nodes.
|
||||
Taildrop TaildropConfig `koanf:"taildrop"`
|
||||
|
||||
// AutoUpdate sets the tailnet-wide default for client auto-updates.
|
||||
AutoUpdate AutoUpdateConfig `koanf:"auto_update"`
|
||||
|
||||
// CLI configures how the headscale CLI reaches the server.
|
||||
CLI CLIConfig `koanf:"cli"`
|
||||
|
||||
// Tuning holds performance settings that rarely need changing.
|
||||
Tuning Tuning `koanf:"tuning"`
|
||||
|
||||
// ConfigDir is where [Config.AbsPath] resolves relative paths: the
|
||||
// configuration file's directory, or the working directory without
|
||||
// one. Set by the loader or from Go; it cannot be set from a file.
|
||||
ConfigDir string `json:"-" koanf:"-"`
|
||||
|
||||
// dns is nil until [Config.StartDNS].
|
||||
@@ -145,13 +218,28 @@ type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Confi
|
||||
|
||||
// NoiseConfig is the key of the Noise protocol clients connect over.
|
||||
type NoiseConfig struct {
|
||||
// PrivateKeyPath is the file holding the Noise private key, which
|
||||
// encrypts traffic between headscale and clients. A missing file is
|
||||
// created with a new key. Relative to the configuration file.
|
||||
PrivateKeyPath string `koanf:"private_key_path"`
|
||||
}
|
||||
|
||||
// PrefixesConfig are the ranges node IPs are allocated from.
|
||||
// PrefixesConfig are the ranges node IPs are allocated from. At least one
|
||||
// is required. Use the Tailscale ranges (100.64.0.0/10, fd7a:115c:a1e0::/48)
|
||||
// or subsets of them: the client assumes them, and breaks in subtle ways
|
||||
// outside them.
|
||||
type PrefixesConfig struct {
|
||||
V4 *netip.Prefix `koanf:"v4"`
|
||||
V6 *netip.Prefix `koanf:"v6"`
|
||||
// V4 is the IPv4 range, e.g. 100.64.0.0/10. Unset gives nodes no IPv4
|
||||
// address.
|
||||
V4 *netip.Prefix `koanf:"v4"`
|
||||
|
||||
// V6 is the IPv6 range, e.g. fd7a:115c:a1e0::/48. Unset gives nodes no
|
||||
// IPv6 address.
|
||||
V6 *netip.Prefix `koanf:"v6"`
|
||||
|
||||
// Allocation is how a new node's IPs are picked: sequential takes the
|
||||
// next free address after the last one handed out, random picks a free
|
||||
// one at random.
|
||||
Allocation IPAllocationStrategy `koanf:"allocation"`
|
||||
}
|
||||
|
||||
@@ -164,25 +252,59 @@ type liveDNS struct {
|
||||
provider hsdns.Provider
|
||||
}
|
||||
|
||||
// DNSConfig is the DNS configuration clients get. To keep headscale out of
|
||||
// clients' DNS, set every field to its empty value.
|
||||
type DNSConfig struct {
|
||||
MagicDNS bool `koanf:"magic_dns"`
|
||||
BaseDomain string `koanf:"base_domain"`
|
||||
OverrideLocalDNS bool `koanf:"override_local_dns"`
|
||||
Nameservers Nameservers `koanf:"nameservers"`
|
||||
SearchDomains []string `koanf:"search_domains"`
|
||||
ExtraRecords []tailcfg.DNSRecord `koanf:"extra_records"`
|
||||
ExtraRecordsPath string `koanf:"extra_records_path"`
|
||||
Certificates CertificatesConfig `koanf:"certificates"`
|
||||
Challenge DNSChallengeConfig `koanf:"challenge"`
|
||||
// MagicDNS gives each node the name hostname.base_domain, resolved by
|
||||
// the client. It requires [DNSConfig.BaseDomain].
|
||||
MagicDNS bool `koanf:"magic_dns"`
|
||||
|
||||
// BaseDomain is the domain MagicDNS names live under, without a
|
||||
// trailing dot, e.g. example.com. server_url's host must not be this
|
||||
// domain or a name below it: clients take the domain over.
|
||||
BaseDomain string `koanf:"base_domain"`
|
||||
|
||||
// OverrideLocalDNS makes clients use [Nameservers.Global] instead of
|
||||
// their local DNS settings, which then requires at least one global
|
||||
// nameserver. False sends them only as fallback resolvers.
|
||||
OverrideLocalDNS bool `koanf:"override_local_dns"`
|
||||
|
||||
// Nameservers are the upstream DNS servers sent to clients.
|
||||
Nameservers Nameservers `koanf:"nameservers"`
|
||||
|
||||
// SearchDomains are DNS search domains sent to clients. With MagicDNS,
|
||||
// base_domain comes first.
|
||||
SearchDomains []string `koanf:"search_domains"`
|
||||
|
||||
// ExtraRecords are DNS records served to clients, each with a name,
|
||||
// type and value. Clients support A and AAAA. Mutually exclusive with
|
||||
// [DNSConfig.ExtraRecordsPath].
|
||||
ExtraRecords []tailcfg.DNSRecord `koanf:"extra_records"`
|
||||
|
||||
// ExtraRecordsPath is a file of extra records, reloaded when it
|
||||
// changes. The extension picks the format: .json, .hujson, .yaml or
|
||||
// .yml. Mutually exclusive with [DNSConfig.ExtraRecords].
|
||||
ExtraRecordsPath string `koanf:"extra_records_path"`
|
||||
|
||||
// Certificates lets nodes get TLS certificates for their MagicDNS
|
||||
// names.
|
||||
Certificates CertificatesConfig `koanf:"certificates"`
|
||||
|
||||
// Challenge is the DNS provider answering ACME DNS-01 challenges.
|
||||
Challenge DNSChallengeConfig `koanf:"challenge"`
|
||||
}
|
||||
|
||||
// CertificatesConfig lets nodes get TLS certificates for their MagicDNS
|
||||
// name with `tailscale cert`. The node runs ACME itself; headscale
|
||||
// publishes its DNS-01 challenge through [DNSChallengeConfig].
|
||||
type CertificatesConfig struct {
|
||||
// Enabled lets nodes run `tailscale cert`. It requires MagicDNS, a
|
||||
// lowercase base_domain and dns.challenge.provider.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
|
||||
// Zone is the public DNS zone challenge records are written to, when
|
||||
// base_domain sits below the zone apex. See [DNSConfig.CertificateZone].
|
||||
// base_domain sits below the zone apex. Empty uses base_domain. See
|
||||
// [DNSConfig.CertificateZone].
|
||||
Zone string `koanf:"zone"`
|
||||
}
|
||||
|
||||
@@ -195,13 +317,23 @@ func (d DNSConfig) CertificateZone() string {
|
||||
// DNSChallengeConfig is the DNS provider answering ACME DNS-01
|
||||
// challenges for node certificates and headscale's own certificate.
|
||||
type DNSChallengeConfig struct {
|
||||
// PropagationTimeout is how long to wait for a challenge record to
|
||||
// show up on every authoritative nameserver. Zero skips the check.
|
||||
PropagationTimeout time.Duration `koanf:"propagation_timeout"`
|
||||
Resolvers []string `koanf:"resolvers"`
|
||||
// ProviderSettings is dns.challenge.provider, name included. Never
|
||||
// serialised: its settings are credentials.
|
||||
|
||||
// Resolvers find the zone's nameservers, each an IP or host with an
|
||||
// optional port (53 if omitted). Empty uses public resolvers, not the
|
||||
// system's.
|
||||
Resolvers []string `koanf:"resolvers"`
|
||||
|
||||
// ProviderSettings is dns.challenge.provider: name selects the
|
||||
// provider, the other keys are its settings, lowercased on load at
|
||||
// every depth. A string setting may be "file:<path>" to read it from
|
||||
// a file. Never serialised: its settings are credentials.
|
||||
ProviderSettings map[string]any `json:"-" koanf:"provider"`
|
||||
// Provider is set only from Go, by an embedder or a test, and wins
|
||||
// over ProviderSettings. The loader never sets it.
|
||||
|
||||
// Provider is a DNS provider set from Go, by an embedder or a test; it
|
||||
// cannot be set from a file. It wins over ProviderSettings.
|
||||
Provider hsdns.Provider `json:"-" koanf:"-"`
|
||||
}
|
||||
|
||||
@@ -262,27 +394,71 @@ func (c DNSChallengeConfig) ResolverAddrs() []string {
|
||||
return addrs
|
||||
}
|
||||
|
||||
// Nameservers are the upstream DNS servers sent to clients. An entry that
|
||||
// is neither an IP address nor a URL is skipped with a warning.
|
||||
type Nameservers struct {
|
||||
Global []string `koanf:"global"`
|
||||
Split map[string][]string `koanf:"split"`
|
||||
// Global are the nameservers for names Split does not cover: IP
|
||||
// addresses, or DNS-over-HTTPS URLs such as
|
||||
// https://dns.nextdns.io/<id>.
|
||||
Global []string `koanf:"global"`
|
||||
|
||||
// Split maps a domain to the nameservers that answer for it (split
|
||||
// DNS). Domains are lowercased on load.
|
||||
Split map[string][]string `koanf:"split"`
|
||||
}
|
||||
|
||||
// SqliteConfig configures the SQLite database.
|
||||
type SqliteConfig struct {
|
||||
Path string `koanf:"path"`
|
||||
WriteAheadLog bool `koanf:"write_ahead_log"`
|
||||
WALAutoCheckPoint int `koanf:"wal_autocheckpoint"`
|
||||
// Path is the database file, relative to the configuration file;
|
||||
// ":memory:" keeps the database in memory.
|
||||
Path string `koanf:"path"`
|
||||
|
||||
// WriteAheadLog applies [SqliteConfig.WALAutoCheckPoint] and compacts
|
||||
// the database (VACUUM) on shutdown. SQLite runs in WAL mode either
|
||||
// way; false keeps the default checkpoint of 1000 frames.
|
||||
WriteAheadLog bool `koanf:"write_ahead_log"`
|
||||
|
||||
// WALAutoCheckPoint is the number of WAL frames after which the WAL
|
||||
// is checkpointed automatically; zero disables automatic checkpoints.
|
||||
// Applied only when write_ahead_log is true.
|
||||
WALAutoCheckPoint int `koanf:"wal_autocheckpoint"`
|
||||
}
|
||||
|
||||
// PostgresConfig configures the PostgreSQL database, supported for legacy
|
||||
// deployments only.
|
||||
type PostgresConfig struct {
|
||||
Host string `koanf:"host"`
|
||||
Port int `koanf:"port"`
|
||||
Name string `koanf:"name"`
|
||||
User string `koanf:"user"`
|
||||
Pass Secret `json:"-" koanf:"pass"` // never serialise the database password
|
||||
Ssl string `koanf:"ssl"`
|
||||
MaxOpenConnections int `koanf:"max_open_conns"`
|
||||
MaxIdleConnections int `koanf:"max_idle_conns"`
|
||||
ConnMaxIdleTimeSecs int `koanf:"conn_max_idle_time_secs"`
|
||||
// Host is the server's host name or IP, or the directory of its Unix
|
||||
// socket (a path starting with /).
|
||||
Host string `koanf:"host"`
|
||||
|
||||
// Port is the server's port, or with a Unix socket directory as Host,
|
||||
// the port in the socket's file name. Zero uses the driver's default.
|
||||
Port int `koanf:"port"`
|
||||
|
||||
// Name is the database name.
|
||||
Name string `koanf:"name"`
|
||||
|
||||
// User is the user to connect as.
|
||||
User string `koanf:"user"`
|
||||
|
||||
// Pass is the password, or "file:<path>" to read it from a file. Read
|
||||
// only for PostgreSQL. Never serialised.
|
||||
Pass Secret `json:"-" koanf:"pass"`
|
||||
|
||||
// Ssl is the TLS mode: "true" keeps the driver's default sslmode,
|
||||
// "false" disables TLS, any other value is passed as sslmode
|
||||
// (require, verify-full, ...).
|
||||
Ssl string `koanf:"ssl"`
|
||||
|
||||
// MaxOpenConnections caps open connections to the database.
|
||||
MaxOpenConnections int `koanf:"max_open_conns"`
|
||||
|
||||
// MaxIdleConnections caps idle connections kept in the pool.
|
||||
MaxIdleConnections int `koanf:"max_idle_conns"`
|
||||
|
||||
// ConnMaxIdleTimeSecs is how long, in seconds, a connection may stay
|
||||
// idle before it is closed.
|
||||
ConnMaxIdleTimeSecs int `koanf:"conn_max_idle_time_secs"`
|
||||
}
|
||||
|
||||
// DSN returns the connection string for this configuration as a
|
||||
@@ -340,21 +516,38 @@ func (cfg PostgresConfig) DSN() string {
|
||||
return u.String()
|
||||
}
|
||||
|
||||
// GormConfig configures query logging; it applies only with
|
||||
// database.debug.
|
||||
type GormConfig struct {
|
||||
// SlowThreshold is in milliseconds.
|
||||
SlowThreshold int `koanf:"slow_threshold"`
|
||||
// SlowThreshold is the query time, in milliseconds, above which a
|
||||
// query is logged as a warning. Zero disables the warning.
|
||||
SlowThreshold int `koanf:"slow_threshold"`
|
||||
|
||||
// SkipErrRecordNotFound leaves "record not found" errors out of the
|
||||
// log.
|
||||
SkipErrRecordNotFound bool `koanf:"skip_err_record_not_found"`
|
||||
ParameterizedQueries bool `koanf:"parameterized_queries"`
|
||||
|
||||
// ParameterizedQueries logs queries without their parameter values.
|
||||
ParameterizedQueries bool `koanf:"parameterized_queries"`
|
||||
}
|
||||
|
||||
// DatabaseConfig selects and configures the database.
|
||||
type DatabaseConfig struct {
|
||||
// Type is the database backend. SQLite is recommended; PostgreSQL is
|
||||
// supported for legacy deployments only.
|
||||
Type DatabaseType `koanf:"type"`
|
||||
// Debug logs queries through [GormConfig].
|
||||
|
||||
// Debug logs database queries at log level debug, as
|
||||
// [DatabaseConfig.Gorm] configures.
|
||||
Debug bool `koanf:"debug"`
|
||||
|
||||
// Gorm configures query logging.
|
||||
Gorm GormConfig `koanf:"gorm"`
|
||||
|
||||
Sqlite SqliteConfig `koanf:"sqlite"`
|
||||
// Sqlite configures SQLite, used when Type names it.
|
||||
Sqlite SqliteConfig `koanf:"sqlite"`
|
||||
|
||||
// Postgres configures PostgreSQL, used when Type is postgres.
|
||||
Postgres PostgresConfig `koanf:"postgres"`
|
||||
}
|
||||
|
||||
@@ -363,73 +556,194 @@ func (d DatabaseConfig) IsSQLite() bool {
|
||||
return d.Type == DatabaseSqlite || d.Type == "sqlite"
|
||||
}
|
||||
|
||||
// TLSConfig is headscale's own certificate: from files, or from ACME. The
|
||||
// two are mutually exclusive.
|
||||
type TLSConfig struct {
|
||||
// CertPath is the PEM certificate file, relative to the configuration
|
||||
// file. Setting it turns TLS on.
|
||||
CertPath string `koanf:"cert_path"`
|
||||
KeyPath string `koanf:"key_path"`
|
||||
|
||||
// KeyPath is the PEM private key file of [TLSConfig.CertPath],
|
||||
// relative to the configuration file.
|
||||
KeyPath string `koanf:"key_path"`
|
||||
|
||||
// ACME gets the certificate from an ACME CA such as Let's Encrypt.
|
||||
ACME ACMEConfig `koanf:"acme"`
|
||||
}
|
||||
|
||||
// ACMEConfig gets headscale's own certificate from an ACME CA.
|
||||
type ACMEConfig struct {
|
||||
Hostname string `koanf:"hostname"`
|
||||
// Hostname is the domain to request a certificate for. Setting it
|
||||
// turns ACME on.
|
||||
Hostname string `koanf:"hostname"`
|
||||
|
||||
// ChallengeType is how the CA verifies the domain. DNS-01 publishes
|
||||
// the challenge through dns.challenge.
|
||||
ChallengeType ACMEChallenge `koanf:"challenge_type"`
|
||||
// HTTPListen serves HTTP-01 challenges.
|
||||
|
||||
// HTTPListen is the host:port serving HTTP-01 challenges; the port
|
||||
// may be a name, as in ":http" for port 80.
|
||||
HTTPListen ListenAddr `koanf:"http_listen"`
|
||||
URL HTTPURL `koanf:"url"`
|
||||
Email string `koanf:"email"`
|
||||
CacheDir string `koanf:"cache_dir"`
|
||||
|
||||
// URL is the CA's ACME directory. Empty uses Let's Encrypt.
|
||||
URL HTTPURL `koanf:"url"`
|
||||
|
||||
// Email is the contact address registered with the CA.
|
||||
Email string `koanf:"email"`
|
||||
|
||||
// CacheDir is where certificates and ACME account data are stored,
|
||||
// relative to the configuration file.
|
||||
CacheDir string `koanf:"cache_dir"`
|
||||
}
|
||||
|
||||
// PKCEConfig configures PKCE (RFC 7636), which protects the OIDC
|
||||
// authorization code from interception.
|
||||
type PKCEConfig struct {
|
||||
Enabled bool `koanf:"enabled"`
|
||||
Method PKCEMethod `koanf:"method"`
|
||||
// Enabled sends a PKCE challenge with each login.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
|
||||
// Method is how the code challenge is derived from the verifier: S256
|
||||
// (base64url SHA-256, recommended) or plain (the verifier itself). The
|
||||
// verifier is sent as is in the token exchange.
|
||||
Method PKCEMethod `koanf:"method"`
|
||||
}
|
||||
|
||||
// OIDCConfig configures login through an OpenID Connect provider.
|
||||
type OIDCConfig struct {
|
||||
OnlyStartIfOIDCIsAvailable bool `koanf:"only_start_if_oidc_is_available"`
|
||||
Issuer HTTPURL `koanf:"issuer"`
|
||||
ClientID string `koanf:"client_id"`
|
||||
ClientSecret Secret `json:"-" koanf:"client_secret"` // never serialise the OIDC client secret
|
||||
Scope []string `koanf:"scope"`
|
||||
ExtraParams map[string]string `koanf:"extra_params"`
|
||||
AllowedDomains []string `koanf:"allowed_domains"`
|
||||
AllowedUsers []string `koanf:"allowed_users"`
|
||||
AllowedGroups []string `koanf:"allowed_groups"`
|
||||
EmailVerifiedRequired bool `koanf:"email_verified_required"`
|
||||
UseExpiryFromToken bool `koanf:"use_expiry_from_token"`
|
||||
PKCE PKCEConfig `koanf:"pkce"`
|
||||
// OnlyStartIfOIDCIsAvailable stops startup when the provider cannot be
|
||||
// reached. False starts without OIDC, with CLI-based registration.
|
||||
OnlyStartIfOIDCIsAvailable bool `koanf:"only_start_if_oidc_is_available"`
|
||||
|
||||
// Issuer is the provider's issuer URL. Setting it turns OIDC on.
|
||||
Issuer HTTPURL `koanf:"issuer"`
|
||||
|
||||
// ClientID is the client ID from the provider; required with Issuer.
|
||||
ClientID string `koanf:"client_id"`
|
||||
|
||||
// ClientSecret is the client secret from the provider, or
|
||||
// "file:<path>" to read it from a file; required with Issuer. Never
|
||||
// serialised.
|
||||
ClientSecret Secret `json:"-" koanf:"client_secret"`
|
||||
|
||||
// Scope are the scopes requested; include "openid".
|
||||
Scope []string `koanf:"scope"`
|
||||
|
||||
// ExtraParams are sent as is to the provider's authorization endpoint,
|
||||
// e.g. domain_hint; names keep their case.
|
||||
ExtraParams map[string]string `koanf:"extra_params"`
|
||||
|
||||
// AllowedDomains admits only users whose email domain is listed.
|
||||
// Empty admits any domain.
|
||||
AllowedDomains []string `koanf:"allowed_domains"`
|
||||
|
||||
// AllowedUsers admits only users whose email address is listed. Empty
|
||||
// admits any user.
|
||||
AllowedUsers []string `koanf:"allowed_users"`
|
||||
|
||||
// AllowedGroups 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.
|
||||
AllowedGroups []string `koanf:"allowed_groups"`
|
||||
|
||||
// EmailVerifiedRequired trusts an email only when the provider marks
|
||||
// it verified: an unverified one fails allowed_domains and
|
||||
// allowed_users and is not copied to the user. Turn it off for a
|
||||
// provider that does not send email_verified.
|
||||
EmailVerifiedRequired bool `koanf:"email_verified_required"`
|
||||
|
||||
// UseExpiryFromToken expires an OIDC-registered node with its token,
|
||||
// instead of node.expiry. Tokens are often short-lived, forcing
|
||||
// frequent logins.
|
||||
UseExpiryFromToken bool `koanf:"use_expiry_from_token"`
|
||||
|
||||
// PKCE configures Proof Key for Code Exchange.
|
||||
PKCE PKCEConfig `koanf:"pkce"`
|
||||
}
|
||||
|
||||
// DERPConfig is the DERP map: the relay servers clients use when a direct
|
||||
// connection fails. Sources merge in order (DERPMap, URLs, Paths, then the
|
||||
// embedded server); a region replaces an earlier one with the same ID.
|
||||
type DERPConfig struct {
|
||||
Server DERPServerConfig `koanf:"server"`
|
||||
URLs []HTTPURL `koanf:"urls"`
|
||||
Paths []string `koanf:"paths"`
|
||||
AutoUpdate bool `koanf:"auto_update_enabled"`
|
||||
UpdateFrequency time.Duration `koanf:"update_frequency"`
|
||||
// DERPMap is set only from Go, by an embedder or a test.
|
||||
// Server is the embedded DERP server.
|
||||
Server DERPServerConfig `koanf:"server"`
|
||||
|
||||
// URLs are DERP maps in JSON to fetch. One that fails to load is
|
||||
// logged and skipped; startup fails only when no region remains.
|
||||
URLs []HTTPURL `koanf:"urls"`
|
||||
|
||||
// Paths are 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 []string `koanf:"paths"`
|
||||
|
||||
// AutoUpdate reloads URLs and Paths every
|
||||
// [DERPConfig.UpdateFrequency].
|
||||
AutoUpdate bool `koanf:"auto_update_enabled"`
|
||||
|
||||
// UpdateFrequency is how often AutoUpdate reloads the DERP map. Zero
|
||||
// disables reloading.
|
||||
UpdateFrequency time.Duration `koanf:"update_frequency"`
|
||||
|
||||
// DERPMap is a DERP map set from Go, by an embedder or a test; it
|
||||
// cannot be set from a file.
|
||||
DERPMap *tailcfg.DERPMap `json:"-" koanf:"-"`
|
||||
}
|
||||
|
||||
// DERPServerConfig is the embedded DERP server.
|
||||
type DERPServerConfig struct {
|
||||
Enabled bool `koanf:"enabled"`
|
||||
RegionID tailcfg.DERPRegionID `koanf:"region_id"`
|
||||
RegionCode string `koanf:"region_code"`
|
||||
RegionName string `koanf:"region_name"`
|
||||
VerifyClients bool `koanf:"verify_clients"`
|
||||
STUNAddr ListenAddr `koanf:"stun_listen_addr"`
|
||||
PrivateKeyPath string `koanf:"private_key_path"`
|
||||
IPv4 string `koanf:"ipv4"`
|
||||
IPv6 string `koanf:"ipv6"`
|
||||
AutomaticallyAddEmbeddedDerpRegion bool `koanf:"automatically_add_embedded_derp_region"`
|
||||
// Enabled runs the embedded DERP server. DERP needs TLS, so
|
||||
// server_url must be https://.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
|
||||
// RegionID is the embedded server's region ID. It replaces a region
|
||||
// with the same ID from the other sources.
|
||||
RegionID tailcfg.DERPRegionID `koanf:"region_id"`
|
||||
|
||||
// RegionCode is the region's short code, shown by Tailscale clients.
|
||||
RegionCode string `koanf:"region_code"`
|
||||
|
||||
// RegionName is the region's name, shown by Tailscale clients.
|
||||
RegionName string `koanf:"region_name"`
|
||||
|
||||
// VerifyClients admits only nodes registered with this server.
|
||||
VerifyClients bool `koanf:"verify_clients"`
|
||||
|
||||
// STUNAddr is the UDP host:port of the STUN server, which helps
|
||||
// clients with NAT traversal; required with Enabled.
|
||||
STUNAddr ListenAddr `koanf:"stun_listen_addr"`
|
||||
|
||||
// PrivateKeyPath is the file holding the DERP server's private key,
|
||||
// relative to the configuration file; required with Enabled. A missing
|
||||
// file is created with a new key. It must differ from
|
||||
// noise.private_key_path.
|
||||
PrivateKeyPath string `koanf:"private_key_path"`
|
||||
|
||||
// IPv4 is the server's public IPv4 address, published in the DERP map
|
||||
// so clients reach it without DNS. Empty publishes none.
|
||||
IPv4 string `koanf:"ipv4"`
|
||||
|
||||
// IPv6 is the server's public IPv6 address, published in the DERP map
|
||||
// so clients reach it without DNS. Empty publishes none.
|
||||
IPv6 string `koanf:"ipv6"`
|
||||
|
||||
// AutomaticallyAddEmbeddedDerpRegion adds the embedded server's region
|
||||
// to the DERP map. False requires derp.paths, where you write the
|
||||
// region yourself.
|
||||
AutomaticallyAddEmbeddedDerpRegion bool `koanf:"automatically_add_embedded_derp_region"`
|
||||
}
|
||||
|
||||
// LogTailConfig controls client logging to Tailscale.
|
||||
type LogTailConfig struct {
|
||||
// Enabled lets nodes send their logs to Tailscale Inc.; headscale
|
||||
// cannot point them at another log server. False tells nodes not to.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
}
|
||||
|
||||
// TaildropConfig controls Taildrop, Tailscale's file sharing between
|
||||
// nodes.
|
||||
type TaildropConfig struct {
|
||||
// Enabled gives every node the file-sharing capability. False omits
|
||||
// it from the baseline; a policy nodeAttrs grant can still give it.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
}
|
||||
|
||||
@@ -439,18 +753,41 @@ type TaildropConfig struct {
|
||||
// node's CapMap; clients fall back to that default unless they have
|
||||
// opted in or out locally.
|
||||
type AutoUpdateConfig struct {
|
||||
// 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.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
}
|
||||
|
||||
// CLIConfig is how the headscale CLI reaches the server: the local
|
||||
// unix_socket without authentication, or a remote address with an API key.
|
||||
type CLIConfig struct {
|
||||
Address string `koanf:"address"`
|
||||
APIKey Secret `json:"-" koanf:"api_key"` // never serialise the headscale admin API key
|
||||
Timeout time.Duration `koanf:"timeout"`
|
||||
Insecure bool `koanf:"insecure"`
|
||||
// Address is the remote server's host:port or URL; https:// is
|
||||
// assumed without a scheme. Empty uses unix_socket.
|
||||
Address string `koanf:"address"`
|
||||
|
||||
// APIKey is the API key the CLI sends to a remote Address, or
|
||||
// "file:<path>" to read it from a file. Read only by the CLI. Never
|
||||
// serialised.
|
||||
APIKey Secret `json:"-" koanf:"api_key"`
|
||||
|
||||
// Timeout bounds each CLI command's requests to the server.
|
||||
Timeout time.Duration `koanf:"timeout"`
|
||||
|
||||
// Insecure skips TLS certificate verification of a remote Address.
|
||||
Insecure bool `koanf:"insecure"`
|
||||
}
|
||||
|
||||
// PolicyConfig is where the access control policy (ACLs and grants) is
|
||||
// stored.
|
||||
type PolicyConfig struct {
|
||||
Path string `koanf:"path"`
|
||||
// Path is the HuJSON policy file read in file mode, relative to the
|
||||
// configuration file. Empty starts without a policy, which allows all
|
||||
// traffic.
|
||||
Path string `koanf:"path"`
|
||||
|
||||
// Mode is where the policy is kept: a file headscale reads, or the
|
||||
// database, edited through the CLI or API.
|
||||
Mode PolicyMode `koanf:"mode"`
|
||||
}
|
||||
|
||||
@@ -458,8 +795,12 @@ func (p *PolicyConfig) IsEmpty() bool {
|
||||
return p.Mode == PolicyModeFile && p.Path == ""
|
||||
}
|
||||
|
||||
// LogConfig configures headscale's own log output.
|
||||
type LogConfig struct {
|
||||
Level LogLevel `koanf:"level"`
|
||||
// Level is the lowest level logged.
|
||||
Level LogLevel `koanf:"level"`
|
||||
|
||||
// Format is how log lines are written.
|
||||
Format LogFormat `koanf:"format"`
|
||||
}
|
||||
|
||||
@@ -469,54 +810,39 @@ type LogConfig struct {
|
||||
// need adjustment. Changes to these values can significantly impact performance
|
||||
// and resource usage.
|
||||
type Tuning struct {
|
||||
// BatchChangeDelay controls how long to wait before sending batched updates
|
||||
// to clients when multiple changes occur in rapid succession.
|
||||
// BatchChangeDelay is how often queued changes are sent to clients
|
||||
// as one update; must be positive.
|
||||
BatchChangeDelay time.Duration `koanf:"batch_change_delay"`
|
||||
|
||||
// NodeMapSessionBufferedChanSize sets the buffer size for the channel that
|
||||
// queues map updates to be sent to connected clients.
|
||||
// NodeMapSessionBufferedChanSize is how many map updates are queued
|
||||
// per connected client.
|
||||
NodeMapSessionBufferedChanSize int `koanf:"node_mapsession_buffered_chan_size"`
|
||||
|
||||
// BatcherWorkers controls the number of parallel workers processing map
|
||||
// updates for connected clients. See [Tuning.BatcherWorkerCount].
|
||||
// BatcherWorkers is the number of workers building map updates for
|
||||
// connected clients. Zero uses three quarters of the CPU cores, at
|
||||
// least one. See [Tuning.BatcherWorkerCount].
|
||||
BatcherWorkers int `koanf:"batcher_workers"`
|
||||
|
||||
// RegisterCacheExpiration is how long registration cache entries remain
|
||||
// valid before being eligible for eviction.
|
||||
// RegisterCacheExpiration is how long a pending registration waits
|
||||
// to be completed. Zero uses the built-in default.
|
||||
RegisterCacheExpiration time.Duration `koanf:"register_cache_expiration"`
|
||||
|
||||
// RegisterCacheMaxEntries bounds pending registrations. At capacity, new
|
||||
// registrations are refused without evicting admitted sessions. SSH checks
|
||||
// can also use 64 reserved slots beyond this limit.
|
||||
// A value of 0 falls back to defaultRegisterCacheMaxEntries (1024).
|
||||
// RegisterCacheMaxEntries bounds pending registrations. At capacity,
|
||||
// new registrations are refused without evicting pending ones; SSH
|
||||
// checks have a small reserve beyond it. Zero uses the built-in
|
||||
// default.
|
||||
RegisterCacheMaxEntries int `koanf:"register_cache_max_entries"`
|
||||
|
||||
// NodeStoreBatchSize controls how many write operations are accumulated
|
||||
// before rebuilding the in-memory node snapshot.
|
||||
//
|
||||
// The NodeStore batches write operations (add/update/delete nodes) before
|
||||
// rebuilding its in-memory data structures. Rebuilding involves recalculating
|
||||
// peer relationships between all nodes based on the current ACL policy, which
|
||||
// is computationally expensive and scales with the square of the number of nodes.
|
||||
//
|
||||
// By batching writes, Headscale can process N operations but only rebuild once,
|
||||
// rather than rebuilding N times. This significantly reduces CPU usage during
|
||||
// bulk operations like initial sync or policy updates.
|
||||
//
|
||||
// Trade-off: Higher values reduce CPU usage from rebuilds but increase latency
|
||||
// for individual operations waiting for their batch to complete.
|
||||
// NodeStoreBatchSize is 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.NodeStoreBatchTimeout]
|
||||
// passes.
|
||||
NodeStoreBatchSize int `koanf:"node_store_batch_size"`
|
||||
|
||||
// NodeStoreBatchTimeout is the maximum time to wait before processing a
|
||||
// partial batch of node operations.
|
||||
//
|
||||
// When [Tuning.NodeStoreBatchSize] operations haven't accumulated, this timeout ensures
|
||||
// writes don't wait indefinitely. The batch processes when either the size
|
||||
// threshold is reached OR this timeout expires, whichever comes first.
|
||||
//
|
||||
// Trade-off: Lower values provide faster response for individual operations
|
||||
// but trigger more frequent (expensive) peer map rebuilds. Higher values
|
||||
// optimize for bulk throughput at the cost of individual operation latency.
|
||||
// NodeStoreBatchTimeout is 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.
|
||||
NodeStoreBatchTimeout time.Duration `koanf:"node_store_batch_timeout"`
|
||||
}
|
||||
|
||||
|
||||
@@ -3,9 +3,13 @@ package types
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"net/netip"
|
||||
"net/url"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/google/go-cmp/cmp"
|
||||
@@ -488,3 +492,73 @@ func TestDerivedValues(t *testing.T) {
|
||||
resolvers(written...).ResolverAddrs()
|
||||
assert.Equal(t, []string{"9.9.9.9"}, written)
|
||||
}
|
||||
|
||||
// TestConfigFieldsDocumented pins a doc comment on every exported field
|
||||
// reachable from Config: generated docs and option descriptions read them.
|
||||
func TestConfigFieldsDocumented(t *testing.T) {
|
||||
files, err := filepath.Glob("config*.go")
|
||||
require.NoError(t, err)
|
||||
|
||||
fset := token.NewFileSet()
|
||||
structs := map[string]*ast.StructType{}
|
||||
|
||||
for _, name := range files {
|
||||
if strings.HasSuffix(name, "_test.go") {
|
||||
continue
|
||||
}
|
||||
|
||||
f, err := parser.ParseFile(fset, name, nil, parser.ParseComments)
|
||||
require.NoError(t, err)
|
||||
|
||||
ast.Inspect(f, func(n ast.Node) bool {
|
||||
if ts, ok := n.(*ast.TypeSpec); ok {
|
||||
if st, ok := ts.Type.(*ast.StructType); ok {
|
||||
structs[ts.Name.Name] = st
|
||||
}
|
||||
}
|
||||
|
||||
return true
|
||||
})
|
||||
}
|
||||
|
||||
var missing []string
|
||||
|
||||
seen := map[string]bool{}
|
||||
queue := []string{"Config"}
|
||||
|
||||
for len(queue) > 0 {
|
||||
typ := queue[0]
|
||||
queue = queue[1:]
|
||||
|
||||
if seen[typ] {
|
||||
continue
|
||||
}
|
||||
|
||||
seen[typ] = true
|
||||
|
||||
require.Contains(t, structs, typ)
|
||||
|
||||
for _, field := range structs[typ].Fields.List {
|
||||
for _, name := range field.Names {
|
||||
if name.IsExported() && field.Doc == nil {
|
||||
missing = append(missing, typ+"."+name.Name)
|
||||
}
|
||||
}
|
||||
|
||||
ast.Inspect(field.Type, func(n ast.Node) bool {
|
||||
switch n := n.(type) {
|
||||
case *ast.SelectorExpr:
|
||||
return false // another package's type
|
||||
case *ast.Ident:
|
||||
if structs[n.Name] != nil {
|
||||
queue = append(queue, n.Name)
|
||||
}
|
||||
}
|
||||
|
||||
return true
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
assert.Empty(t, missing, "fields without a doc comment")
|
||||
}
|
||||
Reference in new issue
Block a user