Unifi Internal DNS

When I moved into my new house, I had a bit of a green fields opportunity where I could start again with my Unifi SDA configuration. One of the things I set out to do was to seperate device types into different vlans for say IOT vs Guest vs Servers use cases. As a result of this, the IP addressing scheme started to get more complicated. To address the complication, internal hosts needed to be resolvable by name.

I also wanted my internal DNS names to be subdomains of my public DNS name. So whilst my public website lives at etse.me, each vlan has an associated subdomain of that name. Thanks to hairpin NAT on the USG, internal access to https://etse.me/ still works just fine.

2024 Update: Users of the Unifi Dream Machine line of hardware can now create Internal DNS records through the UI. USG users still need to use the approach described below.

My Environment

• Unifi Security Gateway 3P
• Unifi Switch 8 60W
• Unifi AC-AP-Pro
• Unifi Controller on iocage (TrueNAS)

Unifi Config

I started out with 4 networks as listed below. The idea of course, was to implement firewall rules between these vlans to add a bit of protection from rogue devices BUT I’ve been too lazy to do this part 🙄

Within the Unifi Controller UI, the DNS Subdomain can be configured under Settings -> Networks -> “Network Name eg IOT” -> expand DHCP Service Management Show Options -> Domain Name: “iot.etse.me”. Apply Changes.

Host Configuration

Just use DHCP. Create static assignments in the Unifi Controller where you need them. And then where absolutely necessary, statically assign addresses from outside the DHCP scope for that VLAN. The Unifi USG uses dnsmasq under the hood to manage DHCP and creation of forward and reverse dns records. So if you staticly assign an address, there is no trigger for dnsmasq to create these records. To handle this situation, we can use a custom config.gateway.json file.

config.gateway.json

When running the Unifi Network Application or Unifi Controller to manage your Unifi SDA network, sometimes there are changes that you would like to make that are not enabled in the GUI. Essentially these devices are Unifi EdgeOS under the hood so anything that you can do on EdgeOS, you can typically do on the USG. However, unlike EdgeOS, changes that you make to the configuration directly on the USG don’t persist between reboots or re-provisioning of the device from the Unifi Controller. The solution to this, is create a custom configuration file called config.gateway.json.

The config.gateway.json is a well documented solution to this problem. You simply need to create this file and store it on your Unifi Controller under unifi/sites/default/config.gateway.json. This folder structure location will vary depending on your host OS. On Ubuntu it lives under /var/lib/unifi/sites/default/config.gateway.json.

The structure of this json configuration is that the top level object keys represent the top level of the CLI config hierachy. So for example the CLI command…

set service ... 

…is the equivalent of…

{
    "service": {}
}

So in our config file below we are going to fill out the options: [] array within the dns forwarding section. PS its always a good idea to edit this file in something like VS Code which has a JSON linter built in which will show you that your json is valid.

{
    "service": {
        "dns": {
            "forwarding": {
                "options": []
            }
        }
    }
}

The options array can filled with strings that are lines of dnsmasq config. Therefore the best resource for checking what options are available is the dnsmasq man page https://dnsmasq.org/docs/dnsmasq-man.html. As far as I am aware, you can basically use any of the dnsmasq options to configure your USG and I have personally used the server=, host-record=, ptr-record=, cname=, src-host= successfully. For now, here is an example of a forward and reverse record a host with a staticly assigned IP.

{
    "service": {
        "dns": {
            "forwarding": {
                "options": [
                    "host-record=pve03.mgmt.etse.me,192.168.254.21",
                    "ptr-record=21.254.168.192.in-addr.arpa,pve03.mgmt.etse.me"
                ]
            }
        }
    }
}

Push this file up to the Unifi Network Application / Unifi Controller and tell your Unifi Security Gateway to provision.. voila! You sould now have a forward and reverse entry in your Internal DNS. To verify

➜  ~ dig pve03.mgmt.etse.me

; <<>> DiG 9.10.6 <<>> pve03.mgmt.etse.me
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 11051
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;pve03.mgmt.etse.me.		IN	A

;; ANSWER SECTION:
pve03.mgmt.etse.me.	0	IN	A	192.168.254.21

;; Query time: 8 msec
;; SERVER: fe80::76ac:b9ff:fe17:bc8a%15#53(fe80::76ac:b9ff:fe17:bc8a%15)
;; WHEN: Wed Sep 04 15:46:09 AWST 2024
;; MSG SIZE  rcvd: 63

➜  ~ dig -x 192.168.254.21

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

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;21.254.168.192.in-addr.arpa.	IN	PTR

;; ANSWER SECTION:
21.254.168.192.in-addr.arpa. 0	IN	PTR	pve03.mgmt.etse.me.

;; Query time: 3 msec
;; SERVER: fe80::76ac:b9ff:fe17:bc8a%15#53(fe80::76ac:b9ff:fe17:bc8a%15)
;; WHEN: Wed Sep 04 15:46:30 AWST 2024
;; MSG SIZE  rcvd: 88

The config.gateway.json file can be used to over ride of supplement pretty much the entire configration of the USG as needed.

Conclusion

This might seem like overkill for your average home network but I have found having DNS names that I can rely upon has made lots of projects that I have undertaken in my Home Lab much simpler. For example Internal Certificate management to name but one. Thanks to the great number of people who have shared their own how-to’s on this topic and helped me work out how to implement it for myself.