mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 22:15:23 +00:00
Code Issues Releases Wiki Activity

[master]Merge branch 'trac4518' (host reservations doc update)

Browse Source
This commit is contained in:
Tomek Mrugalski
2016-07-06 12:03:55 +02:00
parent d8503ce1e7 990ce652a0
commit 99a40fead2
6 changed files with 559 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
doc/examples/kea4/reservations.json
View File

@@ -30,28 +30,88 @@
# "renew-timer": 1000, # "renew-timer": 1000,
# "rebind-timer": 2000, # "rebind-timer": 2000,
# Define a subnet with two reservations for the 192.0.2.202 and
# 192.0.2.100 address. Note that the latter is a reservation for the # Kea supports reservations by several different types of identifiers:
# address which is within the range of the pool of the dynamically # hw-address (hardware/MAC address of the client), duid (DUID inserted by the
# allocated address. The server will exclude this address from this # client), client-id (client identifier inserted by the client) and circuit-id
# pool and only assign it to the client which has a reservation for # (circuit identifier inserted by the relay agent). When told to do so, Kea can
# it. # check for all of those identifier types, but it takes a costly database lookup
# to do so. It is therefore useful from a performance perspective to use only
# the reservation types that are actually used in a given network.
# The example below is not optimal from a performance perspective, but it
# nicely showcases the host reservation capabilities. Please use the minimum
# set of identifier types used in your network.
"host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ],
# Define a subnet with four reservations. Some of the reservations belong
# to the dynamic pool. Kea is able to handle this case, but it is not
# recommended from a performance perspective, as Kea would not only need to
# check if a given address is free, but also whether it is reserved.
# To avoid this check, one can change reservation-mode to out-of-pool, rather
# than 'all'. If a subnet does not have reservations at all, the reservation
# lookup can be skipped altogether (reservation-mode is set to 'disabled').
# Note that the second reservation is for an 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.
"subnet4": [ "subnet4": [
{ {
"pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
"subnet": "192.0.2.0/24", "subnet": "192.0.2.0/24",
"interface": "eth0", "interface": "eth0",
"reservations": [ "reservations": [
# This is a reservation for a specific hardware/MAC address. It's a very
# simple reservation: just an address and nothing else.
{ {
"hw-address": "1a:1b:1c:1d:1e:1f", "hw-address": "1a:1b:1c:1d:1e:1f",
"ip-address": "192.0.2.202" "ip-address": "192.0.2.202"
}, },
# This is a reservation for a specific client-id. It also shows
# the this client will get a reserved hostname. A hostname can be defined
# for any identifier type, not just client-id.
{ {
"hw-address": "0a:0b:0c:0d:0e:0f", "client-id": "01:11:22:33:44:55:66",
"ip-address": "192.0.2.100" "ip-address": "192.0.2.100",
"hostname": "special-snowflake"
},
# The third reservation is based on DUID. This reservation also
# defines special option values for this particular client. If
# the domain-name-servers option would have been defined on a global,
# subnet or class level, the host specific values take preference.
{
"duid": "01:02:03:04:05",
"ip-address": "192.0.2.203",
"option-data": [ {
"name": "domain-name-servers",
"data": "10.1.1.202,10.1.1.203"
} ]
},
# The fourth reservation is based on circuit-id. This is an option inserted
# by the relay agent that forwards the packet from client to the server.
# In this example the host is also assigned vendor specific options.
{
"client-id": "01:11:22:33:44:55:66",
"ip-address": "192.0.2.204",
"option-data": [
{
"name": "vivso-suboptions",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "10.1.1.202,10.1.1.203"
}
]
} }
] ]
} }
] ]
}, },

59
doc/examples/kea6/reservations.json
View File

@@ -25,6 +25,13 @@
"renew-timer": 1000, "renew-timer": 1000,
"rebind-timer": 2000, "rebind-timer": 2000,
# Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address
# of the client) and duid (DUID inserted by the client). When told to do so, Kea can
# check for each of these identifier types, but it takes a costly database lookup
# to do so. It is therefore useful from a performance perspective to use only
# the reservation types that are actually used in a given network.
"host-reservation-identifiers": [ "duid", "hw-address" ],
# The following list defines subnets. Subnet, pools and interface definitions # The following list defines subnets. Subnet, pools and interface definitions
# are the same as in the regular scenario, without host reservations. # are the same as in the regular scenario, without host reservations.
# least subnet and pool entries. # least subnet and pool entries.
@@ -43,33 +50,59 @@
], ],
"interface": "ethX", "interface": "ethX",
# Host reservations. Define two reservations for the 192.0.2.202 and # Host reservations. Define several reservations, note that
# 192.0.2.100 address. Note that the latter is a reservation for the # they are all within the range of the pool of the dynamically
# address which is within the range of the pool of the dynamically # allocated address. The server will exclude the addresses from this
# allocated address. The server will exclude this address from this # pool and only assign them to the client which has a reservation for
# pool and only assign it to the client which has a reservation for # them.
# it.
"reservations": [ "reservations": [
# This is a simple host reservation. The host with DUID matching # This is a simple host reservation. The host with DUID matching
# specified value will get 2001:db8:1::100 address. # the specified value will get an address of 2001:db8:1::100.
{ {
"duid": "01:02:03:04:05:0A:0B:0C:0D:0E", "duid": "01:02:03:04:05:0A:0B:0C:0D:0E",
"ip-addresses": [ "2001:db8:1::100" ] "ip-addresses": [ "2001:db8:1::100" ]
}, },
# This is similar to the previous one, but this time the reservation is done # 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 # based on hardware/MAC address. The server will do its best to extract
# the hardware/MAC address from received packets. # the hardware/MAC address from received packets (see 'mac-sources' directive
# for details). This particular reservation also specifies two extra options
# to be available for this client. If there are options with the same code
# specified in a global, subnet or class scope, the values defined at host level
# take precedence.
{ {
"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" ],
"option-data": [
{
"name": "dns-servers",
"data": "3000:1::234"
},
{
"name": "nis-servers",
"data": "3000:1::234"
}]
}, },
# This is a bit more advanced configuration. The client with specified # This is a bit more advanced reservation. The client with the specified
# DUID will get a reserved address, prefix and a hostname. # DUID will get a reserved address, a reserved prefix and a hostname.
# This reservation is for an address that it not within the dynamic pool.
# Finally, this reservation features vendor specific options for CableLabs,
# which happen to use enterprise-id 4491. Those particular values will
# be returned only to the client that has a DUID matching this reservation.
{ {
"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:cafe::1" ],
"prefixes": [ "2001:db8:2:abcd::/64" ], "prefixes": [ "2001:db8:2:abcd::/64" ],
"hostname": "foo.example.com" "hostname": "foo.example.com",
"option-data": [ {
"name": "vendor-opts",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
} ]
} }
] ]
} }

99
doc/guide/admin.xml
View File

@@ -148,9 +148,86 @@
<section> <section>
<title>Supported Databases</title> <title>Supported Databases</title>
<para>The following table presents the capabilities of available
backends. Please refer to the specific sections dedicated to each backend to
better understand their capabilities and limitations. Choosing the right
backend may be essential for success or failure of your deployment.</para>
<para>
<table frame="all" id="backends">
<title>List of available backends</title>
<tgroup cols='2'>
<colspec colname='feature'/>
<colspec colname='memfile'/>
<colspec colname='mysql'/>
<colspec colname='pgsql'/>
<colspec colname='cql'/>
<thead>
<row>
<entry>Feature</entry>
<entry>Memfile</entry>
<entry>MySQL</entry>
<entry>PostgreSQL</entry>
<entry>CQL(Cassandra)</entry>
</row>
</thead>
<tbody>
<row>
<entry>Status</entry>
<entry>Stable</entry>
<entry>Stable</entry>
<entry>Stable</entry>
<entry>Experimental</entry>
</row>
<row>
<entry>Data format</entry>
<entry>coma separated file</entry>
<entry>SQL RMDB</entry>
<entry>SQL RMDB</entry>
<entry>NoSQL database (CQL)</entry>
</row>
<row>
<entry>Leases</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>yes</entry>
</row>
<row>
<entry>Host Reservations</entry>
<entry>no</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>no</entry>
</row>
<row>
<entry>Options defined on per host basis</entry>
<entry>no</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<section> <section>
<title>memfile</title> <title>memfile</title>
<para>
Memfile backend is able to store lease information, but is not able to
store host reservation details. There are no plans to add the
reservations storage capability to memfile. Host reservations can be
defined in the configuration file.
</para>
<para> <para>
There are no special initialization steps necessary There are no special initialization steps necessary
for the memfile backend. During the first run, both for the memfile backend. During the first run, both
@@ -158,6 +235,7 @@
will create an empty lease file if one is not will create an empty lease file if one is not
present. Necessary disk write permission is required. present. Necessary disk write permission is required.
</para> </para>
<section id="memfile-upgrade"> <section id="memfile-upgrade">
<title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title> <title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title>
<para> <para>
@@ -185,13 +263,17 @@
<section> <section>
<title>MySQL</title> <title>MySQL</title>
<para>
MySQL is able to store leases, host reservations and options defined on
a per host basis.
</para>
<para> <para>
The MySQL database must be properly set up if you want Kea to The MySQL database must be properly set up if you want Kea to
store information in MySQL. This section can be safely ignored store information in MySQL. This section can be safely ignored
if you chose to store the data in other backends. if you chose to store the data in other backends.
</para> </para>
<section id="mysql-database-create"> <section id="mysql-database-create">
<title>First Time Creation of Kea Database</title> <title>First Time Creation of Kea Database</title>
@@ -327,6 +409,12 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
<section> <section>
<title>PostgreSQL</title> <title>PostgreSQL</title>
<para>
PostgreSQL is able to store leases. The capability to store host
reservations (that include addresses, prefixes and options) is planned
for upcoming Kea 1.1.0.
</para>
<para> <para>
A PostgreSQL database must be set up if you want Kea to store A PostgreSQL database must be set up if you want Kea to store
lease and other information in PostgreSQL. This step can be lease and other information in PostgreSQL. This step can be
@@ -496,6 +584,15 @@ $ <userinput>kea-admin lease-init pgsql -u <replaceable>database-user</replaceab
<section> <section>
<title>CQL (Cassandra)</title> <title>CQL (Cassandra)</title>
<para>
Cassandra, or Cassandra Query Language (CQL), is the newest backend
added to Kea. Since it was added recently and has not undergone as much
testing as other backends, it is considered experimental. Please use
with caution. CQL backend is currently able to store leases only. The
ability to store host reservations will likely be added some time in the
future.
</para>
<para> <para>
The CQL database must be properly set up if you want Kea to store The CQL database must be properly set up if you want Kea to store
information in CQL. This section can be safely ignored if you chose to information in CQL. This section can be safely ignored if you chose to

263
doc/guide/dhcp4-srv.xml
View File

@@ -10,13 +10,11 @@
<section id="dhcp4-start-stop"> <section id="dhcp4-start-stop">
<title>Starting and Stopping the DHCPv4 Server</title> <title>Starting and Stopping the DHCPv4 Server</title>
<!-- @todo Rewrite this section once #3422 is done -->
<para> <para>
It is recommended that the Kea DHCPv4 server be started and stopped It is recommended that the Kea DHCPv4 server be started and stopped
using <command>keactrl</command> (described in <xref linkend="keactrl"/>). using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
However, it is also possible to run the server directly: it accepts However, it is also possible to run the server directly: it accepts
the following command-line switches: the following command-line switches:
</para> </para>
<itemizedlist> <itemizedlist>
@@ -64,25 +62,25 @@
</itemizedlist> </itemizedlist>
<para> <para>
The <command>-V</command> command returns the versions of the The <command>-V</command> command returns the versions of the
external libraries dynamically linked. external libraries dynamically linked.
</para> </para>
<para> <para>
The <command>-W</command> command describes the environment used The <command>-W</command> command describes the environment used
to build Kea. This command displays a copy of the to build Kea. This command displays a copy of the
<filename>config.report</filename> file produced by <filename>config.report</filename> file produced by
<userinput>./configure</userinput> that is embedded in the <userinput>./configure</userinput> that is embedded in the
executable binary. executable binary.
</para> </para>
<para> <para>
The <filename>config.report</filename> may also be accessed more The <filename>config.report</filename> may also be accessed more
directly. The following command may be used to extract this directly. The following command may be used to extract this
information. The binary <userinput>path</userinput> may be found information. The binary <userinput>path</userinput> may be found
in the install directory or in the <filename>.libs</filename> in the install directory or in the <filename>.libs</filename>
subdirectory in the source tree. For example subdirectory in the source tree. For example
<filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>. <filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>.
<screen> <screen>
strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p' strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p'
@@ -90,9 +88,9 @@ strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p'
</para> </para>
<para> <para>
When running in a console, the server can be shut down by When running in a console, the server can be shut down by
pressing ctrl-c. It detects the key combination and shuts pressing ctrl-c. It detects the key combination and shuts
down gracefully. down gracefully.
</para> </para>
<para> <para>
@@ -481,13 +479,7 @@ If a timeout is given though, it should be an integer greater than zero.
</section> </section>
<section> <section>
<title>Hosts Storage</title> <title id="hosts4-storage">Hosts Storage</title>
<note>
<para>This feature did not undergo the regular system level
testing conducted by ISC. As such, please treat it as
experimental.</para>
</note>
<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. Hosts database configuration uses the same syntax as lease database. Hosts database configuration uses the same syntax as lease
@@ -750,8 +742,8 @@ temporarily override a list of interface names and listen on all interfaces.
manually specify a unique identifier for each subnet. manually specify a unique identifier for each subnet.
</para> </para>
<para> <para>
The following configuration will assign the specified subnet The following configuration will assign the specified subnet
identifier to the newly configured subnet: identifier to the newly configured subnet:
<screen> <screen>
"Dhcp4": { "Dhcp4": {
@@ -1435,7 +1427,7 @@ It is merely echoed by the server
"type": "ipv4-address", "type": "ipv4-address",
"record-types": "", "record-types": "",
"array": false, "array": false,
"encapsulate "" "encapsulate": ""
}, },
{ {
"name": "subopt2", "name": "subopt2",
@@ -2444,23 +2436,18 @@ It is merely echoed by the server
near future.</para> 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 its hardware/MAC address. There is an optional has to be identified by an identifier, for example hardware/MAC address. There is an optional
<command>reservations</command> array in the <command>Subnet4</command> <command>reservations</command> array in the <command>Subnet4</command>
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, also an address identifier is a hardware or MAC address. In most cases an address
will be specified. It is possible to specify a hostname. Additional will be specified. It is also possible to specify a hostname or host
capabilities are planned.</para> specific options. Additional capabilities are planned.</para>
<note><para>In Kea 1.0.0 it is 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 identifier using client's hardware address. Host reservations by client
(or DUID) are not supported in this version of Kea. This capability will identifier, DUID and circuit-id have been added in Kea 1.1.0.</para>
be implemented in Kea 1.1.0. Currently, the configuration parsing code
will accept the "duid" parameter in the reservation configuration, but
the server will misinterpret its value. Therefore, this parameter MUST
NOT be used until the client identifier based host reservations are
properly implemented and documented.</para></note>
<para>The following example shows how to reserve addresses for specific <para>The following example shows how to reserve addresses for specific
hosts: hosts:
@@ -2477,20 +2464,37 @@ It is merely echoed by the server
"ip-address": "192.0.2.202" "ip-address": "192.0.2.202"
}, },
{ {
"hw-address": "0a:0b:0c:0d:0e:0f", "duid": "0a:0b:0c:0d:0e:0f",
"ip-address": "192.0.2.100", "ip-address": "192.0.2.100",
"hostname": "alice-laptop" "hostname": "alice-laptop"
},
{
"circuit-id": "'charter950'",
"ip-address": "192.0.2.203"
},
{
"client-id": "01:11:22:33:44:55:66",
"ip-address": "192.0.2.204"
} }
]</userinput> ]</userinput>
} }
] ]
</screen> </screen>
The first entry reserves the 192.0.2.202 address for the client that uses The first entry reserves the 192.0.2.202 address for the client that uses
MAC address of 1a:1b:1c:1d:1e:1f. The second entry reserves the address a MAC address 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 192.0.2.100 and the hostname of alice-laptop for the client using a DUID
address 0a:0b:0c:0d:0e:0f. Note that if you plan to do DNS updates, it 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. is strongly recommended for the hostnames to be unique. The third
</para> example reserves address 192.0.3.203 to a client whose request
would be relayed by a relay agent that inserts a circuid-it option
with the value 'charter950'. The fourth entry reserves address
192.0.2.204 for a client that uses a client identifier with value
01:11:22:33:44:55:66.</para>
<para>The above example is used for ilustrational purposes only
and in actual deployments it is recommended to use as few types as possible
(preferably just one). See <xref linkend="reservations4-tuning"/> for detailed
discussion.</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.
@@ -2669,26 +2673,100 @@ It is merely echoed by the server
</section> </section>
<section id="reservation4-options"> <section id="reservation4-options">
<title>Reserving specific options</title> <title>Including specific DHCPv4 options in reservations</title>
<!-- @todo: replace this with the actual text once #3572 is implemented --> <para>Kea 1.1.0 introduced the ability to specify options on a
<para>Currently it is not possible to specify options in host per host basis. The options follow the same rules as any other
reservation. Such a feature will be added in the upcoming Kea options. These can be standard options (see <xref
releases.</para> linkend="dhcp4-std-options" />), custom options (see <xref
linkend="dhcp4-custom-options"/>) or vendor specific options
(see <xref linkend="dhcp4-vendor-opts" />). The following
example showcases how standard options can be defined.</para>
<screen>
{
"subnet4": [ {
"reservations": [
{
"hw-address": "aa:bb:cc:dd:ee:ff",
"ip-address": "192.0.2.1",
<userinput>"option-data": [
{
"name": "cookie-servers",
"data": "10.1.1.202,10.1.1.203"
},
{
"name": "log-servers",
"data": "10.1.1.200,10.1.1.201"
} ]</userinput>
} ]
} ]
}</screen>
<para>Vendor specific options can be reserved in a similar manner:</para>
<screen>
{
"subnet4": [ {
"reservations": [
{
"hw-address": "aa:bb:cc:dd:ee:ff",
"ip-address": "10.0.0.7",
<userinput>"option-data": [
{
"name": "vivso-suboptions",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "10.1.1.202,10.1.1.203"
} ]</userinput>
} ]
} ]
}</screen>
<para>
Options defined on host level have the highest priority. In other words,
if there are options defined with the same type on global, subnet, class and
host level, the host specific values will be used.
</para>
</section> </section>
<section id="reservation4-mode"> <section id="reservations4-mysql">
<title>Fine Tuning IPv4 Host Reservation</title> <title>Storing host reservations in MySQL</title>
<note> <para>
<para><command>reservation-mode</command> configuration parameter in DHCPv4 It is possible to store host reservations in MySQL. See <xref
server is accepted, but not used in the Kea 0.9.1 beta. Full implementation linkend="hosts4-storage" /> for information on how to configure Kea to use
will be available in the upcoming releases.</para> reservations stored in MySQL. Kea does not provide any dedicated tools
</note> for managing MySQL reservations. See Kea wiki <ulink
url="http://kea.isc.org/wiki/HostReservationsHowTo" /> for detailed
information and examples of how reservations can be inserted into the
database.
</para>
</section>
<section id="reservations4-pgsql">
<title>Storing host reservations in PostgreSQL</title>
<para>Kea currently does not support storing reservations in
PostgreSQL, but this feature is planned for Kea 1.1.0.</para>
</section>
<section id="reservations4-cql">
<title>Storing host reservations in CQL (Cassandra)</title>
<para>Kea currently does not support storing reservations in
Cassandra (CQL).</para>
</section>
<section id="reservations4-tuning">
<title>Fine Tuning IPv4 Host Reservation</title>
<para>Host reservation capability introduces additional restrictions for the <para>Host reservation capability introduces additional restrictions for the
allocation engine during lease selection and renewal. In particular, three allocation engine during lease selection and renewal. In particular, three
major checks are necessary. First, when selecting a new lease, it is not major checks are necessary. First, when selecting a new lease, it is not
sufficient for a candidate lease to be not used by another DHCP client. It sufficient for a candidate lease to not be used by another DHCP client. It
also must not be reserved for another client. Second, when renewing a lease, also must not be reserved for another client. Second, when renewing a lease,
additional check must be performed whether the address being renewed is not additional check must be performed whether the address being renewed is not
reserved for another client. Finally, when a host renews an address, the server reserved for another client. Finally, when a host renews an address, the server
@@ -2745,6 +2823,53 @@ It is merely echoed by the server
} }
</screen> </screen>
</para> </para>
<para>Another aspect of the host reservations are different types of
identifiers. Currently (June 2016) Kea supports four types of identifiers
(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
usability perspective. However, there is a drawback. For each incoming
packet Kea has to to extract each identifier type and then query the
database to see if there's a reservation done by this particular
identifier. If there is not, the next identifier is extracted and the next
query is issued. This process continues until either a reservation is
found or all identifier types have been checked. Over time with an increasing
number of supported identifier types, Kea would become slower and
slower.</para>
<para>To address this problem, a parameter called
<command>host-reservation-identifiers</command> has been introduced. It
takes a list of identifier types as a parameter. Kea will check only those
identifier types enumerated in host-reservation-identifiers. From a
performance perspective the number of identifier types should be kept to a
minimum, ideally limited to one. If your deployment uses several
reservation types, please enumerate them from most to least frequently
used as this increases the chances of Kea finding the reservation using the
fewest number of queries. An example of host reservation identifiers looks
as follows:
<screen>
<userinput>"host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ],</userinput>
"subnet4": [
{
"subnet": "192.0.2.0/24",
...
}
]</screen>
</para>
<para>If not specified, the default value is:
<screen>
<userinput>"host-reservation-identifiers": [ "hw-address", "duid", "circuit-id" ]</userinput>
</screen>
<!-- see CfgHostOperations::createConfig4() in
src/lib/dhcpsrv/cfg_host_operations.cc -->
</para>
</section> </section>
</section> </section>
@@ -3283,12 +3408,12 @@ It is merely echoed by the server
</para> </para>
<para> <para>
The length of the path specified by the <command>socket-name</command> The length of the path specified by the <command>socket-name</command>
parameter is restricted by the maximum length for the unix socket name parameter is restricted by the maximum length for the unix socket name
on your operating system, i.e. the size of the <command>sun_path</command> on your operating system, i.e. the size of the <command>sun_path</command>
field in the <command>sockaddr_un</command> structure, decreased by 1. field in the <command>sockaddr_un</command> structure, decreased by 1.
This value varies on different operating systems between 91 and 107 This value varies on different operating systems between 91 and 107
characters. The typical values are 107 on Linux and 103 on FreeBSD. characters. The typical values are 107 on Linux and 103 on FreeBSD.
</para> </para>
<para> <para>

195
doc/guide/dhcp6-srv.xml
View File

@@ -11,10 +11,10 @@
<title>Starting and Stopping the DHCPv6 Server</title> <title>Starting and Stopping the DHCPv6 Server</title>
<para> <para>
It is recommended that the Kea DHCPv6 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"/>). using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
However, it is also possible to run the server directly: it accepts However, it is also possible to run the server directly: it accepts
the following command-line switches: the following command-line switches:
</para> </para>
<itemizedlist> <itemizedlist>
@@ -62,25 +62,25 @@
</itemizedlist> </itemizedlist>
<para> <para>
The <command>-V</command> command returns the versions of the The <command>-V</command> command returns the versions of the
external libraries dynamically linked. external libraries dynamically linked.
</para> </para>
<para> <para>
The <command>-W</command> command describes the environment used The <command>-W</command> command describes the environment used
to build Kea. This command displays a copy of the to build Kea. This command displays a copy of the
<filename>config.report</filename> file produced by <filename>config.report</filename> file produced by
<userinput>./configure</userinput> that is embedded in the <userinput>./configure</userinput> that is embedded in the
executable binary. executable binary.
</para> </para>
<para> <para>
The <filename>config.report</filename> may also be accessed more The <filename>config.report</filename> may also be accessed more
directly. The following command may be used to extract this directly. The following command may be used to extract this
information. The binary <userinput>path</userinput> may be found information. The binary <userinput>path</userinput> may be found
in the install directory or in the <filename>.libs</filename> in the install directory or in the <filename>.libs</filename>
subdirectory in the source tree. For example subdirectory in the source tree. For example
<filename>kea/src/bin/dhcp6/.libs/kea-dhcp6</filename>. <filename>kea/src/bin/dhcp6/.libs/kea-dhcp6</filename>.
<screen> <screen>
strings <userinput>path</userinput>/kea-dhcp6 | sed -n 's/;;;; //p' strings <userinput>path</userinput>/kea-dhcp6 | sed -n 's/;;;; //p'
@@ -88,9 +88,9 @@ strings <userinput>path</userinput>/kea-dhcp6 | sed -n 's/;;;; //p'
</para> </para>
<para> <para>
When running in a console, the server can be shut down by When running in a console, the server can be shut down by
pressing ctrl-c. It detects the key combination and shuts pressing ctrl-c. It detects the key combination and shuts
down gracefully. down gracefully.
</para> </para>
<para> <para>
@@ -479,22 +479,8 @@ If a timeout is given though, it should be an integer greater than zero.
</section> </section>
</section> </section>
<!-- Uncomment this once 4212 is merged. While the host storage for <section id="hosts6-storage">
MySQL is there, it is able to store hosts, but not IPv6
reservations. So technically we have host reservations for v6 in
MySQL, but in practice it's kinda useless right now as it can't
store addresses or prefixes. Let's keep it commented out until
we implement that functionality
<section>
<title>Hosts Storage</title> <title>Hosts Storage</title>
<note>
<para>This feature did not undergo the regular system level
testing conducted by ISC. As such, please treat it as
experimental.</para>
</note>
<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. Hosts database configuration uses the same syntax as lease database. Hosts database configuration uses the same syntax as lease
database. In fact, Kea server opens independent connections for each database. In fact, Kea server opens independent connections for each
@@ -2418,26 +2404,94 @@ should include options from the isc option space:
</section> </section>
<section id="reservation6-options"> <section id="reservation6-options">
<title>Reserving specific options</title> <title>Including specific DHCPv6 options in reservations</title>
<!-- @todo: replace this with the actual text once #3573 is implemented -->
<para>Currently it is not possible to specify options in host <para>Kea 1.1.0 introduced the ability to specify options on a
reservation. Such a feature will be added in the upcoming Kea per host basis. The options follow the same rules as any other
releases.</para> options. These can be standard options (see <xref
linkend="dhcp6-std-options" />), custom options (see <xref
linkend="dhcp6-custom-options"/>) or vendor specific options
(see <xref linkend="dhcp6-vendor-opts" />). The following
example showcases how standard options can be defined.</para>
<screen>
"reservations": [
{
"duid": "01:02:03:05:06:07:08",
"ip-addresses": [ "2001:db8:1::2" ],
<userinput>"option-data": [
{
"option-data": [ {
"name": "dns-servers",
"data": "3000:1::234"
},
{
"name": "nis-servers",
"data": "3000:1::234"
}
} ]</userinput>
} ]</screen>
<para>Vendor specific options can be reserved in a similar manner:</para>
<screen>
"reservations": [
{
"duid": "aa:bb:cc:dd:ee:ff",
"ip-addresses": [ "2001:db8::1" ],
<userinput>"option-data": [
{
"name": "vendor-opts",
"data": 4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
} ]</userinput>
} ]</screen>
<para>
Options defined on host level have the highest priority. In other words,
if there are options defined with the same type on global, subnet, class and
host level, the host specific values will be used.
</para>
</section> </section>
<section id="reservation6-mode"> <section id="reservations6-mysql">
<title>Fine Tuning IPv6 Host Reservation</title> <title>Storing host reservations in MySQL</title>
<note> <para>
<para><command>reservation-mode</command> in the DHCPv6 server is It is possible to store host reservations in MySQL. See <xref
implemented in Kea 0.9.1 beta, but has not been tested and is linkend="hosts6-storage" /> for information how to configure Kea to use
considered experimental.</para> reservations stored in MySQL. Kea does not provide any dedicated tools
</note> for managing MySQL reservations. See Kea wiki <ulink
url="http://kea.isc.org/wiki/HostReservationsHowTo" /> for detailed
information and examples of how reservations can be inserted into the
database.
</para>
</section>
<section id="reservations6-pgsql">
<title>Storing host reservations in PostgreSQL</title>
<para>Kea currently does not support storing reservations in
PostgreSQL, but this feature is planned for Kea 1.1.0.</para>
</section>
<section id="reservations6-cql">
<title>Storing host reservations in CQL (Cassandra)</title>
<para>Kea currently does not support storing reservations in
Cassandra (CQL).</para>
</section>
<section id="reservations6-tuning">
<title>Fine Tuning IPv6 Host Reservation</title>
<para>Host reservation capability introduces additional restrictions for the <para>Host reservation capability introduces additional restrictions for the
allocation engine during lease selection and renewal. In particular, three allocation engine during lease selection and renewal. In particular, three
major checks are necessary. First, when selecting a new lease, it is not major checks are necessary. First, when selecting a new lease, it is not
sufficient for a candidate lease to be not used by another DHCP client. It sufficient for a candidate lease to not be used by another DHCP client. It
also must not be reserved for another client. Second, when renewing a lease, also must not be reserved for another client. Second, when renewing a lease,
additional check must be performed whether the address being renewed is not additional check must be performed whether the address being renewed is not
reserved for another client. Finally, when a host renews an address or a reserved for another client. Finally, when a host renews an address or a
@@ -2493,6 +2547,51 @@ should include options from the isc option space:
} }
</screen> </screen>
</para> </para>
<para>Another aspect of the host reservations are different types of
identifiers. Currently (June 2016) Kea supports two types of identifiers
in DHCPv6: hw-address and duid, but more identifier types
are likely to be added in the future. This is beneficial from a
usability perspective. However, there is a drawback. For each incoming
packet Kea has to to extract each identifier type and then query the
database to see if there's a reservation done by this particular
identifier. If there is not, the next identifier is extracted and next
query is issued. This process continues until either a reservation is
found or all identifier types have been checked. Over time with an increasing
number of supported identifier types, Kea would become slower and
slower.</para>
<para>To address this problem, a parameter called
<command>host-reservation-identifiers</command> has been introduced. It
takes a list of identifier types as a parameter. Kea will check only those
identifier types enumerated in host-reservation-identifiers. From the
performance perspective the number of identifier types should be kept to
minimum, ideally limited to one. If your deployment uses several
reservation types, please enumerate them from most to least frequently
used as this increases the chances of Kea finding the reservation using the
fewest number of queries. An example of host reservation identifiers looks
as follows:
<screen>
<userinput>"host-reservation-identifiers": [ "duid", "hw-address" ],</userinput>
"subnet6": [
{
"subnet": "2001:db8:1::/64",
...
}
]</screen>
</para>
<para>
If not specified, the default value is:
<screen>
<userinput>"host-reservation-identifiers": [ "hw-address", "duid" ]</userinput>
</screen>
</para>
<!-- see CfgHostOperations::createConfig6() in
src/lib/dhcpsrv/cfg_host_operations.cc -->
</section> </section>
<!-- @todo: add support for per IA reservation (that specifies IAID in <!-- @todo: add support for per IA reservation (that specifies IAID in

4
src/lib/dhcpsrv/cfg_host_operations.cc
View File

@@ -17,6 +17,8 @@ CfgHostOperations::CfgHostOperations()
CfgHostOperationsPtr CfgHostOperationsPtr
CfgHostOperations::createConfig4() { CfgHostOperations::createConfig4() {
// If this list is modified, please update reservations4-tuning section in
// doc/guide/dhcp4-srv.xml
CfgHostOperationsPtr cfg(new CfgHostOperations()); CfgHostOperationsPtr cfg(new CfgHostOperations());
cfg->addIdentifierType("hw-address"); cfg->addIdentifierType("hw-address");
cfg->addIdentifierType("duid"); cfg->addIdentifierType("duid");
@@ -26,6 +28,8 @@ CfgHostOperations::createConfig4() {
CfgHostOperationsPtr CfgHostOperationsPtr
CfgHostOperations::createConfig6() { CfgHostOperations::createConfig6() {
// If this list is modified, please update reservations6-tuning section in
// doc/guide/dhcp6-srv.xml
CfgHostOperationsPtr cfg(new CfgHostOperations()); CfgHostOperationsPtr cfg(new CfgHostOperations());
cfg->addIdentifierType("hw-address"); cfg->addIdentifierType("hw-address");
cfg->addIdentifierType("duid"); cfg->addIdentifierType("duid");