Windows Roaming Client Deployment Guide

The Windows Roaming Client is endpoint software that provides off-network protection and allows per-machine granularity when using DNSFilter. It is also a good alternative if your ISP uses Carrier-Grade NAT.

Benefits of Roaming Client

• Active Directory Deployment - The Roaming Client can be distributed across your infrastructure using Group Policy, allowing you to deploy at scale and fit within your existing software ecosystem. It can be tagged so that the dashboard matches your Active Directory OUs.
• Granular Reporting - Each computer with the Roaming Client has a unique history that’s recorded in our Query Log and our Reporting section of the Dashboard, allowing the identification of infected computers or unwanted browsing habits quickly.
• Roaming - Computers with the Roaming Client are protected when roaming to other networks, such as home offices, coffee shops, airports, etc.
• Tagging - Using the tagging feature, you can easily change policies for large groups of computers. Use cases include teachers/students, corporate departments, public/private computers, etc.

Roaming Client Installation

The DNSFilter Windows Roaming Client is a Microsoft Installer (MSI) package and can be installed in a variety of methods. The supported Operating Systems are Windows 10 and 11. It can also be installed via Active Directory. Window's Server Operating Systems and any shared desktop environments are NOT supported. We recommend utilizing a network deployment to keep them protected.

PGP/GPG Installation Method

PGP/GPG programs offer an additional layer of security to protect your electronic communications. Below we have included optional installation steps that can be done if extra security is needed in your environment. This applies to the Windows and MacOS Roaming Clients:

1. For the Windows OS, start by downloading PGP/GPG from these instructions here
2. (Optional) Make sure to add the installation directory to your path so you may type "gpg" from a command line rather than "C:\Program Files\GnuPG\gpg":
   - Go to Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables
   - Choose "Path", and select "Edit", and to the very end of the value, add; C:\Program Files\GnuPG (note the preceding semi-colon)
   - Click OK until you're out of the System dialog box.
   - For this to take effect, you must close any open command windows and start a new one.
3. Download our public key from here.
4. Save the public key somewhere, i.e., C:\Users\Joe\Desktop\dnsfilter-public-key.asc
5. Import the public key:

   gpg --import C:\Users\Joe\Desktop\dnsfilter-public-key.asc

6. Download the installer and the installer.sha256sum.asc checksum file:

   Windows x64

   Installers:
   DNSFilter Agent Installer
   DNS Agent Installer
   Checksums:
   DNSFilter Agent Checksum
   DNS Agent Checksum
   

   Windows x86

   Installers:
   DNSFilter Agent Installer
   DNS Agent Installer
   Checksums:
   DNSFilter Agent Checksum
   DNS Agent Checksum
7. Verify the checksum against the downloaded installer
8. Here's an example for Windows:

   gpg -o - --verify DNSFilter_Agent_Setup.msi.sha256sum.asc | "C:\Program Files (x86)\Gpg4Win\bin\sha256sum.exe" -c -

9. Make sure you see the OK from Step 5 next to the MSI installer line, i.e.:

 Pro Tip: If the file has a space in it, the command should wrap the entire filename in quotes, like this:

gpg -o - --verify "DNS_Agent_Setup.msi.sha256sum.asc" |" C:\Program Files (x86)\Gpg4Win\bin\sha256sum.exe" -c -

If clients require a specific version of the .asc checksum files please contact support - support@dnsfilter.com

Site Association

Upon installation, Roaming Clients must be associated with a specific Site. Whichever Site is associated with the Roaming Client, the DNS queries generated by the Roaming Client will be billed to that Site.

I don’t have a Site. I only intend to use the software and not point DNS at the local network level.

• Create a Site with no IP address associated with it.

I have multiple Sites. With which Site do I associate a Roaming Client?

• If the computer is normally at a specific location (i.e., Office, School, etc.), use that Site.
• If the end-user is always remote and will never be locally on a specific Site, the Site is irrelevant; remember, this will be used for billing.
• Sites can be changed at any time if you change your mind about with which site a Roaming Client is associated.

Once you’ve chosen the Site, generate a Site Secret Key (SSK) from the Roaming Client Deployments panel in the dashboard. This key will be required when installing the Roaming Client.

Standalone Installation

GUI Installation

To perform a standalone GUI installation of the Roaming Client, navigate to the Roaming Client Deployments panel in the dashboard and download and run the installer. You will need the Site Secret Key, which is available on that page.

Below is a screencast illustrating the installation process:

Verify operation by ensuring the tray icon is either blue or green. If the tray icon is red, refer to our Roaming Client Troubleshooting section for more information.

Command-Line (Silent) Installation

The Roaming Client can also be deployed silently via a command prompt.

To perform a silent installation of the client, install the Roaming Client with all default options, and use the below command in an administrative prompt (Please ensure your sitekey is copied as it appears directly from your dashboard):

msiexec /qn /i "C:\path\to\DNSFilter_Agent_Setup.msi" NKEY="SITESECRETKEY"

For Whitelabel version:

msiexec /qn /i "C:\path\to\DNS_Agent_Setup.msi" NKEY="SITESECRETKEY"

Several additional command-line options are available:

• TAGS="tag1,tag2" will associate tags in the Dashboard for easier management of groups of Roaming Clients. They can be whatever you want to specify (locations, people groups, etc.).
• HOSTNAME="SomeOtherHostname" allows you to specify a custom hostname. If this option is not specified, it will default to the Windows hostname of the system.
• TRAYICON="disabled" Hiding the tray icon can reduce end-user awareness of the Roaming Client, thereby reducing tampering attempts to disable the software. The more strict the content filtering policies are, the more likely this is. (Please also remember that hiding the tray icon will make it more difficult to troubleshoot any issues that should arise.)
• ARPSYSTEMCOMPONENT=1 This will hide the Windows Client from the Add/Remove programs list, decreasing end-user awareness of the client and thereby reducing tampering attempts to disable the software. This is particularly useful if the end users commonly have Administrative access to the local machine.
• LOCALDOMAINS="dom1.local,dom2.local" This parameter allows you to specify additional local domains at the install time of the client. (Keep in mind that Search Suffixes provided by Active Directory are automatically added by the client when it starts up and reads the adapter configuration)

Active Directory Installation

The Windows Roaming Client can be mass distributed via Active Directory by creating a Group Policy Object (GPO). Using Microsoft Transform (MST) files, you can integrate any of the command-line options listed above with the installer. This means you can smoothly deploy the client with preset tags, show/hide the tray icon, and associate the client with a specific network location.

The image below shows what the final result looks like in the management panel. Roaming Clients will have a name, one or more tags, and will be associated with a particular site. Policies and block pages can be assigned to groups of clients or even just to one. This ensures you can be as specific as possible in your filtering.

Active Directory Install Procedure

The installation procedure for the Roaming Client is based on the standard method of using Group Policy. The steps are as follows:

1. Create a distribution point for the MSI and MST files. This is done by creating a shared network folder on Windows Server.
2. Generate an Orca transform. This is an MST file containing the Site Secret Key (SSK) for the building location you would like the clients to associate with and any custom tags you would like to attach to the client. You must generate a new transform file for different locations to use the SSK only for a particular site. Otherwise, the clients will all be associated with one network. (note that the Orca tool can be obtained for free from the Windows 10 SDK)
3. Create & Assign GPOs. For each location (and for each unique configuration), create a GPO which is linked to your desired OU for that network. Assign the MSI and MST files using the “Advanced” deployment method.

A start-to-finish screencast of deploying the Roaming Client via Active Directory is below:

Distributed Installation

MST Transform Installation

Some customers desire to mass deploy roaming clients but are not using Active Directory to distribute the installation. This is particularly true of an MSP which uses Remote Monitoring & Management (RMM) software. You can distribute the MSI with all of your options as an Orca transform file. Follow the instructions above to generate an MST, then deploy it via the below command (or your RMM equivalent):

msiexec /qn /i "C:\path\to\DNSFilter_Agent_Setup.msi" TRANSFORMS="C:\path\to\orcatransformed.mst"

Golden-Image Installation

Installing the Roaming Client must be the last step of the image setup process if using a standardized image to deploy or reinstall computers. If the Roaming Client is installed with an active network connection and allowed to register with our API, the Roaming Client will not receive a unique ID on each computer that received the standardized image.

Please use the following steps to ensure the Roaming Client is installed but does not register:

1. Download the Roaming Client Installer from the Dashboard
2. Disconnect all active network connections
3. Install the Roaming Client
4. Finalize Image

Scripted Installation

If using an RMM or other tool to install the Roaming Client, below is a useful PowerShell script that will download and install the Roaming Client without the need to distribute the MSI file to the computers.

mkdir C:\temp
Invoke-WebRequest -Uri "https://download.dnsfilter.com/User_Agent/Windows/DNSFilter_Agent_Setup.msi" -OutFile "C:\temp\DNSFilter_Agent_Setup.msi"
msiexec /qn /i "C:\temp\DNSFilter_Agent_Setup.msi" NKEY="SITESECRETKEY"

For Whitelabel Version:

mkdir C:\temp
Invoke-WebRequest -Uri "https://download.dnsfilter.com/User_Agent/Windows/DNS_Agent_Setup.msi" -OutFile "C:\temp\DNS_Agent_Setup.msi"
msiexec /qn /i "C:\temp\DNS_Agent_Setup.msi" NKEY="SITESECRETKEY"

Roaming Client Uninstall

The Roaming Client can be removed via the Add/Remove programs control panel as most applications unless a silent installation with the ARPSYSTEMCOMPONENT=1 an option has been specified (which hides the client in the list of installed programs).

A command-line uninstallation can also be called using an administrative command prompt or GPO:

To Uninstall a Standard Account Roaming Client:

wmic product where name="DNSFilter Agent" call uninstall

To Uninstall an MSP Roaming Client:

wmic product where name="DNS Agent" call uninstall

Roaming Client Uninstall Notifications

DNSFilter account administrators can be alerted when users uninstall the Windows roaming client. This new capability provides visibility into unexpected uninstalls. Navigating to Deployments → Roaming Clients → Settings will allow an admin to enable notifications. 

Roaming Client 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 (often, these servers are AD Domain Controllers).

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

Technical Details

The Windows 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 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 (Optional)

The Tray Icon displays basic information about the status of the Roaming Client.

Windows Tray Icon Statuses

• If the tray icon is blue, it means that the client is functioning normally. The Windows system service is operational, and the client has contacted our servers. Filtering is active.
• If the tray icon is green, it means the client is online and communicating over an encrypted connection.
• If the tray icon is red, it means 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.

Startup Process

When the Windows Roaming Client system service starts, the following actions occur.

• The DNS Proxy binds to 127.0.0.2:53 (tcp and udp).
  • Fail: The Roaming Client service does not start. Troubleshooting help can be found here.
  • Success: The Roaming Client system service starts successfully.
• The State Machine sends test DNS queries to DNSFilter to ensure the firewall is not blocking DNS resolution to 3rd-party DNS servers.
  • If DNSFilter servers cannot be reached over port 53/udp and tcp, attempt port 853 TLS
  • If DNSFilter servers cannot be reached over port 853
  • Fail: The Roaming Client cannot filter DNS queries and waits until it can reach DNSFilter over port 53 or 853. Troubleshooting help can be found here.
  • Success: The Roaming Client moves on to the next phase.
• The State Machine imports the local list of DNS Suffixes from the Network Adapter properties to forward local DNS queries to the DHCP-delegated or statically-assigned DNS servers.
• The Roaming Client records the DHCP-delegated or statically set DNS servers and is used to resolve local DNS queries.
• The State Machine sets the DNS server on the network adapter to 127.0.0.2 (DNS Proxy)
• The DNS Proxy begins sending public DNS queries directly to DNSFilter, and any requests to *.local, RFC-1918 addresses, and domains that exist in the DNS Suffixes list (usually specified by the DHCP server or Active Directory) are sent to the DHCP-delegated/statically-assigned DNS servers that were originally assigned to the Network Adapter.
• When referring to our "Last Sync" within the tray icon or in our dashboard, this references when the last time the agent communicated with our API to pull the local domains list ONLY. This does NOT determine when a policy has been last updated, as this is done in real-time. This Last Sync occurs either on a service restart or a device restart.

Version Log

You can find the history of Windows Roaming Client release notes on our public changelog.