Kea 2.7.5
isc::dhcp::D2ClientMgr Class Reference

D2ClientMgr isolates Kea from the details of being a D2 client. More...

#include <d2_client_mgr.h>

+ Inheritance diagram for isc::dhcp::D2ClientMgr:

Public Member Functions

 D2ClientMgr ()
 Constructor.
 
 ~D2ClientMgr ()
 Destructor.
 
template<class T >
void adjustDomainName (const T &fqdn, T &fqdn_resp, const DdnsParams &ddns_params)
 Set server FQDN name based on configuration and a given FQDN.
 
template<class T >
void adjustFqdnFlags (const T &fqdn, T &fqdn_resp, const DdnsParams &ddns_params)
 Set server FQDN flags based on configuration and a given FQDN.
 
bool amSending () const
 Returns true if the sender is in send mode, false otherwise.
 
void analyzeFqdn (const bool client_s, const bool client_n, bool &server_s, bool &server_n, const DdnsParams &ddns_params) const
 Determines server flags based on configuration and client flags.
 
void clearQueue ()
 Removes all NCRs queued for transmission.
 
bool ddnsEnabled ()
 Convenience method for checking if DHCP-DDNS is enabled.
 
std::string generateFqdn (const asiolink::IOAddress &address, const DdnsParams &ddns_params, const bool trailing_dot=true) const
 Builds a FQDN based on the configuration and given IP address.
 
const D2ClientConfigPtrgetD2ClientConfig () const
 Fetches the DHCP-DDNS configuration pointer.
 
size_t getQueueMaxSize () const
 Returns the maximum number of NCRs allowed in the queue.
 
size_t getQueueSize () const
 Returns the number of NCRs queued for transmission.
 
template<class T >
void getUpdateDirections (const T &fqdn_resp, bool &forward, bool &reverse)
 Get directional update flags based on server FQDN flags.
 
void invokeClientErrorHandler (const dhcp_ddns::NameChangeSender::Result result, dhcp_ddns::NameChangeRequestPtr &ncr)
 Calls the client's error handler.
 
const dhcp_ddns::NameChangeRequestPtrpeekAt (const size_t index) const
 Returns the nth NCR queued for transmission.
 
std::string qualifyName (const std::string &partial_name, const DdnsParams &ddns_params, const bool trailing_dot) const
 Adds a qualifying suffix to a given domain name.
 
void runReadyIO ()
 Processes sender IO events.
 
void sendRequest (dhcp_ddns::NameChangeRequestPtr &ncr)
 Send the given NameChangeRequests to kea-dhcp-ddns.
 
void setD2ClientConfig (D2ClientConfigPtr &new_config)
 Updates the DHCP-DDNS client configuration to the given value.
 
void startSender (D2ClientErrorHandler error_handler)
 Enables sending NameChangeRequests to kea-dhcp-ddns.
 
void startSender (D2ClientErrorHandler error_handler, const isc::asiolink::IOServicePtr &io_service)
 Enables sending NameChangeRequests to kea-dhcp-ddns.
 
void stop ()
 Stop the sender.
 
void stopSender ()
 Disables sending NameChangeRequests to kea-dhcp-ddns.
 
void suspendUpdates ()
 Suspends sending requests.
 
- Public Member Functions inherited from isc::dhcp_ddns::NameChangeSender::RequestSendHandler
virtual ~RequestSendHandler ()
 

Protected Member Functions

int getRegisteredSelectFd ()
 Fetches the select-fd that is currently registered.
 
int getSelectFd ()
 Fetches the sender's select-fd.
 
virtual void operator() (const dhcp_ddns::NameChangeSender::Result result, dhcp_ddns::NameChangeRequestPtr &ncr)
 Function operator implementing the NCR sender callback.
 

Detailed Description

D2ClientMgr isolates Kea from the details of being a D2 client.

Provides services for managing the current dhcp-ddns configuration and as well as communications with kea-dhcp-ddns. Regarding configuration it provides services to store, update, and access the current dhcp-ddns configuration. As for kea-dhcp-ddns communications, D2ClientMgr creates maintains a NameChangeSender appropriate to the current configuration and provides services to start, stop, and post NCRs to the sender. Additionally there are methods to examine the queue of requests currently waiting for transmission.

The manager also provides the mechanics to integrate the ASIO-based IO used by the NCR IPC with the select-driven IO used by Kea. Senders expose a file descriptor, the "select-fd" that can monitored for read-readiness with the select() function (or variants). D2ClientMgr provides a method, runReadyIO(), that will instructs the sender to process the next ready ready IO handler on the sender's IOservice. Track# 3315 extended Kea's IfaceMgr to support the registration of multiple external sockets with callbacks that are then monitored with IO readiness via select(). D2ClientMgr registers the sender's select-fd and runReadyIO() with IfaceMgr when entering the send mode and unregisters it when exiting send mode.

To place the manager in send mode, the calling layer must supply an error handler and optionally an IOService instance. The error handler is invoked if a send completes with a failed status. This provides the calling layer an opportunity act upon the error.

If the caller supplies an IOService, that service will be used to process the sender's IO. If not supplied, D2ClientMgr pass a private IOService into the sender. Using a private service isolates the sender's IO from any other services.

Definition at line 80 of file d2_client_mgr.h.

Constructor & Destructor Documentation

◆ D2ClientMgr()

isc::dhcp::D2ClientMgr::D2ClientMgr ( )

Constructor.

Default constructor which constructs an instance which has DHCP-DDNS updates disabled.

Definition at line 22 of file d2_client_mgr.cc.

◆ ~D2ClientMgr()

isc::dhcp::D2ClientMgr::~D2ClientMgr ( )

Destructor.

Definition at line 28 of file d2_client_mgr.cc.

References stop(), and stopSender().

+ Here is the call graph for this function:

Member Function Documentation

◆ adjustDomainName()

template<class T >
void isc::dhcp::D2ClientMgr::adjustDomainName ( const T & fqdn,
T & fqdn_resp,
const DdnsParams & ddns_params )

Set server FQDN name based on configuration and a given FQDN.

Template method which adjusts the domain name value and type in a server FQDN from a client (inbound) FQDN and the current configuration. The logic is as follows:

If ddns-replace-client-name is true or the supplied name is empty, the server FQDN is set to ""/PARTIAL.

If ddns-replace-client-name is false and the supplied name is a partial name the server FQDN is set to the supplied name qualified by appending the ddns-qualifying-suffix.

If ddns-replace-client-name is false and the supplied name is a fully qualified name, set the server FQDN to the supplied name.

If hostname-char-set is not empty, the inbound name will be sanitized. This is done by iterating over the domain name labels, sanitizing each individually, and then concatenating them into a new sanitized name. It is done this way to guard against the case where the hostname-char-set does not protect dots from replacement.

Parameters
fqdnFQDN option from which to get client (inbound) name
fqdn_respFQDN option to update with the adjusted name
ddns_paramsDDNS behavioral configuration parameters
Template Parameters
TFQDN Option class containing the FQDN data such as dhcp::Option4ClientFqdn or dhcp::Option6ClientFqdn

Definition at line 484 of file d2_client_mgr.h.

References qualifyName(), isc::dhcp::D2ClientConfig::RCM_ALWAYS, and isc::dhcp::D2ClientConfig::RCM_WHEN_PRESENT.

+ Here is the call graph for this function:

◆ adjustFqdnFlags()

template<class T >
void isc::dhcp::D2ClientMgr::adjustFqdnFlags ( const T & fqdn,
T & fqdn_resp,
const DdnsParams & ddns_params )

Set server FQDN flags based on configuration and a given FQDN.

Template wrapper around the analyzeFqdn() allowing that method to be used for either IPv4 or IPv6 processing. This methods resets all of the flags in the response to zero and then sets the S,N, and O flags. Any other flags are the responsibility of the invoking layer.

Parameters
fqdnFQDN option from which to read client (inbound) flags
fqdn_respFQDN option to update with the server (outbound) flags
ddns_paramsDDNS behavioral configuration parameters
Template Parameters
TFQDN Option class containing the FQDN data such as dhcp::Option4ClientFqdn or dhcp::Option6ClientFqdn

Definition at line 457 of file d2_client_mgr.h.

References analyzeFqdn().

+ Here is the call graph for this function:

◆ amSending()

bool isc::dhcp::D2ClientMgr::amSending ( ) const

Returns true if the sender is in send mode, false otherwise.

A true value indicates that the sender is present and in accepting messages for transmission, false otherwise.

Definition at line 298 of file d2_client_mgr.cc.

Referenced by getSelectFd(), sendRequest(), startSender(), startSender(), and stopSender().

◆ analyzeFqdn()

void isc::dhcp::D2ClientMgr::analyzeFqdn ( const bool client_s,
const bool client_n,
bool & server_s,
bool & server_n,
const DdnsParams & ddns_params ) const

Determines server flags based on configuration and client flags.

This method uses input values for the client's FQDN S and N flags, in conjunction with the configuration parameters updates-enabled, ddns-override-no-updates, and ddns-override-client-updates to determine the values that should be used for the server's FQDN S and N flags. The logic in this method is based upon RFCs 4702 and 4704, and is shown in the following truth table:

When Updates are enabled:
ON = Override No Updates, OC = Override Client Updates
| Client |-------- Server Response Flags ------------|
| Flags | ON=F,OC=F | ON=F,OC=T | ON=T,OC=F | ON=T,OC=T |
| N-S | N-S-O | N-S-O | N-S-O | N-S-O |
----------------------------------------------------------
| 0-0 | 0-0-0 | 0-1-1 | 0-0-0 | 0-1-1 |
| 0-1 | 0-1-0 | 0-1-0 | 0-1-0 | 0-1-0 |
| 1-0 | 1-0-0 | 1-0-0 | 0-1-1 | 0-1-1 |
One can then use the server response flags to know when forward and
reverse updates should be performed:
- Forward updates should be done when the Server S-Flag is true.
- Reverse updates should be done when the Server N-Flag is false.
When Updates are disabled:
| Client | Server |
| N-S | N-S-O |
--------------------
| 0-0 | 1-0-0 |
| 0-1 | 1-0-1 |
| 1-0 | 1-0-0 |
Represents information about a Kea server in the database.
Definition server.h:32
Parameters
client_sS Flag from the client's FQDN
client_nN Flag from the client's FQDN
server_s[out] S Flag for the server's FQDN
server_n[out] N Flag for the server's FQDN
ddns_paramsDDNS behavioral configuration parameters
Exceptions
isc::BadValueif client_s and client_n are both 1 as this is an invalid combination per RFCs.

Definition at line 116 of file d2_client_mgr.cc.

References isc_throw.

Referenced by adjustFqdnFlags().

◆ clearQueue()

void isc::dhcp::D2ClientMgr::clearQueue ( )

Removes all NCRs queued for transmission.

Exceptions
D2ClientErrorif sender instance is null. Underlying layer may throw NCRSenderExceptions exceptions.

Definition at line 383 of file d2_client_mgr.cc.

References isc_throw.

◆ ddnsEnabled()

bool isc::dhcp::D2ClientMgr::ddnsEnabled ( )

Convenience method for checking if DHCP-DDNS is enabled.

Returns
True if the D2 configuration is enabled.

Definition at line 106 of file d2_client_mgr.cc.

Referenced by setD2ClientConfig(), and suspendUpdates().

◆ generateFqdn()

std::string isc::dhcp::D2ClientMgr::generateFqdn ( const asiolink::IOAddress & address,
const DdnsParams & ddns_params,
const bool trailing_dot = true ) const

Builds a FQDN based on the configuration and given IP address.

Using the current values for ddns-generated-prefix, ddns-qualifying-suffix and an IP address, this method constructs a fully qualified domain name. It supports both IPv4 and IPv6 addresses. The format of the name is as follows:

<ddns-generated-prefix>-<ip address>.<ddns-qualifying-suffix>.

<ip-address> is the result of IOAddress.toText() with the delimiters ('.' for IPv4 or ':' for IPv6) replaced with a hyphen, '-'.

Parameters
addressIP address from which to derive the name (IPv4 or IPv6)
ddns_paramsDDNS behavioral configuration parameters
trailing_dotA boolean value which indicates whether trailing dot should be appended (if true) or not (false).
Returns
std::string containing the generated name.

Definition at line 169 of file d2_client_mgr.cc.

References qualifyName().

+ Here is the call graph for this function:

◆ getD2ClientConfig()

const D2ClientConfigPtr & isc::dhcp::D2ClientMgr::getD2ClientConfig ( ) const

Fetches the DHCP-DDNS configuration pointer.

Returns
a reference to the current configuration pointer.

Definition at line 111 of file d2_client_mgr.cc.

◆ getQueueMaxSize()

size_t isc::dhcp::D2ClientMgr::getQueueMaxSize ( ) const

Returns the maximum number of NCRs allowed in the queue.

Definition at line 365 of file d2_client_mgr.cc.

References isc_throw.

◆ getQueueSize()

size_t isc::dhcp::D2ClientMgr::getQueueSize ( ) const

Returns the number of NCRs queued for transmission.

Definition at line 356 of file d2_client_mgr.cc.

References isc_throw.

◆ getRegisteredSelectFd()

int isc::dhcp::D2ClientMgr::getRegisteredSelectFd ( )
protected

Fetches the select-fd that is currently registered.

Returns
The currently registered select-fd or util::WatchSocket::SOCKET_NOT_VALID.
Note
This is only exposed for testing purposes.

◆ getSelectFd()

int isc::dhcp::D2ClientMgr::getSelectFd ( )
protected

Fetches the sender's select-fd.

The select-fd may be used with select() or poll(). If the sender has IO waiting to process, the fd will evaluate as !EWOULDBLOCK.

Note
This is only exposed for testing purposes.
Returns
The sender's select-fd
Exceptions
D2ClientErrorif the sender does not exist or is not in send mode.

Definition at line 408 of file d2_client_mgr.cc.

References amSending(), and isc_throw.

+ Here is the call graph for this function:

◆ getUpdateDirections()

template<class T >
void isc::dhcp::D2ClientMgr::getUpdateDirections ( const T & fqdn_resp,
bool & forward,
bool & reverse )

Get directional update flags based on server FQDN flags.

Template convenience method which determines whether forward and reverse updates should be performed based on a server response version of the FQDN flags. The logic is straight forward and currently not dependent upon configuration specific values:

  • forward will be true if S_FLAG is true
  • reverse will be true if N_FLAG is false
Parameters
fqdn_respFQDN option from which to read server (outbound) flags
[out]forwardbool value will be set to true if forward updates should be done, false if not.
[out]reversebool value will be set to true if reverse updates should be done, false if not.
Template Parameters
TFQDN Option class containing the FQDN data such as dhcp::Option4ClientFqdn or dhcp::Option6ClientFqdn

Definition at line 476 of file d2_client_mgr.h.

◆ invokeClientErrorHandler()

void isc::dhcp::D2ClientMgr::invokeClientErrorHandler ( const dhcp_ddns::NameChangeSender::Result result,
dhcp_ddns::NameChangeRequestPtr & ncr )

Calls the client's error handler.

Calls the error handler method set by startSender() when an error occurs attempting to send a method. If the error handler throws an exception it will be caught and logged.

Parameters
resultcontains that send outcome status.
ncris a pointer to the NameChangeRequest that was attempted.

This method is exception safe.

Definition at line 338 of file d2_client_mgr.cc.

References isc::dhcp::DHCPSRV_DHCP_DDNS_ERROR_EXCEPTION, isc::dhcp::DHCPSRV_DHCP_DDNS_HANDLER_NULL, isc::dhcp::dhcpsrv_logger, and LOG_ERROR.

Referenced by operator()(), and sendRequest().

◆ operator()()

void isc::dhcp::D2ClientMgr::operator() ( const dhcp_ddns::NameChangeSender::Result result,
dhcp_ddns::NameChangeRequestPtr & ncr )
protectedvirtual

Function operator implementing the NCR sender callback.

This method is invoked each time the NameChangeSender completes an asynchronous send.

Parameters
resultcontains that send outcome status.
ncris a pointer to the NameChangeRequest that was delivered (or attempted).
Exceptions
Thismethod MUST NOT throw.

Implements isc::dhcp_ddns::NameChangeSender::RequestSendHandler.

Definition at line 392 of file d2_client_mgr.cc.

References isc::dhcp::DHCPSRV_DBG_TRACE_DETAIL, isc::dhcp::DHCPSRV_DHCP_DDNS_NCR_SENT, isc::dhcp::dhcpsrv_logger, invokeClientErrorHandler(), LOG_DEBUG, and isc::dhcp_ddns::NameChangeSender::SUCCESS.

+ Here is the call graph for this function:

◆ peekAt()

const dhcp_ddns::NameChangeRequestPtr & isc::dhcp::D2ClientMgr::peekAt ( const size_t index) const

Returns the nth NCR queued for transmission.

Note that the entry is not removed from the queue.

Parameters
indexthe index of the entry in the queue to fetch. Valid values are 0 (front of the queue) to (queue size - 1).
Note
This method is for test purposes only.
Returns
Pointer reference to the queue entry.
Exceptions
D2ClientErrorif sender instance is null. Underlying layer may throw NCRSenderExceptions exceptions.

Definition at line 374 of file d2_client_mgr.cc.

References isc_throw.

◆ qualifyName()

std::string isc::dhcp::D2ClientMgr::qualifyName ( const std::string & partial_name,
const DdnsParams & ddns_params,
const bool trailing_dot ) const

Adds a qualifying suffix to a given domain name.

Constructs a FQDN based on the configured ddns-qualifying-suffix and a partial domain name as follows:

<partial_name>.<ddns-qualifying-suffix>.

Note that the qualifying suffix will only be appended if the input name does not already end with that suffix.

Parameters
partial_namedomain name to qualify
ddns_paramsDDNS behavioral configuration parameters
trailing_dotA boolean value which when true guarantees the result will end with a "." and when false that the result will not end with a "." Note that this rule is applied even if the qualifying suffix itself is empty (i.e. "").
Returns
std::string containing the qualified name.

Definition at line 182 of file d2_client_mgr.cc.

Referenced by adjustDomainName(), and generateFqdn().

◆ runReadyIO()

void isc::dhcp::D2ClientMgr::runReadyIO ( )

Processes sender IO events.

Serves as callback registered for the sender's select-fd with IfaceMgr. It instructs the sender to execute the next ready IO handler. It provides an instance method that can be bound via std::bind, as NameChangeSender is abstract.

Definition at line 418 of file d2_client_mgr.cc.

References isc_throw.

Referenced by startSender().

◆ sendRequest()

void isc::dhcp::D2ClientMgr::sendRequest ( dhcp_ddns::NameChangeRequestPtr & ncr)

Send the given NameChangeRequests to kea-dhcp-ddns.

Passes NameChangeRequests to the NCR sender for transmission to kea-dhcp-ddns. If the sender rejects the message, the client's error handler will be invoked. The most likely cause for rejection is the senders' queue has reached maximum capacity.

Parameters
ncrNameChangeRequest to send
Exceptions
D2ClientErrorif sender instance is null or not in send mode. Either of these represents a programmatic error.

Definition at line 322 of file d2_client_mgr.cc.

References amSending(), isc::dhcp::DHCPSRV_DHCP_DDNS_NCR_REJECTED, isc::dhcp::dhcpsrv_logger, isc::dhcp_ddns::NameChangeSender::ERROR, invokeClientErrorHandler(), isc_throw, and LOG_ERROR.

+ Here is the call graph for this function:

◆ setD2ClientConfig()

void isc::dhcp::D2ClientMgr::setD2ClientConfig ( D2ClientConfigPtr & new_config)

Updates the DHCP-DDNS client configuration to the given value.

Parameters
new_configpointer to the new client configuration.
Exceptions
D2ClientErrorif passed an empty pointer.
Todo
  • Should we consider anything queued to be wrong? If only server values changed content might still be right but if content values changed (e.g. suffix or an override flag) then the queued contents might now be invalid. There is no way to regenerate them if they are wrong.

Definition at line 47 of file d2_client_mgr.cc.

References ddnsEnabled(), isc::dhcp::DHCPSRV_CFGMGR_CFG_DHCP_DDNS, isc::dhcp::DHCPSRV_DBG_TRACE, isc::dhcp::dhcpsrv_logger, isc_throw, LOG_DEBUG, isc::dhcp_ddns::NCR_UDP, and stopSender().

+ Here is the call graph for this function:

◆ startSender() [1/2]

void isc::dhcp::D2ClientMgr::startSender ( D2ClientErrorHandler error_handler)

Enables sending NameChangeRequests to kea-dhcp-ddns.

Places the NameChangeSender into send mode. This instructs the sender to begin dequeuing and transmitting requests and to accept additional requests via the sendRequest() method. The manager will create a new, private instance of an IOService for the sender to use for IO event processing.

Parameters
error_handlerapplication level error handler to cope with sends that complete with a failed status. A valid function must be supplied as the manager cannot know how an application should deal with send failures.
Exceptions
D2ClientErrorif sender instance is null. Underlying layer may throw NCRSenderExceptions exceptions.

Definition at line 254 of file d2_client_mgr.cc.

References amSending(), isc::dhcp::DHCPSRV_DHCP_DDNS_SENDER_STARTED, isc::dhcp::dhcpsrv_logger, LOG_INFO, and startSender().

+ Here is the call graph for this function:

◆ startSender() [2/2]

void isc::dhcp::D2ClientMgr::startSender ( D2ClientErrorHandler error_handler,
const isc::asiolink::IOServicePtr & io_service )

Enables sending NameChangeRequests to kea-dhcp-ddns.

Places the NameChangeSender into send mode. This instructs the sender to begin dequeuing and transmitting requests and to accept additional requests via the sendRequest() method.

Parameters
error_handlerapplication level error handler to cope with sends that complete with a failed status. A valid function must be supplied as the manager cannot know how an application should deal with send failures.
io_serviceIOService to be used for sender IO event processing
Warning
It is up to the invoking layer to ensure the io_service instance used outlives the D2ClientMgr send mode. When the send mode is exited, either explicitly by calling stopSender() or implicitly through D2ClientMgr destruction, any ASIO objects such as sockets or timers will be closed and released. If the io_service goes out of scope first this behavior could be unpredictable.
Exceptions
D2ClientErrorif sender instance is null. Underlying layer may throw NCRSenderExceptions exceptions.

Definition at line 268 of file d2_client_mgr.cc.

References amSending(), isc::dhcp::IfaceMgr::instance(), isc_throw, and runReadyIO().

Referenced by startSender().

+ Here is the call graph for this function:

◆ stop()

void isc::dhcp::D2ClientMgr::stop ( )

Stop the sender.

Definition at line 403 of file d2_client_mgr.cc.

Referenced by ~D2ClientMgr().

◆ stopSender()

void isc::dhcp::D2ClientMgr::stopSender ( )

Disables sending NameChangeRequests to kea-dhcp-ddns.

Takes the NameChangeSender out of send mode. The sender will stop transmitting requests, though any queued requests remain queued. Attempts to queue additional requests via sendRequest will fail.

Exceptions
D2ClientErrorif sender instance is null. Underlying layer may throw NCRSenderExceptions exceptions.

Unregister sender's select-fd.

Definition at line 303 of file d2_client_mgr.cc.

References amSending(), isc::dhcp::DHCPSRV_DHCP_DDNS_SENDER_STOPPED, isc::dhcp::dhcpsrv_logger, isc::dhcp::IfaceMgr::instance(), LOG_INFO, and isc::util::WatchSocket::SOCKET_NOT_VALID.

Referenced by ~D2ClientMgr(), setD2ClientConfig(), and suspendUpdates().

+ Here is the call graph for this function:

◆ suspendUpdates()

void isc::dhcp::D2ClientMgr::suspendUpdates ( )

Suspends sending requests.

This method is intended to be used when IO errors occur. It toggles the enable-updates configuration flag to off, and takes the sender out of send mode. Messages in the sender's queue will remain in the queue.

Todo
This logic may change in NameChangeSender is altered allow queuing while stopped. Currently when a sender is not in send mode it will not accept additional messages.
Todo
For now we will disable updates and stop sending. This at least provides a means to shut it off if there are errors.

Definition at line 34 of file d2_client_mgr.cc.

References ddnsEnabled(), isc::dhcp::DHCPSRV_DHCP_DDNS_SUSPEND_UPDATES, isc::dhcp::dhcpsrv_logger, LOG_WARN, and stopSender().

+ Here is the call graph for this function:

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