mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-30 05:27:55 +00:00
[master]Merge branch 'trac4518' (host reservations doc update)
This commit is contained in:
Tomek Mrugalski
commit
99a40fead2
@ -30,28 +30,88 @@
|
||||
# "renew-timer": 1000,
|
||||
# "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
|
||||
# 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.
|
||||
|
||||
# Kea supports reservations by several different types of identifiers:
|
||||
# hw-address (hardware/MAC address of the client), duid (DUID inserted by the
|
||||
# client), client-id (client identifier inserted by the client) and circuit-id
|
||||
# (circuit identifier inserted by the relay agent). When told to do so, Kea can
|
||||
# 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": [
|
||||
{
|
||||
"pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
|
||||
"subnet": "192.0.2.0/24",
|
||||
"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",
|
||||
"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",
|
||||
"ip-address": "192.0.2.100"
|
||||
"client-id": "01:11:22:33:44:55:66",
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
|
||||
@ -25,6 +25,13 @@
|
||||
"renew-timer": 1000,
|
||||
"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
|
||||
# are the same as in the regular scenario, without host reservations.
|
||||
# least subnet and pool entries.
|
||||
@ -43,33 +50,59 @@
|
||||
],
|
||||
"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.
|
||||
# Host reservations. Define several reservations, note that
|
||||
# they are all within the range of the pool of the dynamically
|
||||
# allocated address. The server will exclude the addresses from this
|
||||
# pool and only assign them to the client which has a reservation for
|
||||
# them.
|
||||
"reservations": [
|
||||
# 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",
|
||||
"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.
|
||||
# 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",
|
||||
"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
|
||||
# DUID will get a reserved address, prefix and a hostname.
|
||||
# This is a bit more advanced reservation. The client with the specified
|
||||
# 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",
|
||||
"ip-addresses": [ "2001:db8:1::102" ],
|
||||
"ip-addresses": [ "2001:db8:1:cafe::1" ],
|
||||
"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"
|
||||
} ]
|
||||
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@ -148,9 +148,86 @@
|
||||
<section>
|
||||
<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>
|
||||
<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>
|
||||
There are no special initialization steps necessary
|
||||
for the memfile backend. During the first run, both
|
||||
@ -158,6 +235,7 @@
|
||||
will create an empty lease file if one is not
|
||||
present. Necessary disk write permission is required.
|
||||
</para>
|
||||
|
||||
<section id="memfile-upgrade">
|
||||
<title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title>
|
||||
<para>
|
||||
@ -185,13 +263,17 @@
|
||||
<section>
|
||||
<title>MySQL</title>
|
||||
|
||||
<para>
|
||||
MySQL is able to store leases, host reservations and options defined on
|
||||
a per host basis.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The MySQL database must be properly set up if you want Kea to
|
||||
store information in MySQL. This section can be safely ignored
|
||||
if you chose to store the data in other backends.
|
||||
</para>
|
||||
|
||||
|
||||
<section id="mysql-database-create">
|
||||
<title>First Time Creation of Kea Database</title>
|
||||
|
||||
@ -327,6 +409,12 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
|
||||
<section>
|
||||
<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>
|
||||
A PostgreSQL database must be set up if you want Kea to store
|
||||
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>
|
||||
<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>
|
||||
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
|
||||
|
||||
@ -10,13 +10,11 @@
|
||||
<section id="dhcp4-start-stop">
|
||||
<title>Starting and Stopping the DHCPv4 Server</title>
|
||||
|
||||
<!-- @todo Rewrite this section once #3422 is done -->
|
||||
|
||||
<para>
|
||||
It is recommended that the Kea DHCPv4 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:
|
||||
It is recommended that the Kea DHCPv4 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:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
@ -64,25 +62,25 @@
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
The <command>-V</command> command returns the versions of the
|
||||
external libraries dynamically linked.
|
||||
The <command>-V</command> command returns the versions of the
|
||||
external libraries dynamically linked.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <command>-W</command> command describes the environment used
|
||||
to build Kea. This command displays a copy of the
|
||||
<filename>config.report</filename> file produced by
|
||||
<userinput>./configure</userinput> that is embedded in the
|
||||
executable binary.
|
||||
The <command>-W</command> command describes the environment used
|
||||
to build Kea. This command displays a copy of the
|
||||
<filename>config.report</filename> file produced by
|
||||
<userinput>./configure</userinput> that is embedded in the
|
||||
executable binary.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>config.report</filename> may also be accessed more
|
||||
directly. The following command may be used to extract this
|
||||
information. The binary <userinput>path</userinput> may be found
|
||||
in the install directory or in the <filename>.libs</filename>
|
||||
subdirectory in the source tree. For example
|
||||
<filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>.
|
||||
The <filename>config.report</filename> may also be accessed more
|
||||
directly. The following command may be used to extract this
|
||||
information. The binary <userinput>path</userinput> may be found
|
||||
in the install directory or in the <filename>.libs</filename>
|
||||
subdirectory in the source tree. For example
|
||||
<filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>.
|
||||
|
||||
<screen>
|
||||
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>
|
||||
When running in a console, the server can be shut down by
|
||||
pressing ctrl-c. It detects the key combination and shuts
|
||||
down gracefully.
|
||||
When running in a console, the server can be shut down by
|
||||
pressing ctrl-c. It detects the key combination and shuts
|
||||
down gracefully.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -481,13 +479,7 @@ If a timeout is given though, it should be an integer greater than zero.
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<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>
|
||||
<title id="hosts4-storage">Hosts Storage</title>
|
||||
|
||||
<para>Kea is also able to store information about host reservations in the
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
The following configuration will assign the specified subnet
|
||||
identifier to the newly configured subnet:
|
||||
The following configuration will assign the specified subnet
|
||||
identifier to the newly configured subnet:
|
||||
|
||||
<screen>
|
||||
"Dhcp4": {
|
||||
@ -1435,7 +1427,7 @@ It is merely echoed by the server
|
||||
"type": "ipv4-address",
|
||||
"record-types": "",
|
||||
"array": false,
|
||||
"encapsulate ""
|
||||
"encapsulate": ""
|
||||
},
|
||||
{
|
||||
"name": "subopt2",
|
||||
@ -2444,23 +2436,18 @@ It is merely echoed by the server
|
||||
near future.</para>
|
||||
|
||||
<para>Hosts reservations are defined as parameters for each subnet. Each host
|
||||
has to be identified by its hardware/MAC address. There is an optional
|
||||
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>
|
||||
element. Each element in that array is a structure, that holds information
|
||||
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
|
||||
identifier is a hardware or MAC address. In most cases, also an address
|
||||
will be specified. It is possible to specify a hostname. Additional
|
||||
capabilities are planned.</para>
|
||||
identifier is a hardware or MAC address. In most cases an address
|
||||
will be specified. It is also possible to specify a hostname or host
|
||||
specific options. Additional capabilities are planned.</para>
|
||||
|
||||
<note><para>In Kea 1.0.0 it is only possible to create host reservations
|
||||
using client's hardware address. Host reservations by client identifier
|
||||
(or DUID) are not supported in this version of Kea. This capability will
|
||||
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>In Kea 1.0.0 it was only possible to create host reservations
|
||||
using client's hardware address. Host reservations by client
|
||||
identifier, DUID and circuit-id have been added in Kea 1.1.0.</para>
|
||||
|
||||
<para>The following example shows how to reserve addresses for specific
|
||||
hosts:
|
||||
@ -2477,20 +2464,37 @@ It is merely echoed by the server
|
||||
"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",
|
||||
"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>
|
||||
}
|
||||
]
|
||||
</screen>
|
||||
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
|
||||
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>
|
||||
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 the client using a DUID
|
||||
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. The third
|
||||
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
|
||||
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 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>
|
||||
<title>Including specific DHCPv4 options in reservations</title>
|
||||
<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
|
||||
options. These can be standard options (see <xref
|
||||
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 id="reservation4-mode">
|
||||
<title>Fine Tuning IPv4 Host Reservation</title>
|
||||
<section id="reservations4-mysql">
|
||||
<title>Storing host reservations in MySQL</title>
|
||||
|
||||
<note>
|
||||
<para><command>reservation-mode</command> configuration parameter in DHCPv4
|
||||
server is accepted, but not used in the Kea 0.9.1 beta. Full implementation
|
||||
will be available in the upcoming releases.</para>
|
||||
</note>
|
||||
<para>
|
||||
It is possible to store host reservations in MySQL. See <xref
|
||||
linkend="hosts4-storage" /> for information on how to configure Kea to use
|
||||
reservations stored in MySQL. Kea does not provide any dedicated tools
|
||||
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
|
||||
allocation engine during lease selection and renewal. In particular, three
|
||||
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,
|
||||
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
|
||||
@ -2745,6 +2823,53 @@ It is merely echoed by the server
|
||||
}
|
||||
</screen>
|
||||
</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>
|
||||
@ -3283,12 +3408,12 @@ It is merely echoed by the server
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The length of the path specified by the <command>socket-name</command>
|
||||
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>
|
||||
field in the <command>sockaddr_un</command> structure, decreased by 1.
|
||||
This value varies on different operating systems between 91 and 107
|
||||
characters. The typical values are 107 on Linux and 103 on FreeBSD.
|
||||
The length of the path specified by the <command>socket-name</command>
|
||||
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>
|
||||
field in the <command>sockaddr_un</command> structure, decreased by 1.
|
||||
This value varies on different operating systems between 91 and 107
|
||||
characters. The typical values are 107 on Linux and 103 on FreeBSD.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
@ -11,10 +11,10 @@
|
||||
<title>Starting and Stopping the DHCPv6 Server</title>
|
||||
|
||||
<para>
|
||||
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:
|
||||
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:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
@ -62,25 +62,25 @@
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
The <command>-V</command> command returns the versions of the
|
||||
external libraries dynamically linked.
|
||||
The <command>-V</command> command returns the versions of the
|
||||
external libraries dynamically linked.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <command>-W</command> command describes the environment used
|
||||
to build Kea. This command displays a copy of the
|
||||
<filename>config.report</filename> file produced by
|
||||
<userinput>./configure</userinput> that is embedded in the
|
||||
executable binary.
|
||||
The <command>-W</command> command describes the environment used
|
||||
to build Kea. This command displays a copy of the
|
||||
<filename>config.report</filename> file produced by
|
||||
<userinput>./configure</userinput> that is embedded in the
|
||||
executable binary.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>config.report</filename> may also be accessed more
|
||||
directly. The following command may be used to extract this
|
||||
information. The binary <userinput>path</userinput> may be found
|
||||
in the install directory or in the <filename>.libs</filename>
|
||||
subdirectory in the source tree. For example
|
||||
<filename>kea/src/bin/dhcp6/.libs/kea-dhcp6</filename>.
|
||||
The <filename>config.report</filename> may also be accessed more
|
||||
directly. The following command may be used to extract this
|
||||
information. The binary <userinput>path</userinput> may be found
|
||||
in the install directory or in the <filename>.libs</filename>
|
||||
subdirectory in the source tree. For example
|
||||
<filename>kea/src/bin/dhcp6/.libs/kea-dhcp6</filename>.
|
||||
|
||||
<screen>
|
||||
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>
|
||||
When running in a console, the server can be shut down by
|
||||
pressing ctrl-c. It detects the key combination and shuts
|
||||
down gracefully.
|
||||
When running in a console, the server can be shut down by
|
||||
pressing ctrl-c. It detects the key combination and shuts
|
||||
down gracefully.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -479,22 +479,8 @@ If a timeout is given though, it should be an integer greater than zero.
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<!-- Uncomment this once 4212 is merged. While the host storage for
|
||||
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>
|
||||
<section id="hosts6-storage">
|
||||
<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
|
||||
database. Hosts database configuration uses the same syntax as lease
|
||||
database. In fact, Kea server opens independent connections for each
|
||||
@ -2418,26 +2404,94 @@ should include options from the isc option space:
|
||||
</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>
|
||||
<title>Including specific DHCPv6 options in reservations</title>
|
||||
|
||||
<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
|
||||
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 id="reservation6-mode">
|
||||
<title>Fine Tuning IPv6 Host Reservation</title>
|
||||
<section id="reservations6-mysql">
|
||||
<title>Storing host reservations in MySQL</title>
|
||||
|
||||
<note>
|
||||
<para><command>reservation-mode</command> in the DHCPv6 server is
|
||||
implemented in Kea 0.9.1 beta, but has not been tested and is
|
||||
considered experimental.</para>
|
||||
</note>
|
||||
<para>
|
||||
It is possible to store host reservations in MySQL. See <xref
|
||||
linkend="hosts6-storage" /> for information how to configure Kea to use
|
||||
reservations stored in MySQL. Kea does not provide any dedicated tools
|
||||
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
|
||||
allocation engine during lease selection and renewal. In particular, three
|
||||
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,
|
||||
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
|
||||
@ -2493,6 +2547,51 @@ should include options from the isc option space:
|
||||
}
|
||||
</screen>
|
||||
</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>
|
||||
|
||||
<!-- @todo: add support for per IA reservation (that specifies IAID in
|
||||
|
||||
@ -17,6 +17,8 @@ CfgHostOperations::CfgHostOperations()
|
||||
|
||||
CfgHostOperationsPtr
|
||||
CfgHostOperations::createConfig4() {
|
||||
// If this list is modified, please update reservations4-tuning section in
|
||||
// doc/guide/dhcp4-srv.xml
|
||||
CfgHostOperationsPtr cfg(new CfgHostOperations());
|
||||
cfg->addIdentifierType("hw-address");
|
||||
cfg->addIdentifierType("duid");
|
||||
@ -26,6 +28,8 @@ CfgHostOperations::createConfig4() {
|
||||
|
||||
CfgHostOperationsPtr
|
||||
CfgHostOperations::createConfig6() {
|
||||
// If this list is modified, please update reservations6-tuning section in
|
||||
// doc/guide/dhcp6-srv.xml
|
||||
CfgHostOperationsPtr cfg(new CfgHostOperations());
|
||||
cfg->addIdentifierType("hw-address");
|
||||
cfg->addIdentifierType("duid");
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user