From 5f134d8beb60de4b76d00a38d7d5654142c7e3e4 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Mon, 26 Jan 2015 17:53:01 +0100 Subject: [PATCH 1/3] [3575] Reservations for v4 documented. --- doc/guide/dhcp4-srv.xml | 153 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index dee22e5b6b..4fd3ff93c3 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1729,6 +1729,159 @@ temporarily override a list of interface names and listen on all interfaces. + +
+ Host reservation in DHCPv4 + + 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 + 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 + reservation array. 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 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. + + The following example shows how to reserve addresses for specific + hosts: + + +"subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "subnet": "192.0.2.0/24", + "interface": "eth0", + "reservations": [ + { + "hw-address": "1a:1b:1c:1d:1e:1f", + "ip-address": "192.0.2.202", + "hostname": "alice-laptop" + }, + { + "hw-address": "0a:0b:0c:0d:0e:0f", + "ip-address": "192.0.2.100" + } + ] + } +] + + + + Making a reservation for a mobile host that may visit multiple subnets + requires a separate host definition in each subnet it is expected to visit. + It is not allowed to define multiple host definitions with the same hardware + address in a single subnet. It is a valid configuration, if such definitions + are specified in different subnets, though. + + + Adding host reservation incurs a performance penalty. In principle, + when the server that does not support host reservation responds to a query, + it needs to check whether there is a lease for a given address being + considered for allocation or renewal. The server that also supports host + reservation, has to perform additional checks: not only if the address is + currently used (if there is a lease for it), but also whether the address + could be used by someone else (if there is a reservation for it). That + additional check incurs performance penalty. + +
+ 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 + 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 + belong to configure pools are called in-pool reservations. + In contract, those that do not belong to dynamic pools are called + out-of-pool reservations. This 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 + if there are only out-of-pool reservations as the server will be able + to skip reservation checks when dealing with existing leases. Therefore + system administrators are encouraged to use out-of-pool reservations, if + possible. +
+ +
+ Conflicts in DHCPv4 reservations + As reservations and lease information are kept in different places, + 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. + + 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 not able to assign the requested 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 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 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 + B). Therefore the server will remove the lease and will inform the host A + that it is no longer allowed to use it by sending NAK message. Host A + will then revert to server discovery and will eventually get a different + address. The address 192.0.2.10 is now no longer used. When host B tries + to renew its temporary address, the server will detect that it has a valid + lease, but there is a reservation for a different address. The server will + send NAK to inform host B that its address is no longer usable. The + server will also remove its temporary lease. It will revert to the server + discovery phase and will eventually send a REQUEST message. This time the + server will find out that there is a reservation for that host and the + reserved address 192.0.2.10 is not used, so it will be granted. + + This recovery will succeed, even if other hosts will attempt to get + the reserved address. Had the host C requested address 192.0.2.10 after + the reservation was made, the server will either propose a different + address (when responding to DISCOVER) or would send NAK (when responding + to REQUEST). + + This recovery mechanism allows the server to fully recover from a + case where reservations conflict with existing leases. This procedure + takes time and will roughly take as long as renew-timer value specified. + The best way to avoid such recovery is to not define new reservations that + conflict with existing leases. Another recommendation is to use + out-of-pool reservations. If the reserved address does not belong to a + pool, there is no way that other clients could get this address (note that + having multiple reservations for the same address is not allowed). + +
+ +
+ Reserving a hostname + + Reserving a hostname is currently not supported. It is possible + to specify that information in the configuration file, but that data + is not used by the server engine yet. +
+ +
+ 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. +
+
+ +
Server Identifier in DHCPv4 From e52f39360fbd459b5f82d292c6e2c10e078d962a Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Mon, 26 Jan 2015 20:25:06 +0100 Subject: [PATCH 2/3] [3575] Reservations section added for DHCPv6 --- doc/Makefile.am | 1 + doc/examples/kea6/reservations.json | 94 ++++++++++++++ doc/guide/dhcp4-srv.xml | 45 ++++--- doc/guide/dhcp6-srv.xml | 182 ++++++++++++++++++++++++++++ 4 files changed, 303 insertions(+), 19 deletions(-) create mode 100644 doc/examples/kea6/reservations.json diff --git a/doc/Makefile.am b/doc/Makefile.am index 173f563648..33095d530e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -10,6 +10,7 @@ nobase_dist_doc_DATA += examples/kea6/simple.json nobase_dist_doc_DATA += examples/kea6/several-subnets.json nobase_dist_doc_DATA += examples/kea6/multiple-options.json nobase_dist_doc_DATA += examples/kea6/advanced.json +nobase_dist_doc_DATA += examples/kea6/reservations.json nobase_dist_doc_DATA += examples/ddns/sample1.json nobase_dist_doc_DATA += examples/ddns/template.json diff --git a/doc/examples/kea6/reservations.json b/doc/examples/kea6/reservations.json new file mode 100644 index 0000000000..c34244e8f6 --- /dev/null +++ b/doc/examples/kea6/reservations.json @@ -0,0 +1,94 @@ +# This is an example configuration file for DHCPv6 server in Kea +# that showcases how to do host reservations. It is +# assumed that one subnet (2001:db8:1::/64) is available directly +# over ethX interface. A number of hosts have various combinations +# of addresses and prefixes reserved for them. + +{ "Dhcp6": + +{ +# Kea is told to listen on ethX interface only. + "interfaces": [ "ethX" ], + +# We need to specify lease type. As of May 2014, three backends are supported: +# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require +# any prior set up. + "lease-database": { + "type": "memfile" + }, + +# This is pretty basic stuff, it has nothing to do with reservations. + "preferred-lifetime": 3000, + "valid-lifetime": 4000, + "renew-timer": 1000, + "rebind-timer": 2000, + +# 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. + "subnet6": [ + { + "subnet": "2001:db8:1::/48", + + "pools": [ { "pool": "2001:db8:1::/80" } ], + + "pd-pools": [ + { + "prefix": "2001:db8:1:8000::", + "prefix-len": 56, + "delegated-len": 64 + } + ], + "interface": "ethX", + +# Host reservations. Define two reservations for the 192.0.2.202 and +# 192.0.2.100 address. Note that the latter is a reservation for the +# address which is within the range of the pool of the dynamically +# allocated address. The server will exclude this address from this +# pool and only assign it to the client which has a reservation for +# it. + "reservations": [ +# This is a simple host reservation. The host with DUID matching +# specified value will get 2001:db8:1::100 address. + { + "duid": "01:02:03:04:05:0A:0B:0C:0D:0E", + "ip-addresses": [ "2001:db8:1::100" ] + }, +# 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. + { + "hw-address": "00:01:02:03:04:05", + "ip-addresses": [ "2001:db8:1::101" ] + }, +# This is a bit more advanced configuration. The client with specified +# DUID will get a reserved address, prefix and a hostname. + { + "duid": "01:02:03:04:05:06:07:08:09:0A", + "ip-addresses": [ "2001:db8:1::102" ], + "prefixes": [ "2001:db8:2:abcd::/64" ], + "hostname": "foo.example.com" + } + ] + } + ] +}, + +# The following configures logging. Kea will log all debug messages +# to /var/log/kea-debug.log file. +"Logging": { + "loggers": [ + { + "name": "kea-dhcp6", + "output_options": [ + { + "output": "/var/log/kea-debug.log" + } + ], + "debuglevel": 99, + "severity": "DEBUG" + } + ] +} + +} diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 4fd3ff93c3..b60409c445 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1746,12 +1746,13 @@ temporarily override a list of interface names and listen on all interfaces. Hosts are defined as parameters for each subnet. Each host has to be identified by its hardware/MAC address. There is an optional - reservation array. 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 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. + 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 + 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. The following example shows how to reserve addresses for specific hosts: @@ -1765,17 +1766,22 @@ temporarily override a list of interface names and listen on all interfaces. "reservations": [ { "hw-address": "1a:1b:1c:1d:1e:1f", - "ip-address": "192.0.2.202", - "hostname": "alice-laptop" + "ip-address": "192.0.2.202" }, { "hw-address": "0a:0b:0c:0d:0e:0f", - "ip-address": "192.0.2.100" + "ip-address": "192.0.2.100", + "hostname": "alice-laptop" } ] } ] + 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 + 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. Making a reservation for a mobile host that may visit multiple subnets @@ -1802,13 +1808,13 @@ temporarily override a list of interface names and listen on all interfaces. 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 - belong to configure pools are called in-pool reservations. + belong to configured pools are called in-pool reservations. In contract, those that do not belong to dynamic pools are called - out-of-pool reservations. This is no formal difference + 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 if there are only out-of-pool reservations as the server will be able - to skip reservation checks when dealing with existing leases. Therefore + to skip reservation checks when dealing with existing leases. Therefore, system administrators are encouraged to use out-of-pool reservations, if possible.
@@ -1825,13 +1831,14 @@ temporarily override a list of interface names and listen on all interfaces. 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 not able to assign the requested 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 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 to host B. + situation here. If host B boots up and request 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 + 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. When the host A renews its address, the server will discover that the address being renewed is now reserved for someone else (host diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index ec360906d1..5bd3055b49 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -1712,6 +1712,188 @@ should include options from the isc option space: + +
+ Host reservation in DHCPv6 + + 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 can be + identified by either DUID or its hardware/MAC address. See for details. There is an optional + reservations array in the Subnet6 + structure. 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 + 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. + + The following example shows how to reserve addresses and prefixes + for specific hosts: + + +"subnet6": [ + { + "subnet": "2001:db8:1::/48", + "pools": [ { "pool": "2001:db8:1::/80" } ], + "pd-pools": [ + { + "prefix": "2001:db8:1:8000::", + "prefix-len": 56, + "delegated-len": 64 + } + ], + "reservations": [ + { + "duid": "01:02:03:04:05:0A:0B:0C:0D:0E", + "ip-addresses": [ "2001:db8:1::100" ] + }, + { + "hw-address": "00:01:02:03:04:05", + "ip-addresses": [ "2001:db8:1::101" ] + }, + { + "duid": "01:02:03:04:05:06:07:08:09:0A", + "ip-addresses": [ "2001:db8:1::102" ], + "prefixes": [ "2001:db8:2:abcd::/64" ], + "hostname": "foo.example.com" + } + ] + } +] + + This example makes 3 reservations. The first one reserves 2001:db8:1::100 address + for the client using DUID 01:02:03:04:05:0A:0B:0C:0D:0E. The second one + also reserves an address, but does so using MAC or hardware address, rather than + DUID. The third example is most advanced. It reserves an address, a prefix and + a hostname at the same time. + + + 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 + are plural and are actually arrays. As of 0.9.1 having more than one IPv6 + address or prefix is only partially supported. + + Making a reservation for a mobile host that may visit multiple subnets + requires a separate host definition in each subnet it is expected to visit. + It is not allowed to define multiple host definitions with the same hardware + address in a single subnet. It is a valid configuration, if such definitions + are specified in different subnets, though. + + + Adding host reservation incurs a performance penalty. In principle, + when the server that does not support host reservation responds to a query, + it needs to check whether there is a lease for a given address being + considered for allocation or renewal. The server that also supports host + reservation, has to perform additional checks: not only if the address is + currently used (if there is a lease for it), but also whether the address + could be used by someone else (if there is a reservation for it). That + additional check incurs performance penalty. + +
+ Address/prefix reservation types + + 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 + 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 + 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 if + there are only out-of-pool reservations as the server will be able to skip + reservation checks when dealing with existing leases. Therefore, system + administrators are encouraged to use out-of-pool reservations, if + 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. + + 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 + not able to assign the reserved address 2001:db8::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 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. + + When the host A renews its address, the server will discover that + the address being renewed is now reserved for someone else (host + B). Therefore the server will remove the lease for 2001:db8::10 and select + 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 + 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. + + 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 + the reservation was made, the server will propose a different address. + + This recovery mechanism allows the server to fully recover from a + case where reservations conflict with existing leases. This procedure + takes time and will roughly take as long as renew-timer value specified. + The best way to avoid such recovery is to not define new reservations that + conflict with existing leases. Another recommendation is to use + out-of-pool reservations. If the reserved address does not belong to a + pool, there is no way that other clients could get this address (note that + having multiple reservations for the same address is not allowed). + +
+ +
+ Reserving a hostname + + Reserving a hostname is currently not supported. It is possible + to specify that information in the configuration file, but that data + is not used by the server engine yet. +
+ +
+ 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. +
+ + +
+ +
Server Identifier in DHCPv6 The DHCPv6 protocol uses a "server identifier" (also known From 59ac2f9dff35a354fad82b96bbbabddf62a4bd93 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Mon, 26 Jan 2015 20:31:11 +0100 Subject: [PATCH 3/3] [3575] Small correction in reservations text. --- doc/guide/dhcp6-srv.xml | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 5bd3055b49..88b84c8bde 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -11,7 +11,7 @@ Starting and Stopping the DHCPv6 Server - It is recommended that the Kea DHCPv4 server be started and stopped + It is recommended that the Kea DHCPv6 server be started and stopped using keactrl (described in ). However, it is also possible to run the server directly: it accepts the following command-line switches: @@ -1728,16 +1728,17 @@ should include options from the isc option space: scenarios are possible yet, Kea software will support them in the near future. - Hosts 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 Subnet6 - structure. 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 - 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. + Hosts 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 + Subnet6 structure. 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 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. The following example shows how to reserve addresses and prefixes for specific hosts: