[#1550] added documentation

diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst
index 19340e8ef83c1c78b7e4e5a8de66f29065316a4f..580a49c02d6e568bb124afd89ab6cb55a5a85da0 100644 (file)
--- a/doc/sphinx/arm/dhcp4-srv.rst
+++ b/doc/sphinx/arm/dhcp4-srv.rst
@@ -4519,6 +4519,12 @@ 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.
 
+   Since Kea 1.9.1, the ``reservation-mode`` is replaced by the
+``reservations-global``, ``reservations-in-subnet`` and
+``reservations-out-of-pool`` flags.
+The flags can be activated independently and can produce various combinations,
+some of them being unsupported by the deprecated ``reservation-mode``.
+
 The ``reservation-mode`` parameter can be specified at:
 
 - global level: ``.Dhcp4["reservation-mode"]`` (lowest priority: gets overridden
@@ -4630,12 +4636,6 @@ An example configuration using global reservations is shown below:
        ]
    }
 
-Since Kea 1.9.1, the ``reservation-mode`` is replaced by the
-``reservations-global``, ``reservations-in-subnet`` and
-``reservations-out-of-pool`` flags.
-The flags can be activated independently and can produce various combinations,
-some of them being unsuported by the deprecated ``reservation-mode``.
-
 The meaning of these flags are:
 
 - ``reservations-global``: fetch global reservations.
@@ -4647,7 +4647,10 @@ The meaning of these flags are:
   ``reservations-in-subnet`` flag is true. When ``reservations-out-of-pool``
   is true the server may assume that all host reservations of the subnet are
   for addresses that do not belong to the dynamic pool as described in the
-  ``out-of-pool`` reservation mode.
+  ``out-of-pool`` reservation mode. In this case, the server will not assign
+  reservations that are inside the dynamic pools to the respective clients.
+  This also means that the addresses matching the respective reservations from
+  inside the dynamic pools can be dynamically assigned to other clients.
 
 The ``reservation-mode`` will be deprecated in a future Kea version.
 

diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst
index 85ddb18aa5a2db7cd89c4c7a620cc272fe33c3dc..cec69d97617a96cfc977f2beb1370dd24505ca08 100644 (file)
--- a/doc/sphinx/arm/dhcp6-srv.rst
+++ b/doc/sphinx/arm/dhcp6-srv.rst
@@ -3964,6 +3964,12 @@ 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.
 
+Since Kea 1.9.1, the ``reservation-mode`` is replaced by the
+``reservations-global``, ``reservations-in-subnet`` and
+``reservations-out-of-pool`` flags.
+The flags can be activated independently and can produce various combinations,
+some of them being unsupported by the deprecated ``reservation-mode``.
+
 The ``reservation-mode`` parameter can be specified at:
 
 - global level: ``.Dhcp6["reservation-mode"]`` (lowest priority: gets overridden
@@ -4076,13 +4082,7 @@ An example configuration using global reservations is shown below:
        ]
    }
 
-Since Kea 1.9.1, the ``reservation-mode`` is replaced by the
-``reservations-global``, ``reservations-in-subnet`` and
-``reservations-out-of-pool`` flags.
-The flags can be activated independently and can produce various combinations,
-some of them being unsuported by the deprecated ``reservation-mode``.
-
-The meaning of these flags are:
+The meaning of the reservation flags are:
 
 - ``reservations-global``: fetch global reservations.
 
@@ -4093,7 +4093,11 @@ The meaning of these flags are:
   ``reservations-in-subnet`` flag is true. When ``reservations-out-of-pool``
   is true the server may assume that all host reservations of the subnet are
   for addresses or prefixes that do not belong to the dynamic pool as described
-  in the ``out-of-pool`` reservation mode.
+  in the ``out-of-pool`` reservation mode. In this case, the server will not
+  assign reservations that are inside the dynamic pools to the respective
+  clients. This also means that the addresses matching the respective
+  reservations from inside the dynamic pools can be dynamically assigned to
+  other clients.
 
 The ``reservation-mode`` will be deprecated in a future Kea version.
 

diff --git a/src/lib/dhcpsrv/alloc_engine.cc b/src/lib/dhcpsrv/alloc_engine.cc
index 05bb17ef943b6d020f7619f78c19444dec85a2f6..8d77f71381dae4604f5acde10571753746ba1e83 100644 (file)
--- a/src/lib/dhcpsrv/alloc_engine.cc
+++ b/src/lib/dhcpsrv/alloc_engine.cc
@@ -1010,7 +1010,7 @@ AllocEngine::allocateUnreservedLeases6(ClientContext6& ctx) {
     // the entire subnet (or more subnets) to discover that the pools
     // have been exhausted. Using a subnet from which a lease was
     // assigned most recently is an optimization which increases
-    // the likelyhood of starting from the subnet which pools are not
+    // the likelihood of starting from the subnet which pools are not
     // exhausted.
     SharedNetwork6Ptr network;
     original_subnet->getSharedNetwork(network);

diff --git a/src/lib/dhcpsrv/alloc_engine.h b/src/lib/dhcpsrv/alloc_engine.h
index 4faee11e611d60d8c7e6d27dec1c67b8d16e1010..e526f11120acc2800d773e221742e1eae53cdcf7 100644 (file)
--- a/src/lib/dhcpsrv/alloc_engine.h
+++ b/src/lib/dhcpsrv/alloc_engine.h
@@ -936,12 +936,22 @@ public:
     /// deleted.
     void deleteExpiredReclaimedLeases4(const uint32_t secs);
 
-
     /// @anchor findReservationDecl
     /// @brief Attempts to find appropriate host reservation.
     ///
     /// Attempts to find appropriate host reservation in HostMgr. If found, it
-    /// will be set in ctx.host_.
+    /// will be set in ctx.hosts_.
+    ///
+    /// @node When the out-of-pool flag is enabled, because the function is
+    /// called only once per DHCP message, the reservations that are in-subnet
+    /// are not filtered out as there is no sufficient information regarding the
+    /// selected subnet, shared network or lease types, but will be filtered out
+    /// at allocation time.
+    ///
+    /// @note If reservations-global flag is enabled but they are no
+    /// reservations found, an empty (HostPtr()) will indicate that the search
+    /// does not need to be performed again.
+    ///
     /// @param ctx Client context that contains all necessary information.
     static void findReservation(ClientContext6& ctx);
 
@@ -1020,6 +1030,10 @@ private:
     /// may return more than one lease, but we currently handle only one.
     /// This may change in the future.
     ///
+    /// @note If reservations-out-of-pool flag is enabled, dynamic address that
+    /// match reservations from within the dynamic pool will not be prevented to
+    /// be assigned to any client.
+    ///
     /// @param ctx client context that contains all details (subnet, client-id, etc.)
     ///
     /// @return collection of newly allocated leases
@@ -1033,7 +1047,11 @@ private:
     /// new lease is not created, if there is a lease for specified
     /// address on existing_leases list or there is a lease used by
     /// someone else. It last calls @c allocateGlobalReservedLeases6
-    /// to accomodate subnets using global reservations.
+    /// to accommodate subnets using global reservations.
+    ///
+    /// @note If reservations-out-of-pool flag is enabled, reservations from
+    /// within the dynamic pool will not be checked to be assigned to the
+    /// respective client.
     ///
     /// @param ctx client context that contains all details (subnet, client-id, etc.)
     /// @param existing_leases leases that are already associated with the client
@@ -1568,9 +1586,17 @@ public:
     /// @brief Attempts to find the host reservation for the client.
     ///
     /// This method attempts to find the host reservation for the client. If
-    /// found, it is set in the @c ctx.host_. If the host reservations are
-    /// disabled for the particular subnet or the reservation is not found
-    /// for the client, the @c ctx.host_ is set to NULL.
+    /// found, it is set in the @c ctx.hosts_.
+    ///
+    /// @node When the out-of-pool flag is enabled, because the function is
+    /// called only once per DHCP message, the reservations that are in-subnet
+    /// are not filtered out as there is no sufficient information regarding the
+    /// selected subnet or shared network, but will be filtered out at
+    /// allocation time.
+    ///
+    /// @note If reservations-global flag is enabled but they are no
+    /// reservations found, an empty (HostPtr()) will indicate that the search
+    /// does not need to be performed again.
     ///
     /// @param ctx Client context holding various information about the client.
     static void findReservation(ClientContext4& ctx);