From: Razvan Becheriu Date: Thu, 19 Nov 2020 11:10:21 +0000 (+0200) Subject: [#1550] added documentation X-Git-Tag: Kea-1.9.2~60 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=375bbe34a55077f46679d5335976510aeb9f76cf;p=thirdparty%2Fkea.git [#1550] added documentation --- diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 19340e8ef8..580a49c02d 100644 --- 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 85ddb18aa5..cec69d9761 100644 --- 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 05bb17ef94..8d77f71381 100644 --- 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 4faee11e61..e526f11120 100644 --- 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);