In this article

Network admins use this article to understand how the DNSFilter Roaming Client intercepts and filters Domain Name System (DNS) traffic on Windows and macOS devices, including the connection modes and filtering modes available in current agent versions.

The Roaming Client is endpoint software that enforces DNSFilter policies on devices. The agent applies the assigned policy wherever the device connects: office networks, home networks, guest networks, and mobile hotspots. The device-level identity stays consistent across locations, providing per-machine visibility and control.

How Roaming Clients operate

Although the Windows and macOS agents use different OS-supported methods, both follow the same high-level workflow:

1. Intercept DNS requests at the device level
2. Evaluate each request according to the assigned policy
3. Forward allowed requests to the appropriate DNS resolver
4. Route local-domain queries to local DNS servers when applicable
5. Report device state and diagnostics to DNSFilter

The exact interception method depends on the platform and version.

Windows agent behavior

Windows Roaming Client v2.x and earlier

Earlier versions of the Windows agent only used a loopback interception model:

• The agent updated the device’s DNS settings to point to 127.0.0.x or ::1
• A local DNS proxy listened on these loopback addresses
• The proxy decided whether to forward requests to DNSFilter or to local DNS servers
• Local DNS suffixes and DHCP information were used to identify internal domains

This method remains available in v3.x for compatibility.

Windows Roaming Client v3.x and higher

Windows v3.x introduces a new internal architecture with separate services, updated configuration management, and OS-native interception support. Two key changes impact operational behavior:

Service-based architecture

The Windows agent now includes discrete applications, such as:

• Service Manager – handles configuration updates, registration, diagnostics, and application monitoring
• Filtering service – performs DNS interception and applies filtering rules
• Tray application – displays connection status and diagnostics

These components operate independently for improved stability.

Updated interception methods

Windows v3.x supports two connection modes:

• Transparent proxy – uses Windows Filtering Platform to intercept DNS traffic without modifying DNS settings
• DNS loopback – retains legacy loopback behavior for environments that rely on it

Each mode has different operational characteristics; both are valid depending on deployment requirements.

A separate article provides a full comparison of connection modes and filtering modes .

Windows configuration and logging

Windows v3.x replaced legacy .config and registry-based settings with a unified JSON configuration system stored in an environmental or special folder labeled %ProgramData%. The typical build path is %ProgramData%\DNSFilter, Inc (branded) or %ProgramData%\DNS Agent (Whitelabeled).

Key points:

• appsettings.json reflects dashboard-managed configuration and should not be overridden
• appsettings.Overrides.json supports administrator-supplied local overrides

This structure simplifies configuration management and reduces registry dependency.

macOS agent behavior

Transition from loopback to Apple System Extension

Earlier macOS agents (1.x) intercepted DNS by redirecting requests to 127.0.0.1, where the local DNS proxy could filter traffic.

This method became unreliable as macOS 11 and later introduced new network security restrictions.

The macOS 2.x agent now uses:

• Apple System Extension
• Network Extension DNS APIs

These frameworks provide Apple-supported DNS interception and long-term OS compatibility.

Operational characteristics of the macOS System Extension:

• Intercepts DNS at the OS level using documented APIs
• Supports routing to local DNS servers for internal domains
• Avoids modifying resolver settings or rerouting traffic to localhost
• Provides consistent behavior across macOS 11, 12, 13, and later
• Supports deployment through MDM with required user authorization prompts

This architecture ensures reliable filtering as macOS continues phasing out unsupported interception methods.

Common components

Across both platforms, the Roaming Client includes:

State Machine

Monitors system events such as network changes, adapter state, sleep/wake events, and DNS configuration updates. Determines when the agent must rebind listeners, refresh configuration, or update resolver routing.

DNS evaluation

The filtering service determines whether to:

• Forward requests to DNSFilter
• Forward requests to local DNS servers
• Return a block response
• Apply filtering according to the selected filtering mode

Tray or menu bar application

Displays the Roaming Client status, version, and diagnostics access.
Status indicators may show whether the agent is connected, encrypted, or unable to filter.

Network routing behavior

The Roaming Client records:

• Local DNS servers provided by DHCP or static configuration
• Local DNS suffixes specific to the network
• Network adapter transitions

Local-domain queries (for example, internal domains or domain controllers) route to the appropriate local DNS resolver when the operating system provides that information.

This behavior applies across both Windows and macOS agents.