docs: describe the strict configuration and its generated reference

Updates #3567
Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-17 11:20:18 +00:00
1 parent f5f05440b3
commit 36917c0787
8 files changed
+77 -49

No files matched your search

+1 -1
View File
@@ -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.
+31 -23
View File
@@ -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 <path>` 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: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
- 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" %}
```
+4 -3
View File
@@ -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:
+13 -4
View File
@@ -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: []
+2 -1
View File
@@ -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:<path>` (example: `file:${CREDENTIALS_DIRECTORY}/oidc_client_secret`).
- Redirect URI for your identity provider (example: `https://headscale.example.com/oidc/callback`).
=== "Headscale"
+15 -2
View File
@@ -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:<VERSION> 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:
+7 -11
View File
@@ -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