Commit e52f3936 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[3575] Reservations section added for DHCPv6

parent 5f134d8b
......@@ -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
......
# 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"
}
]
}
}
......@@ -1746,12 +1746,13 @@ temporarily override a list of interface names and listen on all interfaces.
<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:
......@@ -1765,17 +1766,22 @@ temporarily override a list of interface names and listen on all interfaces.
<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
......@@ -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 <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>
......@@ -1825,13 +1831,14 @@ temporarily override a list of interface names and listen on all interfaces.
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
......
......@@ -1712,6 +1712,188 @@ should include options from the isc option space:
</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 &dash; 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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment