dhcp: use documentations prefixes as per RFC

1 files changed, 96 insertions, 70 deletions

diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst
index 083003a4..eb343fb1 100644
--- a/docs/services/dhcp.rst
+++ b/docs/services/dhcp.rst
@@ -15,65 +15,83 @@ identified by a ``shared-network-name``.
 Basic Example
 -------------
 
-We are offering address space in the 172.16.17.0/24 network, which is
+We are offering address space in the 192.0.2.0/24 network, which is
 physically connected on eth1, and pppoe0 is our connection to the internet.
-We are using the network name `dhcpexample`.
+We are using the network name ``<name>``.
 
 Prerequisites:
 
 * Configuring PPPoE interface is assumed to be done already, and appears
   on `pppoe0`
 * Interface ``eth1`` is configured to be connected to our DHCP subnet
-  172.16.17.0/24 by assigning e.g. address 172.16.17.1/24.
+  192.0.2.0/24 by assigning e.g. address 192.0.2.1/24.
 
 Multiple DHCP ranges can be defined and may contain holes.
 
 .. code-block:: sh
 
-  set service dhcp-server shared-network-name dhcpexample authoritative
-  set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1
-  set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1
-  set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400
-  set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100
-  set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199
+  edit service dhcp-server shared-network-name '<name>'
+  set authoritative
+  set subnet 192.0.2.0/24 default-router 192.0.2.1
+  set subnet 192.0.2.0/24 dns-server 192.0.2.1
+  set subnet 192.0.2.0/24 lease 86400
+  set subnet 192.0.2.0/24 range 0 start 192.0.2.100
+  set subnet 192.0.2.0/24 range 0 stop 192.0.2.199
+  exit
+
+The generated config will look like:
+
+.. code-block:: sh
+
+  vyos@vyos# show service dhcp-server shared-network-name '<name>'
+  authoritative
+  subnet 192.0.2.0/24 {
+      default-router 192.0.2.1
+      dns-server 192.0.2.1
+      lease 86400
+      range 0 {
+          start 192.0.2.100
+          stop 192.0.2.199
+      }
+  }
 
 
 Explanation
 ^^^^^^^^^^^
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample authoritative
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' authoritative
 
-  This says that this device is the only DHCP server for this network. If other
-  devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to
-  any device trying to request an IP address that is
-  not valid for this network.
+This says that this device is the only DHCP server for this network. If other
+devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to
+any device trying to request an IP address that is
+not valid for this network.
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 default-router 192.0.2.1
 
-  This is a configuration parameter for the subnet, saying that as part of the
-  response, tell the client that I am the default router for this network
+This is a configuration parameter for the subnet, saying that as part of the
+response, tell the client that I am the default router for this network
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server 192.0.2.1
 
-  This is a configuration parameter for the subnet, saying that as part of the
-  response, tell the client that I am the DNS server for this network. If you
-  do not want to run a DNS server, you could also provide one of the public
-  DNS servers, such as google's. You can add multiple entries by repeating the
-  line.
+This is a configuration parameter for the subnet, saying that as part of the
+response, tell the client that I am the DNS server for this network. If you
+do not want to run a DNS server, you could also provide one of the public
+DNS servers, such as google's. You can add multiple entries by repeating the
+line.
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 lease 86400
 
-  Assign the IP address to this machine for 24 hours. It is unlikely you'd need
-  to shorten this period, unless you are running a network with lots of devices
-  appearing and disappearing.
+Assign the IP address to this machine for 24 hours. It is unlikely you'd need
+to shorten this period, unless you are running a network with lots of devices
+appearing and disappearing.
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 start 192.0.2.100
 
-  Make a range of addresses available for clients starting from .100 [...]
+Make a range of addresses available for clients starting from .100 [...]
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 stop 192.0.2.199
 
-  [...] and ending at .199
+[...] and ending at .199
 
 
 Failover
@@ -83,9 +101,12 @@ VyOS provides support for DHCP failover:
 
 .. code-block:: sh
 
-  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover local-address '192.168.0.1'
-  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover name 'foo'
-  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover peer-address '192.168.0.2'
+  set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' \
+      failover local-address '192.0.2.1'
+  set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' \
+      failover name 'foo'
+  set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' \
+      failover peer-address '192.0.2.2'
 
 .. note:: `name` must be identical on both sides!
 
@@ -94,13 +115,15 @@ primary or secondary
 
 .. code-block:: sh
 
-  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary'
+  set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' \
+      failover status 'primary'
 
 or
 
 .. code-block:: sh
 
-  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary'
+  set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' \
+      failover status 'secondary'
 
 .. note:: In order for the primary and the secondary DHCP server to keep
    their lease tables in sync, they must be able to reach each other on TCP
@@ -114,11 +137,11 @@ MAC address of the station and your desired IP address. The address must be
 inside your subnet definition but can be outside of your range sttement.
 
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping <host> ip-address 172.16.17.10
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 static-mapping <host> ip-address 192.0.2.10
 
 Configure desired IPv4 address for your host referenced to as `host`.
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping <hodt> mac-address ff:ff:ff:ff:ff:ff
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 static-mapping <hodt> mac-address ff:ff:ff:ff:ff:ff
 
 Configure MAC address for your host referenced by as `host` used in this static
 assignment.
@@ -126,23 +149,23 @@ assignment.
 DHCP Options
 ------------
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router '<address>'
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 default-router '<address>'
 
 Specify the default routers IPv4 address which should be used in this subnet.
 This can - of course - be a VRRP address (DHCP option 003).
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server '<address>'
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server '<address>'
 
 Specify the DNS nameservers used (Option 006). This option may be used mulltiple
 times to specify additional DNS nameservers.
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-name '<domain-name>'
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 domain-name '<domain-name>'
 
 The domain-name parameter should be the domain name that will be appended to
 the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP
 Option 015).
 
-.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search '<domain-name>'
+.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 domain-search '<domain-name>'
 
 The domain-name parameter should be the domain name used when completing DNS
 request where no full FQDN is passed. This option can be given multiple times
@@ -164,41 +187,41 @@ Clients receiving advertise messages from multiple servers choose the server
 with the highest preference value. The range for this value is ``0...255``.
 
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default <default-time> | maximum <maximum-time> | minimum <minimum-time>}
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' lease-time {default | maximum | minimum}
 
 The default lease time for DHCPv6 leases is 24 hours. This can be changed by
 supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All values
 need to be supplied in seconds.
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nis-domain '<domain-name>'
 
 A :abbr:`NIS (Network Information Service)` domain can be set to be used for
 DHCPv6 clients.
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nisplus-domain '<domain-name>'
 
 The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)`
 domain is similar to the NIS domain one:
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server <IPv6 address>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nis-server '<address>'
 
 Specify a NIS server address for DHCPv6 clients.
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-server <IPv6 address>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nisplus-server '<address>'
 
 Specify a NIS+ server address for DHCPv6 clients.
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address <IPv6 address>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' sip-server-address '<address>'
 
 Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address for
 all DHCPv6 clients.
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-name <sip-server-name>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' sip-server-name '<fqdn>'
 
 Specify a :abbr:`SIP (Session Initiation Protocol)` server by FQDN for all
 DHCPv6 clients.
 
-.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sntp-server-address <IPv6 address>
+.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' sntp-server-address '<address>'
 
 A SNTP server address can be specified for DHCPv6 clients:
 
@@ -210,16 +233,18 @@ server. The following example describes a common scenario.
 
 **Example:**
 
-* A shared network named ``NET1`` serves subnet ``2001:db8:100::/64``
+* A shared network named ``NET1`` serves subnet ``2001:db8::/64``
 * It is connected to ``eth1``
-* DNS server is located at ``2001:db8:111::111``
-* Address pool shall be ``2001:db8:100::100`` through ``2001:db8:100::199``.
+* DNS server is located at ``2001:db8::ffff``
+* Address pool shall be ``2001:db8::100`` through ``2001:db8::199``.
 * Lease time will be left at the default value which is 24 hours
 
 .. code-block:: sh
 
-  set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 address-range start 2001:db8:100::100 stop 2001:db8:100::199
-  set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 name-server 2001:db8:111::111
+  set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 \
+      address-range start 2001:db8::100 stop 2001:db8::199
+  set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 \
+      name-server 2001:db8::ffff
 
 The configuration will look as follows:
 
@@ -227,13 +252,13 @@ The configuration will look as follows:
 
   show service dhcpv6-server
       shared-network-name NET1 {
-          subnet 2001:db8:100::/64 {
+          subnet 2001:db8::/64 {
              address-range {
-                start 2001:db8:100::100 {
-                   stop 2001:db8:100::199
+                start 2001:db8::100 {
+                   stop 2001:db8::199
                 }
              }
-             name-server 2001:db8:111::111
+             name-server 2001:db8::ffff
           }
       }
 
@@ -245,7 +270,7 @@ be created. The following example explains the process.
 
 **Example:**
 
-* IPv6 address ``2001:db8:100::101`` shall be statically mapped
+* IPv6 address ``2001:db8::101`` shall be statically mapped
 * Device MAC address will be ``00:53:c5:b7:5e:23``
 * Host specific mapping shall be named ``client1``
 
@@ -254,8 +279,10 @@ be created. The following example explains the process.
 
 .. code-block:: sh
 
-  set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 ipv6-address 2001:db8:100::101
-  set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 identifier c5b75e23
+  set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 \
+      static-mapping client1 ipv6-address 2001:db8::101
+  set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 \
+      static-mapping client1 identifier c5b75e23
 
 The configuration will look as follows:
 
@@ -263,15 +290,15 @@ The configuration will look as follows:
 
   show service dhcp-server shared-network-name NET1
      shared-network-name NET1 {
-         subnet 2001:db8:100::/64 {
+         subnet 2001:db8::/64 {
             name-server 2001:db8:111::111
             address-range {
-                start 2001:db8:100::100 {
-                   stop 2001:db8:100::199 {
+                start 2001:db8::100 {
+                   stop 2001:db8::199 {
                 }
             }
             static-mapping client1 {
-               ipv6-address 2001:db8:100::101
+               ipv6-address 2001:db8::101
                identifier c5b75e23
             }
          }
@@ -395,18 +422,17 @@ Configuration
 
 Set eth1 to be the listening interface for the DHCPv6 relay:
 
-.. cfgcmd:: set service dhcpv6-relay upstream-interface eth2 address 2001:db8:100::4
+.. cfgcmd:: set service dhcpv6-relay upstream-interface eth2 address 2001:db8::4
 
 Set eth2 to be the upstream interface and specify the IPv6 address of
 the DHCPv6 server:
 
-
 Example
 ^^^^^^^
 
 * DHCPv6 requests are received by the router on `listening interface` ``eth1``
 * Requests are forwarded through ``eth2`` as the `upstream interface`
-* External DHCPv6 server is at 2001:db8:100::4
+* External DHCPv6 server is at 2001:db8::4
 
 .. figure:: /_static/images/service_dhcpv6-relay01.png
    :scale: 80 %
@@ -423,7 +449,7 @@ The generated configuration will look like:
       listen-interface eth1 {
       }
       upstream-interface eth2 {
-         address 2001:db8:100::4
+         address 2001:db8::4
       }
 
 Options