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 click here!

Benefits of the Roaming Client

• 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 MacOS Roaming Client is downloaded as a Package Installer. The supported Operating Systems are MacOS Catalina, Mojave, High Sierra, Sierra, Big Sur, Monterey and Ventura. It can be downloaded here:

• Branded DNSFilter MacOS Roaming Client
• WhiteLabel MSP MacOS Roaming Client

PGP/GPG Install Method:

PGP/GPG are both programs that 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. Similar steps can be followed for verifying the file checksum via PGP on Linux as well:

1. For the macOS, you can use brew and once that has been installed, you can then use the following command to install GPG via Terminal: brew install gpg or brew install gnupg
   Or you may use which ever appropriate Linux/Windows commands (e.g. Linux: Distro based yum/apt/…)
2. Download our public key from here and save it to dnsfilter_public.asc
3. Import the public key:

   gpg --import dnsfilter_public.asc

4. Download the installer and the installer.sha256sum.asc checksum file:
   DNSFilter Agent installer
   DNS Agent installer
5. Checksum files:
   DNSFilter Agent file
   DNS Agent file
6. Verify the checksum against the downloaded installer
7. In Terminal, run the following command: brew install sha3sum
8. Here's an example for macOS:

   gpg -o - --verify DNSFilter_Agent_Setup_x64-1.7.15.0.msi.sha256sum.asc | shasum -a 256 -c

9. Make sure you see the OK from Step 5 next to the msi installer line, ie:

DNSFilter_Agent_Setup_x64-1.7.15.0.pkg: OK

If it says FAILED, you should re-download and try running the commands again to verify, and if it still fails, please contact support. A failed example would look like the following:

DNSFilter_Agent_Setup_x64-1.7.15.0.pkg: FAILED

 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-1.3.1-Installer.pkg.sha256sum.asc" | shasum -a 256 -c

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.

How would I specify local domains that should follow normal DNS resolution rules?

• At this moment, there is no way to do that manually during the installation – the agent tries to do it automatically with interface search domains.

Silent Install

You can easily install the Mac Roaming Client through the command line or trigger these commands through a RMM tool.

Method 1

This example code assumes you’ve downloaded the installer package and downloaded files go into the Mac’s Downloads folder:

cd ~/Downloads && echo "<your site key here>" > dns_agent_site_key && sudo installer -dumplog -store -pkg "DNSFilter Agent-Installer.pkg" -target /

If using a RMM or other tool to install the Roaming Client, below is a useful bash script which will download and install the Roaming Client without the need to distribute the PKG file to the computers.

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

Method 2

If more settings are required by your location like local domains you can use a configuration file during installation.

The Config file must be called dns_agent.conf and it must be in the same directory as the .pkg file.

Example config file:

SITE_SECRET_KEY=123456789012345678901234
LOCAL_DNS_AND_DOMAINS=10.0.0.1:53,10.0.0.2:53=domain1.local,domain2.local,domain3.local;192.168.0.1:53,192.168.0.2:53=domain1.loc,domain2.loc,domain3.loc
OVERRIDE_CONFIG_FILE=no

Settings Explanation:

LOCAL_DNS_AND_DOMAINS is a comma separated list of local domains. If you have multiple sets of local domains intended for different DNS servers, use a semicolon to separate the various lists (this is shown in the example config file). Domains ending in .local are automatically sent to the original DNS settings of the machine.

OVERRIDE_CONFIG_FILE if set to yes, this will overwrite any previous Roaming Client settings with those in the config file.

This example code also assumes you’ve downloaded the installer package and downloaded files go into the Mac’s Downloads folder:

cd ~/Downloads && sudo installer -dumplog -store -pkg "DNSFilter Agent-Installer.pkg" -target /

It's not currently possible to hide the tray icon for MacOS Roaming Client. If this is a feature you are interested, vote here to express your interest and be notified of any development on this request.

DNS-over-TLS

Version Log

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