Files
headscale/docs/ref/dns.md
T

191 lines
7.3 KiB
Markdown

# DNS
Headscale supports [most DNS features](../about/features.md) from Tailscale. DNS related settings can be configured
within the `dns` section of the [configuration file](configuration.md).
## Setting extra DNS records
Headscale allows to set extra DNS records which are made available via
[MagicDNS](https://tailscale.com/docs/features/magicdns). Extra DNS records can be configured either via static entries
in the [configuration file](configuration.md) or from a JSON file that Headscale continuously watches for changes:
- Use the `dns.extra_records` option in the [configuration file](configuration.md) for entries that are static and
don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the
configuration require a restart of Headscale.
- For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are
generated by scripts the option `dns.extra_records_path` in the [configuration file](configuration.md) is useful.
Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects
changes.
An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus
monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the
hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:3000".
!!! warning "Limitations"
Currently, [only A and AAAA records are processed by Tailscale](https://github.com/tailscale/tailscale/blob/v1.86.5/ipn/ipnlocal/node_backend.go#L662).
1. Configure extra DNS records using one of the available configuration options:
=== "Static entries, via `dns.extra_records`"
```yaml title="config.yaml"
dns:
...
extra_records:
- name: "grafana.myvpn.example.com"
type: "A"
value: "100.64.0.3"
- name: "prometheus.myvpn.example.com"
type: "A"
value: "100.64.0.3"
...
```
Restart your headscale instance.
=== "Dynamic entries, via `dns.extra_records_path`"
```json title="extra-records.json"
[
{
"name": "grafana.myvpn.example.com",
"type": "A",
"value": "100.64.0.3"
},
{
"name": "prometheus.myvpn.example.com",
"type": "A",
"value": "100.64.0.3"
}
]
```
Headscale picks up changes to the above JSON file automatically.
!!! tip "Good to know"
- The `dns.extra_records_path` option in the [configuration file](configuration.md) needs to reference the
file containing extra DNS records. Its extension picks the format: `.json`, `.hujson`, `.yaml` or `.yml`.
A `.json` file is read as [HuJSON](https://github.com/tailscale/hujson), so it may contain comments and
trailing commas.
- Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing.
1. Verify that DNS records are properly set using the DNS querying tool of your choice:
=== "Query with dig"
```console
dig +short grafana.myvpn.example.com
100.64.0.3
```
=== "Query with drill"
```console
drill -Q grafana.myvpn.example.com
100.64.0.3
```
1. Optional: Setup the reverse proxy
The motivating example here was to be able to access internal monitoring services on the same host without
specifying a port, depicted as NGINX configuration snippet:
```nginx title="nginx.conf"
server {
listen 80;
listen [::]:80;
server_name grafana.myvpn.example.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## DNS-01 challenge provider
Headscale supports ACME DNS-01 challenges with the help of a DNS provider. A provider is required to:
- Issue certificates for nodes via `tailscale cert`, enabled with `dns.certificates.enabled`
- Required for [`tailscale serve`](https://tailscale.com/docs/features/tailscale-serve) with HTTPS
- Required for [tsnet](https://tailscale.com/docs/features/tsnet) with HTTPS
- Required for the [Kubernetes operator](https://tailscale.com/docs/kubernetes-operator)
- Get Headscale's own [TLS certificate](tls.md) with `tls.acme.challenge_type: DNS-01`
Configure the provider in the `dns.challenge.provider` section of the [configuration file](configuration.md). Use `name`
to select the provider, the remaining keys are its settings:
```yaml title="config.yaml"
dns:
certificates:
enabled: true
challenge:
provider:
name: gigahost
api_key: "file:${CREDENTIALS_DIRECTORY}/gigahost-api-key"
```
See the [configuration options](configuration-options.md#dns.challenge.provider) for all providers and their settings.
!!! tip "Keep credentials out of the configuration file"
Any setting accepts `file:<path>` to read its value from a file. A setting that is not text, such as the `config`
of `acmedns`, takes a file with its JSON value. See [secrets](configuration-options.md#secrets).
### Environment variables
Each text setting may also be set with `HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING>`:
```shell
export HEADSCALE_DNS_CHALLENGE_PROVIDER_NAME=gigahost
export HEADSCALE_DNS_CHALLENGE_PROVIDER_API_KEY=file:/run/secrets/gigahost-api-key
```
Use `HEADSCALE_DNS_CHALLENGE_PROVIDER` to pass the whole provider as a JSON object. The `config` of `acmedns` is an
object: set it there, or point `HEADSCALE_DNS_CHALLENGE_PROVIDER_CONFIG` to a JSON file with `file:<path>`.
### acme-dns
[acme-dns](https://github.com/joohoi/acme-dns) serves challenge records from its own zone. Each certificate name needs
its own registration:
1. Register the name with acme-dns, see its [documentation](https://github.com/joohoi/acme-dns#register-endpoint). Note
the returned `username`, `password`, `subdomain` and `fulldomain`.
1. Point the `_acme-challenge` record of the name to `fulldomain` with a CNAME:
```text
_acme-challenge.laptop.example.com. CNAME 8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.acme-dns.io.
```
1. Add the registration to `config`, keyed by the certificate name:
```yaml title="config.yaml"
dns:
challenge:
provider:
name: acmedns
config:
laptop.example.com:
username: "<username>"
password: "file:${CREDENTIALS_DIRECTORY}/acme-dns-laptop"
subdomain: "<subdomain>"
server_url: https://auth.acme-dns.io
```
!!! warning "Limitations"
- A node without a registration gets no certificate.
- A single account (`username`, `password`, `subdomain` and `server_url` instead of `config`) only serves
Headscale's own certificate. Headscale refuses to start if it is used together with `dns.certificates.enabled`.