From: Marcin Siodelski Date: Sat, 14 Feb 2015 20:32:31 +0000 (+0100) Subject: [3575] A couple of corrections in the user guide for the host reservations. X-Git-Tag: trac3723_base~35^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9ac4323c4682ffebe7b3f493d702bc80ece4de30;p=thirdparty%2Fkea.git [3575] A couple of corrections in the user guide for the host reservations. --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 3fabb61771..e640cdc693 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1736,23 +1736,30 @@ temporarily override a list of interface names and listen on all interfaces. There are many cases where it is useful to provide a configuration on a per host basis. The most obvious one is to reserve specific, static - address for exclusive use by a given client ‐ returning client will get - the same address every time and other clients will never get that - address. Other example may be a host that has specific requirements, e.g. a - printer that needs additional options. Yes another possible use case for - host reservation is to define unique host names for hosts. Although not all - of those scenarios are possible yet, Kea software will support them in the + address for exclusive use by a given client (host) ‐ returning client will + receive the same address from the server every time, and other clients will + generally not receive that address. Note that there may be cases when the + new reservation has been made for the client for the address being currently + in use by another client. We call this situation a "conflict". The conflicts + get resolved automatically over time as described in the subsequent sections. + Once conflict is resolved,the client will keep receiving the reserved + configuration when it renews. + + Another example when the host reservations are applicable is when a host + that has specific requirements, e.g. a printer that needs additional DHCP options. + Yet another possible use case is to define unique names for hosts. Although not all + of the presented use cases are implemented yet, Kea software will support them in the near future. - Hosts are defined as parameters for each subnet. Each host has to be - identified by its hardware/MAC address. There is an optional + Hosts reservations are defined as parameters for each subnet. Each host + has to be identified by its hardware/MAC address. There is an optional reservations array in the Subnet4 element. Each element in that array is a structure, that holds information - about a single host. In particular, such a structure has to have an - indentifer that uniquely identifies a host. In DHCPv4 context, such an + about reservrations for a single host. In particular, such a structure has + to have an indentifer that uniquely identifies a host. In DHCPv4 context, such an identifier is a hardware or MAC address. In most cases, also an address will be specified. It is possible to specify a hostname. Additional - capabilities are planed. + capabilities are planned. The following example shows how to reserve addresses for specific hosts: @@ -1779,7 +1786,7 @@ temporarily override a list of interface names and listen on all interfaces. The first entry reserves the 192.0.2.202 address for the client that uses MAC adress of 1a:1b:1c:1d:1e:1f. The second entry reserves the address - 192.0.2.100 address and a hostname of alice-laptop for client with MAC + 192.0.2.100 and the hostname of alice-laptop for client using MAC address 0a:0b:0c:0d:0e:0f. Note that if you plan to do DNS updates, it is strongly recommended for the hostnames to be unique. @@ -1803,13 +1810,13 @@ temporarily override a list of interface names and listen on all interfaces.
Address reservation types - In a typical scenario there's an IPv4 subnet defined, - e.g. 192.0.2.0/24 with certain part of it dedicated for dynamic allocation + In a typical scenario there is an IPv4 subnet defined, + e.g. 192.0.2.0/24, with certain part of it dedicated for dynamic allocation by the DHCPv4 server. That dynamic part is referred to as a dynamic pool or - simply a pool. In principle the host reservation can reserve any address - that belongs to the subnet. The reservations that specify an address that + simply a pool. In principle, the host reservation can reserve any address + that belongs to the subnet. The reservations that specify addresses that belong to configured pools are called in-pool reservations. - In contract, those that do not belong to dynamic pools are called + In contrast, those that do not belong to dynamic pools are called out-of-pool reservations. There is no formal difference in the reservation syntax. As of 0.9.1, both reservation types are handled uniformly. However, upcoming releases may offer improved performance @@ -1819,19 +1826,19 @@ temporarily override a list of interface names and listen on all interfaces. possible.
-
+
Conflicts in DHCPv4 reservations - As reservations and lease information are kept separately, - conflict may arrise. Consider the following series of events. The server - has configured 192.0.2.10 to 192.0.2.20 dynamic pool range. Host A - requests an address and gets 19.0.2.10. Now the system administrator - decides to reserve an address for host B. He decides to reserve 192.0.2.10 - for that purpose. In general, reserving an address that is currently - assigned to someone else is not recommended, but there are valid use - cases where such an operation is warranted. + As reservations and lease information are stored separately, + conflicts may arrise. Consider the following series of events. The server + has configured dynamic pool of addresses from the range of 192.0.2.10 to + 192.0.2.20. Host A requests an address and gets 19.0.2.10. Now the system + administrator decides to reserve an address for host B. He decides to + reserve 192.0.2.10 for that purpose. In general, reserving an address that + is currently assigned to someone else is not recommended, but there are + valid use cases where such an operation is warranted. The server now has a conflict to resolve. Let's analyze the - situation here. If host B boots up and request an address, the server is + situation here. If the host B boots up and requests an address, the server is not able to assign the reserved address 192.0.2.10. A naive approach would to be immediately remove the lease for host A and create a new one for host B. That would not solve the problem, though, because as soon as host diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 88b84c8bde..39d03c6d3f 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -1719,16 +1719,23 @@ should include options from the isc option space: There are many cases where it is useful to provide a configuration on a per host basis. The most obvious one is to reserve specific, static IPv6 - address or prefix for exclusive use by a given client ‐ returning - client will get the same address or prefix every time and other clients will - never get that address. Other example may be a host that has specific - requirements, e.g. a printer that needs additional options or a cable modem - need specific parameter. Yes another possible use case for host reservation - is to define unique host names for hosts. Although not all of those - scenarios are possible yet, Kea software will support them in the near - future. - - Hosts are defined as parameters for each subnet. Each host + address or/and prefix for exclusive use by a given client (host) ‐ returning + client will get the same address or/and prefix every time and other clients will + never get that address. Note that there may be cases when the + new reservation has been made for the client for the address or prefix being + currently in use by another client. We call this situation a "conflict". The + conflicts get resolved automatically over time as described in the subsequent + sections. Once conflict is resolved, the client will keep receiving the reserved + configuration when it renews. + + Another example when the host reservations are applicable is when a host + that has specific requirements, e.g. a printer that needs additional DHCP options + or a cable modem needs specific parameters. Yet another possible use case for + host reservation is to define unique names for hosts. Although not all of + the presented use cases are are implemented yet, Kea software will support them + in the near future. + + Hosts reservations are defined as parameters for each subnet. Each host can be identified by either DUID or its hardware/MAC address. See for details. There is an optional reservations array in the @@ -1738,7 +1745,7 @@ should include options from the isc option space: uniquely identifies a host. In DHCPv6 context, such an identifier is a hardware (MAC) address or a DUID. Also, either one or more addresses or prefixes should be specified. It is possible to - specify a hostname. Additional capabilities are planed. + specify a hostname. Additional capabilities are planned. The following example shows how to reserve addresses and prefixes for specific hosts: @@ -1784,7 +1791,7 @@ should include options from the isc option space: Note that DHCPv6 allows for a single client to lease multiple addresses and multiple prefixes at the same time. In the upcoming Kea releases, it will be possible to have multiple addresses and prefixes reserved for a single - host. Therefore ip-addresses" and prefixes + host. Therefore ip-addresses and prefixes are plural and are actually arrays. As of 0.9.1 having more than one IPv6 address or prefix is only partially supported. @@ -1810,11 +1817,11 @@ should include options from the isc option space: In a typical scenario there's an IPv6 subnet defined with a certain part of it dedicated for dynamic address allocation by the DHCPv6 server. There may be an additional address space defined for prefix - delegation. Those dynamic parts is referred to as dynamic pools, address - and prefix pools or simply pools. In principle the host reservation can + delegation. Those dynamic parts are referred to as dynamic pools, address + and prefix pools or simply pools. In principle, the host reservation can reserve any address or prefix that belongs to the subnet. The reservations - that specify an address that belong to configured pools are called - in-pool reservations. In contract, those that do not + that specify an address that belongs to configured pools are called + in-pool reservations. In contrast, those that do not belong to dynamic pools are called out-of-pool reservations. There is no formal difference in the reservation syntax. As of 0.9.1, both reservation types are handled @@ -1825,16 +1832,16 @@ should include options from the isc option space: possible.
-
+
Conflicts in DHCPv6 reservations - As reservations and lease information are kept in different places, - conflict may arrise. Consider the following series of events. The server - has configured 2001:db8::10 to 2001:db8::20 dynamic pool range. Host A - requests an address and gets 2001:db8::10. Now the system administrator - decides to reserve an address for host B. He decides to reserve 2001:db8::10 - for that purpose. In general, reserving an address that is currently - assigned to someone else is not recommended, but there are valid use - cases where such an operation is warranted. + As reservations and lease information are stored in different places, + conflicts may arrise. Consider the following series of events. The server + has configured the dynamic pool of addresses from the range of 2001:db8::10 + to 2001:db8::20. Host A requests an address and gets 2001:db8::10. Now the + system administrator decides to reserve an address for host B. He decides + to reserve 2001:db8::10 for that purpose. In general, reserving an address + that is currently assigned to someone else is not recommended, but there + are valid use cases where such an operation is warranted. The server now has a conflict to resolve. Let's analyze the situation here. If host B boots up and request an address, the server is @@ -1843,8 +1850,8 @@ should include options from the isc option space: for host B. That would not solve the problem, though, because as soon as host B get the address, it will detect that the address is already in use by someone else (host A) and would send Decline. Therefore in this - situation, the server has to temporarily assign a different address (not - matching what has been reserved) to host B. + situation, the server has to temporarily assign a different address from the + dynamic pool (not matching what has been reserved) to host B. When the host A renews its address, the server will discover that the address being renewed is now reserved for someone else (host @@ -1852,12 +1859,13 @@ should include options from the isc option space: a new address and will create a new lease for it. It will send two addresses in its response: the old address with lifetimes set to 0 to explicitly indicate that it is no longer valid and a new address with - non-zero lifetimes.When the host B renews its temporarily assigned + non-zero lifetimes. When the host B renews its temporarily assigned address, the server will detect that the existing lease does not match reservation, so it will release the current address host B has and will create a new lease matching the reservation. Similar as before, the server - will send two addresses: the temporary one with zeroed lifetimes and the - new one that matches reservation with proper lifetimes set. + will send two addresses: the temporarily assigned one with zeroed + lifetimes, and the new one that matches reservation with proper lifetimes + set. This recovery will succeed, even if other hosts will attempt to get the reserved address. Had the host C requested address 2001:db8::10 after