mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-20 04:14:32 +09:00
191 lines
7.3 KiB
Markdown
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`.
|