In this article

This article outlines how the DNSFilter Roaming Client works including operation and technical details. 

The DNSFilter Roaming Client is endpoint software which provides roaming protection and allows per-machine data granularity.

When the Roaming Client is installed, manage what devices can access no matter where they're located: on-network, off-network, anywhere in the world. The policy assigned to the device follows it wherever it goes.

Operation

The Roaming Client functions by running a local proxy on 127.0.0.2:53 for Windows and 127.0.0.1:53 for macOS. The client sets itself as the sole DNS server on the computer so that all internet DNS requests are sent to DNSFilter.

Before the Roaming Client changes the DNS settings, it records the DHCP-provided information for the DNS Suffix Search list and DNS servers. This allows it to intelligently route local queries to your local DNS servers for resolution. These servers are often Entra ID Domain Controllers.

The Roaming Client automatically detects when a new network adapter (wireless, wired, VPN, etc.) is activated and will adjust accordingly.

Remote access VPNs can cause filtering policies to not behave as intended. DNSFilter recommends resolving the issue via a split tunnel configuration, but also provide full tunnel instructions if that solution better fits your requirements. 

Technical details

The Roaming Client is comprised of three components:

State Machine

The State Machine decides what actions to take based on various system settings, user actions, and internal health checks. Switching networks, sleeping/waking, closing/opening the laptop lid, and manually changing DNS settings are all examples of what the State Machine monitors and decides if changes need to occur.

DNS Proxy

The DNS Proxy is the service that binds to 127.0.0.2:53 or 127.0.0.1:53 and is responsible for deciding when to forward DNS requests to DNSFilter, or when to forward DNS requests to the local DNS servers.

Tray Icon

The tray icon displays basic information about the status of the Roaming Client. This includes whether it's online or offline, the operating version, and access to the Diagnostic Tool to troubleshoot Roaming Client issues. 

• Blue. The client is functioning normally. The Windows system service is operational, and the client has contacted our servers. Filtering is active.

  Green. The client is online and communicating over an encrypted connection.

  Red. The client is not functioning and filtering is off. This indicates a problem with either the system service or the communication route to our servers.

• The macOS client displays a checkmark ✔️ (online) and X (offline) as status options. 

Last Sync refers to the last time the agent communicated with the DNSFilter API to pull the Local Domains list. It does not reflect filtering policy changes—these update in real-time. Last Sync occurs on a service or device restart. 

Startup process

When the Roaming Client system service starts, 

• The DNS Proxy binds to 127.0.0.2:53 or 127.0.0.1:53 (TCP and UPD connections)
• The State Machine sends test DNS queries to DNSFilter to ensure the firewall is not blocking DNS resolution to 3rd-party DNS servers

✅ When these two actions are successful, 

• The local list of DNS Suffixes import from the network adapter to forward local DNS queries to the DHCP-delegated or statically-assigned DNS servers. The Roaming Client records these DNS servers and uses them to resolve local DNS queries
• The network adapter's DNS server sets to 127.0.0.2 or 127.0.0.1
• Public DNS queries are sent to DNSFilter to resolve. Requests to *.local, RFC-1918 addresses, and domains on the DNS Suffixes list (usually specified by the DHCP server or Entra ID) are sent to the DHCP-delegated/statically-assigned DNS servers

❌ When either the DNS Proxy bind or test DNS queries fails, troubleshoot the issue.

• If the Proxy fails to bind, check for the most common issues: software conflicts and/or transparent proxying. 
• If the DNSFilter servers cannot be reached over port 53/TCP and UDP, attempt port 853 TLS. If the DNSFilter servers cannot reach port 853 the Roaming Client it cannot filter DNS queries. At this point the agent 'fails' and waits until it can reach DNSFilter over port 53 or 853. If the bind fails check if there is a conflict with another app binding to the DNSFilter ports.