[master] Finished merge of trac4273 (DHCP4o6 user doc)

ChangeLog

@@ -1,3 +1,8 @@
+1143.	[doc]		fdupont
+	User's Guide has been updated with DHCPv4-over-DHCPv6 support
+	details.
+	(Trac #4273, git xxx)
+
 1142.	[doc]		sar
 	Uncomment the example columns in some rows in the table
 	listing the classificaiton examples.

doc/examples/kea4/dhcpv4-over-dhcpv6.json

@@ -0,0 +1,49 @@
+# This is an example configuration file for the DHCPv4 server of
+# DHCPv4-over-DHCPv6 tests in Kea.
+
+{
+
+# DHCPv4 conf
+"Dhcp4":
+{
+  "interfaces-config": {
+    "interfaces": [ "eno33554984" ]
+  },
+
+  "lease-database": {
+    "type": "memfile",
+    "name": "leases4"
+  },
+
+  "valid-lifetime": 4000,
+
+  "subnet4": [
+   {    "subnet": "10.10.10.0/24",
+        # Don't forget the "4o6-" before "interface" here!
+        "4o6-interface": "eno33554984",
+        "4o6-subnet": "2001:db8:1:1::/64",
+        "pools": [ { "pool": "10.10.10.100 - 10.10.10.199" } ] }
+  ],
+
+  # This enables DHCPv4-over-DHCPv6 support
+  "dhcp4o6-port": 6767
+
+},
+
+"Logging":
+{
+  "loggers": [
+    {
+      "name": "kea-dhcp4",
+      "output_options": [
+          {
+            "output": "/tmp/kea-dhcp4.log"
+          }
+      ],
+      "severity": "DEBUG",
+      "debuglevel": 0
+    }
+  ]
+}
+
+}

doc/examples/kea6/dhcpv4-over-dhcpv6.json

@@ -0,0 +1,60 @@
+# This is an example configuration file for the DHCPv6 server of
+# DHCPv4-over-DHCPv6 tests in Kea.
+
+{
+
+# DHCPv6 conf
+"Dhcp6":
+{
+  "interfaces-config": {
+    # Enable unicast
+    "interfaces": [ "eno33554984/2001:db8:1:1::1" ]
+  },
+
+  "lease-database": {
+    "type": "memfile",
+    "name": "leases6"
+  },
+
+  "preferred-lifetime": 3000,
+  "valid-lifetime": 4000,
+  "renew-timer": 1000,
+  "rebind-timer": 2000,
+
+  "subnet6": [
+   {   "subnet": "2001:db8:1:1::/64",
+       "interface": "eno33554984",
+       "pools": [ { "pool": "2001:db8:1:1::1:0/112" } ] }
+   ],
+
+  # This enables DHCPv4-over-DHCPv6 support
+  "dhcp4o6-port": 6767,
+
+  # Required by DHCPv4-over-DHCPv6 clients
+  "option-data": [
+   {  "name": "dhcp4o6-server-addr",
+      "code": 88,
+      "space": "dhcp6",
+      "csv-format": true,
+      # Put the server address here
+      "data": "2001:db8:1:1::1" }
+   ]
+},
+
+"Logging":
+{
+  "loggers": [
+    {
+      "name": "kea-dhcp6",
+      "output_options": [
+          {
+            "output": "/tmp/kea-dhcp6.log"
+          }
+      ],
+      "severity": "DEBUG",
+      "debuglevel": 0
+    }
+  ]
+}
+
+}

doc/guide/dhcp4-srv.xml

@@ -2230,7 +2230,7 @@ It is merely echoed by the server
       which updated
       <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>.
       That update now states that the server must
-      send client-id if the client sent it. That is the default behaviour
+      send client-id if the client sent it. That is the default behavior
       that Kea offers. However, in some cases older devices that do
       not support
       <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
@@ -2411,7 +2411,98 @@ It is merely echoed by the server
 
     </section>
 
-  </section> <!-- end of configuring kea-dhcp4 server section with many subsections -->
+"    <section id="dhcp4-dhcp4o6-config">
+      <title>DHCPv4-over-DHCPv6 DHCPv4 side</title>
+      <para>
+      The support of DHCPv4-over-DHCPv6 transport
+      <ulink url="http://tools.ietf.org/html/rfc7341">RFC 7341</ulink>
+      is implemented using cooperating DHCPv4 and DHCPv6 servers.
+      This section is about the configuration of the DHCPv4 side
+      (the DHCPv6 side is described in <xref linkend="dhcp6-dhcp4o6-config"/>).
+      </para>
+      <note>
+      DHCPv4-over-DHCPv6 support is experimental and the details of
+      the inter-process communication can change: DHCPv4 and DHCPv6
+      should run the same version of Kea.
+      </note>
+      <para>
+      The <command>dhcp4o6-port</command> global parameter specifies
+      the first of the two consecutive ports of the UDP sockets used
+      for the communication between the DHCPv6 and DHCPv4 servers
+      (the DHCPv4 server is bound to ::1 on <command>port</command> + 1
+      and connected to ::1 on <command>port</command>).
+      </para>
+      <para>
+      With DHCPv4-over-DHCPv6 the DHCPv4 server does not have access
+      to several of the identifiers it would normally use to select a
+      subnet.  In order to address this issue three new configuration
+      entires have been added.  The presence of any of these allows the
+      subnet to be used with DHCPv4-over-DHCPv6.  These entries are:
+      <itemizedlist>
+        <listitem>
+        <simpara><command>4o6-subnet</command>: Takes a prefix (i.e., an
+        IPv6 address followed by a slash and a prefix length) which is
+        matched against the source address.
+        </simpara>
+        </listitem>
+        <listitem>
+        <simpara><command>4o6-interface-id</command>: Takes a relay interface
+        ID option value.
+        </simpara>
+        </listitem>
+        <listitem>
+        <simpara><command>4o6-interface</command>: Takes an interface name
+        which is matched against the incoming interface name.
+        </simpara>
+        </listitem>
+      </itemizedlist>
+      </para>
+      <para>
+      The following configuration was used during some tests:
+<screen>
+{
+
+# DHCPv4 conf
+"Dhcp4": {
+    "interfaces-config": {
+        "interfaces": [ "eno33554984" ]
+    },
+
+    "lease-database": {
+        "type": "memfile",
+        "name": "leases4"
+    },
+
+    "valid-lifetime": 4000,
+
+    "subnet4": [ {
+        "subnet": "10.10.10.0/24",
+        <userinput>"4o6-interface": "eno33554984",</userinput>
+        <userinput>"4o6-subnet": "2001:db8:1:1::/64",</userinput>
+        "pools": [ { "pool": "10.10.10.100 - 10.10.10.199" } ]
+    } ],
+
+    <userinput>"dhcp4o6-port": 6767</userinput>
+
+},
+
+"Logging": {
+    "loggers": [ {
+        "name": "kea-dhcp4",
+        "output_options": [ {
+            "output": "/tmp/kea-dhcp4.log"
+        } ],
+        "severity": "DEBUG",
+        "debuglevel": 0
+    } ]
+}
+
+}
+</screen>
+    </para>
+    </section>
+
+  </section> <!-- end of configuring kea-dhcp4 server section -->
 
   <!-- Host reservation is a large topic. There will be many subsections,
    so it should be a section on its own. -->
@@ -3266,10 +3357,11 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
             <entry>pkt4-nak-sent</entry>
             <entry>integer</entry>
             <entry>
-            Number of DHCPNAK packets sent. This statistic is expected to
-            grow when the server choses to not honor the address requested by a
-            client. In general, the sum of pkt4-ack-sent and pkt4-nak-sent
-            should be close to pkt4-request-received.
+            Number of DHCPNAK packets sent. This statistic is expected
+            to grow when the server chooses to not honor the address
+            requested by a client. In general, the sum of
+            pkt4-ack-sent and pkt4-nak-sent should be close to
+            pkt4-request-received.
             </entry>
             </row>
 

doc/guide/dhcp6-srv.xml

@@ -290,7 +290,7 @@ syntax would be used:
     }
 ]
 </screen>
-Note that indentation is optional and is used for aesthetic purposes only.
+Note that indentation is optional and is used for esthetic purposes only.
 In some cases in may be preferable to use more compact notation.
 </para>
 
@@ -2182,6 +2182,92 @@ should include options from the isc option space:
       </para>
     </section>
 
+    <section id="dhcp6-dhcp4o6-config">
+      <title>DHCPv4-over-DHCPv6 DHCPv6 side</title>
+      <para>
+      The support of DHCPv4-over-DHCPv6 transport
+      <ulink url="http://tools.ietf.org/html/rfc7341">RFC 7341</ulink>
+      is implemented using cooperating DHCPv4 and DHCPv6 servers.
+      This section is about the configuration of the DHCPv6 side
+      (the DHCPv4 side is described in <xref linkend="dhcp4-dhcp4o6-config"/>).
+      </para>
+      <note>
+      DHCPv4-over-DHCPv6 support is experimental and the details of
+      the inter-process communication can change: DHCPv4 and DHCPv6
+      should run the same version of Kea.
+      </note>
+      <para>
+      There is only one specific parameter for the DHCPv6 side:
+      <command>dhcp4o6-port</command> which specifies the first of the
+      two consecutive ports of the UDP sockets used for the communication
+      between the DHCPv6 and DHCPv4 servers (the DHCPv6 server is bound
+      to ::1 on <command>port</command> and connected to ::1 on
+      <command>port</command> + 1).
+      </para>
+      <para>
+      Two other configuration entries are in general required: unicast traffic
+      support (see <xref linkend="dhcp6-unicast"/>) and DHCP 4o6 server
+      address option (name "dhcp4o6-server-addr", code  88).
+      </para>
+      <para>
+      The following configuration was used during some tests:
+<screen>
+{
+
+# DHCPv6 conf
+"Dhcp6": {
+
+    "interfaces-config": {
+        "interfaces": [ "eno33554984/2001:db8:1:1::1" ]
+    },
+
+    "lease-database": {
+        "type": "memfile",
+        "name": "leases6"
+    },
+
+    "preferred-lifetime": 3000,
+    "valid-lifetime": 4000,
+    "renew-timer": 1000,
+    "rebind-timer": 2000,
+
+    "subnet6": [ {
+        "subnet": "2001:db8:1:1::/64",
+        "interface": "eno33554984",
+        "pools": [ { "pool": "2001:db8:1:1::1:0/112" } ]
+    } ],
+
+    <userinput>"dhcp4o6-port": 6767,
+
+    "option-data": [ {
+        "name": "dhcp4o6-server-addr",
+        "code": 88,
+        "space": "dhcp6",
+        "csv-format": true,
+        "data": "2001:db8:1:1::1"
+    } ]
+</userinput>
+},
+
+"Logging": {
+    "loggers": [ {
+        "name": "kea-dhcp6",
+        "output_options": [ {
+            "output": "/tmp/kea-dhcp6.log"
+        } ],
+        "severity": "DEBUG",
+        "debuglevel": 0
+    } ]
+}
+
+}
+</screen>
+      </para>
+      <note>
+      Relayed DHCPv4-QUERY DHCPv6 messages are not yet supported.
+      </note>
+    </section>
+
    </section>
 
   <!-- Host reservation is a large topic. There will be many subsections,