diff --git a/doc/Makefile.am b/doc/Makefile.am index 933e221782..f6e66d79fb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -11,6 +11,7 @@ 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/stateless.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 51ae8811ba..d93f945789 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1729,6 +1729,166 @@ 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 + 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: + + +"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" + }, + { + "hw-address": "0a:0b:0c:0d:0e:0f", + "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 + 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 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 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 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 + 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 diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 982921e96a..074f05f7cb 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: @@ -1716,6 +1716,189 @@ 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 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: + + +"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