In this article

Network admins follow this article to configure local domains and resolvers, ensuring seamless access to internal resources while maintaining DNS security through DNSFilter.

Review our local domain and resolver guide for more detail on how this solution can work in your network environment.

Local domains can be set up to function alongside Roaming Clients via:

• DNSFilter dashboard
• DHCP DNS Search Suffix
• Windows Install flag, e.g. LOCALDOMAINS= during Roaming Client installation
• Windows registry settings

How Roaming Clients handle DNS traffic

Roaming Clients intercept DNS requests on the device and then route each request to one of the following:

• DNSFilter for policy enforcement
• The internal DNS resolver
• A domain-specific resolver, if configured

Routing behavior depends on the Roaming Client version and the connection or filtering mode in use.

When Local Domains and Local Resolvers are required
Local Domains and Local Resolvers are needed when the agent uses loopback-based DNS interception:

• Windows Roaming Client in Loopback mode
• macOS Roaming Client
• iOS and Android Roaming Clients

When Local Domains and Local Resolvers are not used
Windows Roaming Client 3.0 and higher ignore Local Domains and Local Resolvers when using:

• Transparent Proxy
• DNS PreCheck

These modes rely exclusively on the DNS resolver already provided by the network or VPN.

Best Practices

• Specify only necessary local domains to limit security risks. Remember that DNSFilter automatically forwards all .local domain requests to the network's originally configured DNS servers, regardless of other network settings
• Ensure your firewall allows EDNS to prevent local DNS resolution failures. Check settings to confirm local DNS queries route correctly
• Use FQDNs whenever possible. Reserve short hostnames for cases like printers or IoT devices, and test locally to confirm resolution

DNS Resolution Priority

More specific local domain configurations take priority. If a local domain is set using DHCP, registry, or installation flags, it will override an identical domain configured in the DNSFilter dashboard. For example, if DHCP provides acme.com and the same domain is set in the DNSFilter dashboard, the device will use the original DNS server from the network interface.

Less specific local domains in the DNSFilter dashboard take priority over broader configurations. If DHCP provides a more specific domain (e.g., corp.acme.com) and a broader domain (acme.com) is set in the DNSFilter dashboard, the dashboard's resolvers will take precedence over the original DNS server on the network interface.

🚨 Multi-Site Considerations All Roaming Clients will use the local resolvers specified in the dashboard, which could result in DNS queries traversing site-to-site VPN or MPLS links before reaching the resolver.

Platform and version considerations

Windows Roaming Client 3.0 or higher

• Transparent Proxy and DNS PreCheck do not use Local Domains or Local Resolvers
• Internal DNS routing follows the device’s original resolver (DHCP, static, or VPN-provided)
• Use Local Domains and Local Resolvers only when using Loopback mode

Windows Roaming Client (pre-3.0) or Loopback mode

• Requires Local Domains and Local Resolvers for Split-Horizon DNS or internal-only domains
• Supports dashboard, registry, DHCP suffixes, or installation flags

macOS, iOS, and Android Roaming Client

• Accepts DNS queries directly and routes them based on Local Domains and domain-specific resolver lists
• Uses Local Domains and Local Resolvers to send traffic to internal DNS instead of DNSFilter

Configure local domains and resolvers

Test local domains resolve to the correct resolver with this PowerShell command:

resolve-dnsname [local domain] -server [local resolver]

DNSFilter Dashboard

Use the Local Domains feature to direct internal traffic to local resolvers such as LAN DNS, Active Directory DNS, or private name servers.

This setup is useful when:

• DHCP’s DNS Search Suffix isn’t configured properly
• Roaming Client installation lacks local domain setup, e.g. macOS devices
• Registry management of local domains is too complex
• LAN environments aren’t suited for DNSFilter Relay
• Network local domains change frequently and need easy updates
• Split-tunnel VPN setups require specific local domain resolution

🚨 IMPORTANT: Local resolvers must be added to the dashboard—they do not default to the originally configured DNS like .local addresses. Adding any valid network resolver ID will suffice.

Follow these steps to add local domains and resolvers to the dashboard.

1. From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients
2. Tab to Local Domains
3. Select the Network Site associated with the Roaming Clients that should reroute the local traffic
4. Enter local domains and resolvers. Traffic sent to local resolvers will attempt the IPs descending from top to bottom on the list—not descending order numerically
5. Select Save

DHCP DNS Search Suffix (Windows)

Configuring a search suffix in DHCP—e.g. internal.bigco.com—allows devices to automatically append domain suffixes to unqualified queries (e.g., internal).

Installation flag (Windows)

The Windows Roaming Client can pass local domains during installation using the flag variable LOCALDOMAINS=. The flag creates the DNSDomainSuffixList in the registry.

The downside to this implementation is that these local domains remain even when roaming off the corporate network. Queries won’t be sent to DNSFilter for lookup, but will be sent to the local DNS for that network.

Registry (Windows)

For Windows Roaming Client version 3.0.0 and later, configure local domains and resolvers in the appsettings.overrides.json file as shown below:

"LocalDomains": {
  "GlobalLocalDomains": [
    "mydomain.lab",
    "fakedomain.ca"
  ]
},
"LoopbackProxy": {
  "LocalResolvers": [
    "192.168.0.1",
    "192.168.1.3"
  ]
}

Admins can modify local domains post-installation by editing the Windows registry (agent versions older than 3.0). Separate entries with a comma.

• HKLM\SOFTWARE\DNSFilter\Agent in the DNSDomainSuffixList key

• HKLM\SOFTWARE\DNSAgent\Agent in the DNSDomainSuffixList key

Modifying the daemon.conf (macOS)

1. Open the daemon.conf file
2. Enter this command:

   • sudo nano /Library/Application\ Support/DNSFilter\ Agent/daemon.conf

   • sudo nano /Library/Application\ Support/DNS\ Agent/daemon.conf

3. Set local_dns_and_domains (example below) for the endpoint

   [misc]
   local_dns_and_domains = "10.0.0.1:53,10.0.0.2:53=domain1.local,domain2.local,domain3.local;192.168.0.1:53,192.168.0.2:53=domain1.loc,domain2.loc,domain3.loc"

4. Restart the Roaming Client:

   • Stop command:

     sudo launchctl bootout system /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist

     Start command:

     sudo launchctl bootstrap system /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist

   • Stop command:

     sudo launchctl bootout system /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist

     Start command:

     sudo launchctl bootstrap system /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist