Commit e73e9daf authored by Shawn Routhier's avatar Shawn Routhier
Browse files

[trac4518] Tidy up some typos and cut and paste errors during review

parent 728c4db7
......@@ -36,23 +36,23 @@
# 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 performance perspective to use only
# that reservation types that are actually used in a given network.
# 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.
# This example below is not the best from performance perspective, but it
# showcases the capabilities nicely. Please use the minimum set of identifier
# types used in your 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 performance perspective, as Kea would not only need to
# check if given address is free, but also whether it is reserved for anyone.
# To avoid this check, one change reservation-mode to out-of-pool, rather
# 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 set to 'disabled').
# lookup can be skipped altogether (reservation-mode is set to 'disabled').
# Note that the second reservation is for the address which is within the
# 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.
......@@ -63,15 +63,15 @@
"interface": "eth0",
"reservations": [
# This is a reservation for specific hardware/MAC address. It's a very
# 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 specific client-id. It also shows
# the this client will get reserved hostname. Hostname can be defined
# 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.
{
"client-id": "01:11:22:33:44:55:66",
......@@ -81,8 +81,8 @@
# The third reservation is based on DUID. This reservation also
# defines special option values for this particular client. If
# domain-name-servers option would be defined on global, subnet or class level,
# the host specific values take preference.
# 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",
......@@ -93,8 +93,8 @@
},
# The fourth reservation is based on circuit-id. This is an option inserted
# by relay agent that forwards the packet from client. In this example the
# host is also assigned vendor specific options.
# 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",
......
......@@ -27,9 +27,9 @@
# 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 those identifier types, but it takes a costly database lookup
# to do so. It is therefore useful from performance perspective to use only
# that reservation types that are actually used in a given network.
# 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
......@@ -50,15 +50,14 @@
],
"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" ]
......@@ -68,8 +67,8 @@
# 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 global, subnet or class scope, the values defined at host level
# takes precedence.
# 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" ],
......@@ -83,7 +82,7 @@
"data": "3000:1::234"
}]
},
# This is a bit more advanced reservation. The client with specified
# This is a bit more advanced reservation. The client with the specified
# DUID will get a reserved address, a reserved prefix and a hostname.
{
"duid": "01:02:03:04:05:06:07:08:09:0A",
......
......@@ -148,9 +148,9 @@
<section>
<title>Supported Databases</title>
<para>The following table presents capabilities of available
backends. Please refer to specific sections dedicated to each backend to
better understand the capabilities and limitations. Choosing the right
<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>
......@@ -172,6 +172,7 @@
</row>
</thead>
<tbody>
<row>
<entry>Status</entry>
<entry>Stable</entry>
......@@ -221,7 +222,7 @@
<title>memfile</title>
<para>
Memfile backend is able to store leases information, but is not able to
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.
......@@ -585,7 +586,7 @@ $ <userinput>kea-admin lease-init pgsql -u <replaceable>database-user</replaceab
<para>
Cassandra, or Cassandra Query Language (CQL), is the newest backend
added to Kea. Since it was added recently and have not undergone as much
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
......
......@@ -2443,11 +2443,11 @@ It is merely echoed by the server
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>
<para>In Kea 1.1.0 it was only possible to create host reservations
<para>In Kea 1.0.0 it was only possible to create host reservations
using client's hardware address. Host reservations by client
identifier, DUID and circuit-id have been added in Kea 1.1.0.</para>
......@@ -2475,7 +2475,7 @@ It is merely echoed by the server
"ip-address": "192.0.2.203"
},
{
"client-id": "01:11:22:33:44:55:66\","
"client-id": "01:11:22:33:44:55:66",
"ip-address": "192.0.2.204"
}
]</userinput>
......@@ -2483,14 +2483,14 @@ It is merely echoed by the server
]
</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 DUID
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 circuid-it option
with value 'charter950'. The fourth entry reserves address
192.0.2.204 for a client that uses client identifier with value
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>Note that the above example is used for ilustrational purposes only
......@@ -2700,7 +2700,7 @@ It is merely echoed by the server
} ]</userinput>
} ]</screen>
<para>Vendor specific options can be reserved in similar manner:</para>
<para>Vendor specific options can be reserved in a similar manner:</para>
<screen>
"reservations": [
......@@ -2708,21 +2708,20 @@ It is merely echoed by the server
"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>
{
"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 option defined with the same type on global, subnet, class and
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>
......@@ -2733,7 +2732,7 @@ It is merely echoed by the server
<para>
It is possible to store host reservations in MySQL. See <xref
linkend="hosts6-storage" /> for information how to configure Kea to use
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
......@@ -2761,7 +2760,7 @@ It is merely echoed by the server
<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
......@@ -2822,25 +2821,25 @@ It is merely echoed by the server
<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 the
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
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 were checked. Over time with increasing
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
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
fewer number of queries. An example of host reservation identifiers looks
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>
......@@ -2853,7 +2852,7 @@ It is merely echoed by the server
]</screen>
</para>
<para>If not specified, the default value is <command>hw-address, duid,
<para>If not specified, the default value is: <command>hw-address, duid,
circuit-id</command>.</para> <!-- see CfgHostOperations::createConfig4() in
src/lib/dhcpsrv/cfg_host_operations.cc -->
......
......@@ -2417,12 +2417,10 @@ should include options from the isc option space:
<screen>
"reservations": [
{
"hw-address": "aa:bb:cc:dd:ee:ff",
"ip-address": "192.0.2.1",
"duid": "01:02:03:05:06:07:08",
"ip-addresses": [ "2001:db8:1::2" ],
<userinput>"option-data": [
{
"duid": "01:02:03:05:06:07:08",
"ip-addresses": [ "2001:db8:1::2" ],
"option-data": [ {
"name": "dns-servers",
"data": "3000:1::234"
......@@ -2434,7 +2432,7 @@ should include options from the isc option space:
} ]</userinput>
} ]</screen>
<para>Vendor specific options can be reserved in similar manner:</para>
<para>Vendor specific options can be reserved in a similar manner:</para>
<screen>
"reservations": [
......@@ -2454,8 +2452,8 @@ should include options from the isc option space:
} ]</screen>
<para>
Options defined on host level have the highest priority. In other words,
if there are option defined with the same type on global, subnet, class and
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>
......@@ -2493,7 +2491,7 @@ should include options from the isc option space:
<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
......@@ -2553,13 +2551,13 @@ should include options from the isc option space:
<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 the
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 were checked. Over time with increasing
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>
......@@ -2570,22 +2568,22 @@ should include options from the isc option space:
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
fewer number of queries. An example of host reservation identifiers looks
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>
"subnet4": [
"subnet6": [
{
"subnet": "192.0.2.0/24",
"subnet": "2001:db8:1::/64",
...
}
]</screen>
</para>
<para>
If not specified, the default value is <command>hw-address,duid</command>.
If not specified, the default value is: <command>hw-address,duid</command>.
</para>
<!-- see CfgHostOperations::createConfig6() in
src/lib/dhcpsrv/cfg_host_operations.cc -->
......
......@@ -17,7 +17,7 @@ CfgHostOperations::CfgHostOperations()
CfgHostOperationsPtr
CfgHostOperations::createConfig4() {
// If this list modified, please update reservations4-tuning section in
// If this list is modified, please update reservations4-tuning section in
// doc/guide/dhcp4-srv.xml
CfgHostOperationsPtr cfg(new CfgHostOperations());
cfg->addIdentifierType("hw-address");
......@@ -28,7 +28,7 @@ CfgHostOperations::createConfig4() {
CfgHostOperationsPtr
CfgHostOperations::createConfig6() {
// If this list modified, please update reservations6-tuning section in
// If this list is modified, please update reservations6-tuning section in
// doc/guide/dhcp6-srv.xml
CfgHostOperationsPtr cfg(new CfgHostOperations());
cfg->addIdentifierType("hw-address");
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment