vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1231 from sarthurdev/kea

Browse Source 
dhcp: T3316: Update documentation for Kea implementation
This commit is contained in:
Christian Breunig 2024-01-11 07:28:54 +01:00 committed by GitHub
commit 129e57debf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 41 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/configexamples/autotest/DHCPRelay_through_GRE/_include/dhcp-server.conf
View File

@ -8,6 +8,7 @@ set protocols static route 10.0.10.0/24 next-hop 10.0.20.254
set protocols static route 192.168.0.0/24 next-hop 127.16.0.2
set service dhcp-server listen-address '172.16.0.1'
set service dhcp-server shared-network-name DHCPTun100 authoritative
set service dhcp-server shared-network-name DHCPTun100 subnet 192.168.0.0/24 default-router '192.168.0.254'
set service dhcp-server shared-network-name DHCPTun100 subnet 192.168.0.0/24 option default-router '192.168.0.254'
set service dhcp-server shared-network-name DHCPTun100 subnet 192.168.0.0/24 range 0 start '192.168.0.30'
set service dhcp-server shared-network-name DHCPTun100 subnet 192.168.0.0/24 range 0 stop '192.168.0.30'
set service dhcp-server shared-network-name DHCPTun100 subnet 192.168.0.0/24 range 0 stop '192.168.0.30'
set service dhcp-server shared-network-name DHCPTun100 subnet 192.168.0.0/24 subnet-id '1'

148
docs/configuration/service/dhcp-server.rst
View File

@ -4,7 +4,7 @@
DHCP Server
###########
VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment.
VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment.
***********
IPv4 server
@ -26,12 +26,7 @@ Configuration
Create DNS record per client lease, by adding clients to /etc/hosts file.
Entry will have format: `<shared-network-name>_<hostname>.<domain-name>`
.. cfgcmd:: set service dhcp-server host-decl-name
Will drop `<shared-network-name>_` from client DNS record, using only the
host declaration name and domain: `<hostname>.<domain-name>`
.. cfgcmd:: set service dhcp-server shared-network-name <name> domain-name <domain-name>
.. cfgcmd:: set service dhcp-server shared-network-name <name> option 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
@ -40,7 +35,7 @@ Configuration
This is the configuration parameter for the entire shared network definition.
All subnets will inherit this configuration item if not specified locally.
.. cfgcmd:: set service dhcp-server shared-network-name <name> domain-search <domain-name>
.. cfgcmd:: set service dhcp-server shared-network-name <name> option 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
@ -49,7 +44,7 @@ Configuration
This is the configuration parameter for the entire shared network definition.
All subnets will inherit this configuration item if not specified locally.
.. cfgcmd:: set service dhcp-server shared-network-name <name> name-server <address>
.. cfgcmd:: set service dhcp-server shared-network-name <name> option name-server <address>
Inform client that the DNS server can be found at `<address>`.
@ -58,21 +53,6 @@ Configuration
Multiple DNS servers can be defined.
.. cfgcmd:: set service dhcp-server shared-network-name <name> ping-check
When the DHCP server is considering dynamically allocating an IP address to a
client, it first sends an ICMP Echo request (a ping) to the address being
assigned. It waits for a second, and if no ICMP Echo response has been heard,
it assigns the address.
If a response is heard, the lease is abandoned, and the server does not
respond to the client. The lease will remain abandoned for a minimum of
abandon-lease-time seconds (defaults to 24 hours).
If there are no free addresses but there are abandoned IP addresses, the
DHCP server will attempt to reclaim an abandoned IP address regardless of the
value of abandon-lease-time.
.. cfgcmd:: set service dhcp-server listen-address <address>
This configuration parameter lets the DHCP server to listen for DHCP
@ -91,14 +71,20 @@ Individual Client Subnet
network.
.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
default-router <address>
subnet-id <id>
This configuration parameter is required and must be unique to each subnet.
It is required to map subnets to lease file entries.
.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
option default-router <address>
This is a configuration parameter for the `<subnet>`, saying that as part of
the response, tell the client that the default gateway can be reached at
`<address>`.
.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
name-server <address>
option name-server <address>
This is a configuration parameter for the subnet, saying that as part of the
response, tell the client that the DNS server can be found at `<address>`.
@ -133,40 +119,19 @@ Individual Client Subnet
This option can be specified multiple times.
.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
domain-name <domain-name>
option 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 <name> subnet <subnet>
domain-search <domain-name>
option 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
if you need multiple search domains (DHCP Option 119).
.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
ping-check
When the DHCP server is considering dynamically allocating an IP address to a
client, it first sends an ICMP Echo request (a ping) to the address being
assigned. It waits for a second, and if no ICMP Echo response has been heard,
it assigns the address.
If a response is heard, the lease is abandoned, and the server does not
respond to the client. The lease will remain abandoned for a minimum of
abandon-lease-time seconds (defaults to 24 hours).
If a there are no free addresses but there are abandoned IP addresses, the
DHCP server will attempt to reclaim an abandoned IP address regardless of the
value of abandon-lease-time.
.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
enable-failover
Enable DHCP failover configuration for this address pool.
Failover
--------
@ -238,6 +203,7 @@ inside the subnet definition but can be outside of the range statement.
.. code-block:: none
set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1
set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100
set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac-address aa:bb:11:22:33:00
@ -251,6 +217,7 @@ The configuration will look as follows:
ip-address 192.168.1.100
mac-address aa:bb:11:22:33:00
}
subnet-id 1
}
Options
@ -391,32 +358,6 @@ Options
Multi: can be specified multiple times.
Raw Parameters
==============
Raw parameters can be passed to shared-network-name, subnet and static-mapping:
.. code-block:: none
set service dhcp-server shared-network-name <name> shared-network-parameters
<text> Additional shared-network parameters for DHCP server.
set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters
<text> Additional subnet parameters for DHCP server.
set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters
<text> Additional static-mapping parameters for DHCP server.
Will be placed inside the "host" block of the mapping.
These parameters are passed as-is to isc-dhcp's dhcpd.conf under the
configuration node they are defined in. They are not validated so an error in
the raw parameters won't be caught by vyos's scripts and will cause dhcpd to
fail to start. Always verify that the parameters are correct before committing
the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information:
https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf
Quotes can be used inside parameter values by replacing all quote characters
with the string ``&quot;``. They will be replaced with literal quote characters
when generating dhcpd.conf.
Example
=======
@ -439,12 +380,12 @@ Common configuration, valid for both primary and secondary node.
.. code-block:: none
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 name-server '192.0.2.254'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250'
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 enable-failover
set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1'
**Primary**
@ -467,47 +408,6 @@ Common configuration, valid for both primary and secondary node.
.. _dhcp-server:v4_example_raw:
Raw Parameters
--------------
* Override static-mapping's name-server with a custom one that will be sent only
to this host.
* An option that takes a quoted string is set by replacing all quote characters
with the string ``&quot;`` inside the static-mapping-parameters value.
The resulting line in dhcpd.conf will be
``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``.
.. code-block:: none
set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;"
set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile &quot;pxelinux.cfg/01-00-15-17-44-2d-aa&quot;;"
Option 43 for UniFI
-------------------
* These parameters need to be part of the DHCP global options.
They stay unchanged.
.. code-block:: none
set service dhcp-server global-parameters 'option space ubnt;'
set service dhcp-server global-parameters 'option ubnt.unifi-address code 1 = ip-address;'
set service dhcp-server global-parameters 'class &quot;ubnt&quot; {'
set service dhcp-server global-parameters 'match if substring (option vendor-class-identifier, 0, 4) = &quot;ubnt&quot;;'
set service dhcp-server global-parameters 'option vendor-class-identifier &quot;ubnt&quot;;'
set service dhcp-server global-parameters 'vendor-option-space ubnt;'
set service dhcp-server global-parameters '}'
* Now we add the option to the scope, adapt to your setup
.. code-block:: none
set service dhcp-server shared-network-name example-scope subnet 10.1.1.0/24 subnet-parameters 'option ubnt.unifi-address 172.16.1.10;'
Operation Mode
==============
@ -614,6 +514,12 @@ Configuration
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 <subnet>
subnet-id <id>
This configuration parameter is required and must be unique to each subnet.
It is required to map subnets to lease file entries.
.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
<prefix> lease-time {default | maximum | minimum}
@ -690,6 +596,7 @@ server. The following example describes a common scenario.
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
set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1
The configuration will look as follows:
@ -704,6 +611,7 @@ The configuration will look as follows:
}
}
name-server 2001:db8::ffff
subnet-id 1
}
}

9
docs/installation/install.rst
View File

@ -458,13 +458,16 @@ In this example we configured an existent VyOS as the DHCP server:
vyos@vyos# show service dhcp-server
shared-network-name mydhcp {
subnet 192.168.1.0/24 {
bootfile-name pxelinux.0
bootfile-server 192.168.1.50
default-router 192.168.1.50
option {
bootfile-name pxelinux.0
bootfile-server 192.168.1.50
default-router 192.168.1.50
}
range 0 {
start 192.168.1.70
stop 192.168.1.100
}
subnet-id 1
}
}

7
docs/quick-start.rst
View File

@ -93,12 +93,13 @@ DNS server.
.. code-block:: none
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 name-server '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'vyos.net'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option default-router '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option name-server '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option domain-name 'vyos.net'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start '192.168.0.9'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 subnet-id '1'
set service dns forwarding cache-size '0'
set service dns forwarding listen-address '192.168.0.1'