From: Marcin Siodelski <marcin@isc.org>
Date: Tue, 14 Oct 2014 15:01:22 +0000 (+0200)
Subject: [3589] Added a paragraph about CfgOption class into developer's guide.
X-Git-Tag: trac3162a_base~4^2~2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3307c992635fa2c747802a573ca01f7290a68768;p=thirdparty%2Fkea.git

[3589] Added a paragraph about CfgOption class into developer's guide.

This was also suggested in the review.
---

diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index 05c2805cb3..fdf9d20004 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -88,6 +88,7 @@
  * - @subpage libdhcpsrv
  *   - @subpage leasemgr
  *   - @subpage cfgmgr
+ *   - @subpage optionsConfig
  *   - @subpage allocengine
  * - @subpage libdhcp_ddns
  * - @subpage dhcpDatabaseBackends
diff --git a/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox
index 9d68cb4265..246f3e5dc6 100644
--- a/src/lib/dhcpsrv/libdhcpsrv.dox
+++ b/src/lib/dhcpsrv/libdhcpsrv.dox
@@ -81,6 +81,37 @@ one that occurred before it etc.
 the \ref isc::dhcp::SrvConfig object. Kea developers are actively working
 on migrating the other configuration parameters to it.
 
+@section optionsConfig Options Configuration Information
+
+The \ref isc::dhcp::CfgOption object holds a collection of options being
+sent to the client. Since, each subnet comes with a distnict set of
+options, every \ref isc::dhcp::Subnet object holds its own copy of the
+\ref isc::dhcp::CfgOption object with specific options.
+
+The DHCP server also allows for configuration of "global" options
+which are shared by all subnets. The rule here is that if a particular
+option appears in the global options set and the subnet specific options
+set, the subnet specific option takes precedence. The global options
+configuration is held in the dedicated instance of the
+\ref isc::dhcp::CfgOption class. This instance is owned by the
+\ref isc::dhcp::SrvConfig class.
+
+When the new configuration is parsed, the global options are merged into
+the \ref isc::dhcp::CfgOption instances for all subnets. This is
+causing some overhead during the reconfiguration of the server but on
+the other hand it avoids the lookup of options in two places (among
+subnet specific options and global options) during each packet
+processing. Note that the merge of global options to the subnet
+specific options doesn't affect the set of global options but only
+adds copies of global options to the subnet specific options.
+
+One of the benefits of keeping a separate set of global options is
+that there may be cases when the server administrator doesn't specify
+any subnet configuration and only wants global options to be used.
+This is the case, when the DHCP server is used for stateless
+configuration, i.e. client's are not allocated an address or prefix,
+and only stateless configruation is handed out.
+
 @section allocengine Allocation Engine
 
 Allocation Engine (\ref isc::dhcp::AllocEngine) is what its name say - an engine