--- /dev/null
+# 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"
+ }
+ ]
+}
+
+}
<para>Hosts are defined as parameters for each subnet. Each host has to be
identified by its hardware/MAC address. There is an optional
- <command>reservation</command> 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.</para>
+ <command>reservations</command> array in the <command>Subnet4</command>
+ 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.</para>
<para>The following example shows how to reserve addresses for specific
hosts:
<userinput>"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"
}
]</userinput>
}
]
</screen>
+ 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.
</para>
<para>Making a reservation for a mobile host that may visit multiple subnets
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 <command>in-pool reservations</command>.
+ belong to configured pools are called <command>in-pool reservations</command>.
In contract, those that do not belong to dynamic pools are called
- <command>out-of-pool reservations</command>. This is no formal difference
+ <command>out-of-pool reservations</command>. 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.</para>
</section>
cases where such an operation is warranted.</para>
<para>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.</para>
+ 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.</para>
<para>When the host A renews its address, the server will discover that
the address being renewed is now reserved for someone else (host
</section>
+ <!-- Host reservation is a large topic. There will be many subsections,
+ so it should be a section on its own. -->
+ <section id="host-reservation-v6">
+ <title>Host reservation in DHCPv6</title>
+
+ <para>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.</para>
+
+ <para>Hosts are defined as parameters for each subnet. Each host can be
+ identified by either DUID or its hardware/MAC address. See <xref
+ linkend="mac-in-dhcpv6"/> for details. There is an optional
+ <command>reservations</command> array in the <command>Subnet6</command>
+ 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.</para>
+
+ <para>The following example shows how to reserve addresses and prefixes
+ for specific hosts:
+
+<screen>
+"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
+ }
+ ],
+ <userinput>"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"
+ }
+ ]</userinput>
+ }
+]
+</screen>
+ 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.
+ </para>
+
+ <para>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 <command>ip-addresses"</command> and <command>prefixes</command>
+ are plural and are actually arrays. As of 0.9.1 having more than one IPv6
+ address or prefix is only partially supported.</para>
+
+ <para>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.
+ </para>
+
+ <para>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.</para>
+
+ <section id="reservation6-types">
+ <title>Address/prefix reservation types</title>
+
+ <para>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
+ <command>in-pool reservations</command>. In contract, those that do not
+ belong to dynamic pools are called <command>out-of-pool
+ reservations</command>. 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.</para>
+ </section>
+
+ <section it="reservation6-conflict">
+ <title>Conflicts in DHCPv6 reservations</title>
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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).
+ </para>
+ </section>
+
+ <section id="reservation6-hostname">
+ <title>Reserving a hostname</title>
+ <!-- @todo: replace this with the actual text once #3689 is implemented -->
+ <para>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.</para>
+ </section>
+
+ <section id="reservation6-options">
+ <title>Reserving specific options</title>
+ <!-- @todo: replace this with the actual text once #3573 is implemented -->
+ <para>Currently it is not possible to specify options in host
+ reservation. Such a feature will be added in the upcoming Kea
+ releases.</para>
+ </section>
+
+ <!-- @todo: add support for per IA reservation (that specifies IAID in
+ the ip-addresses and prefixes) -->
+ </section>
+ <!-- end of host reservations section -->
+
<section id="dhcp6-serverid">
<title>Server Identifier in DHCPv6</title>
<para>The DHCPv6 protocol uses a "server identifier" (also known
projects / thirdparty / kea.git / commitdiff
