DNS Conditional Forwarding on UniFi Security Gateway

Now for something really controversial to start this off: I really like the ease of GUI based management tools for network devices, like UniFi. That said I also really like CLI configuration tools which let me tap into a lot more functionality than the GUI.  If you've ever used an EdgeRouter's CLI, you've probably noticed that there's a lot of functionality in the EdgeRouter that you can't configure for a security gateway through the UniFi controller. One of the prime examples that I run into is DNS Conditional Forwarding.

If you're not familiar with conditional formatting, here's a simple network setup to look at.

So the network's davejlong.xyz and contoso.com have a site-to-site VPN setup between them. If you're on my davejlong.xyz network, and need to do lookups for contoso.com domains, you need to, somehow, get your DNS traffic over to 172.16.1.10. You could set your DNS server as that, but then you need the site to site VPN for all DNS traffic. Instead, Conditional Forwarders allow you to just forward requests for anything in the contoso.com zone to the nameserver you specify for it.

Since UniFi uses dnsmasq for it's DNS service, it should be able to support conditional forwarding easily enough, but there's nowhere in the UniFi controller to configure this. You can SSH into your security gateway and then there is options to configure the dnsmasq service, but those changes will be lost next time your gateway provisions itself.

In my search for an answer, I found an UniFi article about a config.gateway.json file. This JSON file can contain CLI-like configuration settings that will get applied to the gateway in a UniFi site.

Note: Continue at your own risk. Screwing up the file can result in loss of connectivity for your security gateway.

The Solution

Okay, so now that you skipped everything I wrote above and just scrolled down here because you found me on Google and just need a quick answer, here it is. To setup a persistent conditional forwarder on your UniFi Security Gateway, you first need to know the Site ID of the site you need to configure. When you open a site in the UniFi controller, the URL will look something like https://unifi.contoso.com/manage/site/bthnpk7m/dashboard, and the Site ID is bthnpk7m.

With Site ID in hand, connect to your controller's console and find your controller's data directory. On my Ubuntu server it's at /var/lib/unifi. Then navigate into sites/<site id>. In that folder create a file named config.gateway.json and the contents should look like the following:

{
	"service": {
    	"dns": {
        	"forwarding": {
            	"options": [
                	"server=/contoso.com/172.16.1.10",
                    "server=1.1.1.1",
                    "server=1.0.0.1"
                ]
            }
        }
    }
}

What the file is doing is merging the configuration here with the gateways primary configuration. In this case it will update the DNS forwarding options key to contain the 3 servers. The first one tells dnsmasq to forward all contoso.com requests to 172.16.1.10. The next 2 tells dnsmasq to forward any DNS requests that the gateway doesn't have an answer for to 1.1.1.1 or 1.0.0.1.

That's it. Now force the gateway to provision and it'll pickup the new DNS settings.