diff options
| -rw-r--r-- | docs/services/dhcp.rst | 166 |
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 |