mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-09-04 07:55:18 +00:00
[2324] Developer's Guide section written
This commit is contained in:
Tomek Mrugalski
@@ -57,76 +57,4 @@
|
||||
* that does not support msgq. That is useful for embedded environments.
|
||||
* It may also be useful in validation.
|
||||
*
|
||||
* @page libdhcp libdhcp++
|
||||
*
|
||||
* @section libdhcpIntro Libdhcp++ Library Introduction
|
||||
*
|
||||
* libdhcp++ is an all-purpose DHCP-manipulation library, written in
|
||||
* C++. It offers packet parsing and assembly, DHCPv4 and DHCPv6
|
||||
* options parsing and ssembly, interface detection (currently on
|
||||
* Linux systems only) and socket operations. Following classes are
|
||||
* implemented:
|
||||
*
|
||||
* - isc::dhcp::Pkt4 - represents DHCPv4 packet.
|
||||
* - isc::dhcp::Pkt6 - represents DHCPv6 packet.
|
||||
*
|
||||
* There are two pointer types defined: Pkt4Ptr and Pkt6Ptr. They are
|
||||
* smart pointer and are using boost::shared_ptr. There are not const
|
||||
* versions defined, as we assume that hooks can modify any aspect of
|
||||
* the packet at almost any stage of processing.
|
||||
*
|
||||
* Both packets use collection of Option objects to represent DHCPv4
|
||||
* and DHCPv6 options. The base class -- Option -- can be used to
|
||||
* represent generic option that contains collection of
|
||||
* bytes. Depending on if the option is instantiated as v4 or v6
|
||||
* option, it will adjust its header (DHCPv4 options use 1 octet for
|
||||
* type and 1 octet for length, while DHCPv6 options use 2 bytes for
|
||||
* each).
|
||||
*
|
||||
* There are many specialized classes that are intended to handle options with
|
||||
* specific content:
|
||||
* - isc::dhcp::Option4AddrLst -- DHCPv4 option, contains one or more IPv4 addresses;
|
||||
* - isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses;
|
||||
* - isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR_OPTION (an option that
|
||||
* contains IPv6 address with extra parameters);
|
||||
* - isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions.
|
||||
*
|
||||
* All options can store sub-options (i.e. options that are stored within option
|
||||
* rather than in a message directly). This functionality is commonly used in
|
||||
* DHCPv6, but is rarely used in DHCPv4. isc::dhcp::Option::addOption(),
|
||||
* isc::dhcp::Option::delOption(), isc::dhcp::Option::getOption() can be used
|
||||
* for that purpose.
|
||||
*
|
||||
* @section libdhcpIfaceMgr Interface Manager
|
||||
*
|
||||
* Interface Manager (or IfaceMgr) is an abstraction layer about low-level
|
||||
* network operations. In particlar, it provides information about existing
|
||||
* network interfaces See isc::dhcp::IfaceMgr::Iface class and
|
||||
* isc::dhcp::IfaceMgr::detectIfaces() and isc::dhcp::IfaceMgr::getIface().
|
||||
*
|
||||
* Currently there is interface detection is implemented in Linux only. There
|
||||
* are plans to implement such support for other OSes, but they remain low
|
||||
* priority for now.
|
||||
*
|
||||
* Generic parts of the code are isc::dhcp::IfaceMgr class in
|
||||
* src/lib/dhcp/iface_mgr.cc file. OS-specific code is located in separate
|
||||
* files, e.g. iface_mgr_linux.cc. Such separation should be maintained when
|
||||
* additional code will be developed.
|
||||
*
|
||||
* For systems that interface detection is not supported on, there is a stub
|
||||
* mechanism implemented. It assumes that interface name is read from a text
|
||||
* file. This is a temporary solution and will be removed as soon as proper
|
||||
* interface detection is implemented. It is not going to be developed further.
|
||||
* To use this feature, store interfaces.txt file. It uses a simple syntax.
|
||||
* Each line represents an interface name, followed by IPv4 or IPv6 address
|
||||
* that follows it. This is usually link-local IPv6 address that the server
|
||||
* should bind to. In theory this mechanism also supports IPv4, but it was
|
||||
* never tested. The code currently supports only a single interface defined
|
||||
* that way.
|
||||
*
|
||||
* Another useful methods are dedicated to transmission
|
||||
* (isc::dhcp::IfaceMgr::send(), 2 overloads) and reception
|
||||
* (isc::dhcp::IfaceMgr::receive4() and isc::dhcp::IfaceMgr::receive6()).
|
||||
* Note that receive4() and receive6() methods may return NULL, e.g.
|
||||
* when timeout is reached or if dhcp daemon receives a signal.
|
||||
*/
|
||||
@@ -29,6 +29,10 @@
|
||||
* - @subpage libdhcp
|
||||
* - @subpage libdhcpIntro
|
||||
* - @subpage libdhcpIfaceMgr
|
||||
* - @subpage libdhcpsrv
|
||||
* - @subpage leasemgr
|
||||
* - @subpage cfgmgr
|
||||
* - @subpage allocengine
|
||||
* - @subpage perfdhcpInternals
|
||||
*
|
||||
* @section misc Miscellaneous topics
|
||||
|
||||
@@ -35,7 +35,7 @@
|
||||
|
||||
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
|
||||
from a \ref isc::dhcp::DhcpConfigParser 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.
|
||||
@@ -51,7 +51,7 @@
|
||||
|
||||
@section dhcpv6-config-inherit DHCPv6 Configuration Inheritance
|
||||
|
||||
One notable useful features of DHCP configuration is its parameter 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
|
||||
@@ -64,7 +64,7 @@
|
||||
phase (commit() method), appropriate parsers can use apply parameter inheritance.
|
||||
|
||||
Debugging configuration parser may be confusing. Therefore there is a special
|
||||
class called \ref isc::dhcp::DummyParser. It does not configure anything, but just
|
||||
class called \ref isc::dhcp::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
|
||||
|
||||
79
src/lib/dhcp/libdhcp++.dox
Normal file
79
src/lib/dhcp/libdhcp++.dox
Normal file
@@ -0,0 +1,79 @@
|
||||
/**
|
||||
@page libdhcp libdhcp++
|
||||
|
||||
@section libdhcpIntro Libdhcp++ Library Introduction
|
||||
|
||||
libdhcp++ is an all-purpose DHCP-manipulation library, written in
|
||||
C++. It offers packet parsing and assembly, DHCPv4 and DHCPv6
|
||||
options parsing and ssembly, interface detection (currently on
|
||||
Linux systems only) and socket operations. It is a generic purpose library that
|
||||
can be used by server, client, relay, performance tools and other DHCP-related
|
||||
tools. For server specific library, see \ref libdhcpsrv. Please do not
|
||||
add any server-specific code to libdhcp++ and use \ref libdhcpsrv instead.
|
||||
|
||||
The following classes for packet manipulation are implemented:
|
||||
|
||||
- isc::dhcp::Pkt4 - represents DHCPv4 packet.
|
||||
- isc::dhcp::Pkt6 - represents DHCPv6 packet.
|
||||
|
||||
There are two pointer types defined: Pkt4Ptr and Pkt6Ptr. They are
|
||||
smart pointer and are using boost::shared_ptr. There are not const
|
||||
versions defined, as we assume that hooks can modify any aspect of
|
||||
the packet at almost any stage of processing.
|
||||
|
||||
Both packets use collection of Option objects to represent DHCPv4
|
||||
and DHCPv6 options. The base class -- Option -- can be used to
|
||||
represent generic option that contains collection of
|
||||
bytes. Depending on if the option is instantiated as v4 or v6
|
||||
option, it will adjust its header (DHCPv4 options use 1 octet for
|
||||
type and 1 octet for length, while DHCPv6 options use 2 bytes for
|
||||
each).
|
||||
|
||||
There are many specialized classes that are intended to handle options with
|
||||
specific content:
|
||||
- isc::dhcp::Option4AddrLst -- DHCPv4 option, contains one or more IPv4 addresses;
|
||||
- isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses;
|
||||
- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR_OPTION (an option that
|
||||
contains IPv6 address with extra parameters);
|
||||
- isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions.
|
||||
|
||||
All options can store sub-options (i.e. options that are stored within option
|
||||
rather than in a message directly). This functionality is commonly used in
|
||||
DHCPv6, but is rarely used in DHCPv4. isc::dhcp::Option::addOption(),
|
||||
isc::dhcp::Option::delOption(), isc::dhcp::Option::getOption() can be used
|
||||
for that purpose.
|
||||
|
||||
@section libdhcpIfaceMgr Interface Manager
|
||||
|
||||
Interface Manager (or IfaceMgr) is an abstraction layer about low-level
|
||||
network operations. In particlar, it provides information about existing
|
||||
network interfaces See isc::dhcp::IfaceMgr::Iface class and
|
||||
isc::dhcp::IfaceMgr::detectIfaces() and isc::dhcp::IfaceMgr::getIface().
|
||||
|
||||
Currently there is interface detection is implemented in Linux only. There
|
||||
are plans to implement such support for other OSes, but they remain low
|
||||
priority for now.
|
||||
|
||||
Generic parts of the code are isc::dhcp::IfaceMgr class in
|
||||
src/lib/dhcp/iface_mgr.cc file. OS-specific code is located in separate
|
||||
files, e.g. iface_mgr_linux.cc. Such separation should be maintained when
|
||||
additional code will be developed.
|
||||
|
||||
For systems that interface detection is not supported on, there is a stub
|
||||
mechanism implemented. It assumes that interface name is read from a text
|
||||
file. This is a temporary solution and will be removed as soon as proper
|
||||
interface detection is implemented. It is not going to be developed further.
|
||||
To use this feature, store interfaces.txt file. It uses a simple syntax.
|
||||
Each line represents an interface name, followed by IPv4 or IPv6 address
|
||||
that follows it. This is usually link-local IPv6 address that the server
|
||||
should bind to. In theory this mechanism also supports IPv4, but it was
|
||||
never tested. The code currently supports only a single interface defined
|
||||
that way.
|
||||
|
||||
Another useful methods are dedicated to transmission
|
||||
(isc::dhcp::IfaceMgr::send(), 2 overloads) and reception
|
||||
(isc::dhcp::IfaceMgr::receive4() and isc::dhcp::IfaceMgr::receive6()).
|
||||
Note that receive4() and receive6() methods may return NULL, e.g.
|
||||
when timeout is reached or if dhcp daemon receives a signal.
|
||||
|
||||
*/
|
||||
86
src/lib/dhcp/libdhcsrv.dox
Normal file
86
src/lib/dhcp/libdhcsrv.dox
Normal file
@@ -0,0 +1,86 @@
|
||||
/**
|
||||
@page libdhcpsrv libdhcpsrv - Server DHCP library
|
||||
|
||||
This library contains code useful for DHCPv4 and DHCPv6 server operations, like
|
||||
Lease Manager that stores leases information, configuration manager that stores
|
||||
configuration etc. The code here is server specific. For generic (useful in
|
||||
server, client, relay and other tools like perfdhcp) code, please see
|
||||
\ref libdhcp.
|
||||
|
||||
This library contains several crucial elements of the DHCP server operation:
|
||||
|
||||
- isc::dhcp::LeaseMgr - Lease Manager is a name for database backend that stores
|
||||
leases.
|
||||
- isc::dhcp::CfgMgr - Configuration Manager that holds DHCP specific
|
||||
configuration information (subnets, pools, options, timer values etc.) in
|
||||
easy to use format.
|
||||
- AllocEngine - allocation engine that handles new requestes and allocates new
|
||||
leases.
|
||||
|
||||
@section leasemgr Lease Manager
|
||||
|
||||
LeaseMgr provides a common, unified abstract API for all database backends. All
|
||||
backends are derived from the base class isc::dhcp::LeaseMgr. Currently the
|
||||
only available backend is MySQL (see \ref isc::dhcp::MySqlLeaseMgr).
|
||||
|
||||
@section cfgmgr Configuration Manager
|
||||
|
||||
Configuration Manager (\ref isc::dhcp::CfgMgr) stores configuration information
|
||||
necessary for DHCPv4 and DHCPv6 server operation. In particular, it stores
|
||||
subnets (\ref isc::dhcp::Subnet4 and \ref isc::dhcp::Subnet6) together with
|
||||
their pools (\ref isc::dhcp::Pool4 and \ref isc::dhcp::Pool6), options and
|
||||
other information specified by the used in BIND10 configuration.
|
||||
|
||||
@section allocengine Allocation Engine
|
||||
|
||||
Allocation Engine (\ref isc::dhcp::AllocEngine) is what its name say - an engine
|
||||
that handles allocation of new leases. It takes parameters that the client
|
||||
provided (client-id, DUID, subnet, a hint if the user provided one, etc.) and
|
||||
then attempts to allocate a lease.
|
||||
|
||||
There is no single best soluction to the address assignment problem. Server
|
||||
is expected to pick an address from its available pools is currently not used.
|
||||
There are many possible algorithms that can do that, each with its own advantages
|
||||
and drawbacks. This allocation engine must provide robust operation is radically
|
||||
different scenarios, so there address selection problem was abstracted into
|
||||
separate module, called allocator. Its sole purpose is to pick an address from
|
||||
a pool. Allocation engine will then check if the picked address is free and if
|
||||
it is not, then will ask allocator to pick again.
|
||||
|
||||
At lease 3 allocators will be implemented:
|
||||
|
||||
- Iterative - it iterates over all addresses in available pools, one
|
||||
by one. The advantages of this approach are speed (typically it only needs to
|
||||
increase last address), the guarantee to cover all addresses and predictability.
|
||||
This allocator behaves very good in case of nearing depletion. Even when pools
|
||||
are almost completely allocated, it still will be able to allocate outstanding
|
||||
leases efficiently. Predictability can also be considered a serious flaw in
|
||||
some environments, as prediction of the next address is trivial and can be
|
||||
leveraged by an attacker. Another drawback of this allocator is that it does
|
||||
not attempt to give the same address to returning clients (clients that released
|
||||
or expired their leases and are requesting a new lease will likely to get a
|
||||
different lease). This allocator is implemented in \ref isc::dhcp::AllocEngine::IterativeAllocator.
|
||||
|
||||
- Hashed - ISC-DHCP uses hash of the client-id or DUID to determine, which
|
||||
address is tried first. If that address is not available, the result is hashed
|
||||
again. That procedure is repeated until available address is found or there
|
||||
are no more addresses left. The benefit of that approach is that it provides
|
||||
a relative lease stability, so returning old clients are likely to get the same
|
||||
address again. The drawbacks are increased computation cost, as each iteration
|
||||
requires use of a hashing function. That is especially difficult when the
|
||||
pools are almost depleted. It also may be difficult to guarantee that the
|
||||
repeated hashing will iterate over all available addresses in all pools. Flawed
|
||||
hash algorithm can go into cycles that iterate over only part of the addresses.
|
||||
It is difficult to detect such issues as only some initial seed (client-id
|
||||
or DUID) values may trigger short cycles. This allocator is currently not
|
||||
implemented.
|
||||
|
||||
- Random - Another possible approach to address selection is randomization. This
|
||||
allocator can pick an address randomly from the configured pool. The benefit
|
||||
of this approach is that it is easy to implement and makes attacks based on
|
||||
address prediction more difficult. The drawback of this approach is that
|
||||
returning clients are almost guaranteed to get a different address. Another
|
||||
drawback is that with almost depleted pools it is increasingly difficult to
|
||||
"guess" an address that is free. This allocator is currently not implemented.
|
||||
|
||||
*/
|
||||
@@ -141,6 +141,7 @@ public:
|
||||
|
||||
/// @brief the constructor for Pool6 "min-max" style definition
|
||||
///
|
||||
/// @param type type of the pool (IA, TA or PD)
|
||||
/// @param first the first address in a pool
|
||||
/// @param last the last address in a pool
|
||||
Pool6(Pool6Type type, const isc::asiolink::IOAddress& first,
|
||||
@@ -148,6 +149,7 @@ public:
|
||||
|
||||
/// @brief the constructor for Pool6 "prefix/len" style definition
|
||||
///
|
||||
/// @param type type of the pool (IA, TA or PD)
|
||||
/// @param prefix specifies prefix of the pool
|
||||
/// @param prefix_len specifies length of the prefix of the pool
|
||||
Pool6(Pool6Type type, const isc::asiolink::IOAddress& prefix,
|
||||
|
||||
Reference in New Issue
Block a user