Skip to content

DNS Filter - Endpoint Deployment

Testing Encouraged

A standalone installation is recommended 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. One area we strongly recommend testing is the resolution of local domains.

At this time there is no DNS Filter Agent for Linux.

Windows#

Download the DNS Filter client for windows here. SolCyber will provide you with a Site Key to be used during agent installation.

Usage of the DNS Filter agent on Windows Server operating systems is NOT supported. Protect your servers by deploying DNS Filter at the Network Level.

GUI Installation#

Double click the installer, follow the on screen instructions and enter the site key when prompted.

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

Command-Line (Silent) Installation#

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

Additional command-line options:

  • TRAYICON="disabled" Hiding the tray icon can be desirable to 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, which will decrease end-user awareness of the client, thereby reducing tampering attempts to disable the software. This is particularly useful if the end users commonly have Administrative access to the local machine.

For more documentation on other Windows deployment options, please see:

https://help.dnsfilter.com/hc/en-us/articles/1500008104822-Windows-Roaming-Client-Deployment-Guide

Client Uninstall#

Agent version 2.01 and above#

  1. Copy the GUID from this registry key:

    text
    Computer\HKEY_LOCAL_MACHINE\SOFTWARE\DNSAgent\Agent

  2. Insert the GUID into this prompt and run it from an administrator command prompt:

    text
    msiexec /X{GUIDHERE} REGCLEAN=true/false (to remove and cleanup registry or not)

The Roaming Client will be uninstalled once the command run finishes.

If an error occurs during the uninstall process, re-run the commands with these edits to create a log file. Our Support team can review these files to investigate the issue.

text
msiexec /X{GUIDHERE} REGCLEAN=true/false (to remove and cleanup registry or not) /L*vx! FOLDERANDLOGFILE (eq: C:\Temp\dns_agent_uninstall.log)

Agent versions BEFORE 2.01#

The DNS Filter 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 client in the list of installed programs).

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

text
wmic product where name="DNS Agent" call uninstall

Known Issues and Limitations#

MacOS#

SolCyber will provide you a Site Key to use during installation.

The DNS Filter agent requires specific macOS permissions. These permissions can be granted via MDM profiles, or manually, via end-user interaction. We strongly recommend using an MDM to deploy DNS Filter and its accompanying profiles to your end user devices.

Silent Install (no user interaction)#

Step 1: Deploy the Extension.mobileconfig Profile#

  1. Download DNSAgent Extension.mobileconfig
  2. Upload Extension.mobileconfig to your MDM
  3. Deploy to all target macOS devices
  4. Verify that it is successfully installed before continuing

This profile approves the system extension used by the agent.

Step 2: Deploy the Proxy.mobileconfig Profile#

Deploy this profile after confirming successful deployment of the Extension profile.

  1. Download DNSAgent Proxy.mobileconfig
  2. Upload Proxy.mobileconfig to your MDM
  3. Deploy to all target macOS devices
  4. Verify the Proxy profile is active on the endpoint

This profile configures the network proxy required for the agent to function correctly.

Step 3: Deploy the DNS Filter certificate#

When a user browses to a blocked site, the following page will display:

Because DNS Filter is intercepting the blocked site and displaying a different webpage, the browser will display a certificate mismatch error if the DNS Filter Root CA certificate is not installed on the computer.

  1. Download the root CA certificate: https://app.dnsfilter.com/certs/NetAlerts.cer
  2. Deploy the certificate to all target macOS devices using your MDM.

Step 4: Install the the Roaming Client#

While each MDM is different, below you will find a useful bash script which will download and install the Roaming Client without the need to distribute the PKG file to the computers.

bash
#!/bin/bash
curl https://download.dnsfilter.com/User_Agent/MacOS/DNS%20Agent-Installer.pkg -o /tmp/DNS%20Agent-Installer.pkg
cd /tmp
echo "your site key here" > dns_agent_site_key && sudo installer -dumplog -pkg DNS%20Agent-Installer.pkg -target /

Standard Install (end user must approve prompts)#

Step 1: Download and Install the Roaming Client#

bash
#!/bin/bash
curl https://download.dnsfilter.com/User_Agent/MacOS/DNS%20Agent-Installer.pkg -o /tmp/DNS%20Agent-Installer.pkg
cd /tmp
echo "your site key here" > dns_agent_site_key && sudo installer -dumplog -pkg DNS%20Agent-Installer.pkg -target /

Users will be presented with the following prompts during install:

Step 2: Deploy the DNS Filter certificate#

When a user browses to a blocked site, the following page will display:

Because DNS Filter is intercepting the blocked site and displaying a different webpage, the browser will display a certificate mismatch error if the DNS Filter Root CA certificate is not installed on the computer.

Use the following bash script to download and install the root CA (requires admin “sudo” password):

bash
#!/bin/bash
curl https://app.dnsfilter.com/certs/NetAlerts.cer -o /tmp/NetAlerts.cer
sudo /usr/bin/security add-trusted-cert -d -r trustRoot -p ssl -p basic -k /Library/Keychains/System.keychain /tmp/NetAlerts.cer

Client Uninstall#

text
sudo sh /Applications/DNS\ Agent.app/Contents/Resources/uninstall.sh