headscale/docs/ref/dns.md

DNS

Headscale supports most DNS features from Tailscale and DNS releated settings can be configured in the configuration file within the dns section.

Setting custom DNS records

!!! warning "Community documentation"

This page is not actively maintained by the headscale authors and is
written by community members. It is _not_ verified by headscale developers.

**It might be outdated and it might miss necessary steps**.

Headscale allows to set custom DNS records which are made available via MagicDNS. 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"

[Not all types of records are supported](https://github.com/tailscale/tailscale/blob/6edf357b96b28ee1be659a70232c0135b2ffedfd/ipn/ipnlocal/local.go#L2989-L3007), especially no CNAME records.

1. Update the configuration file to contain the desired records like so:

   dns:
     ...
     extra_records:
       - name: "prometheus.myvpn.example.com"
         type: "A"
         value: "100.64.0.3"
   
       - name: "grafana.myvpn.example.com"
         type: "A"
         value: "100.64.0.3"
     ...
   

2. Restart your headscale instance.

3. Verify that DNS records are properly set using the DNS querying tool of your choice:

   === "Query with dig"

   ```shell
   dig +short grafana.myvpn.example.com
   100.64.0.3
   ```
   

   === "Query with drill"

   ```shell
   drill -Q grafana.myvpn.example.com
   100.64.0.3
   ```
   

4. 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;
       }
   
   }