In this article

In macOS Roaming Client 2.2.0, captive portal login pages (e.g., on airplanes, in hotels, or cafés) may not appear when connecting to networks that require web-based authentication. This occurs when the client cannot detect the network’s DNS resolver, so the captive portal check never starts.

Update to latest agent version

Version 2.3.8 or higher includes these changes:

• Travel Wi-Fi mode: Adds a manual option that opens a short window for captive-portal sign-in on inflight, hotel, and other public Wi-Fi networks. Protection resumes automatically when the window ends
• Better network recovery: Reduces cases where the agent showed Offline or stopped resolving DNS after changing networks
• Improved captive portal loading: Sign-in pages now appear more reliably on public Wi-Fi, reducing stalls or failures

What we know

Our team identified three issues that could contribute to the behavior in v2.2.0: 

• Device DNS configuration stuck to 127.0.0.1. On some systems, the DNS setting is locked to 127.0.0.1 from older client versions that upgraded to 2.X. On macOS, the Roaming Client cannot remove this setting due to OS restrictions—it must be cleared via MDM or manually by an administrator
• Local DNS resolvers may be required but aren't detected. Some networks (e.g. hotels, cafés, airplanes) rely on private DNS resolvers (like 10.x.x.x or 192.168.x.x) to present the captive portal. If the Roaming Client doesn’t detect and use this local resolver, and instead tries a public DNS server (like 8.8.8.8), the portal will not appear—and network access may fail
• Encrypted DNS blocked by captive portals. If the client attempts to use DNS-over-TLS (DoT) first, the request may be blocked by the captive portal before login, preventing detection

How to work around the issue

Update to the 2.3.x agent version. If an update is not an option, try the following in order:

1. Check for 127.0.0.1 as the DNS resolver
   • If found, remove it manually or via MDM
   • ⚠️ The Roaming Client cannot remove or modify a 127.0.0.1 resolver setting on macOS due to Apple's system restrictions. This must be done outside the client
2. Add a public DNS resolver
   • In the DNSFilter Dashboard, go to the site’s Local Resolvers section and add a public resolver like 8.8.8.8
   • ✍️ Note: This may work on some networks, but will not help if the network requires use of its own local resolver (e.g. on many airline or hotel networks)
3. Change DNS protocol order in daemon.conf
   • On the affected device, open the daemon.conf file

     1. Locate: upstream_order = [ "tcp-tls", "udp", "tcp" ]

        Note: If the line doesn’t exist, it is using the default setting, so you need to add the line, as opposed to changing the line. It must be at the top of the config or the change will break the file

     2. Change it to: upstream_order = [ "udp", "tcp-tls", "tcp" ]
4. Save the file and restart the Roaming Client service
   • This forces the client to try unencrypted UDP DNS first, improving the chance that the captive portal will respond

Change DNS protocol order MDM script

This is an example MDM script to update the daemon.conf to set DNS protocol order to prioritize UDP.

This script is designed to look for updates in both standard and whitelabel environments.

#!/bin/zsh
​
user=$(id -u)
if [[ $user -ne 0 ]]; then
    echo "Please run as root"
    exit 0
fi
​
​
sleep 2
​
# Stop the daemon
if [[ $(launchctl list | grep com.dnsfilter.agent.macos.helper) ]]; then
  sudo launchctl unload /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist
  echo "Stopped DNSFilter Agent"
  daemon_conf_dir="/Library/Application Support/DNSFilter Agent"
  daemon_conf_file="daemon.conf"
elif [[ -f "/Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist" ]] && [[ $(launchctl list | grep io.netalerts.agent.macos.helper) ]]; then
  sudo launchctl unload /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist
  echo "Stopped DNS Agent"
  daemon_conf_dir="/Library/Application Support/DNS Agent"
  daemon_conf_file="daemon.conf"
else
  echo "No DNS agent is installed on this machine"
  exit 1
fi
​
# Wait a few seconds to ensure the daemon stops
sleep 5
​
upstream_order_line="upstream_order = [ \"udp\", \"tcp\", \"tcp-tls\" ]"
temp_file="/tmp/temp_daemon.conf"
config_file="${daemon_conf_dir}/${daemon_conf_file}"
​
# Check if the line with upstream_order exists in the config file
if sudo grep -q "upstream_order" "$config_file"; then
  # Replace the line with udp
  sudo awk -v upstream_order="$upstream_order_line" '/upstream_order/ {$0=upstream_order} 1' "$config_file" > "$temp_file"
else
  echo "$upstream_order_line" | cat - "$config_file" > "$temp_file"
fi
​
# Replace the original config file with the new one
sudo mv "$temp_file" "$config_file"
​
sleep 3
​
sudo cat "$config_file"
​
​
​
# Check which agent is installed, and start.
if [[ -f "/Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist" ]]; then
  sudo launchctl load -w /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist
  echo "Started DNSFilter Agent"
elif [[ -f "/Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist" ]]; then
  sudo launchctl load -w /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist
  echo "Started DNS Agent"
else
  echo "No DNS agent is installed on this machine"
fi