3.3 Applying a Snapshot

3 min read

Each snapshot replaces resolvd's scopes whole (PSPU §6.9). Applying one has three parts: the hostname, the scope list, and the cache.

3.3.1 The hostname #

The snapshot's hostname is used when it is not empty. When it is empty, resolvd reads the kernel's hostname at that moment, into a 256-byte buffer; a kernel hostname that is empty or (none) counts as none.
The result is parsed as a domain name. A name that does not parse, or the root, leaves resolvd with no hostname: no synthetic answer is given for it, and status reports an empty hostname.
The kernel's hostname is otherwise read only at startup. A change to it is not seen until the next snapshot with an empty hostname.

3.3.2 The scope list #

Each DnsScope in the snapshot becomes one scope, in snapshot order:

Snapshot field	Becomes
`ifid`	The scope key
`name`	The interface name reported in answers and in `status`
`servers`	Server addresses, in order. Malformed addresses are logged and dropped. Link-local IPv6 addresses use the containing interface; an optional `%name` or `%index` must match it (§4.7). There is no port; servers are asked on port 53.
`domains`	Search domains, in order. A string that does not parse as a name, and the root, are dropped.
`addresses`	`(address, prefix length)` pairs. A string that is not `address/prefix` is dropped.
`default_route`, `exclusive`, `metric`, `level`	Carried as they are
`ntp`	Ignored

The ifid is used as it arrives. netd's interface ids are UUIDs, so none is fallback, the key of the fallback scope (§4.4); a scope that did arrive with that key would share the fallback scope's cache entries, would be asked through the fallback servers, and would lend its interface name to the fallback scope's answers.

3.3.2.1 Every scope is kept #

Dropped entries are dropped silently. Every scope in the snapshot is kept, whatever its level or server count; which of them take part in routing is decided per question (§4.4).

3.3.2.2 The snapshot summary line #

resolvd then logs one line at info level summarising the snapshot:

netd: eth0: 1 server(s), 1 domain(s), default; wg0: 1 server(s), 0 domain(s)

with , default on each scope that claims the default route, or netd: no scopes for an empty snapshot. The counts are of the servers and domains left after parsing.

3.3.3 The cache #

Comparing the new scope list with the old one, by scope key:

a scope whose key is new loses any cached answers under that key;
a scope whose server list differs from before — in content or in order — loses its cached answers;
a scope missing from the new snapshot loses its cached answers;
a change to a scope's domains, addresses, flags, metric or level leaves its cache alone.

Demotion is kept per server address, not per scope, and survives every snapshot (§4.6).

3.3.4 Questions already in flight #

A candidate is routed when it is first asked (§4.4), and its retries stay with the scope key it was routed to. When that scope's servers change, retries use the new list; when the scope has gone, the next retry finds no servers and the question ends unavailable.
A transaction already sent is not cancelled by a snapshot, and its reply is cached under the scope key it was routed to.

Edit this page