From 36917c078769e87ebda4cabecd8846a617ab659c Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Tue, 17 Nov 2026 11:20:18 +0000 Subject: [PATCH] docs: describe the strict configuration and its generated reference Updates #3567 Updates #1926 --- README.md | 8 ++--- docs/about/faq.md | 2 +- docs/ref/configuration.md | 54 +++++++++++++++++++-------------- docs/ref/debug.md | 7 +++-- docs/ref/derp.md | 17 ++++++++--- docs/ref/oidc.md | 3 +- docs/setup/install/container.md | 17 +++++++++-- docs/setup/install/official.md | 18 +++++------ 8 files changed, 77 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index c3a854f0a..1c3f69abd 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ An open source, self-hosted implementation of the Tailscale control server. Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat. -**Note:** Always select the same GitHub tag as the released version you use -to ensure you have the correct example configuration. The `main` branch might -contain unreleased changes. The documentation is available for stable and +**Note:** Use `headscale generate config` to print the example configuration of the +version you have installed. The documentation is available for stable and development versions: - [Documentation for the stable version](https://headscale.net/stable/) -- [Documentation for the development version](https://headscale.net/development/) +- [Documentation for the development version](https://headscale.net/development/), + which follows the `main` branch and might describe unreleased changes ## What is Tailscale diff --git a/docs/about/faq.md b/docs/about/faq.md index 101112337..1159fb0a4 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -153,7 +153,7 @@ Headscale checks if the policy is valid during startup and refuses to start if i indicates which part of the policy is invalid. Follow these steps to fix your policy: - Dump the policy to a file: `headscale policy get --bypass-server-and-access-database-directly > policy.json` -- Edit and fixup `policy.json`. Use the command `headscale policy check --file policy.json` to validate the policy. +- Edit and fixup `policy.json`. Use the command `headscale check policy --file policy.json` to validate the policy. - Load the modified policy: `headscale policy set --bypass-server-and-access-database-directly --file policy.json` - Start Headscale as usual. diff --git a/docs/ref/configuration.md b/docs/ref/configuration.md index b8d64a093..e21681af3 100644 --- a/docs/ref/configuration.md +++ b/docs/ref/configuration.md @@ -1,41 +1,49 @@ # Configuration -- Headscale loads its configuration from a YAML file -- It searches for `config.yaml` in the following paths: +- Headscale loads its configuration from a YAML, JSON or HuJSON file +- It searches for `config.json`, `config.yaml`, `config.yml` or `config.hujson`, in that order, in the following paths: - `/etc/headscale` + - `$XDG_CONFIG_HOME/headscale` (default `$HOME/.config/headscale`) + - `headscale` under each directory in `$XDG_CONFIG_DIRS` (default `/etc/xdg`) - `$HOME/.headscale` - the current working directory +- Configuration keys are always lower case. An unknown or removed configuration entry prevents Headscale from starting +- An unknown or removed `HEADSCALE_*` environment variable logs a warning +- A [secret](configuration-options.md#secrets) can be either a string value or a file path starting with `file:`: + - an empty file is an error + - file is only read where the secret is used - To load the configuration from a different path, use: - the command line flag `-c`, `--config` - the environment variable `HEADSCALE_CONFIG` -- Validate the configuration file with: `headscale configtest` +- The configuration can be checked with: `headscale check config`. Use `-f ` to load from path. +- Additional configuration can be checked with: `headscale check all`: + - [Policy](configuration-options.md#policy.path) + - [DERP Maps](configuration-options.md#derp.paths) + - [TLS Certs](configuration-options.md#tls.cert_path) + - [Extra records](configuration-options.md#dns.extra_records_path) -!!! example "Get the [example configuration from the GitHub repository](https://github.com/juanfont/headscale/blob/main/config-example.yaml)" +## Example configuration - Always select the [same GitHub tag](https://github.com/juanfont/headscale/tags) as the released version you use to - ensure you have the correct example configuration. The `main` branch might contain unreleased changes. +The full configuration for your version can be generated using `headscale generate config` and will print a +configuration file with all configuration options, their documentation and the default values. - === "View on GitHub" +Write it to a file to start a new configuration: - - Development version: - - Version {{ headscale.version }}: https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml +```shell +headscale generate config > /etc/headscale/config.yaml +``` - === "Download with `wget`" +Use `--no-docs` to print a dense configuration file without the comments/documentation. - ```shell - # Development version - wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml +Use `--minimal` to print the most essential configuration options. - # Version {{ headscale.version }} - wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml - ``` +Use `--running` to print the current running configuration of the live Headscale server, with secrets redacted. - === "Download with `curl`" +[Configuration options](configuration-options.md) describes every key, with examples for the configuration file, the +environment and NixOS. - ```shell - # Development version - curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml +??? example "Example configuration of this version" - # Version {{ headscale.version }} - curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml - ``` + ```yaml + {% include "./config-example.yaml" start="do not edit.\n" %} + ``` diff --git a/docs/ref/debug.md b/docs/ref/debug.md index 334bdffc2..ccb415a1d 100644 --- a/docs/ref/debug.md +++ b/docs/ref/debug.md @@ -34,12 +34,13 @@ log: ### Database logging -The database debug mode logs all database queries. Enable it to see how Headscale interacts with its database. This also -requires the application log level to be set to either `debug` or `trace`. +The database debug mode logs database queries: ordinary queries at level `debug`, queries slower than +`database.gorm.slow_threshold` at `warn` and failed queries at `error`. Enable it to see how Headscale interacts with its +database. Ordinary queries show only with the application log level set to either `debug` or `trace`. ```yaml hl_lines="3 7" database: - # Enable debug mode. This setting requires the log.level to be set to "debug" or "trace". + # Enable query logging. Ordinary queries need log.level "debug" or "trace". debug: false log: diff --git a/docs/ref/derp.md b/docs/ref/derp.md index 390220c7a..9dcb597e6 100644 --- a/docs/ref/derp.md +++ b/docs/ref/derp.md @@ -7,8 +7,8 @@ DERP server to ensure seamless connectivity between nodes. ## Configuration DERP related settings are configured within the `derp` section of the [configuration file](configuration.md). The -following sections only use a few of the available settings, check the [example configuration](configuration.md) for -all available configuration options. +following sections only use a few of the available settings; [`derp`](configuration-options.md#derp) in the +configuration options lists all of them. ### Enable embedded DERP @@ -16,14 +16,20 @@ Headscale ships with an embedded DERP server which allows to run your own self-h DERP server is disabled by default and needs to be enabled. In addition, you should configure the public IPv4 and public IPv6 address of your Headscale server for improved connection stability: -```yaml title="config.yaml" hl_lines="3-5" +```yaml title="config.yaml" hl_lines="3-8" derp: server: enabled: true + region_id: 999 + stun_listen_addr: 0.0.0.0:3478 + private_key_path: /var/lib/headscale/derp_server_private.key ipv4: 198.51.100.1 ipv6: 2001:db8::1 ``` +`region_id`, `stun_listen_addr` and `private_key_path` are required. Tailscale keeps the region IDs 900-999 for your own +regions. + Keep in mind that [additional ports are needed to run a DERP server](../setup/requirements.md#ports-in-use). Besides relaying traffic, it also uses STUN (udp/3478) to help clients discover their public IP addresses and perform NAT traversal. [Check DERP server connectivity](#check-derp-server-connectivity) to see if everything works. @@ -34,10 +40,13 @@ Once enabled, Headscale's embedded DERP is added to the list of free-to-use [DER servers](https://tailscale.com/docs/reference/derp-servers) offered by Tailscale Inc. To only use Headscale's embedded DERP server, disable the loading of the default DERP map: -```yaml title="config.yaml" hl_lines="6" +```yaml title="config.yaml" hl_lines="9" derp: server: enabled: true + region_id: 999 + stun_listen_addr: 0.0.0.0:3478 + private_key_path: /var/lib/headscale/derp_server_private.key ipv4: 198.51.100.1 ipv6: 2001:db8::1 urls: [] diff --git a/docs/ref/oidc.md b/docs/ref/oidc.md index 32f3f5681..74a84b9a9 100644 --- a/docs/ref/oidc.md +++ b/docs/ref/oidc.md @@ -26,7 +26,8 @@ A basic configuration connects Headscale to an identity provider and typically r - OpenID Connect Issuer URL from the identity provider. Headscale uses the OpenID Connect Discovery Protocol 1.0 to automatically obtain OpenID configuration parameters (example: `https://sso.example.com`). - Client ID from the identity provider (example: `headscale`). -- Client secret generated by the identity provider (example: `generated-secret`). +- Client secret generated by the identity provider (example: `generated-secret`). To keep it out of the configuration + file, use `file:` (example: `file:${CREDENTIALS_DIRECTORY}/oidc_client_secret`). - Redirect URI for your identity provider (example: `https://headscale.example.com/oidc/callback`). === "Headscale" diff --git a/docs/setup/install/container.md b/docs/setup/install/container.md index 789e359ac..fc5ad9785 100644 --- a/docs/setup/install/container.md +++ b/docs/setup/install/container.md @@ -24,8 +24,21 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c cd ./headscale ``` -1. Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the - configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details. +1. Write a configuration to `./config/config.yaml`. `server_url`, the URL clients reach headscale at, is the only key + without a default, so one line is a configuration: + + ```shell + echo 'server_url: https://headscale.example.com' > ./config/config.yaml + ``` + + Or write the example configuration of your chosen version, every key with its default and documentation, and set + `server_url` in it. See [Configuration](../../ref/configuration.md) for details. + + ```shell + docker run --rm headscale/headscale: generate config > ./config/config.yaml + ``` + + The published port 9090 serves `/metrics` only with `metrics_listen_addr: 0.0.0.0:9090` in the configuration. 1. Start headscale from within the previously created `./headscale` directory: diff --git a/docs/setup/install/official.md b/docs/setup/install/official.md index 52988836d..5ae016945 100644 --- a/docs/setup/install/official.md +++ b/docs/setup/install/official.md @@ -24,8 +24,9 @@ distributions are Ubuntu 22.04 or newer, Debian 12 or newer. sudo apt install ./headscale.deb ``` -1. [Configure headscale by editing the configuration file](../../ref/configuration.md). An up-to date example - configuration file is also available in `/usr/share/doc/headscale/examples/config-example.yaml`: +1. [Configure Headscale by editing the configuration file](../../ref/configuration.md). A new install will find the + default configuration file under `/etc/headscale/config.yaml`. Set `server_url`. A copy of the shipped file is in + `/usr/share/doc/headscale/examples/config-example.yaml`: ```shell sudo nano /etc/headscale/config.yaml @@ -82,11 +83,13 @@ managed by systemd. headscale ``` -1. Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the - configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details. +1. Generate a default configuration and write it to `/etc/headscale/config.yaml`, then adjust it to suit your needs. + Set `server_url`. Check the configuration with `headscale check config`. See + [Configuration](../../ref/configuration.md) for details. ```shell sudo mkdir -p /etc/headscale + headscale generate config | sudo tee /etc/headscale/config.yaml sudo nano /etc/headscale/config.yaml ``` @@ -94,13 +97,6 @@ managed by systemd. to `/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`. -1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a path that is writable by the - `headscale` user or group: - - ```yaml title="config.yaml" - unix_socket: /var/run/headscale/headscale.sock - ``` - 1. Reload systemd to load the new configuration file: ```shell