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< ClientContext4 >	ClientContext4Ptr
	Pointer to the `ClientContext4`.

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

typedef std::list< IdentifierPair >	IdentifierList
	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, ResourceCompare >	ResourceContainer
	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::ReadWriteMutex &	getReadWriteMutex ()
	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 (ConstSubnetPtr 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

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

Pointer to the ClientContext4.

Definition at line 1386 of file alloc_engine.h.

◆ HintContainer

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

Container for client's hints.

Definition at line 185 of file alloc_engine.h.

◆ IdentifierList

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

Map holding values to be used as host identifiers.

Definition at line 194 of file alloc_engine.h.

◆ IdentifierPair

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

std::set<Resource, ResourceCompare> isc::dhcp::AllocEngine::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

attempts number 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

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 3693 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:

◆ 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:

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 461 of file alloc_engine.cc.

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] lease A pointer to the reclaimed lease.

Definition at line 3267 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] lease A pointer to the reclaimed lease.

Definition at line 3276 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

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

Definition at line 3100 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:

◆ deleteExpiredReclaimedLeases6()

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 2667 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:

◆ 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

ctx	Client context holding various information about the client.

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

Definition at line 3840 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:

◆ 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

ctx	Client 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::HostMgr::get6(), 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

ctx	Client context holding various information about the client.

Definition at line 3737 of file alloc_engine.cc.

References isc::dhcp::AllocEngine::ClientContext4::early_global_reservations_lookup_, 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:

◆ 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

ctx	Client 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::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:

◆ 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

	ctx	client context that passes all necessary information. See ClientContext6 for details.
[out]	preferred	set to the preferred lifetime that should be used.
[out]	valid	set 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::ClientClasses::empty(), isc::util::Triplet< T >::get(), isc::dhcp::CfgMgr::getCurrentCfg(), isc::dhcp::AllocEngine::ClientContext6::IAContext::hints_, isc::dhcp::CfgMgr::instance(), LOG_DEBUG, isc::dhcp::AllocEngine::ClientContext6::query_, isc::dhcp::AllocEngine::ClientContext6::subnet_, and isc::util::Optional< T >::unspecified().

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

ctx	Client context holding various information about the client.

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

Definition at line 4183 of file alloc_engine.cc.

References isc::dhcp::ClientClasses::empty(), isc::dhcp::AllocEngine::ClientContext4::fake_allocation_, isc::util::Optional< T >::get(), isc::dhcp::CfgMgr::getCurrentCfg(), isc::dhcp::CfgMgr::instance(), isc::dhcp::AllocEngine::ClientContext4::query_, isc::dhcp::AllocEngine::ClientContext4::subnet_, and isc::util::Optional< T >::unspecified().

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 1861 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

ctx	Client context holding various information about the client.

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

Definition at line 4218 of file alloc_engine.cc.

References isc::dhcp::DHO_DHCP_LEASE_TIME, isc::dhcp::ClientClasses::empty(), isc::util::Triplet< T >::get(), isc::dhcp::CfgMgr::getCurrentCfg(), 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 ( ConstSubnetPtr 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

subnet pointer to the source subnet

Returns: string containing the generated label

Definition at line 3317 of file alloc_engine.cc.

◆ makeIPv6Resrv()

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

References isc::dhcp::Lease::addr_, isc::dhcp::Lease6::prefixlen_, isc::dhcp::Lease6::type_, 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_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 2689 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_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 2710 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(), isc::dhcp::LeaseMgr::getExpiredLeases4(), isc::util::Stopwatch::getTotalMilliseconds(), Hooks, isc::dhcp::LeaseMgrFactory::instance(), isc::util::MultiThreadingMgr::instance(), LOG_DEBUG, LOG_ERROR, LOG_WARN, isc::util::Stopwatch::logFormatTotalDuration(), rw_mutex_, and isc::util::Stopwatch::stop().

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_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 2526 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_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 2547 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(), isc::dhcp::LeaseMgr::getExpiredLeases6(), isc::util::Stopwatch::getTotalMilliseconds(), Hooks, isc::dhcp::LeaseMgrFactory::instance(), isc::util::MultiThreadingMgr::instance(), LOG_DEBUG, LOG_ERROR, LOG_WARN, isc::util::Stopwatch::logFormatTotalDuration(), rw_mutex_, and isc::util::Stopwatch::stop().

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

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 2085 of file alloc_engine.cc.

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]	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 4981 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::getCurrentCfg(), 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]	lease	A pointer to the lease to be updated.
	ctx	A context containing information from the server about the client and its message.

Definition at line 5065 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::util::OutputBuffer::getData(), isc::util::OutputBuffer::getLength(), 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 1866 of file alloc_engine.h.

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

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ClientContext4Ptr

◆ HintContainer

◆ IdentifierList

◆ IdentifierPair

◆ ResourceContainer

Constructor & Destructor Documentation

◆ AllocEngine()

◆ ~AllocEngine()

Member Function Documentation

◆ allocateLease4()

◆ allocateLeases6()

◆ clearReclaimedExtendedInfo() [1/2]

◆ clearReclaimedExtendedInfo() [2/2]

◆ deleteExpiredReclaimedLeases4()

◆ deleteExpiredReclaimedLeases6()

◆ findGlobalReservation() [1/2]

◆ findGlobalReservation() [2/2]

◆ findReservation() [1/2]

◆ findReservation() [2/2]

◆ getLifetimes6()

◆ getOfferLft()

◆ getReadWriteMutex()

◆ getValidLft()

◆ labelNetworkOrSubnet()

◆ makeIPv6Resrv()

◆ reclaimExpiredLeases4()

◆ reclaimExpiredLeases4Internal()

◆ reclaimExpiredLeases6()

◆ reclaimExpiredLeases6Internal()

◆ renewLeases6()

◆ updateLease4ExtendedInfo()

◆ updateLease6ExtendedInfo()

Member Data Documentation

◆ rw_mutex_