BIND 10 trac2269, updated. 5b9ab4bc5c038d3fe6e12a0cf90c33e5f54d0f45 [2269] Developer's guide updated.
BIND 10 source code commits
bind10-changes at lists.isc.org
Mon Oct 1 17:20:21 UTC 2012
The branch, trac2269 has been updated
via 5b9ab4bc5c038d3fe6e12a0cf90c33e5f54d0f45 (commit)
via 43636d3f31d1684984eb5337b91a418dd1725fbe (commit)
from 938d8b3145666d6f7d7084668b0ee665b3458e4a (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 5b9ab4bc5c038d3fe6e12a0cf90c33e5f54d0f45
Author: Tomek Mrugalski <tomasz at isc.org>
Date: Mon Oct 1 19:19:49 2012 +0200
[2269] Developer's guide updated.
commit 43636d3f31d1684984eb5337b91a418dd1725fbe
Author: Tomek Mrugalski <tomasz at isc.org>
Date: Mon Oct 1 18:56:55 2012 +0200
[2269] Remaining DHCPv6 config parsers documented.
-----------------------------------------------------------------------
Summary of changes:
doc/devel/mainpage.dox | 5 ++
src/bin/dhcp6/config_parser.cc | 126 +++++++++++++++++++++++++++++++++++++---
src/bin/dhcp6/dhcp6.dox | 115 ++++++++++++++++++------------------
3 files changed, 181 insertions(+), 65 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index ca9d881..0da5287 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -15,12 +15,17 @@
* <a href="http://bind10.isc.org/">BIND10 webpage (http://bind10.isc.org)</a>
*
* @section DNS
+ * - Authoritative DNS (todo)
+ * - Recursive resolver (todo)
* - @subpage DataScrubbing
*
* @section DHCP
* - @subpage dhcpv4
* - @subpage dhcpv4Session
* - @subpage dhcpv6
+ * - @subpage dhcpv6-session
+ * - @subpage dhcpv6-config-parser
+ * - @subpage dhcpv6-config-inherit
* - @subpage libdhcp
* - @subpage libdhcpIntro
* - @subpage libdhcpIfaceMgr
diff --git a/src/bin/dhcp6/config_parser.cc b/src/bin/dhcp6/config_parser.cc
index 271c3b1..6c6c937 100644
--- a/src/bin/dhcp6/config_parser.cc
+++ b/src/bin/dhcp6/config_parser.cc
@@ -218,7 +218,7 @@ public:
:storage_(&string_defaults), param_name_(param_name) {
}
- /// @brief builds parameter value
+ /// @brief parses parameter value
///
/// Parses configuration entry and stored it in storage. See
/// \ref setStorage() for details.
@@ -275,6 +275,8 @@ protected:
/// 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.
+///
+/// It is useful for parsing Dhcp6/interface parameter.
class InterfaceListConfigParser : public Dhcp6ConfigParser {
public:
@@ -321,12 +323,30 @@ protected:
vector<string> interfaces_;
};
+/// @brief parser for pool definition
+///
+/// This parser handles pool definitions, i.e. a list of entries of one
+/// of two syntaxes: min-max and prefix/len. Pool6 objects are created
+/// and stored in chosen PoolStorage container.
+///
+/// As there are no default values for pool, setStorage() must be called
+/// before build(). Otherwise exception will be thrown.
+///
+/// It is useful for parsing Dhcp6/subnet6[X]/pool parameters.
class PoolParser : public Dhcp6ConfigParser {
public:
+
+ /// @brief constructor.
PoolParser(const std::string& /*param_name*/)
:pools_(NULL) {
// ignore parameter name, it is always Dhcp6/subnet6[X]/pool
}
+
+ /// @brief parses the actual list
+ ///
+ /// This method parses the actual list of interfaces.
+ /// No validation is done at this stage, everything is interpreted as
+ /// interface name.
void build(ConstElementPtr pools_list) {
// setStorage() should have been called before build
if (!pools_) {
@@ -336,8 +356,6 @@ public:
BOOST_FOREACH(ConstElementPtr text_pool, pools_list->listValue()) {
-
-
// That should be a single pool representation. It should contain
// text is form prefix/len or first - last. Note that spaces
// are allowed
@@ -390,27 +408,54 @@ public:
". Does not contain - (for min-max) nor / (prefix/len)");
}
}
+
+ /// @brief sets storage for value of this parameter
+ ///
+ /// See \ref dhcpv6-config-inherit for details.
+ ///
+ /// @param storage pointer to the storage container
void setStorage(PoolStorage* storage) {
pools_ = storage;
}
- void commit() {}
+ /// @brief does nothing.
+ ///
+ /// This method is required for all parser. The value itself
+ /// is not commited anywhere. Higher level parsers (for subnet) are expected
+ /// to use values stored in the storage,
+ virtual void commit() {}
+ /// @brief factory that constructs PoolParser objects
+ ///
+ /// @param param_name name of the parameter to be parsed
static Dhcp6ConfigParser* Factory(const std::string& param_name) {
return (new PoolParser(param_name));
}
protected:
+ /// @brief pointer to the actual Pools storage
+ ///
+ /// That is typically a storage somewhere in Subnet parser
+ /// (an upper level parser).
PoolStorage * pools_;
-
};
/// @brief this class parses a single subnet
+///
+/// This class parses the whole subnet definition. It creates parsers
+/// for received configuration parameters as needed.
class Subnet6ConfigParser : public Dhcp6ConfigParser {
public:
- Subnet6ConfigParser(const std::string& param_name) {
+
+ /// @brief constructor
+ Subnet6ConfigParser(const std::string& ) {
+ // The parameter should always be "subnet", but we don't check here
+ // against it in case some wants to reuse this parser somewhere.
}
+ /// @brief parses parameter value
+ ///
+ /// @param subnet pointer to the content of subnet definition
void build(ConstElementPtr subnet) {
BOOST_FOREACH(ConfigPair param, subnet->mapValue()) {
@@ -444,6 +489,12 @@ public:
// Ok, we now have subnet parsed
}
+ /// @brief commits received configuration.
+ ///
+ /// This method does most of the configuration. Many other parsers are just
+ /// storing the values that are actually consumed here. Pool definitions
+ /// created in other parsers are used here and added to newly created Subnet6
+ /// objects. Subnet6 are then added to DHCP CfgMgr.
void commit() {
StringStorage::const_iterator it = string_values_.find("subnet");
@@ -486,6 +537,13 @@ public:
}
protected:
+
+ /// @brief creates parsers for entries in subnet definition
+ ///
+ /// @todo Add subnet-specific things here (e.g. subnet-specific options)
+ ///
+ /// @param config_id name od the entry
+ /// @return parser object for specified entry name
Dhcp6ConfigParser* createSubnet6ConfigParser(const std::string& config_id) {
FactoryMap factories;
@@ -516,6 +574,14 @@ protected:
return (f->second(config_id));
}
+ /// @brief returns value for a given parameter (after using inheritance)
+ ///
+ /// This method implements inheritance. For a given parameter name, it first
+ /// checks if there is a global value for it and overwrites it with specific
+ /// value if such value was defined in subnet.
+ ///
+ /// @param name name of the parameter
+ /// @return triplet with the parameter name
Triplet<uint32_t> getParam(const std::string& name) {
uint32_t value = 0;
bool found = false;
@@ -540,18 +606,39 @@ protected:
}
}
+ /// storage for subnet-specific uint32 values
Uint32Storage uint32_values_;
+
+ /// storage for subnet-specific integer values
StringStorage string_values_;
+
+ /// storage for pools belonging to this subnet
PoolStorage pools_;
+
+ /// parsers are stored here
ParserCollection parsers_;
};
/// @brief this class parses list of subnets
+///
+/// This is a wrapper parser that handles the whole list of Subnet6
+/// definitions. It iterates over all entries and creates Subnet6ConfigParser
+/// for each entry.
class Subnets6ListConfigParser : public Dhcp6ConfigParser {
public:
- Subnets6ListConfigParser(const std::string& param_name) {
+
+ /// @brief constructor
+ ///
+ Subnets6ListConfigParser(const std::string&) {
+ /// parameter name is ignored
}
+ /// @brief parses contents of the list
+ ///
+ /// Iterates over all entries on the list and creates Subnet6ConfigParser
+ /// for each entry.
+ ///
+ /// @param subnets_list pointer to a list of IPv6 subnets
void build(ConstElementPtr subnets_list) {
// No need to define FactoryMap here. There's only one type
@@ -566,6 +653,10 @@ public:
}
+ /// @brief commits subnets definitions.
+ ///
+ /// Iterates over all Subnet6 parsers. Each parser contains definitions
+ /// of a single subnet and its parameters and commits each subnet separately.
void commit() {
// @todo: Implement more subtle reconfiguration than toss
// the old one and replace with the new one.
@@ -579,10 +670,14 @@ public:
}
+ /// @brief Returns Subnet6ListConfigParser object
+ /// @param param_name name of the parameter
+ /// @return Subnets6ListConfigParser object
static Dhcp6ConfigParser* Factory(const std::string& param_name) {
return (new Subnets6ListConfigParser(param_name));
}
+ /// @brief collection of subnet parsers.
ParserCollection subnets_;
};
@@ -590,6 +685,9 @@ public:
///
/// This method creates global parsers that parse global parameters, i.e.
/// those that take format of Dhcp6/param1, Dhcp6/param2 and so forth.
+///
+/// @param config_id pointer to received global configuration entry
+/// @return parser for specified global DHCPv6 parameter
Dhcp6ConfigParser* createGlobalDhcp6ConfigParser(const std::string& config_id) {
FactoryMap factories;
@@ -623,6 +721,20 @@ Dhcp6ConfigParser* createGlobalDhcp6ConfigParser(const std::string& config_id) {
return (f->second(config_id));
}
+/// @brief configures DHCPv6 server
+///
+/// This function is called every time a new configuration is received. The extra
+/// parameter is a reference to DHCPv6 server component. It is currently not used
+/// and CfgMgr::instance() is accessed instead.
+///
+/// This method does not throw. It catches all exceptions and returns them as
+/// reconfiguration statuses. It may return the following response codes:
+/// 0 - configuration successful
+/// 1 - malformed configuration (parsing failed)
+/// 2 - logical error (parsing was successful, but the values are invalid)
+///
+/// @param config_set a new configuration for DHCPv6 server
+/// @return answer that contains result of reconfiguration
ConstElementPtr
configureDhcp6Server(Dhcpv6Srv& , ConstElementPtr config_set) {
if (!config_set) {
diff --git a/src/bin/dhcp6/dhcp6.dox b/src/bin/dhcp6/dhcp6.dox
index aafd4d6..fe842de 100644
--- a/src/bin/dhcp6/dhcp6.dox
+++ b/src/bin/dhcp6/dhcp6.dox
@@ -1,71 +1,72 @@
/**
- * @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 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 dhcpv6-session 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.
+ initial configuration (See \ref
+ isc::dhcp::ControlledDhcpv6Srv::establishSession()), the configuration handler
+ callback is installed (see isc::dhcp::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
+ isc::data::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.
+ 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 isc::dhcp::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
+ All parsers are defined in src/bin/dhcp6/config_parser.cc file. Some of them
+ are generic (e.g. \ref isc::dhcp::Uint32Parser that is able to handle any
+ unsigned 32 bit integer), but some are very specialized (e.g. \ref
+ isc::dhcp::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.
-
+ 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.
+ 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 isc::dhcp::Uint32Parser and \ref
+ isc::dhcp::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 isc::dhcp::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,
+ class called \ref isc::dhcp::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.
@@ -76,5 +77,3 @@
do not implement any fancy inheritance logic.
*/
-
-
More information about the bind10-changes
mailing list