BIND 10 trac3251, updated. 26ec9c66db6d73c45d59ce731d05d91c75674890 [3251] Added section to developer guide about packet filters in DHCPv6.

[BIND 10 source code commits]

The branch, trac3251 has been updated
       via  26ec9c66db6d73c45d59ce731d05d91c75674890 (commit)
      from  b173ea75b749984a94830c81ad6834f42387f8ba (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 26ec9c66db6d73c45d59ce731d05d91c75674890
Author: Marcin Siodelski <marcin at isc.org>
Date:   Fri Dec 13 11:19:12 2013 +0100

    [3251] Added section to developer guide about packet filters in DHCPv6.

-----------------------------------------------------------------------

Summary of changes:
 doc/devel/mainpage.dox     |    1 +
 src/lib/dhcp/libdhcp++.dox |   45 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

-----------------------------------------------------------------------
diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index 4110b26..88b7e54 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -72,6 +72,7 @@
  *   - @subpage libdhcpRelay
  *   - @subpage libdhcpIfaceMgr
  *   - @subpage libdhcpPktFilter
+ *   - @subpage libdhcpPktFilter6
  * - @subpage libdhcpsrv
  *   - @subpage leasemgr
  *   - @subpage cfgmgr
diff --git a/src/lib/dhcp/libdhcp++.dox b/src/lib/dhcp/libdhcp++.dox
index 6397a4b..8ec0ea1 100644
--- a/src/lib/dhcp/libdhcp++.dox
+++ b/src/lib/dhcp/libdhcp++.dox
@@ -184,5 +184,50 @@ the regular IP/UDP socket. The isc::dhcp::PktFilterInet should be used in all
 cases when an application using the libdhcp++ doesn't require sending
 DHCP messages to a device which doesn't have an address yet.
 
+ at section libdhcpPktFilter6 Switchable Packet Filters for DHCPv6
+
+The DHCPv6 implementation doesn't suffer from the problems described in \ref
+libdhcpPktFilter. Therefore, the socket creation and methods used to send
+and receive DHCPv6 messages are common for all OSes. However, there is
+still a need to customize the operations on the sockets to reliably unit test
+the \ref isc::dhcp::IfaceMgr logic.
+
+The \ref isc::dhcp::IfaceMgr::openSockets6 function examines configuration
+of detected interfaces for their availability to listen DHCPv6 traffic. For
+all running interfaces (except local loopback) it will try to open a socket
+and bind it to the link local or global unicast address. The socket will
+not be opened on the interface which is down or for which it was explicitly
+specified that it should not be used to listen to DHCPv6 messages. There is
+a substantial amount of logic in this function that has to be unit tested for
+various interface configurations, e.g.:
+- multiple interfaces with link-local addresses only
+- multiple interfaces, some of them having global unicast addresses,
+- multiple interfaces, some of them disabled
+- no interfaces
+
+The \ref isc::dhcp::IfaceMgr::openSockets6 function attempts to open
+sockets on detected interfaces. At the same time, the number of interfaces,
+and their configuration is specific to OS where the tests are being run.
+So the test doesn't have any means to configure interfaces for the test case
+being run. Moreover, a unit test should not change the configuration of the
+system. For example, a change to the configuration of the interface which
+is used to access the machine running a test, may effectively break the
+access to this machine.
+
+In order to overcome the problem described above, the unit tests use
+fake interfaces which can be freely added, configured and removed from the
+\ref isc::dhcp::IfaceMgr. Obviously, it is not possible to open a socket
+on a fake interface, nor use it to send or receive IP packets. To mimic
+socket operations on fake interfaces it is required that the functions
+which open sockets, send messages and receive messages have to be
+customizable. This is achieved by implementation of replaceable packet
+filter objects which derive from the \ref isc::dhcp::PktFilter6 class.
+The default implementation of this class is \ref isc::dhcp::PktFilterInet6
+which creates a regular datagram IPv6/UDPv6 socket. The unit tests use a
+stub implementation isc::dhcp::test::PktFilter6Stub which contains no-op
+functions.
+
+Use \ref isc::dhcp::IfaceMgr::setPacketFilter function to set the custom packet
+filter object to be used by Interface Manager.
 
 */