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.

Note: Some users may lose internet connectivity after updating from a v1.x.x agent to v2.x.x or later.

This happens when the device’s DNS settings still point to the old DNSFilter loopback IP, which is no longer used in the new proxy-based agent.

Fix: Update the device’s DNS settings to a public resolver (for example, Google DNS: 8.8.8.8) to restore connectivity.

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 is outside DNSFilter's control. Use the silent install instructions below to avoid end-user prompts. As of agent version 2.3.8, Installation Error prompts are available in the Tray Icon to assist with device prompt approvals.

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

  1. From the DNSFilter dashboard, navigate to Roaming Clients 
  2. Select Install Roaming Client
  3. Select a Site to associate the agent with
  4. Select the applicable OS (macOS)
  5. Download the installer
  6. Copy the Site Key 
  7. Start the installation. After entering the Site Key, end-users must respond to two system prompts:
    1. "DNSFilter Agent"/"DNS Agent" would like to use a new network extension
      1. Select Open System Settings from the prompt
      2. Locate the DNS agent under Network Extensions
      3. Toggle on the extension and enter the local password to confirm the change
         
    2. "DNSFilter Agent"/"DNS Agent" would like to Add DNS Proxy Configurations 
      1. Select Allow 
  8. Deploy the SSL Certificate. Starting with macOS 15, the macOS Roaming Client cannot automatically install the Root CA certificate required to display the Block Page on HTTPS-based websites. End-users will receive a prompt to accept the certificate, but denial will not prevent the agent deployment

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

If any of the installer prompts are denied, the agent will be visible in the DNSFilter Roaming Clients dashboard but will 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. Urge end-users to respond to the Fix Installation Issue prompts from the tray icon to resolve the issue.

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, mobile configuration profiles (.mobileconfig) are deployed prior to agent installation to complete a silent installation. This differs from previous versions and requires updates to existing deployment workflows.

  • Do not edit the configuration profiles before deployment. Changes can break the installation
  • 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, an MDM-managed installation is recommended.

Prerequisites

These items are necessary for the deployment:

➡️ Three mobileconfig profiles: one for the Extension, Proxy, and SSL Certificate

Starting with macOS 15, the Roaming Client cannot automatically install the Root CA certificate needed to display the Block Page on HTTPS sites.

If this profile is not deployed, users will see certificate mismatch errors instead of the Block Page. Filtering will still work.

➡️ The Agent Installer (.pkg) and Site Key from the DNSFilter Roaming Clients dashboard (Install Roaming Client)

➡️ 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 installer package deploys the same way, so after the 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, a warning may display that is 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. This message can be safely ignored; 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: Deploy the DNSFilter_Certificates.mobileconfig profile

Deploy this profile in order to display the Block Page on HTTPS-based websites. The file contains both the whitelabel and standard account certificates. 

  1. Upload DNSFilter_Certificates.mobileconfig to your MDM
  2. Deploy to all target macOS devices
  3. Verify that it is successfully installed before continuing

Step 4: Host the agent installer

Ensure the Agent-2.x.x-Installer.pkg is hosted on a web-accessible location (for example, an MDM CDN or storage bucket). The direct URL is needed in the deployment script.

✍️ If the MDM cannot host the URL, a DNSFilter-hosted 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

✍️ After a new Roaming Client release, the installer file at this URL may take up to 24 hours to reflect the latest version. To download the latest versioned installer immediately, use the link from the DNSFilter dashboard under Deployments > Roaming Clients > Install Roaming Client.

✍️ These URLs always download the latest available installer and are recommended for most deployments. If a device needs to remain on a specific agent version (staged rollouts, change-control freezes), version-pinned installers are available by adding the version to the filename:

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

For example, DNSFilter%20Agent-2.4.5-Installer.pkg. When pinning to a specific version, also turn off auto-updates for those agents. Otherwise, the agent updates itself on the next release cadence regardless of which installer was deployed.

Step 5: Update the deployment script

Use the following script in the MDM, replacing the placeholder values. Add any configuration updates here for bulk implementation. 

  • #!/bin/bash

# -- Configuration --
SITE_SECRET_KEY="your-24-character-site-key"
LOCATION="/tmp"
PKG_NAME="DNSFilter Agent-Installer.pkg"
DOWNLOAD_URL="https://download.dnsfilter.com/User_Agent/MacOS/DNSFilter%20Agent-Installer.pkg"

# -- Download installer --
curl -kL --silent -o "$LOCATION/$PKG_NAME" "$DOWNLOAD_URL" || {
    echo "Download failed."
    exit 1
}

# -- Create dns_agent.conf in the same directory as the pkg --
cat > "$LOCATION/dns_agent.conf" << EOF
SITE_SECRET_KEY=$SITE_SECRET_KEY
OVERRIDE_CONFIG_FILE=yes
EOF

# -- Install --
sudo installer -dumplog -pkg "$LOCATION/$PKG_NAME" -target / || {
    echo "Installation failed."
    rm -f "$LOCATION/$PKG_NAME" "$LOCATION/dns_agent.conf"
    exit 1
}

# -- Clean up --
rm -f "$LOCATION/$PKG_NAME" "$LOCATION/dns_agent.conf"

exit 0
  • #!/bin/bash

# -- Configuration --
SITE_SECRET_KEY="your-24-character-site-key"
LOCATION="/tmp"
PKG_NAME="DNS Agent-Installer.pkg"
DOWNLOAD_URL="https://download.dnsfilter.com/User_Agent/MacOS/DNS%20Agent-Installer.pkg"

# -- Download installer --
curl -kL --silent -o "$LOCATION/$PKG_NAME" "$DOWNLOAD_URL" || {
    echo "Download failed."
    exit 1
}

# -- Create dns_agent.conf in the same directory as the pkg --
cat > "$LOCATION/dns_agent.conf" << EOF
SITE_SECRET_KEY=$SITE_SECRET_KEY
OVERRIDE_CONFIG_FILE=yes
EOF

# -- Install --
sudo installer -dumplog -pkg "$LOCATION/$PKG_NAME" -target / || {
    echo "Installation failed."
    rm -f "$LOCATION/$PKG_NAME" "$LOCATION/dns_agent.conf"
    exit 1
}

# -- Clean up --
rm -f "$LOCATION/$PKG_NAME" "$LOCATION/dns_agent.conf"

exit 0

Step 6: Execute the script via MDM

Deploy the above script using the 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 7: 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 to verify traffic is routed through DNSFilter
    • dig debug.dnsfilter.com txt

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

Troubleshooting 2.x.x installs

FAQ

I have some agents that aren't under an MDM. Do I have to do anything with them for this update?

If auto-updates are enabled, no special action is required, but end-users will receive security prompts to allow the proxy. Notifying end-users in advance is recommended so they know to expect the prompts.

If auto-updates are disabled, install the agent version manually. End-users will still receive update prompts.

The .mobileconfig files are specific to performing a silent installation, which can only happen under MDM solutions.
How can I manage the timing of this update? Turn off auto-updates from the DNSFilter dashboard. From Control Center or through inline edits, toggle off auto-updates for any agents that require manual update control.
One of my end-users denied the installation prompts. Will they lose internet connectivity? How do I fix this?

If there is an existing Roaming Client on the device (for example, v1.8.6), it will continue to filter traffic until v2.x.x is successfully installed.

v2.x.x will appear 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 the list to find the DNSFilter Agent/DNS Agent prompt. 

Under Login Items & Extensions, toggle the DNSFilter Agent/DNS Agent on to allow the extension. 

Restart the device after approving the prompt to complete the update.
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?

After the mobileconfig profiles are deployed, the environment is ready for the production release of the DNSFilter macOS Roaming Client v2.x.x.

No further action is required unless choosing to manually install the agent before auto-update. Devices with auto-update enabled will receive the new agent on the next 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.