MacOS Roaming Client Deployment Guide

Article author
Josh L
  • Updated

The MacOS Roaming Client is endpoint software which provides off-network protection and allows per-machine granularity when using DNSFilter. It is also a suitable alternative if your ISP uses Carrier-Grade NAT.

Roaming Client Installation

The DNSFilter MacOS Roaming Client is downloaded as a Package Installer. The supported Operating Systems are Big Sur, Monterey, Ventura, Sonoma.

Download Package Installer:

Local Domains

Prior to taking over your DNS, we make note of your previously configured DNS IPs. We restore your original configuration when the agent is shut down, or as part of a reboot. Review the What are Local Domains article to learn more about options for your specific situation.


To prevent DNS interception or tampering by third parties, you may optionally configure the Roaming Client to use DNS-over-TLS. The article Enabling DNS-over-TLS explains how to enable on Roaming Clients.

PGP/GPG Install Method

PGP/GPG are both programs that offer an additional layer of security to protect your electronic communications. Below are included optional installation steps that can be done if extra security is needed. Similar steps can be followed for verifying the file checksum via PGP on Linux as well.

  1. For the macOS, use brew, and once that has been installed, 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 and save it to dnsfilter_public.asc
  3. Import the public key:
    gpg --import dnsfilter_public.asc
  4. Download the installer:
  5. Download the installer.sha256sum.asc checksum file:
  6. Verify the checksum against the downloaded installer
  7. In Terminal, run the following command: brew install sha3sum
    Here's an example for macOS:
    gpg -o - --verify DNSFilter Agent-Installer.pkg.sha256sum.asc | shasum -a 256 -c
    Make sure you see the OK from Step 5 next to the MSI installer line

If clients require a specific version of the .asc checksum files, contact Support.

Silent Install Method

Install the MacOS Roaming Client through the command line or trigger these commands through an RMM tool.

For WhiteLabel MSP MacOS Roaming Client

Replace DNSFilter Agent-Installer.pkg with DNS Agent-Installer.pkg

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 an 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.

curl -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, 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:


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 /

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 (i.e.: Office, School, etc.), use that Site.
  • If the end user 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 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?

  • From the DNSFilter Dashboard, you may optionally create a list of local domains and/or hostnames and force those DNS queries to a specific set of DNS resolvers.

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

Release Notes / Version Log

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

Was this article helpful?

1 out of 2 found this helpful

Have more questions? Submit a request



Article is closed for comments.