mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-20 04:14:32 +09:00
docs: describe the strict configuration and its generated reference
Updates #3567 Updates #1926
This commit is contained in:
1 parent
f5f05440b3
commit
36917c0787
8 files changed
+77
-49
No files matched your search
+31
-23
@@ -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
@@ -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
@@ -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
@@ -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"
|
||||
|
||||
Reference in new issue
Block a user