dynamic-dns: rewrite with new cfgcmd/opcmd syntax

2 files changed, 102 insertions, 91 deletions

diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst
index ed133b08..80027647 100644
--- a/docs/services/dynamic-dns.rst
+++ b/docs/services/dynamic-dns.rst
@@ -14,141 +14,153 @@ 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
 can configure both in VyOS.
 
-CLI and RFC2136
-===============
+Configuration
+=============
 
-First, create an :rfc:`2136` config node :
+:rfc:`2136` Based
+-----------------
 
-.. code-block:: none
+.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name>
 
-  edit service dns dynamic interface eth0 rfc2136 <confignodename>
+Create new :rfc:`2136` DNS update configuration which will update the IP address
+assigned to `<interface>` on the service you configured under `<service-name>`.
 
-Present your RNDC key to ddclient :
+.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> key <keyfile>
 
-.. code-block:: none
+File identified by `<keyfile>` containing the secret RNDC key shared with
+remote DNS server.
 
-  set key /config/dyndns/mydnsserver.rndc.key
+.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server>
 
-Set the DNS server IP/FQDN :
+Configure the DNS `<server>` IP/FQDN used when updating this dynamic assignemnt.
 
-.. code-block:: none
+.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone>
 
-  set server dns.mydomain.com
+Configure DNS `<zone>` to be updated.
 
-Set the NS zone to be updated :
-
-.. code-block:: none
+.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record>
 
-  set zone mydomain.com
+Configure DNS `<record>` which should be updated. This can be set multiple
+times.
 
-Set the records to be updated :
+.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl>
 
-.. code-block:: none
+Configure optional TTL value on the given resource record. This defualts to 600
+seconds.
 
-  set record dyn
-  set record dyn2
+Example
+^^^^^^^
 
-You can optionally set a TTL (note : default value is 600 seconds) :
+* 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
 
 .. code-block:: none
 
-  set ttl 600
+  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
+       }
+   }
 
-This will generate the following ddclient config blocks:
+This will render the following ddclient_ configuration entry:
 
 .. code-block:: none
 
-  server=dns.mydomain.com
-  protocol=nsupdate
-  password=/config/dyndns/mydnsserver.rndc.key
-  ttl=600
-  zone=mydomain.com
-  dyn
-  server=dns.mydomain.com
+  #
+  # 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/dyndns/mydnsserver.rndc.key
-  ttl=600
-  zone=mydomain.com
-  dyn2
+  password=/config/auth/my.key
+  ttl=300
+  zone=vyos.io
+  example.vyos.io
 
-You can also keep a different dns zone updated. Just create a new config node:
+.. 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>``
 
-.. code-block:: none
+HTTP based services
+-------------------
 
-  edit service dns dynamic interface eth0 rfc2136 <confignode2>
+VyOS is also able to use any service relying on protocols supported by ddclient.
 
-CLI and HTTP dynamic DNS services
-=================================
+To use such a service, one must define a login, password, one or multiple
+hostnames, protocol and server.
 
-VyOS is also able to use any service relying on protocols supported
-by ddclient.
+.. cfgcmd:: set service dns dynamic interface <interface> service <service> host-name <hostname>
 
-To use such a service, you must define a login, a password, one or multiple
-hostnames, a protocol and a server.
+Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS provider
+identified by `<service>` when the IP address on interface `<interface>`
+changes.
 
-.. code-block:: none
+.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username>
 
-  edit service dns dynamic interface eth0 service HeNet
-  set login my-login # set password my-password
-  set host-name my-tunnel-id
-  set protocol dyndns2
-  set server ipv4.tunnelbroker.net
+Configure `<username>` used when authenticating the update request for DynDNS
+service identified by `<service>`.
 
-VyOS is also shipped with a list of known services. You don't need to set the
-protocol and server value as VyOS has defaults provided for those. These are
-the services VyOS knows about:
+.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password>
 
-* afraid
-* changeip
-* dnspark
-* dslreports
-* dyndns
-* easydns
-* namecheap
-* noip
-* zoneedit
+Configure `<password>` used when authenticating the update request for DynDNS
+service identified by `<service>`.
 
-To use DynDNS for example:
+.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password>
 
-.. code-block:: none
+Configure `<password>` used when authenticating the update request for DynDNS
+service identified by `<service>`.
+
+.. cfgcmd:: set service dns dynamic interface <interface> service <service> protocol <protocol>
+
+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.
+
+.. cfgcmd:: set service dns dynamic interface <interface> service <service> server <server>
+
+When a ``custom`` DynDNS provider is used the `<server>` where update requests
+are beeing sent to must be specified.
 
-  edit service dns dynamic interface eth0 service dyndns
-  set login my-login
-  set password my-password
-  set host-name my-dyndns-hostname
+Example:
+^^^^^^^^
 
-It's possible to use multiple services :
+Use DynDNS as your preferred provider:
 
 .. code-block:: none
 
-  edit service dns dynamic interface eth0 service dyndns
-  set login my-login
-  set password my-password
-  set host-name my-dyndns-hostname
-  edit service dns dynamic interface eth0 service HeNet
-  set login my-login
-  set password my-password
-  set host-name my-tunnel-id
-  set protocol dyndns2
-  set server ipv4.tunnelbroker.net
-
-ddclient behind NAT
-===================
-
-By default, ddclient will update a dynamic dns record using the IP address
+  set service dns dynamic interface eth0 service dyndns
+  set service dns dynamic interface eth0 service dyndns login my-login
+  set service dns dynamic interface eth0 service dyndns password my-password
+  set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname
+
+.. note:: Multiple services can be used per interface. Just specify as many
+   serives per interface as you like!
+
+Running Behind NAT
+------------------
+
+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.
 
 ddclient_ has another way to determine the WAN IP address. This is controlled
-by these two options:
+by:
 
-.. code-block:: none
+.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url>
+
+Use configured `<url>` to determine your IP address. ddclient_ will load `<url>`
+and tries to extract your IP address from the response.
 
-  set service dns dynamic interface eth0 use-web url
-  set service dns dynamic interface eth0 use-web skip
+.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern>
 
-ddclient_ will load the webpage at `[url]` and will try to extract an IP
-address for the response. ddclient_ will skip any address located before the
-string set in `[skip]`.
+ddclient_ will skip any address located before the string set in `<pattern>`.
 
-.. include:: references.rst
+.. _ddclient: https://sourceforge.net/p/ddclient/wiki/Home/
diff --git a/docs/services/references.rst b/docs/services/references.rst
index 7d9ae82c..fc576eba 100644
--- a/docs/services/references.rst
+++ b/docs/services/references.rst
@@ -1,5 +1,4 @@
 .. _`Cisco Discovery Protocol`: https://en.wikipedia.org/wiki/Cisco_Discovery_Protocol
-.. _ddclient: https://sourceforge.net/p/ddclient/wiki/Home/
 .. _`Foundry Discovery Protocol`: https://en.wikipedia.org/wiki/Foundry_Discovery_Protocol
 .. _MIB: https://en.wikipedia.org/wiki/Management_information_base
 .. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol