UniFi Network Controller DNS Setup for Gateways, DHCP, and Local Records

Misconfigured DNS is behind a surprising number of UniFi network headaches — slow internet, broken VLANs, internal hostnames that refuse to resolve, and clients falling back to ISP resolvers you specifically wanted to replace. UniFi's DNS plumbing runs deeper than most people expect: there's the DNS your gateway uses to reach the internet, the DNS it pushes to clients via DHCP, per-network overrides for segmented VLANs, and local DNS records for LAN hostnames. Get any layer wrong and troubleshooting becomes a rabbit hole. This guide covers every layer, with exact menu paths for UniFi Network Application 8.x on both cloud gateways and self-hosted setups, plus CLI verification so you can confirm the change actually landed.

How UniFi Handles DNS Internally

On hardware gateways (Dream Machine Pro, UDM SE, Cloud Gateway Ultra, Cloud Gateway Max), UniFi runs dnsmasq as a local resolver and DHCP server. By default, clients receive the gateway's LAN IP as their DNS server. The gateway then forwards those queries upstream to whatever DNS you've configured on the WAN — which, unless you've changed it, is whatever your ISP handed out over DHCP.

This two-tier structure matters because a problem at the WAN tier looks identical from a client's perspective to a problem in the DHCP tier. Before touching any menus, identify which layer is actually broken:

• Clients can't reach DNS at all: DHCP is handing out the wrong server address, or the gateway's dnsmasq process is down.
• Clients resolve public names but not internal hostnames: Local DNS records are missing or the gateway isn't authoritative for your domain.
• DNS is slow or intermittently failing: Upstream DNS on the WAN is misconfigured or the ISP resolver is flaky.
• One VLAN can't resolve but others can: Per-network DNS override is missing or the VLAN isn't routing DNS traffic back to the gateway.

Self-hosted UniFi Network Server (running on Linux, Windows, or Docker) is a different case: the controller software itself does not run DNS. DNS is handled entirely by whatever gateway device you've adopted. The admin UI at https://[server-ip]:8443 configures your gateways — it doesn't touch DNS on the host OS.

Step 1: Set Upstream (WAN) DNS on Your UniFi Gateway

This controls where your gateway sends DNS queries it can't answer from cache or local records. Getting this right means your entire network isn't silently relying on ISP resolvers.

1. Open UniFi Network Application and go to Settings > Internet.
2. Click your primary WAN connection (usually labelled Primary or WAN1).
3. If your WAN uses DHCP (most home and small-office setups), expand Advanced and look for DNS Server Override. Enter your preferred servers — for example, 1.1.1.1 and 1.0.0.1 (Cloudflare) or 8.8.8.8 and 8.8.4.4 (Google).
4. If your WAN is a static connection, the DNS fields appear directly inside the IPv4 configuration section.
5. For IPv6 WAN, expand IPv6 Configuration and set the IPv6 DNS to 2606:4700:4700::1111 (Cloudflare v6) or 2001:4860:4860::8888 (Google v6) to avoid falling back to ISP resolvers on v6 traffic.
6. Click Apply Changes and wait 10–15 seconds for dnsmasq to reload before testing.

Step 2: Push DNS Servers to Clients via DHCP

By default, UniFi DHCP hands out the gateway's LAN IP as the DNS server, which then forwards to your WAN DNS. This is usually what you want. If you need to push a specific resolver directly to clients — or route through a local resolver like Pi-hole or AdGuard Home — override it per network:

1. Go to Settings > Networks.
2. Click the network you want to modify (e.g., Default, or a named VLAN).
3. Scroll down to the DHCP section.
4. Under DNS Server, enter the IP addresses you want clients to receive. You can enter up to four servers.
5. To restore the default (gateway as DNS), clear the DNS Server fields entirely — leave them blank, not zeroed out.
6. Click Apply Changes. Existing DHCP leases won't update until clients renew.

Force a lease renewal after changes: on Windows run ipconfig /release then ipconfig /renew. On Linux run sudo dhclient -r && sudo dhclient. On macOS go to System Settings > Network > [interface] and toggle the connection, or run sudo ipconfig set en0 DHCP in Terminal.

Common mistake: entering a Pi-hole or AdGuard Home IP in the WAN DNS field instead of the DHCP DNS field. The WAN field controls what the gateway itself queries; the DHCP field controls what clients query. They are independent layers and must be set separately if you want both the gateway and clients using the same resolver.

Step 3: Per-VLAN DNS Override

If you're running segmented networks — IoT VLAN, guest VLAN, management VLAN — each network in UniFi has its own DHCP DNS configuration. Repeat Step 2 for each network. Watch for these VLAN-specific pitfalls:

• Guest networks with Client Device Isolation enabled block clients from reaching the gateway IP as DNS. Either disable isolation or push a public resolver like 1.1.1.1 directly in the DHCP DNS field for that guest network.
• IoT VLANs that firewall off LAN access will fail to reach a Pi-hole sitting on the main LAN unless you add a firewall rule permitting DNS (UDP/TCP port 53) from the IoT subnet to the Pi-hole IP.
• If a VLAN's DNS field is blank, it defaults to the gateway IP as resolver — it does not inherit whatever you set in the Default network's DHCP DNS fields.

Step 4: Create Local DNS Records for LAN Hostnames

Local DNS records let you assign hostnames like nas.home or printer.lan to LAN IPs without running a separate internal DNS server. UniFi Network Application 8.4+ exposes a dedicated entry point for these:

1. Navigate to Settings > DNS in the left sidebar of UNA.
2. Click Local DNS Records (sometimes labelled DNS Overrides in older 8.x builds).
3. Click Add Record and enter the hostname (e.g., nas.lan) and the target LAN IP of the device.
4. Save. Records take effect within seconds without a full dnsmasq restart.

If you don't see a dedicated DNS section, your firmware predates the split. On UDM firmware below 2.4 and UNA below 8.0, local DNS records live under Settings > Services > DHCP > [network] > DHCP Name Server. You can also SSH into the gateway and add entries to /etc/dnsmasq.d/ as custom config files — but firmware updates can overwrite files written this way, so the UI method is strongly preferred.

DNS Filtering and the UniFi DNS Shield

UniFi's DNS Shield (introduced in UNA 7.x, expanded in 8.x) intercepts DNS queries from your network and routes them through Cloudflare's DNS-over-HTTPS infrastructure, with optional content filtering categories. Find it at Settings > Security > DNS Filtering, or in some firmware versions under Traffic & Device Identification > DNS Filtering.

Critical interaction to understand: when DNS Shield is enabled, it overrides the upstream DNS set in your WAN configuration. Clients appear to use whatever you configured in DHCP DNS, but the gateway silently redirects all port-53 traffic through Cloudflare DoH. This is a frequent source of confusion when someone configures Pi-hole — queries still hit the local resolver, but the gateway also intercepts clients attempting to reach external resolvers directly on port 53.

To allow a specific device (like your Pi-hole host) to bypass DNS Shield interception, create a firewall rule permitting that source IP to exit on port 53 unrestricted, placed above the Shield intercept rule in priority. Set the destination to the Pi-hole IP specifically, not "any" — keep the rule tight.

Verifying DNS Settings from Client Devices

Windows

macOS

Linux

iOS and Android

On iOS, go to Settings > Wi-Fi > [network name] > (i) > Configure DNS. If set to Automatic, iOS uses whatever DHCP provides. Switch to Manual to override with a specific server for testing. On Android, navigate to Settings > Network & Internet > Private DNS to configure DNS-over-TLS. Note that Private DNS bypasses DHCP-pushed servers entirely and may bypass Pi-hole or DNS Shield. If network-wide DNS filtering matters, disable Private DNS on those devices or add a UniFi firewall rule blocking outbound port 853.

Self-Hosted UniFi Network Server vs Cloud Gateway

If you run UniFi Network Application on a Raspberry Pi, Ubuntu server, or Docker container — without a UniFi gateway — the DNS settings in UNA have no effect on client DNS for your network. On a self-hosted setup:

• DNS for the UNA host machine is set at the OS level: /etc/resolv.conf, systemd-resolved, or Netplan on Ubuntu.
• Client DNS is controlled by whichever device serves DHCP on your network — usually your ISP router. Configure DNS there, not in UNA.
• If you adopt a UniFi Security Gateway (USG) or UniFi Dream Router as your gateway device, DNS for the network is controlled through UNA exactly as described in this guide.

The most common self-hosted confusion: someone installs UNA, adopts access points only (no UniFi gateway), and wonders why DNS settings in UNA have no effect on client DNS. UniFi APs are layer-2 devices. They pass traffic but don't serve DHCP or DNS. Your existing router still handles that entirely, and UNA doesn't touch it.

Common Misdiagnoses

1. DNS settings don't appear to save. The change likely did save, but existing DHCP leases haven't expired. Renew leases on test clients as shown above. In UNA before 8.2, a known bug sometimes required clicking Apply Changes twice to persist DNS overrides — upgrade if you're still on an affected version.

2. Pi-hole shows no queries from the UniFi network. You set Pi-hole's IP in the WAN DNS field instead of the per-network DHCP DNS field. The gateway queries Pi-hole, but clients query the gateway IP — which forwards queries upstream while bypassing Pi-hole's logging interface. Fix: set the Pi-hole IP in the DHCP DNS field of each network, not the WAN DNS field.

3. Some devices bypass custom DNS. Hardcoded DNS in smart TVs, Google Home, and Android Private DNS ignores DHCP-pushed servers. Block outbound port 53 and port 853 in your UniFi firewall, permitting only your intended resolver IP as the destination.

4. Internal hostnames stopped resolving after a firmware update. Firmware updates can overwrite custom dnsmasq configurations added via SSH. Use the built-in Local DNS Records UI — those entries survive firmware updates because they're stored in the UniFi database, not in raw dnsmasq config files.

5. Guest VLAN has no DNS. Client isolation is blocking access to the gateway IP on that network. Push a public resolver directly via DHCP DNS for the guest network instead of relying on gateway forwarding — 1.1.1.1 is the simplest fix.

2026 Notes: IPv6, DoH, DoT, and DNSSEC

UniFi's 2025–2026 firmware cycle introduced several DNS changes that affect behavior in ways the UI doesn't make obvious:

• DoH by default in DNS Shield: When Shield is active, the gateway tunnels forwarded queries over DNS-over-HTTPS — even if your WAN DNS is set to a plain address like 8.8.8.8. This improves privacy but adds latency. Disable Shield if you need guaranteed plain-DNS forwarding to a specific upstream.
• DNSSEC validation: UDM firmware 4.x+ supports DNSSEC via dnsmasq. Enable it under Settings > Internet > Advanced > DNSSEC. Be aware that DNSSEC and split-horizon DNS can conflict — if you return different A records for the same hostname internally versus externally, DNSSEC validation may fail on those names with SERVFAIL.
• IPv6 dual-stack resolver paths: With IPv6 enabled via DHCPv6 or SLAAC, clients prefer IPv6 resolution paths. Set IPv6 upstream DNS in the WAN configuration to avoid falling back to ISP resolvers on v6 traffic. Cloudflare's 2606:4700:4700::1111 is a reliable choice.
• Mobile OS encrypted DNS bypass: Android Private DNS (DoT on port 853) and iOS DoH in Safari bypass your DHCP DNS configuration entirely. To enforce network-wide DNS filtering on mobile clients, block port 853 outbound and restrict HTTPS traffic to known public DoH resolver IPs from within your UniFi firewall rules.

For foundational DNS protocol reference, RFC 1035 is the canonical document — useful when debugging dnsmasq behavior at the packet level or tracing DNSSEC validation failures through the chain.

Confirming the Fix Worked

After applying DNS changes in UniFi, run through this checklist before calling it done:

1. Renew DHCP leases on a test client in each affected network.
2. Confirm the client received the correct DNS server: ipconfig /all on Windows or resolvectl status on Linux.
3. Query a public hostname: nslookup google.com should resolve in under 50ms if your upstream is healthy.
4. If you configured local DNS records, query a local hostname: nslookup nas.lan 192.168.1.1 should return the LAN IP you entered.
5. From the gateway SSH shell, confirm dnsmasq is running: ps aux | grep dnsmasq.
6. If using Pi-hole, confirm queries appear in the Pi-hole query log within 30 seconds of a DNS lookup on a client device.

If resolution works but is slower than expected, compare latency directly: run dig +stats google.com @1.1.1.1 and compare it to dig +stats google.com @192.168.1.1. A gap of more than 20ms on the gateway path suggests the forwarding layer has a problem — check whether DNS Shield or DNSSEC validation is adding overhead you didn't anticipate.