This guide is for troubleshooting any issues associated with the Roaming Client.
This guide assumes that the Tray Icon has been enabled at install time, which is contextually important for troubleshooting the Roaming Client.
If you are in the testing phase of deploying the Roaming Client, it’s recommended to keep the Tray Icon enabled until initial issues which prevent wider deployment are resolved.
If you are beyond the testing phase of deploying the Roaming Client and do not have the Tray Icon enabled, all troubleshooting steps will need to be followed.
The first thing to check when diagnosing problems with the Roaming Client is to check for software conflicts. Some software applications have a known conflict with the Roaming Client, and their settings will need to be adjusted or turned off to ensure smooth operation.
Browsers, VPNs, and Security Software
Our Software Conflicts article has a list of software that we have identified will have to be adjusted for DNSFilter to work properly on your network and on Roaming Clients. Check this article to see if any of the applications listed are being used in your environment.
Windows Roaming Client v1.12.0 has been updated with improved compatibility when running on machines that also leverage virtualized platforms or technologies that previously could conflict with DNSFilter and it's use of Port 53. Improvements should be seen when using Hyper-V, Windows Subsystem for Linux (WSL), and Docker or Windows Sandbox containers.
While the Hyper-V hypervisor itself or its virtual machines do not conflict with the Roaming Client, we have seen issues with some services that the Hyper-V system uses. The chief culprit is the "Internet Connection Sharing" (ICS) service, which automatically runs a DNS server on 0.0.0.0:53 (all interfaces), which prevents the Roaming Client system service from being able to start.
On Windows 11 and 10 the issue likely occurs either after waking from sleep or after shutdown . The error logs for your agent will show an error about being unable to bind to port 53.
If the Roaming Client service (DNS Agent/DNSFilter Agent) starts BEFORE the ICS service, the ICS service can start with no issues, so as a work around there are two approaches:
- Open a command prompt under Administrator mode and disable any trigger for Host Network Service via triggerinfo
sc qtriggerinfo hns delete
- Restart your machine.
- Stop the Host Network Service (HNS) service (required before you can stop the ICS service).
- Stop the Internet Connection Sharing service.
- Start the Roaming Client service.
- Restart the Host Network Service (which will automatically restart the ICS service as well).
Note. If you set the HNS and ICS services to manual start as a startup type, this may give the RC service enough time to start before them on a reboot. This avoids having to have manual stop/start of services each time to get the RC to run.
Windows Defender Application Guard
If you are not running any virtual machines, it could be that a Windows Defender feature called Application Guard (which uses Hyper-V) is turned on. This feature uses Hyper-V to open untrusted sites in an isolated container in the Microsoft Edge browser. If you run in an environment where Edge is your primary browser, you may want to consider switching to Chrome Enterprise.
If Application Guard is in use, you may see the same behavior as you do with the Hyper-V example above, and the issue can be resolved similarly, as the Application Guard service will also use ICS.
In exceptional situations, after the client is installed, Windows will display a limited network connectivity indicator (a yellow triangle) in the tray menu.
Here are a few possible causes and solutions:
- A limitation in NCSI - Microsoft’s Network Connectivity Status Indicator (NCSI) feature. Since the Fall 2017 Creator’s Update of Windows 10, this can be easily remedied by running the below line in an Administrative Command Prompt:
reg add "HKEY_LOCAL_MACHINE\SOFTWARE\POLICIES\MICROSOFT\Windows\NetworkConnectivityStatusIndicator" /v UseGlobalDNS /t REG_DWORD /d 1 /f
- NCSI is blocked - Especially true if you have a heavily restricted policy. Whitelist the domain
msftncsi.comin your policy.
USB Wi-Fi and HotSpots
Most USB-based Wi-Fi and HotSpot devices enforce their own DNS servers on the network adapter that is created when plugged in. As a result, they will likely not be compatible. Testing is encouraged.
Juniper SRX Firewall
If you are using the Juniper SRX Firewall, DNS Doctoring will need to be disabled, which is only available in the Command Line Interface. More information available In Juniper’s Documentation.
Roaming Client Malfunction
If you have checked for known software and hardware conflicts and believe that the Roaming Client is malfunctioning, there are a few troubleshooting steps that you can take:
Check Service Status (Started/Stopped)
The tray icon for the Roaming Client should be Blue or Green. If it is Red, this is an indication that the client is not actively filtering DNS queries. There may be a problem with the system service. Verify the status of the service by:
Rto open the Run dialog. Type in
services.mscand hit Enter.
- Scroll down to the service called
DNS Agent(MSP Version). You may also check this via the command-line using:
SC QUERY "DNSFilter Agent"
or for the MSP version below:
SC QUERY "DNS Agent"
The Agent status should be “started” and “running”. If the Agent is “stopped”, you can restart it from the services menu or by running:
SC START "DNSFilter Agent"
or for the MSP version below:
SC START "DNS Agent"
Check Port Bindings
In addition to checking the service status of the Roaming Client, you will want to check that no other applications are binding to DNS ports on the local machine (127.0.0.X:53).
You can discover this by running the following prompt command:
netstat -ban | findstr :53
The image below illustrates the ideal output of the command. The first line shows that the local listen to address and port (TCP) 127.0.0.2:53 is listening for connections from any address (0.0.0.0:0). The LISTENING message shows that this connection is actively bound by the Roaming Client and listening for traffic. The second line shows the same thing for UDP (although the connection is not active). **If there are other connections listening on 127.0.0.X:53, there may be a port binding conflict between that software and the Roaming Client.
Netstat showing proper Roaming Client binding
Check Transparent Proxying
If the service is started, and the Roaming Client ports are properly bound, you should check to see if DNS requests are being proxied on your network or by your ISP. Our Transparent Proxying article goes into detail on this subject.
Roaming Client Not Filtering
When the tray icon is a green or blue color, filtering should be occurring. If domains which should be blocked are not being blocked, there could be software or network settings which interfere with the DNS queries (usually the response, rather than the query).
Generating a HAR file
- Open Chrome and go to the page where the issue is occurring.
- Look for the ⋮ button and select More Tools > Developer Tools.
- From the panel that appears, select the Network tab. You must keep the menu open while you reproduce the issue.
- Look for a round record button in the upper left corner of the tab, and make sure it is red. If it is grey, click the button once to start recording.
- If it isn't, check the Preserve log box.
- Click the crossed circle button to clear any existing logs from the network tab.
- Reproduce the issue while the network requests are recorded.
- Click the download button, Export HAR, to download, and save the file to your computer: Save as HAR with Content.
- Upload the HAR file to your ticket
If using a VPN, try disabling the VPN to see if it’s interfering with the ability to filter DNS requests. You may need to contact support with the brand/version of the VPN to investigate further.
Windows Roaming Client Logs
As of v 1.10.2, the number of logs kept by the Windows RC is limited to a max of 10 files with a size limit of 20 MB.
Logging is enabled with the Windows Roaming Client by default. It is set up to hold 1 week's worth of log files and then delete the oldest one each time it gets to 7 log files.
Getting over these roaming client logs is one of the best ways for DNSFilter to diagnose the issue. If a computer with the Roaming Client installed is continually having an issue that can be replicated, please follow these steps:
- If your system tray icon is not hidden, you can utilize our Diagnostic Tool if you're running the 1.10.5 version of our roaming client or newer. If it is hidden, you can run this same script by downloading it here, and it will generate the files in C:\temp instead.
You will first right-click on the tray icon and select "Diagnostic Tool"
After this, you'll be presented with the below screen, where you can select the reasoning for running this tool. These options do not affect how the tool will be run. It's purely for us. After you select an option, click "Run Diagnostics Now." It will then run and automatically open up your file explorer to Downloads, where there will be a zip file that contains everything we will need to troubleshoot your issue further.
Once you have the folder opened from either method above, please find and attach the zip file to your ticket.
Providing logs is necessary if you are experiencing issues with the Roaming Client, such as:
- No DNS Resolution
- Failure to resolve local resources
- No Internet Connectivity
- Failure to start the System Service
Please send the logs to DNSFilter Support