docs: Update Dynamic DNS page to VyOS 1.5 standards (#2164)

* docs: Update Dynamic DNS page to VyOS 1.5 standards

2 files changed, 353 insertions, 0 deletions

diff --git a/docs/configuration/service/dynamic-dns.md b/docs/configuration/service/dynamic-dns.md
new file mode 100644
index 00000000..a828a7c3
--- /dev/null
+++ b/docs/configuration/service/dynamic-dns.md
@@ -0,0 +1,352 @@
+---
+myst:
+  html_meta:
+    description: |
+      Dynamic DNS is a VyOS service that keeps a DNS record updated
+      with the current IP address of an interface. It supports direct
+      DNS updates via RFC 2136 and hosted updates via third-party
+      dynamic DNS providers such as Cloudflare, DuckDNS, deSEC, and
+      DynDNS.
+    keywords: dynamic dns, ddns, rfc 2136, nsupdate, cloudflare, dyndns
+---
+
+(dynamic-dns)=
+
+# Dynamic DNS
+
+The dynamic DNS service updates the DNS record (an A record for IPv4 or
+an AAAA record for IPv6) that maps your hostname to your device whenever
+your IP address changes, so you can always reach your device by
+hostname.
+
+Two update mechanisms are available:
+
+- Direct DNS update ([RFC 2136](https://datatracker.ietf.org/doc/html/rfc2136)):
+  Updates the record by sending an RFC 2136 DNS UPDATE message to an
+  authoritative DNS server. Use this option when you run your own DNS
+  server.
+- Hosted DNS update: Updates the record by sending an HTTP(S) update
+  request to a third-party dynamic DNS provider (such as Cloudflare,
+  DuckDNS, deSEC, or DynDNS). Use this option when relying on an
+  external provider.
+
+## Configuration
+
+### Common commands
+
+The following commands apply to both direct and hosted DNS updates.
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+
+**Configure the interface whose IP address the dynamic DNS record
+points to.**
+```
+
+```{note}
+Mutually exclusive with `address web` within the same dynamic DNS
+`<service-name>` configuration.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS address interface eth0
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+
+**Configure a description for the dynamic DNS service configuration.**
+
+Limited to 255 characters.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS description 'RFC 2136 dynamic DNS service'
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<hostname\>
+
+**Configure a hostname whose DNS record is kept updated with the current
+IP address.**
+
+Accepts a standard hostname, `@` for the zone apex, or `*` for a
+wildcard record. Repeat the command to add several hostnames to the
+same dynamic DNS `<service-name>` configuration.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS host-name host.example.com
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> protocol \<protocol\>
+
+**Configure the protocol used to send updates.**
+
+Use `nsupdate` for direct DNS updates, or a provider-specific protocol
+such as `cloudflare`, `dyndns2`, or `duckdns` for hosted DNS updates.
+Use CLI tab-completion to list the available protocols.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS protocol nsupdate
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+
+**Configure the IP address or {abbr}`FQDN (Fully Qualified Domain Name)`
+of the authoritative DNS server (direct DNS updates), or the provider's
+endpoint (hosted DNS updates).**
+
+Required for `nsupdate` and optional for HTTP(S)-based protocols.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS server ns1.example.com
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> zone \<zone\>
+
+**Configure the DNS zone that contains the configured hostnames.**
+
+The value must be an FQDN. Required for protocols `cloudflare`,
+`digitalocean`, `godaddy`, `hetzner`, `gandi`, `nfsn`, and `nsupdate`.
+Also accepted for `dnsexit2` and `zoneedit1`. Not supported for any
+other protocol.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS zone example.com
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> ttl \<0-2147483647\>
+
+**Configure the {abbr}`TTL (Time-To-Live)`, in seconds, of the updated
+DNS records.**
+
+The TTL sets how long DNS resolvers may cache the record before it must
+be re-fetched. Supported only for protocols `cloudflare`, `dnsexit2`,
+`gandi`, `godaddy`, `hetzner`, `nfsn`, and `nsupdate`. When unset, no
+TTL is included in the update.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS ttl 300
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> ip-version \<ipv4 | ipv6 | both\>
+
+**Configure which DNS record types are updated:**
+
+- `ipv4`: Updates the A record only.
+- `ipv6`: Updates the AAAA record only.
+- `both`: Updates both the A and AAAA records.
+
+The default is `ipv4`.
+
+`both` is supported only for protocols `cloudflare`, `digitalocean`,
+`dnsexit2`, `duckdns`, `dyndns2`, `easydns`, `freedns`, `hetzner`,
+`infomaniak`, and `njalla`.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS ip-version ipv6
+```
+
+```{cfgcmd} set service dns dynamic interval \<60-3600\>
+
+**Configure the interval, in seconds, between updates of the configured
+DNS records.**
+
+The default is 300.
+```
+
+Example:
+
+```none
+set service dns dynamic interval 300
+```
+
+### Running behind NAT
+
+By default, the IP address configured under `address interface` is what
+gets registered. When VyOS is behind NAT, this is the internal address
+that cannot be reached from the public Internet. Configure `address web`
+instead so the DNS record points to the public IP address.
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address web url \<url\>
+
+**Configure an HTTP(S) URL from which dynamic DNS obtains the IP address
+for the DNS record.**
+```
+
+```{note}
+Mutually exclusive with `address interface` within the same dynamic DNS
+`<service-name>` configuration.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS address web url https://ipv4.icanhazip.com
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address web skip \<pattern\>
+
+**Configure dynamic DNS to ignore URL response text before the
+specified pattern when extracting the public IP address.**
+```
+
+```{note}
+Requires `address web url` to be set within the same dynamic DNS
+`<service-name>` configuration.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS address web skip 'Current IP Address:'
+```
+
+### Direct DNS update (RFC 2136)
+
+```{cfgcmd} set service dns dynamic name \<service-name\> key \<filename\>
+
+**Configure the file containing the {abbr}`TSIG (Transaction Signature)`
+key used to authenticate direct DNS update messages.**
+
+The file must be within the `/config/auth` directory. Required when
+`protocol` is `nsupdate`; other protocols use `password` instead.
+```
+
+Example:
+
+```none
+set service dns dynamic name VyOS-DNS key /config/auth/my.key
+```
+
+### Hosted (provider-based) DNS update
+
+```{cfgcmd} set service dns dynamic name \<service-name\> username \<username\>
+
+**Configure the username presented in HTTP(S) update requests to the
+dynamic DNS provider.**
+
+Required for most protocols. Not required for `1984`, `cloudflare`,
+`cloudns`, `digitalocean`, `dnsexit2`, `duckdns`, `freemyip`, `hetzner`,
+`keysystems`, `njalla`, `nsupdate`, and `regfishde`.
+```
+
+Example:
+
+```none
+set service dns dynamic name dedyn username myusername
+```
+
+```{cfgcmd} set service dns dynamic name \<service-name\> password \<password\>
+
+**Configure the password, or provider API token, presented in HTTP(S)
+update requests to the dynamic DNS provider.**
+
+Required for every protocol except `nsupdate`, which uses `key` instead.
+```
+
+Example:
+
+```none
+set service dns dynamic name dedyn password mypassword
+```
+
+## Examples
+
+### Direct DNS update ([RFC 2136](https://datatracker.ietf.org/doc/html/rfc2136))
+
+The following example registers the DNS record `example.vyos.io` on the
+DNS server `ns1.vyos.io`, keeps it updated with the current IP address
+of `eth0`, authenticates updates with the TSIG key at
+`/config/auth/my.key`, and sets a TTL of 300 seconds.
+
+```none
+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'
+```
+
+Resulting configuration:
+
+```none
+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
+ }
+```
+
+```{note}
+You can define multiple dynamic DNS `<service-name>` configurations,
+each registering its own set of DNS records.
+```
+
+### Hosted (provider-based) DNS update
+
+The following example registers the DNS record `myhostname.dedyn.io`
+with deSEC via the `dyndns2` protocol, keeps it updated with the current
+IP address of `eth0`, and authenticates updates with the configured
+username and password.
+
+```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'
+```
+
+```{note}
+You can define multiple dynamic DNS `<service-name>` configurations,
+each registering its own set of DNS records.
+```
+
+The following example is the same as above, but restricted to IPv6: the
+AAAA record for `myhostname.dedyn.io` is updated with the current IPv6
+address of `eth0`, using deSEC's IPv6 update endpoint
+`update6.dedyn.io`.
+
+```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'
+```
diff --git a/docs/configuration/service/index.md b/docs/configuration/service/index.md
index 05041abf..d807fcc8 100644
--- a/docs/configuration/service/index.md
+++ b/docs/configuration/service/index.md
@@ -11,6 +11,7 @@ console-server
 dhcp-relay
 dhcp-server
 dns
+dynamic-dns
 eventhandler
 https
 ipoe-server