From: Thomas Markwalder Date: Mon, 14 Apr 2014 20:06:40 +0000 (-0400) Subject: [3158] Added doxygen developer's guide page for D2 X-Git-Tag: trac2406k_base~1^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e010525d24113f46fe2107b8b29c7babcd11b699;p=thirdparty%2Fkea.git [3158] Added doxygen developer's guide page for D2 Added src/bin/d2/images to image path in doc/Doxyfile Added d2 subpage to doc/devel/mainpage.dox Added the following: --- diff --git a/doc/Doxyfile b/doc/Doxyfile index c2aec859a5..975fe9cc39 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -779,7 +779,7 @@ EXAMPLE_RECURSIVE = NO # directories that contain image that are included in the documentation (see # the \image command). -IMAGE_PATH = ../doc/images ../src/lib/hooks/images +IMAGE_PATH = ../doc/images ../src/lib/hooks/images ../src/bin/d2/images # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index f31e7bfef5..a033083b4d 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -70,6 +70,7 @@ * - @subpage dhcpv6OptionsParse * - @subpage dhcpv6Classifier * - @subpage dhcpv6Other + * - @subpage d2 * - @subpage libdhcp * - @subpage libdhcpIntro * - @subpage libdhcpRelay diff --git a/src/bin/d2/d2.dox b/src/bin/d2/d2.dox new file mode 100644 index 0000000000..7e4b579427 --- /dev/null +++ b/src/bin/d2/d2.dox @@ -0,0 +1,358 @@ +// Copyright (C) 2014 Internet Systems Consortium, Inc. ("ISC") +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +// AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +// PERFORMANCE OF THIS SOFTWARE. + +/** + @page d2 DHCP-DDNS Component + +Kea is capable of providing DDNS driven by changes to leases based on DHCP +requests processed by Kea's DHCP servers. When DDNS updating is enabled, +the DHCP servers generate requests to update DNS as they make lease changes. +These requests, implemented by isc::dhcp_ddns::NameChangeRequest (NCR), are sent +to a separate process, informally known as D2. D2 processes these requests by +carrying out DDNS conversations with the appropriate DNS servers such that they +update the DNS data. + +The design documentation for D2 can be found here: +D2 Design). + +This document contains several UML diagrams, and a few conventions used within +these diagrams are worth noting: + +- If a class is appearing on class diagram for the first time (within this +document) its background color will be yellow. If it has been presented +already, its background color will be blue and/or its details may not be shown. + +- Associations between classes in D2 are implemented in most cases via typedefs, +sometimes through a small chain of typedefs. These typedefs are shown for +accuracy but are unimportant to a general discussion. + + +@section d2CPL Controllable Process Layer (CPL): + +D2 is built upon an abstract set of classes referred to as the Controllable +Process Layer or CPL. This layer provides the essentials for a controllable, +configurable, asynchronous process. They are the result of an effort to +distill the common facets of process control currently duplicated in in Kea's +DHCP servers into a reusable construct. The classes which form this abstract +base are shown in the following class diagram: + +@image html abstract_app_classes.svg "Controllable Process Layer Classes" + +- isc::d2::DControllerBase - provides all of the services necessary to manage +an application process class derived from DProcess. These services include: + - Command line argument handling + - Process instantiation and initialization + - Support for stand-alone execution + - Support for integrated operation as a BIND10 module (session management + and event handling) + - Process event loop invocation and shutdown + +It creates and manages an instance of DProcessBase. The CPL is designed +for asynchronous event processing applications. It is constructed to use ASIO +library for IO processing. DControllerBase own an isc::asiolink::io_service instance and it passes this into the DProcessBase constructor and it is this +service that is used drivel the process's event loop. + +DControllerBase also provides the ability to operate one of two modes: +"stand-alone" mode or "managed" mode. In stand-alone mode, the controller has + no IO of it's own, thus there is two-way control communication between the application and the outside world. + +@todo DControllerBase does yet support reading the configuration from a +command line argument. It's command line argument processing can be very easily +extended to do so. + +In "managed mode" the controller creates a BIND10 Session, allowing it to +participate as a BIND10 module and therefore receive control commands such as +configuration updates, status requests, and shutdown. BIND10 modules are +required to supply two callbacks: one for configuration events and one for +command events. DControllerBase supplies these callbacks which largely +pass the information through to its DProcessBase instance. The key aspect +to take from this is that the controller handles the interface for receiving +asynchronous commands and the invokes the appropriate services in the process's +interface. + +@todo At the time of this writing Kea is being separated from the BIND10 +framework. As such, use of the BIND10 Session will be removed but could +readily be replaced with an authenticated socket connection for receiving and +responding to directives asynchronously. + +- isc::d2::DProcessBase - defines an asynchronous-event processor (i.e. +application) which provides a uniform interface to: + - Instantiate and initialize a process instance + - "Run" the application by starting its event loop + - Inject events to control the process +It owns an instance of DCfgMgrBase. + +- isc::d2::DCfgMgrBase - provides the mechanisms for managing an application's +configuration. This includes services for parsing sets of configuration +values, storing the parsed information in its converted form, and retrieving +the information on demand. It owns an instance of DCfgContextBase, which +provides a "global" context for information that is accessible before, during, +and after parsing. + +- isc::d2::DCfgContextBase - implements a container for configuration +information or "context". It provides a single enclosure for the storage of +configuration parameters or any other information that needs to accessible +within a given context. + +The following sequence diagram shows how a configuration update, received +asynchronously through the session command channel, moves through the CPL: + +@image html config_sequence.svg "CPL Configuration Update Sequence" + +The CPL classes will likely move into a common library. + +@section d2ProcesDerivation D2 Application Core Classes + +D2's core application classes are DDNS-specific derivations of the CPL as show +in the diagram below: + +@image html d2_app_classes.svg "D2's CPL Derivations" + +- isc::d2::D2Controller - entry point for running D2, it processes command line +options, starts and controls the application process, D2Process. + +- isc::d2::D2Process - creates and manages D2's primary resources and implements +the main event loop described in @ref d2EventLoop. + +- isc::d2::D2CfgMgr - creates, updates, and provides access to D2's application +configuration which is embodied by D2Context. + +- isc::d2::D2CfgContext - warehouses D2's application configuration. + +@section d2ConfigMgt Configuration Management + +D2's configuration management uses the same underlying mechanisms as Kea's DHCP +servers. It's configuration information is organized into a hierarchical data +model which is mirrored in the implementation by a hierarchy of parser classes +and the runtime classes they instantiate. + +D2's data model is is organized as follows: + +- A set of application level values such as the D2's IP address, port + +- Two lists of "domains": one for Forward DNS and one for Reverse DNS. @n + Each domain is described by a zone name and a list of DNS servers that can + update that zone. + +- A list of TSIG keys for conducting signed DDNS exchanges with DNS servers + +The runtime classes that embody this model are shown in the following diagram: + +@image html config_data_classes.svg "D2's Configuration Data Classes" + +- isc::d2::D2CfgContext - D2-specific derivation of DCfgContextBase. It +houses the "global" configuration for an instance of D2. +- isc::d2::DdnsDomainListMgr - manages a list of domains. Currently there is +one manager instance for the list of forward domains, and one for the list of +reverse domains. In addition the domain list, it will may house other values + specific to that list of domains (e.g. enable flag) +- isc::d2::DdnsDomain - represents a DNS domain (really a zone). When requests +are received they are matched to a domain by comparing their FQDN to the domain's name. +- isc::d2::DnsServerInfo - describes a DNS server which supports DDNS for a +given domain. +- isc::d2::TSIGKeyInfo - describes a TSIG key used for authenticated DDNS for +a given domain. + +The parsing classes, as one would expect, parallel the runtime classes quite +closely. The parsers are named for the runtime class they instantiate and are +either designed to parse a single occurrence of that class or list of that +class. The parser classes are shown in the diagram below: + +@image html config_parser_classes.svg "D2's Configuration Parsers" + +- isc::d2::DdnsDomainListMgrParser - parser for a domain list manager, it +creates a domain list parser +- isc::d2::DdnsDomainListParser - parser for a list of domains, it creates a +domain parser for domain described in a list domains +- isc::d2::DdnsDomainParser - Parser for a domain, it creates a DNS server list +parser +- isc::d2::DnsServerInfoListParser - parser for a list of DNS servers, it +creates a DNS server parser for server described in a list of servers +- isc::d2::DnsServerInfoParser - parser for DNS server +- isc::d2::TSIGKeyInfoListParser - parser for a list of TSIG keys, it creates a +parser for key described in a list of keys +- isc::d2::TSIGKeyInfoParser + +The underlying common libraries for configuration parsing support configuration +input in JSON format, that complies with a fixed set of generic constructs that +may be described by a spec file (also JSON). This mechanism is subject to +change, but in the meantime, the spec file describe D2's configuration may be +found here: src/bin/d2/dhcp-ddns.spec + +@section d2NCRReceipt Request Reception and Queueing + +D2 is designed to receive requests from Kea's DHCP servers, asynchronously and +store them in queue to be processed. The classes responsible for this are +shown in the diagram below: + +@image html request_mgt_classes.svg "Request Management Classes" + +- isc::d2::D2QueueMgr - owned by D2Process, it listens for NameChangeRequests +and queues them for processing. It also provides services for adding, +finding, and removing queue entries. It owns the interface used to receive +requests and thus shields the remainder of D2 from any specific knowledge or +interaction with this interface. +- isc::d2::RequestQueue - storage container for the received requests. +- isc::dhcp_ddns::NameChangeListener - Abstract asynchronous interface for +receiving requests which uses ASIO to process IO and invoke a callback upon +request receipt +- isc::dhcp_ddns::NameChangeUDPListener - Derivation of NameChangeListener +which supports receiving request via UDP socket +- isc::dhcp_ddns::NameChangeRequest - embodies a request to update DNS entries +based upon a DHCP lease change + +D2QueueMgr is state-driven, albeit with a very simple state model. The states +are defined by isc::d2::D2QueueMgr::State, and described in detail in in +@ref d2_queue_mgr.h. + +@section d2DDNSUpdateExecution Update Execution + +The DDNS protocol can lead to a multiple step conversation between the updater +and the DNS server to update entries for a single client. In addition, +NameChangeRequests can request changes be made for both forward and reverse +DNS. In order to carry out the appropriate conversation, D2 wraps each request +in a stateful, transaction. + +Working such transactions serially can be inefficient, especially if those +requests involve different DNS servers. Therefore, D2 has been designed to +work on more than one transaction at a time by creating and managing a list of +transactions. + +The classes which are responsible for carrying out this work are shown in the +following diagram: + +@image html update_exec_classes.svg "Update Execution Classes" + +- isc::d2::D2UpdateMgr owned by D2Process, orchestrates the fulfillment of +each request by managing the execution of its transaction. Its high level +method @ref isc::d2::D2UpdateMgr::sweep() is meant to be called whenever IO +events occur. The following steps are performed each time the method is called: + - Any transaction which has been completed, is logged and culled from the + transaction list. + - Start a new transaction for the next queued request (if any) + +- isc::d2::NameChangeTransaction - abstract state-driven class which carries +out the steps necessary to fulfill a single request. Fulfilling a request is +achieved as IO events in response it DDNS requests drive the transaction +through its state model. The type of transaction is based on the nature of +the request, this is discussed further on @ref d2TransDetail + +- isc::d2::DNSClient - an asynchronous worker which atomically performs a +single DDNS packet exchange with a given server, providing the response via a +callback mechanism. Each time a transaction's state model calls for a packet +exchange with a DNS server, it uses an instance of this class to do it. + +- isc::d2::D2UpdateMessage - container for sending and receiving DDNS packets + +@section d2EventLoop D2's Event Loop + +Now that all of the primary components have been introduced it is worth while +discussing D2's main event loop. As mentioned earlier D2 is constructed around +the CPL which designed to be driven by asynchronous IO processed by a +common IO service thread (isc::asiolink::io_service). Any IO that needs to be +performed by the application thread uses this service to do so. This organizes +the IO event processing into a single event loop centered around the service. +(This does not preclude spinning off worker threads to conduct other tasks, +with their own io_service instances). D2's main event loop, implemented in @ref isc::d2::D2Process::run() may be paraphrased as follows: + +@code + As long as we should not shutdown repeat the following steps: + 1. Check on the state of the request queue. Take any actions necessary + regarding it. For example, it may be in the process of shutting down + its listener prior to applying a configuration change. + + 2. Give update manager a "time slice" to cull finished transactions and + start new ones. + + 3. Block until one or more of the following IO events occur: + a. NCR message has been received + b. Transaction IO has completed + c. Interval timer expired + d. A process command has been received + e. Something has stopped the IO service (most likely a fatal error) +@endcode + +@section d2TransDetail D2 Transactions + +There are two types of NameChangeRequests: an "Add" that is issued when DNS +entries need to be added for new or updated lease, and a "Remove" that is +issued when DNS entries need to be removed for obsolete or expired lease. The +DDNS protocol dictates the steps that should be followed in both cases. + +D2's design addresses this by calling for two types of transactions: one for +adding entries and one for removing them, each with their own state model. +The transaction classes are shown in the following diagram: + +@image html trans_classes.svg "NameChangeTransaction Derviations" + +- isc::d2::NameAddTransaction - carries out a NameChangeRequest to add entries +- isc::d2::NameRemoveTransaction - carries out a NameChangeRequest to remove entries +- isc::d2::StateModel - abstract state model described in @ref d2StateModel + +The state models for these two transactions implement DDNS with conflict +resolution as described in RFC 4703. + +The state model for isc::d2::NameAddTransaction is diagrammed below: + +@image html add_state_model.svg "State Model for NameAddTransaction" + +The state model for isc::d2::NameRemoveTransaction is depicted next: + +@image html remove_state_model.svg "State Model for NameRemoveTransaction" + +@subsection d2StateModel State Model Implementation + +D2 implements a abstract state-machine through a light weight set of classes. +At construction, the model's dictionary of events and states is initialized. +This allows, the deriving class the ability to bind a method of its choosing +to each state as thats state's handler. Each handler contains the knowledge +of how to respond to the "posted" event and including posting other events and +transitioning to other states. + +Executing the model consists of beginning at the current state with the posted +event and continuing until the model needs to wait for an IO-based event or +it has reached the end of the state model. These classes will likely move to +a common library. + +@image html state_model_classes.svg "State Model Classes" + +- isc::d2::StateModel - provides the mechanics for executing a state model +described by a dictionary events and states. It provides methods to: + - initialize the model - constructs the dictionary of events and states + - start the model - sets the model to its initial state, posts a "start" + event and starts the model "running" + "start event" + - run the model - process the posted event (if one) until the model reaches + a wait state or reaches the end state. + - transition from one state to another +- isc::d2::Event - Defines an event used to stimulate the model +- isc::d2::State - Defines a state with the model, each state has a handler +method that is executed upon transition "into" that state from another +- isc::d2::LabeledValue - An abstract that associates a integer value with a +text label +- isc::d2::LabeledValueSet - A collection of LabeledValues for which the integer +values must be unique + +@subsection d2TransExecExample Transaction Execution Example + +The following sequence chart depicts the typically sequence of events that occur +when D2UpdateMgr creates and starts executing a transaction: + +@image html nc_trans_sequence.svg "Transaction Execution Sequence" + + + + + +*/ diff --git a/src/bin/d2/images/abstract_app_classes.svg b/src/bin/d2/images/abstract_app_classes.svg new file mode 100644 index 0000000000..53e1fe90a0 --- /dev/null +++ b/src/bin/d2/images/abstract_app_classes.svg @@ -0,0 +1,225 @@ + + + + + + + + + DCfgContextBase + + OPTIONAL + REQUIRED + boolean_values_ + uint32_values_ + string_values_ + + DCfgContextBase() + ~DCfgContextBase() + getParam() + getParam() + getParam() + getBooleanStorage() + getUint32Storage() + getStringStorage() + clone() + DCfgContextBase() + operator =() + + + + + + DControllerBase + + app_name_ + bin_name_ + stand_alone_ + verbose_ + spec_file_name_ + + DControllerBase() + ~DControllerBase() + launch() + dummyConfigHandler() + configHandler() + commandHandler() + updateConfig() + executeCommand() + customOption() + createProcess() + customControllerCommand() + onSessionConnect() + onSessionDisconnect() + getUsageText() + getCustomOpts() + getAppName() + getBinName() + isStandAlone() + setStandAlone() + isVerbose() + setVerbose() + getIOService() + getSpecFileName() + setSpecFileName() + getController() + setController() + parseArgs() + initProcess() + establishSession() + runProcess() + disconnectSession() + shutdown() + usage() + + + + + + DProcessBase + + app_name_ + shut_down_flag_ + + DProcessBase() + init() + run() + shutdown() + configure() + command() + ~DProcessBase() + shouldShutdown() + setShutdownFlag() + getAppName() + getIoService() + stopIOService() + getCfgMgr() + + + + + + DCfgMgrBase + + + DCfgMgrBase() + ~DCfgMgrBase() + parseConfig() + addToParseOrder() + getParseOrder() + getContext() + createConfigParser() + buildAndCommit() + + + + + + <<typedef>> + DProcessBasePtr + + + + + + + + + + + + + + + + + + + context_ + + + process_ + + + io_service_ + + + cfg_mgr_ + + + io_service_ + + + + + + <<typedef>> + IOServicePtr + + + + + + + + <<typedef>> + DCfgMgrBasePtr + + + + + + + + <<typedef>> + DCfgContextBasePtr + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/bin/d2/images/add_state_model.svg b/src/bin/d2/images/add_state_model.svg new file mode 100644 index 0000000000..b21e7b0fcc --- /dev/null +++ b/src/bin/d2/images/add_state_model.svg @@ -0,0 +1,301 @@ + + + + + + + + READY_ST + + + + + SELECTING_FWD_SERVER_ST + + + + + SELECTING_REV_SERVER_ST + + + + + ADDING_FWD_ADDRS_ST + + + + + REPLACING_FWD_ADDRS_ST + + + + + PROCESS_ADD_FAILED_ST + + + + + PROCESSS_ADD_OK_ST + + + + + + + + + + <<DNS IO Callback>> + + + + <<DNS IO Callback>> + + + + <<DNS IO Callback>> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + UPDATE_FAILED_EVT + + + SERVER_IO_ERROR_EVT + + + FQDN_IN_USE_EVT + + + SERVER_IO_ERROR_EVT + + + FQDN_NOT_IN_USE_EVT + + + UPDATE_OK_EVT + + + No reverse change requested + + + START_EVT + + + END_EVT + + + UPDATE_OK_EVT + + + UPDATE_FAILED_EVT + + + Reverse change requested + + + END_EVT + + + NO_MORE_SERVERS_EVT + + + SERVER_SELECTED_EVT + + + IO_COMPLETED_EVT + + + + + + REPLACING_REV_PTRS_ST + + + + + + + + + + + + + + + + + + + + + Forward change requested + + + Only reverse change requested + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + SERVER_IO_ERROR_EVT + + + SERVER_SELECTED_ST + + + UPDATE_OK_EVT + + + IO_COMPLETED_EVT + + + IO_COMPLETED_EVT + + diff --git a/src/bin/d2/images/config_data_classes.svg b/src/bin/d2/images/config_data_classes.svg new file mode 100644 index 0000000000..7953b88b07 --- /dev/null +++ b/src/bin/d2/images/config_data_classes.svg @@ -0,0 +1,299 @@ + + + + + + + + + D2CfgContext + + + D2CfgContext() + ~D2CfgContext() + clone() + getForwardMgr() + getReverseMgr() + getKeys() + D2CfgContext() + operator =() + + + + + + DnsServerInfo + + STANDARD_DNS_PORT + EMPTY_IP_STR + hostname_ + ip_address_ + port_ + enabled_ + + DnsServerInfo() + ~DnsServerInfo() + getHostname() + getPort() + getIpAddress() + isEnabled() + enable() + disable() + toText() + + + + + + <<typedef>> + TSIGKeyInfoPtr + + + + + + + + <<typedef>> + DdnsDomainMap + + + + + + + + <<typedef>> + DnsServerInfoStoragePtr + + + + + + + + <<typedef>> + DdnsDomainListMgrPtr + + + + + + + + <<typedef>> + DnsServerInfoPtr + + + + + + + + TSIGKeyInfo + + name_ + algorithm_ + secret_ + + TSIGKeyInfo() + ~TSIGKeyInfo() + getName() + getAlgorithm() + getSecret() + + + + + + + + + + + + + + + + + + + + + + + + + + + + DdnsDomainListMgr + + wildcard_domain_name_ + name_ + + DdnsDomainListMgr() + ~DdnsDomainListMgr() + matchDomain() + getName() + size() + getWildcardDomain() + getDomains() + setDomains() + + + + + + <<typedef>> + DnsServerInfoStorage + + + + + + + + + + + + + + + + + + + + + + + + + + <<typedef>> + DdnsDomainPtr + + + + + + + + + + + + + + + + + + + + + + + + + DdnsDomain + + name_ + key_name_ + + DdnsDomain() + ~DdnsDomain() + getName() + getKeyName() + getServers() + + + + + + + + + + + + + + reverse_mgr_ + + + forward_mgr_ + + + keys_ + + + wildcard_domain_ + + + servers_ + + + domains_ + + + + + + <<typedef>> + TSIGKeyInfoMapPtr + + + + + + + + <<typedef>> + DdnsDomainMapPtr + + + + + + + + + + + + + + + + + + + + + + + + + <<typedef>> + TSIGKeyInfoMap + + + + + + + + + + + + + + + + + diff --git a/src/bin/d2/images/config_parser_classes.svg b/src/bin/d2/images/config_parser_classes.svg new file mode 100644 index 0000000000..974bf0f8d5 --- /dev/null +++ b/src/bin/d2/images/config_parser_classes.svg @@ -0,0 +1,262 @@ + + + + + + + + + DdnsDomainListMgr + + wildcard_domain_name_ + name_ + + DdnsDomainListMgr() + ~DdnsDomainListMgr() + matchDomain() + getName() + size() + getWildcardDomain() + getDomains() + setDomains() + + + + + + DnsServerInfo + + STANDARD_DNS_PORT + EMPTY_IP_STR + hostname_ + ip_address_ + port_ + enabled_ + + DnsServerInfo() + ~DnsServerInfo() + getHostname() + getPort() + getIpAddress() + isEnabled() + enable() + disable() + toText() + + + + + + DdnsDomain + + name_ + key_name_ + + DdnsDomain() + ~DdnsDomain() + getName() + getKeyName() + getServers() + + + + + + DnsServerInfoListParser + + list_name_ + parsers_ + + DnsServerInfoListParser() + ~DnsServerInfoListParser() + build() + commit() + + + + + + DnsServerInfoParser + + entry_name_ + + DnsServerInfoParser() + ~DnsServerInfoParser() + build() + createConfigParser() + commit() + + + + + + DdnsDomainListMgrParser + + entry_name_ + + DdnsDomainListMgrParser() + ~DdnsDomainListMgrParser() + build() + createConfigParser() + commit() + + + + + + TSIGKeyInfoParser + + entry_name_ + + TSIGKeyInfoParser() + ~TSIGKeyInfoParser() + build() + createConfigParser() + commit() + + + + + + + + + + + + + + + + + + + + + + + + TSIGKeyInfoListParser + + list_name_ + parsers_ + + TSIGKeyInfoListParser() + ~TSIGKeyInfoListParser() + build() + commit() + + + + + + DdnsDomainParser + + entry_name_ + + DdnsDomainParser() + ~DdnsDomainParser() + build() + createConfigParser() + commit() + + + + + + DdnsDomainListParser + + list_name_ + parsers_ + + DdnsDomainListParser() + ~DdnsDomainListParser() + build() + commit() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TSIGKeyInfo + + name_ + algorithm_ + secret_ + + TSIGKeyInfo() + ~TSIGKeyInfo() + getName() + getAlgorithm() + getSecret() + + + + + + + + + D2CfgMgr + + IPV4_REV_ZONE_SUFFIX + IPV6_REV_ZONE_SUFFIX + + D2CfgMgr() + ~D2CfgMgr() + getD2CfgContext() + matchForward() + matchReverse() + reverseIpAddress() + reverseV4Address() + reverseV6Address() + createConfigParser() + + + + + + + + + + + + diff --git a/src/bin/d2/images/config_sequence.svg b/src/bin/d2/images/config_sequence.svg new file mode 100644 index 0000000000..ff17ea932e --- /dev/null +++ b/src/bin/d2/images/config_sequence.svg @@ -0,0 +1,94 @@ + + + + + + + + + :DCfgMgrBase + + + + + + :ModuleCCSession + + + + + + + + + :DProcessBase + + + + + + + + + + + + + + + :DControllerBase + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + parseConfig(in new_config : isc::data::ElementPtr) : isc::data::ConstElementPtr + + + updateConfig(in new_config : isc::data::ConstElementPtr) : isc::data::ConstElementPtr + + + getFullConfig() : ConstElementPtr + + + configure(in config_set : isc::data::ConstElementPtr) : isc::data::ConstElementPtr + + + configHandler(in new_config : isc::data::ConstElementPtr) : isc::data::ConstElementPtr + + diff --git a/src/bin/d2/images/d2_app_classes.svg b/src/bin/d2/images/d2_app_classes.svg new file mode 100644 index 0000000000..b631aa6ada --- /dev/null +++ b/src/bin/d2/images/d2_app_classes.svg @@ -0,0 +1,342 @@ + + + + + + + + + D2CfgContext + + + D2CfgContext() + ~D2CfgContext() + clone() + getForwardMgr() + getReverseMgr() + getKeys() + D2CfgContext() + operator =() + + + + + + DControllerBase + + app_name_ + bin_name_ + stand_alone_ + verbose_ + spec_file_name_ + + DControllerBase() + ~DControllerBase() + launch() + dummyConfigHandler() + configHandler() + commandHandler() + updateConfig() + executeCommand() + customOption() + createProcess() + customControllerCommand() + onSessionConnect() + onSessionDisconnect() + getUsageText() + getCustomOpts() + getAppName() + getBinName() + isStandAlone() + setStandAlone() + isVerbose() + setVerbose() + getIOService() + getSpecFileName() + setSpecFileName() + getController() + setController() + parseArgs() + initProcess() + establishSession() + runProcess() + disconnectSession() + shutdown() + usage() + + + + + + DProcessBase + + app_name_ + shut_down_flag_ + + DProcessBase() + init() + run() + shutdown() + configure() + command() + ~DProcessBase() + shouldShutdown() + setShutdownFlag() + getAppName() + getIoService() + stopIOService() + getCfgMgr() + + + + + + DCfgContextBase + + OPTIONAL + REQUIRED + boolean_values_ + uint32_values_ + string_values_ + + DCfgContextBase() + ~DCfgContextBase() + getParam() + getParam() + getParam() + getBooleanStorage() + getUint32Storage() + getStringStorage() + clone() + DCfgContextBase() + operator =() + + + + + + D2CfgMgr + + IPV4_REV_ZONE_SUFFIX + IPV6_REV_ZONE_SUFFIX + + D2CfgMgr() + ~D2CfgMgr() + getD2CfgContext() + matchForward() + matchReverse() + reverseIpAddress() + reverseV4Address() + reverseV6Address() + createConfigParser() + + + + + + + + + + + + + + + + + D2Process + + QUEUE_RESTART_PERCENT + reconf_queue_flag_ + + D2Process() + init() + run() + shutdown() + configure() + command() + ~D2Process() + checkQueueStatus() + reconfigureQueueMgr() + runIO() + canShutdown() + setReconfQueueFlag() + setShutdownType() + getD2CfgMgr() + getD2QueueMgr() + getD2UpdateMgr() + getReconfQueueFlag() + getShutdownType() + getShutdownTypeStr() + + + + + + DCfgMgrBase + + + DCfgMgrBase() + ~DCfgMgrBase() + parseConfig() + addToParseOrder() + getParseOrder() + getContext() + createConfigParser() + buildAndCommit() + + + + + + + + + + + + + + + + + + <<typedef>> + DProcessBasePtr + + + + + + + + + + + + + + + + + + + + + + + + + + + D2Controller + + d2_app_name_ + d2_bin_name_ + + instance() + ~D2Controller() + createProcess() + D2Controller() + + + + + + + + + + + + + + io_service_ + + + cfg_mgr_ + + + process_ + + + context_ + + + io_service_ + + + + + + <<typedef>> + IOServicePtr + + + + + + + + <<typedef>> + DCfgMgrBasePtr + + + + + + + + <<typedef>> + DCfgContextBasePtr + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/bin/d2/images/nc_trans_sequence.svg b/src/bin/d2/images/nc_trans_sequence.svg new file mode 100644 index 0000000000..ae0daebbca --- /dev/null +++ b/src/bin/d2/images/nc_trans_sequence.svg @@ -0,0 +1,230 @@ + + + + + + + + + :DNSClient + + + + + + + + + + + + :D2UpdateMgr + + Sequence depicting a + simple state model which + performs a single update. + + + + As part of Update + Manager's sweep() + between events it + creates and starts the + transaction + + + + + runStateModel() Iterates through + states until DONE_ST is + reached + + + + + + + + + + + + :NameChangeTransaction + + + + + At some point later, DNSClient + invokes callback when IO + completes + + + + + + + + + + + + + + + + + + + + runStateModel() Iterates through + states until an update is initiated + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + doUpdate() + + + setState(READY_ST) + + + runStateModel(START_TRANSACTION_EVT) + + + startTransaction() + + + (getStateHandler())() + + + operator ()() + + + initStateHandlerMap() + + + setDnsUpdateStatus() + + + runStateModel(IO_COMPLETED_EVT) + + + NameChangeTransaction() + + + (getStateHandler)() + + + setNextEvent(NOP_EVT) + + + setState(DONE_ST) + + + setNextEvent(NOP_EVT) + + diff --git a/src/bin/d2/images/remove_state_model.svg b/src/bin/d2/images/remove_state_model.svg new file mode 100644 index 0000000000..317ad17828 --- /dev/null +++ b/src/bin/d2/images/remove_state_model.svg @@ -0,0 +1,304 @@ + + + + + + + + READY_ST + + + + + SELECTING_FWD_SERVER_ST + + + + + SELECTING_REV_SERVER_ST + + + + + REMOVING_FWD_ADDRS_ST + + + + + REMOVING_FWD_RRS_ST + + + + + PROCESS_REMOVE_FAILED_ST + + + + + PROCESS_REMOVE_OK_ST + + + + + REMOVING_REV_PTRS_ST + + + + + + + + + + + <<DNS IO Callback>> + + + + <<DNS IO Callback>> + + + + <<DNS IO Callback>> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NO_MORE_SERVERS_EVT + + + END_EVT + + + UPDATE_OK_EVT + + + UPDATE_FAILED_EVT + + + SERVER_SELECTED_EVT + + + UPDATE_OK_EVT + + + IO_COMPLETED_EVT + + + SERVER_SELEGTED_EVT + + + No reverse change requested + + + END_EVT + + + Reverse change requested + + + UPDATE_FAILED_EVT + + + SERVER_IO_ERROR_EVT + + + NO_MORE_SERVERS_EVT + + + UPDATE_OK_EVT + + + UPDATE_FAILED_EVT + + + SERVER_IO_ERROR_EVT + + + Only reverse change requested + + + START_EVT + + + Forward change requested + + + SERVER_IO_ERROR_EVT + + + IO_COMPLETED_EVT + + + IO_COMPLETED_EVT + + + + + + + + + + + + diff --git a/src/bin/d2/images/request_mgt_classes.svg b/src/bin/d2/images/request_mgt_classes.svg new file mode 100644 index 0000000000..600c1879b5 --- /dev/null +++ b/src/bin/d2/images/request_mgt_classes.svg @@ -0,0 +1,316 @@ + + + + + + + + + D2Process + + QUEUE_RESTART_PERCENT + reconf_queue_flag_ + + D2Process() + init() + run() + shutdown() + configure() + command() + ~D2Process() + checkQueueStatus() + reconfigureQueueMgr() + runIO() + canShutdown() + setReconfQueueFlag() + setShutdownType() + getD2CfgMgr() + getD2QueueMgr() + getD2UpdateMgr() + getReconfQueueFlag() + getShutdownType() + getShutdownTypeStr() + + + + + + <<typedef>> + IOServicePtr + + + + + + + + NameChangeListener + + listening_ + io_pending_ + + NameChangeListener() + ~NameChangeListener() + startListening() + stopListening() + receiveNext() + invokeRecvHandler() + open() + close() + doReceive() + amListening() + isIoPending() + setListening() + + + + + + + + + + + NameChangeRequest + + forward_change_ + reverse_change_ + fqdn_ + lease_expires_on_ + lease_length_ + + NameChangeRequest() + NameChangeRequest() + fromFormat() + toFormat() + fromJSON() + toJSON() + validateContent() + getChangeType() + setChangeType() + setChangeType() + isForwardChange() + setForwardChange() + setForwardChange() + isReverseChange() + setReverseChange() + setReverseChange() + getFqdn() + setFqdn() + setFqdn() + getIpAddress() + getIpIoAddress() + isV4() + isV6() + setIpAddress() + setIpAddress() + getDhcid() + setDhcid() + setDhcid() + getLeaseExpiresOn() + getLeaseExpiresOnStr() + setLeaseExpiresOn() + setLeaseExpiresOn() + getLeaseLength() + setLeaseLength() + setLeaseLength() + getStatus() + setStatus() + getElement() + toText() + operator ==() + operator !=() + + + + + + D2QueueMgr + + MAX_QUEUE_DEFAULT + max_queue_size_ + + D2QueueMgr() + ~D2QueueMgr() + initUDPListener() + startListening() + operator ()() + stopListening() + removeListener() + getQueueSize() + getMaxQueueSize() + setMaxQueueSize() + getMgrState() + peek() + peekAt() + dequeueAt() + dequeue() + enqueue() + clearQueue() + updateStopState() + + + + + + <<typedef>> + NameChangeListenerPtr + + + + + + + + NameChangeUDPListener + + RECV_BUF_MAX + port_ + asio_socket_ + reuse_address_ + + NameChangeUDPListener() + ~NameChangeUDPListener() + open() + close() + doReceive() + receiveCompletionHandler() + NameChangeUDPListener() + operator =() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <<typedef>> + RequestQueue + + + + + + + + <<enum>> + State + + NOT_INITTED + INITTED + RUNNING + STOPPING + STOPPED_QUEUE_FULL + STOPPED_RECV_ERROR + STOPPED + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <<typedef>> + NameChangeRequestPtr + + + + + + + + + + + + + + + queue_mgr_ + + + io_service_ + + + target_stop_state_ + + + listener_ + + + mgr_state_ + + + ncr_queue_ + + + + + + <<typedef>> + D2QueueMgrPtr + + + + + + + + + + + + + + + diff --git a/src/bin/d2/images/state_model_classes.svg b/src/bin/d2/images/state_model_classes.svg new file mode 100644 index 0000000000..d212694cb4 --- /dev/null +++ b/src/bin/d2/images/state_model_classes.svg @@ -0,0 +1,246 @@ + + + + + + + + + State + + + State() + ~State() + run() + + + + + + <<typedef>> + StatePtr + + + + + + + + + + states_ + + + map_ + + + handler_ + + + events_ + + + + + + <<typedef>> + StateHandler + + + + + + + + + + + + + + <<typedef>> + Event + + + + + + + + <<typedef>> + EventPtr + + + + + + + + StateModel + + NEW_ST + END_ST + SM_DERIVED_STATE_MIN + NOP_EVT + START_EVT + END_EVT + FAIL_EVT + SM_DERIVED_EVENT_MIN + dictionaries_initted_ + curr_state_ + prev_state_ + last_event_ + next_event_ + on_entry_flag_ + on_exit_flag_ + + StateModel() + ~StateModel() + startModel() + runModel() + endModel() + nopStateHandler() + initDictionaries() + defineEvents() + defineEvent() + getEvent() + verifyEvents() + defineStates() + defineState() + getState() + verifyStates() + onModelFailure() + transition() + abortModel() + setState() + postNextEvent() + doOnEntry() + doOnExit() + getCurrState() + getPrevState() + getLastEvent() + getNextEvent() + isModelNew() + isModelRunning() + isModelWaiting() + isModelDone() + didModelFail() + getEventLabel() + getStateLabel() + getContextStr() + getPrevContextStr() + + + + + + LabeledValueSet + + UNDEFINED_LABEL + + LabeledValueSet() + ~LabeledValueSet() + add() + add() + get() + isDefined() + getLabel() + + + + + + + + + + + + <<typedef>> + LabeledValueMap + + + + + + + + StateSet + + + StateSet() + ~StateSet() + add() + getState() + + + + + + + + + + + + + + + + + + + + + + + + <<typedef>> + LabeledValuePtr + + + + + + + + + + + + + + + + + + LabeledValue + + value_ + label_ + + LabeledValue() + ~LabeledValue() + getValue() + getLabel() + operator ==() + operator !=() + operator <() + + + + + + + + + + + + + + + + + + diff --git a/src/bin/d2/images/trans_classes.svg b/src/bin/d2/images/trans_classes.svg new file mode 100644 index 0000000000..5023c02aad --- /dev/null +++ b/src/bin/d2/images/trans_classes.svg @@ -0,0 +1,208 @@ + + + + + + + + + NameAddTransaction + + ADDING_FWD_ADDRS_ST + REPLACING_FWD_ADDRS_ST + REPLACING_REV_PTRS_ST + FQDN_IN_USE_EVT + FQDN_NOT_IN_USE_EVT + + NameAddTransaction() + ~NameAddTransaction() + defineEvents() + verifyEvents() + defineStates() + verifyStates() + readyHandler() + selectingFwdServerHandler() + selectingRevServerHandler() + addingFwdAddrsHandler() + replacingFwdAddrsHandler() + replacingRevPtrsHandler() + processAddOkHandler() + processAddFailedHandler() + buildAddFwdAddressRequest() + buildReplaceFwdAddressRequest() + buildReplaceRevPtrsRequest() + + + + + + NameChangeTransaction + + READY_ST + SELECTING_FWD_SERVER_ST + SELECTING_REV_SERVER_ST + PROCESS_TRANS_OK_ST + PROCESS_TRANS_FAILED_ST + NCT_DERIVED_STATE_MIN + SELECT_SERVER_EVT + SERVER_SELECTED_EVT + SERVER_IO_ERROR_EVT + NO_MORE_SERVERS_EVT + IO_COMPLETED_EVT + UPDATE_OK_EVT + UPDATE_FAILED_EVT + NCT_DERIVED_EVENT_MIN + DNS_UPDATE_DEFAULT_TIMEOUT + MAX_UPDATE_TRIES_PER_SERVER + forward_change_completed_ + reverse_change_completed_ + next_server_pos_ + update_attempts_ + + NameChangeTransaction() + ~NameChangeTransaction() + startTransaction() + operator ()() + sendUpdate() + defineEvents() + verifyEvents() + defineStates() + verifyStates() + onModelFailure() + retryTransition() + setDnsUpdateRequest() + clearDnsUpdateRequest() + setDnsUpdateStatus() + setDnsUpdateResponse() + clearDnsUpdateResponse() + setForwardChangeCompleted() + setReverseChangeCompleted() + setNcrStatus() + initServerSelection() + selectNextServer() + setUpdateAttempts() + getIOService() + prepNewRequest() + addLeaseAddressRdata() + addDhcidRdata() + addPtrRdata() + getNcr() + getTransactionKey() + getNcrStatus() + getForwardDomain() + getReverseDomain() + getCurrentServer() + getDNSClient() + getDnsUpdateRequest() + getDnsUpdateStatus() + getDnsUpdateResponse() + getForwardChangeCompleted() + getReverseChangeCompleted() + getUpdateAttempts() + getAddressRRType() + + + + + + + + + + + + NameRemoveTransaction + + REMOVING_FWD_ADDRS_ST + REMOVING_FWD_RRS_ST + REMOVING_REV_PTRS_ST + + NameRemoveTransaction() + ~NameRemoveTransaction() + defineEvents() + verifyEvents() + defineStates() + verifyStates() + readyHandler() + selectingFwdServerHandler() + selectingRevServerHandler() + removingFwdAddrsHandler() + removingFwdRRsHandler() + removingRevPtrsHandler() + processRemoveOkHandler() + processRemoveFailedHandler() + buildRemoveFwdAddressRequest() + buildRemoveFwdRRsRequest() + buildRemoveRevPtrsRequest() + + + + + + StateModel + + NEW_ST + END_ST + SM_DERIVED_STATE_MIN + NOP_EVT + START_EVT + END_EVT + FAIL_EVT + SM_DERIVED_EVENT_MIN + dictionaries_initted_ + curr_state_ + prev_state_ + last_event_ + next_event_ + on_entry_flag_ + on_exit_flag_ + + StateModel() + ~StateModel() + startModel() + runModel() + endModel() + nopStateHandler() + initDictionaries() + defineEvents() + defineEvent() + getEvent() + verifyEvents() + defineStates() + defineState() + getState() + verifyStates() + onModelFailure() + transition() + abortModel() + setState() + postNextEvent() + doOnEntry() + doOnExit() + getCurrState() + getPrevState() + getLastEvent() + getNextEvent() + isModelNew() + isModelRunning() + isModelWaiting() + isModelDone() + didModelFail() + getEventLabel() + getStateLabel() + getContextStr() + getPrevContextStr() + + + + + + + + + + + + + + diff --git a/src/bin/d2/images/update_exec_classes.svg b/src/bin/d2/images/update_exec_classes.svg new file mode 100644 index 0000000000..d815a095b5 --- /dev/null +++ b/src/bin/d2/images/update_exec_classes.svg @@ -0,0 +1,387 @@ + + + + + + + + + D2Process + + QUEUE_RESTART_PERCENT + reconf_queue_flag_ + + D2Process() + init() + run() + shutdown() + configure() + command() + ~D2Process() + checkQueueStatus() + reconfigureQueueMgr() + runIO() + canShutdown() + setReconfQueueFlag() + setShutdownType() + getD2CfgMgr() + getD2QueueMgr() + getD2UpdateMgr() + getReconfQueueFlag() + getShutdownType() + getShutdownTypeStr() + + + + + + <<typedef>> + IOServicePtr + + + + + + + + NameChangeTransaction + + READY_ST + SELECTING_FWD_SERVER_ST + SELECTING_REV_SERVER_ST + PROCESS_TRANS_OK_ST + PROCESS_TRANS_FAILED_ST + NCT_DERIVED_STATE_MIN + SELECT_SERVER_EVT + SERVER_SELECTED_EVT + SERVER_IO_ERROR_EVT + NO_MORE_SERVERS_EVT + IO_COMPLETED_EVT + UPDATE_OK_EVT + UPDATE_FAILED_EVT + NCT_DERIVED_EVENT_MIN + DNS_UPDATE_DEFAULT_TIMEOUT + MAX_UPDATE_TRIES_PER_SERVER + forward_change_completed_ + reverse_change_completed_ + next_server_pos_ + update_attempts_ + + NameChangeTransaction() + ~NameChangeTransaction() + startTransaction() + operator ()() + getNcr() + getTransactionKey() + getNcrStatus() + getForwardDomain() + getReverseDomain() + getCurrentServer() + getDNSClient() + getDnsUpdateRequest() + getDnsUpdateStatus() + getDnsUpdateResponse() + getForwardChangeCompleted() + getReverseChangeCompleted() + getUpdateAttempts() + getAddressRRType() + + + + + + + + + + + + <<typedef>> + NameChangeTransactionPtr + + + + + + + + + + + + + <<typedef>> + NameChangeRequestPtr + + + + + + + + + + + transaction_list_ + + + dns_update_request_ + + + reverse_domain_ + + + dns_update_response_ + + + forward_domain_ + + + dns_client_ + + + queue_mgr_ + + + update_mgr_ + + + ncr_ + + + io_service_ + + + io_service_ + + + queue_mgr_ + + + + + + <<typedef>> + DdnsDomainPtr + + + + + + + + <<typedef>> + D2QueueMgrPtr + + + + + + + + <<typedef>> + DNSClientPtr + + + + + + + + <<typedef>> + D2UpdateMessagePtr + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + D2UpdateMgr + + MAX_TRANSACTIONS_DEFAULT + max_transactions_ + + D2UpdateMgr() + ~D2UpdateMgr() + sweep() + checkFinishedTransactions() + pickNextJob() + makeTransaction() + getIOService() + getMaxTransactions() + setMaxTransactions() + findTransaction() + transactionListEnd() + transactionListBegin() + hasTransaction() + removeTransaction() + clearTransactionList() + getQueueCount() + getTransactionCount() + + + + + + DNSClient + + + DNSClient() + ~DNSClient() + DNSClient() + operator =() + getMaxTimeout() + doUpdate() + doUpdate() + + + + + + + + + + + + + + + + + + + + + + + D2UpdateMessage + + message_ + + D2UpdateMessage() + D2UpdateMessage() + operator =() + getQRFlag() + getId() + setId() + getRcode() + setRcode() + getRRCount() + beginSection() + endSection() + setZone() + getZone() + addRRset() + toWire() + fromWire() + ddnsToDnsSection() + validateResponse() + + + + + + <<typedef>> + D2UpdateMgrPtr + + + + + + + + + + + <<typedef>> + TransactionList + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +