In this article
This article helps to diagnose and resolve Roaming Client issues using diagnostic logs. Most of these issues can also be diagnosed without access to the log files; alternative methods are listed were applicable.
Some issues may stem from other factors, so we recommend exploring all troubleshooting resources if you don't find the solution here. Good places to start include checking your security environment, filtering policy configurations, or gaps in the deployment process.
Prerequisites
- Ability to download and view diagnostic logs from an impacted device. Here are links for Windows and MacOS instructions. For a clearer view of the issue, attempt to recreate the error and then run the diagnostic tool
- Admin or higher DNSFilter dashboard permissions
Roaming Client Fails to Install
Cause
The Site Secret Key (SSK) does not match the Site assigned to the agent.
Verify this is the issue
Since the agent fails to install, there won't be an option to collect log files.
Instead, open the installation file and compare the SSK value (Windows= NetworkKey Registry
value MacOS= secret_key
) against the SSK listed for the Roaming Client's Site in the dashboard. If the values do not match edit the file to correct the misalignment.
Solution
-
Edit the installation file to include the accurate SSK for the Site associated with the agent and reinstall the agent
-
If this does not correct the issue, confirm nothing else in your network environment is blocking the appropriate IP addresses and ports to connect to DNSFilter
Filtering Policy isn't blocking websites
Cause
Policy enforcement isn’t working because another service is listening on port 53.
Verify this is the issue
Without the logs: Navigate to the DNS Query Log and verify DNS traffic is registered from the device/Site associated with the agent. If there is not traffic this is likely the issue
With the logs: Review the nslookup
results for any returns listed as vercel-dns.com
. This return indicates another DNS service is likely interfering
Solution
-
Examine your network environment to verify that no other services are listening on port 53
-
Enable DoT as the primary upstream order
Internet Redirects to unknown.dnsfilter.com
Cause
IP addresses are missing or incorrectly configured during deployment, or potentially due to a DDNS error.
Verify this is the issue
No need to use logs for this issue! Here are a couple options to examine IP addresses:
- From an impacted device, follow these troubleshooting steps to examine the listed IP addresses vs. what should be expected
- Run an
nslookup -type=txt debug.dnsfilter.com
command. If nonetworkID
ormyip
values appear, this indicates an issue with the setup
Solution
Verify the setup configuration for the DNSFilter Roaming Client, ensuring the deployment includes all necessary IP addresses.
Agent intermittently goes offline or some websites fail to load
Cause
The network settings prioritize IPv6 instead of IPv4.
Where to Look in Logs
Check DNS servers
under the network adapter settings for any IPv6 addresses.
Solution
-
Update the Roaming Client to the latest production version
-
Edit the
UpstreamIpVersion
to auto-detect IPv6-IPv4 -
Restart the Roaming Client and test
Connection Issues with Internal Wiki or Company-managed resources
Cause
Local domains or resolvers are not configured correctly.
Verify this is the issue
- Without the logs: Navigate to Local Domains in the Roaming Clients dashboard and review the Local Domains and Resolvers are accurate
- With the logs:
-
Search the logs for
LocalResolversValidator
. Any IP address listed as "passed" is verified from the dashboard. If the return is blank this indicates the dashboard configuration needs updates. -
- Attempt to access the internal resource and then gather the logs
- Search the most recent log entries for the resource name
- Examine where the DNS request is sent (if configured correctly, this will be the local resolver) and whether the query is successful. If a misconfiguration is the issue, the query will fail
Solution
Update the Local Domain dashboard configuration to ensure all required IPs for internal domains are listed and live.
Comments
0 comments
Please sign in to leave a comment.