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

[master] Merge branch 'trac3575' (doc update for host reservation)

Conflicts:
	doc/Makefile.am
parents 2090b643 a6a25b16
......@@ -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
......
# 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"
}
]
}
}
......@@ -1847,6 +1847,196 @@ temporarily override a list of interface names and listen on all interfaces.
</section> <!-- end of configuring kea-dhcp4 server section with many subsections -->
<!-- Host reservation is a large topic. There will be many subsections,
so it should be a section on its own. -->
<section id="host-reservation-v4">
<title>Host reservation in DHCPv4</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
address for exclusive use by a given client (host) &dash; 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.</para>
<para>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.</para>
<para>Hosts reservations are defined as parameters for each subnet. Each host
has to be identified by its hardware/MAC address. There is an optional
<command>reservations</command> array in the <command>Subnet4</command>
element. Each element in that array is a structure, that holds information
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 planned.</para>
<para>The following example shows how to reserve addresses for specific
hosts:
<screen>
"subnet4": [
{
"pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
"subnet": "192.0.2.0/24",
"interface": "eth0",
<userinput>"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"
}
]</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 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.
</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="reservation4-types">
<title>Address reservation types</title>
<para>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 addresses that
belong to configured pools are called <command>in-pool reservations</command>.
In contrast, 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 id="reservation4-conflict">
<title>Conflicts in DHCPv4 reservations</title>
<para>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.</para>
<para>The server now has a conflict to resolve. Let's analyze the
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
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>
<!-- let's keep this text around. It describes how that is working in v6
<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 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.</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 inform the host A that it is no longer
allowed to use it by sending NAK message. The server will remove the
lease, though, as there's small chance that the NAK may be lost if the
network is lossy. If that happens, the client will not receive any
responses, so it will retransmit its Request packet. Once the NAK is
received by the host A, it will then revert to the server discovery and
will eventually get a different address. Besides allocating a new lease,
the server will also remove the old one. As a result the address
192.0.2.10 will be 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, but will keep its
least (again, the NAK may be lost, so the server will keep it, until the
client gets back for a new address). The host B 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. It will
also remove the lease for the temporary address that the host B previously
had.</para>
<para>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).</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="reservation4-hostname">
<title>Reserving a hostname</title>
<!-- @todo: replace this with the actual text once #3688 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="reservation4-options">
<title>Reserving specific options</title>
<!-- @todo: replace this with the actual text once #3572 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>
</section>
<!-- end of host reservations section -->
<section id="dhcp4-serverid">
<title>Server Identifier in DHCPv4</title>
<para>
......
......@@ -11,7 +11,7 @@
<title>Starting and Stopping the DHCPv6 Server</title>
<para>
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 <command>keactrl</command> (described in <xref linkend="keactrl"/>).
However, it is also possible to run the server directly: it accepts
the following command-line switches:
......@@ -1787,6 +1787,200 @@ 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/and prefix for exclusive use by a given client (host) &dash; 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.</para>
<para>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.</para>
<para>Hosts reservations 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 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 planned.</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. The reservation for a given host
should include only one identifier, either DUID or hwardware address. Defining
both for the same host is considered a configuration error, but as of 0.9.1
beta, it is not rejected.
</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 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 belongs to configured pools are called
<command>in-pool reservations</command>. In contrast, 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 id="reservation6-conflict">
<title>Conflicts in DHCPv6 reservations</title>
<para>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.</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 from the
dynamic pool (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 temporarily assigned 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