[3484] Updated heavily outdated sections about the DHCPv6 component.

doc/Doxyfile

@@ -659,6 +659,7 @@ INPUT                  = ../src/bin/d2 \
                          ../src/lib/dhcp \
                          ../src/lib/dhcp_ddns \
                          ../src/lib/dhcpsrv \
+                         ../src/lib/dhcpsrv/parsers \
                          ../src/lib/dns \
                          ../src/lib/exceptions \
                          ../src/lib/hooks \

src/bin/dhcp6/dhcp6.dox

@@ -15,62 +15,102 @@
 /**
  @page dhcp6 DHCPv6 Server Component
 
- Kea offers DHCPv6 server implementation. It is implemented as
- kea-dhcp6 component. Its primary code is located in
- isc::dhcp::Dhcpv6Srv class. It uses \ref libdhcp extensively,
- especially lib::dhcp::Pkt6, isc::dhcp::Option and
- isc::dhcp::IfaceMgr classes. Currently this code offers skeleton
- functionality, i.e. it is able to receive and process incoming
- requests and transmit responses. However, it does not have database
- management, so it returns only one, hardcoded lease to whoever asks
- for it.
+Kea includes the "kea-dhcp6" component, which is the DHCPv6 server
+implementation. This component is built around the
+@ref isc::dhcp::Dhcpv6Srv class which controls all major operations
+performed by the server such as: DHCP messages processing, callouts
+execution for many hook points, FQDN processing and interactions with the
+"kea-dhcp-ddns" component, lease allocation, system signals handling etc.
 
- DHCPv6 server component does not support relayed traffic yet, as
- support for relay decapsulation is not implemented yet.
+The "kea-dhcp6" component requires linking with many different libraries
+to obtain access to common functions like: interfaces and sockets
+management, configuration parsing, leases management and allocation,
+hooks infrastructure, statistics management etc.
 
- @section dhcpv6ConfigParser Configuration Parser in DHCPv6
+The following sections walk through some of the details of the "kea-dhcp6"
+component implementation.
 
- \note With the implementation of the Kea ticket #3534 we're moving away from
- the concept of commit being called for individual parsers. When this ticket
- and a couple of followup tickets are implemented, the commit will be a
- single operation executed for the whole configuration received from many
- parsers.
+@section dhcpv6ConfigParser Configuration Parsers in DHCPv6
 
- All parsers are defined in src/bin/dhcp6/config_parser.cc file. Some of them
- are generic (e.g. Uint32Parser that is able to handle any
- unsigned 32 bit integer), but some are very specialized (e.g.
- Subnets6ListConfigParser parses definitions of Subnet6 lists). In some cases,
- e.g. subnet6 definitions, the configuration entry is not a simple value, but
- a map or a list itself. In such case, the parser iterates over all elements
- and creates parsers for a given scope. This process may be repeated (sort of)
- recursively.
+The common configuration parsers for the DHCP servers are located in the
+src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv6 component
+are located in the src/bin/dhcp6/json_config_parser.cc. These parsers derive
+from the common configuration parsers and customize their behavior. For
+example: the @c Subnet6ConfigParser is used to parse parameters
+describing a single subnet. It derives from the @ref
+isc::dhcp::SubnetConfigParser, which implements the common base for both
+DHCPv4 and DHCPv6 subnets. The @ref isc::dhcp::Subnet6ConfigParser
+implements the @c initSubnet abstract method, which creates an instance of
+the DHCPv6 subnet. This method is invoked by the parent class.
 
- @section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
+Some parsers for the DHCPv6 server derive from the isc::dhcp::DhcpConfigParser
+class directly. This is an abstract class, defining a basic interface for
+all configuration parsers. All DHCPv6 parsers deriving from this class
+directly have their entire implementation in the
+src/bin/dhcp6/json_config_parser.cc.
 
- One notable useful feature of DHCP configuration is its parameter inheritance.
- For example, renew-timer value may be specified at a global scope and it then
- applies to all subnets. However, some subnets may have it overwritten with more
- specific values that takes precedence over global values that are considered
- defaults. Some parsers (e.g. Uint32Parser and StringParser) implement that
- inheritance. By default, they store values in global uint32_defaults and
- string_defaults storages. However, it is possible to instruct them to store
- parsed values in more specific storages. That capability is used, e.g. in
- Subnet6ConfigParser that has its own storage that is unique for each subnet.
- Finally, during commit phase (commit() method), appropriate parsers can use
- apply parameter inheritance.
+@section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
 
- Debugging configuration parser may be confusing. Therefore there is a special
- class called DebugParser. It does not configure anything, but just
- accepts any parameter of any type. If requested to commit configuration, it will
- print out received parameter name and its value. This class is not currently used,
- but it is convenient to have it every time a new parameter is added to DHCP
- configuration. For that purpose it should be left in the code.
+One notable useful feature of DHCP configuration is its parameter inheritance.
+For example, "renew-timer" value may be specified at a global scope and it then
+applies to all subnets. However, some subnets may have it overwritten with subnet
+specific values that takes precedence over global values that are considered
+defaults. The parameters inheritance is implemented by means of the "global
+context". The global context is represented by the @ref isc::dhcp::ParserContext
+class and it holds pointers to storages of different kind, e.g. text parameters,
+numeric parameters etc. When the server is parsing the top level configuration
+parameters it passes pointers to the storages of the appropriate kind, to the
+parsers being invoked to parse the global values. Parsers will store the
+parsed values into these storages. Once the global parameters are stored in the
+global context, the parsers for the nested configuration parameters are invoked.
+These parsers check the presence of the parameters overriding the values of
+the global parameters. If a value is not present, the values from the global
+context is used.
 
- Parameter inheritance is done during reconfiguration phase, as reconfigurations
- are rare, so extra logic here is not a problem. On the other hand, values of
- those parameters may be used thousands times per second, so its use must be as
- simple as possible. In fact, currently the code has to call Subnet6->getT1() and
- do not implement any fancy inheritance logic.
+A good example of inheritance is the implementation of the @ref
+isc::dhcp::SubnetConfigParser. The @c getParam method is used throughout the
+class to obtain values of the parameters defining a subnet. It first checks
+if the specific value is present in the local values storage. If it is not
+present, it uses the value from the global context.
+
+@code
+isc::dhcp::Triplet<uint32_t>
+SubnetConfigParser::getParam(const std::string& name) {
+    uint32_t value = 0;
+    try {
+        // look for local value
+         value = uint32_values_->getParam(name);
+    } catch (const DhcpConfigError &) {
+        try {
+            // no local, use global value
+            value = global_context_->uint32_values_->getParam(name);
+        } catch (const DhcpConfigError &) {
+            isc_throw(DhcpConfigError, "Mandatory parameter " << name
+                      << " missing (no global default and no subnet-"
+                      << "specific value)");
+        }
+    }
+
+    return (Triplet<uint32_t>(value));
+}
+@endcode
+
+Note that if the value is neither present in the local storage nor in the global
+context an error is signalled.
+
+Parameter inheritance is done once, during the reconfiguration phase.
+Reconfigurations are rare, so extra logic here is not a problem. On the other
+hand, values of those parameters may be used thousands times per second, so
+access to these parameters must be as efficient as possible. In fact,
+currently the code has to only call @c Subnet6::getT1(), regardless if the
+"renew-timer" has been specified as a global or subnet specific value.
+
+Debugging configuration parser may be confusing. Therefore there is a special
+class called DebugParser. It does not configure anything, but just
+accepts any parameter of any type. If requested to commit configuration, it will
+print out received parameter name and its value. This class is not currently used,
+but it is convenient to have it every time a new parameter is added to DHCP
+configuration. For that purpose it should be left in the code.
 
 @section dhcpv6DDNSIntegration DHCPv6 Server Support for the Dynamic DNS Updates
 
@@ -156,12 +196,12 @@ formats and set option values. A number of options formats have been defined
 for standard options in libdhcp++. However, the formats for vendor specific
 options are dynamically configured by the server's administrator and thus can't
 be stored in libdhcp++. Such option formats are stored in the
-@c isc::dhcp::CfgMgr. The libdhcp++ provides functions for recursive parsing
+@ref isc::dhcp::CfgMgr. The libdhcp++ provides functions for recursive parsing
 of options which may be encapsulated by other options up to the any level of
 encapsulation but these functions are unaware of the option formats defined
-in the @c isc::dhcp::CfgMgr because they belong to a different library.
-Therefore, the generic functions @c isc::dhcp::LibDHCP::unpackOptions4 and
-@c isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
+in the @ref isc::dhcp::CfgMgr because they belong to a different library.
+Therefore, the generic functions @ref isc::dhcp::LibDHCP::unpackOptions4 and
+@ref isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
 options which definitions are provided in the libdhcp++. In order to overcome
 this problem a callback mechanism has been implemented in @c Option and @c Pkt6
 classes. By installing a callback function on the instance of the @c Pkt6 the
@@ -255,13 +295,9 @@ through the main loop. This method fetches the last received signal and calls
 a handler function defined in the kea_controller.cc. The handler function
 calls a static function @c configure defined in the kea_controller.cc.
 
-In order for the signal handler to know the location of the configuration file
-(specified at process startup), the location of this file needs to be stored
-in a static variable so as it may be directly accessed by the signal handler.
-This static variable is stored in the @c dhcp::Daemon class and all Kea processes
-can use it (all processes derive from this class). The configuration file
-location is initialized when the @c Daemon::init method is called. Therefore,
-derived classes should call it in their implementations of the @c init method.
+The signal handler reconfigures the server using the configuration file
+specified at the server startup. The location of this file is held in the
+@c Daemon class.
 
  @section dhcpv6Other Other DHCPv6 topics