BIND 10 trac3180, updated. ff3ddd8332fbaab5ff76f140ae9f185a2d2d6e34 [3180] Updated Developer Guide with an info about option parsing callbacks.
BIND 10 source code commits
bind10-changes at lists.isc.org
Mon Oct 7 09:31:30 UTC 2013
The branch, trac3180 has been updated
via ff3ddd8332fbaab5ff76f140ae9f185a2d2d6e34 (commit)
via 0fcc98b098d285dddcbdc73a06c38aeb826cb16a (commit)
via b054ce924f26fba021c4ab86bd663d9acaa6ae34 (commit)
from d06b0d68f9d91b363183fe86a3d8ce9e46eb37f7 (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 ff3ddd8332fbaab5ff76f140ae9f185a2d2d6e34
Author: Marcin Siodelski <marcin at isc.org>
Date: Mon Oct 7 11:30:53 2013 +0200
[3180] Updated Developer Guide with an info about option parsing callbacks.
commit 0fcc98b098d285dddcbdc73a06c38aeb826cb16a
Author: Marcin Siodelski <marcin at isc.org>
Date: Mon Oct 7 10:56:03 2013 +0200
[3180] Fixed doxygen errors in OptionDefinition.
commit b054ce924f26fba021c4ab86bd663d9acaa6ae34
Author: Marcin Siodelski <marcin at isc.org>
Date: Mon Oct 7 10:47:03 2013 +0200
[3180] Test that unpackOptions works properly for Dhcpv4Srv.
-----------------------------------------------------------------------
Summary of changes:
doc/devel/mainpage.dox | 2 +
src/bin/dhcp4/dhcp4.dox | 7 ++-
src/bin/dhcp4/dhcp4_srv.h | 4 +-
src/bin/dhcp4/tests/dhcp4_srv_unittest.cc | 98 +++++++++++++++++++++++++----
src/bin/dhcp6/dhcp6.dox | 23 +++++++
src/lib/dhcp/option_definition.h | 15 +++++
6 files changed, 134 insertions(+), 15 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index 2b1ea8d..97b722a 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -53,12 +53,14 @@
* - @subpage dhcpv4Session
* - @subpage dhcpv4ConfigParser
* - @subpage dhcpv4ConfigInherit
+ * - @subpage dhcpv4OptionsParse
* - @subpage dhcpv4Other
* - @subpage dhcp6
* - @subpage dhcpv6Session
* - @subpage dhcpv6ConfigParser
* - @subpage dhcpv6ConfigInherit
* - @subpage dhcpv6DDNSIntegration
+ * - @subpage dhcpv6OptionsParse
* - @subpage dhcpv6Other
* - @subpage libdhcp
* - @subpage libdhcpIntro
diff --git a/src/bin/dhcp4/dhcp4.dox b/src/bin/dhcp4/dhcp4.dox
index bd490fb..b77ac24 100644
--- a/src/bin/dhcp4/dhcp4.dox
+++ b/src/bin/dhcp4/dhcp4.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2013 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
@@ -79,6 +79,11 @@ See \ref dhcpv6ConfigParser.
Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
counterpart. See \ref dhcpv6ConfigInherit.
+ at section dhcpv4OptionsParse Custom functions to parse message options
+
+The DHCPv4 server uses the same logic to supply custom callback function to
+parse message option as DHCPv6 server implementation. See \ref dhcpv6OptionsParse.
+
@section dhcpv4Other Other DHCPv4 topics
For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
diff --git a/src/bin/dhcp4/dhcp4_srv.h b/src/bin/dhcp4/dhcp4_srv.h
index 32f1c6e..5c89c85 100644
--- a/src/bin/dhcp4/dhcp4_srv.h
+++ b/src/bin/dhcp4/dhcp4_srv.h
@@ -349,8 +349,6 @@ protected:
/// simulates transmission of a packet. For that purpose it is protected.
virtual void sendPacket(const Pkt4Ptr& pkt);
-private:
-
/// @brief Implements a callback function to parse options in the message.
///
/// @param buf a A buffer holding options in on-wire format.
@@ -363,6 +361,8 @@ private:
const std::string& option_space,
isc::dhcp::OptionCollection& options);
+private:
+
/// @brief Constructs netmask option based on subnet4
/// @param subnet subnet for which the netmask will be calculated
///
diff --git a/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc b/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc
index 0abeb10..2b33630 100644
--- a/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc
+++ b/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc
@@ -22,6 +22,7 @@
#include <dhcp/option.h>
#include <dhcp/option4_addrlst.h>
#include <dhcp/option_custom.h>
+#include <dhcp/option_int.h>
#include <dhcp/option_int_array.h>
#include <dhcp/pkt_filter.h>
#include <dhcp/pkt_filter_inet.h>
@@ -147,6 +148,7 @@ public:
using Dhcpv4Srv::writeServerID;
using Dhcpv4Srv::sanityCheck;
using Dhcpv4Srv::srvidToString;
+ using Dhcpv4Srv::unpackOptions;
};
static const char* SRVID_FILE = "server-id-test.txt";
@@ -1658,21 +1660,93 @@ TEST_F(Dhcpv4SrvTest, Hooks) {
EXPECT_TRUE(hook_index_buffer4_send > 0);
}
- // a dummy MAC address
- const uint8_t dummyMacAddr[] = {0, 1, 2, 3, 4, 5};
+// This test verifies that the following option structure can be parsed:
+// - option (option space 'foobar')
+// - sub option (option space 'foo')
+// - sub option (option space 'bar')
+TEST_F(Dhcpv4SrvTest, unpackOptions) {
+ // Create option definition for each level of encapsulation. Each option
+ // definition is for the option code 1. Options may have the same
+ // option code because they belong to different option spaces.
+
+ // Top level option encapsulates options which belong to 'space-foo'.
+ OptionDefinitionPtr opt_def(new OptionDefinition("option-foobar", 1, "uint32",
+ "space-foo"));\
+ // Middle option encapsulates options which belong to 'space-bar'
+ OptionDefinitionPtr opt_def2(new OptionDefinition("option-foo", 1, "uint16",
+ "space-bar"));
+ // Low level option doesn't encapsulate any option space.
+ OptionDefinitionPtr opt_def3(new OptionDefinition("option-bar", 1,
+ "uint8"));
+
+ // Add option definitions to the Configuration Manager. Each goes under
+ // different option space.
+ CfgMgr& cfgmgr = CfgMgr::instance();
+ ASSERT_NO_THROW(cfgmgr.addOptionDef(opt_def, "space-foobar"));
+ ASSERT_NO_THROW(cfgmgr.addOptionDef(opt_def2, "space-foo"));
+ ASSERT_NO_THROW(cfgmgr.addOptionDef(opt_def3, "space-bar"));
+
+ // Create the buffer holding the structure of options.
+ const char raw_data[] = {
+ // First option starts here.
+ 0x01, // option code = 1
+ 0x0B, // option length = 11
+ 0x00, 0x01, 0x02, 0x03, // This option carries uint32 value
+ // Sub option starts here.
+ 0x01, // option code = 1
+ 0x05, // option length = 5
+ 0x01, 0x02, // this option carries uint16 value
+ // Last option starts here.
+ 0x01, // option code = 1
+ 0x01, // option length = 1
+ 0x00 // This option carries a single uint8
+ // value and has no sub options.
+ };
+ OptionBuffer buf(raw_data, raw_data + sizeof(raw_data));
+
+ // Parse options.
+ NakedDhcpv4Srv srv(0);
+ OptionCollection options;
+ ASSERT_NO_THROW(srv.unpackOptions(buf, "space-foobar", options));
+
+ // There should be one top level option.
+ ASSERT_EQ(1, options.size());
+ boost::shared_ptr<OptionInt<uint32_t> > option_foobar =
+ boost::dynamic_pointer_cast<OptionInt<uint32_t> >(options.begin()->
+ second);
+ ASSERT_TRUE(option_foobar);
+ EXPECT_EQ(1, option_foobar->getType());
+ EXPECT_EQ(0x00010203, option_foobar->getValue());
+ // There should be a middle level option held in option_foobar.
+ boost::shared_ptr<OptionInt<uint16_t> > option_foo =
+ boost::dynamic_pointer_cast<OptionInt<uint16_t> >(option_foobar->
+ getOption(1));
+ ASSERT_TRUE(option_foo);
+ EXPECT_EQ(1, option_foo->getType());
+ EXPECT_EQ(0x0102, option_foo->getValue());
+ // Finally, there should be a low level option under option_foo.
+ boost::shared_ptr<OptionInt<uint8_t> > option_bar =
+ boost::dynamic_pointer_cast<OptionInt<uint8_t> >(option_foo->getOption(1));
+ ASSERT_TRUE(option_bar);
+ EXPECT_EQ(1, option_bar->getType());
+ EXPECT_EQ(0x0, option_bar->getValue());
+}
+
+// a dummy MAC address
+const uint8_t dummyMacAddr[] = {0, 1, 2, 3, 4, 5};
- // A dummy MAC address, padded with 0s
- const uint8_t dummyChaddr[16] = {0, 1, 2, 3, 4, 5, 0, 0,
- 0, 0, 0, 0, 0, 0, 0, 0 };
+// A dummy MAC address, padded with 0s
+const uint8_t dummyChaddr[16] = {0, 1, 2, 3, 4, 5, 0, 0,
+ 0, 0, 0, 0, 0, 0, 0, 0 };
- // Let's use some creative test content here (128 chars + \0)
- const uint8_t dummyFile[] = "Lorem ipsum dolor sit amet, consectetur "
- "adipiscing elit. Proin mollis placerat metus, at "
- "lacinia orci ornare vitae. Mauris amet.";
+// Let's use some creative test content here (128 chars + \0)
+const uint8_t dummyFile[] = "Lorem ipsum dolor sit amet, consectetur "
+ "adipiscing elit. Proin mollis placerat metus, at "
+ "lacinia orci ornare vitae. Mauris amet.";
- // Yet another type of test content (64 chars + \0)
- const uint8_t dummySname[] = "Lorem ipsum dolor sit amet, consectetur "
- "adipiscing elit posuere.";
+// Yet another type of test content (64 chars + \0)
+const uint8_t dummySname[] = "Lorem ipsum dolor sit amet, consectetur "
+ "adipiscing elit posuere.";
/// @brief a class dedicated to Hooks testing in DHCPv4 server
///
diff --git a/src/bin/dhcp6/dhcp6.dox b/src/bin/dhcp6/dhcp6.dox
index 4cdea53..7684f53 100644
--- a/src/bin/dhcp6/dhcp6.dox
+++ b/src/bin/dhcp6/dhcp6.dox
@@ -167,6 +167,29 @@ Once the configuration is implemented, these constants will be removed.
@todo Add section about setting up options and their definitions with bindctl.
+ at section dhcpv6OptionsParse Custom functions to parse message options
+
+The DHCPv6 server implementation provides a generic support to define option
+formats and set option values. A number of options formats have been defined
+for standard options in libdhcp++. However, the formats for vendor specific
+options are dynamically configured by the server's administrator and thus can't
+be stored in libdhcp++. Such option formats are stored in the
+ at c isc::dhcp::CfgMgr. The libdhcp++ provides functions for recursive parsing
+of options which may be encapsulated by other options up to the any level of
+encapsulation but these functions are unaware of the option formats defined
+in the @c isc::dhcp::CfgMgr because they belong to a different library.
+Therefore, the generic functions @c isc::dhcp::LibDHCP::unpackOptions4 and
+ at c isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
+options which definitions are provided in the libdhcp++. In order to overcome
+this problem a callback mechanism has been implemented in @c Option and @c Pkt6
+classes. By installing a callback function on the instance of the @c Pkt6 the
+server may provide a custom implementation of the options parsing algorithm.
+This callback function will take precedence over the @c LibDHCP::unpackOptions6
+and @c LibDHCP::unpackOptions4 functions. With this approach, the callback is
+implemented within the context of the server and it has access to all objects
+which define its configuration (including dynamically created option
+definitions).
+
@section dhcpv6Other Other DHCPv6 topics
For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
diff --git a/src/lib/dhcp/option_definition.h b/src/lib/dhcp/option_definition.h
index cc8b495..878abeb 100644
--- a/src/lib/dhcp/option_definition.h
+++ b/src/lib/dhcp/option_definition.h
@@ -310,6 +310,10 @@ public:
/// @param type option type.
/// @param begin beginning of the option buffer.
/// @param end end of the option buffer.
+ /// @param callback An instance of the function which parses packet options.
+ /// If this is set to non NULL value this function will be used instead of
+ /// @c isc::dhcp::LibDHCP::unpackOptions6 and
+ /// isc::dhcp::LibDHCP::unpackOptions4.
///
/// @return instance of the DHCP option.
/// @throw InvalidOptionValue if data for the option is invalid.
@@ -331,6 +335,10 @@ public:
/// @param u option universe (V4 or V6).
/// @param type option type.
/// @param buf option buffer.
+ /// @param callback An instance of the function which parses packet options.
+ /// If this is set to non NULL value this function will be used instead of
+ /// @c isc::dhcp::LibDHCP::unpackOptions6 and
+ /// isc::dhcp::LibDHCP::unpackOptions4.
///
/// @return instance of the DHCP option.
/// @throw InvalidOptionValue if data for the option is invalid.
@@ -439,8 +447,15 @@ public:
///
/// @param u universe (V4 or V6).
/// @param type option type.
+ /// @param encapsulated_space An option space being encapsulated by the
+ /// options created by this factory function. The options which belong to
+ /// encapsulated option space are sub options of this option.
/// @param begin iterator pointing to the beginning of the buffer.
/// @param end iterator pointing to the end of the buffer.
+ /// @param callback An instance of the function which parses packet options.
+ /// If this is set to non NULL value this function will be used instead of
+ /// @c isc::dhcp::LibDHCP::unpackOptions6 and
+ /// isc::dhcp::LibDHCP::unpackOptions4.
/// @tparam T type of the data field (must be one of the uintX_t or intX_t).
///
/// @throw isc::OutOfRange if provided option buffer length is invalid.
More information about the bind10-changes
mailing list