Skip to main content

Deploying SafeDNS Endpoint Lite for macOS via MDM

System requirements: macOS Tahoe 26 or later, Mac with Apple silicon — M1 chip or later.
The Agent is available on the following billing plans: Safe Family, Pro, Pro Plus, and archived Safe@Home, Safe@Office.

This guide explains how to deploy SafeDNS Endpoint Lite for macOS to multiple macOS devices using an MDM solution.

The deployment consists of three components:

The order in which these three components are assigned does not matter, but we recommend deploying the config.plist and the configuration profile first. The package has a built-in safeguard (config gate): if it reaches a device before the script that creates config.plist, it waits up to 5 minutes for config.plist to appear, and only then installs the daemon, registers the device, and deploys the host.

1. Installing the agent

Before deploying the agent at scale, complete the preparation steps below.
  • Ask SafeDNS technical support (support@safedns.com) to enable the required features for your account.
  • Obtain your Base64-encoded AuthKey from SafeDNS.

After these steps are complete, assign the three objects below to a device group in your MDM solution. They can be assigned in any order.

Step 1. Merged configuration profile

Upload and assign one profile. It contains two payloads:

  • System Extension approval (com.apple.system-extension-policy) — silently approves the SafeDNS system extension.
  • DNS Proxy (com.apple.dnsProxy.managed) — activates the DNS proxy without prompting the user.

File: ⤵SafeDNS_merged_profile.mobileconfig. Upload it as a Custom Configuration Profile (device profile).

Step 2. config.plist (the AuthKey needs to be added by the administrator)

Upload and assign the configuration script according to these instructions.

You enter the key into the script yourself. This is a security requirement: the key is never embedded in the installer package.

AUTH_KEY="Enter here your authKey "   # ← enter your Base64-encoded AuthKey here

The script creates the /Library/Application Support/SafeDNS/config.plist file with the AuthKeyBase64 key.

Step 3. Single installer package (daemon + host + filtering module)

Upload the SafeDNS Endpoint Lite_1.8.0.0_2026-09-15_1215.pkg file to the Apps catalog of your MDM solution and assign it to the same device group.

The package performs the following steps automatically and in the correct order:

  1. The daemon is installed and started, and it registers the device in the SafeDNS Dashboard.
  2. The registration is verified (dnsToken). The host is deployed only after successful registration.
  3. The host with the filtering module is moved to /Applications, and the system extension is activated silently (using the profile from Step 1).

To verify the installation, run the following commands on a target device:

# The SafeDNS extension must be listed as [activated enabled]
systemextensionsctl list

# Prints the dnsToken if the device is registered
/usr/libexec/PlistBuddy -c "Print :dnsToken" "/Library/Application Support/SafeDNS/state.plist"

The agent runs in the background and has no user interface.

2. Uninstalling the agent

To remove SafeDNS Endpoint Lite from target devices:
  1. Add the SafeDNS_Uninstaller.sh script to Scripts in SimpleMDM according to the Running the SafeDNS Uninstaller script guide.
  2. Deploy the uninstaller script to the target devices.
  3. Remove the SafeDNS configuration profile, the SafeDNS Endpoint Lite agent and SafeDNSDaemon daemon from the target devices in your MDM console.
  4. After the uninstaller script runs, each target device restarts automatically after 3 minutes.

IMPORTANT! After the agent and the daemon are removed, each target device must be RESTARTED. The restart happens automatically 3 minutes after the uninstaller script runs. The agent runs as a system extension. After removal, its records remain in the system extension registry until the device is restarted. Without a restart, reinstalling the agent on the same device may cause errors.

3. Choosing the DNS transport protocol

The administrator sets the DNS transport mode using the Switch_mode.sh script, which must be deployed to the target devices in advance.

Available modes:

  • UDP — DNS over UDP (port 1253)
  • DoH — DNS over HTTPS (port 443)
  • DoT — DNS over TLS (port 853)

4. Preventing DoH bypass in browsers

Advanced users may try to bypass system DNS filtering by configuring a custom DNS-over-HTTPS (DoH) resolver in Chromium-based browsers. The SafeDNS agent works with system DNS, so additional protection is required to reduce this risk.

SafeDNS provides two layers of protection against this scenario:

1. Browser DNS policy configuration profile

Download and deploy this custom configuration profile: ⤵safedns_browser_dns_policy.mobileconfig

This profile is deployed in the same way as the merged configuration profile from Step 1.

The profile restricts access to DNS-related settings in major browsers. However, it does not cover all browsers: Firefox is not included.

2. Built-in DoH bypass detection

The SafeDNS filtering module includes a mechanism that detects attempts to bypass filtering through third-party DoH services and blocks those connections. It blocks the bootstrap domains of public DoH providers (Cloudflare, Google, Quad9, and others).

If an advanced user manually configures a self-hosted DoH resolver or another non-standard custom DoH solution in the browser, DNS filtering may not work as expected.

5. VPN limitation — important notice

IMPORTANT: A VPN that resolves DNS remotely bypasses the agent's filtering.

The agent filters traffic at the DNS resolver level: it intercepts queries sent to the system DNS. A VPN that resolves domain names on its own server (remote DNS) takes those queries out of the agent's sight, so filtering does not work for that traffic.

This is not a defect of the agent. It is a fundamental limitation of DNS-level filtering on macOS, and every product that filters at the DNS level behaves the same way (e.g. DNSFilter, NextDNS, Cisco Umbrella).

Examples of VPNs with remote DNS:

  • Browser VPN extensions (HTTP/SOCKS proxies): SandVPN, Browsec, Hola, Urban VPN, Touch VPN, ZenMate, and similar.
  • VPN clients (DNS leak protection is enabled by default): NordVPN, ExpressVPN, Surfshark, Proton VPN, Private Internet Access, IPVanish, CyberGhost, Mullvad, IVPN, Windscribe, and similar.
  • WireGuard / OpenVPN — if the tunnel configuration overrides the DNS server with the VPN server (standard for commercial providers).
Ways to address this limitation
Option What it does Best for
Split-tunnel VPN (recommended) The VPN tunnels only corporate routes. All other traffic, including DNS, goes through the system resolver, so filtering works. Customers who need a VPN to access internal resources
Blocking the Proxies & Anonymizers category The DNS filter blocks the domains of VPN providers, so the VPN client cannot connect. Customers who do not need a VPN for work
Allowlist The domain of the legitimate corporate VPN is added to the SafeDNS Allowlist. It resolves, while everything else stays blocked. Used together with blocking the Proxies & Anonymizers category
Blocking VPNs at the MDM level An MDM policy prevents users from installing or running VPN clients and browser extensions. Corporate devices with a strict policy

Full control of traffic inside a VPN (inspection of encrypted tunnels) belongs to the SIG/NGFW class of products (e.g. Cisco Umbrella SIG, Zscaler) and is outside the scope of DNS filtering.

6. Collecting diagnostic logs

To collect diagnostic logs on a target device, use the SafeDNS EL_get_logs.sh script. Like Switch_mode.sh, it must be deployed to the target devices (Scripts in SimpleMDM).

  1. Add the SafeDNS EL_get_logs.sh script to Scripts in SimpleMDM.
  2. Deploy it to the target devices (the same device group).

The script collects:

  • the unified log for the last 24 hours for the DNS Proxy (com.safedns.agent.SafeDNSMacProxy) and daemon (com.safedns.agent.SafeDNSDaemon) subsystems;
  • the rotated App Group bridge logs (safedns-unified.log*);
  • the system files /var/log/safedns-*.log and /Library/Logs/SafeDNS;
  • a snapshot of config.plist and the output of systemextensionsctl list.

The result is an archive on the Desktop of the target user: safedns-all-logs-<YYYYMMDD-HHMMSS>.tar.gz. The log of the collection process itself is saved to /var/log/safedns-mdm-collect-logs.log.

The collection window is the 24 hours before the script runs. For example, you can connect the device to the problematic network in the evening and collect the logs the next morning.

7. Testing the filtering

When you check filtering on a target device, test category blocking with VPN turned off: a browser VPN proxy resolves DNS on its own server, so the agent does not see those queries.

Control check:

dig +short example.com @127.0.0.1                         # allowed domain: returns an IP address
dig +short <domain-from-a-blocked-category> @127.0.0.1    # blocked domain: NXDOMAIN / 0.0.0.0
Back to top