From b939bf7dbdb4e035a8d6cd22cfcea8ee245ab128 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Tue, 28 Jun 2016 20:11:16 +0200 Subject: [PATCH 1/7] [4518] User's Guide, examples updated for DHCPv4 --- doc/examples/kea4/reservations.json | 80 ++++++++++++-- doc/guide/admin.xml | 98 ++++++++++++++++- doc/guide/dhcp4-srv.xml | 164 ++++++++++++++++++++++------ 3 files changed, 295 insertions(+), 47 deletions(-) diff --git a/doc/examples/kea4/reservations.json b/doc/examples/kea4/reservations.json index 954d84a48f..9b6cfbf941 100644 --- a/doc/examples/kea4/reservations.json +++ b/doc/examples/kea4/reservations.json @@ -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 several 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 performance perspective to use only +# that 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. +"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 +# than 'all'. If a subnet does not have reservations at all, the reservation +# lookup can be skipped altogether (reservation-mode set to 'disabled'). + +# Note that the second reservation is 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. "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 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 +# 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 +# domain-name-servers option would be defined on 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 relay agent that forwards the packet from client. 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" + } + ] } ] - } + } ] }, diff --git a/doc/guide/admin.xml b/doc/guide/admin.xml index 8fa45140eb..0f507bd0e0 100644 --- a/doc/guide/admin.xml +++ b/doc/guide/admin.xml @@ -148,9 +148,85 @@
Supported Databases + 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 + backend may be essential for success or failure of your deployment. + + + + List of available backends + + + + + + + + + Feature + Memfile + MySQL + PostgreSQL + CQL(Cassandra) + + + + + Status + Stable + Stable + Stable + Experimental + + + + Data format + coma separated file + SQL RMDB + SQL RMDB + NoSQL database (CQL) + + + + Leases + yes + yes + yes + yes + + + + Host Reservations + no + yes + no + no + + + + Options defined on per host basis + no + yes + no + no + + + + +
+ +
memfile + + Memfile backend is able to store leases 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. + + There are no special initialization steps necessary for the memfile backend. During the first run, both @@ -158,6 +234,7 @@ will create an empty lease file if one is not present. Necessary disk write permission is required. +
Upgrading Memfile Lease Files from an Earlier Version of Kea @@ -185,13 +262,17 @@
MySQL + + MySQL is able to store leases, host reservations and options defined on + a per host basis. + + 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. -
First Time Creation of Kea Database @@ -327,6 +408,12 @@ $ kea-admin lease-upgrade mysql -u database-user PostgreSQL + + 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. + + 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 +583,15 @@ $ kea-admin lease-init pgsql -u database-user CQL (Cassandra) + + Cassandra, or Cassandra Query Language (CQL), is the newest backend + added to Kea. Since it was added recently and have 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. + + 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 diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index a0f422e37c..beea6e910d 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -90,9 +90,9 @@ strings path/kea-dhcp4 | sed -n 's/;;;; //p' - 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. @@ -750,8 +750,8 @@ temporarily override a list of interface names and listen on all interfaces. manually specify a unique identifier for each subnet. - 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: "Dhcp4": { @@ -2444,7 +2444,7 @@ It is merely echoed by the server near future. 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 reservations array in the Subnet4 element. Each element in that array is a structure, that holds information about reservations for a single host. In particular, such a structure has @@ -2453,14 +2453,9 @@ It is merely echoed by the server will be specified. It is possible to specify a hostname. Additional capabilities are planned. - 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. + In Kea 1.1.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. The following example shows how to reserve addresses for specific hosts: @@ -2477,9 +2472,17 @@ 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" } ] } @@ -2487,10 +2490,19 @@ It is merely echoed by the server 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. - + 192.0.2.100 and the hostname of alice-laptop for client using 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 + 01:11:22:33:44:55:66. + + Note that 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 for detailed + discussion. 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. @@ -2670,21 +2682,61 @@ It is merely echoed by the server
Reserving specific options - - Currently it is not possible to specify options in host - reservation. Such a feature will be added in the upcoming Kea - releases. + 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 ), custom options (see ) or vendor specific options + (see ). The following + example showcases how standard options can be defined. + + +"reservations": [ +{ + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "192.0.2.1", + "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" + } ] +} ] + + Vendor specific options can be reserved in similar manner: + + +"reservations": [ +{ + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "10.0.0.7", + "option-data": [ + { + "name": "vivso-suboptions"," + "data": "4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "10.1.1.202,10.1.1.203" + } + ] +} ] + + + 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 + host level, the host specific values will be used. + +
-
+
Fine Tuning IPv4 Host Reservation - - reservation-mode 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. - - 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 @@ -2745,6 +2797,46 @@ It is merely echoed by the server } + + 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 + 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 + number of supported identifier types, Kea would become slower and + slower. + + To address this problem, a parameter called + host-reservation-identifiers 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 + fewer number of queries. An example of host reservation identifiers looks + as follows: + + +"host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ], +"subnet4": [ + { + "subnet": "192.0.2.0/24", + ... + } +] + + +If not specified, the default value is hw-address, duid, +circuit-id. + +
@@ -3283,12 +3375,12 @@ It is merely echoed by the server - The length of the path specified by the socket-name - parameter is restricted by the maximum length for the unix socket name - on your operating system, i.e. the size of the sun_path - field in the sockaddr_un 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 socket-name + parameter is restricted by the maximum length for the unix socket name + on your operating system, i.e. the size of the sun_path + field in the sockaddr_un 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. From 6f4e9166ad626809bc15310540512739393a42f9 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Wed, 29 Jun 2016 13:43:21 +0200 Subject: [PATCH 2/7] [4518] Documentation for DHCPv6 reservations updated. --- doc/examples/kea4/reservations.json | 2 +- doc/examples/kea6/reservations.json | 28 ++++++- doc/guide/dhcp4-srv.xml | 4 +- doc/guide/dhcp6-srv.xml | 107 ++++++++++++++++++++++--- src/lib/dhcpsrv/cfg_host_operations.cc | 4 + 5 files changed, 127 insertions(+), 18 deletions(-) diff --git a/doc/examples/kea4/reservations.json b/doc/examples/kea4/reservations.json index 9b6cfbf941..415ef1b250 100644 --- a/doc/examples/kea4/reservations.json +++ b/doc/examples/kea4/reservations.json @@ -31,7 +31,7 @@ # "rebind-timer": 2000, -# Kea supports several reservations by several different types of identifiers: +# 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 diff --git a/doc/examples/kea6/reservations.json b/doc/examples/kea6/reservations.json index 6162fc1730..275b0a9b41 100644 --- a/doc/examples/kea6/reservations.json +++ b/doc/examples/kea6/reservations.json @@ -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 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. + "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. @@ -58,13 +65,26 @@ }, # 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 global, subnet or class scope, the values defined at host level +# takes 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 specified +# DUID will get a reserved address, a reserved prefix and a hostname. { "duid": "01:02:03:04:05:06:07:08:09:0A", "ip-addresses": [ "2001:db8:1::102" ], diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index beea6e910d..7e9f792638 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2501,7 +2501,7 @@ It is merely echoed by the server Note that 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 for detailed + (preferably just one). See for detailed discussion. Making a reservation for a mobile host that may visit multiple subnets @@ -2734,7 +2734,7 @@ It is merely echoed by the server
-
+
Fine Tuning IPv4 Host Reservation Host reservation capability introduces additional restrictions for the diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index aad1159738..6d7e46d74a 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2419,21 +2419,65 @@ should include options from the isc option space:
Reserving specific options - - Currently it is not possible to specify options in host - reservation. Such a feature will be added in the upcoming Kea - releases. + + 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 ), custom options (see ) or vendor specific options + (see ). The following + example showcases how standard options can be defined. + + +"reservations": [ +{ + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "192.0.2.1", + "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" + }, + { + "name": "nis-servers", + "data": "3000:1::234" + } + } ] +} ] + + Vendor specific options can be reserved in similar manner: + + +"reservations": [ +{ + "duid": "aa:bb:cc:dd:ee:ff", + "ip-addresses": [ "2001:db8::1" ], + "option-data": [ + { + "name": "vendor-opts", + "data": 4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "3000:1::234" + } ] +} ] + + + 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 + host level, the host specific values will be used. + +
-
+
Fine Tuning IPv6 Host Reservation - - reservation-mode in the DHCPv6 server is - implemented in Kea 0.9.1 beta, but has not been tested and is - considered experimental. - - 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 @@ -2493,6 +2537,47 @@ should include options from the isc option space: } + + 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 + 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 + number of supported identifier types, Kea would become slower and + slower. + + To address this problem, a parameter called + host-reservation-identifiers 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 + fewer number of queries. An example of host reservation identifiers looks + as follows: + + +"host-reservation-identifiers": [ "duid", "hw-address" ], +"subnet4": [ + { + "subnet": "192.0.2.0/24", + ... + } +] + + + + If not specified, the default value is hw-address,duid. + + +
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index aaba3f7f0e..975c807c86 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2417,12 +2417,10 @@ should include options from the isc option space: "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" ], "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: } ] } ] - Vendor specific options can be reserved in similar manner: + Vendor specific options can be reserved in a similar manner: "reservations": [ @@ -2454,8 +2452,8 @@ should include options from the isc option space: } ] - 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. @@ -2493,7 +2491,7 @@ should include options from the isc option space: 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: 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. @@ -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: "host-reservation-identifiers": [ "duid", "hw-address" ], -"subnet4": [ +"subnet6": [ { - "subnet": "192.0.2.0/24", + "subnet": "2001:db8:1::/64", ... } ] - If not specified, the default value is hw-address,duid. + If not specified, the default value is: hw-address,duid. diff --git a/src/lib/dhcpsrv/cfg_host_operations.cc b/src/lib/dhcpsrv/cfg_host_operations.cc index e2f584d3d7..6a19f1b454 100644 --- a/src/lib/dhcpsrv/cfg_host_operations.cc +++ b/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"); From cba07cb92b7e84c3d8ca69f19c65a0ef03d447c5 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Tue, 5 Jul 2016 14:27:25 +0200 Subject: [PATCH 5/7] [4518] Changes after review: - added vendor options example and made it out-of-pool in kea6/reservations.json - fixed couple indents in dhcp{4,6}-srv.xml - added enclosing subnet4 where it was missing in examples - renamed section dedicated to option reservations - default value of host-reservation-identifiers presented differently --- doc/examples/kea6/reservations.json | 18 +++++- doc/guide/dhcp4-srv.xml | 87 ++++++++++++++++------------- doc/guide/dhcp6-srv.xml | 48 ++++++++-------- 3 files changed, 90 insertions(+), 63 deletions(-) diff --git a/doc/examples/kea6/reservations.json b/doc/examples/kea6/reservations.json index 9f568fa666..79bf115575 100644 --- a/doc/examples/kea6/reservations.json +++ b/doc/examples/kea6/reservations.json @@ -84,11 +84,25 @@ }, # 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" + } ] + } ] } diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 3eddc4fec0..81a36533aa 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -10,13 +10,11 @@
Starting and Stopping the DHCPv4 Server - - - It is recommended that the Kea DHCPv4 server be started and stopped - using keactrl (described in ). - 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 keactrl (described in ). + However, it is also possible to run the server directly: it accepts + the following command-line switches: @@ -64,25 +62,25 @@ - The -V command returns the versions of the - external libraries dynamically linked. + The -V command returns the versions of the + external libraries dynamically linked. - The -W command describes the environment used - to build Kea. This command displays a copy of the - config.report file produced by - ./configure that is embedded in the - executable binary. + The -W command describes the environment used + to build Kea. This command displays a copy of the + config.report file produced by + ./configure that is embedded in the + executable binary. - The config.report may also be accessed more - directly. The following command may be used to extract this - information. The binary path may be found - in the install directory or in the .libs - subdirectory in the source tree. For example - kea/src/bin/dhcp4/.libs/kea-dhcp4. + The config.report may also be accessed more + directly. The following command may be used to extract this + information. The binary path may be found + in the install directory or in the .libs + subdirectory in the source tree. For example + kea/src/bin/dhcp4/.libs/kea-dhcp4. strings path/kea-dhcp4 | sed -n 's/;;;; //p' @@ -90,9 +88,9 @@ strings path/kea-dhcp4 | sed -n 's/;;;; //p' - 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. @@ -2493,7 +2491,7 @@ It is merely echoed by the server 192.0.2.204 for a client that uses a client identifier with value 01:11:22:33:44:55:66. - Note that the above example is used for ilustrational purposes only + 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 for detailed discussion. @@ -2675,7 +2673,7 @@ It is merely echoed by the server
- Reserving specific options + Including specific DHCPv4 options in reservations 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 -"reservations": [ { - "hw-address": "aa:bb:cc:dd:ee:ff", - "ip-address": "192.0.2.1", - "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" - } ] -} ] + "subnet4": [ { + "reservations": [ + { + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "192.0.2.1", + "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" + } ] + } ] + } ] +} Vendor specific options can be reserved in a similar manner: @@ -2852,10 +2854,17 @@ It is merely echoed by the server ] -If not specified, the default value is: hw-address, duid, -circuit-id. + + +
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 975c807c86..6cdee0b6bf 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -11,10 +11,10 @@ Starting and Stopping the DHCPv6 Server - It is recommended that the Kea DHCPv6 server be started and stopped - using keactrl (described in ). - 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 keactrl (described in ). + However, it is also possible to run the server directly: it accepts + the following command-line switches: @@ -62,25 +62,25 @@ - The -V command returns the versions of the - external libraries dynamically linked. + The -V command returns the versions of the + external libraries dynamically linked. - The -W command describes the environment used - to build Kea. This command displays a copy of the - config.report file produced by - ./configure that is embedded in the - executable binary. + The -W command describes the environment used + to build Kea. This command displays a copy of the + config.report file produced by + ./configure that is embedded in the + executable binary. - The config.report may also be accessed more - directly. The following command may be used to extract this - information. The binary path may be found - in the install directory or in the .libs - subdirectory in the source tree. For example - kea/src/bin/dhcp6/.libs/kea-dhcp6. + The config.report may also be accessed more + directly. The following command may be used to extract this + information. The binary path may be found + in the install directory or in the .libs + subdirectory in the source tree. For example + kea/src/bin/dhcp6/.libs/kea-dhcp6. strings path/kea-dhcp6 | sed -n 's/;;;; //p' @@ -88,9 +88,9 @@ strings path/kea-dhcp6 | sed -n 's/;;;; //p' - 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. @@ -2404,7 +2404,7 @@ should include options from the isc option space:
- Reserving specific options + Including specific DHCPv6 options in reservations Kea 1.1.0 introduced the ability to specify options on a per host basis. The options follow the same rules as any other @@ -2583,7 +2583,11 @@ should include options from the isc option space: - If not specified, the default value is: hw-address,duid. + If not specified, the default value is: + +"host-reservation-identifiers": [ "hw-address", "duid" ] + + From 589bf2cb3ebdbd752192df87aac83715fc1f8623 Mon Sep 17 00:00:00 2001 From: Shawn Routhier Date: Tue, 5 Jul 2016 14:04:42 -0700 Subject: [PATCH 6/7] [4518] Fix typo in custom options example --- doc/guide/dhcp4-srv.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 81a36533aa..6578e4487b 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1427,7 +1427,7 @@ It is merely echoed by the server "type": "ipv4-address", "record-types": "", "array": false, - "encapsulate "" + "encapsulate": "" }, { "name": "subopt2", From 990ce652a04d6cacbd39aa02f3e28c14f0ab4baa Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Wed, 6 Jul 2016 12:03:00 +0200 Subject: [PATCH 7/7] [4518] One reservation example updated. --- doc/guide/dhcp4-srv.xml | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 6578e4487b..d869021a17 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2705,21 +2705,25 @@ It is merely echoed by the server Vendor specific options can be reserved in a similar manner: -"reservations": [ { - "hw-address": "aa:bb:cc:dd:ee:ff", - "ip-address": "10.0.0.7", - "option-data": [ - { - "name": "vivso-suboptions", - "data": "4491" - }, - { - "name": "tftp-servers", - "space": "vendor-4491", - "data": "10.1.1.202,10.1.1.203" - } ] -} ] + "subnet4": [ { + "reservations": [ + { + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "10.0.0.7", + "option-data": [ + { + "name": "vivso-suboptions", + "data": "4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "10.1.1.202,10.1.1.203" + } ] + } ] + } ] +} Options defined on host level have the highest priority. In other words,