Commit 9ac4323c authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3575] A couple of corrections in the user guide for the host reservations.

parent a4a158f9
......@@ -1736,23 +1736,30 @@ temporarily override a list of interface names and listen on all interfaces.
<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 &dash; 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
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 are defined as parameters for each subnet. Each host has to be
identified by its hardware/MAC address. There is an optional
<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 a single host. In particular, such a structure has to have an
indentifer that uniquely identifies a host. In DHCPv4 context, such an
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 planed.</para>
capabilities are planned.</para>
<para>The following example shows how to reserve addresses for specific
hosts:
......@@ -1779,7 +1786,7 @@ temporarily override a list of interface names and listen on all interfaces.
</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
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>
......@@ -1803,13 +1810,13 @@ temporarily override a list of interface names and listen on all interfaces.
<section id="reservation4-types">
<title>Address reservation types</title>
<para>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
<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 an address that
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 contract, those that do not belong to dynamic pools are called
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
......@@ -1819,19 +1826,19 @@ temporarily override a list of interface names and listen on all interfaces.
possible.</para>
</section>
<section it="reservation4-conflict">
<section id="reservation4-conflict">
<title>Conflicts in DHCPv4 reservations</title>
<para>As reservations and lease information are kept separately,
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.</para>
<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 host B boots up and request an address, the server is
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
......
......@@ -1719,16 +1719,23 @@ should include options from the isc option space:
<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
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
......@@ -1738,7 +1745,7 @@ should include options from the isc option space:
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.</para>
specify a hostname. Additional capabilities are planned.</para>
<para>The following example shows how to reserve addresses and prefixes
for specific hosts:
......@@ -1784,7 +1791,7 @@ should include options from the isc option space:
<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>
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>
......@@ -1810,11 +1817,11 @@ should include options from the isc option space:
<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
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 belong to configured pools are called
<command>in-pool reservations</command>. In contract, those that do not
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
......@@ -1825,16 +1832,16 @@ should include options from the isc option space:
possible.</para>
</section>
<section it="reservation6-conflict">
<section id="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>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
......@@ -1843,8 +1850,8 @@ should include options from the isc option space:
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>
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
......@@ -1852,12 +1859,13 @@ should include options from the isc option space:
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
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>
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
......
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