[#1299] document host reservations

diff --git a/ChangeLog b/ChangeLog
index 640276eb58d9cb2a2242e662e1b1cd8721d282b8..6051e70b11521f6ec381495bb9e7ab1b4132094b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+1818.  [doc]           andrei
+       Add to the reservation documentation:
+       * instructions on how to choose "reservation-mode"
+       * priority of "reservation-mode" specified at all levels
+       * priority of file reservations vs database reservations
+       (Gitlab #1299)
+
 1817.  [func]          fdupont
        Redact control agent logs to hide basic HTTP authentication
        passwords from the configuration files. Note that when HTTP

diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst
index b4027bbc79110422f73641f00f92b16e3c78c88e..538f2c6b01c7df16b0a647dc74a6df0a6f8234d7 100644 (file)
--- a/doc/sphinx/arm/dhcp4-srv.rst
+++ b/doc/sphinx/arm/dhcp4-srv.rst
@@ -732,6 +732,11 @@ entry, as in:
 For additional Cassandra-specific parameters, see
 :ref:`cassandra-database-configuration4`.
 
+If the same host is configured both in-file and in-database, Kea won't warn of
+the duplicate like it would if you specified them both in the same data source.
+Instead the host configured in-file will have priority over the one configured
+in-database.
+
 .. _read-only-database-configuration4:
 
 Using Read-Only Databases for Host Reservations with DHCPv4
@@ -3941,7 +3946,7 @@ DHCPv4 message such as siaddr, sname, or file.
 
 .. note::
 
-   Kea requires that reserved address must be within the subnet.
+   Kea requires that the reserved address must be within the subnet.
    Kea 1.7.10 is the last release that does not enforce this.
 
 The following example shows how to reserve addresses for specific hosts
@@ -4441,8 +4446,75 @@ allocating or renewing a lease for the client. Allowed values are:
    defined will be completely ignored. As the checks are skipped, the
    server may operate faster in this mode.
 
-The parameter can be specified at global, subnet, and shared-network
-levels.
+The ``reservation-mode`` parameter can be specified at:
+
+- global level: ``.Dhcp4["reservation-mode"]`` (lowest priority: gets overridden
+  by all others)
+
+- subnet level: ``.Dhcp4.subnet4[]["reservation-mode"]`` (low priority)
+
+- shared-network level: ``.Dhcp4["shared-networks"][]["reservation-mode"]``
+  (high priority)
+
+- shared-network subnet-level:
+  ``.Dhcp4["shared-networks"][].subnet4[]["reservation-mode"]`` (highest
+  priority: overrides all others)
+
+For deciding what ``"reservation-mode"`` to choose, you may refer to the
+following decision diagram:
+
+::
+
+
+                                  O
+                                  |
+                                  v
+    +-----------------------------+------------------------------+
+    |         Is per-host configuration needed, such as          |
+    |                reserving specific addresses,               |
+    |               assigning specific options or                |
+    | assigning packets to specific classes on per-device basis? |
+    +-+-----------------+----------------------------------------+
+      |                 |
+    no|              yes|
+      |                 |   +--------------------------------------+
+      |                 |   |         For all given hosts,         |
+      +--> "disabled"   +-->+      can the reserved resources      |
+                            |  be used in all configured subnets?  |
+                            +--------+---------------------------+-+
+                                     |                           |
+    +----------------------------+   |no                         |yes
+    |             Is             |   |                           |
+    |  at least one reservation  +<--+               "global" <--+
+    | used to reserve addresses? |
+    +-+------------------------+-+
+      |                        |
+    no|                     yes|   +---------------------------+
+      |                        |   | Is high leases-per-second |
+      +--> "out-of-pool"       +-->+ performance or efficient  |
+            ^                      |      resource usage       |
+            |                      |  (CPU ticks, RAM usage,   |
+            |                      |   database roundtrips)    |
+            |                      | important to your setup?  |
+            |                      +-+----------------+--------+
+            |                        |                |
+            |                     yes|              no|
+            |                        |                |
+            |          +-------------+                |
+            |          |                              |
+            |          |   +----------------------+   |
+            |          |   | Can it be guaranteed |   |
+            |          +-->+  that the reserved   |   |
+            |              |      addresses       |   |
+            |              |  aren't part of the  |   |
+            |              |   pools configured   |   |
+            |              |  in the respective   |   |
+            |              |       subnet?        |   |
+            |              +-+------------------+-+   |
+            |                |                  |     |
+            |             yes|                no|     |
+            |                |                  |     V
+            +----------------+                  +--> "all"
 
 An example configuration that disables reservation looks as follows:
 

diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst
index 0113dc930e6d05ee127fa9e41244322003620669..d2eecd0e387ac69084f0dc14b878baac80eb2efe 100644 (file)
--- a/doc/sphinx/arm/dhcp6-srv.rst
+++ b/doc/sphinx/arm/dhcp6-srv.rst
@@ -613,7 +613,7 @@ specified:
 
 ::
 
-   "Dhcp6": { "host-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }
+   "Dhcp6": { "hosts-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }
 
 If the server is unable to reconnect to the database after making the
 maximum number of attempts, the server will exit. A value of zero (the
@@ -670,6 +670,11 @@ entry, as in:
 For additional Cassandra-specific parameters, see
 :ref:`cassandra-database-configuration4`.
 
+If the same host is configured both in-file and in-database, Kea won't warn of
+the duplicate like it would if you specified them both in the same data source.
+Instead the host configured in-file will have priority over the one configured
+in-database.
+
 .. _read-only-database-configuration6:
 
 Using Read-Only Databases for Host Reservations with DHCPv6
@@ -3840,8 +3845,75 @@ allocating or renewing a lease for the client. Allowed values are:
    defined will be completely ignored. As the checks are skipped, the
    server may operate faster in this mode.
 
-The parameter can be specified at global, subnet, and shared-network
-levels.
+The ``reservation-mode`` parameter can be specified at:
+
+- global level: ``.Dhcp6["reservation-mode"]`` (lowest priority: gets overridden
+  by all others)
+
+- subnet level: ``.Dhcp6.subnet6[]["reservation-mode"]`` (low priority)
+
+- shared-network level: ``.Dhcp6["shared-networks"][]["reservation-mode"]``
+  (high priority)
+
+- shared-network subnet-level:
+  ``.Dhcp6["shared-networks"][].subnet6[]["reservation-mode"]`` (highest
+  priority: overrides all others)
+
+For deciding what ``"reservation-mode"`` to choose, you may refer to the
+following decision diagram:
+
+::
+
+                                  O
+                                  |
+                                  v
+    +-----------------------------+------------------------------+
+    |         Is per-host configuration needed, such as          |
+    |                reserving specific addresses,               |
+    |               assigning specific options or                |
+    | assigning packets to specific classes on per-device basis? |
+    +-+-----------------+----------------------------------------+
+      |                 |
+    no|              yes|
+      |                 |   +--------------------------------------+
+      |                 |   |         For all given hosts,         |
+      +--> "disabled"   +-->+      can the reserved resources      |
+                            |  be used in all configured subnets?  |
+                            +--------+---------------------------+-+
+                                     |                           |
+    +----------------------------+   |no                         |yes
+    |             Is             |   |                           |
+    |  at least one reservation  +<--+               "global" <--+
+    | used to reserve addresses  |
+    |        or prefixes?        |
+    +-+------------------------+-+
+      |                        |
+    no|                     yes|   +---------------------------+
+      |                        |   | Is high leases-per-second |
+      +--> "out-of-pool"       +-->+ performance or efficient  |
+            ^                      |      resource usage       |
+            |                      |  (CPU ticks, RAM usage,   |
+            |                      |   database roundtrips)    |
+            |                      | important to your setup?  |
+            |                      +-+----------------+--------+
+            |                        |                |
+            |                     yes|              no|
+            |                        |                |
+            |          +-------------+                |
+            |          |                              |
+            |          |   +----------------------+   |
+            |          |   | Can it be guaranteed |   |
+            |          +-->+  that the reserved   |   |
+            |              |  addresses/prefixes  |   |
+            |              |  aren't part of the  |   |
+            |              |   pools configured   |   |
+            |              |  in the respective   |   |
+            |              |       subnet?        |   |
+            |              +-+------------------+-+   |
+            |                |                  |     |
+            |             yes|                no|     |
+            |                |                  |     V
+            +----------------+                  +--> "all"
 
 An example configuration that disables reservation looks as follows:
 

diff --git a/src/lib/database/dbaccess_parser.h b/src/lib/database/dbaccess_parser.h
index 2e55d20ea6de5eb02bee6b00c3b573409f489dbf..bf25234597d0a8a6fc948e01d7d396a28def4049 100644 (file)
--- a/src/lib/database/dbaccess_parser.h
+++ b/src/lib/database/dbaccess_parser.h
@@ -20,7 +20,7 @@ namespace db {
 /// @brief Parse Database Parameters
 ///
 /// This class is the parser for the database configuration.  This is a
-/// map under the top-level "lease-database", "host-database" and
+/// map under the top-level "lease-database", "hosts-database" and
 /// "config-database" elements, and comprises a map of strings.
 class DbAccessParser: public isc::data::SimpleParser {
 public:

diff --git a/src/share/api/reservation-get.json b/src/share/api/reservation-get.json
index 5ff39f5b09cdf3f216dedc5fc51a43fd5d4bfca6..e221097825c2191817e3ce7bd41658284d015309 100644 (file)
--- a/src/share/api/reservation-get.json
+++ b/src/share/api/reservation-get.json
@@ -40,7 +40,7 @@
         "        \"next-server\": <string (IPv4 address)>,",
         "        \"option-data-list\": [ <comma-separated structures defining options> ],",
         "        \"prefixes\": [ <comma-separated IPv6 prefixes> ],",
-        "        \"reservation-client-classes\": [ <comma-separated strings> ],",
+        "        \"client-classes\": [ <comma-separated strings> ],",
         "        \"server-hostname\": <string>,",
         "        \"subnet-id\": <integer>,",
         "        \"user-context\": <any valid JSON>",