In this article

The macOS Roaming Client (v2.2.0 and higher) uses Apple’s System Extensions framework for secure, system-wide DNS interception. While this improves stability and security, it also means that VPN clients, endpoint detection and response (EDR) tools, and firewalls can conflict with DNSFilter when they install their own DNS proxy or enforce DNS rules.

Causes

• Single DNS Proxy Limit
  macOS allows only one DNS proxy to intercept DNS traffic system-wide. If another application binds to ports 53 or 5454, the Roaming Client cannot function
• Separate Routing Contexts
  VPNs using user-space networking may operate outside the protected routing tables used by Network Extensions, creating routing mismatches that break DNS interception
• VPN-Enforced DNS Tunneling
  VPNs often route all DNS traffic through their tunnel, bypassing DNSFilter unless configured for split DNS/tunneling
• Security Tool DNS Enforcement
  EDR and firewall products may implement their own DNS rules, use competing Network Extensions, or bind to DNS ports before DNSFilter, preventing proper DNS interception

Solutions

1. Disable Competing DNS Features
   • Turn off “Use custom DNS” or similar settings in VPN clients
   • Disable DNS enforcement or DNS proxy features in EDR/firewall products
2. Use Split DNS/Tunneling
   • Send only specific domains (such as internal domains) through the VPN
   • Route all other DNS queries through DNSFilter
3. Confirm No Port Conflicts

   • Verify only DNSFilter is bound to ports 53 and 5454:

     lsof -i :53
     lsof -i :5454

   • Remove or reconfigure any service occupying these ports
4. Check Active System Extensions
   • Ensure only DNSFilter is active for DNS interception
5. Restart in the Correct Order
   • Disconnect VPN → Restart DNSFilter → Reconnect VPN
   • This allows DNSFilter to bind to required ports first
6. Restart the Device
   • Apply all configuration changes and clear residual conflicts

Palo Alto GlobalProtect limitation

While Palo Alto GlobalProtect is connected, internal domains configured in the DNSFilter dashboard do not resolve through the macOS Roaming Client v2.x. This is a macOS platform limitation with no configuration workaround for v2.x.

macOS allows only one DNS proxy to own DNS traffic on a VPN tunnel at a time. GlobalProtect registers as a transparent proxy and takes ownership of DNS flows before the Roaming Client can respond, so lookups for internal domains fail for the duration of the VPN session. Public DNS filtering through DNSFilter continues to work normally.

The following solutions in this article do not apply to the GlobalProtect case:

• Disable Competing DNS Features
• Use Split DNS/Tunneling
• Restart in the Correct Order

The macOS Roaming Client v1.8.6 uses a legacy loopback architecture that does not conflict with GlobalProtect's transparent proxy. However, v1.8.6 is end-of-life and unsupported. DNSFilter does not recommend running unsupported software in production environments.

For assistance, submit a Support request with the details listed in the If Issues Persist section.

DNS-over-HTTPS fallback for VPNs that block port 853

Some VPNs enforce full-tunnel DNS routing and block port 853, which is the port the macOS Roaming Client uses for DNS-over-TLS. When this happens, filtering silently stops; blocked domains load normally with no block page and no dashboard alert.

As of macOS Roaming Client v2.4.6, DNS-over-HTTPS (DoH) fallback is available as an opt-in solution. When enabled, the client uses doh.dnsfilter.com on TCP/443 as a last-resort transport. This is a port VPN full-tunnel policies typically cannot block without also breaking HTTPS entirely.

DoH fallback is off by default. Enabling it is an opt-in action and does not change default behavior. With the flag off, the original bypass behavior remains.

Even with DoH enabled, a brief unfiltered window of a few seconds to approximately 20 seconds may occur when a VPN tunnel reconnects, depending on the VPN type.

How to enable DoH fallback

There are exactly two supported methods. DoH fallback cannot be set via an Apple MDM configuration profile, the DNSFilter dashboard, or any synced API response.

Method 1: At install time (via dns_agent.conf):

Add ENABLE_DOH_FALLBACK=true to the dns_agent.conf file placed in the same folder as the installer package before deployment. See Pre-configure macOS Roaming Client settings before MDM deployment for the full dns_agent.conf reference.

✍️ The dns_agent.conf file must be in the same directory as the installer package. Some MDM tools copy only the package to a scratch folder, which silently drops the conf file.

Method 2: On a live device (via configuration.json):

Add "EnableDoHFallback": true under Options in the device's configuration.json. The change takes effect in approximately 15 seconds with no reinstall or reboot required.

Network requirements

doh.dnsfilter.com on TCP/443 must be reachable and excluded from TLS inspection. If TLS inspection intercepts this hostname, DoH fails silently. See URLs and IP address ranges for DNSFilter deployments for the full endpoint list.

If Issues Persist

Collect the following and open a request for our Support team to review:

• Security product name and version
• Summary of configuration changes made
• macOS agent diagnostic logs