Commit 655ba0fe authored by Marcin Siodelski's avatar Marcin Siodelski

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

parent 35f4c76b
......@@ -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 \
......
......@@ -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.
DHCPv6 server component does not support relayed traffic yet, as
support for relay decapsulation is not implemented yet.
@section dhcpv6ConfigParser Configuration Parser in DHCPv6
\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.
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.
@section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
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.
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.
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.
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.
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.
The following sections walk through some of the details of the "kea-dhcp6"
component implementation.
@section dhcpv6ConfigParser Configuration Parsers in DHCPv6
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.
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.
@section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
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.
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
......
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