Files
headscale/docs/ref/dns.md

7.3 KiB

DNS

Headscale supports most DNS features from Tailscale. DNS related settings can be configured within the dns section of the configuration file.

Setting extra DNS records

Headscale allows to set extra DNS records which are made available via MagicDNS. Extra DNS records can be configured either via static entries in the configuration file or from a JSON file that Headscale continuously watches for changes:

  • Use the dns.extra_records option in the configuration file 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 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.
    
  2. 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
     ```
    
  3. 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:

    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:

Configure the provider in the dns.challenge.provider section of the configuration file. Use name to select the provider, the remaining keys are its settings:

dns:
  certificates:
    enabled: true
  challenge:
    provider:
      name: gigahost
      api_key: "file:${CREDENTIALS_DIRECTORY}/gigahost-api-key"

See the configuration options 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>:

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 serves challenge records from its own zone. Each certificate name needs its own registration:

  1. Register the name with acme-dns, see its documentation. Note the returned username, password, subdomain and fulldomain.

  2. Point the _acme-challenge record of the name to fulldomain with a CNAME:

    _acme-challenge.laptop.example.com. CNAME 8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.acme-dns.io.
    
  3. Add the registration to config, keyed by the certificate name:

    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`.