# 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:` 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_`: ```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:`. ### 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: "" password: "file:${CREDENTIALS_DIRECTORY}/acme-dns-laptop" 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`.