DNS settings declarative configuration for Apple devices
Use the DNS settings configuration to route a device’s DNS queries through an encrypted DNS server using DNS over HTTPS or DNS over TLS. You can specify which domains use the encrypted server and set on-demand rules that adjust behavior based on the network.
The DNS settings configuration supports the following:
Minimum supported operating system versions and channels: iOS 27, iPadOS 27, Shared iPad device, macOS 27 device, visionOS 27.
Requires supervision: No.
Supported enrollment methods: Device Enrollment, Automated Device Enrollment.
DNS settings
Setting | Description | Required | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Visible name | The name of the DNS settings that the operating system displays on the device. | Yes | |||||||||
DNS settings | A dictionary that defines a configuration for an encrypted DNS server. See the DNS settings dictionary. | Yes | |||||||||
On Demand rules | A list of rules that define the DNS settings. If not set, the operating system always applies the DNS settings. These rules are identical to the On Demand rules list in VPN payloads. Each item is described in the On Demand rules settings. | No | |||||||||
Prohibit disablement | If turned on, the operating system prevents users from disabling the DNS settings. | No | |||||||||
DNS settings dictionary
Setting | Description | Required | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
DNS protocol | The encrypted transport protocol (HTTPS or TLS) used to communicate with the DNS server. | Yes | |||||||||
Server URL | The URI template of a DNS-over-HTTPS server, as defined in RFC 8484. This URL needs to use the | Required if the DNS protocol is HTTPS. | |||||||||
Server name | The hostname of a DNS-over-TLS server used to validate the server certificate, as defined in RFC 7858. If no DNS server addresses are provided, the operating system uses the hostname to determine the server addresses. | Required if the DNS protocol is TLS. | |||||||||
DNS server addresses | An unordered list of DNS server IP address strings. These IP addresses can be a mixture of IPv4 and IPv6 addresses. | No | |||||||||
Allow failover | If turned on, the device allows failover to the default system DNS resolver. | No | |||||||||
Certificate identity asset reference | Specifies the identifier of an asset declaration containing an identity that the operating system uses to authenticate the user to the DNS resolver. | No | |||||||||
Supplemental match domains | 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 operating system supports a single wildcard ( | No | |||||||||
On Demand rules settings
Setting | Description | Required |
|---|---|---|
Action parameters | A list of dictionaries that provide per-connection rules. The operating system uses this list only for settings where the On Demand action value is evaluate. Each item specifies a list of domains and domain action. | No |
DNS domain match | A list 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 operating system supports a single wildcard ( | No |
DNS server address match | A list of IP addresses. This rule matches if any of the network’s specified DNS servers match any entry in the list. The operating system supports matching with a single wildcard. For example, | No |
Interface type match | An interface type. If specified, this rule matches only if the primary network interface hardware matches the specified type. | No |
On Demand action | The action (connect, disconnect, evaluate) to take if this dictionary matches the current network. | Yes |
SSID match | A list 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 list, the match fails. Omit this key and the corresponding list to match against any SSID. | No |
URL string probe | A URL to probe. This rule matches if this URL is successfully fetched and returns a 200 HTTP status code without redirection. | No |
Note: Not all configurations and their settings are available in all device management services. Each device management service developer implements these settings differently. To learn which settings are available for your devices, consult your developer’s device management service documentation.