From c3f093e58cae6c7818b9273eaa29bf12011ee3fe Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Tue, 26 Nov 2019 20:41:21 +0100 Subject: dhcp: use documentations prefixes as per RFC --- docs/services/dhcp.rst | 166 ++++++++++++++++++++++++++++--------------------- 1 file 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 ````. 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 '' + 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 '' + 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 '' 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 '' 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 '' 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 '' 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 '' 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 '' 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 ip-address 172.16.17.10 +.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 static-mapping 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 mac-address ff:ff:ff:ff:ff:ff +.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 static-mapping 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 '
' +.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 default-router '
' 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 '
' +.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 dns-server '
' 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 '' +.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 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 '' +.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 domain-search '' 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 subnet lease-time {default | maximum | minimum } +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' 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 subnet nis-domain +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nis-domain '' A :abbr:`NIS (Network Information Service)` domain can be set to be used for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name subnet nisplus-domain +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nisplus-domain '' 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 subnet nis-server +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nis-server '
' Specify a NIS server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name subnet nisplus-server +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nisplus-server '
' Specify a NIS+ server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name subnet sip-server-address +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' sip-server-address '
' Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name subnet sip-server-name +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' sip-server-name '' Specify a :abbr:`SIP (Session Initiation Protocol)` server by FQDN for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name subnet sntp-server-address +.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' sntp-server-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 -- cgit v1.2.3