Skip to main content

How can we help you?

Search

help Knowledge Base
forum Community
checklist Release Notes
event Events

Pre-configure macOS Roaming Client settings before MDM deployment

Minetta Gould
  • Updated

    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
# ALLOW_MANUAL_CAPTIVE_PORTAL=true
# CAPTIVE_PORTAL_DELAY=30

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
  • Do not modify the PKG installer directly; apply all customization through the deployment script
  • 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:

Field Required Accepted values What it does
SITE_SECRET_KEY Fresh install only Exactly 24-character string Associates the agent with a DNSFilter Site
OVERRIDE_CONFIG_FILE No yes or no Overwrites the existing configuration.json on reinstall; requires SITE_SECRET_KEY to also be present
LOCAL_DNS_AND_DOMAINS No Semicolon-separated ip:port[,ip:port]=domain[,domain] pairs Split-DNS; routes the named domains to local resolvers
UPSTREAM_ORDER No Comma-separated: udp, tcp, tcp-tls Sets the protocol preference order for upstream DNS queries
IncludeLocalResolversEdnsRecords No true or false Includes EDNS information in requests sent to local resolvers
ALLOW_MANUAL_CAPTIVE_PORTAL No true or false Enables Travel Wi-Fi mode; lets the agent temporarily bypass DNS filtering to complete sign-in on captive portal networks
CAPTIVE_PORTAL_DELAY No Integer (seconds) Length of the Travel Wi-Fi bypass window before filtering resumes; defaults to 30 seconds when omitted, and takes effect only when ALLOW_MANUAL_CAPTIVE_PORTAL=true

The two Travel Wi-Fi fields work together: CAPTIVE_PORTAL_DELAY applies only when ALLOW_MANUAL_CAPTIVE_PORTAL=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
Was this article helpful?
0 out of 0 found this helpful
Return to top

Comments

0 comments

Please sign in to leave a comment.