Commit 938d8b31 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[2269] Documentation update in progress

parent 680279e6
......@@ -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
......
......@@ -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_;
};
......
......@@ -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
......
/**
* @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.
*/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment