Commit 8cd0316d authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3684] Updated Kea User's Guide for host reservations in Kea 1.1.0.

parent ec6e634e
...@@ -479,7 +479,7 @@ If a timeout is given though, it should be an integer greater than zero. ...@@ -479,7 +479,7 @@ If a timeout is given though, it should be an integer greater than zero.
</section> </section>
<section> <section>
<title id="hosts4-storage">Hosts Storage</title> <title id="hosts-storage4">Hosts Storage</title>
<para>Kea is also able to store information about host reservations in the <para>Kea is also able to store information about host reservations in the
database. The hosts database configuration uses the same syntax as the lease database. The hosts database configuration uses the same syntax as the lease
...@@ -2580,7 +2580,7 @@ It is merely echoed by the server ...@@ -2580,7 +2580,7 @@ It is merely echoed by the server
<!-- Host reservation is a large topic. There will be many subsections, <!-- Host reservation is a large topic. There will be many subsections,
so it should be a section on its own. --> so it should be a section on its own. -->
<section id="host-reservation-v4"> <section id="host-reservation-v4">
<title>Host reservation in DHCPv4</title> <title>Host Reservation in DHCPv4</title>
<para>There are many cases where it is useful to provide a configuration on <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 a per host basis. The most obvious one is to reserve specific, static
...@@ -2595,9 +2595,7 @@ It is merely echoed by the server ...@@ -2595,9 +2595,7 @@ It is merely echoed by the server
<para>Another example when the host reservations are applicable is when a host <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. 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 Yet another possible use case is to define unique names for hosts.</para>
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 <para>Hosts reservations are defined as parameters for each subnet. Each host
has to be identified by an identifier, for example hardware/MAC address. There is an optional has to be identified by an identifier, for example hardware/MAC address. There is an optional
...@@ -2605,9 +2603,10 @@ It is merely echoed by the server ...@@ -2605,9 +2603,10 @@ It is merely echoed by the server
element. Each element in that array is a structure, that holds information element. Each element in that array is a structure, that holds information
about reservations for a single host. In particular, such a structure has about reservations for a single host. In particular, such a structure has
to have an identifier that uniquely identifies a host. In DHCPv4 context, such an to have an identifier that uniquely identifies a host. In DHCPv4 context, such an
identifier is a hardware or MAC address. In most cases an address identifier is usually a hardware or MAC address. In most cases an IP address
will be specified. It is also possible to specify a hostname or host will be specified. It is also possible to specify a hostname, host
specific options. Additional capabilities are planned.</para> specific options or fields carried within DHCPv4 message such as siaddr,
sname or file.</para>
<para>In Kea 1.0.0 it was only possible to create host reservations <para>In Kea 1.0.0 it was only possible to create host reservations
using client's hardware address. Host reservations by client using client's hardware address. Host reservations by client
...@@ -2677,7 +2676,7 @@ It is merely echoed by the server ...@@ -2677,7 +2676,7 @@ It is merely echoed by the server
additional check incurs performance penalty.</para> additional check incurs performance penalty.</para>
<section id="reservation4-types"> <section id="reservation4-types">
<title>Address reservation types</title> <title>Address Reservation Types</title>
<para>In a typical scenario there is an IPv4 subnet defined, <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 e.g. 192.0.2.0/24, with certain part of it dedicated for dynamic allocation
...@@ -2696,7 +2695,7 @@ It is merely echoed by the server ...@@ -2696,7 +2695,7 @@ It is merely echoed by the server
</section> </section>
<section id="reservation4-conflict"> <section id="reservation4-conflict">
<title>Conflicts in DHCPv4 reservations</title> <title>Conflicts in DHCPv4 Reservations</title>
<para>As the reservations and lease information are stored separately, <para>As the reservations and lease information are stored separately,
conflicts may arise. Consider the following series of events. The server conflicts may arise. Consider the following series of events. The server
has configured the dynamic pool of addresses from the range of 192.0.2.10 to has configured the dynamic pool of addresses from the range of 192.0.2.10 to
...@@ -2774,7 +2773,7 @@ It is merely echoed by the server ...@@ -2774,7 +2773,7 @@ It is merely echoed by the server
</section> </section>
<section id="reservation4-hostname"> <section id="reservation4-hostname">
<title>Reserving a hostname</title> <title>Reserving a Hostname</title>
<para>When the reservation for the client includes the <command>hostname <para>When the reservation for the client includes the <command>hostname
</command>, the server will assign this hostname to the client and send </command>, the server will assign this hostname to the client and send
it back in the Client FQDN or Hostname option, depending on which of them it back in the Client FQDN or Hostname option, depending on which of them
...@@ -2837,7 +2836,7 @@ It is merely echoed by the server ...@@ -2837,7 +2836,7 @@ It is merely echoed by the server
</section> </section>
<section id="reservation4-options"> <section id="reservation4-options">
<title>Including specific DHCPv4 options in reservations</title> <title>Including Specific DHCPv4 Options in Reservations</title>
<para>Kea 1.1.0 introduced the ability to specify options on a <para>Kea 1.1.0 introduced the ability to specify options on a
per host basis. The options follow the same rules as any other per host basis. The options follow the same rules as any other
options. These can be standard options (see <xref options. These can be standard options (see <xref
...@@ -2927,17 +2926,20 @@ It is merely echoed by the server ...@@ -2927,17 +2926,20 @@ It is merely echoed by the server
</section> </section>
<section id="reservations4-mysql-pgsql"> <section id="reservations4-mysql-pgsql">
<title>Storing host reservations in MySQL or PostgreSQL</title> <title>Storing Host Reservations in MySQL or PostgreSQL</title>
<para> <para>
It is possible to store host reservations in MySQL or PostgreSQL. See <xref It is possible to store host reservations in MySQL or PostgreSQL database. See
linkend="hosts4-storage" /> for information on how to configure Kea to use <xref linkend="hosts-storage4"/> for information on how to configure Kea to use
reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
tools for managing reservations in a database. See Kea wiki <ulink tools for managing reservations in a database. See Kea wiki <ulink
url="http://kea.isc.org/wiki/HostReservationsHowTo" /> for detailed url="http://kea.isc.org/wiki/HostReservationsHowTo" /> for detailed
information and examples of how reservations can be inserted into the information and examples of how reservations can be inserted into the
database. database.
</para> </para>
<note><simpara>In Kea 1.1.0 maximum length of an option specified per host is
arbitrarily set to 4096 bytes.</simpara></note>
</section> </section>
<section id="reservations4-cql"> <section id="reservations4-cql">
...@@ -2982,7 +2984,7 @@ It is merely echoed by the server ...@@ -2982,7 +2984,7 @@ It is merely echoed by the server
dynamic pool. Therefore it can skip the reservation checks when dealing dynamic pool. Therefore it can skip the reservation checks when dealing
with in-pool addresses, thus improving performance. Do not use this mode with in-pool addresses, thus improving performance. Do not use this mode
if any of your reservations use in-pool address. Caution is advised when if any of your reservations use in-pool address. Caution is advised when
using this setting. Kea 0.9.1 does not sanity check the reservations against using this setting. Kea 1.1.0 does not sanity check the reservations against
<command>reservation-mode</command>. Misconfiguration may cause problems. <command>reservation-mode</command>. Misconfiguration may cause problems.
</simpara></listitem> </simpara></listitem>
...@@ -3012,7 +3014,7 @@ It is merely echoed by the server ...@@ -3012,7 +3014,7 @@ It is merely echoed by the server
</para> </para>
<para>Another aspect of the host reservations are different types of <para>Another aspect of the host reservations are different types of
identifiers. Currently (June 2016) Kea supports four types of identifiers identifiers. Kea 1.1.0 supports four types of identifiers
(hw-address, duid, client-id and circuit-id), but more identifier types (hw-address, duid, client-id and circuit-id), but more identifier types
are likely to be added in the future. This is beneficial from a are likely to be added in the future. This is beneficial from a
usability perspective. However, there is a drawback. For each incoming usability perspective. However, there is a drawback. For each incoming
......
...@@ -2304,7 +2304,7 @@ should include options from the isc option space: ...@@ -2304,7 +2304,7 @@ should include options from the isc option space:
<!-- Host reservation is a large topic. There will be many subsections, <!-- Host reservation is a large topic. There will be many subsections,
so it should be a section on its own. --> so it should be a section on its own. -->
<section id="host-reservation-v6"> <section id="host-reservation-v6">
<title>Host reservation in DHCPv6</title> <title>Host Reservation in DHCPv6</title>
<para>There are many cases where it is useful to provide a configuration on <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 a per host basis. The most obvious one is to reserve specific, static IPv6
...@@ -2320,9 +2320,7 @@ should include options from the isc option space: ...@@ -2320,9 +2320,7 @@ should include options from the isc option space:
<para>Another example when the host reservations are applicable is when a host <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 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 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 host reservation is to define unique names for hosts.</para>
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 <para>Hosts reservations are defined as parameters for each subnet. Each host
can be identified by either DUID or its hardware/MAC address. See can be identified by either DUID or its hardware/MAC address. See
...@@ -2332,9 +2330,9 @@ should include options from the isc option space: ...@@ -2332,9 +2330,9 @@ should include options from the isc option space:
is a structure, that holds information about a single host. In is a structure, that holds information about a single host. In
particular, such a structure has to have an identifier that particular, such a structure has to have an identifier that
uniquely identifies a host. In DHCPv6 context, such an identifier uniquely identifies a host. In DHCPv6 context, such an identifier
is a hardware (MAC) address or a DUID. Also, either one or more is usually a DUID, but can also be a hardware or MAC address. Also,
addresses or prefixes should be specified. It is possible to either one or more addresses or prefixes may be specified. It is
specify a hostname. Additional capabilities are planned.</para> possible to specify a hostname and DHCPv6 options for a given host.</para>
<para>The following example shows how to reserve addresses and prefixes <para>The following example shows how to reserve addresses and prefixes
for specific hosts: for specific hosts:
...@@ -2358,11 +2356,11 @@ should include options from the isc option space: ...@@ -2358,11 +2356,11 @@ should include options from the isc option space:
}, },
{ {
"hw-address": "00:01:02:03:04:05", "hw-address": "00:01:02:03:04:05",
"ip-addresses": [ "2001:db8:1::101" ] "ip-addresses": [ "2001:db8:1::101, 2001:db8:1::102" ]
}, },
{ {
"duid": "01:02:03:04:05:06:07:08:09:0A", "duid": "01:02:03:04:05:06:07:08:09:0A",
"ip-addresses": [ "2001:db8:1::102" ], "ip-addresses": [ "2001:db8:1::103" ],
"prefixes": [ "2001:db8:2:abcd::/64" ], "prefixes": [ "2001:db8:2:abcd::/64" ],
"hostname": "foo.example.com" "hostname": "foo.example.com"
} }
...@@ -2370,19 +2368,36 @@ should include options from the isc option space: ...@@ -2370,19 +2368,36 @@ should include options from the isc option space:
} }
] ]
</screen> </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 This example includes reservations for 3 different clients. First reservation
also reserves an address, but does so using MAC or hardware address, rather than is made for the address 2001:db8:1::100 for a client using DUID
DUID. The third example is most advanced. It reserves an address, a prefix and 01:02:03:04:05:0A:0B:0C:0D:0E. Second reservation is made for two addresses
a hostname at the same time. 2001:db8:1::101 and 2001:db8:1::102 for a client using MAC address
00:01:02:03:04:05. Lastly, address 2001:db8:1::103 and prefix 2001:db8:2:abcd::/64
are reserved for a client using DUID 01:02:03:04:05:06:07:08:09:0A. This
last reservation also assigns a hostname to this client.
</para> </para>
<para>Note that DHCPv6 allows for a single client to lease multiple addresses <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 and multiple prefixes at the same time. Therefore <command>ip-addresses</command>
be possible to have multiple addresses and prefixes reserved for a single and <command>prefixes</command> are plural and are actually arrays.
host. Therefore <command>ip-addresses</command> and <command>prefixes</command> When the client sends multiple IA options (IA_NA or IA_PD), each reserved
are plural and are actually arrays. As of 0.9.1 having more than one IPv6 address or prefix is assigned to individual IA of appropriate type. If
address or prefix is only partially supported.</para> the number of IAs of specific type is lower than the number of reservations
of that type, the number of reserved addresses or prefixes assigned to the
client is equal to the number of IA_NAs or IA_PDs sent by the client, i.e.
some reserved addresses or prefixes are not assigned to the client. Though,
they still remain reserved for this client and the server will not assign
them to any other client. If the number of IAs of specific type sent by the
client is greater than the number of reserved addresses or prefixes, the
server will try to assign all reserved addresses or prefixes to the individual
IAs and dynamically allocate addresses or prefixes to remaining IAs. If the
server cannot assign any of the reserved addresses or prefixes because of the
conflict, the server will pick next reserved address or prefix and try to
assign it to the client. If the server subsequently finds that there are no
more reservations that can be assigned to the client at the moment, the
server will try to assign leases dynamically.
</para>
<para>Making a reservation for a mobile host that may visit multiple subnets <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. requires a separate host definition in each subnet it is expected to visit.
...@@ -2390,8 +2405,8 @@ should include options from the isc option space: ...@@ -2390,8 +2405,8 @@ should include options from the isc option space:
address in a single subnet. It is a valid configuration, if such definitions 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 are specified in different subnets, though. The reservation for a given host
should include only one identifier, either DUID or hardware address. Defining should include only one identifier, either DUID or hardware address. Defining
both for the same host is considered a configuration error, but as of 0.9.1 both for the same host is considered a configuration error, but as of 1.1.0,
beta, it is not rejected. it is not rejected.
</para> </para>
<para>Adding host reservation incurs a performance penalty. In principle, <para>Adding host reservation incurs a performance penalty. In principle,
...@@ -2416,7 +2431,7 @@ should include options from the isc option space: ...@@ -2416,7 +2431,7 @@ should include options from the isc option space:
<command>in-pool reservations</command>. In contrast, those that do not <command>in-pool reservations</command>. In contrast, those that do not
belong to dynamic pools are called <command>out-of-pool belong to dynamic pools are called <command>out-of-pool
reservations</command>. There is no formal difference in the reservation reservations</command>. There is no formal difference in the reservation
syntax. As of 0.9.1, both reservation types are handled syntax. As of Kea 1.1.0, both reservation types are handled
uniformly. However, upcoming releases may offer improved performance if uniformly. However, upcoming releases may offer improved performance if
there are only out-of-pool reservations as the server will be able to skip there are only out-of-pool reservations as the server will be able to skip
reservation checks when dealing with existing leases. Therefore, system reservation checks when dealing with existing leases. Therefore, system
...@@ -2425,7 +2440,7 @@ should include options from the isc option space: ...@@ -2425,7 +2440,7 @@ should include options from the isc option space:
</section> </section>
<section id="reservation6-conflict"> <section id="reservation6-conflict">
<title>Conflicts in DHCPv6 reservations</title> <title>Conflicts in DHCPv6 Reservations</title>
<para>As reservations and lease information are stored in different places, <para>As reservations and lease information are stored in different places,
conflicts may arise. Consider the following series of events. The server conflicts may arise. Consider the following series of events. The server
has configured the dynamic pool of addresses from the range of 2001:db8::10 has configured the dynamic pool of addresses from the range of 2001:db8::10
...@@ -2603,6 +2618,9 @@ should include options from the isc option space: ...@@ -2603,6 +2618,9 @@ should include options from the isc option space:
information and examples of how reservations can be inserted into the information and examples of how reservations can be inserted into the
database. database.
</para> </para>
<note><simpara>In Kea 1.1.0 maximum length of an option specified per host is
arbitrarily set to 4096 bytes.</simpara></note>
</section> </section>
<section id="reservations6-cql"> <section id="reservations6-cql">
...@@ -2645,7 +2663,7 @@ should include options from the isc option space: ...@@ -2645,7 +2663,7 @@ should include options from the isc option space:
dynamic pool. Therefore it can skip the reservation checks when dealing dynamic pool. Therefore it can skip the reservation checks when dealing
with in-pool addresses, thus improving performance. Do not use this mode with in-pool addresses, thus improving performance. Do not use this mode
if any of your reservations use in-pool address. Caution is advised when if any of your reservations use in-pool address. Caution is advised when
using this setting. Kea 0.9.1 does not sanity check the reservations against using this setting. Kea 1.1.0 does not sanity check the reservations against
<command>reservation-mode</command>. Misconfiguration may cause problems. <command>reservation-mode</command>. Misconfiguration may cause problems.
</simpara></listitem> </simpara></listitem>
...@@ -2675,7 +2693,7 @@ should include options from the isc option space: ...@@ -2675,7 +2693,7 @@ should include options from the isc option space:
</para> </para>
<para>Another aspect of the host reservations are different types of <para>Another aspect of the host reservations are different types of
identifiers. Currently (June 2016) Kea supports two types of identifiers identifiers. Kea 1.1.0 supports two types of identifiers
in DHCPv6: hw-address and duid, but more identifier types in DHCPv6: hw-address and duid, but more identifier types
are likely to be added in the future. This is beneficial from a are likely to be added in the future. This is beneficial from a
usability perspective. However, there is a drawback. For each incoming usability perspective. However, there is a drawback. For each incoming
......
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