In this article

Network administrators use this article to pre-configure the macOS Roaming Client dns_agent.conf settings before deploying through MDM. This applies a consistent configuration to every device at install time, with no manual post-install edits.

Custom values can be added to the MDM deployment script so every device receives the configuration automatically.

Add custom settings to the deployment script

In the MDM deployment script, locate the cat block that writes the temporary config file and add custom settings before deploying:

# Must be named dns_agent.conf, placed in the same directory as the .pkg file.
# Uncomment and populate only the fields you need.
SITE_SECRET_KEY=your-24-character-key
# OVERRIDE_CONFIG_FILE=yes
# LOCAL_DNS_AND_DOMAINS=192.168.1.1:53=corp.example.com
# UPSTREAM_ORDER=udp,tcp,tcp-tls
# IncludeLocalResolversEdnsRecords=false
# ENABLE_TRAVEL_WIFI=true
# TRAVEL_WIFI_DELAY=30
# ENABLE_DOH_FALLBACK=true

Common settings include local domains and resolvers, DoT upstream order, and Travel Wi-Fi mode.

Important notes

• dns_agent.conf uses KEY=value format, one setting per line
• ENABLE_DOH_FALLBACK and other product settings cannot be set through Apple MDM configuration profiles; use dns_agent.conf at install time or configuration.json on a live device
• Do not modify the PKG installer directly; apply all customization through the deployment script
• As of macOS Roaming Client v2.4.6, ALIAS_ADDRESSES and OPERATION_MODE are no longer supported and are silently ignored with no warning or error; remove these keys from any dns_agent.conf carried forward from earlier versions
• If devices are not receiving the expected configuration after deployment:
  • Confirm the correct file path is referenced for the installation type
  • Review the relevant section of the deployment script to verify syntax and formatting

dns_agent.conf field reference

The following fields are confirmed for use in dns_agent.conf:

The two Travel Wi-Fi fields work together: TRAVEL_WIFI_DELAY applies only when ENABLE_TRAVEL_WIFI=true is set, and the bypass window defaults to 30 seconds when the delay is omitted.

Field validation rules

The installer applies these rules when parsing dns_agent.conf:

• All fields accept uppercase or lowercase (for example, SITE_SECRET_KEY or site_secret_key), except IncludeLocalResolversEdnsRecords, which must be written exactly as shown with no lowercase alias
• SITE_SECRET_KEY must be exactly 24 characters; shorter or longer values are dropped during parsing without warning, and the installer then exits with an error on a fresh install
• OVERRIDE_CONFIG_FILE accepts only yes or no; any other value is ignored without warning
• OVERRIDE_CONFIG_FILE=yes requires SITE_SECRET_KEY to also be present; if the key is omitted, the override is ignored and the existing configuration is left in place
• Double quotes around values are removed automatically