mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-03 15:35:17 +00:00
Code Issues Releases Wiki Activity

[2270] Documentation for DHCPv4 config. parser written.

Browse Source
This commit is contained in:
Tomek Mrugalski
2012-10-12 14:55:59 +02:00
parent d2c2edbfa7
commit 4b59798e65
5 changed files with 170 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
doc/devel/02-dhcp.dox
View File

@@ -1,62 +1,4 @@
/**
* @page dhcpv4 DHCPv4 Server Component
*
* BIND10 offers DHCPv4 server implementation. It is implemented as
* b10-dhcp4 component. Its primary code is located in
* isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively,
* especially isc::dhcp::Pkt4, 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.
*
* DHCPv4 server component does not support direct traffic (relayed
* only), as support for transmission to hosts without IPv4 address
* assigned is not implemented in IfaceMgr yet.
*
* DHCPv4 server component does not use BIND10 logging yet.
*
* @section dhcpv4Session BIND10 message queue integration
*
* DHCPv4 server component is now integrated with BIND10 message queue.
* The integration is performed by establishSession() and disconnectSession()
* functions in isc::dhcp::ControlledDhcpv4Srv class. main() method deifined
* in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
* class that establishes connection with msgq and install necessary handlers
* for receiving commands and configuration updates. It is derived from
* a base isc::dhcp::Dhcpv4Srv class that implements DHCPv4 server functionality,
* without any controlling mechanisms.
*
* ControlledDhcpv4Srv instantiates several components to make management
* session possible. In particular, isc::cc::Session cc_session
* object uses ASIO for establishing connection. It registers its socket
* in isc::asiolink::IOService io_service object. Typically, other components
* (e.g. auth or resolver) that use ASIO for their communication, register their
* other sockets in the
* same io_service and then just call io_service.run() method that does
* not return, until one of the callback decides that it is time to shut down
* the whole component cal calls io_service.stop(). DHCPv4 works in a
* different way. It does receive messages using select()
* (see isc::dhcp::IfaceMgr::receive4()), which is incompatible with ASIO.
* To solve this problem, socket descriptor is extracted from cc_session
* object and is passed to IfaceMgr by using isc::dhcp::IfaceMgr::set_session_socket().
* IfaceMgr then uses this socket in its select() call. If there is some
* data to be read, it calls registered callback that is supposed to
* read and process incoming data.
*
* This somewhat complicated approach is needed for a simple reason. In
* embedded deployments there will be no message queue. Not referring directly
* to anything related to message queue in isc::dhcp::Dhcpv4Srv and
* isc::dhcp::IfaceMgr classes brings in two benefits. First, the can
* be used with and without message queue. Second benefit is related to the
* first one: \ref libdhcp is supposed to be simple and robust and not require
* many dependencies. One notable example of a use case that benefits from
* this approach is a perfdhcp tool. Finally, the idea is that it should be
* possible to instantiate Dhcpv4Srv object directly, thus getting a server
* 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

14
doc/devel/mainpage.dox
View File

@@ -20,12 +20,14 @@
* - @subpage DataScrubbing
*
* @section DHCP
* - @subpage dhcpv4
* - @subpage dhcpv4Session
* - @subpage dhcpv6
* - @subpage dhcpv6-session
* - @subpage dhcpv6-config-parser
* - @subpage dhcpv6-config-inherit
* - @subpage dhcp4
* - @subpage dhcp4-session
* - @subpage dhcp4-config-parser
* - @subpage dhcp4-config-inherit
* - @subpage dhcp6
* - @subpage dhcp6-session
* - @subpage dhcp6-config-parser
* - @subpage dhcp6-config-inherit
* - @subpage libdhcp
* - @subpage libdhcpIntro
* - @subpage libdhcpIfaceMgr

96
doc/guide/bind10-guide.xml
View File

@@ -2750,16 +2750,94 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<section id="dhcp4-config">
<title>DHCPv4 Server Configuration</title>
<para>
The DHCPv4 server does not have a lease database implemented yet
nor any support for configuration, so the same set
of configuration options (including the same fixed address)
will be assigned every time.
Once the server is started, it can be configured. To view the
current configuration, use the following command in <command>bindctl</command>:
<screen>
&gt; <userinput>config show Dhcp4</userinput></screen>
When starting Dhcp4 daemon for the first time, the default configuration
will be available. It will look similar to this:
<screen>
&gt; <userinput>config show Dhcp4</userinput>
Dhcp4/interface/ list (default)
Dhcp4/renew-timer 1000 integer (default)
Dhcp4/rebind-timer 2000 integer (default)
Dhcp4/preferred-lifetime 3000 integer (default)
Dhcp4/valid-lifetime 4000 integer (default)
Dhcp4/subnet4 [] list (default)</screen>
</para>
<para>
To change one of the parameters, simply follow
the usual <command>bindctl</command> procedure. For example, to make the
leases longer, change their valid-lifetime parameter:
<screen>
&gt; <userinput>config set Dhcp4/valid-lifetime 7200</userinput>
&gt; <userinput>config commit</userinput></screen>
Please note that most Dhcp4 parameters are of global scope
and apply to all defined subnets, unless they are overridden on a
per-subnet basis.
</para>
<para>
The essential role of DHCPv4 server is address assignment. The server
has to be configured with at least one subnet and one pool of dynamic
addresses to be managed. For example, assume that the server
is connected to a network segment that uses the 192.0.2.0/24
prefix. The Administrator of that network has decided that addresses from range
192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4
server. Such a configuration can be achieved in the following way:
<screen>
&gt; <userinput>config add Dhcp4/subnet4</userinput>
&gt; <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
&gt; <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
&gt; <userinput>config commit</userinput></screen>
Note that subnet is defined as a simple string, but the pool parameter
is actually a list of pools: for this reason, the pool definition is
enclosed in square brackets, even though only one range of addresses
is specified.</para>
<para>It is possible to define more than one pool in a
subnet: continuing the previous example, further assume that
192.0.2.64/26 should be also be managed by the server. It could be written as
192.0.2.64 to 192.0.2.127. Alternatively, it can be expressed more simply as
192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the pool list.
For example, one could define the following pools:
<screen>
&gt; <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ]</userinput>
&gt; <userinput>config commit</userinput></screen>
The number of pools is not limited, but for performance reasons it is recommended to
use as few as possible. Space and tabulations in pool definitions are ignored, so
spaces before and after hyphen are optional. They can be used to improve readability.
</para>
<para>
At this stage of development, the only way to alter the server
configuration is to modify its source code. To do so, please
edit src/bin/dhcp4/dhcp4_srv.cc file and modify following
parameters and recompile:
The server may be configured to serve more than one subnet. To add a second subnet,
use a command similar to the following:
<screen>
&gt; <userinput>config add Dhcp4/subnet4</userinput>
&gt; <userinput>config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24"</userinput>
&gt; <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput>
&gt; <userinput>config commit</userinput></screen>
Arrays are counted from 0. subnet[0] refers to the subnet defined in the
previous example. The <command>config add Dhcp4/subnet4</command> adds
another (second) subnet. It can be referred to as
<command>Dhcp4/subnet4[1]</command>. In this example, we allow server to
dynamically assign all addresses available in the whole subnet.
</para>
<para>
When configuring a DHCPv4 server using prefix/length notation, please pay
attention to the boundary values. When specifying that the server should use
a given pool, it will be able to allocate also first (typically network
address) and the last (typically broadcast address) address from that pool.
In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and
192.0.3.255 addresses may be assigned as well. This may be invalid in some
network configurations. If you want to avoid this, please use min-max notation.
</para>
<para>
Note: Although configuration is now accepted, it is not internally used
by they server yet. At this stage of development, the only way to alter
server configuration is to modify its source code. To do so, please edit
src/bin/dhcp6/dhcp4_srv.cc file, modify the following parameters and
recompile:
<screen>
const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease
const std::string HARDCODED_NETMASK = "255.255.255.0";
@@ -2769,7 +2847,7 @@ const std::string HARDCODED_DNS_SERVER = "192.0.2.2";
const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";
const std::string HARDCODED_SERVER_ID = "192.0.2.1";</screen>
Lease database and configuration support is planned for 2012.
Lease database and configuration support is planned for end of 2012.
</para>
</section>

70
src/bin/dhcp4/dhcp4.dox Normal file
View File

@@ -0,0 +1,70 @@
/**
@page dhcp4 DHCPv4 Server Component
BIND10 offers DHCPv4 server implementation. It is implemented as
b10-dhcp4 component. Its primary code is located in
isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively,
especially isc::dhcp::Pkt4, 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.
DHCPv4 server component does not support direct traffic (relayed
only), as support for transmission to hosts without IPv4 address
assigned is not implemented in IfaceMgr yet.
DHCPv4 server component does not use BIND10 logging yet.
@section dhcp4-session BIND10 message queue integration
DHCPv4 server component is now integrated with BIND10 message queue.
The integration is performed by establishSession() and disconnectSession()
functions in isc::dhcp::ControlledDhcpv4Srv class. main() method deifined
in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
class that establishes connection with msgq and install necessary handlers
for receiving commands and configuration updates. It is derived from
a base isc::dhcp::Dhcpv4Srv class that implements DHCPv4 server functionality,
without any controlling mechanisms.
ControlledDhcpv4Srv instantiates several components to make management
session possible. In particular, isc::cc::Session cc_session
object uses ASIO for establishing connection. It registers its socket
in isc::asiolink::IOService io_service object. Typically, other components
(e.g. auth or resolver) that use ASIO for their communication, register their
other sockets in the
same io_service and then just call io_service.run() method that does
not return, until one of the callback decides that it is time to shut down
the whole component cal calls io_service.stop(). DHCPv4 works in a
different way. It does receive messages using select()
(see isc::dhcp::IfaceMgr::receive4()), which is incompatible with ASIO.
To solve this problem, socket descriptor is extracted from cc_session
object and is passed to IfaceMgr by using isc::dhcp::IfaceMgr::set_session_socket().
IfaceMgr then uses this socket in its select() call. If there is some
data to be read, it calls registered callback that is supposed to
read and process incoming data.
This somewhat complicated approach is needed for a simple reason. In
embedded deployments there will be no message queue. Not referring directly
to anything related to message queue in isc::dhcp::Dhcpv4Srv and
isc::dhcp::IfaceMgr classes brings in two benefits. First, the can
be used with and without message queue. Second benefit is related to the
first one: \ref libdhcp is supposed to be simple and robust and not require
many dependencies. One notable example of a use case that benefits from
this approach is a perfdhcp tool. Finally, the idea is that it should be
possible to instantiate Dhcpv4Srv object directly, thus getting a server
that does not support msgq. That is useful for embedded environments.
It may also be useful in validation.
@section dhcp4-config-parser Configuration Parser in DHCPv4
This parser follows exactly the same logic as its DHCPv6 counterpart.
See \ref dhcp6-config-parser.
@section dhcp4-config-inherit DHCPv4 configuration inheritance
Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
counterpart. See \ref dhcp6-config-inherit.
*/

10
src/bin/dhcp6/dhcp6.dox
View File

@@ -1,5 +1,5 @@
/**
@page dhcpv6 DHCPv6 Server Component
@page dhcp6 DHCPv6 Server Component
BIND10 offers DHCPv6 server implementation. It is implemented as
b10-dhcp6 component. Its primary code is located in
@@ -16,13 +16,13 @@
DHCPv6 server component does not use BIND10 logging yet.
@section dhcpv6-session BIND10 message queue integration
@section dhcp6-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
@section dhcp6-config-parser Configuration Parser in DHCPv6
b10-dhcp6 component uses BIND10 cfgmgr for commands and configuration. During
initial configuration (See \ref
@@ -49,7 +49,7 @@
elements and creates parsers for a given scope. This process may be repeated
(sort of) recursively.
@section dhcpv6-config-inherit DHCPv6 Configuration Inheritance
@section dhcp6-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
@@ -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