docs: Update DNS forwarding page to VyOS 1.5 standards (#2163)

* docs: Update DNS forwarding page to VyOS 1.5 standards

* Update dns.md

* Update dns.md

1 files changed, 819 insertions, 313 deletions

diff --git a/docs/configuration/service/dns.md b/docs/configuration/service/dns.md
index e7e9b457..8e98a43a 100644
--- a/docs/configuration/service/dns.md
+++ b/docs/configuration/service/dns.md
@@ -1,582 +1,1088 @@
+---
+myst:
+  html_meta:
+    description: |
+      DNS forwarding is a VyOS service that resolves DNS queries for
+      connected clients by forwarding to configurable upstream servers
+      or by operating as a full recursive resolver.
+    keywords: dns, dns forwarding, recursive dns, authoritative dns, dnssec
+---
+
 (dns-forwarding)=
 
-# DNS Forwarding
+# DNS forwarding
+
+VyOS provides DNS infrastructure for small networks, designed to be
+lightweight and suitable for resource-constrained routers and
+firewalls.
+
+Connected clients are served through the DNS forwarding service,
+configured under `service dns forwarding`. It can either forward
+queries to configurable upstream DNS servers or operate as a full
+recursive DNS server without requiring upstream DNS servers. Operating
+without upstream servers avoids exposing client queries to an upstream
+DNS operator.
 
 ## Configuration
 
-VyOS provides DNS infrastructure for small networks. It is designed to be
-lightweight and have a small footprint, suitable for resource constrained
-routers and firewalls. For this we utilize PowerDNS recursor.
+```{note}
+A DNS forwarding configuration is committable only when both
+`listen-address` and `allow-from` are set. Otherwise, the commit
+fails.
+```
 
-The VyOS DNS forwarder does not require an upstream DNS server. It can serve as
-a full recursive DNS server - but it can also forward queries to configurable
-upstream DNS servers. By not configuring any upstream DNS servers you also
-avoid being tracked by the provider of your upstream DNS server.
+### Listener
 
-```{cfgcmd} set service dns forwarding system
+```{cfgcmd} set service dns forwarding listen-address \<address\>
 
-   Forward incoming DNS queries to the DNS servers configured under the ``system
-   name-server`` nodes.
+**Configure a local IPv4 or IPv6 address on which DNS forwarding
+listens for incoming queries.**
+
+The address must already be assigned to a local interface. Repeat the
+command to configure multiple listen addresses. At least one
+listen-address is required for a successful commit.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding dhcp \<interface\>
+```none
+set service dns forwarding listen-address 192.0.2.1
+set service dns forwarding listen-address 2001:db8::1
+```
+
+```{cfgcmd} set service dns forwarding port \<1-65535\>
 
-Interfaces whose DHCP client nameservers to forward requests to.
+**Configure the port on which DNS forwarding listens for incoming
+queries.**
+
+The default is 53.
+```
+
+Example:
+
+```none
+set service dns forwarding port 5353
 ```
 
+```{cfgcmd} set service dns forwarding allow-from \<prefix\>
 
-```{cfgcmd} set service dns forwarding name-server \<address\> port \<port\>
+**Restrict incoming queries to clients whose source IP is within the
+specified IPv4 or IPv6 prefix.**
 
-Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`
-on optional port specified under `<port>`. The port defaults to 53. You can
-configure multiple nameservers here.
+Repeat the command to allow multiple prefixes. At least one prefix is
+required for a successful commit.
 ```
 
+```{note}
+Restrict `allow-from` to trusted networks. Do not use `0.0.0.0/0` or
+`::/0` if the service is reachable from the public Internet.
+```
 
-```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\>
+Example:
+
+```none
+set service dns forwarding allow-from 192.0.2.0/24
+set service dns forwarding allow-from 2001:db8::/32
+```
+
+```{cfgcmd} set service dns forwarding exclude-throttle-address \<address\>
 
-Forward received queries for a particular domain
-(specified via `domain-name`) to a given nameserver. Multiple nameservers
-can be specified. You can use this feature for a DNS split-horizon
-configuration.
+**Prevent throttling of authoritative servers matching the specified
+IPv4 or IPv6 address or prefix.**
 
-:::{note}
-This also works for reverse-lookup zones (``18.172.in-addr.arpa``).
-:::
+DNS forwarding throttles authoritative servers that do not answer a
+query or return responses DNS forwarding rejects. This command exempts
+the specified addresses from throttling. Repeat the command to add
+multiple addresses.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding domain \<domain-name\> addnta
+```none
+set service dns forwarding exclude-throttle-address 192.0.2.53
+set service dns forwarding exclude-throttle-address 2001:db8::53
+```
+
+### Upstream forwarding
+
+```{cfgcmd} set service dns forwarding name-server \<address\>
+
+**Forward queries to the specified IPv4 or IPv6 upstream DNS server.**
 
-Add NTA (negative trust anchor) for this domain. This must be set if the
-domain does not support DNSSEC.
+The upstream servers are configured directly under DNS forwarding.
+Repeat the command to configure multiple upstream servers.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding domain \<domain-name\> recursion-desired
+```none
+set service dns forwarding name-server 192.0.2.53
+set service dns forwarding name-server 2001:db8::53
+```
+
+```{cfgcmd} set service dns forwarding name-server \<address\> port \<1-65535\>
+
+**Configure the destination port used when forwarding queries to the
+specified upstream DNS server.**
 
-Set the "recursion desired" bit in requests to the upstream nameserver.
+The default is 53.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding allow-from \<network\>
+```none
+set service dns forwarding name-server 192.0.2.53 port 853
+```
+
+```{cfgcmd} set service dns forwarding system
+
+**Forward queries to the upstream DNS servers configured under `system
+name-server`.**
 
-Given the fact that open DNS recursors could be used on DDoS amplification
-attacks, you must configure the networks which are allowed to use this
-recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and
-IPv6 networks to query this server. This is generally a bad idea.
+The upstream servers are inherited from `system name-server`.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding dnssec \<off | process-no-validate | process | log-fail | validate\>
+```none
+set service dns forwarding system
+```
+
+```{cfgcmd} set service dns forwarding dhcp \<interface\>
+
+**Forward queries to the DNS servers learned via the DHCPv4 or DHCPv6
+client on the specified interface.**
 
-The PowerDNS recursor has 5 different levels of DNSSEC processing, which can
-be set with the dnssec setting. In order from least to most processing, these
-are:
+Repeat the command to forward queries to DHCP-learned servers from
+multiple interfaces.
+```
+
+Example:
 
-* **off** In this mode, no DNSSEC processing takes place. The recursor will
-not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the
-DO and AD bits in queries.
+```none
+set service dns forwarding dhcp eth0
+```
 
-* **process-no-validate** In this mode the recursor acts as a "security
-aware, non-validating" nameserver, meaning it will set the DO-bit on
-outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to
-clients that ask for them (by means of a DO-bit in the query), except for
-zones provided through the auth-zones setting. It will not do any
-validation in this mode, not even when requested by the client.
+```{cfgcmd} set service dns forwarding source-address \<address\>
 
-* **process** When dnssec is set to process the behavior is similar to
-process-no-validate. However, the recursor will try to validate the data
-if at least one of the DO or AD bits is set in the query; in that case,
-it will set the AD-bit in the response when the data is validated
-successfully, or send SERVFAIL when the validation comes up bogus.
+**Configure the local IPv4 or IPv6 address used as the source when DNS
+forwarding initiates outbound queries.**
 
-* **log-fail** In this mode, the recursor will attempt to validate all data
-it retrieves from authoritative servers, regardless of the client's DNSSEC
-desires, and will log the validation result. This mode can be used to
-determine the extra load and amount of possibly bogus answers before
-turning on full-blown validation. Responses to client queries are the same
-as with process.
+The default is `0.0.0.0` and `::`, which means that the source address
+is selected per outgoing query. Repeat the command to configure
+multiple source addresses.
+```
 
-* **validate** The highest mode of DNSSEC processing. In this mode, all
-queries will be validated and will be answered with a SERVFAIL in case of
-bogus data, regardless of the client's request.
+Example:
+
+```none
+set service dns forwarding source-address 192.0.2.1
+set service dns forwarding source-address 2001:db8::1
+```
+
+```{cfgcmd} set service dns forwarding no-serve-rfc1918
 
-:::{note}
-The popular Unix/Linux ``dig`` tool sets the AD-bit in the query.
-This might lead to unexpected query results when testing. Set ``+noad``
-on the ``dig`` command line when this is the case.
-:::
+**Disable authoritative answering of queries for `10.in-addr.arpa`,
+`168.192.in-addr.arpa`, and `16-31.172.in-addr.arpa` zones.**
 
-:::{note}
-The ``CD``-bit is honored correctly for process and validate. For
-log-fail, failures will be logged too.
-:::
+These are the reverse-lookup zones for the RFC 1918 private address
+ranges. Queries for these zones are then forwarded to the configured
+upstream servers.
 ```
 
+Example:
+
+```none
+set service dns forwarding no-serve-rfc1918
+```
 
 ```{cfgcmd} set service dns forwarding ignore-hosts-file
 
-Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP
-server will use this file to add resolvers to assigned addresses.
+**Do not use the local `/etc/hosts` file in name resolution.**
+
+By default, DNS forwarding answers queries using `/etc/hosts` before
+performing recursion or forwarding.
 ```
 
+Example:
+
+```none
+set service dns forwarding ignore-hosts-file
+```
+
+### Cache and timers
 
 ```{cfgcmd} set service dns forwarding cache-size \<0-2147483647\>
 
-Maximum number of DNS cache entries. 1 million per CPU core will generally
-suffice for most installations.
+**Configure the maximum number of DNS cache entries.**
 
-This defaults to 10000.
+The default is 10000. A value of 0 disables the cache.
 ```
 
+Example:
+
+```none
+set service dns forwarding cache-size 1000000
+```
 
 ```{cfgcmd} set service dns forwarding negative-ttl \<0-7200\>
 
-A query for which there is authoritatively no answer is cached to quickly
-deny a record's existence later on, without putting a heavy load on the
-remote server. In practice, caches can become saturated with hundreds of
-thousands of hosts which are tried only once.
+**Configure the maximum time, in seconds, that negative answers
+(NXDOMAIN and NODATA) are cached.**
+
+The default is 3600.
+```
+
+Example:
+
+```none
+set service dns forwarding negative-ttl 60
+```
+
+```{cfgcmd} set service dns forwarding minimum-ttl-override \<0-2147483647\>
+
+**Configure the minimum {abbr}`TTL (Time-to-Live)`, in seconds,
+applied to cached records regardless of the TTL received from the
+authoritative server.**
+
+Records with a TTL below this value are cached with this minimum
+TTL. The default is `1`.
+```
 
-This setting, which defaults to 3600 seconds, puts a maximum on the amount
-of time negative entries are cached.
+```{note}
+Change this only if you have a specific reason to raise short TTLs,
+as higher values extend caching beyond the authoritative TTL. If the
+record changes upstream, clients receive the outdated cached value
+until the override expires.
 ```
 
+Example:
+
+```none
+set service dns forwarding minimum-ttl-override 30
+```
 
 ```{cfgcmd} set service dns forwarding timeout \<10-60000\>
 
-The number of milliseconds to wait for a remote authoritative server to
-respond before timing out and responding with SERVFAIL.
+**Configure the time, in milliseconds, to wait for a remote
+authoritative server to respond to an outgoing query.**
 
-This setting defaults to 1500 and is valid between 10 and 60000.
+The default is 1500.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding listen-address \<address\>
+```none
+set service dns forwarding timeout 2000
+```
 
-The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder
-will listen on this address for incoming connections.
+```{cfgcmd} set service dns forwarding ttl-percent \<0-100\>
+
+**Refresh cached records in the background when the remaining TTL
+falls below this percentage of the original TTL.**
+
+Clients continue to receive the existing cached answer during refresh.
+The default is 0, which disables background refresh.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding source-address \<address\>
+```none
+set service dns forwarding ttl-percent 10
+```
 
-The local IPv4 or IPv6 addresses to use as a source address for sending queries.
-The forwarder will send forwarded outbound DNS requests from this address.
+```{cfgcmd} set service dns forwarding serve-stale-extension \<0-65535\>
+
+**Configure how many times an expired record's TTL can be extended by
+30 seconds when the record cannot be refreshed.**
+
+The default is 0, which disables serving stale records.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding no-serve-rfc1918
+```none
+set service dns forwarding serve-stale-extension 30
+```
+
+### DNSSEC and NXDOMAIN behavior
 
-This makes the server authoritatively not aware of: 10.in-addr.arpa,
-168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream
-DNS server(s) to be used for reverse lookups of these zones.
+```{cfgcmd} set service dns forwarding dnssec \<off | process-no-validate | process | log-fail | validate\>
+
+**Configure the DNSSEC processing mode for outgoing queries and
+responses:**
+
+- `off`: No DNSSEC processing. DO bits in client queries are ignored,
+  and no DNSSEC records are requested from authoritative servers.
+- `process-no-validate`: Returns DNSSEC records (RRSIG, NSEC) to
+  clients that request them, but does not validate.
+- `process`: Validates responses only when the client requests it (DO
+  or AD bit set). Returns `SERVFAIL` on bogus data.
+- `log-fail`: Validates all responses regardless of client request,
+  logs bogus responses, but returns the same answers as `process`
+  mode.
+- `validate`: Validates all responses and returns `SERVFAIL` on bogus
+  data regardless of client request.
+
+The default is `process-no-validate`.
 ```
 
-### Authoritative zones
+Example:
+
+```none
+set service dns forwarding dnssec validate
+```
+
+```{cfgcmd} set service dns forwarding nothing-below-nxdomain \<no | dnssec | yes\>
+
+**Configure how DNS forwarding handles the NXDOMAIN cut.**
+
+When DNS forwarding has a cached NXDOMAIN, it can also return NXDOMAIN
+for any name beneath the denied name, without asking upstream. This
+setting controls when that behavior applies:
+
+- `no`: Never apply the NXDOMAIN cut.
+- `dnssec`: Apply the NXDOMAIN cut only for DNSSEC-validated NXDOMAIN
+  entries.
+- `yes`: Apply the NXDOMAIN cut for any cached NXDOMAIN that is not
+  bogus.
+
+The default is `dnssec`.
+```
+
+Example:
+
+```none
+set service dns forwarding nothing-below-nxdomain yes
+```
+
+### DNS64
+
+```{cfgcmd} set service dns forwarding dns64-prefix \<prefix\>
+
+**Synthesize AAAA records from A records for names that have no AAAA
+records, using the specified NAT64 IPv6 prefix.**
+
+The prefix length must be exactly `/96`.
+```
+
+Example:
+
+```none
+set service dns forwarding dns64-prefix 2001:db8:64::/96
+```
+
+### EDNS Client Subnet
+
+```{cfgcmd} set service dns forwarding options ecs-add-for \<prefix\>
+
+**Configure which client source address is sent as the
+{abbr}`ECS (EDNS Client Subnet)` value in outgoing queries.**
+
+For clients whose source address matches the specified prefix, the
+client's real address is sent. For non-matching clients, a
+placeholder address is sent instead so no client-specific subnet is
+exposed.
+
+ECS is only sent for queries matching `edns-subnet-allow-list`. This
+option controls only the value, not whether ECS is sent.
+
+Prepend `!` to exclude a prefix. Repeat the command for multiple
+entries.
+```
+
+Example:
+
+```none
+set service dns forwarding options ecs-add-for 192.0.2.0/24
+set service dns forwarding options ecs-add-for !192.0.2.128/25
+```
+
+```{cfgcmd} set service dns forwarding options ecs-ipv4-bits \<0-32\>
+
+**Configure the number of bits of the client's IPv4 address included
+in the ECS option sent to authoritative servers.**
+
+Applies only to queries where ECS is sent (those matching
+`edns-subnet-allow-list`).
+```
+
+Example:
+
+```none
+set service dns forwarding options ecs-ipv4-bits 24
+```
+
+```{cfgcmd} set service dns forwarding options edns-subnet-allow-list \<value\>
+
+**Enable ECS in outgoing queries when the destination server's address
+is within the specified netmask, or when the query name is under the
+specified domain.**
+
+Repeat the command to add multiple entries.
+```
+
+Example:
+
+```none
+set service dns forwarding options edns-subnet-allow-list example.com
+set service dns forwarding options edns-subnet-allow-list 192.0.2.0/24
+```
+
+### Per-domain forwarding
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\>
+
+**Forward queries for the specified domain to the given IPv4 or IPv6
+upstream DNS server.**
+
+Repeat the command to configure multiple nameservers for the same
+domain. Use this option to implement split-horizon DNS. The domain may
+also be a reverse-lookup zone such as `2.0.192.in-addr.arpa`.
+```
+
+Example:
+
+```none
+set service dns forwarding domain example.com name-server 192.0.2.53
+set service dns forwarding domain example.com name-server 2001:db8::53
+```
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\> port \<1-65535\>
+
+**Configure the port on the given upstream DNS server to which queries
+for the specified domain are forwarded.**
+
+The default is 53.
+```
+
+Example:
+
+```none
+set service dns forwarding domain example.com name-server 192.0.2.53 port 853
+```
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> addnta
+
+**Configure the specified domain as an {abbr}`NTA (Negative Trust
+Anchor)`, disabling DNSSEC validation for it.**
+
+Configure this when queries for a DNSSEC-broken domain return
+`SERVFAIL`, so the domain becomes reachable again.
+```
+
+Example:
+
+```none
+set service dns forwarding domain example.com addnta
+```
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> recursion-desired
+
+**Set the {abbr}`RD (Recursion Desired)` bit in queries sent to the
+upstream DNS server for this domain.**
+```
+
+Example:
+
+```none
+set service dns forwarding domain example.com recursion-desired
+```
 
+### Authoritative zones
 
-The VyOS DNS forwarder can also be configured to host authoritative records for a domain.
+DNS forwarding can host authoritative records for a domain, answering
+directly rather than forwarding or recursing queries.
 
 ```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> disable
 
-Disable hosting authoritative zone for `<domain-name>` without deleting from
-configuration.
+**Prevent DNS forwarding from serving the specified authoritative
+zone, without removing it from configuration.**
+
+Queries for names in the zone are forwarded or recursed instead.
 ```
 
+Example:
+
+```none
+set service dns forwarding authoritative-domain example.com disable
+```
 
 ```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> disable
 
-Disable specific record without deleting it from configuration.
+**Prevent DNS forwarding from serving a specific record within the
+authoritative zone, without removing it from configuration.**
+
+Queries matching the record are forwarded or recursed instead.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> ttl \<seconds\>
+```none
+set service dns forwarding authoritative-domain example.com records a www disable
+```
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> ttl \<0-2147483647\>
 
-Set the {abbr}`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds.
+**Configure the TTL, in seconds, for the specified record.**
+
+The default is 300.
+```
+
+Example:
+
+```none
+set service dns forwarding authoritative-domain example.com records a www ttl 600
 ```
 
 #### Record types
 
+The record-type commands in this section accept the following
+record-name keywords:
 
-Below are a list of record types available to be configured within VyOS. Some records
-support special `<name>` keywords:
+- `@`: Represents a zone apex, e.g., `example.com`. Accepted by every
+  record type.
+- `any`: Represents a wildcard record, e.g., `*.example.com`, that
+  matches every subdomain under the apex. Accepted by `a` and `aaaa`
+  records only.
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records a \<name\> address \<ipv4-address\>
 
-- `@` Use @ as record name to set the record for the root domain.
-- `any` Use any as record name to configure the record as a wildcard.
+**Configure an {abbr}`A (IPv4 address)` record in the specified
+authoritative zone.**
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records a \<name\> address \<x.x.x.x\>
+Supports `@` and `any` as `<name>`. Repeat the command to add multiple
+IPv4 addresses to the same record.
+```
 
-Set an {abbr}`A (Address)` record. Supports ``@`` and ``any`` keywords.
+Example:
+
+```none
+set service dns forwarding authoritative-domain example.com records a www address 192.0.2.10
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records aaaa \<name\> address \<ipv6-address\>
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records aaaa \<name\> address \<h:h:h:h:h:h:h:h\>
+**Configure an {abbr}`AAAA (IPv6 address)` record in the specified
+authoritative zone.**
 
-Set an {abbr}`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords.
+Supports `@` and `any` as `<name>`. Repeat the command to add multiple
+IPv6 addresses to the same record.
 ```
 
+Example:
+
+```none
+set service dns forwarding authoritative-domain example.com records aaaa www address 2001:db8::10
+```
 
 ```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records cname \<name\> target \<target-domain-name\>
 
-Set an {abbr}`CNAME (Canonical name)` record. Supports ``@`` keyword.
+**Configure a {abbr}`CNAME (Canonical Name)` record in the specified
+authoritative zone.**
+
+Supports `@` as `<name>`.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<rule-number\> \<option\> \<value\>
+```none
+set service dns forwarding authoritative-domain example.com records cname www target host.example.com
+```
 
-Set an {abbr}`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword.
-NAPTR records support the following options:
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records mx \<name\> server \<server\>
 
-* **lookup-a** A Flag.
+**Configure an {abbr}`MX (Mail Exchanger)` record in the specified
+authoritative zone.**
 
-* **lookup-srv** S flag.
+Supports `@` as `<name>`. Repeat the command to add multiple mail
+servers to the same record.
+```
 
-* **order** Rule order. Requires `<value>`.
+Example:
 
-* **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set.
+```none
+set service dns forwarding authoritative-domain example.com records mx @ server mail.example.com
+```
 
-* **protocol-specific** P flag.
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records mx \<name\> server \<server\> priority \<1-999\>
 
-* **regexp** Regular expression. Requires `<value>`.
+**Configure the priority of the specified MX record.**
 
-* **replacement** Replacement DNS name.
+Lower values are preferred. The default is 10.
+```
 
-* **resolve-uri** U flag.
+Example:
 
-* **service** Service type. Requires `<value>`.
+```none
+set service dns forwarding authoritative-domain example.com records mx @ server mail.example.com priority 20
 ```
 
-
 ```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ns \<name\> target \<target-name\>
 
-Set an {abbr}`NS (Nameserver)` record.
+**Configure an {abbr}`NS (Name Server)` record in the specified
+authoritative zone.**
+
+Supports `@` as `<name>`. Repeat the command to add multiple
+nameservers to the same record.
 ```
 
+Example:
+
+```none
+set service dns forwarding authoritative-domain example.com records ns @ target ns1.example.com
+```
 
 ```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ptr \<name\> target \<target-name\>
 
-Set an {abbr}`PTR (Pointer record)` record. Supports ``@`` keyword.
-```
+**Configure a {abbr}`PTR (Pointer)` record in the specified
+authoritative zone.**
 
+Supports `@` as `<name>`.
+```
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records spf \<name\> value \<value\>
+Example:
 
-Set an {abbr}`SPF (Sender policy framework)` record. Supports ``@`` keyword.
+```none
+set service dns forwarding authoritative-domain 2.0.192.in-addr.arpa records ptr 10 target host.example.com
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records txt \<name\> value \<value\>
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<entry-number\> [hostname | port | priority | weight] \<value\>
+**Configure a {abbr}`TXT (Text)` record in the specified authoritative
+zone.**
 
-Set an {abbr}`SRV (Service)` record. Supports ``@`` keyword.
+Supports `@` as `<name>`. Repeat the command to add multiple TXT
+strings to the same record.
 ```
 
+Example:
 
-```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records txt \<name\> value \<value\>
+```none
+set service dns forwarding authoritative-domain example.com records txt @ value 'v=spf1 -all'
+```
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records spf \<name\> value \<value\>
+
+**Configure an {abbr}`SPF (Sender Policy Framework)` record in the
+specified authoritative zone.**
 
-Set an {abbr}`TXT (Text)` record. Supports ``@`` keyword.
+Supports `@` as `<name>`.
 ```
 
-## Example
+```{note}
+SPF records are deprecated in favor of TXT records. Prefer TXT records
+for new deployments.
+```
 
+Example:
 
-A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to
-implement a split-horizon DNS configuration for example.com.
+```none
+set service dns forwarding authoritative-domain example.com records spf @ value 'v=spf1 -all'
+```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<0-65535\> hostname \<name\>
 
-In this scenario:
+**Configure the target hostname of an {abbr}`SRV (Service Locator)`
+record entry in the specified authoritative zone.**
 
+Supports `@` as `<name>`.
+```
 
-- All DNS requests for example.com must be forwarded to a DNS server
-  at 192.0.2.254 and 2001:db8:cafe::1
-- All other DNS requests will be forwarded to a different set of DNS servers at
-  192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff
-- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN)
-  interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6
-- The VyOS DNS forwarder will only accept lookup requests from the
-  LAN subnets - 192.168.1.0/24 and 2001:db8::/64
-- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa,
-  168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server.
+Example:
 
 ```none
-set service dns forwarding domain example.com name-server 192.0.2.254
-set service dns forwarding domain example.com name-server 2001:db8:cafe::1
-set service dns forwarding name-server 192.0.2.1
-set service dns forwarding name-server 192.0.2.2
-set service dns forwarding name-server 192.0.2.3 port 853
-set service dns forwarding name-server 2001:db8::1:ffff
-set service dns forwarding name-server 2001:db8::2:ffff
-set service dns forwarding name-server 2001:db8::3:ffff port 8053
-set service dns forwarding listen-address 192.168.1.254
-set service dns forwarding listen-address 2001:db8::ffff
-set service dns forwarding allow-from 192.168.1.0/24
-set service dns forwarding allow-from 2001:db8::/64
-set service dns forwarding no-serve-rfc1918
+set service dns forwarding authoritative-domain example.com records srv _sip._tcp entry 0 hostname sip.example.com
 ```
 
-## Operation
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<0-65535\> port \<0-65535\>
+
+**Configure the port of an SRV record entry in the specified
+authoritative zone.**
+```
 
-```{opcmd} reset dns forwarding \<all | domain\>
+Example:
 
-Resets the local DNS forwarding cache database. You can reset the cache
-for all entries or only for entries to a specific domain.
+```none
+set service dns forwarding authoritative-domain example.com records srv _sip._tcp entry 0 port 5060
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<0-65535\> priority \<0-65535\>
 
-```{opcmd} restart dns forwarding
+**Configure the priority of an SRV record entry in the specified
+authoritative zone.**
 
-Restarts the DNS recursor process. This also invalidates the local DNS
-forwarding cache.
+Lower values are preferred. The default is 10.
 ```
 
-(dynamic-dns)=
+Example:
 
-# Dynamic DNS
+```none
+set service dns forwarding authoritative-domain example.com records srv _sip._tcp entry 0 priority 20
+```
 
-VyOS is able to update a remote DNS record when an interface gets a new IP
-address. In order to do so, VyOS includes [ddclient], a Perl script written for
-this only one purpose.
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<0-65535\> weight \<0-65535\>
 
-[ddclient] uses two methods to update a DNS record. The first one will send
-updates directly to the DNS daemon, in compliance with {rfc}`2136`. The second
-one involves a third party service, like DynDNS.com or any other such
-service provider. This method uses HTTP requests to transmit the new IP address.
-You can configure both in VyOS.
-(dns-dynamic-config)=
+**Configure the weight of an SRV record entry in the specified
+authoritative zone.**
 
-## Configuration
-### {rfc}`2136` Based
+Weight is used to distribute load among entries with equal priority.
+The default is 0.
+```
 
-```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+Example:
 
-   Create new dynamic DNS update configuration which will update the IP
-   address assigned to `<interface>` on the service you configured under
-   `<service-name>`.
+```none
+set service dns forwarding authoritative-domain example.com records srv _sip._tcp entry 0 weight 50
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> order \<0-65535\>
 
-```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+**Configure the order field of a {abbr}`NAPTR (Naming Authority
+Pointer)` rule in the specified authoritative zone.**
 
-Set description `<text>` for dynamic DNS service being configured.
+Supports `@` as `<name>`. Rules with lower order are evaluated first.
 ```
 
+Example:
 
-```{cfgcmd} set service dns dynamic name \<service-name\> key \<filename\>
-
-File identified by `<filename>` containing the TSIG authentication key for RFC2136
-nsupdate on remote DNS server.
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 order 10
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> preference \<0-65535\>
 
-```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+**Configure the preference field of a NAPTR rule in the specified
+authoritative zone.**
 
-Configure the DNS `<server>` IP/FQDN used when updating this dynamic
-assignment.
+Supports `@` as `<name>`. The default is 0.
 ```
 
+Example:
 
-```{cfgcmd} set service dns dynamic name \<service-name\> zone \<zone\>
-
-Configure DNS `<zone>` to be updated.
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 preference 50
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> lookup-a
 
-```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<record\>
+**Set the A flag on a NAPTR rule in the specified authoritative
+zone.**
 
-Configure DNS `<record>` which should be updated. This can be set multiple times.
+When set, DNS forwarding treats the rule's output as a domain name and
+looks up its A or AAAA record. No further NAPTR lookups follow.
 ```
 
+```{note}
+Set at most one of `lookup-a`, `lookup-srv`, `resolve-uri`, and
+`protocol-specific` on the same NAPTR rule. These flags define
+mutually exclusive next actions in the DNS resolution.
+```
 
-```{cfgcmd} set service dns dynamic name \<service-name\> ttl \<ttl\>
+Example:
 
-Configure optional TTL value on the given resource record. This defaults to
-600 seconds.
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 lookup-a
 ```
 
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> lookup-srv
 
-```{cfgcmd} set service dns dynamic interval \<60-3600\>
+**Set the S flag on a NAPTR rule in the specified authoritative
+zone.**
 
-Specify interval in seconds to wait between Dynamic DNS updates.
-The default is  300 seconds.
+When set, DNS forwarding treats the rule's output as a domain name and
+looks up its SRV record. No further NAPTR lookups follow.
 ```
 
-(dns-dynamic-example)=
+Example:
 
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 lookup-srv
+```
 
-#### Example
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> resolve-uri
 
+**Set the U flag on a NAPTR rule in the specified authoritative
+zone.**
 
-- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io`
-- Use auth key file at `/config/auth/my.key`
-- Set TTL to 300 seconds
+When set, DNS forwarding treats the rule's output as a URI and uses it
+directly. No further DNS lookups follow.
+```
+
+Example:
 
 ```none
-# Configuration commands entered:
-#
-set service dns dynamic name 'VyOS-DNS' address interface 'eth0'
-set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service'
-set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key'
-set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io'
-set service dns dynamic name 'VyOS-DNS' zone 'vyos.io'
-set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io'
-set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate'
-set service dns dynamic name 'VyOS-DNS' ttl '300'
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 resolve-uri
+```
 
-# Resulting config:
-#
-vyos@vyos# show service dns dynamic
- name VyOS-DNS {
-     address {
-         interface eth0
-     }
-     description "RFC 2136 dynamic dns service"
-     host-name example.vyos.io
-     key /config/auth/my.key
-     protocol nsupdate
-     server ns1.vyos.io
-     ttl 300
-     zone vyos.io
- }
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> protocol-specific
+
+**Set the P flag on a NAPTR rule in the specified authoritative
+zone.**
+
+When set, DNS forwarding treats the rule's output according to the
+associated application protocol. No further DNS lookups follow.
 ```
 
-This will render the following [ddclient] configuration entry:
+Example:
 
 ```none
-# ddclient configuration for interface "eth0":
-#
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 protocol-specific
+```
 
-# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io]
-use=if, \
-if=eth0, \
-protocol=nsupdate, \
-server=ns1.vyos.io, \
-zone=vyos.io, \
-password='/config/auth/my.key', \
-ttl=300 \
-example.vyos.io
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> service \<service\>
+
+**Configure the Service field of a NAPTR rule in the specified
+authoritative zone.**
+
+Defines the protocol and resolution service this rule offers in
+`Protocol+ResolutionService` format (for example, SIP over TCP →
+`SIP+D2T`).
 ```
 
-:::{note}
-You can also keep different DNS zone updated. Just create a new
-config node: `set service dns dynamic interface <interface> rfc2136
-<other-service-name>`
-:::
+Example:
+
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 service SIP+D2T
+```
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> regexp \<expression\>
+
+**Configure the Regexp field of a NAPTR rule in the specified
+authoritative zone.**
+
+A substitution expression in `!ere!replacement!` format, applied to
+the query name to produce the next-lookup target or URI.
+```
 
+```{note}
+A rule uses either `regexp` or `replacement`, not both. Setting both
+produces a malformed NAPTR record.
+```
 
-### HTTP based services
+Example:
 
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 regexp !^.*$!sip:helpdesk@example.com!
+```
 
-VyOS is also able to use any service relying on protocols supported by ddclient.
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<0-65535\> replacement \<target-name\>
 
+**Configure the Replacement field of a NAPTR rule in the specified
+authoritative zone.**
 
-To use such a service, one must define a login, password, one or multiple
-hostnames, protocol and server.
+An absolute DNS name used as the target of the next lookup, whose type
+depends on the rule's flag.
+```
 
-```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+Example:
 
-Create new dynamic DNS update configuration which will update the IP
-address assigned to `<interface>` on the service you configured under
-`<service-name>`.
+```none
+set service dns forwarding authoritative-domain example.com records naptr @ rule 100 replacement sip.example.com
 ```
 
+### Zone caching
 
-```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+DNS forwarding can load a zone directly into its cache via
+AXFR or from a zone file at a URL.
+Zone caching is configured under
+`service dns forwarding zone-cache <domain-name>`.
 
-Set description `<text>` for dynamic DNS service being configured.
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> source axfr \<address\>
+
+**Configure DNS forwarding to load the specified zone via AXFR from
+the given IPv4 or IPv6 DNS server.**
+```
+
+Example:
+
+```none
+set service dns forwarding zone-cache example.com source axfr 192.0.2.53
 ```
 
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> source url \<url\>
 
-```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<hostname\>
+**Configure DNS forwarding to load the specified zone from the given
+HTTP(S) URL pointing to a zone file.**
+```
+
+Example:
 
-Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS
-provider identified by `<service-name>`.
+```none
+set service dns forwarding zone-cache example.com source url https://zones.example.com/example.com.zone
 ```
 
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options timeout \<1-3600\>
 
-```{cfgcmd} set service dns dynamic name \<service-name\> username \<username\>
+**Configure how long, in seconds, DNS forwarding waits for the zone to
+be retrieved before aborting the attempt.**
 
-Configure `<username>` used when authenticating the update request for
-DynDNS service identified by `<service-name>`.
+The default is 20.
 ```
 
+Example:
+
+```none
+set service dns forwarding zone-cache example.com options timeout 60
+```
 
-```{cfgcmd} set service dns dynamic name \<service-name\> password \<password\>
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options refresh interval \<0-31536000\>
 
-Configure `<password>` used when authenticating the update request for
-DynDNS service identified by `<service-name>`.
+**Configure the interval, in seconds, between periodic retrievals of
+the zone into the cache.**
+
+The default is 86400. A value of 0 disables periodic refresh.
+```
+
+Example:
+
+```none
+set service dns forwarding zone-cache example.com options refresh interval 3600
 ```
 
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options refresh on-reload
 
-```{cfgcmd} set service dns dynamic name \<service-name\> protocol \<protocol\>
+**Retrieve the zone into the cache only at startup and when the
+service is reloaded.**
+```
+
+Example:
 
-When a ``custom`` DynDNS provider is used, the protocol used for communicating
-to the provider must be specified under `<protocol>`. See the embedded
-completion helper when entering above command for available protocols.
+```none
+set service dns forwarding zone-cache example.com options refresh on-reload
 ```
 
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options retry-interval \<1-86400\>
 
-```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+**Configure the interval, in seconds, before retrying zone retrieval
+after an error.**
 
-When a ``custom`` DynDNS provider is used the `<server>` where update
-requests are being sent to must be specified.
+The default is 60.
 ```
 
+Example:
+
+```none
+set service dns forwarding zone-cache example.com options retry-interval 300
+```
 
-```{cfgcmd} set service dns dynamic name \<service-name\> ip-version 'ipv6'
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options max-zone-size \<0-1024\>
 
-Allow explicit IPv6 address for the interface.
+**Configure the maximum size, in megabytes, of a zone loaded into the
+cache.**
+
+The default is 0, which imposes no limit.
+```
+
+Example:
+
+```none
+set service dns forwarding zone-cache example.com options max-zone-size 100
 ```
 
-#### Example:
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options zonemd \<ignore | validate | require\>
 
-Use deSEC (dedyn.io) as your preferred provider:
+**Configure how DNS forwarding treats the ZONEMD digest of a retrieved
+zone:**
+
+- `ignore`: Does not check the ZONEMD digest.
+- `validate`: Validates the ZONEMD digest if present.
+- `require`: Rejects the zone unless a valid ZONEMD digest is present.
+
+The default is `validate`.
+```
+
+Example:
 
 ```none
-set service dns dynamic name dedyn description 'deSEC dynamic dns service'
-set service dns dynamic name dedyn username 'myusername'
-set service dns dynamic name dedyn password 'mypassword'
-set service dns dynamic name dedyn host-name 'myhostname.dedyn.io'
-set service dns dynamic name dedyn protocol 'dyndns2'
-set service dns dynamic name dedyn server 'update.dedyn.io'
-set service dns dynamic name dedyn address interface 'eth0'
+set service dns forwarding zone-cache example.com options zonemd require
 ```
 
-:::{note}
-Multiple services can be used per interface. Just specify as many
-services per interface as you like!
-:::
-#### Example IPv6 only:
+```{cfgcmd} set service dns forwarding zone-cache \<domain-name\> options dnssec \<ignore | validate | require\>
+
+**Configure the DNSSEC validation policy for a retrieved zone:**
+
+- `ignore`: No DNSSEC validation.
+- `validate`: Rejects zones with incorrect signatures but accepts
+  unsigned zones.
+- `require`: Rejects the zone unless it is DNSSEC-signed and passes
+  signature validation.
+
+The default is `validate`.
+```
+
+Example:
 
 ```none
-set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service'
-set service dns dynamic name dedyn username 'myusername'
-set service dns dynamic name dedyn password 'mypassword'
-set service dns dynamic name dedyn host-name 'myhostname.dedyn.io'
-set service dns dynamic name dedyn protocol 'dyndns2'
-set service dns dynamic name dedyn ip-version 'ipv6'
-set service dns dynamic name dedyn server 'update6.dedyn.io'
-set service dns dynamic name dedyn address interface 'eth0'
+set service dns forwarding zone-cache example.com options dnssec require
+```
+
+## Operation
+
+### Show
+
+```{opcmd} show dns forwarding statistics
+
+**Show operational statistics collected by DNS forwarding.**
 ```
 
-### Running Behind NAT
+```{opcmd} show log dns forwarding
+
+**Show log entries for DNS forwarding since the last boot.**
+```
 
-By default, [ddclient] will update a dynamic dns record using the IP address
-directly attached to the interface. If your VyOS instance is behind NAT, your
-record will be updated to point to your internal IP.
+```{opcmd} monitor log dns forwarding
 
-[ddclient] has another way to determine the WAN IP address. This is controlled
-by:
+**Follow the DNS forwarding service log in real time.**
+```
+
+### Reset and restart
+
+```{opcmd} reset dns forwarding all
+
+**Clear the entire DNS forwarding cache.**
+```
 
-```{cfgcmd} set service dns dynamic name \<service-name\> address web \<url\>
+```{opcmd} reset dns forwarding domain \<domain-name\>
 
-Use configured `<url>` to determine your IP address. [ddclient] will load
-`<url>` and tries to extract your IP address from the response.
+**Clear the DNS forwarding cache entries for the specified domain
+only.**
 ```
-```{cfgcmd} set service dns dynamic name \<service-name\> address web skip \<pattern\>
 
-ddclient will skip any address located before the string set in `<pattern>`.
+```{opcmd} restart dns forwarding
+
+**Restart the DNS forwarding service.**
+
+Restarting the service also clears its cache.
 ```
 
-[ddclient]: https://github.com/ddclient/ddclient
+## Example
+
+The following configuration implements split-horizon DNS for
+`example.com` on a VyOS router with two interfaces (`eth0` WAN, `eth1`
+LAN):
+
+- DNS queries for `example.com` are forwarded to `192.0.2.254` and
+  `2001:db8:cafe::1`.
+- All other DNS queries are forwarded to a set of upstream servers,
+  two of which use non-standard ports.
+- DNS forwarding listens only on LAN interface addresses.
+- DNS forwarding accepts DNS queries only from LAN clients.
+- Reverse lookups for RFC 1918 zones are forwarded upstream rather
+  than answered locally.
+
+```none
+set service dns forwarding domain example.com name-server 192.0.2.254
+set service dns forwarding domain example.com name-server 2001:db8:cafe::1
+set service dns forwarding name-server 192.0.2.1
+set service dns forwarding name-server 192.0.2.2
+set service dns forwarding name-server 192.0.2.3 port 853
+set service dns forwarding name-server 2001:db8::1:ffff
+set service dns forwarding name-server 2001:db8::2:ffff
+set service dns forwarding name-server 2001:db8::3:ffff port 8053
+set service dns forwarding listen-address 192.168.1.254
+set service dns forwarding listen-address 2001:db8::ffff
+set service dns forwarding allow-from 192.168.1.0/24
+set service dns forwarding allow-from 2001:db8::/64
+set service dns forwarding no-serve-rfc1918
+```