mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-19 20:04: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
+1
-1
@@ -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
@@ -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"
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user