DNS#

Services → DNS, at /dns. It owns the service dns subtree. Four tabs: Resolver, Dynamic DNS, mDNS and CLI. This page documents the Resolver tab; Dynamic DNS and mDNS repeater have pages of their own.

The resolver is the router answering DNS for the hosts behind it: forwarding what it does not know upstream, caching the answers, and serving whatever local names you have given it.

Where the data comes from#

Call	Polled	Returns
`GET /api/dns`	every 15 s	the `service dns` configuration subtree, and `show dns forwarding statistics` parsed into rows
`GET /api/ddns`	every 60 s	the dynamic DNS configuration and status, for the second tab
`GET /api/config/commands?path=service dns`	on load and after each commit	the subtree as commands, for the CLI tab

agent/opmode.go (handleDNS).

The empty state's commands are the minimum:

set service dns forwarding listen-address 10.0.0.1
set service dns forwarding allow-from 10.0.0.0/16
set service dns forwarding name-server 8.8.8.8

The four tiles#

Tile	Value	Sub-line
Cache entries	`Cache entries` from the statistics	`max <Max cache entries>`
Cache size	`Cache size` from the statistics	—
Upstream servers	how many `name-server` entries the configuration declares	the servers, joined
Authoritative records	how many records the page found	—

The first two come from the router's own statistics output and are printed as it printed them, units and all. A dash means the router did not report that row.

The forwarder panel#

Four values, read straight from service dns forwarding:

Field	Node	What it does
Listen address	`listen-address`	the address the resolver answers on. It is a listener, not a filter
Allow from	`allow-from`	the prefixes allowed to query. This is the filter
Cache size	`cache-size`	how many entries the cache holds
Upstream	the keys under `name-server`	where questions go when the cache and the local zones cannot answer

allow-from is read as either a single value or a list, because VyOS renders a multi-valued leaf either way.

There is no editor for any of these four. Changing the listener, the allowed prefixes, the cache size or the upstream servers is a CLI command or a config-tree edit. The only editor on this tab is for records.

Authoritative records#

The bottom panel is every record the router serves itself, flattened out of

service dns forwarding authoritative-domain <zone> records <type> <name> <leaf> <value>

Column	Shows
Name	`<name>.<zone>`, or `<zone> (apex)` when the name is `@`
Type	the record type, upper-cased
Value	the leaf's value
Zone	the authoritative domain it belongs to

An authoritative domain is a zone the router answers for itself instead of forwarding. That is how an internal name resolves to an internal address on the LAN, and it is also how you override a public name for the hosts behind this router.

The record editor#

+ Add record stages exactly one command. The type decides which leaf the value is written to, which is the part that is easy to get wrong at the CLI:

Type	Leaf	Field label	Example value
A	`address`	Address	`10.0.3.1`
AAAA	`address`	Address	`2001:db8::1`
CNAME	`target`	Target	`host.example.com`
TXT	`value`	Value	`v=spf1 -all`
MX	`server`	Mail server	`mail.example.com`
NS	`target`	Target	`ns1.example.com`

set service dns forwarding authoritative-domain lan.example.com records a nas address 10.0.2.10

The Name field defaults to @, the zone apex. Both the zone and the value are required; the type menu offers the six above and nothing else.

There is no editor for an existing record and no delete button on the table. To change a record, stage a set with the new value; to remove one, delete the node from the config tree or the CLI:

delete service dns forwarding authoritative-domain lan.example.com records a nas

An MX record's priority, a record's TTL and an SRV record are not offered by this editor.

The CLI tab#

GET /api/config/commands?path=service dns for the whole subtree — the forwarder, every authoritative zone, and the dynamic DNS configuration, since that lives under service dns dynamic. Below admin, values whose leaf name is a secret are blanked before the response leaves the agent, which covers the dynamic DNS password leaf here — agent/security.go. The GET /api/dns call behind the rest of this page carries no such wrapper; see Dynamic DNS.

What breaks if you get it wrong#

Clients pointed at a resolver that does not listen on that address. Check listen-address against the address the DHCP pool hands out as default-router or name-server — see DHCP.
allow-from narrower than your segments. A new VLAN gets addresses and no name resolution, and it looks like a DHCP fault.
An authoritative zone that swallows a public domain. Described above. The symptom is that one name works and everything else in the domain stops.
A CNAME at the apex. @ with a CNAME is invalid DNS and behaves unpredictably even where it commits.
Cache size raised to something the box cannot hold. The resolver competes with the agent and everything else on the router for memory.

Worked example: a local name for the NAS#

Services → DNS, Resolver tab, + Add record.
Zone lan.example.com, type A, name nas, address 10.0.2.10.

The Commands block shows one line:

set service dns forwarding authoritative-domain lan.example.com records a nas address 10.0.2.10

Stage record, then commit.
The record appears in the table as nas.lan.example.com.
Check it the way a client would, through the router's own resolver: the Diagnostics page's lookup tool runs show host lookup on the router, which is the answer your clients get — see Diagnostics → Tools.

If step 6 returns nothing, the usual cause is that the client is not using this resolver at all. Look at what the DHCP pool hands out.

App integrations#

Installed apps can offer configuration for this page — an ad-filtering or DNS container offering to become the upstream, for instance. Offers appear between the header and the tabs, and only when an app declaring a hint for the dns page is installed. An offer may carry placeholders — the router's own address and its domain among them — which are filled from this router's configuration first; the full list is on Integration offers.