Skip to main content

How can we help you?

Search

help Knowledge Base
forum Community
checklist Release Notes
event Events

Install macOS Roaming Client v1.8.6 and older

Minetta Gould
  • Updated

    In this article

This is a legacy article outlining how to deploy the macOS Roaming Client v1.8.6 and older. As of agent version 2.2.0 the architecture of the macOS agent updated to a System Extension method that requires a new, updated installation method. 

Update to the latest agent version for a fully supported filtering experience. 

Install macOS Roaming Client v1.8.6 and older

Insure devices are on and connected to the internet during the installation process.

Before installation, create a Site to associate with the Roaming Client.

Step one: Copy Site Key

✍️ Out of date installer packages are not available for download. 

  1. From the DNSFilter dashboard, navigate to Deployments and select Sites
  2. Select the Site to associate with the agent
  3. Under Advanced, copy the Site Key

Step two: Run the installer

  1. Run the installer package
  2. Paste in the Site Key
  3. Click through the installer and agree to any security prompts

The Roaming Client is now active and filtering DNS requests. A tray icon will appear and show active status. 

✍️ macOS root certificate

As of macOS 15 Sequoia, Apple requires an administrator password to install the agent's root certificate. If running an OS version older than 15 and deploying an older agent the certificate will deploy automatically. If either are newer, the certificate deployment is manual.  

Step three: Test the connection

  1. Verify the Roaming Client is active and filtering the desired categories by visiting debug.dnsfilter.com
  2. Attempt to browse to a well-known domain that is allowed by your policy (i.e., google.com)
  3. Attempt to visit a domain on your policy Block List in Incognito Mode

Silent installation legacy method

There are two methods to deploy the v1.x.x macOS Roaming Client via silent install: with or without the need for additional location-based settings, like Local Domains.  

Deploy without location-based settings

  1. Follow the Roaming Client deployment guide for details to setup a Site, copy the Site Secret Key, and download the installer
    1. Confirm the installer is in the mac's Downloads folder
  2. Add the Site Secret Key and run this command:
    • cd ~/Downloads && echo "<your site key here>" > dns_agent_site_key && sudo installer -dumplog -pkg "DNSFilter Agent-Installer.pkg" -target /
    • cd ~/Downloads && echo "<your site key here>" > dns_agent_site_key && sudo installer -dumplog -pkg "DNS Agent-Installer.pkg" -target /

Deploy with location-based settings

Use a configuration file during installation if more settings are required by location.

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

  1. Prepare the Config file by adding the Site Secret Key and local domains. Use this example for reference:

    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

    Config File details

    LOCAL_DNS_AND_DOMAINS is a comma separated list of local domains. Separate local domain lists with a semicolon (see example config). 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.

  2. Download the installer into the mac's Downloads folder. Follow the Roaming Client deployment guide for detailed download steps
  3. Add the Site Secret Key and run this command:
    • cd ~/Downloads && sudo installer -dumplog -pkg "DNSFilter Agent-Installer.pkg" -target /
    • cd ~/Downloads && sudo installer -dumplog -pkg "DNS Agent-Installer.pkg" -target /

RMM legacy method

This command requires the .pkg file is already installed on the device. Note to replace "your site key here" before running the command. 

  • #!/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 -pkg DNSFilter%20Agent-Installer.pkg -target /
  • #!/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 /

Related legacy deployment articles

🚨 Important: these additional deployment guides only apply to agent versions 1.8.6 and older. Follow the 2.2.0+ installation guide for up to date Silent (MDM) installation. 

 

Was this article helpful?
0 out of 0 found this helpful
Return to top

Comments

0 comments

Please sign in to leave a comment.