Windows Roaming Client Deployment Guide

Windows Roaming Client Deployment Guide

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 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 (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 " -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 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 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 (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 (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.

    • Related Articles

    • Windows Roaming Client Troubleshooting

      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 ...
    • MacOS Roaming Client Deployment Guide

      The MacOS 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. For local domain documentation, please ...
    • Linux Roaming Client

      While we don't have an officially supported Roaming Client for Linux devices, for the use case where a Linux device is on a LAN which cannot be configured using the normal Site Deployment Guide, you may decide to use our Relay product to fill the ...
    • Site Deployment Guide - Installing SSL Certificates

      Installation of the DNSFilter SSL Root certificate is optional. It is utilized to display block page messages when users attempt to visit https://websites that are blocked in your Policy. Without certificate installation, the user will receive an ...
    • Site Deployment Guide - Configuring Your Network

      After you have Tested Your Connection with one computer to DNSFilter servers, you can change your network configuration to point all outbound DNS traffic to our servers. This will ensure comprehensive filtering and security coverage for all devices ...
    • Popular Articles

    • Old Browser Versions

      Question: I am using an older browser version and am having problems. What can be done ? We are not able to upgrade the browser at this time.   This is a challenge for any company that makes software that utilizes a browser. Since Stoneware does not ...
    • LCS Redirection

      Problem: How to redirect the LCS in an environment with multiple LCSs and students connecting to them. Solution(s): Create an allow.cfg on all LCS(s) (including the Master) in the network, however, even if no allow.cfg is present on an LCS, machines ...
    • Time windows allows for Service Shutdown

      Issue: Can the time windows gives a service to shut down before it kills the service be increased? Solution: Yes, the following information comes from the Microsoft URL : To specify the wait time, do the ...
    • How to disable password saving - Internet Explorer

      Having multiple methods for saving a password in the browser can cause confusion for the user.   To disable password saving in Internet Explorer, launch Internet Explorer and perform the following steps. Click the blue Settings menu icon in the upper ...
    • How to disable password saving - Chrome

      Having multiple methods for saving a password in the browser can cause confusion for the user.  To disable password saving in Chrome, launch Chrome and perform the following steps. Click the Chrome menu button in the upper right corner of the Chrome ...
    • Recent Articles

    • Lenovo Unified Workspace Released

      Highlights of Unified Workspace Before you install: Please view the installation notes here. Requires new 7.0 license file. Below is a list of enhancements and fixes for Unified Workspace New Profile Style New Login ...
    • How to fix customized login and profile after upgrading to v7.0

      With the release of 7.0 the default login page has been modified to simplify the customization process.  If you are having an issue with the login page not displaying, after upgrading to v7.0, you will need to delete the custom CSS code and start ...
    • SAML SP - Sync Directory Password

      Login script to prompt for directory password Since the user does not login into Unified Workspace with a password, we cannot capture the password to use in the @@password@@ variable.  If you would like to use the Active Directory password for other ...
    • MySQL 8 SSL

      Issue Admin is making a database connection to a MySQL 8 database.  When clicking the Ping button on the DB Connection object, the following error is presented: WARN: Establishing SSL connection without server's identity verification is not ...
    • 7.0 excludeProtocols - includeProtocols - allowCiphers - denyCiphers config file

      excludeProtocols - includeProtocols - allowCiphers - denyCiphers config file The following configuration is recommended for systems running, and higher. (For older 6.5 releases of UW, please see this article.) ...