The payload that configures encrypted DNS settings.
| Setting | Type | Required | Default | Manual Install | Supported OS |
|---|---|---|---|---|---|
DNS Settings DNSSettings A dictionary that defines a configuration for an encrypted DNS server. 7 subkeys | dictionary | required | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ DNS Protocol DNSProtocol The encrypted transport protocol used to communicate with the DNS server. | string | required | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ Server URL ServerURL The URI template of a DNS-over-HTTPS server, as defined in RFC 8484. This URL needs to use the `https://` scheme, and the system uses the hostname or address in the URL to validate the server certificate. If no `ServerAddresses` are provided, the system uses the hostname or address in the URL to determine the server addresses. Required if `DNSProtocol` is `HTTPS`. | string | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ Server Name ServerName The hostname of a DNS-over-TLS server used to validate the server certificate, as defined in RFC 7858. If no `ServerAddresses` are provided, the system uses the hostname to determine the server addresses. This key must be present only if the DNSProtocol is `TLS`. | string | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ DNS Server Addresses ServerAddresses An unordered list of DNS server IP address strings. These IP addresses can be a mixture of IPv4 and IPv6 addresses. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ Server Address Element ServerAddressesElement | string | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | |
└─ Allow Failover AllowFailover If `true`, the device allows failover to the default system DNS resolver. | boolean | optional | false | ✓Yes | iOS (26.0+)macOS (26.0+)visionOS (26.0+) |
└─ Certificate UUID PayloadCertificateUUID The UUID that points to an identity certificate payload. The system uses this identity to authenticate the user to the DNS resolver. | string | optional | — | ✓Yes | iOS (16.0+)macOS (13.0+) |
└─ Supplemental Match Domains SupplementalMatchDomains A list of domain strings used to determine which DNS queries use the DNS server. If not set, all domains use the DNS server.
The system supports a single wildcard (`*`) prefix, but it's not required. For example, both `*.example.com` and `example.com` match against `mydomain.example.com` and `your.domain.example.com`, but don't match against `mydomain-example.com`. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ Supplemental Match Domains Element SupplementalMatchDomainsElement | string | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | |
On Demand Rules OnDemandRules An array of rules that define the DNS settings. If not set, the system always applies the DNS settings. These rules are identical to the `OnDemandRules` array in VPN payloads. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ On Demand Rules Element OnDemandRulesElement 7 subkeys | dictionary | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | |
└─ └─ On Demand Action Action The action to take if this dictionary matches the current network. Allowed values:
- `Connect`: Apply DNS Settings when the dictionary matches.
- `Disconnect`: Don't apply DNS Settings when the dictionary matches.
- `EvaluateConnection`: Apply DNS Settings with per-domain exceptions when the dictionary matches. | string | required | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ Action Parameters ActionParameters An array of dictionaries that provide per-connection rules. The system uses this array only for settings where the `Action` value is `EvaluateConnection`. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ └─ Action Parameter ActionParameter A dictionary that provides per-connection rules.
The keys allowed in each dictionary are described below. Note: This array is only for dictionaries in which `EvaluateConnection` is the `Action` value. 2 subkeys | dictionary | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ └─ └─ [Structure continues recursively] ↻ This structure continues with 2 subkeys (deeply nested - 2 subkeys). See Apple's documentation for the complete structure. | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | ||
└─ └─ DNS Domain Match DNSDomainMatch An array of domain names. This rule matches if any of the domain names in the specified list matches any domain in the device's search domains list.
The system supports a single wildcard (`*`) prefix, but it's not required. For example, both `*.example.com` and `example.com` match against `mydomain.example.com` and `your.domain.example.com`, but don't match against `mydomain-example.com`. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ └─ DNS Domain Match Element DNSDomainMatchElement | string | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | |
└─ └─ DNS Server Address Match DNSServerAddressMatch An array of IP addresses. This rule matches if any of the network's specified DNS servers match any entry in the array.
The system supports matching with a single wildcard. For example, `17.*` matches any DNS server in the 17.0.0.0/8 subnet. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ └─ DNS Server Address Match Element DNSServerAddressMatchElement | string | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | |
└─ └─ Interface Type Match InterfaceTypeMatch An interface type. If specified, this rule matches only if the primary network interface hardware matches the specified type. | string | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ SSID Match SSIDMatch An array of SSIDs to match against the current network. If the network isn't a Wi-Fi network or if the SSID doesn't appear in this array, the match fails. Omit this key and the corresponding array to match against any SSID. 1 subkey | array | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
└─ └─ └─ SSID Match Element SSIDMatchElement | string | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) | |
└─ └─ URL String Probe URLStringProbe A URL to probe. This rule matches if this URL is successfully fetched and returns a 200 HTTP status code without redirection. | string | optional | — | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
Prohibit Disablement ProhibitDisablement If `true`, the system prohibits users from disabling DNS settings. This key is only available on supervised devices. | boolean | optional | false | ✓Yes | iOS (14.0+)macOS (11.0+)visionOS (1.0+) |
