Commit 461164b5 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[2324] Developer's Guide section written

parent 71a249c1
......@@ -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.
*/
\ No newline at end of file
......@@ -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
......
/**
@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.
*/
\ No newline at end of file
/**
@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.
*/
\ No newline at end of file
......@@ -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,
......
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