BIND 10 trac1531, updated. 21c1954e0e26413c1110f68d2b7c730ae79c3d44 [1531] Several developer documentation updates:
BIND 10 source code commits
bind10-changes at lists.isc.org
Mon Mar 19 13:54:42 UTC 2012
The branch, trac1531 has been updated
via 21c1954e0e26413c1110f68d2b7c730ae79c3d44 (commit)
from 4b7786c01f7cc727ae9e36b3808bf727022e562e (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 21c1954e0e26413c1110f68d2b7c730ae79c3d44
Author: Tomek Mrugalski <tomasz at isc.org>
Date: Mon Mar 19 14:54:18 2012 +0100
[1531] Several developer documentation updates:
- Added make devel target in doc directory.
- Doxygen warnings/errors are now part of the Developer's guide itself.
- renamed mainpage.dox file
- Added extra information to main page
- Extended libdhcp++ descriptions
- Added doc/.gitignore to ignore doc/html (potentially 1000s of files)
-----------------------------------------------------------------------
Summary of changes:
doc/.gitignore | 1 +
doc/Doxyfile | 2 +-
doc/Makefile.am | 4 +-
doc/devel/00-mainpage.dox | 28 -----------
doc/devel/02-dhcp.dox | 119 ++++++++++++++++++++++++++++++++++++++------
doc/devel/mainpage.dox | 35 +++++++++++++
doc/images/isc-logo.png | Bin 0 -> 12595 bytes
7 files changed, 141 insertions(+), 48 deletions(-)
create mode 100644 doc/.gitignore
delete mode 100644 doc/devel/00-mainpage.dox
create mode 100644 doc/devel/mainpage.dox
create mode 100644 doc/images/isc-logo.png
-----------------------------------------------------------------------
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..1936cc1
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+html
diff --git a/doc/Doxyfile b/doc/Doxyfile
index 3b9e9f2..d7706d2 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -652,7 +652,7 @@ EXAMPLE_RECURSIVE = NO
# directories that contain image that are included in the documentation (see
# the \image command).
-IMAGE_PATH =
+IMAGE_PATH = ../doc/images
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c18d198..833a56c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,9 +5,9 @@ EXTRA_DIST = version.ent.in
devel:
mkdir -p html
doxygen Doxyfile > html/doxygen.log 2> html/doxygen-error.log
- echo "`wc -l html/doxygen-error.log` errors detected."
+ echo "`wc -l html/doxygen-error.log` warnings/errors detected."
-# That's a bit of a hack, but we are makeing sure that devel target
+# That's a bit of a hack, but we are making sure that devel target
# is always valid. The alternative is to make devel depend on all
# *.cc *.h files in the whole tree.
.PHONY: devel
diff --git a/doc/devel/00-mainpage.dox b/doc/devel/00-mainpage.dox
deleted file mode 100644
index 1ebda2b..0000000
--- a/doc/devel/00-mainpage.dox
+++ /dev/null
@@ -1,28 +0,0 @@
-/**
- *
- * @mainpage BIND10 Developer's Guide
- *
- * Welcome to BIND10 Developer's Guide. This documentation is addressed
- * at existing and prospecting developers and programmers, who would like
- * to gain insight into internal workings of BIND 10.
- *
- * If you are a user or system administrator, rather than software engineer,
- * you should read BIND10 Guide instead.
- *
- * @section DNS
- * - @subpage DataScrubbing
- * @section DHCP
-
- * - @subpage dhcpv4
- * - @subpage dhcpv6
- * - @subpage libdhcp
- *
- * @section Miscellaneous topics
- * - @subpage LoggingApi
- * - @subpage LoggingApiOverview
- * - @subpage LoggingApiLoggerNames
- * - @subpage LoggingApiLoggingMessages
- * - @subpage SocketSessionUtility
- *
- * <a href="./doxygen-error.log">Documentation warnings and errors</a>
- */
\ No newline at end of file
diff --git a/doc/devel/02-dhcp.dox b/doc/devel/02-dhcp.dox
index d0a2a6b..7ebd9b2 100644
--- a/doc/devel/02-dhcp.dox
+++ b/doc/devel/02-dhcp.dox
@@ -1,32 +1,117 @@
/**
- * @page dhcpv4 DHCPv4 Component
+ * @page dhcpv4 DHCPv4 Server Component
*
- * BIND10 offers DHCPv4 server implementation. It is implemented as b10-dhcp4 component.
- * It's 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.
+ * 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.
*
- * @todo Describe DHCPv4 component properly.
- *
- * @page dhcpv6 DHCPv6 Component
+ * 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 listen to BIND10 message queue.
+ *
+ * DHCPv4 server component does not use BIND10 logging yet.
+ *
+ * DHCPv4 server component is not integrated with boss yet.
+ *
+ * @page dhcpv6 DHCPv6 Server Component
+ *
+ * BIND10 offers DHCPv6 server implementation. It is implemented as
+ * b10-dhcp6 component. Its primary code is located in
+ * isc::dhcp::Dhcpv6Srv class. It uses \ref libdhcp extensively,
+ * especially lib::dhcp::Pkt6, 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.
+ *
+ * DHCPv6 server component does not support relayed traffic yet, as
+ * support for relay decapsulation is not implemented yet.
+ *
+ * DHCPv6 server component does not listen to BIND10 message queue.
+ *
+ * DHCPv6 server component does not use BIND10 logging yet.
+ *
+ * DHCPv6 server component is not integrated with boss yet.
*
- * @todo DHCPv6 component will be described here.
- *
* @page libdhcp libdhcp++ library
*
* @section libdhcpIntro Libdhcp++ Introduction
*
- * libdhcp++ is an all-purpose DHCP-manipulation library, written in C++. It offers packet
- * parsing and assembly, DHCPv4 and DHCPv6 options parsing and assembly, interface detection
- * (currently on Linux systems only) and socket operations. Following classes are implemented:
+ * 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 lidhcpIfaceMgr 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().
- * Another useful methods are dedicated to transmission (isc::dhcp::IfaceMgr::send(), 2 overloads)
- * and reception (isc::dhcp::IfaceMgr::receive4() and isc::dhcp::IfaceMgr::receive6()).
+ * 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
diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
new file mode 100644
index 0000000..fd14a44
--- /dev/null
+++ b/doc/devel/mainpage.dox
@@ -0,0 +1,35 @@
+/**
+ *
+ * @mainpage BIND10 Developer's Guide
+ *
+ * Welcome to BIND10 Developer's Guide. This documentation is addressed
+ * at existing and prospecting developers and programmers, who would like
+ * to gain insight into internal workings of BIND 10. It could also be useful
+ * for existing and prospective contributors.
+ *
+ * If you are a user or system administrator, rather than software engineer,
+ * you should read BIND10 Guide (Administrator Reference for BIND10) instead.
+ *
+ * Regardless of your field of expertise, you are encouraged to visit
+ * <a href="http://bind10.isc.org/">BIND10 webpage (http://bind10.isc.org)</a>
+ *
+ * @section DNS
+ * - @subpage DataScrubbing
+ *
+ * @section DHCP
+ * - @subpage dhcpv4
+ * - @subpage dhcpv6
+ * - @subpage libdhcp
+ *
+ * @section misc Miscellaneous topics
+ * - @subpage LoggingApi
+ * - @subpage LoggingApiOverview
+ * - @subpage LoggingApiLoggerNames
+ * - @subpage LoggingApiLoggingMessages
+ * - @subpage SocketSessionUtility
+ * - <a href="./doxygen-error.log">Documentation warnings and errors</a>
+ *
+ * @todo: Move this logo to the right (and possibly up). Not sure what
+ * is the best way to do it in Doxygen, without using CSS hacks.
+ * @image html isc-logo.png
+ */
\ No newline at end of file
diff --git a/doc/images/isc-logo.png b/doc/images/isc-logo.png
new file mode 100644
index 0000000..1f7af96
Binary files /dev/null and b/doc/images/isc-logo.png differ
More information about the bind10-changes
mailing list