DNSFilter Knowledge Base

Windows Roaming Client Deployment Guide

A guide for deploying the Roaming Client to one or many machines.

The Windows Roaming Client is endpoint software which 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 the 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, as well as our Reporting section of the Dashboard, allowing 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 7, 8, 8.1, 10 (64-bit only) /w .NET Framework 4.5 It can also be installed via Active Directory .

Site Association

Upon installation, Roaming Clients must be associated with a specific sitesite - A site is the physical location of one network (such as an office-building). . 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 (ie: Office, School, etc), use that Site.
If the enduser always remote and will never be locally on a specific Site, the Site is irrelevant; just remember this will be used for billing.
Sites can be changed at any point in 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) for it from Roaming Client Deployments panel in the dashboard. This key will be required when installing the Roaming Client.

Standalone Installation

🚧

Testing Encouraged

A standalone installation is recommend when initially testing the Roaming Client on your computers/network. DNSFilter recommends 1-2 days of testing with one or more computers to ensure smooth operation before performing a mass deployment.

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, simply use the below command in an administrative prompt:

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

There are several additional command-line options that 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 be desirable to reduce enduser 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 keep in mind 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, which will decrease enduser awareness of the client, thereby reducing tampering attempts to disable the software. This is particularly useful if the endusers 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). Through the use of Microsoft Transform (MST) files, you can also integrate any of the command-line options listed above along with the installer. This means that you can smoothly deploy the client with preset tags, show/hide the tray icon, and associate the client to 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 to a certain site. Policies and block pages can be assigned to groups of clients, or even just to one. This ensures you have the capability to be as specific as possible in your filtering.

Roaming Client Tagging

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 which contains the Site Secret Key (SSK) for the building location you wish the clients to associate to, as well as any custom tags you wish to attach to the client. For different locations, you will need to generate a new transform file so the SSK is used only for a particular site. Otherwise, the clients will all be associated to 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 both 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

If using a standardized image to deploy or reinstall computers, installing the Roaming Client must be the very last step of the image setup process. 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 which 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 a RMM or other tool to install the Roaming Client, below is a useful PowerShell script which will download and install the Roaming Client without the need to distribute the MSI file to the computers.

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"

Roaming Client Un-Installation

The Roaming Client can be removed via the Add/Remove programs control panel as most applications, unless a silent installation with the ARPSYSTEMCOMPONENT=1 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 Operation

The Roaming Client functions by running a local proxy on 127.0.0.2:53 of the host. 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 make adjustments 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, sleep/wake, close/open laptop lid, 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 which 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 Agent 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 made contact with 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 with 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. Troubleshoot
    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, attempt port 5353
    If DNSFilter servers cannot be reached over port 5353
    Fail: The Roaming Client cannot filter DNS queries, and waits until it can reach DNSFilter over port 53 or 5353. Troubleshoot
    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 so that it may forward local DNS queries to the DHCP-delegated, or statically-assigned DNS servers.
  • The DHCP-delegated, or statically set DNS servers are recorded by the Roaming Client, and 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 which 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.

Version Log

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

Updated 2 months ago

Windows Roaming Client Deployment Guide


A guide for deploying the Roaming Client to one or many machines.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.