Direct internal resource traffic to local servers when using Roaming Clients

How Roaming Clients handle DNS traffic

Roaming Clients intercept DNS requests on the device and 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 agent version and the connection or filtering mode in use.

When local domains are required

Local domains are required when the OS or network configuration does not provide enough information to identify local domain suffixes and Classic DNS Filtering mode is active.

Classic DNS Filtering mode applies to both DNS Loopback Connection mode (always) and Transparent Proxy Connection mode (when configured to use Classic DNS Filtering).

Without local domain configuration, the agent may not be able to determine whether a domain belongs to a local resolver or should be resolved by DNSFilter—which can result in local domains returning invalid or unexpected results.

DHCP hints, Active Directory configuration, search lists, and DNS suffixes configured at the network or Windows level may supply this context automatically.

When these are not available or configured, the Local Domains feature in the DNSFilter dashboard provides an alternative. See Understanding local domains and resolvers for more detail on how local domain context is determined.

When local resolvers are required

Local resolvers are only required when using DNS Loopback Connection mode. DNS Loopback intercepts traffic by redirecting it to a specific address, which removes the information needed to identify the original destination of the request.

Local resolvers provide the Roaming Client with the resolver addresses to prioritize for local DNS resolution.

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.

Example

A device gets 192.168.0.1 as its DNS via DHCP, and the following configuration is set in the dashboard:

Local Domains: dundermifflin.com
Local Resolvers: 192.168.100.1

When resolving www.dundermifflin.com, the Roaming Client:

Queries 192.168.100.1
If unreachable, queries 192.168.0.1 (DHCP-assigned DNS)
If still unresolved, forwards the request to DNSFilter

🚨 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 v3.0 and higher

Transparent Proxy + Classic DNS Filtering mode. Local Domains are used to differentiate queries that should route to DNSFilter from those that should resolve locally. Local Resolvers are not used in this configuration and will be ignored
Transparent Proxy + DNS PreCheck Filtering mode. Local Domains and Local Resolvers are not used and will be ignored. DNS PreCheck resolves queries against the local resolver determined by Windows according to OS and platform rules, interface metrics, and IP configuration
DNS Loopback Connection mode. Both Local Domains and Local Resolvers may be used to provide context the agent cannot determine on its own

Windows Roaming Client (pre-v3.0) or Loopback mode

Requires Local Domains and Local Resolvers for split-horizon DNS or internal-only domains. Supports configuration via the dashboard, registry, DHCP suffixes, or installation flags.

macOS, iOS, and Android Roaming Client

Accept DNS queries directly and route them based on Local Domains and domain-specific resolver lists. Use Local Domains and Local Resolvers to send traffic to internal DNS instead of DNSFilter.

Why not the Chrome Extension?

The use of local domains and resolvers isn't necessary for the Chrome Extension Roaming Client because the core functionality is different. When a website is accessed on a Chromebook with the Roaming Client, it first checks with DNSFilter to determine if the site is allowed. If the site is approved, DNSFilter does not provide the website’s address.

Instead, the Chromebook queries the DNS server configured on the device, such as the one assigned by the network via DHCP. As long as the site is allowed, the device relies on its configured DNS server to resolve the request.

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.

From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients
Tab to Local Domains
Select the Network Site associated with the Roaming Clients that should reroute the local traffic
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
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)

Open the daemon.conf file

Enter this command:

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

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

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"

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