instagram arrow-down
Kalle Lilja


DNS Request Routing Configuraiton – UniFi

Conditional DNS Forwarding setup using config.gateway.json

DNS Request Routing or Conditional Forwarding is a feature that allows you to send DNS requests to specific DNS servers based on the domain requested.
This setting is frequently used in branch offices with the central equipment behind a VPN.

A quick and recent example would be a branch-office network with a UniFi stack, the client computers needs to be AD joined, and there’s no possibility of a local domain controller.
The solution would be to configure an IPSec site-to-site VPN between the branch and main site, have the clients use the domain controller on the other side of the VPN as primary DNS, thus allowing full and proper DNS resolution.
Issues will arise if say, the latency over the VPN is bad-ish, resulting in sluggish performance on the clients, as most things are DNS handled, thus, forced over the VPN.

The solution to this will be DNS Request Routing.


We’ll be able to set up a rule on the USG to send only traffic for and to the DNS server on the other side of the VPN while keeping everything else on the local USG Thus only using the VPN when the VPN is actually needed.


Set up the UniFi side of things, the local LAN with as Domain Name, the WAN connection, the IPSec VPN, and so on.
With that in place, the local computers won’t find the domain, but, they should all be able to connect to the dns, eg, nslookup -q=a

DNS Request Route is not a feature configurable via the GUI at the moment, Controller version 5.7.20, as such, there are 3 ways forward.
1. Connect to the USG using SSH and configure the setting using the CLI commands.
2. Connect to the USG using SSH and set the configuration on the Linux side.
3. Push the config to the USG using config.gateway.json.

There are pros and cons to each solution;

Configuration Pros Cons SSH
1 PoC, is needed to Generate solution 3 Wont persist through FW upgrade USG
2 Quick and dirty, PoC Wont persist through FW upgrade USG
3 Will persist through FW upgrade Could get complicated Controller

Configuration 1

ssh ubnt@

sudo su -
touch /etc/dnsmasq.d/workdns.conf
echo -e "server=/\nserver=/" | sudo tee -a /etc/dnsmasq.d/workdns.conf
/etc/init.d/dnsmasq force-reload

Configuration 2

ssh ubnt@

set service dns forwarding options server=/
set service dns forwarding options server=/

Configuration 3
This is the solution to go for!
What needs to be done;
Create a config.gateway.json file on the UniFi Controller for the branch-office site, add the Request Routing configuration, force a re-provision of the USG using the GUI.

Gain access to your UniFi Controller, wither by SSH, or, well FTP/sFTP will do the trick.
Navigate the the Site location, /var/lib/unifi/data/sites/SiteID/, and create a new file – config.gateway.json.
  The SiteID is the string of text After “/site/” in the URL, example:, SiteID would be asd123asd in this case, as such, the file needed to be created would be /var/lib/unifi/data/sites/asd123asd/config.gateway.json. More Information.
Add the following configuration, change the domain and server of course, and save the file.

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

Lastly, trigger a forced re-provision of the USG, or change a setting via the GUI to trigger one.

That’s it! The clients will not use DNS like the following:
Client – nslookup * -> > ISP/Roots -> Resolved
Client – nslookup * -> > -> Resolved

I’ll throw in a side note here;
If you’d like to go through the process of generating the .json config as well what you’d need to do is perform the CLI configuration via SSH (Configuration 1) followed by using the command mca-ctrl -t dump-cfg to dump the current config.
With that, find the related section, in this example Service: dns: forwarding: options.
Extract the changes and wrap them in { } – pretty much, again more information.