Skip to content

Setting custom DNS records

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.


This documentation has the goal of showing how a user can set custom DNS records with headscales magic dns. An example use case is to serve 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 "" instead of the hostname and portnum combination "".


1. Change the configuration

  1. Change the config.yaml to contain the desired records like so:

        - name: ""
          type: "A"
          value: ""
        - name: ""
          type: "A"
          value: ""
  2. Restart your headscale instance.


    Beware of the limitations listed later on!

2. Verify that the records are set

You can use a DNS querying tool of your choice on one of your hosts to verify that your newly set records are actually available in MagicDNS, here we used dig:

$ dig

; <<>> DiG 9.18.10 <<>>
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 44054
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

; EDNS: version: 0, flags:; udp: 65494
;         IN      A

;; ANSWER SECTION:  593     IN      A

;; Query time: 0 msec
;; WHEN: Sat Dec 31 11:46:55 CET 2022
;; MSG SIZE  rcvd: 66

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:

server {
    listen 80;
    listen [::]:80;


    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;



Not all types of records are supported, especially no CNAME records.