What's the grammar of the Dynamic Store's DNS config?

Question

This helpful answer talks about how using the dynamic store is preferred over the bsd-style /etc/resolver/* files, and includes a helpful example. I did find some docs that mention the same dns properties, but it does leave some questions. Is this doc relevant to the dynamic store? Why does it only talk about these properties being valid when configuring a IKEv2 VPN? In this specific example, how does the wildcard work?

Here, a wildcard is given to both ServerAddresses and SupplementalMatchDomains. How does this work?

sudo scutil
d.init
d.add ServerAddresses * 9.9.9.9
d.add SupplementalMatchDomains * stackexchange.com
set State:/Network/Service/whatever-you-want-as-long-as-unique/DNS

Apple says about ServerAddresses:

An array of DNS server IP address strings. These IP addresses can be a mixture of IPv4 and IPv6 addresses.

Apple says about SupplementalMatchDomains:

A list of domain strings used to determine which DNS queries will use the DNS resolver settings contained in ServerAddresses. This key is used to create a split DNS configuration where only hosts in certain domains are resolved using the tunnelʼs DNS resolver. Hosts not in one of the domains in this list are resolved using the systemʼs default resolver. If SupplementalMatchDomains contains the empty string it becomes the default domain. This is how a split-tunnel configuration can direct all DNS queries first to the VPN DNS servers before the primary DNS servers. If the VPN tunnel becomes the networkʼs default route, the servers listed in ServerAddresses become the default resolver and the SupplementalMatchDomains list is ignored.

Answer 1

Is this doc relevant to the dynamic store?

Not directly but Apple uses the same options throughout the entire system and wherever they are used, they also have the same meaning.

The Dynamic Store is where certain dynamic aspects of the current system configuration is stored, which mainly the network configuration (including active VPN configuration), the machine name and some power saving settings. The sc in scutil stands for System Configuration.

Configuration Profiles are used to provide Macs/iPhones with a predefined configuration setup, e.g. if a company wants to roll out thousand devices to employees, that all shall use the same base configuration, then you put that configuration into a profile and upload that profile to each of these devices. And one thing you may want to configure in such a profile is a VPN setup, so these devices have access to some internal company LAN via VPN and to describe that configuration, the same keys are used as in the Dynamic Store.

Why does it only talk about these properties being valid when configuring a IKEv2 VPN?

You typically don't roll out a static network configuration via profile, you'd rather setup a DHCP server and provide network configuration based on the device's hardware (MAC) address.

However, the PDF you've linked is from 2019. If I check the current online references for device profiles, it does mention those keys also for the case you want to push a static DNS configuration to devices:

https://developer.apple.com/documentation/devicemanagement/dnssettings/dnssettings

BTW, the documentation of the System Configuration framework itself can be found here:

https://developer.apple.com/documentation/systemconfiguration

It also does list all the existing keys, e.g. here are all the DNS related keys:

https://developer.apple.com/documentation/systemconfiguration/scschemadefinitions/dns_entity_keys

But it does not really provide any explanation since that documentation is intended for developers that should know what these keys mean (and if they don't, they should not touch them).

In this specific example, how does the wildcard work?

The commands mean:

d.init

Initialize a new dictionary (a key/value data structure, where values are referenced by a key; some programming languages would also call that a hash or a associative array)

d.add ServerAddresses * 9.9.9.9

Add a new entry to the dictionary named ServerAddresses of type array (*) with a value of 9.9.9.9

d.add SupplementalMatchDomains * stackexchange.com

Add a new entry to the dictionary named SupplementalMatchDomains of type array (*) with a value of stackexchange.com

set State:/Network/Service/whatever-you-want-as-long-as-unique/DNS

Save the current dictionary to the Dynamic Store under the key
State:/Network/Service/whatever-you-want-as-long-as-unique/DNS

For more details, see echo help | scutil:

 d.add key [*#?%] val [v2 ...]  : add information to dictionary
       (*=array, #=number, ?=boolean, %=hex data)

d.add KEY VALUE would also create a dictionary entry named KEY with a value VALUE but that value would be of type string. By adding *, #, ? or % you can change the value type accordingly.

Compare:

> d.init
> d.add someKey someValue
> d.show
<dictionary> {
  someKey : someValue
}

with:

> d.init
> d.add someKey * someValue
> d.show
<dictionary> {
  someKey : <array> {
    0 : someValue
  }
}
>