>From e92addb478068ee37d7271963fb08221c1360973 Mon Sep 17 00:00:00 2001
From: Gene Czarcinski <gene@czarc.net>
Date: Sat, 3 Nov 2012 14:40:18 -0400
Subject: [PATCH] Update documentation for DHCPv6 support.

This patch reflects the changes in virtual network xml specification
to support the IPv6 DHCP service.
---
 docs/formatnetwork.html.in | 108 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 98 insertions(+), 10 deletions(-)

diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
index 49206dd..420b552 100644
--- a/docs/formatnetwork.html.in
+++ b/docs/formatnetwork.html.in
@@ -577,8 +577,10 @@
         dotted-decimal format, or an IPv6 address in standard
         colon-separated hexadecimal format, that will be configured on
         the bridge
-        device associated with the virtual network. To the guests this
-        address will be their default route. For IPv4 addresses, the <code>netmask</code>
+        device associated with the virtual network. To the guests this IPv4
+        address will be their IPv4 default route.  For IPv6, the default route is
+        established via Router Advertisement.   
+        For IPv4 addresses, the <code>netmask</code>
         attribute defines the significant bits of the network address,
         again specified in dotted-decimal format.  For IPv6 addresses,
         and as an alternate method for IPv4 addresses, you can specify
@@ -587,10 +589,13 @@
         could also be given as <code>prefix='24'</code>. The <code>family</code>
         attribute is used to specify the type of address - 'ipv4' or 'ipv6'; if no
         <code>family</code> is given, 'ipv4' is assumed. A network can have more than
-        one of each family of address defined, but only a single address can have a
-        <code>dhcp</code> or <code>tftp</code> element. <span class="since">Since 0.3.0;
+        one of each family of address defined, but only a single IPv4 address can have a
+        <code>dhcp</code> or <code>tftp</code> element. <span class="since">Since 0.3.0 </span>
         IPv6, multiple addresses on a single network, <code>family</code>, and
-        <code>prefix</code> since 0.8.7</span>
+        <code>prefix</code>. <span class="since">Since 0.8.7</span>  In addition 
+        to the one IPv4 address which has a <code>dhcp</code> definition, one IPv6
+        address can have a <code>dhcp</code> definition.  
+        <span class="since">Since 1.0.1</span>
         <dl>
           <dt><code>tftp</code></dt>
           <dd>Immediately within
@@ -611,27 +616,46 @@
             <code>dhcp</code> element is not supported for IPv6, and
             is only supported on a single IP address per network for IPv4.
             <span class="since">Since 0.3.0</span>
+            The <code>dhcp</code> element is now supported for IPv6.  
+            Again, there is a restriction that only one IPv6 address definition
+            is able to have a <code>dhcp</code> element.
+            <span class="since">Since 1.0.1</span> 
             <dl>
               <dt><code>range</code></dt>
               <dd>The <code>start</code> and <code>end</code> attributes on the
                 <code>range</code> element specify the boundaries of a pool of
-                IPv4 addresses to be provided to DHCP clients. These two addresses
+                addresses to be provided to DHCP clients. These two addresses
                 must lie within the scope of the network defined on the parent
-                <code>ip</code> element.  <span class="since">Since 0.3.0</span>
+                <code>ip</code> element.  There may be zero or more
+                <code>range</code> elements specified. 
+                <span class="since">Since 0.3.0</span>
+                <code>Range</code> can be specified for one IPv4 address, 
+                one IPv6 address, or both.   <span class="since">Since 1.0.1</span>
               </dd>
               <dt><code>host</code></dt>
               <dd>Within the <code>dhcp</code> element there may be zero or more
-                <code>host</code> elements; these specify hosts which will be given
+                <code>host</code> elements.  These specify hosts which will be given
                 names and predefined IP addresses by the built-in DHCP server. Any
-                such element must specify the MAC address of the host to be assigned
+                such IPv4 element must specify the MAC address of the host to be assigned
                 a given name (via the <code>mac</code> attribute), the IP to be
                 assigned to that host (via the <code>ip</code> attribute), and the
                 name to be given that host by the DHCP server (via the
                 <code>name</code> attribute).  <span class="since">Since 0.4.5</span>
+                Within the IPv6 <code>dhcp</code> element zero or more
+                <code>host</code> elements are now supported.  The definition for 
+                an IPv6 <code>host</code> element differs from that for IPv4:  
+                there is no <code>mac</code> attribute since a MAC address has no
+                defined meaning in IPv6.  Instead, the <code>name</code> attribute is
+                used to identify the host to be assigned the IPv6 address.  For DHCPv6,
+                the name is the plain name of the client host sent by the 
+                client to the server.  Note that this method of assigning a 
+                specific IP address can be used instead of the <code>mac</code> 
+                attribute for IPv4.  <span class="since">Since 1.0.1</span>
               </dd>
               <dt><code>bootp</code></dt>
               <dd>The optional <code>bootp</code>
-                element specifies BOOTP options to be provided by the DHCP server.
+                element specifies BOOTP options to be provided by the DHCP 
+                server for IPv4 only.
                 Two attributes are supported: <code>file</code> is mandatory and
                 gives the file to be used for the boot image; <code>server</code> is
                 optional and gives the address of the TFTP server from which the boot
@@ -674,6 +698,29 @@
         &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" /&gt;
       &lt;/network&gt;</pre>
 
+
+    <p>
+      Below is a variation of the above example which adds an IPv6
+      dhcp range definition.
+    </p>
+
+    <pre>
+      &lt;network&gt;
+        &lt;name&gt;default6&lt;/name&gt;
+        &lt;bridge name="virbr0" /&gt;
+        &lt;forward mode="nat"/&gt;
+        &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
+          &lt;dhcp&gt;
+            &lt;range start="192.168.122.2" end="192.168.122.254" /&gt;
+          &lt;/dhcp&gt;
+        &lt;/ip&gt;
+        &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" &gt;
+          &lt;dhcp&gt;
+            &lt;range start="2001:db8:ca2:2:1::10" end="2001:db8:ca2:2:1::ff" /&gt;
+          &lt;/dhcp&gt;
+        &lt;/ip&gt;
+      &lt;/network&gt;</pre>
+
     <h3><a name="examplesRoute">Routed network config</a></h3>
 
     <p>
@@ -698,6 +745,29 @@
         &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" /&gt;
       &lt;/network&gt;</pre>
 
+    <p>
+      Below is another IPv6 varition.  Instead of a dhcp range being
+      specified, this example has a couple of IPv6 host definitions.
+    </p>
+
+    <pre>
+      &lt;network&gt;
+        &lt;name&gt;local6&lt;/name&gt;
+        &lt;bridge name="virbr1" /&gt;
+        &lt;forward mode="route" dev="eth1"/&gt;
+        &lt;ip address="192.168.122.1" netmask="255.255.255.0"&gt;
+          &lt;dhcp&gt;
+            &lt;range start="192.168.122.2" end="192.168.122.254" /&gt;
+          &lt;/dhcp&gt;
+        &lt;/ip&gt;
+        &lt;ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" &gt;
+          &lt;dhcp&gt;
+            &lt;host name="paul"   ip="2001:db8:ca2:2:3::1" /&gt;
+            &lt;host name="bob"    ip="2001:db8:ca2:2:3::2" /&gt;
+          &lt;/dhcp&gt;
+        &lt;/ip&gt;
+      &lt;/network&gt;</pre>
+
     <h3><a name="examplesPrivate">Isolated network config</a></h3>
 
     <p>
@@ -720,6 +790,24 @@
         &lt;ip family="ipv6" address="2001:db8:ca2:3::1" prefix="64" /&gt;
       &lt;/network&gt;</pre>
 
+    <h3><a name="examplesPrivate">Isolated IPv6 network config</a></h3>
+
+    <p>
+      This variation of an isolated network defines only IPv6.
+    </p>
+
+    <pre>
+      &lt;network&gt;
+        &lt;name&gt;sixnet&lt;/name&gt;
+        &lt;bridge name="virbr6" /&gt;
+        &lt;ip family="ipv6" address="2001:db8:ca2:6::1" prefix="64" &gt;
+          &lt;dhcp&gt;
+            &lt;host name="peter"   ip="2001:db8:ca2:6:6::1" /&gt;
+            &lt;host name="dariusz" ip="2001:db8:ca2:6:6::2" /&gt;
+          &lt;/dhcp&gt;
+        &lt;/ip&gt;
+      &lt;/network&gt;</pre>
+
     <h3><a name="examplesBridge">Using an existing host bridge</a></h3>
 
     <p>
-- 
1.7.11.7

