DHCPv4 and DHCPv6 allocation engine. More...

#include <alloc_engine.h>

Inheritance diagram for isc::dhcp::AllocEngine:

Classes
class	Allocator
	Base class for all address/prefix allocation algorithms. More...

struct	ClientContext4
	Context information for the DHCPv4 lease allocation. More...

struct	ClientContext6
	Context information for the DHCPv6 leases allocation. More...

class	HashedAllocator
	Address/prefix allocator that gets an address based on a hash. More...

class	IterativeAllocator
	Address/prefix allocator that iterates over all addresses. More...

class	RandomAllocator
	Random allocator that picks address randomly. More...

class	Resource
	Defines a single hint. More...

struct	ResourceCompare
	Resource compare class. More...

Public Types
enum	AllocType { ALLOC_ITERATIVE, ALLOC_HASHED, ALLOC_RANDOM }
	Specifies allocation type. More...

typedef boost::shared_ptr< ClientContext4 >	ClientContext4Ptr
	Pointer to the `ClientContext4`. More...

typedef std::vector< Resource >	HintContainer
	Container for client's hints. More...

typedef std::list< IdentifierPair >	IdentifierList
	Map holding values to be used as host identifiers. More...

typedef std::pair< Host::IdentifierType, std::vector< uint8_t > >	IdentifierPair
	A tuple holding host identifier type and value. More...

typedef std::set< Resource, ResourceCompare >	ResourceContainer
	Container holding allocated prefixes or addresses. More...

Public Member Functions
	AllocEngine (AllocType engine_type, uint64_t attempts, bool ipv6=true)
	Constructor. More...

virtual	~AllocEngine ()
	Destructor. More...

Lease4Ptr	allocateLease4 (ClientContext4 &ctx)
	Returns IPv4 lease. More...

Lease6Collection	allocateLeases6 (ClientContext6 &ctx)
	Allocates IPv6 leases for a given IA container. More...

void	deleteExpiredReclaimedLeases4 (const uint32_t secs)
	Deletes reclaimed leases expired more than specified amount of time ago. More...

void	deleteExpiredReclaimedLeases6 (const uint32_t secs)
	Deletes reclaimed leases expired more than specified amount of time ago. More...

AllocatorPtr	getAllocator (Lease::Type type)
	Returns allocator for a given pool type. More...

isc::util::ReadWriteMutex &	getReadWriteMutex ()
	Get the read-write mutex. More...

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. More...

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. More...

Lease6Collection	renewLeases6 (ClientContext6 &ctx)
	Renews existing DHCPv6 leases for a given IA. More...

Static Public Member Functions
static ConstHostPtr	findGlobalReservation (ClientContext6 &ctx)
	Attempts to find the host reservation for the client. More...

static ConstHostPtr	findGlobalReservation (ClientContext4 &ctx)
	Attempts to find the host reservation for the client. More...

static void	findReservation (ClientContext6 &ctx)
	Attempts to find appropriate host reservation. More...

static void	findReservation (ClientContext4 &ctx)
	Attempts to find the host reservation for the client. More...

static uint32_t	getValidLft (const ClientContext4 &ctx)
	Returns the valid lifetime based on the v4 context. More...

static IPv6Resrv	makeIPv6Resrv (const Lease6 &lease)
	Creates an IPv6Resrv instance from a Lease6. More...

Public Attributes
isc::util::ReadWriteMutex	rw_mutex_
	The read-write mutex. More...

Protected Types
typedef boost::shared_ptr< Allocator >	AllocatorPtr
	defines a pointer to allocator More...

Protected Member Functions
bool	updateLease4ExtendedInfo (const Lease4Ptr &lease, const ClientContext4 &ctx) const
	Stores additional client query parameters on a V4 lease. More...

bool	updateLease6ExtendedInfo (const Lease6Ptr &lease, const ClientContext6 &ctx) const
	Stores additional client query parameters on a V6 lease. More...

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.

Todo:

: Does not handle out of leases well

: Does not handle out of allocation attempts well

Definition at line 63 of file alloc_engine.h.

Member Typedef Documentation

typedef boost::shared_ptr<Allocator> isc::dhcp::AllocEngine::AllocatorPtr

protected

defines a pointer to allocator

Definition at line 140 of file alloc_engine.h.

typedef boost::shared_ptr<ClientContext4> isc::dhcp::AllocEngine::ClientContext4Ptr

Pointer to the ClientContext4.

Definition at line 1492 of file alloc_engine.h.

typedef std::vector<Resource> isc::dhcp::AllocEngine::HintContainer

Container for client's hints.

Definition at line 426 of file alloc_engine.h.

typedef std::list<IdentifierPair> isc::dhcp::AllocEngine::IdentifierList

Map holding values to be used as host identifiers.

Definition at line 435 of file alloc_engine.h.

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

A tuple holding host identifier type and value.

Definition at line 432 of file alloc_engine.h.

typedef std::set<Resource, ResourceCompare> isc::dhcp::AllocEngine::ResourceContainer

Container holding allocated prefixes or addresses.

Definition at line 429 of file alloc_engine.h.

Member Enumeration Documentation

enum isc::dhcp::AllocEngine::AllocType

Specifies allocation type.

Enumerator
ALLOC_ITERATIVE
ALLOC_HASHED
ALLOC_RANDOM

Definition at line 268 of file alloc_engine.h.

Constructor & Destructor Documentation

isc::dhcp::AllocEngine::AllocEngine	(	AllocType	engine_type,
		uint64_t	attempts,
		bool	ipv6 = `true`
	)

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

engine_type	selects allocation algorithm
attempts	number of attempts for each lease allocation before we give up (0 means unlimited)
ipv6	specifies if the engine should work for IPv4 or IPv6

Definition at line 315 of file alloc_engine.cc.

References ALLOC_HASHED, ALLOC_ITERATIVE, ALLOC_RANDOM, Hooks, isc_throw, isc::dhcp::Lease::TYPE_NA, isc::dhcp::Lease::TYPE_PD, isc::dhcp::Lease::TYPE_TA, and isc::dhcp::Lease::TYPE_V4.

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

inlinevirtual

Destructor.

Definition at line 288 of file alloc_engine.h.

Member Function Documentation

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

ctx	client context that passes all necessary information. See ClientContext4 for details.

The following fields of ClientContext4 are used:

ClientContext4::subnet_ subnet the allocation should come from
ClientContext4::clientid_ Client identifier
ClientContext4::hwaddr_ Client's hardware address info
ClientContext4::requested_address_ A hint that the client provided
ClientContext4::fwd_dns_update_ Indicates whether forward DNS update will be performed for the client (true) or not (false).
ClientContext4::rev_dns_update_ Indicates whether reverse DNS update will be performed for the client (true) or not (false).
ClientContext4::hostname_ A string carrying hostname to be used for DNS updates.
ClientContext4::fake_allocation_ Is this real i.e. REQUEST (false) or just picking an address for DISCOVER that is not really allocated (true)
ClientContext4::callout_handle_ A callout handle (used in hooks). A lease callouts will be executed if this parameter is passed.
ClientContext4::old_lease_ [out] Holds the pointer to a previous instance of a lease. The NULL pointer indicates that lease didn't exist prior to calling this function (e.g. new lease has been allocated).

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

Definition at line 3400 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_, isc::dhcp::AllocEngine::ClientContext4::subnet_, and isc::Exception::what().

Here is the call graph for this function:

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:

disabled (no host reservation at all). This is the most performant one as the code can skip all checks;
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);
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:

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
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
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
Case 4. if there are no leases and no reservations... assign new leases (this is the "normal" case when the reservations are disabled).

Parameters

ctx	client 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 708 of file alloc_engine.cc.

Here is the call graph for this function:

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

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

Parameters

secs	Minimum number of seconds after which the lease can be deleted.

Definition at line 2896 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::LeaseMgr::deleteExpiredReclaimedLeases4(), isc::dhcp::LeaseMgrFactory::instance(), LOG_DEBUG, and LOG_ERROR.

Here is the call graph for this function:

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

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

Parameters

secs	Minimum number of seconds after which the lease can be deleted.

Definition at line 2543 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::LeaseMgr::deleteExpiredReclaimedLeases6(), isc::dhcp::LeaseMgrFactory::instance(), LOG_DEBUG, and LOG_ERROR.

Here is the call graph for this function:

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

ctx	Client context holding various information about the client.

Returns: Pointer to the reservation found, or an empty pointer.

Definition at line 691 of file alloc_engine.cc.

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

Referenced by findReservation().

Here is the call graph for this function:

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

ctx	Client context holding various information about the client.

Returns: Pointer to the reservation found, or an empty pointer.

Definition at line 3535 of file alloc_engine.cc.

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

Here is the call graph for this function:

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

ctx	Client context that contains all necessary information.

Definition at line 600 of file alloc_engine.cc.

References findGlobalReservation(), isc::dhcp::HostMgr::get6(), isc::dhcp::HostMgr::getAll(), isc::dhcp::HostMgr::getDisableSingleQuery(), 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:

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

ctx	Client context holding various information about the client.

Definition at line 3444 of file alloc_engine.cc.

References findGlobalReservation(), isc::dhcp::HostMgr::get4(), isc::dhcp::HostMgr::getAll(), isc::dhcp::HostMgr::getDisableSingleQuery(), 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:

AllocEngine::AllocatorPtr isc::dhcp::AllocEngine::getAllocator ( Lease::Type type )

Returns allocator for a given pool type.

Parameters

type	type of pool (V4, IA, TA or PD)

Exceptions

BadValue if allocator for a given type is missing

Returns: pointer to allocator handling a given resource types

Definition at line 364 of file alloc_engine.cc.

References isc_throw, and isc::dhcp::Lease::typeToText().

Here is the call graph for this function:

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 1945 of file alloc_engine.h.

References rw_mutex_.

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

ctx	Client context holding various information about the client.

Returns: unsigned integer value of the valid lifetime to use.

Definition at line 3846 of file alloc_engine.cc.

References isc::dhcp::ClientClasses::cbegin(), isc::dhcp::ClientClasses::cend(), isc::dhcp::DHO_DHCP_LEASE_TIME, isc::dhcp::ClientClasses::empty(), isc::dhcp::Triplet< T >::get(), isc::dhcp::CfgMgr::getCurrentCfg(), isc::dhcp::OptionInt< T >::getValue(), isc::dhcp::Lease::INFINITY_LFT, isc::dhcp::CfgMgr::instance(), isc::dhcp::AllocEngine::ClientContext4::query_, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

Here is the call graph for this function:

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

inlinestatic

Creates an IPv6Resrv instance from a Lease6.

Parameters

lease Reference to the Lease6

Returns: The newly formed IPv6Resrv instance

Definition at line 990 of file alloc_engine.h.

References isc::dhcp::Lease::addr_, isc::dhcp::Lease6::prefixlen_, isc::dhcp::Lease6::type_, isc::dhcp::Lease::TYPE_NA, isc::dhcp::IPv6Resrv::TYPE_NA, and isc::dhcp::IPv6Resrv::TYPE_PD.

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_leases	Maximum number of leases to be reclaimed.
timeout	Maximum amount of time that the reclamation routine may be processing expired leases, expressed in milliseconds.
remove_lease	A 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_cycles	A 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 2565 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_START, isc::dhcp::ALLOC_ENGINE_V4_LEASES_RECLAMATION_TIMEOUT, isc::dhcp::ALLOC_ENGINE_V4_NO_MORE_EXPIRED_LEASES, isc::dhcp::LeaseMgr::getExpiredLeases4(), isc::util::Stopwatch::getTotalMilliseconds(), Hooks, isc::dhcp::LeaseMgrFactory::instance(), LOG_DEBUG, LOG_ERROR, LOG_WARN, isc::util::Stopwatch::logFormatTotalDuration(), rw_mutex_, and isc::util::Stopwatch::stop().

Here is the call graph for this function:

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_leases	Maximum number of leases to be reclaimed.
timeout	Maximum amount of time that the reclamation routine may be processing expired leases, expressed in milliseconds.
remove_lease	A 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_cycles	A 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 2419 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_START, isc::dhcp::ALLOC_ENGINE_V6_LEASES_RECLAMATION_TIMEOUT, isc::dhcp::ALLOC_ENGINE_V6_NO_MORE_EXPIRED_LEASES, isc::dhcp::LeaseMgr::getExpiredLeases6(), isc::util::Stopwatch::getTotalMilliseconds(), Hooks, isc::dhcp::LeaseMgrFactory::instance(), LOG_DEBUG, LOG_ERROR, LOG_WARN, isc::util::Stopwatch::logFormatTotalDuration(), rw_mutex_, and isc::util::Stopwatch::stop().

Here is the call graph for this function:

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

ctx Message 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 2033 of file alloc_engine.cc.

Here is the call graph for this function:

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]	lease	A pointer to the lease to be updated.
	ctx	A 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 4480 of file alloc_engine.cc.

References isc::dhcp::DHO_DHCP_AGENT_OPTIONS, isc::dhcp::AllocEngine::ClientContext4::query_, and isc::dhcp::AllocEngine::ClientContext4::subnet_.

bool 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]	lease	A pointer to the lease to be updated.
	ctx	A 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 4525 of file alloc_engine.cc.

References isc::util::encode::encodeHex(), isc::util::OutputBuffer::getData(), isc::util::OutputBuffer::getLength(), 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

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

The read-write mutex.

Definition at line 1950 of file alloc_engine.h.

Referenced by getReadWriteMutex(), reclaimExpiredLeases4(), and reclaimExpiredLeases6().

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation