Merge pull request #1314 from vyos/mergify/bp/master/pr-1313

Rewrote Dynamic DNS documentation/examples to align with T5791 (backport #1313)

1 files changed, 93 insertions, 105 deletions

diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst
index e430dc73..c6deb179 100644
--- a/docs/configuration/service/dns.rst
+++ b/docs/configuration/service/dns.rst
@@ -143,33 +143,6 @@ avoid being tracked by the provider of your upstream DNS server.
    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 serve-stale-extension <0-65535>
-
-   Maximum number of times an expired record’s TTL is extended by 30s when
-   serving stale. Extension only occurs if a record cannot be refreshed. A
-   value of 0 means the Serve Stale mechanism is not used. To allow records
-   becoming stale to be served for an hour, use a value of 120.
-
-.. cfgcmd:: set service dns forwarding exclude-throttle-address <ip|prefix>
-
-   When an authoritative server does not answer a query or sends a reply the
-   recursor does not like, it is throttled. Any servers matching the supplied
-   netmasks will never be throttled.
-
-.. cfgcmd:: set service dns forwarding options ecs-add-for <address>
-
-   The requestor netmask for which the requestor IP Address should be used as the
-   EDNS Client Subnet for outgoing queries.
-
-.. cfgcmd:: set service dns forwarding options ecs-ipv4-bits <number>
-
-   Number of bits of client IPv4 address to pass when sending EDNS Client Subnet
-   address information.
-
-.. cfgcmd:: set service dns forwarding options edns-subnet-allow-list <address|domain>
-
-   The netmask or domain that EDNS Client Subnet should be enabled for in outgoing queries.
-
 Example
 =======
 
@@ -231,8 +204,8 @@ this only one purpose.
 
 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 similar
-website. This method uses HTTP requests to transmit the new IP address. You
+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:dynmaic_config:
@@ -243,46 +216,43 @@ Configuration
 :rfc:`2136` Based
 -----------------
 
-.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name>
+.. cfgcmd:: set service dns dynamic name <service-name> address interface <interface>
 
-   Create new :rfc:`2136` DNS update configuration which will update the IP
+   Create new dynamic DNS update configuration which will update the IP
    address assigned to `<interface>` on the service you configured under
    `<service-name>`.
 
-.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name>
-   key <keyfile>
+.. cfgcmd:: set service dns dynamic name <service-name> description <text>
+   
+   Set description `<text>` for dynamic DNS service being configured.
+
+.. cfgcmd:: set service dns dynamic name <service-name> key <filename>
 
-   File identified by `<keyfile>` containing the secret RNDC key shared with
-   remote DNS server.
+   File identified by `<filename>` containing the TSIG authentication key for RFC2136
+   nsupdate on remote DNS server.
 
-.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name>
-   server <server>
+.. cfgcmd:: set service dns dynamic name <service-name> server <server>
 
    Configure the DNS `<server>` IP/FQDN used when updating this dynamic
    assignment.
 
-.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name>
-   zone <zone>
+.. cfgcmd:: set service dns dynamic name <service-name> zone <zone>
 
    Configure DNS `<zone>` to be updated.
 
-.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name>
-   record <record>
+.. cfgcmd:: set service dns dynamic name <service-name> host-name <record>
 
-   Configure DNS `<record>` which should be updated. This can be set multiple
-   times.
+   Configure DNS `<record>` which should be updated. This can be set multiple times.
 
-.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name>
-   ttl <ttl>
+.. cfgcmd:: set service dns dynamic name <service-name> ttl <ttl>
 
    Configure optional TTL value on the given resource record. This defaults to
    600 seconds.
 
-.. cfgcmd:: set service dns dynamic timeout <60-3600>
+.. cfgcmd:: set service dns dynamic interval <60-3600>
 
-   Specify timeout / update interval to check if IP address changed.
-
-   This defaults to 300 seconds.
+   Specify interval in seconds to wait between Dynamic DNS updates.
+   The default is  300 seconds.
 
 .. _dns:dynmaic_example:
 
@@ -295,32 +265,48 @@ Example
 
 .. code-block:: 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'
+
+  # Resulting config:
+  #
   vyos@vyos# show service dns dynamic
-   interface eth0.7 {
-       rfc2136 VyOS-DNS {
-           key /config/auth/my.key
-           record example.vyos.io
-           server ns1.vyos.io
-           ttl 300
-           zone vyos.io
+   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
    }
 
 This will render the following ddclient_ configuration entry:
 
 .. code-block:: none
 
+  # ddclient configuration for interface "eth0":
   #
-  # ddclient configuration for interface "eth0.7":
-  #
-  use=if, if=eth0.7
-
-  # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io
-  server=ns1.vyos.io
-  protocol=nsupdate
-  password=/config/auth/my.key
-  ttl=300
-  zone=vyos.io
+
+  # 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
 
 .. note:: You can also keep different DNS zone updated. Just create a new
@@ -335,40 +321,43 @@ VyOS is also able to use any service relying on protocols supported by ddclient.
 To use such a service, one must define a login, password, one or multiple
 hostnames, protocol and server.
 
-.. cfgcmd:: set service dns dynamic address <interface> service <service>
-   host-name <hostname>
+.. cfgcmd:: set service dns dynamic name <service-name> address interface <interface>
+  
+   Create new dynamic DNS update configuration which will update the IP   
+   address assigned to `<interface>` on the service you configured under
+   `<service-name>`.
+
+.. cfgcmd:: set service dns dynamic name <service-name> description <text>
+
+   Set description `<text>` for dynamic DNS service being configured.
+
+.. cfgcmd:: set service dns dynamic name <service-name> host-name <hostname>
 
    Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS
-   provider identified by `<service>` when the IP address on address
-   `<interface>` changes.
+   provider identified by `<service-name>`.
 
-.. cfgcmd:: set service dns dynamic address <interface> service <service>
-   username <username>
+.. cfgcmd:: set service dns dynamic name <service-name> username <username>
 
    Configure `<username>` used when authenticating the update request for
-   DynDNS service identified by `<service>`.
-   For Namecheap, set the <domain> you wish to update.
+   DynDNS service identified by `<service-name>`.
 
-.. cfgcmd:: set service dns dynamic address <interface> service <service>
-   password <password>
+.. cfgcmd:: set service dns dynamic name <service-name> password <password>
 
    Configure `<password>` used when authenticating the update request for
-   DynDNS service identified by `<service>`.
+   DynDNS service identified by `<service-name>`.
 
-.. cfgcmd:: set service dns dynamic address <interface> service <service>
-   protocol <protocol>
+.. cfgcmd:: set service dns dynamic name <service-name> protocol <protocol>
 
-   When a ``custom`` DynDNS provider is used the protocol used for communicating
+   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 for available protocols.
+   completion helper when entering above command for available protocols.
 
-.. cfgcmd:: set service dns dynamic address <interface> service <service>
-   server <server>
+.. cfgcmd:: set service dns dynamic name <service-name> server <server>
 
    When a ``custom`` DynDNS provider is used the `<server>` where update
    requests are being sent to must be specified.
 
-.. cfgcmd:: set service dns dynamic address <interface> ipv6-enable
+.. cfgcmd:: set service dns dynamic name <service-name> ip-version 'ipv6'
 
    Allow explicit IPv6 address for the interface.
 
@@ -376,14 +365,17 @@ hostnames, protocol and server.
 Example:
 ^^^^^^^^
 
-Use DynDNS as your preferred provider:
+Use deSEC (dedyn.io) as your preferred provider:
 
 .. code-block:: none
 
-  set service dns dynamic address eth0 service dyndns
-  set service dns dynamic address eth0 service dyndns username my-login
-  set service dns dynamic address eth0 service dyndns password my-password
-  set service dns dynamic address eth0 service dyndns host-name my-dyndns-hostname
+  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:: Multiple services can be used per interface. Just specify as many
    services per interface as you like!
@@ -393,12 +385,14 @@ Example IPv6 only:
 
 .. code-block:: none
 
-  set service dns dynamic address eth0 ipv6-enable
-  set service dns dynamic address eth0 service dyndns6 username my-login
-  set service dns dynamic address eth0 service dyndns6 password my-password
-  set service dns dynamic address eth0 service dyndns6 host-name my-dyndns-hostname
-  set service dns dynamic address eth0 service dyndns6 protocol dyndns2
-  set service dns dynamic address eth0 service dyndns6 server dyndns-v6-server
+  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'
 
 
 Running Behind NAT
@@ -408,21 +402,15 @@ 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.
 
-Above, command syntax isn noted to configure dynamic dns on a specific interface.
-It is possible to overlook the additional address option, web, when completeing
-those commands. ddclient_ has another way to determine the WAN IP address, using
-a web-based url to determine the external IP. Each of the commands above will
-need to be modified to use 'web' as the 'interface' specified if this functionality
-is to be utilized.
-
-This functionality is controlled by adding the following configuration:
+ddclient_ has another way to determine the WAN IP address. This is controlled
+by:
 
-.. cfgcmd:: set service dns dynamic address web web-options url <url>
+.. cfgcmd:: set service dns dynamic name <service-name> address web <url>
 
    Use configured `<url>` to determine your IP address. ddclient_ will load
    `<url>` and tries to extract your IP address from the response.
 
-.. cfgcmd:: set service dns dynamic address web web-options skip <pattern>
+.. cfgcmd:: set service dns dynamic name <service-name> address web skip <pattern>
 
    ddclient_ will skip any address located before the string set in `<pattern>`.