[2270] Documentation for DHCPv4 config. parser written.

doc/devel/02-dhcp.dox

@@ -1,62 +1,4 @@
 /**
- * @page dhcpv4 DHCPv4 Server Component
- *
- * 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.
- *
- * 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 use BIND10 logging yet.
- *
- * @section dhcpv4Session BIND10 message queue integration
- *
- * DHCPv4 server component is now integrated with BIND10 message queue.
- * The integration is performed by establishSession() and disconnectSession()
- * functions in isc::dhcp::ControlledDhcpv4Srv class. main() method deifined
- * in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
- * class that establishes connection with msgq and install necessary handlers
- * for receiving commands and configuration updates. It is derived from
- * a base isc::dhcp::Dhcpv4Srv class that implements DHCPv4 server functionality,
- * without any controlling mechanisms.
- *
- * ControlledDhcpv4Srv instantiates several components to make management
- * session possible. In particular, isc::cc::Session cc_session
- * object uses ASIO for establishing connection. It registers its socket
- * in isc::asiolink::IOService io_service object. Typically, other components
- * (e.g. auth or resolver) that use ASIO for their communication, register their
- * other sockets in the
- * same io_service and then just call io_service.run() method that does
- * not return, until one of the callback decides that it is time to shut down
- * the whole component cal calls io_service.stop(). DHCPv4 works in a
- * different way. It does receive messages using select()
- * (see isc::dhcp::IfaceMgr::receive4()), which is incompatible with ASIO.
- * To solve this problem, socket descriptor is extracted from cc_session
- * object and is passed to IfaceMgr by using isc::dhcp::IfaceMgr::set_session_socket().
- * IfaceMgr then uses this socket in its select() call. If there is some
- * data to be read, it calls registered callback that is supposed to
- * read and process incoming data.
- *
- * This somewhat complicated approach is needed for a simple reason. In
- * embedded deployments there will be no message queue. Not referring directly
- * to anything related to message queue in isc::dhcp::Dhcpv4Srv and
- * isc::dhcp::IfaceMgr classes brings in two benefits. First, the can
- * be used with and without message queue. Second benefit is related to the
- * first one: \ref libdhcp is supposed to be simple and robust and not require
- * many dependencies. One notable example of a use case that benefits from
- * this approach is a perfdhcp tool. Finally, the idea is that it should be
- * possible to instantiate Dhcpv4Srv object directly, thus getting a server
- * that does not support msgq. That is useful for embedded environments.
- * It may also be useful in validation.
- *
  * @page libdhcp libdhcp++
  *
  * @section libdhcpIntro Libdhcp++ Library Introduction

doc/devel/mainpage.dox

@@ -20,12 +20,14 @@
  * - @subpage DataScrubbing
  *
  * @section DHCP
- * - @subpage dhcpv4
- *   - @subpage dhcpv4Session
- * - @subpage dhcpv6
- *   - @subpage dhcpv6-session
- *   - @subpage dhcpv6-config-parser
- *   - @subpage dhcpv6-config-inherit
+ * - @subpage dhcp4
+ *   - @subpage dhcp4-session
+ *   - @subpage dhcp4-config-parser
+ *   - @subpage dhcp4-config-inherit
+ * - @subpage dhcp6
+ *   - @subpage dhcp6-session
+ *   - @subpage dhcp6-config-parser
+ *   - @subpage dhcp6-config-inherit
  * - @subpage libdhcp
  *   - @subpage libdhcpIntro
  *   - @subpage libdhcpIfaceMgr

doc/guide/bind10-guide.xml

@@ -2750,16 +2750,94 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
     <section id="dhcp4-config">
       <title>DHCPv4 Server Configuration</title>
       <para>
-        The DHCPv4 server does not have a lease database implemented yet
-        nor any support for configuration, so the same set
-        of configuration options (including the same fixed address)
-        will be assigned every time.
+        Once the server is started, it can be configured. To view the
+        current configuration, use the following command in <command>bindctl</command>:
+        <screen>
+&gt; <userinput>config show Dhcp4</userinput></screen>
+        When starting Dhcp4 daemon for the first time, the default configuration
+        will be available. It will look similar to this:
+        <screen>
+&gt; <userinput>config show Dhcp4</userinput>
+Dhcp4/interface/                list    (default)
+Dhcp4/renew-timer        1000   integer	(default)
+Dhcp4/rebind-timer       2000   integer	(default)
+Dhcp4/preferred-lifetime 3000   integer	(default)
+Dhcp4/valid-lifetime	 4000   integer	(default)
+Dhcp4/subnet4	         []     list    (default)</screen>
+      </para>
+
+      <para>
+        To change one of the parameters, simply follow
+        the usual <command>bindctl</command> procedure. For example, to make the
+        leases longer, change their valid-lifetime parameter:
+        <screen>
+&gt; <userinput>config set Dhcp4/valid-lifetime 7200</userinput>
+&gt; <userinput>config commit</userinput></screen>
+        Please note that most Dhcp4 parameters are of global scope
+        and apply to all defined subnets, unless they are overridden on a
+        per-subnet basis.
       </para>
+
       <para>
-        At this stage of development, the only way to alter the server
-        configuration is to modify its source code. To do so, please
-        edit src/bin/dhcp4/dhcp4_srv.cc file and modify following
-        parameters and recompile:
+        The essential role of DHCPv4 server is address assignment. The server
+        has to be configured with at least one subnet and one pool of dynamic
+        addresses to be managed. For example, assume that the server
+        is connected to a network segment that uses the 192.0.2.0/24
+        prefix. The Administrator of that network has decided that addresses from range
+        192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4
+        server. Such a configuration can be achieved in the following way:
+        <screen>
+&gt; <userinput>config add Dhcp4/subnet4</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
+&gt; <userinput>config commit</userinput></screen>
+        Note that subnet is defined as a simple string, but the pool parameter
+        is actually a list of pools: for this reason, the pool definition is
+        enclosed in square brackets, even though only one range of addresses
+        is specified.</para>
+        <para>It is possible to define more than one pool in a
+        subnet: continuing the previous example, further assume that
+        192.0.2.64/26 should be also be managed by the server. It could be written as
+        192.0.2.64 to 192.0.2.127. Alternatively, it can be expressed more simply as
+        192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the pool list.
+        For example, one could define the following pools:
+        <screen>
+&gt; <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10-192.0.2.20", "192.0.2.64/26" ]</userinput>
+&gt; <userinput>config commit</userinput></screen>
+        The number of pools is not limited, but for performance reasons it is recommended to
+        use as few as possible. Space and tabulations in pool definitions are ignored, so
+        spaces before and after hyphen are optional. They can be used to improve readability.
+      </para>
+      <para>
+         The server may be configured to serve more than one subnet. To add a second subnet,
+         use a command similar to the following:
+        <screen>
+&gt; <userinput>config add Dhcp4/subnet4</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[1]/subnet "192.0.3.0/24"</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput>
+&gt; <userinput>config commit</userinput></screen>
+        Arrays are counted from 0. subnet[0] refers to the subnet defined in the
+        previous example.  The <command>config add Dhcp4/subnet4</command> adds
+        another (second) subnet. It can be referred to as
+        <command>Dhcp4/subnet4[1]</command>. In this example, we allow server to
+        dynamically assign all addresses available in the whole subnet.
+      </para>
+      <para>
+        When configuring a DHCPv4 server using prefix/length notation, please pay
+        attention to the boundary values. When specifying that the server should use
+        a given pool, it will be able to allocate also first (typically network
+        address) and the last (typically broadcast address) address from that pool.
+        In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and
+        192.0.3.255 addresses may be assigned as well. This may be invalid in some
+        network configurations. If you want to avoid this, please use min-max notation.
+      </para>
+
+      <para>
+        Note: Although configuration is now accepted, it is not internally used
+        by they server yet.  At this stage of development, the only way to alter
+        server configuration is to modify its source code. To do so, please edit
+        src/bin/dhcp6/dhcp4_srv.cc file, modify the following parameters and
+        recompile:
         <screen>
 const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease
 const std::string HARDCODED_NETMASK = "255.255.255.0";
@@ -2769,7 +2847,7 @@ const std::string HARDCODED_DNS_SERVER = "192.0.2.2";
 const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";
 const std::string HARDCODED_SERVER_ID = "192.0.2.1";</screen>
 
-        Lease database and configuration support is planned for 2012.
+        Lease database and configuration support is planned for end of 2012.
       </para>
     </section>
 

src/bin/dhcp4/dhcp4.dox

@@ -0,0 +1,70 @@
+/**
+ @page dhcp4 DHCPv4 Server Component
+
+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.
+
+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 use BIND10 logging yet.
+
+@section dhcp4-session BIND10 message queue integration
+
+DHCPv4 server component is now integrated with BIND10 message queue.
+The integration is performed by establishSession() and disconnectSession()
+functions in isc::dhcp::ControlledDhcpv4Srv class. main() method deifined
+in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
+class that establishes connection with msgq and install necessary handlers
+for receiving commands and configuration updates. It is derived from
+a base isc::dhcp::Dhcpv4Srv class that implements DHCPv4 server functionality,
+without any controlling mechanisms.
+
+ControlledDhcpv4Srv instantiates several components to make management
+session possible. In particular, isc::cc::Session cc_session
+object uses ASIO for establishing connection. It registers its socket
+in isc::asiolink::IOService io_service object. Typically, other components
+(e.g. auth or resolver) that use ASIO for their communication, register their
+other sockets in the
+same io_service and then just call io_service.run() method that does
+not return, until one of the callback decides that it is time to shut down
+the whole component cal calls io_service.stop(). DHCPv4 works in a
+different way. It does receive messages using select()
+(see isc::dhcp::IfaceMgr::receive4()), which is incompatible with ASIO.
+To solve this problem, socket descriptor is extracted from cc_session
+object and is passed to IfaceMgr by using isc::dhcp::IfaceMgr::set_session_socket().
+IfaceMgr then uses this socket in its select() call. If there is some
+data to be read, it calls registered callback that is supposed to
+read and process incoming data.
+
+This somewhat complicated approach is needed for a simple reason. In
+embedded deployments there will be no message queue. Not referring directly
+to anything related to message queue in isc::dhcp::Dhcpv4Srv and
+isc::dhcp::IfaceMgr classes brings in two benefits. First, the can
+be used with and without message queue. Second benefit is related to the
+first one: \ref libdhcp is supposed to be simple and robust and not require
+many dependencies. One notable example of a use case that benefits from
+this approach is a perfdhcp tool. Finally, the idea is that it should be
+possible to instantiate Dhcpv4Srv object directly, thus getting a server
+that does not support msgq. That is useful for embedded environments.
+It may also be useful in validation.
+
+@section dhcp4-config-parser Configuration Parser in DHCPv4
+
+This parser follows exactly the same logic as its DHCPv6 counterpart.
+See \ref dhcp6-config-parser.
+
+@section dhcp4-config-inherit DHCPv4 configuration inheritance
+
+Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
+counterpart. See \ref dhcp6-config-inherit.
+
+*/

src/bin/dhcp6/dhcp6.dox

@@ -1,5 +1,5 @@
 /**
- @page dhcpv6 DHCPv6 Server Component
+ @page dhcp6 DHCPv6 Server Component
 
  BIND10 offers DHCPv6 server implementation. It is implemented as
  b10-dhcp6 component. Its primary code is located in
@@ -16,13 +16,13 @@
 
  DHCPv6 server component does not use BIND10 logging yet.
 
- @section dhcpv6-session BIND10 message queue integration
+ @section dhcp6-session BIND10 message queue integration
 
  DHCPv4 server component is now integrated with BIND10 message queue.
  It follows the same principle as DHCPv4. See \ref dhcpv4Session for
  details.
 
- @section dhcpv6-config-parser Configuration Parser in DHCPv6
+ @section dhcp6-config-parser Configuration Parser in DHCPv6
 
  b10-dhcp6 component uses BIND10 cfgmgr for commands and configuration. During
  initial configuration (See \ref
@@ -49,7 +49,7 @@
  elements and creates parsers for a given scope. This process may be repeated
  (sort of) recursively.
 
- @section dhcpv6-config-inherit DHCPv6 Configuration Inheritance
+ @section dhcp6-config-inherit DHCPv6 Configuration Inheritance
 
  One notable useful features of DHCP configuration is its parameter inheritance.
  For example, renew-timer value may be specified at a global scope and it then
@@ -64,7 +64,7 @@
  phase (commit() method), appropriate parsers can use apply parameter inheritance.
 
  Debugging configuration parser may be confusing. Therefore there is a special
- class called \ref isc::dhcp::DummyParser. It does not configure anything, but just
+ class called \ref isc::dhcp::DebugParser. It does not configure anything, but just
  accepts any parameter of any type. If requested to commit configuration, it will
  print out received parameter name and its value. This class is not currently used,
  but it is convenient to have it every time a new parameter is added to DHCP