Skip to main content

How can we help you?

Search

help Knowledge Base
forum Community
checklist Release Notes
event Events

Install macOS Roaming Client v2.2.0 or higher

Minetta Gould
  • Updated

    In this article

Follow this article to install the DNSFilter Roaming Client v2.2.0+ on macOS devices.

Standard install (end-users must approve prompts)

Follow these steps to deploy the agent to a single device or in unmanaged environments.

🚨 Important

End-users must agree to the system prompts for the update to complete. The Roaming Client does not attempt to reinstall components if any of the prompts are denied; it enters a holding state awaiting user approval or admin intervention.

This is a requirement by Apple, and outside our control. Use the silent install instructions below to avoid end-user prompts.

See Related Content below for troubleshooting steps and frequently asked questions.

  1. From the DNSFilter dashboard, navigate to Roaming Clients 

  2. Select Install Guide

  3. Select a Site to associate the agent with

  4. Copy the Site Secret Key (SSK)

  5. Download the 2.2.0 installer

  6. Start the installation, agreeing to any prompts, including entering the SSK

Once complete, the DNS Proxy will populate in the System Network Filters settings and begin sending traffic to DNSFilter.  

If any of the prompts are denied, the v2.2.0 agent will show up in the DNSFilter Roaming Clients dashboard but appear offline. The device's older Roaming Client version will remain active (if this is not a new install), filtering traffic until the deployment is fixed or the agent version reaches end-of-life. 

Silent install (no end-user prompts)

Follow these steps to install the agent silently using a Mobile Device Management (MDM) solution. 

⚠️ Important Change

As of version 2.2.0, two mobile configuration profiles (.mobileconfig) must be deployed prior to agent installation to complete a silent installation. This is a change from previous versions and requires updates to existing deployment workflows.

RMM tools cannot install .mobileconfig profiles the same way MDM solutions can.
MDM tools use Apple’s system-level management APIs, allowing silent, enforced profile deployment without user interaction.

To avoid user prompts and ensure proper deployment, we recommend an MDM-managed installation.

Prerequisites

These items are necessary for the deployment:

➡️ Two mobileconfig profiles: one for the Extension and Proxy

➡️ The Agent v2.2.0 Installer (.pkg) and Site Secret Key (SSK) from the DNSFilter Roaming Clients dashboard (Install Guide)

➡️ An MDM capable of:

  • Deploying .mobileconfig profiles
  • Deploying .pkg installers
  • Executing shell scripts on macOS endpoints

✍️ Competing profiles—such as other proxy, DNS, or system extension configurations—may interfere with DNSFilter profiles. Review and resolve conflicts within the MDM.

Deployment Process

Follow these steps to deploy the agent. For questions about MDM configurations, consult the vendor's documentation.  

Already have DNSFilter protecting devices on an older agent version?

The way in which the installer package deploys is the same, so once the two mobileconfig files are pushed to devices, auto-updates (if enabled) will continue as expected on the release cadence. The profiles suppress end-user prompts and do not change the functionality of the agent itself.

🚨 Important: Deploying the .pkg installer before these profiles are in place will result in user-facing installation prompts and system password requests. 

Note for JAMF users

When deploying via JAMF, you may see a warning related to the ProviderDesignatedRequirement key in the .mobileconfig profile. This is an Apple-documented key, and the warning appears to be a false flag from JAMF’s parser. You can safely ignore this message and proceed with deployment.

Step 1: Deploy the Extension.mobileconfig Profile

  1. Upload Extension.mobileconfig to your MDM

  2. Deploy to all target macOS devices

  3. 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. Upload Proxy.mobileconfig to your MDM

  2. Deploy to all target macOS devices

  3. Verify the Proxy profile is active on the endpoint

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

Step 3: Host the Agent Installer

Ensure the Agent-2.2.0-Installer.pkg is hosted on a web-accessible location (e.g., your MDM CDN or storage bucket). You'll need the direct URL in the deployment script.

✍️ If your MDM can't host the URL, our S3 URL is available for use:

  • https://download.dnsfilter.com/User_Agent/MacOS/DNSFilter%20Agent-Installer.pkg 

  • https://download.dnsfilter.com/User_Agent/MacOS/DNS%20Agent-Installer.pkg

Step 4: Update the Deployment Script

Use the following script in your MDM, replacing the placeholder values:

  • #!/bin/bash

VERSION="2.2.0"
DOWNLOADURL="https://your-mdm-cdn.com/path/to/DNSFilter Agent-2.2.0-Installer.pkg"
SITE_SECRET_KEY="your-site-secret-key"

FILENAME="DNSFilter Agent-$VERSION-Installer.pkg"
LOCATION="/tmp"
TEMP_CONFIG_NAME="dns_agent.conf"

# Stop existing Agent
pkill -f "DNSFilter Agent.app" || echo "No existing agent to stop."

# Flush DNS cache
dscacheutil -flushcache
killall -HUP mDNSResponder || true
killall mDNSResponderHelper || true

# Download PKG
curl -kL --silent -o "$LOCATION/$FILENAME" "$DOWNLOADURL" || {
    echo "Download failed."
    exit 1
}

# Create temporary config file
cat > "$LOCATION/$TEMP_CONFIG_NAME" << EOF
SITE_SECRET_KEY="$SITE_SECRET_KEY"
LOCAL_DNS_AND_DOMAINS=""
OVERRIDE_CONFIG_FILE=yes
EOF

# Install PKG
sudo installer -dumplog -pkg "$LOCATION/$FILENAME" -target / || {
    echo "Installation failed."
    rm -f "$LOCATION/$FILENAME" "$LOCATION/$TEMP_CONFIG_NAME"
    exit 1
}

# Clean up
rm -f "$LOCATION/$FILENAME" "$LOCATION/$TEMP_CONFIG_NAME"

# Launch agent
sleep 7
open -a "DNSFilter Agent.app" || echo "Launch failed or unnecessary."

exit 0
  • #!/bin/bash

VERSION="2.2.0"
DOWNLOADURL="https://your-mdm-cdn.com/path/to/DNS Agent-2.2.0-Installer.pkg"
SITE_SECRET_KEY="your-site-secret-key"

FILENAME="DNS Agent-$VERSION-Installer.pkg"
LOCATION="/tmp"
TEMP_CONFIG_NAME="dns_agent.conf"

# Stop existing Agent
pkill -f "DNS Agent.app" || echo "No existing agent to stop."

# Flush DNS cache
dscacheutil -flushcache
killall -HUP mDNSResponder || true
killall mDNSResponderHelper || true

# Download PKG
curl -kL --silent -o "$LOCATION/$FILENAME" "$DOWNLOADURL" || {
    echo "Download failed."
    exit 1
}

# Create temporary config file
cat > "$LOCATION/$TEMP_CONFIG_NAME" << EOF
SITE_SECRET_KEY="$SITE_SECRET_KEY"
LOCAL_DNS_AND_DOMAINS=""
OVERRIDE_CONFIG_FILE=yes
EOF

# Install PKG
sudo installer -dumplog -pkg "$LOCATION/$FILENAME" -target / || {
    echo "Installation failed."
    rm -f "$LOCATION/$FILENAME" "$LOCATION/$TEMP_CONFIG_NAME"
    exit 1
}

# Clean up
rm -f "$LOCATION/$FILENAME" "$LOCATION/$TEMP_CONFIG_NAME"

# Launch agent
sleep 7
open -a "DNS Agent.app" || echo "Launch failed or unnecessary."

exit 0

Step 5: Execute the Script via MDM

Deploy the above script using your MDM's scripting functionality. This will:

  • Stop any existing agent process

  • Flush DNS cache

  • Download and install the agent

  • Create and apply the configuration

  • Launch the Roaming Client

Step 6: Post-Deployment Verification

After deployment:

  • Confirm the agent appears in System Settings > Network on the macOS device

  • Check that filtering policies are being correctly applied

  • Test DNS resolution using dig or nslookup to verify traffic is routed through DNSFilter

    • nslookup -type=txt debug.dnsfilter.com
    • dig debug.dnsfilter.com txt

Once the tests are successful the installation is complete. If issues occur, submit a Support Request including diagnostic logs (if applicable), screenshots of error messages, and a summary of the troubleshooting steps already taken. 

Related Content

Troubleshooting

FAQ

Q. I have some agents that aren't under an MDM. Do I have to touch them for this update?
A. If you have auto-updates enabled, you don't have to do anything special for the update to happen, but your end-users will receive security prompts to allow the proxy. We suggest notifying them ahead of time so they aren't caught off guard.

If auto-updates are disabled: just like any other release, you'll need to manually install the agent version. End-users will still receive the prompts.

The .mobileconfig files are specific to performing a silent installation, which can only happen under MDM solutions.

Q. How can I manage the timing of this update?
A. Easy! Turn off auto-updates from the DNSFilter dashboard. From the Roaming Clients Control Center, toggle off the feature for any agents you'd like more control over. 

Q. One of my end-users denied the installation prompts. Will they lose internet connectivity? How do I fix this?
A. If there's an existing Roaming Client on the device—e.g. v1.8.6—it will continue to filtering traffic until v2.2.0 is successfully installed. v2.2.0 will show up in the Roaming Clients dashboard, but will not receive traffic.

The installation prompts should still be in the user's System Privacy & Security and Login Items & Extensions settings. In Privacy & Security, scroll to the bottom of this list and the DNSFilter Agent/DNS Agent prompt will be there. Under Login Items & Extensions, toggle the DNSFilter Agent/DNS Agent on to allow the extension. Restart the device after approving the prompt to push the update. 

Q. I already have DNSFilter agents deployed across my environment, and auto-updates are enabled. Can I just deploy the mobileconfig files, or do I need to update other parts of the install process?
A. Since you've deployed both the Extension.mobileconfig and Proxy.mobileconfig profiles, you're all set for the Production release of the DNSFilter macOS Roaming Client v2.2.0. No further action is required on your end unless you choose to manually install the agent before auto‐update. Once the production release goes live, devices with auto‐update enabled will receive the new agent automatically on the release cadence.

Comments

4 comments

Date Votes
  • Tobias Linder
    • Edited

    Thank you for the new beta. Works great so far.

    What we would love to see is the ability to send the Site Secret Key and other optional values directly with the MDM Profile to the Mac the same way we do it with iPadOS and iOS (see screenshot). Like this we could skip the Deployment script and just push the package to the Mac the same way we normally distribute software.

    It would also be very convenient for the scoping of different sites. Then we could use the same install policy for all Macs and would just have to create different MDM Profiles for different device groups.

    I will also create a feature request for this.

    2
  • Minetta Gould Community Team DNSFilter Staff

    Hey Tobias Linder , glad to hear this version is working well for you, and thanks for the suggestion! Very interesting idea—the Product Team will keep an eye out for your feature request and see what's feasible 💖

    0
  • Daniel Stranathan
    • Edited

    Id LOVE to see a MDM profile for the Secret Key and other site data in a single place, which would simplify the install process. Having to manage additional scripts is messy and not needed in 2025 when we have robust MDMs and Apple's frameworks.

     Thanks Tobias Linder 

    1
  • Minetta Gould Community Team DNSFilter Staff

    Daniel Stranathan Thanks for the feedback! As Tobias mentioned, they created a feature request for this suggestion: feel free to add your vote there to help influence our product development and be notified of any updates on the request. 

    1

Please sign in to leave a comment.