Kea: isc::dhcp::Lease4 Struct Reference

| Kea 3.2.0-git

isc::dhcp::Lease4 Struct Reference

Structure that holds a lease for IPv4 address. More...

`#include <lease.h>`

Inheritance diagram for isc::dhcp::Lease4:
[legend]

## Public Member Functions
| Lease4 ()
| Default constructor.
| Lease4 (const isc::asiolink::IOAddress &addr, const HWAddrPtr &hwaddr, const uint8_t *clientid, size_t clientid_len, uint32_t valid_lft, time_t cltt, uint32_t subnet_id, const bool fqdn_fwd=false, const bool fqdn_rev=false, const std::string &hostname="")
| Constructor.
| Lease4 (const isc::asiolink::IOAddress &address, const HWAddrPtr &hw_address, const ClientIdPtr &client_id, const uint32_t valid_lifetime, const time_t cltt, const SubnetID subnet_id, const bool fqdn_fwd=false, const bool fqdn_rev=false, const std::string &hostname="")
| Constructor.
bool | belongsToClient (const HWAddrPtr &hw_address, const ClientIdPtr &client_id) const
| Check if the lease belongs to the client with the given identifiers.
void | decline (uint32_t probation_period)
| Sets IPv4 lease to declined state.
const std::vector< uint8_t > & | getClientIdVector () const
| Returns a client identifier.
virtual Lease::Type | getType () const
| Returns Lease type.
bool | operator!= (const Lease4 &other) const
| Compare two leases for inequality.
bool | operator== (const Lease4 &other) const
| Compare two leases for equality.
virtual isc::data::ElementPtr | toElement () const
| Return the JSON representation of a lease.
virtual std::string | toText () const
| Convert lease to printable form.
| Lease (const isc::asiolink::IOAddress &addr, uint32_t valid_lft, SubnetID subnet_id, time_t cltt, const bool fqdn_fwd, const bool fqdn_rev, const std::string &hostname, const HWAddrPtr &hwaddr)
| Constructor.
virtual | ~Lease ()
| Destructor.
bool | expired () const
| returns true if the lease is expired
bool | stateExpiredReclaimed () const
| Indicates if the lease is in the "expired-reclaimed" state.
bool | stateDeclined () const
| Indicates if the lease is in the "declined" state.
bool | stateRegistered () const
| Indicates if the lease is in the "registered" state.
bool | hasIdenticalFqdn (const Lease &other) const
| Returns true if the other lease has equal FQDN data.
const std::vector< uint8_t > & | getHWAddrVector () const
| Returns raw (as vector) hardware address.
int64_t | getExpirationTime () const
| Returns lease expiration time.
void | updateCurrentExpirationTime ()
| Update lease current expiration time with new value, so that additional operations can be done without performing extra read from the database.
bool | updateUserContextISC (const std::string elem_name, data::ConstElementPtr new_values)
| Update the ISC entry in the lease's user-context.
Public Member Functions inherited from isc::data::UserContext
void | contextToElement (data::ElementPtr map) const
| Merge unparse a user_context object.
data::ConstElementPtr | getContext () const
| Returns const pointer to the user context.
void | setContext (const data::ConstElementPtr &ctx)
| Sets user context.
Public Member Functions inherited from isc::data::CfgToElement
virtual | ~CfgToElement ()
| Destructor.

## Static Public Member Functions
static Lease4Ptr | fromElement (const data::ConstElementPtr &element)
| Returns pointer to the IPv4 lease created from JSON representation.
static std::string | statesToText (const uint32_t state)
| Returns name of the lease states specific to DHCPv4.
Static Public Member Functions inherited from isc::dhcp::Lease
static std::string | lifetimeToText (uint32_t lifetime)
| Print lifetime.
static Type | textToType (const std::string &text)
| Converts type name to the actual type.
static std::string | typeToText (Type type)
| returns text representation of a lease type
static std::string | basicStatesToText (const uint32_t state)
| Returns name(s) of the basic lease state(s).
static void | syncCurrentExpirationTime (const Lease &from, Lease &to)
| Sync lease current expiration time with new value from another lease, so that additional operations can be done without performing extra read from the database.
Static Public Member Functions inherited from isc::data::UserContext
static data::ElementPtr | toElement (data::ConstElementPtr map)
| Copy an Element map.

## Public Attributes
ClientIdPtr | client_id_
| Client identifier.
std::vector< uint8_t > | relay_id_
| Relay identifier for Bulk Lease Query.
std::vector< uint8_t > | remote_id_
| Remote identifier for Bulk Lease Query.
isc::asiolink::IOAddress | addr_
| IPv4 ot IPv6 address.
uint32_t | valid_lft_
| Valid lifetime.
uint32_t | current_valid_lft_
| Current valid lifetime.
uint32_t | reuseable_valid_lft_
| Remaining valid lifetime.
time_t | cltt_
| Client last transmission time.
time_t | current_cltt_
| Current client last transmission time.
SubnetID | subnet_id_
| Subnet identifier.
uint32_t | pool_id_
| The pool id.
std::string | hostname_
| Client hostname.
bool | fqdn_fwd_
| Forward zone updated?
bool | fqdn_rev_
| Reverse zone updated?
HWAddrPtr | hwaddr_
| Client's MAC/hardware address.
uint32_t | state_
| Holds the lease state(s).

## Additional Inherited Members
Public Types inherited from isc::dhcp::Lease
enum | Type : uint16_t { TYPE_NA = 0 , TYPE_TA = 1 , TYPE_PD = 2 , TYPE_V4 = 3 }
| Type of lease or pool. More...
Static Public Attributes inherited from isc::dhcp::Lease
static const uint32_t | INFINITY_LFT = 0xffffffff
| Infinity (means static, i.e. never expire).
static constexpr uint32_t | STATE_DEFAULT = 0
| A lease in the default state.
static constexpr uint32_t | STATE_DECLINED = 1
| Declined lease.
static constexpr uint32_t | STATE_EXPIRED_RECLAIMED = 2
| Expired and reclaimed lease.
static constexpr uint32_t | STATE_RELEASED = 3
| Released lease held in the database for lease affinity.
static constexpr uint32_t | STATE_REGISTERED = 4
| Registered self-generated lease.
static void | fromElementCommon (const LeasePtr &lease, const data::ConstElementPtr &element)
| Sets common (for v4 and v6) properties of the lease object.
Protected Attributes inherited from isc::data::UserContext
data::ConstElementPtr | user_context_
| Pointer to the user context (may be NULL).

## Detailed Description

Structure that holds a lease for IPv4 address.

For performance reasons it is a simple structure, not a class. If we chose make it a class, all fields would have to made private and getters/setters would be required. As this is a critical part of the code that will be used extensively, direct access is warranted.

Definition at line 323 of file lease.h.

## Constructor & Destructor Documentation

## ◆ Lease4() [1/3]

isc::dhcp::Lease4::Lease4 | ( | const isc::asiolink::IOAddress & | addr,
|  | const HWAddrPtr & | hwaddr,
|  | const uint8_t * | clientid,
|  | size_t | clientid_len,
|  | uint32_t | valid_lft,
|  | time_t | cltt,
|  | uint32_t | subnet_id,
|  | const bool | fqdn_fwd = false,
|  | const bool | fqdn_rev = false,
|  | const std::string & | hostname = "" )
| inline

Constructor.

Parameters

  addr | IPv4 address.
  hwaddr | A pointer to HWAddr structure
  clientid | Client identification buffer
  clientid_len | Length of client identification buffer
  valid_lft | Lifetime of the lease
  cltt | Client last transmission time
  subnet_id | Subnet identification
  fqdn_fwd | If true, forward DNS update is performed for a lease.
  fqdn_rev | If true, reverse DNS update is performed for a lease.
  hostname | FQDN of the client which gets the lease.

Definition at line 343 of file lease.h.

References isc::dhcp::Lease::Lease(), and client_id_.

Referenced by operator!=(), and operator==().

Here is the call graph for this function:

## ◆ Lease4() [2/3]

isc::dhcp::Lease4::Lease4 | ( | const isc::asiolink::IOAddress & | address,
|  | const HWAddrPtr & | hw_address,
|  | const ClientIdPtr & | client_id,
|  | const uint32_t | valid_lifetime,
|  | const time_t | cltt,
|  | const SubnetID | subnet_id,
|  | const bool | fqdn_fwd = false,
|  | const bool | fqdn_rev = false,
|  | const std::string & | hostname = "" )

Constructor.

Parameters

  address | IPv4 address.
  hw_address | Pointer to client's HW address.
  client_id | pointer to the client id structure.
  valid_lifetime | Valid lifetime value.
  cltt | Timestamp when the lease is acquired, renewed.
  subnet_id | Subnet identifier.
  fqdn_fwd | Forward DNS update performed.
  fqdn_rev | Reverse DNS update performed.
  hostname | Client's name for the DNS update..

Definition at line 321 of file lease.cc.

References isc::dhcp::Lease::Lease(), client_id_, relay_id_, and remote_id_.

Here is the call graph for this function:

## ◆ Lease4() [3/3]

isc::dhcp::Lease4::Lease4 | ( |  | ) |

Default constructor.

Initialize fields that don't have a default constructor.

Definition at line 335 of file lease.cc.

References isc::dhcp::Lease::Lease().

Referenced by fromElement().

Here is the call graph for this function:

## Member Function Documentation

## ◆ belongsToClient()

bool isc::dhcp::Lease4::belongsToClient | ( | const HWAddrPtr & | hw_address,
|  | const ClientIdPtr & | client_id ) const

Check if the lease belongs to the client with the given identifiers.

This method checks if the lease belongs to the client using the specified HW address and/or client identifier. Note that any of the pointers passed to this method may be set to null, in which case they are treated as unspecified and are not used for matching the client with the lease.

According to the DHCPv4 specifications, the client identifier takes precedence over the HW address when identifying the lease for the client on the server side. In particular, the RFC4361 introduces the use of DUID for DHCPv4 which should be a stable identifier for the client. The use of stable identifier allows for the correlation of the DHCPv4 and DHCPv6 clients in the dual stack networks. It also allows for allocating the same lease to the client which hardware (and thus MAC address) has changed.

By default, Kea respects the precedence of the client identifier over MAC address and when this method finds the match of the client identifier with the client identifier stored in the lease, it will treat the lease as the lease of this client, even when the HW address doesn't match.

The HW address is used for matching the client with the lease only when the lease is not associated with any client identifier (client identifier for the lease is null) or when the client identifier parameter passed to this method is null. This facilitates the following cases:

- client didn't generate client identifier and is only using the chaddr field to identify itself.
- server's administrator configured the server to NOT match client identifiers, the client obtained the new lease, and the administrator reconfigured the server to match the client identifiers. The client is trying to renew its lease and both the client identifier and HW address is used for matching the lease which doesn't have the record of the client identifier.
- client obtained the lease using the HW address and client identifier, the server's administrator configured the server to NOT match the client identifiers, and the client returns to renew the lease. This time, the lease has a record of both client identifier and the HW address but only the HW address is used for matching the client to the lease.

Note that the typical case when the server's administrator may want to disable matching the client identifier passed in the client's message is when the client is performing multi-stage boot. In such case, the client identifiers may change on various stages of the boot, but the HW address will remain stable. The server's administrator prefers using the HW address for client identification in this case.

It may also be useful to disable matching client identifiers to mitigate the problem of broken client implementations which generate new client identifiers every time they connect to the network.

Parameters

  hw_address | Pointer to the HW address of the client.
  client_id | Pointer to the client identifier structure.

Returns
  true if the lease belongs to the client using the specified hardware address and/or client identifier.

Definition at line 363 of file lease.cc.

References client_id_, isc::util::equalValues(), and isc::dhcp::Lease::hwaddr_.

Here is the call graph for this function:

## ◆ decline()

void isc::dhcp::Lease4::decline | ( | uint32_t | probation_period | ) |
| virtual

Sets IPv4 lease to declined state.

See Lease::decline for detailed description.

Parameters

  probation_period | valid lifetime will be set to this value

Implements isc::dhcp::Lease.

Definition at line 380 of file lease.cc.

References client_id_, isc::dhcp::Lease::cltt_, isc::dhcp::Lease::fqdn_fwd_, isc::dhcp::Lease::fqdn_rev_, isc::dhcp::Lease::hostname_, isc::dhcp::Lease::hwaddr_, isc::data::UserContext::setContext(), isc::dhcp::Lease::state_, isc::dhcp::Lease::STATE_DECLINED, and isc::dhcp::Lease::valid_lft_.

Here is the call graph for this function:

## ◆ fromElement()

Lease4Ptr isc::dhcp::Lease4::fromElement | ( | const data::ConstElementPtr & | element | ) |
| static

Returns pointer to the IPv4 lease created from JSON representation.

Parameters

  element | pointer to the data element object to be parsed.

Returns
  Pointer to the created lease.

Definition at line 421 of file lease.cc.

References Lease4(), isc::dhcp::Lease::fromElementCommon(), isc::dhcp::ClientId::fromText(), isc_throw, and isc::data::Element::string.

Here is the call graph for this function:

## ◆ getClientIdVector()

const std::vector< uint8_t > & isc::dhcp::Lease4::getClientIdVector | ( |  | ) | const

Returns a client identifier.

Warning
  Since the function returns the reference to a vector (not a copy), the returned object should be used with caution because it will remain valid only for the period of time when an object which returned it exists.

Returns
  A reference to a vector holding client identifier, or an empty vector if client identifier is NULL.

Definition at line 344 of file lease.cc.

References client_id_.

## ◆ getType()

virtual Lease::Type isc::dhcp::Lease4::getType | ( |  | ) | const
| inlinevirtual

Returns Lease type.

Since `Lease` does not define a member for lease type, we implement this so we don't store the same value in a billion v4 lease instances.

Returns
  Lease::TYPE_V4

Implements isc::dhcp::Lease.

Definition at line 388 of file lease.h.

References isc::dhcp::Lease::TYPE_V4.

## ◆ operator!=()

bool isc::dhcp::Lease4::operator!= | ( | const Lease4 & | other | ) | const
| inline

Compare two leases for inequality.

Parameters

  other | lease6 object with which to compare

Definition at line 484 of file lease.h.

References Lease4().

Here is the call graph for this function:

## ◆ operator==()

bool isc::dhcp::Lease4::operator== | ( | const Lease4 & | other | ) | const

Compare two leases for equality.

Parameters

  other | lease6 object with which to compare

Definition at line 603 of file lease.cc.

References Lease4(), isc::dhcp::Lease::addr_, client_id_, isc::dhcp::Lease::cltt_, isc::dhcp::Lease::current_cltt_, isc::dhcp::Lease::current_valid_lft_, isc::dhcp::Lease::fqdn_fwd_, isc::dhcp::Lease::fqdn_rev_, isc::data::UserContext::getContext(), isc::dhcp::Lease::hostname_, isc::dhcp::Lease::hwaddr_, isc::util::nullOrEqualValues(), isc::dhcp::Lease::pool_id_, isc::dhcp::Lease::reuseable_valid_lft_, isc::dhcp::Lease::state_, isc::dhcp::Lease::subnet_id_, and isc::dhcp::Lease::valid_lft_.

Here is the call graph for this function:

## ◆ statesToText()

std::string isc::dhcp::Lease4::statesToText | ( | const uint32_t | state | ) |
| static

Returns name of the lease states specific to DHCPv4.

Todo
  Currently it simply returns common states for DHCPv4 and DHCPv6. This method will have to be extended to handle DHCPv4 specific states when they are defined.

Parameters

  state | Numeric value holding lease states.

Returns
  Comma separated list of lease state names.

Definition at line 339 of file lease.cc.

References isc::dhcp::Lease::basicStatesToText().

Referenced by isc::run_script::RunScriptImpl::extractLease4(), and toText().

Here is the call graph for this function:

## ◆ toElement()

isc::data::ElementPtr isc::dhcp::Lease4::toElement | ( |  | ) | const
| virtual

Return the JSON representation of a lease.

Reimplemented from isc::dhcp::Lease.

Definition at line 393 of file lease.cc.

References isc::dhcp::Lease::addr_, client_id_, isc::dhcp::Lease::cltt_, isc::data::UserContext::contextToElement(), isc::data::Element::create(), isc::data::Element::createMap(), isc::dhcp::Lease::fqdn_fwd_, isc::dhcp::Lease::fqdn_rev_, isc::dhcp::Lease::hostname_, isc::dhcp::Lease::hwaddr_, isc::dhcp::Lease::pool_id_, isc::dhcp::Lease::state_, isc::dhcp::Lease::subnet_id_, and isc::dhcp::Lease::valid_lft_.

Referenced by isc::ha::CommandCreator::createLease4Delete(), and isc::ha::CommandCreator::createLease4Update().

Here is the call graph for this function:

## ◆ toText()

std::string isc::dhcp::Lease4::toText | ( |  | ) | const
| virtual

Convert lease to printable form.

Returns
  Textual representation of lease data

Implements isc::dhcp::Lease.

Definition at line 579 of file lease.cc.

References isc::dhcp::Lease::addr_, client_id_, isc::dhcp::Lease::cltt_, isc::util::str::dumpAsHex(), isc::data::UserContext::getContext(), isc::dhcp::Lease::hwaddr_, isc::dhcp::Lease::lifetimeToText(), isc::dhcp::Lease::pool_id_, relay_id_, remote_id_, isc::dhcp::Lease::state_, statesToText(), isc::dhcp::Lease::subnet_id_, and isc::dhcp::Lease::valid_lft_.

Here is the call graph for this function:

## Member Data Documentation

## ◆ client_id_

ClientIdPtr isc::dhcp::Lease4::client_id_

Client identifier.

Todo
  Should this be a pointer to a client ID or the ID itself? Compare with the DUID in the Lease6 structure.

Definition at line 329 of file lease.h.

Referenced by Lease4(), Lease4(), isc::dhcp::CSVLeaseFile4::append(), belongsToClient(), decline(), getClientIdVector(), operator==(), toElement(), and toText().

## ◆ relay_id_

std::vector<uint8_t> isc::dhcp::Lease4::relay_id_

Relay identifier for Bulk Lease Query.

Definition at line 516 of file lease.h.

Referenced by Lease4(), and toText().

## ◆ remote_id_

std::vector<uint8_t> isc::dhcp::Lease4::remote_id_

Remote identifier for Bulk Lease Query.

Todo
  : Add DHCPv4 failover related fields here

Definition at line 513 of file lease.h.

Referenced by Lease4(), and toText().

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

- lease.h
- lease.cc