BIND 10 trac2642, updated. 8765402aa09dbbf42b7cf3e8449a633a850221c4 [2642] Changes to DHCP part of manual based on review comments

BIND 10 source code commits bind10-changes at lists.isc.org
Tue Jan 22 12:26:18 UTC 2013


The branch, trac2642 has been updated
       via  8765402aa09dbbf42b7cf3e8449a633a850221c4 (commit)
      from  83c28cb3836d45e3e1abdc5a53c0d994148d1af2 (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 8765402aa09dbbf42b7cf3e8449a633a850221c4
Author: Stephen Morris <stephen at isc.org>
Date:   Tue Jan 22 12:25:03 2013 +0000

    [2642] Changes to DHCP part of manual based on review comments

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

Summary of changes:
 doc/guide/bind10-guide.xml |  200 +++++++++++++++++++++-----------------------
 1 file changed, 95 insertions(+), 105 deletions(-)

-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index ede91e9..804761e 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -3334,7 +3334,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
     be deployed that facilitate communication between servers and
     clients. Even though principles of both DHCPv4 and DHCPv6 are
     somewhat similar, these are two radically different
-    protocols. BIND 10 offers server implementations, one for DHCPv4
+    protocols. BIND 10 offers two server implementations, one for DHCPv4
     and one for DHCPv6.</para>
     <para>This chapter covers those parts of BIND 10 that are common to
     both servers.  DHCPv4-specific details are covered in <xref linkend="dhcp4"/>,
@@ -3344,9 +3344,11 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
     <section id="dhcp-install-configure">
       <title>DHCP Database Installation and Configuration</title>
       <para>
-      The current version of BIND 10 DHCP stores lease information in a MySQL
-      database.  This section covers the building of BIND 10 with MySQL and the
-      creation of the lease database.
+      BIND 10 DHCP stores its leases in a lease database.  The software has been written in
+      a way that makes it possible to choose which database product should be used to
+      store the lease information.  At present, only support for MySQL is provided, and that support must
+      be explicitly included when BIND 10 is built.  This section covers the building of
+      BIND 10 with MySQL and the creation of the lease database.
       </para>
       <section>
         <title>Install MySQL</title>
@@ -3359,7 +3361,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
         <title>Build and Install BIND 10</title>
         <para>
           Build and install BIND 10 as described in <xref linkend="installation"/>, with
-          the following modification: to enable the MySQL database code, the
+          the following modification: to enable the MySQL database code, at the
           "configure" step (see <xref linkend="configure"/>), specify the location of the
           MySQL configuration program "mysql_config" with the "--with-mysql-config" switch,
           i.e.
@@ -3438,7 +3440,7 @@ $</screen>
       </para>
 
       <para>
-        During start-up the server will detect available network interfaces
+        On start-up, the server will detect available network interfaces
         and will attempt to open UDP sockets on all interfaces that
         are up, running, are not loopback, and have IPv4 address
         assigned.
@@ -3494,15 +3496,23 @@ Dhcp4/subnet4	[]	list	(default)
       <title>Database Configuration</title>
       <para>
       All leases issued by the server are stored in the lease database.  Currently,
-      the only supported database is MySQL, and so the server must be configured to
+      the only supported database is MySQL
+      <footnote>
+      <para>
+      The server comes with an in-memory database ("memfile") configured as the default
+      database. This is used for internal testing and is not supported.  In addition,
+      it does not store lease information on disk: lease information will be lost if the
+      server is restarted. 
+      </para>
+      </footnote>, and so the server must be configured to
       access the correct database with the appropriate credentials.
       </para>
         <note>
             <para>
             Database access information must be configured for the DHCPv4 server, even if
             it has already been configured for the DHCPv6 server.  The servers store their
-            information independently, and the databases used by the server need not be the
-            same.
+            information independently, so each server can use a separate
+            database or both servers can use the same database.
             </para>
         </note>
       <para>
@@ -3517,8 +3527,8 @@ Dhcp4/subnet4	[]	list	(default)
 > <userinput>config set Dhcp4/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
 </screen>
       If the database is located on a different system to the DHCPv4 server, the
-      database host name must also be specified: note however that this configuration
-      may have a severe impact on server performance:
+      database host name must also be specified (although note that this configuration
+      may have a severe impact on server performance):
 <screen>
 > <userinput>config set Dhcp4/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
 </screen>
@@ -3584,7 +3594,7 @@ Dhcp4/subnet4	[]	list	(default)
 > <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput>
 > <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
+        previous example.  The <command>config add Dhcp4/subnet4</command> 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.
@@ -3596,7 +3606,7 @@ Dhcp4/subnet4	[]	list	(default)
         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.
+        network configurations. If you want to avoid this, please use the "min-max" notation.
       </para>
       </section>
     </section>
@@ -3607,11 +3617,11 @@ Dhcp4/subnet4	[]	list	(default)
       supported:</para>
       <itemizedlist>
           <listitem>
-            <simpara>RFC 2131: Supported messages are DISCOVER, OFFER,
-            REQUEST, and ACK.</simpara>
+            <simpara><ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>: Supported messages are DISCOVER, OFFER,
+            REQUEST, RELEASE, ACK, and NAK.</simpara>
           </listitem>
           <listitem>
-            <simpara>RFC 2132: Supported options are: PAD (0),
+            <simpara><ulink url="http://tools.ietf.org/html/rfc2132">RFC 2132</ulink>: Supported options are: PAD (0),
             END(255), Message Type(53), DHCP Server Identifier (54),
             Domain Name (15), DNS Servers (6), IP Address Lease Time
             (51), Subnet mask (1), and Routers (3).</simpara>
@@ -3627,6 +3637,18 @@ Dhcp4/subnet4	[]	list	(default)
       yet</quote>, rather than actual limitations.</para>
       <itemizedlist>
           <listitem>
+          <para>
+            On startup, the DHCPv4 server does not get the full configuration from
+            BIND 10.  To remedy this, after starting BIND 10, modify any parameter
+            and commit the changes, e.g.
+            <screen>
+> <userinput>config show Dhcp4/renew-timer</userinput>
+Dhcp4/renew-timer	1000	integer	(default)
+> <userinput>config set Dhcp4/renew-timer 1001</userinput>
+> <userinput>config commit</userinput></screen>
+          </para>
+        </listitem>
+          <listitem>
             <simpara>During the initial IPv4 node configuration, the
             server is expected to send packets to a node that does not
             have IPv4 address assigned yet. The server requires
@@ -3644,10 +3666,10 @@ Dhcp4/subnet4	[]	list	(default)
 
           <listitem>
             <simpara>The DHCPv4 server does not support
-            BOOTP. That is a design choice. This limitation is
+            BOOTP. That is a design choice and the limitation is
             permanent. If you have legacy nodes that can't use DHCP and
-            require BOOTP support, please use the latest version of ISC DHCP
-            via <ulink url="http://www.isc.org/software/dhcp"/>.</simpara>
+            require BOOTP support, please use the latest version of ISC DHCP,
+            available from <ulink url="http://www.isc.org/software/dhcp"/>.</simpara>
           </listitem>
           <listitem>
             <simpara>Interface detection is currently working on Linux
@@ -3655,17 +3677,13 @@ Dhcp4/subnet4	[]	list	(default)
           </listitem>
           <listitem>
             <simpara>The DHCPv4 server does not  verify that
-            assigned address is unused. According to RFC 2131, the
-            allocating server should verify that address is no used by
+            assigned address is unused. According to <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>, the
+            allocating server should verify that address is not used by
             sending ICMP echo request.</simpara>
           </listitem>
           <listitem>
-            <simpara>Address rebinding (REBIND),
-            confirmation (CONFIRM), duplication report (DECLINE) and
-            release (RELEASE) are not supported yet.</simpara>
-          </listitem>
-          <listitem>
-            <simpara>DNS Update is not supported yet.</simpara>
+            <simpara>Address rebinding (REBIND) and duplication report (DECLINE)
+            are not supported yet.</simpara>
           </listitem>
 
       </itemizedlist>
@@ -3685,8 +3703,8 @@ Dhcp4/subnet4	[]	list	(default)
         program.
       </para>
       <para>
-        After starting BIND 10 and entering bindctl, the first step
-        in configuring the server is to add it to the list of running BIND 10 services.
+        After starting BIND 10 and starting <command>bindctl</command>, the first step
+        in configuring the server is to add <command>b10-dhcp6</command> to the list of running BIND 10 services.
 <screen>
 > <userinput>config add Boss/components b10-dhcp6</userinput>
 > <userinput>config set Boss/components/b10-dhcp6/kind dispensable</userinput>
@@ -3717,15 +3735,10 @@ Dhcp4/subnet4	[]	list	(default)
         During start-up the server will detect available network interfaces
         and will attempt to open UDP sockets on all interfaces that
         are up, running, are not loopback, are multicast-capable, and
-        have IPv6 address assigned. It will then listen to incoming traffic. The
-        currently supported client messages are SOLICIT and REQUEST. The server
-        will respond to them with ADVERTISE and REPLY, respectively.
-      </para>
-      <para>
-        Since the DHCPv6 server opens privileged ports, it requires root
-        access. Make sure you run this daemon as root.
+        have IPv6 address assigned. It will then listen to incoming traffic.
       </para>
 
+
     </section>
 
     <section id="dhcp6-configuration">
@@ -3744,11 +3757,11 @@ Dhcp6/rebind-timer	2000	integer	(default)
 Dhcp6/preferred-lifetime	3000	integer	(default)
 Dhcp6/valid-lifetime	4000	integer	(default)
 Dhcp6/option-data	[]	list	(default)
-Dhcp6/lease-database/type	"mysql"	string	
-Dhcp6/lease-database/name	"kea"	string	
-Dhcp6/lease-database/user	"kea"	string	
+Dhcp6/lease-database/type	"memfile"	string	(default)
+Dhcp6/lease-database/name	""	string	(default)
+Dhcp6/lease-database/user	""	string	(default)
 Dhcp6/lease-database/host	""	string	(default)
-Dhcp6/lease-database/password	""	string	(modified)
+Dhcp6/lease-database/password	""	string	(default)
 Dhcp6/subnet6/	list	
 </screen>
       </para>
@@ -3774,15 +3787,23 @@ Dhcp6/subnet6/	list
       <title>Database Configuration</title>
       <para>
       All leases issued by the server are stored in the lease database.  Currently,
-      the only supported database is MySQL, and so the server must be configured to
+      the only supported database is MySQL
+      <footnote>
+      <para>
+      The server comes with an in-memory database ("memfile") configured as the default
+      database. This is used for internal testing and is not supported.  In addition,
+      it does not store lease information on disk: lease information will be lost if the
+      server is restarted. 
+      </para>
+      </footnote>, and so the server must be configured to
       access the correct database with the appropriate credentials.
       </para>
       <note>
         <para>
-          Database access information must be configured for the DHCPv6 server, even if
-          it has already been configured for the DHCPv4 server.  The servers store their
-          information independently, and the databases used by the server need not be the
-          same.
+            Database access information must be configured for the DHCPv6 server, even if
+            it has already been configured for the DHCPv4 server.  The servers store their
+            information independently, so each server can use a separate
+            database or both servers can use the same database.
           </para>
         </note>
       <para>
@@ -3797,13 +3818,13 @@ Dhcp6/subnet6/	list
 > <userinput>config set Dhcp6/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
 </screen>
       If the database is located on a different system to the DHCPv6 server, the
-      database host name must also be specified: note however that this configuration
-      may have a severe impact on server performance:
+      database host name must also be specified (although note that this configuration
+      may have a severe impact on server performance):
 <screen>
 > <userinput>config set Dhcp6/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
 </screen>
       The usual state of affairs will be to have the database on the same machine as the
-      DHCPv4 server.  In this case, set the value to the empty string (this is the default):
+      DHCPv6 server.  In this case, set the value to the empty string (this is the default):
 <screen>
 > <userinput>config set Dhcp6/lease-database/host ""</userinput>
 </screen>
@@ -3846,19 +3867,7 @@ Dhcp6/subnet6/	list
         <para>It is possible to define more than one pool in a
         subnet: continuing the previous example, further assume that
         2001:db8:1:0:5::/80 should be also be managed by the server. It could be written as
-        2001:db8:1:0:5:: tDhcp6/interface/	list	(default)
-Dhcp6/renew-timer	1000	integer	(default)
-Dhcp6/rebind-timer	2000	integer	(default)
-Dhcp6/preferred-lifetime	3000	integer	(default)
-Dhcp6/valid-lifetime	4000	integer	(default)
-Dhcp6/option-data	[]	list	(default)
-Dhcp6/lease-database/type	""	string	(default)
-Dhcp6/lease-database/name	""	string	(default)
-Dhcp6/lease-database/user	""	string	(default)
-Dhcp6/lease-database/host	""	string	(default)
-Dhcp6/lease-database/password	""	string	(default)
-Dhcp6/subnet6	[]	list	(default)
-o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
+        2001:db8:1:0:5:: to 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
         is cumbersome. It can be expressed more simply as 2001:db8:1:0:5::/80. Both
         formats are supported by Dhcp6 and can be mixed in the pool list.
         For example, one could define the following pools:
@@ -3877,7 +3886,7 @@ o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
 > <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
 > <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 Dhcp6/subnet6</command> adds
+        previous example.  The <command>config add Dhcp6/subnet6</command> command adds
         another (second) subnet. It can be referred to as
         <command>Dhcp6/subnet6[1]</command>. In this example, we allow server to
         dynamically assign all addresses available in the whole subnet. Although
@@ -3890,7 +3899,7 @@ o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
         a given pool, it will be able to allocate also first (typically network
         address) address from that pool. For example for pool 2001:db8::/64 the
         2001:db8:: address may be assigned as well. If you want to avoid this,
-        please use min-max notation.
+        please use the "min-max" notation.
       </para>
       <para>
         Options can also be configured: the following commands configure
@@ -3905,7 +3914,7 @@ o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
 > <userinput>config commit</userinput>
         </screen>
        (The value for the setting of the "data" element is split across two
-        lines in this document for clarity: when entering the command, all the
+        lines in this document for clarity: when entering the command, the whole
         string should be entered on the same line.)
       </para>
       <para>
@@ -3936,7 +3945,14 @@ o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
           <para>
           The DHCPv6 server may receive requests from local (connected to the same
           subnet as the server) and remote (connecting via relays)
-          clients. As it may have many subnet configurations defined, it
+          clients.
+          <note>
+          <para>
+          Currently relayed DHCPv6 traffic is not supported.  The server will
+          only respond to local DHCPv6 requests - see <xref linkend="dhcp6-limit"/>
+          </para>
+          </note>
+          As it may have many subnet configurations defined, it
           must select appropriate subnet for a given request. To do this, the server first
           checks if there is only one subnet defined and source of the packet is
           link-local. If this is the case, the server assumes that the only subnet
@@ -3968,12 +3984,11 @@ o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
       supported:</para>
       <itemizedlist>
           <listitem>
-            <simpara>RFC 3315: Supported messages are SOLICIT,
-            ADVERTISE, REQUEST, and REPLY. Supported options are
-            SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS.</simpara>
+            <simpara><ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink>: Supported messages are SOLICIT,
+            ADVERTISE, REQUEST, RELEASE, RENEW, and REPLY.</simpara>
           </listitem>
           <listitem>
-            <simpara>RFC 3646: Supported option is DNS_SERVERS.</simpara>
+            <simpara><ulink url="http://tools.ietf.org/html/rfc3646">RFC 3646</ulink>: Supported option is DNS_SERVERS.</simpara>
           </listitem>
       </itemizedlist>
     </section>
@@ -3985,16 +4000,7 @@ o 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
       software. Most of them are reflections of the early stage of
       development and should be treated as <quote>not implemented
       yet</quote>, rather than actual limitations.</para>
-      <para>
       <itemizedlist>
-        <listitem>
-          <para>The DHCPv6 server has only been tested on Debian
-          operating systems.  There are known problems with the
-          handling of packets in CentOS and RHEL.</para>
-        </listitem>
-        <listitem>
-          <para>Relayed traffic is not supported.</para>
-        </listitem>
 
         <listitem>
           <para>
@@ -4009,40 +4015,26 @@ Dhcp6/renew-timer	1000	integer	(default)
           </para>
         </listitem>
         <listitem>
-          <para>Upon start, the server will open sockets on all
-          interfaces that are not loopback, are up, running and are
-          multicast capable and have IPv6 address.  Support for
-          multiple interfaces is not coded in reception routines yet,
-          so if you are running this code on a machine that has many
-          interfaces and <command>b10-dhcp6</command> happens to
-          listen on wrong interface, the easiest way to work around
-          this problem is to turn down other interfaces. This
-          limitation will be fixed shortly.</para>
+          <simpara>Relayed traffic is not supported.</simpara>
         </listitem>
         <listitem>
-          <para>ORO (Option Request Option, a list of options
-          requested by a client) is currently unsupported.</para>
+          <simpara>Temporary addresses are not supported.</simpara>
         </listitem>
         <listitem>
-          <para>Temporary addresses are not supported.</para>
+          <simpara>Prefix delegation is not supported.</simpara>
         </listitem>
         <listitem>
-          <para>Prefix delegation is not supported.</para>
+          <simpara>Rebinding (REBIND), confirmation (CONFIRM),
+          and duplication report (DECLINE) are not yet supported.</simpara>
         </listitem>
         <listitem>
-          <para>Address renewal (RENEW), rebinding (REBIND),
-          confirmation (CONFIRM), duplication report (DECLINE) and
-          release (RELEASE) are not supported.</para>
+          <simpara>DNS Update is not supported.</simpara>
         </listitem>
         <listitem>
-          <para>DNS Update is not supported.</para>
-        </listitem>
-        <listitem>
-          <para>Interface detection is currently working on Linux
-          only. See <xref linkend="iface-detect"/> for details.</para>
+          <simpara>Interface detection is currently working on Linux
+          only. See <xref linkend="iface-detect"/> for details.</simpara>
         </listitem>
       </itemizedlist>
-      </para>
     </section>
 
   </chapter>
@@ -4051,7 +4043,7 @@ Dhcp6/renew-timer	1000	integer	(default)
     <title>libdhcp++ library</title>
     <para>
       libdhcp++ is a common library written in C++ that handles
-      many DHCP-related tasks, including
+      many DHCP-related tasks, including:
       <itemizedlist>
         <listitem>
           <simpara>DHCPv4 and DHCPv6 packets parsing, manipulation and assembly</simpara>
@@ -4069,10 +4061,8 @@ Dhcp6/renew-timer	1000	integer	(default)
     </para>
 
     <para>
-    While this library is currently used by
-    <command>b10-dhcp4</command> and <command>b10-dhcp6</command>
-    only, it is designed to be a portable, universal library, useful for
-    any kind of DHCP-related software.
+    While this library is currently used by BIND 10 DHCP, it is designed to
+    be a portable, universal library, useful for any kind of DHCP-related software.
     </para>
 
 <!-- TODO: point to doxygen docs -->



More information about the bind10-changes mailing list