dns-forwarding: use new cfgcmd/opcmd syntax

1 files changed, 43 insertions, 55 deletions

diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst
index a431469e..707d7858 100644
--- a/docs/services/dns-forwarding.rst
+++ b/docs/services/dns-forwarding.rst
@@ -4,75 +4,63 @@
 DNS Forwarding
 ##############
 
-Use DNS forwarding if you want your router to function as a DNS server for the
-local network. There are several options, the easiest being 'forward all
-traffic to the system DNS server(s)' (defined with set system name-server):
+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.
 
-.. code-block:: none
-
-  set service dns forwarding system
-
-Manually setting DNS servers for forwarding:
-
-.. code-block:: none
+VyOS DNS forwarder doe 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.
 
-  set service dns forwarding name-server 8.8.8.8
-  set service dns forwarding name-server 8.8.4.4
+.. cfgcmd:: set service dns forwarding system
 
-Manually setting DNS servers with IPv6 connectivity:
+Forward incoming DNS queries to the DNS servers configured under the ``system
+name-server`` nodes.
 
-.. code-block:: none
+.. cfgcmd:: set service dns forwarding name-server <address>
 
-  set service dns forwarding name-server 2001:4860:4860::8888
-  set service dns forwarding name-server 2001:4860:4860::8844
+Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`.
+You can configure multiple nameservers here.
 
-Setting a forwarding DNS server for a specific domain:
+.. cfgcmd:: set service dns forwarding domain <domain-name> server <address>
 
-.. code-block:: none
+Forward received queries for a particular domain (specified via `domain-name`)
+to a given name-server. Multiple nameservers can be specified.
 
-  set service dns forwarding domain example.com server 192.0.2.1
+.. note:: This also works for reverse-lookup zones e.g. ``18.172.in-addr.arpa``.
 
-Set which networks or clients are allowed to query the DNS Server. Allow from all:
+.. cfgcmd:: set service dns forwarding allow-from <network>
 
-.. code-block:: none
+Given the fact that open DNS recursors could be used on DDOS amplification
+attacts, 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 on general a bad idea.
 
-  set service dns forwarding allow-from 0.0.0.0/0
+Example
+=======
 
-Examples
-========
+Router with two interfaces eth0 (WAN link) and eth1 (LAN) does want to make
+use of DNS split-horizon for example.com.
 
-Example 1
----------
-
-Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com.
-
-* DNS request for a local domain (example.com) get forwarded to 192.0.2.1
-* Other DNS requests are forwarded to Google's DNS servers.
-* The IP address for the LAN interface is 192.168.0.1.
+* DNS request for example.com need to get forwarded to IPv4 address 192.0.2.254
+  and IPv6 address 2001:db8:cafe::1
+* All other DNS requests are forwarded to DNS server listening on 192.0.2.1,
+  192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff
+* DNS server is listening on the LAN interface addresses only, 192.168.1.254
+  for IPv4 and 2001:db8::ffff for IPv6
+* Only clients from the LAN segment (192.168.1.0/24) are allowed to use this
+  server
 
 .. code-block:: none
 
-  set service dns forwarding domain example.com server 192.0.2.1
-  set service dns forwarding name-server 8.8.8.8
-  set service dns forwarding name-server 8.8.4.4
-  set service dns forwarding listen-address 192.168.0.1
-  set service dns forwarding allow-from 0.0.0.0/0
-
-Example 2
----------
-
-Same as example 1 but with additional IPv6 addresses for Google's public DNS
-servers.
-
-The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1
-
-.. code-block:: none
+  set service dns forwarding domain example.com server 192.0.2.254
+  set service dns forwarding domain example.com 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 2001:db8::1:ffff
+  set service dns forwarding name-server 2001:db8::2:ffff
+  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 domain example.com server 192.0.2.1
-  set service dns forwarding name-server 8.8.8.8
-  set service dns forwarding name-server 8.8.4.4
-  set service dns forwarding name-server 2001:4860:4860::8888
-  set service dns forwarding name-server 2001:4860:4860::8844
-  set service dns forwarding listen-address 2001:db8::1
-  set service dns forwarding listen-address 192.168.0.1
-  set service dns forwarding allow-from 0.0.0.0/0