Network relay declarative configuration for Apple devices
Use the Network relay configuration to route a device’s traffic through one or more relay servers using HTTP/3 or HTTP/2. You can specify which domains use the relay, which domains are excluded, and whether DNS failover is allowed.
The Network relay configuration supports the following:
Minimum supported operating system versions and channels: iOS 27, iPadOS 27, Shared iPad device, macOS 27 device, macOS 27 user, visionOS 27.
Requires supervision: No.
Supported enrollment methods: User Enrollment, Device Enrollment, Automated Device Enrollment.
Network relay settings
Setting | Description | Required | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Visible name | The name of the network relays that the operating system displays on the device. | Yes | |||||||||
Relays | A list of dictionaries that describe one or more relay servers that the operating system can chain together. Each item is described in the Relays settings. | Yes | |||||||||
Match domains | A list of domain strings that the operating system uses to determine which connection to route through the servers in Relays. Any connection that matches a domain in the list exactly or is a subdomain of the listed domain uses the relay servers, unless it matches a domain in Excluded domains. If this list and Match FQDNs are empty, the operating system routes traffic to all domains to the relay servers, except those that match an excluded domain or excluded FQDN. | No | |||||||||
Excluded domains | A list of domain strings to exclude from routing through the servers in Relays. Any connection that matches a domain in the list exactly or is a subdomain of the listed domain won’t use the relay server. | No | |||||||||
Match FQDNs | A list of Fully Qualified Domain Names (FQDNs) to route through the servers contained in Relays. Any connection that matches an FQDN in the list exactly uses the relay servers. If this list and Match domains are empty, the operating system routes traffic to all domains to the relay servers, except those that match an excluded domain or excluded FQDN. | No | |||||||||
Excluded FQDNs | A list of Fully Qualified Domain Names (FQDNs) to exclude from routing through the servers contained in Relays. Any connection that matches an FQDN in the list exactly won’t use the relay server. When Match domains is also present, any FQDN listed in the list should be a subdomain of at least one entry, otherwise it won’t have any effect. | No | |||||||||
Relay UUID | A globally unique identifier for this relay configuration. The operating system uses this UUID to route managed apps through the servers in Relays. | Required for User Enrollment | |||||||||
UI toggle enabled | If turned on, the device allows the user to turn off this network relay configuration. | No | |||||||||
Allow DNS failover | If turned on, the device allows the relay to failover to the default system DNS resolver. | No | |||||||||
Relays settings
Setting | Description | Required | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP/3 relay URL | The URL or URI template, as defined in RFC 9298, of a relay server that’s reachable using HTTP/3 and supports proxying TCP and UDP using the CONNECT method. Each relay needs to include either HTTP/2 relay URL or HTTP/3 relay URL, or it can include both. | No | |||||||||
HTTP/2 relay URL | The URL or URI template, as defined in RFC 9298, of a relay server that’s reachable using HTTP/2 and supports proxying TCP and UDP using the CONNECT method. Each relay needs to include either HTTP/2 relay URL or HTTP/3 relay URL, or it can include both. | No | |||||||||
Additional HTTP header fields | A dictionary that contains custom HTTP header keys and values to add to each request. | No | |||||||||
Identity asset reference | The identifier of an asset declaration that contains the identity to use for authentication with the relay. | No | |||||||||
Public keys | A list of references to data assets containing DER-encoded public key data that the operating system uses to authenticate the server during a TLS handshake. If this list is empty, the operating system uses the default TLS trust evaluation. | 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.