From: Marcin Siodelski Date: Wed, 8 Jul 2015 12:42:49 +0000 (+0200) Subject: [3484] Updated sections of the Developer's Guide concerning libdhcp++. X-Git-Tag: trac4006_base~25^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=96fac8d57e68edceb9fd447cf946675c64a61783;p=thirdparty%2Fkea.git [3484] Updated sections of the Developer's Guide concerning libdhcp++. --- diff --git a/src/lib/dhcp/libdhcp++.dox b/src/lib/dhcp/libdhcp++.dox index 4dfedcfee4..f504dcb7ff 100644 --- a/src/lib/dhcp/libdhcp++.dox +++ b/src/lib/dhcp/libdhcp++.dox @@ -1,4 +1,4 @@ -// Copyright (C) 2012-2014 Internet Systems Consortium, Inc. ("ISC") +// Copyright (C) 2012-2015 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 @@ -31,32 +31,45 @@ The following classes for packet manipulation 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. +The following pointer types are defined: \c Pkt4Ptr and \c Pkt6Ptr. They are +smart pointers using the \c boost::shared_ptr type. There are no const +versions of packet types 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 +Both packet types use collection of \ref isc::dhcp::Option objects to +represent DHCPv4 and DHCPv6 options. The base class @c Option can be used to represent generic option that contains collection of -bytes. Depending on if the option is instantiated as v4 or v6 +bytes. Depending on whether the option is instantiated as DHCPv4 or DHCPv6 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: +There are many specialized classes that are intended to handle options having +specific formats: - 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::Option4ClientFqdn -- DHCPv4 Client FQDN option; +- isc::dhcp::Option6ClientFqdn -- DHCPv6 Client FQDN option; +- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR option (an option that + contains IPv6 address with extra parameters); +- isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents IAPREFIX option (an option + that contains IPv6 prefix in prefix delegation); - 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. +- isc::dhcp::Option6StatusCode -- DHCPv6 option, carries a status code to the client; +- isc::dhcp::OptionCustom -- Represents option having many different formats, where + data fields can be accessed in a convenient way; +- isc::dhcp::OptionInt -- DHCPv4 or DHCPv6 option, carries a single numeric value; +- isc::dhcp::OptionString -- DHCPv4 or DHCPv6 option, carries a text value; +- isc::dhcp::OptionVendor -- DHCPv4 or DHCPv6 option, carries Vendor Specific + Information; +- isc::dhcp::OptionVendorClass -- DHCPv4 or DHCPv6 option, contains vendor class + information. + +Various options can store sub-options (i.e. options that are stored within an +option rather than in a message directly). This functionality is commonly used in +DHCPv6, but is rarely used in DHCPv4. \ref isc::dhcp::Option::addOption(), +\ref isc::dhcp::Option::delOption(), \ref isc::dhcp::Option::getOption() can +be used to add, remove and retrieve sub-options from within an option. @section libdhcpRelay Relay v6 support in Pkt6 @@ -80,7 +93,7 @@ that interface-id in its copy, when sending data back to the client. This will be used by the relay to choose proper interface when forwarding response towards the client. -Pkt6 class has a public Pkt6::relay_info_ field, which is of type Pkt6::RelayInfo. +Pkt6 class has a public \c Pkt6::relay_info_ field, which is of type \c Pkt6::RelayInfo. This is a simple structure that represents the information in each RELAY_FORW or RELAY_REPL message. It is important to understand the order in which the data appear here. Consider the following network: @@ -93,7 +106,7 @@ Client will transmit SOLICIT message. Relay1 will forward it as RELAY_FORW with SOLICIT in it. Relay2 forward it as RELAY_FORW with RELAY_FORW with SOLICIT in it. Finally the third relay will add yet another RELAY_FORW around it. The server will parse the packet and -create Pkt6 object for it. Its relay_info_ will have 3 +create \c Pkt6 object for it. Its relay_info_ will have 3 elements. Packet parsing is done in reverse order, compare to the order the packet traversed in the network. The first element (relay_info_[0]) will represent relay3 information (the "last" relay or @@ -103,40 +116,25 @@ the first relay (relay1) or in other words the one closest to the client. Packets sent by the server must maintain the same encapsulation order. This is easy to do - just copy data from client's message object into -server's response object. See Pkt6::coyRelayInfo for details. +server's response object. See @ref isc::dhcp::Pkt6::RelayInfo for details. @section libdhcpIfaceMgr Interface Manager -Interface Manager (or IfaceMgr) is an abstraction layer about low-level +Interface Manager (or IfaceMgr) is an abstraction layer for 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 and BSD. -There are plans to implement such support for other OSes, but they -remain low priority for now. +network interfaces See @ref isc::dhcp::Iface class and +@ref isc::dhcp::IfaceMgr::detectIfaces() and @ref isc::dhcp::IfaceMgr::getIface(). -Generic parts of the code are isc::dhcp::IfaceMgr class in +Generic parts of the code are @ref 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, iface_mgr_bsd. 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. - Other 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. +(\ref isc::dhcp::IfaceMgr::send(), 2 overloads) and reception +(\ref isc::dhcp::IfaceMgr::receive4() and \ref isc::dhcp::IfaceMgr::receive6()). +Note that \c receive4() and \c receive6() methods may return NULL, e.g. +when timeout is reached or if the DHCP daemon receives a signal. @section libdhcpPktFilter Switchable Packet Filter objects used by Interface Manager