apple_device-management/mdm/profiles/com.apple.relay.managed.yaml

title: Relay
description: The payload that configures relay settings.
payload:
  payloadtype: com.apple.relay.managed
  supportedOS:
    iOS:
      introduced: '17.0'
      multiple: true
      supervised: false
      allowmanualinstall: true
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: false
      userenrollment:
        mode: allowed
    macOS:
      introduced: '14.0'
      multiple: true
      devicechannel: true
      userchannel: true
      supervised: false
      requiresdep: false
      userapprovedmdm: false
      allowmanualinstall: true
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: '17.0'
      multiple: true
      supervised: false
      allowmanualinstall: true
    visionOS:
      introduced: '1.0'
      multiple: true
      supervised: false
      allowmanualinstall: true
      userenrollment:
        mode: allowed
    watchOS:
      introduced: n/a
payloadkeys:
- key: Relays
  title: Relays
  type: <array>
  presence: required
  content: An array of dictionaries that describe one or more relay servers that the
    system can chain together.
  subkeys:
  - key: Relay
    title: Network relay
    type: <dictionary>
    subkeys:
    - key: HTTP3RelayURL
      title: HTTP/3 relay URL
      type: <string>
      presence: optional
      content: |-
        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 `HTTP2RelayURL` or `HTTP3RelayURL`, or it can include both.
    - key: HTTP2RelayURL
      title: HTTP/2 relay URL
      type: <string>
      presence: optional
      content: |-
        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 `HTTP2RelayURL` or `HTTP3RelayURL`, or it can include both.
    - key: AdditionalHTTPHeaderFields
      title: Additional HTTP header fields
      type: <dictionary>
      presence: optional
      content: A dictionary that contains custom HTTP header keys and values to add
        to each request. The dictionary key name represents the HTTP header field
        name to use, and the dictionary value is the string to use as the HTTP header
        field value.
      subkeys:
      - key: ANY
        type: <string>
        presence: required
        content: The HTTP header field value for the corresponding header field name.
    - key: PayloadCertificateUUID
      title: Certificate UUID
      type: <string>
      presence: optional
      format: ^[0-9A-Za-z]{8}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{12}$
      content: The UUID that points to an identity certificate payload, which the
        system uses to authenticate the user to the relay server.
    - key: RawPublicKeys
      title: Raw public keys
      type: <array>
      presence: optional
      content: |-
        An array of DER-encoded raw public keys that the system uses to authenticate the server during a TLS handshake. The server needs to use one of the keys in the handshake to authenticate.

        If this array is empty, the system uses the default TLS trust evaluation.
      subkeys:
      - key: RawPublicKeysElement
        title: Raw public key element
        type: <data>
- key: MatchDomains
  title: Match domains
  type: <array>
  presence: optional
  content: |-
    A list of domain strings that the 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 `ExcludedDomains`.

    If this list and `MatchFQDNs` are empty, the system routes traffic to all domains to the relay servers, except those that match an excluded domain or excluded FQDN.
  subkeys:
  - key: MatchDomainsElement
    title: Match domains element
    type: <string>
- key: ExcludedDomains
  title: Excluded domains
  type: <array>
  presence: optional
  content: 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.
  subkeys:
  - key: ExcludedDomainsElement
    title: Excluded domains element
    type: <string>
- key: MatchFQDNs
  title: Match FQDNs
  supportedOS:
    iOS:
      introduced: '18.4'
    macOS:
      introduced: '15.4'
    tvOS:
      introduced: '18.4'
    visionOS:
      introduced: '2.4'
  type: <array>
  presence: optional
  content: 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 `MatchDomains` are empty, the system
    routes traffic to all domains to the relay servers, except those that match an
    excluded domain or excluded FQDN.
  subkeys:
  - key: MatchFQDNsElement
    title: Match FQDNs element
    type: <string>
- key: ExcludedFQDNs
  title: Excluded FQDNs
  supportedOS:
    iOS:
      introduced: '18.4'
    macOS:
      introduced: '15.4'
    tvOS:
      introduced: '18.4'
    visionOS:
      introduced: '2.4'
  type: <array>
  presence: optional
  content: 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 `MatchDomains` is also present,
    any FQDN listed in the list should be a subdomain of at least one `MatchDomain`
    value, otherwise it won't have any effect.
  subkeys:
  - key: ExcludedFQDNsElement
    title: Excluded FQDNs element
    type: <string>
- key: RelayUUID
  title: Relay UUID
  supportedOS:
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: A globally unique identifier for this relay configuration. The system uses
    this UUID to route managed apps through the servers in `Relays`. This key is required
    for user enrollment.
- key: UIToggleEnabled
  title: UI toggle enabled
  supportedOS:
    iOS:
      introduced: '26.0'
    macOS:
      introduced: '26.0'
    tvOS:
      introduced: '26.0'
    visionOS:
      introduced: '26.0'
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, the device allows the user to disable this network relay configuration.
- key: AllowDNSFailover
  title: Allow DNS failover
  supportedOS:
    iOS:
      introduced: '26.0'
    macOS:
      introduced: '26.0'
    tvOS:
      introduced: '26.0'
    visionOS:
      introduced: '26.0'
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the device allows the relay to failover to the default system
    DNS resolver.