In this article

Use this article to understand the three configuration layers available for the macOS Roaming Client and the settings available in each.

Configuration layers

The macOS Roaming Client uses three separate configuration layers. Each layer serves a different purpose, and settings that belong in one layer are silently ignored in another. Admins manage the macOS Roaming Client through their MDM tool in three ways: a configuration profile grants permissions, dns_agent.conf applies product settings at install, and configuration.json updates product settings on a running device.

Apple MDM configuration profiles

The three .mobileconfig profiles DNSFilter distributes carry permissions only. They tell macOS to trust the DNSFilter system extension, allow the DNS proxy, and trust the root CA certificates. They contain no product settings and cannot be used to configure filtering behavior, enable features, or set site keys.

Attempting to add product settings to a .mobileconfig profile produces no error. The settings are silently ignored.

For profile deployment steps, see Install macOS Roaming Client v2.2.0 or higher.

dns_agent.conf

dns_agent.conf is a plain text file placed in the same directory as the installer .pkg before deployment. The installer reads dns_agent.conf once. To change settings after installation, edit configuration.json.

✍️ Some MDM tools copy only the .pkg to a temporary folder. Confirm that your MDM deploys dns_agent.conf alongside the package.

Use dns_agent.conf to pre-configure a fleet consistently at install time without post-install scripts. For the full key reference, see Pre-configure macOS Roaming Client settings before MDM deployment.

configuration.json

configuration.json is the agent's live configuration file on the device. It is written by the installer at install time from dns_agent.conf values and can be edited directly on a running device. Changes take effect within approximately 15 seconds without a restart or reinstall.

File path

The file location differs by agent type.

File structure

configuration.json uses JSON format with the following structure:

{
  "SiteKey": "<your 24-character site key>",
  "Options": {
    "EnableDoHFallback": false,
    "EnableTravelWiFi": false,
    "TravelWiFiDelay": 30,
    "RandomizeLocalServers": true
  },
  "Servers": {
    "Upstream": [
      {
        "Protocols": ["udp", "tcp", "tcp-tls"]
      }
    ],
    "Local": []
  }
}

Options

The following keys are available in the Options object.

Servers

The following keys are available in the Servers object.

Applying changes

Changes to configuration.json take effect within approximately 15 seconds. No restart or reinstall is required. To apply changes immediately, restart the helper using the commands in macOS Roaming Client commands.

To edit configuration.json on a live device via MDM script, use a script that reads the existing file and updates only the keys that need to change, rather than overwriting the entire file. Overwriting the file removes any keys not included in the script.

DNSFilter dashboard

Some settings are configurable from the DNSFilter dashboard and sync to the agent automatically. Dashboard settings apply at the Site level and affect all devices assigned to that Site. Device-level overrides in configuration.json take precedence over dashboard settings for the keys they share.

Related content

• Install macOS Roaming Client v2.2.0 or higher
• Pre-configure macOS Roaming Client settings before MDM deployment
• macOS Roaming Client commands
• Avoid filtering interruptions by encrypting DNS (DoT)
• Airplane and hotel Wi-Fi login page not loading on macOS
• VPN, EDR, and firewall compatibility issues with macOS Roaming Client v2.2.0+