mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-30 13:37:55 +00:00
[trac3565] Merge branch 'trac3575' into trac3565 (HR docs)
Conflicts: doc/Makefile.am
This commit is contained in:
Tomek Mrugalski
@@ -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
|
||||
|
||||
|
||||
94
doc/examples/kea6/reservations.json
Normal file
94
doc/examples/kea6/reservations.json
Normal file
@@ -0,0 +1,94 @@
|
||||
# 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
}
|
||||
@@ -1729,6 +1729,166 @@ 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 ‐ 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
|
||||
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
|
||||
<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:
|
||||
|
||||
<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 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
|
||||
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's 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
|
||||
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="reservation4-conflict">
|
||||
<title>Conflicts in DHCPv4 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 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>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 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
|
||||
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>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:
|
||||
@@ -1716,6 +1716,189 @@ 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 ‐ 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 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>
|
||||
|
||||
<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
|
||||
|
||||
Reference in New Issue
Block a user