From: Tomek Mrugalski Date: Wed, 29 Jun 2016 11:43:21 +0000 (+0200) Subject: [4518] Documentation for DHCPv6 reservations updated. X-Git-Tag: trac4551_base~31^2~5 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=6f4e9166ad626809bc15310540512739393a42f9;p=thirdparty%2Fkea.git [4518] Documentation for DHCPv6 reservations updated. --- diff --git a/doc/examples/kea4/reservations.json b/doc/examples/kea4/reservations.json index 9b6cfbf941..415ef1b250 100644 --- a/doc/examples/kea4/reservations.json +++ b/doc/examples/kea4/reservations.json @@ -31,7 +31,7 @@ # "rebind-timer": 2000, -# Kea supports several reservations by several different types of identifiers: +# Kea supports reservations by several different types of identifiers: # hw-address (hardware/MAC address of the client), duid (DUID inserted by the # client), client-id (client identifier inserted by the client) and circuit-id # (circuit identifier inserted by the relay agent). When told to do so, Kea can diff --git a/doc/examples/kea6/reservations.json b/doc/examples/kea6/reservations.json index 6162fc1730..275b0a9b41 100644 --- a/doc/examples/kea6/reservations.json +++ b/doc/examples/kea6/reservations.json @@ -25,6 +25,13 @@ "renew-timer": 1000, "rebind-timer": 2000, +# Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address +# of the client) and duid (DUID inserted by the client). When told to do so, Kea can +# check for each of those identifier types, but it takes a costly database lookup +# to do so. It is therefore useful from performance perspective to use only +# that reservation types that are actually used in a given network. + "host-reservation-identifiers": [ "duid", "hw-address" ], + # The following list defines subnets. Subnet, pools and interface definitions # are the same as in the regular scenario, without host reservations. # least subnet and pool entries. @@ -58,13 +65,26 @@ }, # This is similar to the previous one, but this time the reservation is done # based on hardware/MAC address. The server will do its best to extract -# the hardware/MAC address from received packets. +# the hardware/MAC address from received packets (see 'mac-sources' directive +# for details). This particular reservation also specifies two extra options +# to be available for this client. If there are options with the same code +# specified in global, subnet or class scope, the values defined at host level +# takes precedence. { "hw-address": "00:01:02:03:04:05", - "ip-addresses": [ "2001:db8:1::101" ] + "ip-addresses": [ "2001:db8:1::101" ], + "option-data": [ + { + "name": "dns-servers", + "data": "3000:1::234" + }, + { + "name": "nis-servers", + "data": "3000:1::234" + }] }, -# This is a bit more advanced configuration. The client with specified -# DUID will get a reserved address, prefix and a hostname. +# This is a bit more advanced reservation. The client with specified +# DUID will get a reserved address, a reserved prefix and a hostname. { "duid": "01:02:03:04:05:06:07:08:09:0A", "ip-addresses": [ "2001:db8:1::102" ], diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index beea6e910d..7e9f792638 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2501,7 +2501,7 @@ It is merely echoed by the server Note that the above example is used for ilustrational purposes only and in actual deployments it is recommended to use as few types as possible - (preferably just one). See for detailed + (preferably just one). See for detailed discussion. Making a reservation for a mobile host that may visit multiple subnets @@ -2734,7 +2734,7 @@ It is merely echoed by the server -
+
Fine Tuning IPv4 Host Reservation Host reservation capability introduces additional restrictions for the diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index aad1159738..6d7e46d74a 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2419,21 +2419,65 @@ should include options from the isc option space:
Reserving specific options - - Currently it is not possible to specify options in host - reservation. Such a feature will be added in the upcoming Kea - releases. + + Kea 1.1.0 introduced the ability to specify options on a + per host basis. The options follow the same rules as any other + options. These can be standard options (see ), custom options (see ) or vendor specific options + (see ). The following + example showcases how standard options can be defined. + + +"reservations": [ +{ + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "192.0.2.1", + "option-data": [ + { + "duid": "01:02:03:05:06:07:08", + "ip-addresses": [ "2001:db8:1::2" ], + "option-data": [ { + "name": "dns-servers", + "data": "3000:1::234" + }, + { + "name": "nis-servers", + "data": "3000:1::234" + } + } ] +} ] + + Vendor specific options can be reserved in similar manner: + + +"reservations": [ +{ + "duid": "aa:bb:cc:dd:ee:ff", + "ip-addresses": [ "2001:db8::1" ], + "option-data": [ + { + "name": "vendor-opts", + "data": 4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "3000:1::234" + } ] +} ] + + + Options defined on host level have the highest priority. In other words, + if there are option defined with the same type on global, subnet, class and + host level, the host specific values will be used. + +
-
+
Fine Tuning IPv6 Host Reservation - - reservation-mode in the DHCPv6 server is - implemented in Kea 0.9.1 beta, but has not been tested and is - considered experimental. - - Host reservation capability introduces additional restrictions for the allocation engine during lease selection and renewal. In particular, three major checks are necessary. First, when selecting a new lease, it is not @@ -2493,6 +2537,47 @@ should include options from the isc option space: } + + Another aspect of the host reservations are different types of + identifiers. Currently (June 2016) Kea supports two types of identifiers + in DHCPv6: hw-address and duid, but more identifier types + are likely to be added in the future. This is beneficial from the + usability perspective. However, there is a drawback. For each incoming + packet Kea has to to extract each identifier type and then query the + database to see if there's a reservation done by this particular + identifier. If there is not, the next identifier is extracted and next + query is issued. This process continues until either a reservation is + found or all identifier types were checked. Over time with increasing + number of supported identifier types, Kea would become slower and + slower. + + To address this problem, a parameter called + host-reservation-identifiers has been introduced. It + takes a list of identifier types as a parameter. Kea will check only those + identifier types enumerated in host-reservation-identifiers. From the + performance perspective the number of identifier types should be kept to + minimum, ideally limited to one. If your deployment uses several + reservation types, please enumerate them from most to least frequently + used as this increases the chances of Kea finding the reservation using + fewer number of queries. An example of host reservation identifiers looks + as follows: + + +"host-reservation-identifiers": [ "duid", "hw-address" ], +"subnet4": [ + { + "subnet": "192.0.2.0/24", + ... + } +] + + + + If not specified, the default value is hw-address,duid. + + +