DNSFilter Knowledge Base

Windows Agent Deployment Guide

A guide for deploying the User Agent to one or many machines.

The Windows User agent 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 User Agent

  • Active Directory Deployment - The User Agent 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 User Agent 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 User Agent 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.

User Agent Installation

The DNSFilter Windows Agent 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, User Agents must be associated with a specific site - site - A site is the physical location of one network (such as an office-building). . Whichever Site is associated with the User Agent, the DNS queries generated by the User Agent 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 User Agent?
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 User Agent is associated.

Once you've chosen the Site, generate a Site Secret Key (SSK) for it from Agent Deployments panel in the dashboard. This key will be required when installing the User Agent.

32-bit Unsupported

32-bit operating systems are currently unsupported. If you attempt to install the package, you will receive an error that says "This installation package is not supported by this processor type. Contact your product vendor."

Vote/comment for this feature in our Feature Request System

Standalone Installation

Testing Encouraged

A standalone installation is recommend when initially testing the User Agent 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 User Agent, navigate to the Agent 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:

User Agent Standalone Installation

User Agent Standalone Installation

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

Command-Line (Silent) Installation

The User Agent can also be deployed silently via a command prompt.

To perform a silent installation of the agent install the User Agent 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 user agents. 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 Agent, 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 Agent from the Add/Remove programs list, which will decrease enduser awareness of the agent, 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 agent. (Keep in mind that Search Suffixes provided by Active Directory are automatically added by the agent when it starts up and reads the adapter configuration)

Active Directory Installation

The Windows User Agent 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 agent with preset tags, show/hide the tray icon, and associate the agent to a specific network location.

The image below shows what the final result looks like in the management panel. Agents 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 agents, or even just to one. This ensures you have the capability to be as specific as possible in your filtering.

User Agent Tagging

User Agent Tagging

Per-machine filtering

DNSFilter plans in the future to implement user-based filtering that is synchronized to Active Directory OUs. However, current filtering policies are per-network or per-machine. In most environments, machines are given to particular users, so the desired effect of limiting access to certain users can be achieved.

Active Directory Install Procedure

The installation procedure for the User Agent 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 agents to associate to, as well as any custom tags you wish to attach to the agent. For different locations, you will need to generate a new transform file so the SSK is used only for a particular site. Otherwise, the agents 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 User Agent via Active Directory is below:

Deploying the User Agent with Active Directory

Deploying the User Agent with Active Directory

Distributed Installation

MST Transform Installation

Some customers desire to mass deploy roaming agents 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 User Agent must be the very last step of the image setup process. If the User Agent is installed with an active network connection and allowed to register with our API, the User Agent will not receive a unique ID on each computer which received the standardized image.

Please use the following steps to ensure the User Agent is installed, but does not register:

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

User Agent Un-Installation

The User Agent 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 agent 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 User Agent:

wmic product where name=“DNSFilter Agent” call uninstall

To Uninstall an MSP User Agent:

wmic product where name=“DNS Agent” call uninstall

User Agent Operation

The User Agent functions by running a local proxy on 127.0.0.2:53 of the host. The Agent sets itself as the sole DNS server on the computer, so that all internet DNS requests are sent to DNSFilter.

Before the User Agent 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 User Agent automatically detects when a new network adapter (wireless, wired, VPN, etc) is activated, and will make adjustments accordingly.

Technical Details

The Windows User Agent 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 User Agent.

Windows Agent Tray Icon Statuses

Windows Agent Tray Icon Statuses

  • If the tray icon is blue, it means that the agent is functioning normally. The Windows system service is operational and the agent has made contact with our servers. Filtering is active.
  • If the tray icon is green, it means the agent is online and communicating over an encrypted connection.
  • If the tray icon is red, it means the agent 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 User Agent system service starts, the following actions occur

  • The DNS Proxy binds to 127.0.0.2:53 (tcp and udp).
    Fail: The User Agent service does not start. Troubleshoot
    Success: The User Agent 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 User Agent cannot filter DNS queries, and waits until it can reach DNSFilter over port 53 or 5353. Troubleshoot
    Success: The User Agent 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 Agent, 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.