Feature

DNS Resolver

Built-in DNS resolver component providing cached DNS queries to all Ze components. Uses github.com/miekg/dns (the library CoreDNS is built on).

This is the client side: Ze asking somebody else. Ze also answers queries, from three plugins that share one server harness (internal/core/dnsserver): two authoritative ones, as112 (see AS112 guide for the answer policy the harness enforces) and geodns (per-source-IP answers, service { geodns { ... } }), and the LAN resolver dnsresolver (service { dns-resolver { ... } }), a caching forwarder that answers recursive queries from customer LANs (LAN DNS resolver guide).

The client side shares no configuration and no cache with any of them.

Feature Description
Static name servers system { name-server [8.8.8.8 1.1.1.1]; } sets upstream DNS servers
Router resolver selection One rule picks the router's servers: the configured name-server list when it has an entry, else every learned record (DHCPv4, DHCPv6, PPPoE IPCP, RA RDNSS), and the host's only while none of those lists a server. /etc/resolv.conf
resolv.conf writer Writes the router's servers to resolv-conf-path, and rewrites it whenever a source changes
Learned DNS Under the default list, static servers take priority over the servers a DHCP lease, a PPPoE session or a router advertisement supplied
Query types A, AAAA, TXT, PTR, CNAME, MX, NS, SRV
LRU cache O(1) operations, configurable size and max TTL
TTL-aware Respects response TTL, caps at configured maximum, honors TTL=0 (do not cache)
Concurrent safe Mutex-protected cache, safe for multi-goroutine use
Server failover The internal resolver asks the router's servers in order. A server that gives no answer, or answers SERVFAIL, REFUSED or any RCODE other than NOERROR and NXDOMAIN, passes the query to the next one. When every server fails, the caller gets the last server failure, never an empty success
Fail closed With no server selected, queries fail with no DNS server configured. No public resolver is ever added
Timeout control Per-resolver configurable timeout (1-60 seconds)
Cache management List entries, inspect by name, and clear with clear dns cache all/record/stats: flush everything, delete by name/type, or reset the counters
| resolve pipe Reverse DNS enrichment for IP addresses in any command's JSON output
| origin pipe ASN/network enrichment for IP addresses via Team Cymru DNS queries

Configuration

system {
    name-server [8.8.8.8 1.1.1.1]
    dns {
        resolv-conf-path /tmp/resolv.conf
        timeout 5
        cache-size 10000
        cache-ttl 86400
    }
}
Option Default Description
name-server (none) Static DNS servers: the configured source of the router's list. Under the default list, when set, they are the router's servers: the internal resolver asks them in order, and resolv.conf lists them all.
dns-source source [ configured received ], mode first-usable The ordered sources of the router's servers and how they combine (next section).
resolv-conf-path /tmp/resolv.conf Path for resolv.conf. Default suits gokrazy (read-only rootfs). Empty disables writing. Any other value must be an absolute path in clean form (no .. or repeated /): ze config validate and commit refuse it otherwise, and the refusal names the path to write.
timeout 5 Query timeout in seconds for each server asked (1-60)
cache-size 10000 Maximum cached entries (0 disables caching)
cache-ttl 86400 Maximum cache TTL in seconds (0 uses response TTL only)

Where the router's servers come from

Ze keeps the static name-server list and, apart from it, one record per learned source: one per DHCP client (DHCPv4 or DHCPv6, per interface and unit), one per PPPoE client session (the servers IPCP supplied, RFC 1877, primary first), one per unit that accepts Router Advertisements (the RDNSS servers, RFC 8106), and one for the host's own /etc/resolv.conf. A record carries how long it stays valid: a DHCPv4 lease until the lease expires (until withdrawn for an infinite lease), a DHCPv6 Reply until the valid lifetime of its last binding runs out, an RA record until its last server's Lifetime runs out (a pppoe-client's until its session ends, if that comes first), an IPCP lease and the host's file until withdrawn. When a record's validity ends, Ze withdraws it at that moment, whether or not its client said so.

An RA record exists only for a unit whose ipv6 accept-ra is set above 0, or for an enabled pppoe-client whose ipv6 accept-ra is set above 0: the RAs of that client's WAN session arrive on its session device, which carries the client's name, and the record is named after the client. The kernel processes the RA, and only when its accept_ra lets it; it then hands the RDNSS option to Ze. Ze checks the option as RFC 8106 Section 5.3.1 says (a Length of at least 3 and odd, unicast addresses) and discards an invalid one with a warning naming the interface and the Length. Each server lives for the option's Lifetime from receipt, a later RA with the same server moves its expiry, Lifetime 0 removes it at once, and a new server is listed first (RFC 8106 Section 6.2). One unit keeps at most 8 RA servers; past that, the one that expires first is dropped. A unit that loses its accept-ra, or is removed, has its RA record withdrawn on that commit, and so does a pppoe-client. A pppoe-client's RA record is also withdrawn when its session ends, together with its IPCP lease, whatever Lifetime its servers had left: they were reached over the session device, which ends with the session, and the next session's RAs build a fresh record. An interface unit's RA record is not tied to its device that way: it stays until its Lifetime runs out, a Lifetime 0 arrives, or a commit removes the unit.

On every change, one rule selects the router's servers from them, walking the list system dns-source names. Two classes of source can be named there: configured (the name-server list) and received (every learned record, DHCPv4 first, then DHCPv6, then PPPoE, then RA RDNSS, each by interface then unit, in the order each source sent them). The host's file is a fallback inside received: its servers are listed only while no other learned record lists a server. The mode says how two classes combine:

mode The router's servers
first-usable the first class in the list that holds a usable server, alone; a later class is a backup, used only while the earlier ones hold none
merge every class, in list order, a server already listed not repeated; Ze's internal resolver tries a later server when an earlier one does not answer or answers a server failure

With no dns-source written, the default is source [ configured received ] with mode first-usable. That is what Ze always did:

Situation, under the default The router's servers
name-server configured the static servers alone; a learned server never overrides them (RFC 3646 Section 6)
✕ every learned record's servers, in the received order above
a renewal reply omits the DNS option, or a lease ends or expires that lease's servers leave the selection; the other sources' stay (RFC 9915 Section 18.2.10.5 for DHCPv6)
every source withdrawn ✕

Two examples. To keep your own resolvers and fall back to the ISP's only when none is configured, write nothing: that is the default. To prefer the ISP's and keep your own as a backup asked after them:

system {
    name-server [ 198.51.100.53 ]
    dns-source {
        source [ received configured ]
        mode merge
    }
}

received-interface [ eth1 ] narrows received to the leases learned on the named interfaces, in the order listed, then by origin, then by unit. An interface that holds no lease yet is accepted, because it may learn one later.

Ze refuses, at ze config validate, at commit, at boot and at reload:

Written Refusal
two sources and no mode system dns-source names 2 sources (configured, received) and no mode: Ze cannot tell whether a later source is a backup or an addition. Set mode first-usable or mode merge
received-interface without received in source the filter would select nothing. Add source received, or delete received-interface
source self Ze cannot be its own upstream. Name upstream servers with name-server, or use source received
source radius RADIUS resolvers belong to one PPP subscriber, not the router
a dns-source container with no source an empty list offers no resolver. Name a source, or delete dns-source to take the default
one class twice in source its second place can never contribute a server. Delete the repeat
a source or mode word Ze does not know Ze cannot tell what the word selects. Use a class from the list below, and first-usable or merge

A list naming one source needs no mode, because both modes give it the same answer.

An address that cannot name a resolver (the unspecified address, a multicast address, 255.255.255.255) is skipped, whatever its source. A loopback address such as the 127.0.0.53 of a host stub resolver stays, because Ze's own lookups can reach it.

The host's /etc/resolv.conf keeps a Ze on a standard distribution resolving when no name-server is configured and no lease supplies one. It stands in for a lease and never joins one: while a DHCPv4, DHCPv6, PPPoE or RA record lists a server, the host's servers are left out, so a container's resolver (Docker's 127.0.0.11) is never written beside the servers IPCP supplied. When the last such record expires or is withdrawn, the host's servers return. Ze reads it at startup and on every config reload, not when the file changes. Ze never reads it when it is the same file as resolv-conf-path (symlinks are followed), because Ze would then read back the servers it wrote.

The selection is the one source of truth for every reader:

Reader What it does with the selection
Ze's internal resolver Asks every selected server in order, and follows the selection on each lease change and reload
resolv-conf-path Lists every selected server
A plugin, in process or external Subscribes to the system-dns event namespace ("The system-dns namespace"). docs/architecture/api/process-protocol.md

The local commands ze resolve dns and ze resolve cymru run without a daemon, so they cannot see a lease. They ask the server that --server (--dns-server for cymru) names, else the servers of the host's /etc/resolv.conf, else they fail closed.

The dns-source list and the learned record

dns-source is one YANG grouping, declared in ze-types, so every consumer that hands resolver addresses on writes the same list. The router's system dns-source, the LAN resolver's upstreams (service dns-resolver forward dns-source), a DHCP subnet's option 6 (service dhcp-server shared-network subnet dns-source) and a unit's RA RDNSS (interface ... unit ... ipv6 router-advertisement rdnss dns-source) and a subscriber pool's IPCP DNS (l2tp pool ipv4 dns-source, l2tp pool named-pool dns-source) use it.

Leaf Shape
source the classes, in the order the consumer falls through them, each class at most once
mode first-usable or merge, with no default. A list of two or more classes needs one
received-interface interface names, in order. It narrows received and nothing else
Class What it lists
received every unexpired learned record, by origin rank, then interface, then unit
configured the consumer's own static list: for the router, system name-server
self Ze's own address on the interface the client is on
radius the resolvers RADIUS gives one PPP subscriber: the Access-Accept's MS-Primary-DNS-Server and MS-Secondary-DNS-Server (RFC 2548), allowed only in a pool's list

A class names a role, never a protocol. A protocol that learns resolvers registers an origin with a rank, and its records appear inside received. Each consumer declares the classes it cannot use, with the reason and the fix it prints: the router refuses self and radius. A refusal of a list that sits under a keyed node names that instance, its keys filled in, so its fix command runs as printed: delete interface ethernet eth0 unit 0 ipv6 router-advertisement rdnss dns-source source radius, service dhcp-server shared-network LAN subnet 192.168.1.0/24 dns-source, l2tp pool named-pool gold dns-source. A consumer's built-in default applies only while its dns-source container is absent. Once the container is written, the default no longer applies, its mode included.

Each consumer also states who receives its servers. The router and the LAN resolver's upstreams serve Ze itself, so a loopback server such as 127.0.0.53 or an IPv6 link-local server is usable there. DHCPv4 option 6, RA RDNSS and a subscriber's IPCP hand addresses to another host, so the selection drops a loopback address (127.0.0.0/8, ::1) and an IPv6 link-local address with no zone from them, logs each drop with the consumer's path, and falls through to the next entry or class. IPv4 link-local (169.254.0.0/16) is kept: a server there on the client's own link is reachable from it.

A consumer plugin, in the engine process or its own, subscribes to the system-dns snapshot, asks for a replay once it has started, and keeps the newest snapshot's records with dnssource.Follower, which drops a snapshot older than the last it kept. A plugin process receives the JSON form and hands it to Accept. A component in the daemon (the interface component, for RDNSS) subscribes to the typed handle dnssource.SnapshotEvent, hands the value to AcceptSnapshot, and emits dnssource.SnapshotRequest after it subscribes. A plugin that receives a snapshot it cannot decode keeps its previous learned resolvers, logs the cause at WARN, counts it in ze_dns_source_snapshots_rejected_total{consumer}, and applies the next snapshot, including one delivered in the same batch. A plugin that answers clients (the LAN resolver, the DHCP server) holds each answer until it applied the replay, for 2 seconds at most (ExpectReplay, Replayed, AwaitReplay), so none is built from the empty record set it starts with.

Each consumer also publishes what its lists chose, so show system dns and show doctor (the daemon form of ze doctor) can read every consumer from the daemon. A consumer emits (system-dns, selection) carrying a dnssource.Publication: its plugin name and one ConsumerSelection per list (the config path, the instance it belongs to, such as the subnet, the unit or the pool, the sources and mode, default while the built-in default applies, the classes used, the servers, self, the servers the self class contributed, and for the LAN resolver serves, the listener addresses whose UDP socket is bound now: a configured listener that is not bound is not listed, so ze doctor warns about a self address nothing answers on). It publishes its whole set after it starts and whenever a selection changes, because the registry replaces the consumer's previous set with each publication: a list the operator removed leaves by being absent. The registry keys the sets by the consumer's name and names no consumer itself. The router's own selection stays in the snapshot.

Consumer Instance Published when
dns-resolver none (one forward list) a policy build, after start, and each listener bind or unbind; a disabled resolver publishes an empty set
dhcpserver the subnet prefix each config install and each fresh snapshot; self is the listened device's address inside the subnet
interface <interface> unit <unit> each RA reconcile; the servers are the ones the RDNSS option carries
l2tp-pool none for the default pool, the name for a named pool joining the bus, each pool install and each fresh snapshot

RADIUS names a subscriber's servers when the session asks, so the pool's published selection is what a session whose RADIUS reply carries no MS DNS server is offered: the radius class contributes nothing to it.

show system dns answers records (every learned record) and consumers: the router first, under the consumer name system, then every consumer that has published, sorted by name. A consumer that has not published yet is absent: its plugin is not running or has not received its first snapshot. A plugin the engine removes while the daemon runs sends a withdrawal (dnssource.NewWithdrawal) from its bye handler, and the registry then forgets it, so its last selection is not reported after it stopped.

The registry exports ze_dns_source_records{origin}, the learned records each origin holds (zero once its leases are withdrawn), and ze_dns_source_selection_changes_total{consumer}, one per change of a consumer's published selection after its first, the router's under system. A repeated publication of the same answer is not a change.

show doctor warns, for the router and every published list, when a list that names received selected no server (doctor-dns-source-empty), when a received-interface entry names an interface that holds no learned record (doctor-dns-source-interface-silent), and when a self server is an address no service dns-resolver listener answers on (doctor-dns-source-self-unserved). Each message names the list's path and instance, and the fix line names the command to run: show system dns for an empty or silent list, set service dns-resolver listener <name> ip <address> for an unserved self address. The local ze doctor process does not run these checks, because the registry they read is filled only in the daemon: it asks the running daemon's show doctor for them, and says so with a doctor-runtime-not-checked warning when no daemon answers.

Origin Rank Learned from
dhcpv4 100 DHCPv4 option 6
dhcpv6 200 DHCPv6 DNS Recursive Name Server option
ppp 300 IPCP on a PPPoE client session (RFC 1877)
ra 400 Router Advertisement RDNSS (RFC 8106)
host 500 the host's, registered as a fallback. /etc/resolv.conf

A lower rank lists first. A fallback origin's records are listed only while no other record lists an address.

Each learned record holds its origin and rank, the interface and unit that learned it (both empty for the host's file), the addresses in the order the source sent them, when it was received and when it expires. A record with no expiry is valid until its source withdraws it. The record also reserves priority, name, transport, port and path for RFC 9463 encrypted resolver discovery (DNR), which Ze does not implement yet. A record that names a transport is not plain DNS on port 53, so received skips it. The JSON form of a record is in docs/architecture/api/process-protocol.md, "The system-dns namespace".

Cache management

The DNS cache can be inspected and managed at runtime via CLI commands.

Inspection:

show dns cache stats                            # Hit/miss/eviction counters + rates
show dns cache list                             # All non-expired entries (sorted by TTL)
show dns cache record example.com               # Entries for a specific name

Clearing:

clear dns cache all                             # Flush all entries and reset counters (bare `clear dns cache` is refused)
clear dns cache stats                           # Zero counters without removing entries
clear dns cache record example.com              # Delete entries for a name (all types)
clear dns cache record example.com type AAAA    # Delete a single name+type entry

Pipe operators

Two pipe operators enrich JSON output from any command with DNS-based lookups:

Pipe Description
| resolve Adds a <key>-name field with the PTR (reverse DNS) hostname for each IP address value in the JSON output. Uses the system DNS resolver with cache. 500ms timeout per lookup.
| origin Adds <key>-asn, <key>-as-name, and <key>-prefix fields for each IP address value via Team Cymru DNS queries. 2s timeout.

Both pipes walk JSON values, detect IP addresses, and add sibling fields. They work on any command output, including show traceroute, show bgp, etc. In monitor traceroute | log mode, they enrich the hop legend.

Reload behavior

A reload that changes name-server or dns-source reaches the internal resolver and resolv.conf at once: the reload re-runs the selection with the new list, and under the default list removing every static server hands both back to the learned records. A reload whose dns-source Ze refuses is refused whole, and the running list stays. The dns settings (timeout, cache-size, cache-ttl) are applied at startup, and a change to them needs a process restart.