In this article

These commands can be useful during troubleshooting issues, scripting, or getting help from our Support team.  

✍️ macOS agents deployed via an MDM tool should be managed through the tool, e.g. start/stop service directives should follow the MDM's guidance. 

If you're here looking for troubleshooting tools, start with the macOS Roaming Client issue diagnostics article to run the Diagnostic Tool. 

Check agent status

Use these commands to check the agent's daemon state, System Extension, and version. Support requests these first when troubleshooting.

Daemon status

• sudo launchctl list com.dnsfilter.agent.macos.helper

• sudo launchctl list io.netalerts.agent.macos.helper

The output is a property list dictionary. Two keys matter:

• PID: a number means the daemon is running; if the key is absent, the daemon is not running
• LastExitStatus: the exit code from the last run; a non-zero value indicates an error worth checking in the logs

System Extension status

systemextensionsctl list

The DNSFilter Agent extension appears under team ID Y532KV8739. The first two columns show state: * means enabled and active, and a blank means it is not.

Running normally:

enabled  active  teamID      bundleID (version)                          name      [state]
*        *       Y532KV8739  com.dnsfilter.agent.macos.DNSProxy (2.4.1)  DNSProxy

Not running:

enabled  active  teamID      bundleID (version)                          name      [state]
                 Y532KV8739  com.dnsfilter.agent.macos.DNSProxy (2.4.1)  DNSProxy  [terminated waiting to uninstall on reboot]

✍️ The extension bundle ID differs for MSP/Whitelabel (DNS Agent) deployments.

✍️ The v2.x agent uses a System Extension and does not bind to port 53, so checking for a port 53 listener does not indicate whether the agent is active. Use the System Extension status above to confirm the agent is running.

Agent version

• /usr/libexec/PlistBuddy -c 'Print CFBundleShortVersionString' /Applications/DNSFilter\ Agent.app/Contents/Info.plist

• /usr/libexec/PlistBuddy -c 'Print CFBundleShortVersionString' /Applications/DNS\ Agent.app/Contents/Info.plist

Start and stop the service

These advanced commands are useful if the agent needs quickly stopped/started instead of rebooting the device. Only use these commands on manually deployed agents: if the agent was deployed via MDM use that tool to stop or start the Roaming Client.

Manually stop Roaming Client

• sudo launchctl bootout system /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist

• sudo launchctl bootout system /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist

Manually start the Roaming Client

• sudo launchctl bootstrap system /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist

• sudo launchctl bootstrap system /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist

Manually stop and disable the Roaming Client

• sudo launchctl bootout system /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist
  sudo launchctl disable system/com.dnsfilter.agent.macos.helper

• sudo launchctl bootout system /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist
  sudo launchctl disable system/io.netalerts.agent.macos.helper

The disable subcommand marks the service as disabled in launchd, which prevents it from starting at boot or being restarted by KeepAlive. The plist file remains on disk, so the agent can be re-enabled without reinstalling.

✍️ The legacy syntax sudo launchctl unload -w /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist is equivalent and still works on current macOS.

Manually re-enable and start the Roaming Client

• sudo launchctl enable system/com.dnsfilter.agent.macos.helper
  sudo launchctl bootstrap system /Library/LaunchDaemons/com.dnsfilter.agent.macos.helper.plist

• sudo launchctl enable system/io.netalerts.agent.macos.helper
  sudo launchctl bootstrap system /Library/LaunchDaemons/io.netalerts.agent.macos.helper.plist