[2269] Documentation update in progress

doc/devel/02-dhcp.dox

@@ -57,29 +57,6 @@
  * that does not support msgq. That is useful for embedded environments.
  * It may also be useful in validation.
  *
- * @page dhcpv6 DHCPv6 Server Component
- *
- * BIND10 offers DHCPv6 server implementation. It is implemented as
- * b10-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 trasmit responses. However, it does not have database
- * management, so it returns only one, hardcoded lease to whoever asks
- * for it.
- *
- * DHCPv6 server component does not support relayed traffic yet, as
- * support for relay decapsulation is not implemented yet.
- *
- * DHCPv6 server component does not use BIND10 logging yet.
- *
- * @section dhcpv6Session BIND10 message queue integration
- *
- * DHCPv4 server component is now integrated with BIND10 message queue.
- * It follows the same principle as DHCPv4. See \ref dhcpv4Session for
- * details.
- *
  * @page libdhcp libdhcp++
  *
  * @section libdhcpIntro Libdhcp++ Library Introduction

src/bin/dhcp6/config_parser.cc

@@ -39,20 +39,33 @@ using namespace isc::asiolink;
 namespace isc {
 namespace dhcp {
 
-typedef boost::shared_ptr<Dhcp6ConfigParser> ParserPtr;
+/// @brief auxiliary type used for storing element name and its parser
 typedef pair<string, ConstElementPtr> ConfigPair;
-typedef std::vector<ParserPtr> ParserCollection;
+
+/// @brief a factory method that will create a parser for a given element name
 typedef Dhcp6ConfigParser* ParserFactory(const std::string& config_id);
+
+/// @brief a collection of factories that creates parsers for specified element names
 typedef std::map<std::string, ParserFactory*> FactoryMap;
+
+/// @brief a collection of elements that store uint32 values (e.g. renew-timer = 900)
 typedef std::map<string, uint32_t> Uint32Storage;
-/// @brief That is a map with global parameters that will be used as defaults
-Uint32Storage uint32_defaults;
 
+/// @brief a collection of elements that store string values
 typedef std::map<string, string> StringStorage;
-StringStorage string_defaults;
 
+/// @brief a collection of pools
+///
+/// That type is used as intermediate storage, when pools are parsed, but there is
+/// no subnet object created yet to store them.
 typedef std::vector<Pool6Ptr> PoolStorage;
 
+/// @brief Global uint32 parameters that will be used as defaults.
+Uint32Storage uint32_defaults;
+
+/// @brief global string parameters that will be used as defaults.
+StringStorage string_defaults;
+
 /// @brief a dummy configuration parser
 ///
 /// It is a debugging parser. It does not configure anything,
@@ -74,6 +87,8 @@ public:
     /// @brief builds parameter value
     ///
     /// See \ref Dhcp6ConfigParser class for details.
+    ///
+    /// @param new_config pointer to the new configuration
     virtual void build(ConstElementPtr new_config) {
         std::cout << "Build for token: [" << param_name_ << "] = ["
                   << value_->str() << "]" << std::endl;
@@ -109,7 +124,7 @@ protected:
     ConstElementPtr value_;
 };
 
-/// @brief Configuration parser for uint32 types
+/// @brief Configuration parser for uint32 parameters
 ///
 /// This class is a generic parser that is able to handle any uint32 integer
 /// type. By default it stores the value in external global container
@@ -117,19 +132,21 @@ protected:
 /// in subnet config), it can be pointed to a different storage, using
 /// setStorage() method. This class follows the parser interface, laid out
 /// in its base class, \ref Dhcp6ConfigParser.
-
+///
+/// For overview of usability of this generic purpose parser, see
+/// \ref dhcpv6-config-inherit page.
 class Uint32Parser : public Dhcp6ConfigParser {
 public:
 
     /// @brief constructor for Uint32Parser
-    /// @param param_name name of the parameter that is going to be parsed
+    /// @param param_name name of the configuration parameter being parsed
     Uint32Parser(const std::string& param_name)
         :storage_(&uint32_defaults), param_name_(param_name) {
     }
 
     /// @brief builds parameter value
     ///
-    /// Parses configuration entry and stored it in storage. See
+    /// Parses configuration entry and stores it in a storage. See
     /// \ref setStorage() for details.
     ///
     /// @param value pointer to the content of parsed values
@@ -154,76 +171,153 @@ public:
     virtual void commit() {
     }
 
-    /// @brief factory that constructs DummyParser objects
+    /// @brief factory that constructs Uint32Parser objects
     ///
     /// @param param_name name of the parameter to be parsed
     static Dhcp6ConfigParser* Factory(const std::string& param_name) {
         return (new Uint32Parser(param_name));
     }
 
+    /// @brief sets storage for value of this parameter
+    ///
+    /// See \ref dhcpv6-config-inherit for details.
+    ///
+    /// @param storage pointer to the storage container
     void setStorage(Uint32Storage* storage) {
         storage_ = storage;
     }
 
 protected:
+    /// pointer to the storage, where parsed value will be stored
     Uint32Storage * storage_;
+
+    /// name of the parameter to be parsed
     std::string param_name_;
+
+    /// the actual parsed value
     uint32_t value_;
 };
 
+/// @brief Configuration parser for string parameters
+///
+/// This class is a generic parser that is able to handle any string
+/// parameter. By default it stores the value in external global container
+/// (string_defaults). If used in smaller scopes (e.g. to parse parameters
+/// in subnet config), it can be pointed to a different storage, using
+/// setStorage() method. This class follows the parser interface, laid out
+/// in its base class, \ref Dhcp6ConfigParser.
+///
+/// For overview of usability of this generic purpose parser, see
+/// \ref dhcpv6-config-inherit page.
 class StringParser : public Dhcp6ConfigParser {
 public:
+
+    /// @brief constructor for StringParser
+    /// @param param_name name of the configuration parameter being parsed
     StringParser(const std::string& param_name)
         :storage_(&string_defaults), param_name_(param_name) {
     }
 
+    /// @brief builds parameter value
+    ///
+    /// Parses configuration entry and stored it in storage. See
+    /// \ref setStorage() for details.
+    ///
+    /// @param value pointer to the content of parsed values
     virtual void build(ConstElementPtr value) {
         value_ = value->str();
         boost::erase_all(value_, "\"");
         storage_->insert(pair<string, string>(param_name_, value_));
     }
 
+    /// @brief does nothing
+    ///
+    /// This method is required for all parser. The value itself
+    /// is not commited anywhere. Higher level parsers are expected to
+    /// use values stored in the storage, e.g. renew-timer for a given
+    /// subnet is stored in subnet-specific storage. It is not commited
+    /// here, but is rather used by its parent parser when constructing
+    /// an object, e.g. the subnet.
     virtual void commit() {
     }
 
+    /// @brief factory that constructs StringParser objects
+    ///
+    /// @param param_name name of the parameter to be parsed
     static Dhcp6ConfigParser* Factory(const std::string& param_name) {
         return (new StringParser(param_name));
     }
 
+    /// @brief sets storage for value of this parameter
+    ///
+    /// See \ref dhcpv6-config-inherit for details.
+    ///
+    /// @param storage pointer to the storage container
     void setStorage(StringStorage * storage) {
         storage_ = storage;
     }
 
 protected:
+    /// pointer to the storage, where parsed value will be stored
     StringStorage * storage_;
+
+    /// name of the parameter to be parsed
     std::string param_name_;
+
+    /// the actual parsed value
     std::string value_;
 };
 
+
+/// @brief parser for interface list definition
+///
+/// This parser handles Dhcp6/interface entry.
+/// It contains a list of network interfaces that the server listens on.
+/// In particular, it can contain an entry called "all" or "any" that
+/// designates all interfaces.
 class InterfaceListConfigParser : public Dhcp6ConfigParser {
 public:
+
+    /// @brief constructor
+    ///
+    /// As this is a dedicated parser, it must be used to parse
+    /// "interface" parameter only. All other types will throw exception.
+    ///
+    /// @param param_name name of the configuration parameter being parsed
     InterfaceListConfigParser(const std::string& param_name) {
         if (param_name != "interface") {
             isc_throw(NotImplemented, "Internal error. Interface configuration "
                       "parser called for the wrong parameter: " << param_name);
         }
     }
+
+    /// @brief parses parameters value
+    ///
+    /// Parses configuration entry (list of parameters) and stores it in
+    /// storage. See \ref setStorage() for details.
+    ///
+    /// @param value pointer to the content of parsed values
     virtual void build(ConstElementPtr value) {
         BOOST_FOREACH(ConstElementPtr iface, value->listValue()) {
             interfaces_.push_back(iface->str());
         }
     }
 
+    /// @brief commits interfaces list configuration
     virtual void commit() {
-        /// @todo: Implement per interface listening. Currently always listening on all
-        /// interfaces.
+        /// @todo: Implement per interface listening. Currently always listening
+        /// on all interfaces.
     }
 
+    /// @brief factory that constructs InterfaceListConfigParser objects
+    ///
+    /// @param param_name name of the parameter to be parsed
     static Dhcp6ConfigParser* Factory(const std::string& param_name) {
         return (new InterfaceListConfigParser(param_name));
     }
 
 protected:
+    /// contains list of network interfaces
     vector<string> interfaces_;
 };
 

src/bin/dhcp6/config_parser.h

@@ -28,6 +28,12 @@ class Dhcpv6Srv;
 /// \c Dhcpv6Srv object.
 class Dhcp6ConfigError : public isc::Exception {
 public:
+
+/// @brief constructor
+///
+/// @param file name of the file, where exception occurred
+/// @param line line of the file, where exception occurred
+/// @param what text description of the issue that caused exception
 Dhcp6ConfigError(const char* file, size_t line, const char* what) :
     isc::Exception(file, line, what) {}
 };
@@ -103,6 +109,15 @@ public:
     virtual void commit() = 0;
 };
 
+/// @brief a pointer to configuration parser
+typedef boost::shared_ptr<Dhcp6ConfigParser> ParserPtr;
+
+/// @brief a collection of parsers
+///
+/// This container is used to store pointer to parsers for a given scope.
+typedef std::vector<ParserPtr> ParserCollection;
+
+
 /// Configure an \c Dhcpv6Srv object with a set of configuration values.
 ///
 /// This function parses configuration information stored in \c config_set

src/bin/dhcp6/dhcp6.dox

@@ -0,0 +1,80 @@
+/**
+ * @page dhcpv6 DHCPv6 Server Component
+ *
+ * BIND10 offers DHCPv6 server implementation. It is implemented as
+ * b10-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 trasmit responses. However, it does not have database
+ * management, so it returns only one, hardcoded lease to whoever asks
+ * for it.
+ *
+ * DHCPv6 server component does not support relayed traffic yet, as
+ * support for relay decapsulation is not implemented yet.
+ *
+ * DHCPv6 server component does not use BIND10 logging yet.
+ *
+ * @section dhcpv6Session BIND10 message queue integration
+ *
+ * DHCPv4 server component is now integrated with BIND10 message queue.
+ * It follows the same principle as DHCPv4. See \ref dhcpv4Session for
+ * details.
+  
+ @section dhcpv6-config-parser Configuration Parser in DHCPv6
+
+ b10-dhcp6 component uses BIND10 cfgmgr for commands and configuration. During
+ initial configuration (See \ref ControlledDhcpv6Srv::establishSession()),
+ the configuration handler callback is installed 
+ (see ControlledDhcpv6Srv::dhcp6ConfigHandler(). It is called every time there
+ is a new configuration. In particular, it is called every time during daemon
+ start process. It contains a ConstElementPtr to a new configuration. This
+ simple handler calls \ref isc::dhcp::configureDhcp6Server() method that
+ processes received configuration.
+
+ This method iterates over list of received configuration elements and creates
+ a list of parsers for each received entry. Parser is an object that is derived
+ from a \ref Dhcp6ConfigParser class. Once a parser is created (constructor),
+ its value is set (using build() method). Once all parsers are build, the
+ configuration is then applied ("commited") and commit() method is called.
+
+ All parsers are defined in src/bin/dhcp6/config_parser.cc file. Some
+ of them are generic (e.g. \ref Uint32Parser that is able to handle
+ any unsigned 32 bit integer), but some are very specialized
+ (e.g. \ref 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.
+ 
+ @section dhcpv6-config-inherit DHCPv6 Configuration Inheritance
+
+ One notable useful features 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. \ref Uint32ConfigParser 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 \ref 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.
+
+ Debugging configuration parser may be confusing. Therefore there is a special
+ class called \ref DummyParser. 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.
+
+ 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.
+
+ */
+
+