Kea 2.7.4
isc::dhcp::AllocEngine Class Reference

DHCPv4 and DHCPv6 allocation engine. More...

#include <alloc_engine.h>

+ Inheritance diagram for isc::dhcp::AllocEngine:

Classes

struct  ClientContext4
 Context information for the DHCPv4 lease allocation. More...
 
struct  ClientContext6
 Context information for the DHCPv6 leases allocation. More...
 
class  Resource
 Defines a single hint. More...
 
struct  ResourceCompare
 Resource compare class. More...
 

Public Types

typedef boost::shared_ptr< ClientContext4ClientContext4Ptr
 Pointer to the ClientContext4.
 
typedef std::vector< ResourceHintContainer
 Container for client's hints.
 
typedef std::list< IdentifierPairIdentifierList
 Map holding values to be used as host identifiers.
 
typedef std::pair< Host::IdentifierType, std::vector< uint8_t > > IdentifierPair
 A tuple holding host identifier type and value.
 
typedef std::set< Resource, ResourceCompareResourceContainer
 Container holding allocated prefixes or addresses.
 

Public Member Functions

 AllocEngine (isc::util::uint128_t const &attempts)
 Constructor.
 
virtual ~AllocEngine ()
 Destructor.
 
Lease4Ptr allocateLease4 (ClientContext4 &ctx)
 Returns IPv4 lease.
 
Lease6Collection allocateLeases6 (ClientContext6 &ctx)
 Allocates IPv6 leases for a given IA container.
 
void deleteExpiredReclaimedLeases4 (const uint32_t secs)
 Deletes reclaimed leases expired more than specified amount of time ago.
 
void deleteExpiredReclaimedLeases6 (const uint32_t secs)
 Deletes reclaimed leases expired more than specified amount of time ago.
 
isc::util::ReadWriteMutexgetReadWriteMutex ()
 Get the read-write mutex.
 
void reclaimExpiredLeases4 (const size_t max_leases, const uint16_t timeout, const bool remove_lease, const uint16_t max_unwarned_cycles=0)
 Reclaims expired IPv4 leases.
 
void reclaimExpiredLeases4Internal (const size_t max_leases, const uint16_t timeout, const bool remove_lease, const uint16_t max_unwarned_cycles=0)
 Body of reclaimExpiredLeases4.
 
void reclaimExpiredLeases6 (const size_t max_leases, const uint16_t timeout, const bool remove_lease, const uint16_t max_unwarned_cycles=0)
 Reclaims expired IPv6 leases.
 
void reclaimExpiredLeases6Internal (const size_t max_leases, const uint16_t timeout, const bool remove_lease, const uint16_t max_unwarned_cycles=0)
 Body of reclaimExpiredLeases6.
 
Lease6Collection renewLeases6 (ClientContext6 &ctx)
 Renews existing DHCPv6 leases for a given IA.
 

Static Public Member Functions

static ConstHostPtr findGlobalReservation (ClientContext4 &ctx)
 Attempts to find the host reservation for the client.
 
static ConstHostPtr findGlobalReservation (ClientContext6 &ctx)
 Attempts to find the host reservation for the client.
 
static void findReservation (ClientContext4 &ctx)
 Attempts to find the host reservation for the client.
 
static void findReservation (ClientContext6 &ctx)
 
 
static void getLifetimes6 (ClientContext6 &ctx, uint32_t &preferred, uint32_t &valid)
 Determines the preferred and valid v6 lease lifetimes.
 
static uint32_t getOfferLft (const ClientContext4 &ctx)
 Returns the offer lifetime based on the v4 context.
 
static uint32_t getValidLft (const ClientContext4 &ctx)
 Returns the valid lifetime based on the v4 context.
 
static std::string labelNetworkOrSubnet (SubnetPtr subnet)
 Generates a label for subnet or shared-network from subnet.
 
static IPv6Resrv makeIPv6Resrv (const Lease6 &lease)
 Creates an IPv6Resrv instance from a Lease6.
 

Public Attributes

isc::util::ReadWriteMutex rw_mutex_
 The read-write mutex.
 

Protected Member Functions

void clearReclaimedExtendedInfo (const Lease4Ptr &lease) const
 Clear extended info from a reclaimed V4 lease.
 
void clearReclaimedExtendedInfo (const Lease6Ptr &lease) const
 Clear extended info from a reclaimed V6 lease.
 
bool updateLease4ExtendedInfo (const Lease4Ptr &lease, const ClientContext4 &ctx) const
 Stores additional client query parameters on a V4 lease.
 
void updateLease6ExtendedInfo (const Lease6Ptr &lease, const ClientContext6 &ctx) const
 Stores additional client query parameters on a V6 lease.
 

Detailed Description

DHCPv4 and DHCPv6 allocation engine.

This class represents a DHCP allocation engine. It is responsible for picking subnets, choosing and allocating a lease, extending, renewing, releasing and possibly expiring leases.

Definition at line 47 of file alloc_engine.h.

Member Typedef Documentation

◆ ClientContext4Ptr

Pointer to the ClientContext4.

Definition at line 1378 of file alloc_engine.h.

◆ HintContainer

Container for client's hints.

Definition at line 185 of file alloc_engine.h.

◆ IdentifierList

Map holding values to be used as host identifiers.

Definition at line 194 of file alloc_engine.h.

◆ IdentifierPair

typedef std::pair<Host::IdentifierType, std::vector<uint8_t> > isc::dhcp::AllocEngine::IdentifierPair

A tuple holding host identifier type and value.

Definition at line 191 of file alloc_engine.h.

◆ ResourceContainer

Container holding allocated prefixes or addresses.

Definition at line 188 of file alloc_engine.h.

Constructor & Destructor Documentation

◆ AllocEngine()

isc::dhcp::AllocEngine::AllocEngine ( isc::util::uint128_t const & attempts)

Constructor.

Instantiates necessary services, required to run DHCP server. In particular, creates IfaceMgr that will be responsible for network interaction. Will instantiate lease manager, and load old or create new DUID.

Parameters
attemptsnumber of attempts for each lease allocation before we give up (0 means unlimited)

Definition at line 94 of file alloc_engine.cc.

References Hooks.

◆ ~AllocEngine()

virtual isc::dhcp::AllocEngine::~AllocEngine ( )
inlinevirtual

Destructor.

Definition at line 62 of file alloc_engine.h.

Member Function Documentation

◆ allocateLease4()

Lease4Ptr isc::dhcp::AllocEngine::allocateLease4 ( ClientContext4 & ctx)

Returns IPv4 lease.

This method finds a lease for a client using the following algorithm:

  • If a lease exists for the combination of the HW address or client id and a subnet, try to use this lease for the client. If the client has a reservation for an address for which the lease was created or the client desires to renew the lease for this address (ciaddr or requested IP address option), the server renews the lease for the client. If the client desires a different address or the server has a (potentially new) reservation for a different address for this client, the existing lease is replaced with a new lease.
  • If the client has no lease in the lease database the server will try to allocate a new lease. If the client has a reservation for the particular address or if it has specified a desired address the server will check if the particular address is not allocated to another client. If the address is available, the server will allocate this address for the client.
  • If the desired address is unavailable the server checks if the lease for this address has expired. If the lease is expired, the server will allocate this lease to the client. The relevant information will be updated, e.g. new client HW address, host name etc.
  • If the desired address is in use by another client, the server will try to allocate a different address. The server picks addresses from a dynamic pool and checks if the address is available and that it is not reserved for another client. If it is in use by another client or if it is reserved for another client, the address is not allocated. The server picks the next address and repeats this check. Note that the server ceases allocation after the configured number of unsuccessful attempts.

The lease allocation process is slightly different for the DHCPDISCOVER and DHCPREQUEST messages. In the former case, the client may specify the requested IP address option with a desired address and the server treats this address as a hint. This means that the server may allocate a different address at its discretion and send it to the client in the DHCPOFFER. If the client accepts this offer it specifies this address in the requested IP address option in the DHCPREQUEST. At this point, the allocation engine will use the requested IP address as a hard requirement and if this address can't be allocated for any reason, the allocation engine returns NULL lease. As a result, the DHCP server sends a DHCPNAK to the client and the client falls back to the DHCP server discovery.

The only exception from this rule is when the client doesn't specify a requested IP address option (invalid behavior) in which case the allocation engine will try to allocate any address.

If there is an address reservation specified for the particular client the reserved address always takes precedence over addresses from the dynamic pool or even an address currently allocated for this client.

It is possible that the address reserved for the particular client is in use by another client, e.g. as a result of pools reconfiguration. In this case, when the client requests allocation of the reserved address and the server determines that it is leased to someone else, the allocation engine allocates a different address for this client.

When the client having a lease returns to renew, the allocation engine doesn't extend the lease for it and returns a NULL pointer. The client falls back to the 4-way exchange and a different lease is allocated. At this point, the reserved address is freed and can be allocated to the client which holds this reservation. However, this client has a lease for a different address at this time. When the client renews its lease it receives the DHCPNAK and falls back to the DHCP server discovery and obtains the lease for the reserved address.

When a server should do DNS updates, it is required that allocation returns the information about how the lease was obtained by the allocation engine. In particular, the DHCP server should be able to check whether an existing lease was returned, or a new lease was allocated. When an existing lease was returned, the server should check whether the FQDN has changed between the allocation of the old and new lease. If so, the server should perform the appropriate DNS update. If not, the server may choose to not perform the update. The information about the old lease is returned via old_lease parameter. If NULL value is returned, it is an indication that a new lease was allocated for the client. If non-NULL value is returned, it is an indication that allocation engine reused/renewed an existing lease.

Parameters
ctxclient context that passes all necessary information. See ClientContext4 for details.

The following fields of ClientContext4 are used:

Returns
Allocated IPv4 lease (or NULL if allocation failed).

Definition at line 3684 of file alloc_engine.cc.

References isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V4_ALLOC_ERROR, isc::dhcp::AllocEngine::ClientContext4::fake_allocation_, isc::dhcp::AllocEngine::ClientContext4::hwaddr_, isc_throw, LOG_ERROR, isc::dhcp::AllocEngine::ClientContext4::new_lease_, isc::dhcp::AllocEngine::ClientContext4::old_lease_, isc::dhcp::AllocEngine::ClientContext4::query_, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

◆ allocateLeases6()

Lease6Collection isc::dhcp::AllocEngine::allocateLeases6 ( ClientContext6 & ctx)

Allocates IPv6 leases for a given IA container.

This method uses the currently selected allocator to pick allocable resources (i.e. addresses or prefixes) from specified subnet, creates a lease (one or more, if needed) for that resources and then inserts it into LeaseMgr (if this allocation is not fake, i.e. this is not a response to SOLICIT).

This method uses host reservation if ClientContext6::hosts_ is set. The easy way to set it is to call findReservationDecl. The host reservation is convenient, but incurs performance penalty, so it can be tweaked on a per subnet basis. There are three possible modes:

  1. disabled (no host reservation at all). This is the most performant one as the code can skip all checks;
  2. out-of-pool (only reservations that are outside of the dynamic pools are allowed. This is a compromise - it requires a sysadmin to be more careful with the reservations, but the code can skip reservation checks while managing in-pool addresses);
  3. in-pool (which also allow out-of-pool; this is the most flexible mode, but it means that the allocation engine has to do reservation checks on every lease, even those dynamically assigned, which degrades performance).

The logic in this method is as follows:

  1. Case 1. if there are no leases, and there are reservations... Are the reserved addresses/prefixes used by someone else?
    1. yes: we have a problem. We can't assign the reserved address yet, because it is used by someone else. We can't immediately release the lease as there is some other client that is currently using it. We will temporarily assign a different, unreserved lease for this client. In the mean time, the other client will hopefully get back to us, so we could revoke his lease.
    2. no: assign them => done
  2. Case 2. if there are leases and there are no reservations... Are the leases reserved for someone else?
    1. yes: release them, assign something else
    2. no: renew them => done
  3. Case 3. if there are leases and there are reservations... Are the leases matching reservations?
    1. yes: renew them => done
    2. no: release existing leases, assign new ones based on reservations
  4. Case 4. if there are no leases and no reservations... assign new leases (this is the "normal" case when the reservations are disabled).
Parameters
ctxclient context that passes all necessary information. See ClientContext6 for details.

The following fields of ClientContext6 are used:

ClientContext6::subnet_ subnet the allocation should come from
ClientContext6::duid_ Client's DUID
ClientContext6::IAContext::iaid_ iaid field from the IA_NA container that client sent
ClientContext6::IAContext::hints_ a hint that the client provided
ClientContext6::IAContext::type_ lease type (IA, TA or PD)
ClientContext6::fwd_dns_update_ A boolean value which indicates that server takes responsibility for the forward DNS Update for this lease (if true).
ClientContext6::rev_dns_update_ A boolean value which indicates that server takes responsibility for the reverse DNS Update for this lease (if true).
ClientContext6::hostname_ A fully qualified domain-name of the client.
ClientContext6::fake_allocation_ is this real i.e. REQUEST (false) or just picking an address for SOLICIT that is not really allocated (true)
ClientContext6::callout_handle_ a callout handle (used in hooks). A lease callouts will be executed if this parameter is passed.
ClientContext6::IAContext::old_leases_ [out] Collection to which this function will append old leases. Leases are stored in the same order as in the collection of new leases, being returned. For newly allocated leases (not renewed) the NULL pointers are stored in this collection as old leases.
ClientContext6::hwaddr_ Hardware address (optional, may be null if not available)
ClientContext6::hosts_ Host reservations. allocateLeases6 will set this field, if appropriate reservations are found.

Returns
Allocated IPv6 leases (may be empty if allocation failed)

Definition at line 461 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext6::addAllocatedResource(), isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V6_ALLOC_ERROR, isc::dhcp::ALLOC_ENGINE_V6_ALLOC_LEASES_HR, isc::dhcp::ALLOC_ENGINE_V6_ALLOC_LEASES_NO_HR, isc::dhcp::ALLOC_ENGINE_V6_ALLOC_NO_LEASES_HR, isc::dhcp::ALLOC_ENGINE_V6_ALLOC_UNRESERVED, isc::dhcp::AllocEngine::ClientContext6::currentIA(), isc::dhcp::AllocEngine::ClientContext6::duid_, isc::dhcp::AllocEngine::ClientContext6::hosts_, isc::dhcp::AllocEngine::ClientContext6::IAContext::iaid_, isc::dhcp::LeaseMgrFactory::instance(), isc_throw, LOG_DEBUG, LOG_ERROR, isc::dhcp::AllocEngine::ClientContext6::new_leases_, isc::dhcp::AllocEngine::ClientContext6::query_, isc::dhcp::AllocEngine::ClientContext6::subnet_, and isc::dhcp::AllocEngine::ClientContext6::IAContext::type_.

+ Here is the call graph for this function:

◆ clearReclaimedExtendedInfo() [1/2]

void isc::dhcp::AllocEngine::clearReclaimedExtendedInfo ( const Lease4Ptr & lease) const
protected

Clear extended info from a reclaimed V4 lease.

Parameters
[out]leaseA pointer to the reclaimed lease.

Definition at line 3258 of file alloc_engine.cc.

◆ clearReclaimedExtendedInfo() [2/2]

void isc::dhcp::AllocEngine::clearReclaimedExtendedInfo ( const Lease6Ptr & lease) const
protected

Clear extended info from a reclaimed V6 lease.

Parameters
[out]leaseA pointer to the reclaimed lease.

Definition at line 3267 of file alloc_engine.cc.

References isc::dhcp::Lease6::ACTION_DELETE.

◆ deleteExpiredReclaimedLeases4()

void isc::dhcp::AllocEngine::deleteExpiredReclaimedLeases4 ( const uint32_t secs)

Deletes reclaimed leases expired more than specified amount of time ago.

Parameters
secsMinimum number of seconds after which the lease can be deleted.

Definition at line 3091 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE, isc::dhcp::ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE_COMPLETE, isc::dhcp::ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE_FAILED, isc::dhcp::LeaseMgrFactory::instance(), LOG_DEBUG, and LOG_ERROR.

+ Here is the call graph for this function:

◆ deleteExpiredReclaimedLeases6()

void isc::dhcp::AllocEngine::deleteExpiredReclaimedLeases6 ( const uint32_t secs)

Deletes reclaimed leases expired more than specified amount of time ago.

Parameters
secsMinimum number of seconds after which the lease can be deleted.

Definition at line 2658 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V6_RECLAIMED_LEASES_DELETE, isc::dhcp::ALLOC_ENGINE_V6_RECLAIMED_LEASES_DELETE_COMPLETE, isc::dhcp::ALLOC_ENGINE_V6_RECLAIMED_LEASES_DELETE_FAILED, isc::dhcp::LeaseMgrFactory::instance(), LOG_DEBUG, and LOG_ERROR.

+ Here is the call graph for this function:

◆ findGlobalReservation() [1/2]

ConstHostPtr isc::dhcp::AllocEngine::findGlobalReservation ( ClientContext4 & ctx)
static

Attempts to find the host reservation for the client.

This method attempts to find a "global" host reservation matching the client identifier. It will return the first global reservation that matches per the configured list of host identifiers, or an empty pointer if no matches are found.

Parameters
ctxClient context holding various information about the client.
Returns
Pointer to the reservation found, or an empty pointer.

Definition at line 3831 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext4::host_identifiers_, and isc::dhcp::HostMgr::instance().

+ Here is the call graph for this function:

◆ findGlobalReservation() [2/2]

ConstHostPtr isc::dhcp::AllocEngine::findGlobalReservation ( ClientContext6 & ctx)
static

Attempts to find the host reservation for the client.

This method attempts to find a "global" host reservation matching the client identifier. It will return the first global reservation that matches per the configured list of host identifiers, or an empty pointer if no matches are found.

Parameters
ctxClient context holding various information about the client.
Returns
Pointer to the reservation found, or an empty pointer.

Definition at line 444 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext6::host_identifiers_, and isc::dhcp::HostMgr::instance().

Referenced by findReservation(), and findReservation().

+ Here is the call graph for this function:

◆ findReservation() [1/2]

void isc::dhcp::AllocEngine::findReservation ( ClientContext4 & ctx)
static

Attempts to find the host reservation for the client.

Attempts to find appropriate host reservation in HostMgr. If found, it is set in the ClientContext4::hosts_.

Note
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.
Parameters
ctxClient context holding various information about the client.

Definition at line 3728 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext4::early_global_reservations_lookup_, findGlobalReservation(), isc::dhcp::AllocEngine::ClientContext4::host_identifiers_, isc::dhcp::AllocEngine::ClientContext4::hosts_, isc::dhcp::HostMgr::instance(), isc::dhcp::AllocEngine::ClientContext4::query_, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

+ Here is the call graph for this function:

◆ findReservation() [2/2]

void isc::dhcp::AllocEngine::findReservation ( ClientContext6 & ctx)
static

Attempts to find appropriate host reservation.

Attempts to find appropriate host reservation in HostMgr. If found, it is set in the ClientContext6::hosts_.

Note
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.
Parameters
ctxClient context that contains all necessary information.

Definition at line 340 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext6::early_global_reservations_lookup_, findGlobalReservation(), isc::dhcp::AllocEngine::ClientContext6::host_identifiers_, isc::dhcp::AllocEngine::ClientContext6::hosts_, isc::dhcp::HostMgr::instance(), isc::dhcp::AllocEngine::ClientContext6::query_, and isc::dhcp::AllocEngine::ClientContext6::subnet_.

+ Here is the call graph for this function:

◆ getLifetimes6()

void isc::dhcp::AllocEngine::getLifetimes6 ( ClientContext6 & ctx,
uint32_t & preferred,
uint32_t & valid )
static

Determines the preferred and valid v6 lease lifetimes.

A candidate triplet for both preferred and valid lifetimes will be selected from the first class matched to the query which defines the value or from the subnet if none do. Classes are searched in the order they are assigned to the query.

If the client requested a lifetime IA hint, then the lifetime values returned will be the requested values bounded by the candidate triplets. If the client did not request a value, then it simply returns the candidate triplet's default value.

Parameters
ctxclient context that passes all necessary information. See ClientContext6 for details.
[out]preferredset to the preferred lifetime that should be used.
[out]validset to the valid lifetime that should be used.

Definition at line 1878 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V6_CALCULATED_PREFERRED_LIFETIME, isc::dhcp::AllocEngine::ClientContext6::currentIA(), isc::dhcp::AllocEngine::ClientContext6::IAContext::hints_, isc::dhcp::CfgMgr::instance(), LOG_DEBUG, isc::dhcp::AllocEngine::ClientContext6::query_, and isc::dhcp::AllocEngine::ClientContext6::subnet_.

+ Here is the call graph for this function:

◆ getOfferLft()

uint32_t isc::dhcp::AllocEngine::getOfferLft ( const ClientContext4 & ctx)
static

Returns the offer lifetime based on the v4 context.

If the client query is a BOOTP query or something other than DHCPDISCOVER, return 0.

Otherwise, the value will be selected from the first class matched to the query which defines it or from the subnet if none do. Classes are searched in the order they are assigned to the query.

Parameters
ctxClient context holding various information about the client.
Returns
unsigned integer value of the offer lifetime to use.

Definition at line 4174 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext4::fake_allocation_, isc::dhcp::CfgMgr::instance(), isc::dhcp::AllocEngine::ClientContext4::query_, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

+ Here is the call graph for this function:

◆ getReadWriteMutex()

isc::util::ReadWriteMutex & isc::dhcp::AllocEngine::getReadWriteMutex ( )
inline

Get the read-write mutex.

This read-write mutex is used to make reclamation exclusive of multi-threaded packet processing.

Returns
A reference to the read-write mutex.

Definition at line 1853 of file alloc_engine.h.

References rw_mutex_.

◆ getValidLft()

uint32_t isc::dhcp::AllocEngine::getValidLft ( const ClientContext4 & ctx)
static

Returns the valid lifetime based on the v4 context.

If the client query is a BOOTP query, the value returned will be Lease::INFINITY_LFT.

Otherwise, a candidate triplet will be selected from the first class matched to the query which defines it or from the subnet if none do. Classes are searched in the order they are assigned to the query.

If the client requested a lifetime value via DHCP option 51, then the lifetime value returned will be the requested value bounded by the candidate triplet. If the client did not request a value, then it simply returns the candidate triplet's default value.

Parameters
ctxClient context holding various information about the client.
Returns
unsigned integer value of the valid lifetime to use.

Definition at line 4209 of file alloc_engine.cc.

References isc::dhcp::DHO_DHCP_LEASE_TIME, isc::dhcp::Lease::INFINITY_LFT, isc::dhcp::CfgMgr::instance(), isc::dhcp::AllocEngine::ClientContext4::query_, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

Referenced by isc::dhcp::Dhcpv4Srv::assignLease().

+ Here is the call graph for this function:

◆ labelNetworkOrSubnet()

std::string isc::dhcp::AllocEngine::labelNetworkOrSubnet ( SubnetPtr subnet)
static

Generates a label for subnet or shared-network from subnet.

Creates a string for the subnet and its ID for stand alone subnets or the shared-network and its name if the given subnet belongs to a shared-network.

Parameters
subnetpointer to the source subnet
Returns
string containing the generated label

Definition at line 3308 of file alloc_engine.cc.

◆ makeIPv6Resrv()

static IPv6Resrv isc::dhcp::AllocEngine::makeIPv6Resrv ( const Lease6 & lease)
inlinestatic

Creates an IPv6Resrv instance from a Lease6.

Parameters
leaseReference to the Lease6
Returns
The newly formed IPv6Resrv instance

Definition at line 788 of file alloc_engine.h.

References isc::dhcp::IPv6Resrv::TYPE_NA, isc::dhcp::Lease::TYPE_NA, and isc::dhcp::IPv6Resrv::TYPE_PD.

◆ reclaimExpiredLeases4()

void isc::dhcp::AllocEngine::reclaimExpiredLeases4 ( const size_t max_leases,
const uint16_t timeout,
const bool remove_lease,
const uint16_t max_unwarned_cycles = 0 )

Reclaims expired IPv4 leases.

This method retrieves a collection of expired leases and reclaims them. See https://gitlab.isc.org/isc-projects/kea/wikis/designs/lease-expiration#leases-reclamation-routine for the details.

This method is executed periodically to act upon expired leases. This includes for each lease:

  • executing "lease_expire4" hook,
  • removing DNS record for a lease,
  • reclaiming a lease in the database, i.e. setting its state to "expired-reclaimed" or removing it from the lease database,
  • updating statistics of assigned and reclaimed leases

Note: declined leases fall under the same expiration/reclamation processing as normal leases. In principle, it would be more elegant to have a separate processing for declined leases reclamation. However, due to performance reasons we decided to use them together. Several aspects were taken into consideration. First, normal leases are expected to expire frequently, so in a typical deployment this method will have some leases to process. Second, declined leases are expected to be very rare event, so in most cases there won't be any declined expired leases. Third, the calls to LeaseMgr to obtain all leases of specific expiration criteria are expensive, so it is better to have one call rather than two, especially if one of those calls is expected to usually return no leases.

It doesn't make sense to retain declined leases that are reclaimed, because those leases don't contain any useful information (all client identifying information was stripped when the leave was moved to the declined state). Therefore remove_leases parameter is ignored for declined leases. They are always removed.

Also, for declined leases reclaimDeclinedLease4 is called. It conducts several declined specific operation (extra log entry, stats dump, hooks).

Parameters
max_leasesMaximum number of leases to be reclaimed.
timeoutMaximum amount of time that the reclamation routine may be processing expired leases, expressed in milliseconds.
remove_leaseA boolean value indicating if the lease should be removed when it is reclaimed (if true) or it should be left in the database in the "expired-reclaimed" state (if false).
max_unwarned_cyclesA number of consecutive processing cycles of expired leases, after which the system issues a warning if there are still expired leases in the database. If this value is 0, the warning is never issued.

Definition at line 2680 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V4_LEASES_RECLAMATION_FAILED, isc::dhcp::ALLOC_ENGINE_V4_LEASES_RECLAMATION_START, LOG_DEBUG, LOG_ERROR, and reclaimExpiredLeases4Internal().

+ Here is the call graph for this function:

◆ reclaimExpiredLeases4Internal()

void isc::dhcp::AllocEngine::reclaimExpiredLeases4Internal ( const size_t max_leases,
const uint16_t timeout,
const bool remove_lease,
const uint16_t max_unwarned_cycles = 0 )

Body of reclaimExpiredLeases4.

Parameters
max_leasesMaximum number of leases to be reclaimed.
timeoutMaximum amount of time that the reclamation routine may be processing expired leases, expressed in milliseconds.
remove_leaseA boolean value indicating if the lease should be removed when it is reclaimed (if true) or it should be left in the database in the "expired-reclaimed" state (if false).
max_unwarned_cyclesA number of consecutive processing cycles of expired leases, after which the system issues a warning if there are still expired leases in the database. If this value is 0, the warning is never issued.

Definition at line 2701 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V4_LEASE_RECLAMATION_FAILED, isc::dhcp::ALLOC_ENGINE_V4_LEASES_RECLAMATION_COMPLETE, isc::dhcp::ALLOC_ENGINE_V4_LEASES_RECLAMATION_SLOW, isc::dhcp::ALLOC_ENGINE_V4_LEASES_RECLAMATION_TIMEOUT, isc::dhcp::ALLOC_ENGINE_V4_NO_MORE_EXPIRED_LEASES, isc::hooks::HooksManager::calloutsPresent(), isc::hooks::HooksManager::createCalloutHandle(), Hooks, isc::dhcp::LeaseMgrFactory::instance(), isc::util::MultiThreadingMgr::instance(), LOG_DEBUG, LOG_ERROR, LOG_WARN, and rw_mutex_.

Referenced by reclaimExpiredLeases4().

+ Here is the call graph for this function:

◆ reclaimExpiredLeases6()

void isc::dhcp::AllocEngine::reclaimExpiredLeases6 ( const size_t max_leases,
const uint16_t timeout,
const bool remove_lease,
const uint16_t max_unwarned_cycles = 0 )

Reclaims expired IPv6 leases.

This method retrieves a collection of expired leases and reclaims them. See https://gitlab.isc.org/isc-projects/kea/wikis/designs/lease-expiration#leases-reclamation-routine for the details.

This method is executed periodically to act upon expired leases. This includes for each lease:

  • executing "lease_expire6" hook,
  • removing DNS record for a lease,
  • reclaiming a lease in the database, i.e. setting its state to "expired-reclaimed" or removing it from the lease database,
  • updating statistics of assigned and reclaimed leases

Note: declined leases fall under the same expiration/reclamation processing as normal leases. In principle, it would be more elegant to have a separate processing for declined leases reclamation. However, due to performance reasons we decided to use them together. Several aspects were taken into consideration. First, normal leases are expected to expire frequently, so in a typical deployment this method will have some leases to process. Second, declined leases are expected to be very rare event, so in most cases there won't be any declined expired leases. Third, the calls to LeaseMgr to obtain all leases of specific expiration criteria are expensive, so it is better to have one call rather than two, especially if one of those calls is expected to usually return no leases.

It doesn't make sense to retain declined leases that are reclaimed, because those leases don't contain any useful information (all client identifying information was stripped when the leave was moved to the declined state). Therefore remove_leases parameter is ignored for declined leases. They are always removed.

Also, for declined leases reclaimDeclinedLease6 is called. It conducts several declined specific operation (extra log entry, stats dump, hooks).

Parameters
max_leasesMaximum number of leases to be reclaimed.
timeoutMaximum amount of time that the reclamation routine may be processing expired leases, expressed in milliseconds.
remove_leaseA boolean value indicating if the lease should be removed when it is reclaimed (if true) or it should be left in the database in the "expired-reclaimed" state (if false).
max_unwarned_cyclesA number of consecutive processing cycles of expired leases, after which the system issues a warning if there are still expired leases in the database. If this value is 0, the warning is never issued.

Definition at line 2517 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V6_LEASES_RECLAMATION_FAILED, isc::dhcp::ALLOC_ENGINE_V6_LEASES_RECLAMATION_START, LOG_DEBUG, LOG_ERROR, and reclaimExpiredLeases6Internal().

+ Here is the call graph for this function:

◆ reclaimExpiredLeases6Internal()

void isc::dhcp::AllocEngine::reclaimExpiredLeases6Internal ( const size_t max_leases,
const uint16_t timeout,
const bool remove_lease,
const uint16_t max_unwarned_cycles = 0 )

Body of reclaimExpiredLeases6.

Parameters
max_leasesMaximum number of leases to be reclaimed.
timeoutMaximum amount of time that the reclamation routine may be processing expired leases, expressed in milliseconds.
remove_leaseA boolean value indicating if the lease should be removed when it is reclaimed (if true) or it should be left in the database in the "expired-reclaimed" state (if false).
max_unwarned_cyclesA number of consecutive processing cycles of expired leases, after which the system issues a warning if there are still expired leases in the database. If this value is 0, the warning is never issued.

Definition at line 2538 of file alloc_engine.cc.

References isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V6_LEASE_RECLAMATION_FAILED, isc::dhcp::ALLOC_ENGINE_V6_LEASES_RECLAMATION_COMPLETE, isc::dhcp::ALLOC_ENGINE_V6_LEASES_RECLAMATION_SLOW, isc::dhcp::ALLOC_ENGINE_V6_LEASES_RECLAMATION_TIMEOUT, isc::dhcp::ALLOC_ENGINE_V6_NO_MORE_EXPIRED_LEASES, isc::hooks::HooksManager::calloutsPresent(), isc::hooks::HooksManager::createCalloutHandle(), Hooks, isc::dhcp::LeaseMgrFactory::instance(), isc::util::MultiThreadingMgr::instance(), LOG_DEBUG, LOG_ERROR, LOG_WARN, and rw_mutex_.

Referenced by reclaimExpiredLeases6().

+ Here is the call graph for this function:

◆ renewLeases6()

Lease6Collection isc::dhcp::AllocEngine::renewLeases6 ( ClientContext6 & ctx)

Renews existing DHCPv6 leases for a given IA.

This method updates the leases associated with a specified IA container. It will extend the leases under normal circumstances, but sometimes there may be reasons why not to do so. Such a reasons may be:

  • client attempts to renew an address that is not valid
  • client attempts to renew an address that is now reserved for someone else (see host reservation)
  • client's leases does not match his reservations

This method will call the lease6_renew callout.

Parameters
ctxMessage processing context. It holds various information extracted from the client's message and required to allocate a lease. In particular, ClientContext6::IAContext::hints_ provides list of addresses or prefixes the client had sent. ClientContext6::IAContext::old_leases_ will contain removed leases in this case.
Returns
Returns renewed lease.

Definition at line 2085 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext6::addAllocatedResource(), isc::dhcp::ALLOC_ENGINE_DBG_TRACE, isc::dhcp::ALLOC_ENGINE_DBG_TRACE_DETAIL, isc::dhcp::alloc_engine_logger, isc::dhcp::ALLOC_ENGINE_V6_EXTEND_ALLOC_UNRESERVED, isc::dhcp::ALLOC_ENGINE_V6_EXTEND_ERROR, isc::dhcp::ALLOC_ENGINE_V6_EXTEND_LEASE, isc::dhcp::ALLOC_ENGINE_V6_RENEW_HR, isc::dhcp::ALLOC_ENGINE_V6_RENEW_REMOVE_RESERVED, isc::dhcp::AllocEngine::ClientContext6::currentIA(), isc::dhcp::AllocEngine::ClientContext6::duid_, isc::dhcp::AllocEngine::ClientContext6::hosts_, isc::dhcp::AllocEngine::ClientContext6::IAContext::iaid_, isc::dhcp::LeaseMgrFactory::instance(), isc_throw, isc::dhcp::AllocEngine::ClientContext6::IAContext::isNewResource(), LOG_DEBUG, LOG_ERROR, isc::dhcp::AllocEngine::ClientContext6::new_leases_, isc::dhcp::AllocEngine::ClientContext6::query_, isc::dhcp::AllocEngine::ClientContext6::subnet_, and isc::dhcp::AllocEngine::ClientContext6::IAContext::type_.

+ Here is the call graph for this function:

◆ updateLease4ExtendedInfo()

bool isc::dhcp::AllocEngine::updateLease4ExtendedInfo ( const Lease4Ptr & lease,
const ClientContext4 & ctx ) const
protected

Stores additional client query parameters on a V4 lease.

Extended features such as LeaseQuery require additional parameters to be stored for each lease, than we would otherwise retain. This function adds that information to the lease's user-context. (Note it is protected to facilitate unit testing).

Warning
This method doesn't check if the pointer to the lease is valid nor if the subnet to the pointer in the ctx is valid. The caller is responsible for making sure that they are valid.
Parameters
[out]leaseA pointer to the lease to be updated.
ctxA context containing information from the server about the client and its message.
Returns
True if there was a significant (e.g. other than cltt) change, false otherwise.

Definition at line 4969 of file alloc_engine.cc.

References isc::data::Element::boolean, isc::data::copy(), isc::data::Element::create(), isc::data::Element::createMap(), isc::dhcp::DHO_DHCP_AGENT_OPTIONS, isc::util::encode::encodeHex(), isc::dhcp::CfgMgr::instance(), isc::data::Element::map, isc::dhcp::AllocEngine::ClientContext4::query_, isc::dhcp::RAI_OPTION_RELAY_ID, isc::dhcp::RAI_OPTION_REMOTE_ID, isc::dhcp::CfgGlobals::STASH_AGENT_OPTIONS, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

+ Here is the call graph for this function:

◆ updateLease6ExtendedInfo()

void isc::dhcp::AllocEngine::updateLease6ExtendedInfo ( const Lease6Ptr & lease,
const ClientContext6 & ctx ) const
protected

Stores additional client query parameters on a V6 lease.

Extended features such as LeaseQuery and Reconfigure require additional parameters to be stored for each lease, than we would otherwise retain. This function adds that information to the lease's user-context. (Note it is protected to facilitate unit testing).

Warning
This method doesn't check if the pointer to the lease is valid nor if the subnet to the pointer in the ctx is valid. The caller is responsible for making sure that they are valid.
Parameters
[out]leaseA pointer to the lease to be updated.
ctxA context containing information from the server about the client and its message.

Definition at line 5053 of file alloc_engine.cc.

References isc::dhcp::Lease6::ACTION_IGNORE, isc::dhcp::Lease6::ACTION_UPDATE, isc::data::copy(), isc::data::Element::create(), isc::data::Element::createList(), isc::data::Element::createMap(), D6O_RELAY_ID, D6O_REMOTE_ID, isc::util::encode::encodeHex(), isc::data::Element::map, isc::dhcp::LibDHCP::packOptions6(), isc::dhcp::AllocEngine::ClientContext6::query_, and isc::dhcp::AllocEngine::ClientContext6::subnet_.

+ Here is the call graph for this function:

Member Data Documentation

◆ rw_mutex_

isc::util::ReadWriteMutex isc::dhcp::AllocEngine::rw_mutex_

The read-write mutex.

Definition at line 1858 of file alloc_engine.h.

Referenced by getReadWriteMutex(), reclaimExpiredLeases4Internal(), and reclaimExpiredLeases6Internal().


The documentation for this class was generated from the following files: