[3604] Updated Kea user guide with the new config structure for interfaces.

doc/guide/config.xml

@@ -56,7 +56,10 @@
 
 # DHCPv4 specific configuration starts here.
 "Dhcp4": {
-    "interfaces": [ "eth0" ],
+    "interfaces-config": {
+        "interfaces": [ "eth0" ],
+        "socket-type": "raw"
+    },
     "valid-lifetime": 4000,
     "renew-timer": 1000,
     "rebind-timer": 2000,
@@ -70,7 +73,9 @@
 
 # DHCPv6 specific configuration starts here.
 "Dhcp6": {
-    "interfaces": [ "eth1" ],
+    "interfaces-config": {
+        "interfaces": [ "eth1" ]
+    },
     "preferred-lifetime": 3000,
     "valid-lifetime": 4000,
     "renew-timer": 1000,
@@ -119,8 +124,7 @@
         If there is an array, a specific instance within that array is referenced by
         a number in square brackets (with numbering starting at zero). For example, in the above configuration the
         valid-lifetime in the Dhcp6 component can be referred to as
-        Dhcp6/valid-lifetime, the first interface for the DHCPv4 server as
-        Dhcp4/interfaces[0] and the pool in the first subnet defined in the DHCPv6
+        Dhcp6/valid-lifetime and the pool in the first subnet defined in the DHCPv6
         configuration as Dhcp6/subnet6[0]/pool.</para>
       
       <!-- @todo Add a reference here after #3422 is done -->

doc/guide/dhcp4-srv.xml

@@ -92,12 +92,16 @@
 "Dhcp4": {
 
 # First we set up global values
-    "interfaces": [ "eth0" ],
     "valid-lifetime": 4000,
     "renew-timer": 1000,
     "rebind-timer": 2000,
 
-# Next we specify the type of lease database
+# Next we setup the interfaces to be used by the server.
+    "interfaces-config": {
+        "interfaces": [ "eth0" ]
+    },
+
+# And we specify the type of lease database
     "lease-database": {
         "type": "memfile",
         "persist": true,
@@ -154,19 +158,8 @@ ignored. This is unlikely to cause any confusion as there are no real life
 reasons to keep multiple copies of the same parameter in your configuration
 file.</para>
 
-<para>Moving onto the DHCPv4 configuration elements,
-the line defining <command>interfaces</command> parameter specifies a list
-of network interfaces on which the server should listen.
-Lists are opened and closed with square brackets, with elements
-separated by commas. Had we wanted to listen on two interfaces, the line could
-look like this:
-<screen>
-"interfaces": [ "eth0", "eth1" ],
-</screen>
-As "<command>interfaces</command>" is not the last parameter in the configuration,
-a trailing comma is required.</para>
-<para>A number of other parameters
-follow. <command>valid-lifetime</command> defines for how long the addresses (leases) given out by the
+<para>Moving onto the DHCPv4 configuration elements, the very first few elements
+define some global parameters. <command>valid-lifetime</command> defines for how long the addresses (leases) given out by the
 server are valid. If nothing changes, a client that got an address is allowed to
 use it for 4000 seconds. (Note that integer numbers are specified as is,
 without any quotes around them.) <command>renew-timer</command> and
@@ -177,6 +170,20 @@ rebind procedures. Note that <command>renew-timer</command> and
 client will select values for T1 and T2 timers according to the
 <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>.</para>
 
+<para>The <command>interfaces-config</command> map specifies the server
+configuration concerning the network interfaces, on which the server should
+listen to the DHCP messages. The <command>interfaces</command> parameter
+specifies a list of network interfaces on which the server should listen.
+Lists are opened and closed with square brackets, with elements separated
+by commas. Had we wanted to listen on two interfaces, the
+<command>interfaces-config</command> would look like this:
+<screen>
+"interfaces-config": {
+    "interfaces": [ "eth0", "eth1" ]
+},
+</screen>
+</para>
+
 <para>The next couple of lines define the lease database, the place where the server
 stores its lease information. This particular example tells the server to use
 <command>memfile</command>, which is the simplest (and fastest) database
@@ -332,22 +339,40 @@ url="http://jsonviewer.stack.hu/"/>.
 </section>
 </section>
 
-<section id="dhcp4-interface-selection">
-  <title>Interface selection</title>
+<section id="dhcp4-interface-configuration">
+  <title>Interface configuration</title>
   <para>The DHCPv4 server has to be configured to listen on specific network
   interfaces.  The simplest network interface configuration tells the server to
   listen on all available interfaces:
   <screen>
-"Dhcp4": { <userinput>"interfaces": ["*"]</userinput>, ... }</screen>
+"Dhcp4": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"*"</userinput> ]
+    }
+    ...
+},
+  </screen>
   The asterisk plays the role of a wildcard and means "listen on all interfaces".
   However, it is usually a good idea to explicitly specify interface names:
   <screen>
-"Dhcp4": { <userinput>"interfaces": [ "eth1", "eth3" ]</userinput>, ... }</screen>
+"Dhcp4": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1", "eth3"</userinput> ]
+    },
+    ...
+}
+  </screen>
   </para>
   <para>It is possible to use wildcard interface name (asterisk) concurrently
   with explicit interface names:
   <screen>
-"Dhcp4": { <userinput>"interfaces": [ "eth1", "eth3", "*" ]</userinput>, ... }</screen>
+"Dhcp4": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1", "eth3", "*"</userinput> ]
+    },
+    ...
+}
+  </screen>
 It is anticipated that this form of usage will only be used when it is desired to
 temporarily override a list of interface names and listen on all interfaces.
   </para>
@@ -357,10 +382,60 @@ temporarily override a list of interface names and listen on all interfaces.
   instance should be bound to a different address on the particular interface.
   In these situations, the address to use can be selected by
   appending an IPv4 address to the interface name in the following manner:
-<screen>
-"Dhcp4": { <userinput>"interfaces": [ "eth1/10.0.0.1", "eth3/192.0.2.3" ]</userinput>, ... }</screen>
+  <screen>
+"Dhcp4": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1/10.0.0.1", "eth3/192.0.2.3"</userinput> ]
+    },
+    ...
+}
+  </screen>
   Note that only one address can be specified on each interface.
   </para>
+
+  <para>Kea supports responding to directly connected clients which don't have
+  an address configured on the interface yet. This requires that the server
+  injects the hardware address of the destination into the data link layer
+  of the packet being sent to the client. The DHCPv4 server utilizes the
+  raw sockets to achieve this, and builds the entire IP/UDP stack for the
+  outgoing packets. The down side of raw socket use, however, is that incoming
+  and outgoing packets bypass the firewalls (e.g. iptables). It is also
+  troublesome to handle traffic on multiple IPv4 addresses assigned to the
+  same interface, as raw sockets are bound to the interface and advanced
+  packet filtering techniques (e.g. using the BPF) have to be used to
+  receive unicast traffic on the desired addresses assigned to the interface,
+  rather than capturing whole traffic reaching the interface to which the raw
+  socket is bound. Therefore, in the deployments where the server doesn't
+  have to provision the directly connected clients and only receives the
+  unicast packets from the relay agents, it is desired to configure the
+  DHCP server to utilize the IP/UDP datagram sockets, instead of raw sockets.
+  The following configuration demonstrates how this can be achieved:
+
+  <screen>
+"Dhcp4": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1", "eth3"</userinput> ],
+        "socket-type": "datagram"
+    },
+    ...
+}
+  </screen>
+  The <command>socket-type</command> specifies that the datagram sockets will
+  be opened on all interfaces on which the server listens, i.e. "eth1" and
+  "eth3" in our case. If the <command>socket-type</command> is set to
+  <userinput>raw</userinput>, it configures the server to use raw sockets
+  instead. If the <command>socket-type</command> value is not specified, the
+  default value <userinput>raw</userinput> is used.
+  </para>
+
+  <note>
+    <para>Specifying the value <userinput>raw</userinput> as the socket type,
+    doesn't guarantee that the raw sockets will be used! The use of raw sockets
+    to handle the traffic from the directly connected clients is currently
+    supported on Linux and BSD systems only. If the raw sockets are not
+    supported on the particular OS, the server will issue a warning and
+    fall back to use the datagram sockets.</para>
+  </note>
 </section>
 
 <section id="ipv4-subnet-id">

doc/guide/dhcp6-srv.xml

@@ -92,13 +92,17 @@
 "Dhcp6": {
 
 # First we set up global values
-    "interfaces": [ "eth0" ],
     "renew-timer": 1000,
     "rebind-timer": 2000,
     "preferred-lifetime": 3000,
     "valid-lifetime": 4000,
 
-# Next we specify the type of lease database
+# Next we setup the interfaces to be used by the server.
+    "interfaces-config": {
+        "interfaces": [ "eth0" ]
+    },
+
+# And we specify the type of a lease database
     "lease-database": {
         "type": "memfile",
         "persist": true,
@@ -156,19 +160,8 @@ ignored. This is unlikely to cause any confusion as there are no real life
 reasons to keep multiple copies of the same parameter in your configuration
 file.</para>
 
-<para>Moving onto the DHCPv6 configuration elements,
-the line defining <command>interfaces</command> parameter specifies a list
-of network interfaces on which the server should listen.
-Lists are opened and closed with square brackets, with elements
-separated by commas. Had we wanted to listen on two interfaces, the line could
-look like this:
-<screen>
-"interfaces": [ "eth0", "eth1" ],
-</screen>
-
-As "<command>interfaces</command>" is not the last parameter in the
-configuration, a trailing comma is required.</para>
-<para>A number of other parameters follow. <command>valid-lifetime</command>
+<para>Moving onto the DHCPv6 configuration elements, the very first few elements
+define some global parameters. <command>valid-lifetime</command>
 defines for how long the addresses (leases) given out by the server are valid. If
 nothing changes, a client that got an address is allowed to use it for 4000
 seconds. (Note that integer numbers are specified as is, without any quotes
@@ -178,6 +171,20 @@ connections). <command>renew-timer</command> and <command>
 rebind-timer</command> are values that define T1 and T2 timers that govern when
 the client will begin the renewal and rebind procedures.</para>
 
+<para>The <command>interfaces-config</command> map specifies the server
+configuration concerning the network interfaces, on which the server should
+listen to the DHCP messages. The <command>interfaces</command> parameter
+specifies a list of network interfaces on which the server should listen.
+Lists are opened and closed with square brackets, with elements separated
+by commas. Had we wanted to listen on two interfaces, the
+<command>interfaces-config</command> would look like this:
+<screen>
+"interfaces-config": {
+    "interfaces": [ "eth0", "eth1" ]
+},
+</screen>
+</para>
+
 <para>The next couple of lines define the lease database, the place where the server
 stores its lease information. This particular example tells the server to use
 <command>memfile</command>, which is the simplest (and fastest) database
@@ -339,19 +346,37 @@ JSON validator is available at <ulink url="http://jsonviewer.stack.hu/"/>.
 <section id="dhcp6-interface-selection">
   <title>Interface selection</title>
   <para>The DHCPv6 server has to be configured to listen on specific network
-  interfaces.  The simplest network interface configuration tells the server to
+  interfaces.  The simplest network interface configuration instructs the server to
   listen on all available interfaces:
   <screen>
-"Dhcp6": { <userinput>"interfaces": ["*"]</userinput>, ... }</screen>
+"Dhcp6": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"*"</userinput> ]
+    }
+    ...
+}
+</screen>
   The asterisk plays the role of a wildcard and means "listen on all interfaces".
   However, it is usually a good idea to explicitly specify interface names:
   <screen>
-"Dhcp6": { <userinput>"interfaces": [ "eth1", "eth3" ]</userinput>, ... }</screen>
-  </para>
+"Dhcp6": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1", "eth3"</userinput> ]
+    },
+    ...
+}
+  </screen>
+</para>
   <para>It is possible to use wildcard interface name (asterisk) concurrently
-  with explicit interface names:
+  with the actual interface names:
   <screen>
-"Dhcp6": { <userinput>"interfaces": [ "eth1", "eth3", "*" ]</userinput>, ... }</screen>
+"Dhcp6": {
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1", "eth3", "*"</userinput> ]
+    },
+    ...
+}
+  </screen>
 It is anticipated that this will form of usage only be used where it is desired to
 temporarily override a list of interface names and listen on all interfaces.
   </para>
@@ -413,23 +438,26 @@ temporarily override a list of interface names and listen on all interfaces.
         notation to specify interfaces has been extended.  An interface name can be
         optionally followed by a slash, followed by the global unicast address on which
         the server should listen. This will be done in addition to normal
-        link-local binding + listening on ff02::1:2 address. The sample commands
-        listed below show how to listen on 2001:db8::1 (a global address)
+        link-local binding + listening on ff02::1:2 address. The sample configuration
+        below shows how to listen on 2001:db8::1 (a global address)
         configured on the eth1 interface.
       </para>
       <para>
  <screen>
 "Dhcp6": {
-    <userinput>"interfaces": [ "eth1/2001:db8::1"],</userinput>
+    "interfaces-config": {
+        "interfaces": [ <userinput>"eth1/2001:db8::1"</userinput> ]
+    },
     ...
-}</screen>
+}
+ </screen>
 
-        When this configuration gets committed, the server will start to listen on
+        This configuration will cause the server to listen on
         eth1 on link-local address, multicast group (ff02::1:2) and 2001:db8::1.
       </para>
       <para>
         It is possible to mix interface names, wildcards and interface name/addresses
-        on the Dhcp6/interface list. It is not possible to specify more than one
+        on the list of interfaces. It is not possible to specify more than one
         unicast address on a given interface.
       </para>
       <para>
@@ -1771,7 +1799,9 @@ should include options from the isc option space:
       such a configuration:
 <screen>
 "Dhcp6": {
-    "interfaces": [ "ethX" ],
+    "interfaces-config": {
+        "interfaces": [ "ethX" ]
+    },
     <userinput>"option-data": [ {
         "name": "dns-servers",
         "data": "2001:db8::1, 2001:db8::2"