MacOS Roaming Client Deployment Guide

Article author
Josh Lamb
  • 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 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, and Monterey – we are currently testing on more Operating Systems, so you can expect more to be listed. It can be downloaded here:

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.

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 /

For WhiteLabel MSP MacOS Roaming Client replace

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

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:


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 /

For WhiteLabel MSP MacOS Roaming Client replace

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

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.


Roaming Client Auto Updates

The MacOS Roaming Client will automatically update within 1 to 2 days of us releasing a new version. It can be forced to auto update through a restart of the service, or by reboot!

The automatic update service can be disabled in your organization settings.


To prevent DNS interception or tampering by third parties, you may optionally configure the Roaming Client to use DNS-over-TLS.


Version Log

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

Was this article helpful?

0 out of 1 found this helpful

Have more questions? Submit a request



Article is closed for comments.