[#464,!238] User's guide updated

diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml
index acc46e66b11e9882f2a55737b2e5055d3ee283d3..d96ba4d003252d286dbb91b073f7893d4e9220ab 100644 (file)
--- a/doc/guide/dhcp4-srv.xml
+++ b/doc/guide/dhcp4-srv.xml
@@ -1145,7 +1145,7 @@ temporarily override a list of interface names and listen on all interfaces.
     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 the "min-max" 
+    network configurations. If you want to avoid this, please use the "min-max"
     notation.
   </para>
 </section>
@@ -2078,6 +2078,109 @@ It is merely echoed by the server
 }</screen>
       </para>
 
+      <para>
+        Another popular option that is often somewhat imprecisely called vendor
+        option is option 125. It's proper name is vendor-independent
+        vendor-specific information option or vivso. The idea behind those
+        options is that each vendor has its own unique set of options with their
+        own custom formats. The vendor is identified by a 32 unsigned integer
+        called enterprise-id or vendor-id. For example, vivso with vendor-id
+        4491 repesents DOCSIS options and you are likely to see many of them
+        when dealing with cable modems.
+      </para>
+
+      <para>
+        In Kea each vendor is represented by its own vendor space. Since there
+        are hundreds of vendors and sometimes they use different option
+        definitions for different hardware, it's impossible for Kea to support
+        them all out of the box. Fortunately, it's easy to define support for
+        new vendor options. Let's take an example of Genexis home gateway. This
+        device requires sending vivso 125 option with a suboption 2 that
+        contains a string with TFTP server URL. To support such a device, three
+        steps are needed. First, we need to define option definitions that will
+        explain how the option is supposed to be formed. Second, we will need to
+        define option values.  Third, we will need to tell Kea when to send
+        those specific options. This last step will be done with client
+        classification.
+      </para>
+
+       <para>
+        An example snippet of a configuration could look similar to the
+        following:
+
+<screen>
+{
+    // First, we need to define that suboption 2 in vivso option for
+    // vendor-id 25167 has specific format (it's a plain string in this example).
+    // After this definition, we can specify values for option tftp.
+    "option-def": [
+    {
+        // We define a short name, so the option could be referenced by name.
+        // The option has code 2 and resides with vendor space 25167.
+        // Its data is a plain string.
+        "name": "tftp",
+        "code": 2,
+        "space": "vendor-25167",
+        "type": "string"
+    } ],
+
+    "client-classes": [
+    {
+        // We now need to tell Kea how to recognize when to use vendor space 25167.
+        // Usually we can use simple expression such as checking if the device
+        // sent a vivso option with specific vendor-id, e.g.  "vendor[4491].exists"
+        // Unfortunately, Genexis is a bit unusual in this aspect, because it
+        // doesn't send vivso. In this case we need to look into vendor class
+        // (option code 60) and see if there's specific string that identifies
+        // the device.
+        "name": "cpe_genexis",
+        "test": "substring(option[60].hex,0,7) == 'HMC1000'",
+
+        // Once the device is recognized, we want to send two options:
+        // the VIVSO option with vendor-id set to 25167 and a suboption 2.
+        "option-data": [
+            {
+                "name": "vivso-suboptions",
+                "data": "25167",
+                "encapsulate": "vendor-25167"
+            },
+
+            // The suboption 2 value is defined as any other option. However,
+            // we want to send this suboption 2, even when the client didn't
+            // explicitly requested it (often there is no way to do that for
+            // vendor options). Therefore we use always-send to force Kea
+            // to always send this option when 25167 vendor space is involved.
+            {
+                "name": "tftp",
+                "space": "vendor-25167",
+                "data": "tftp://192.0.2.1/genexis/HMC1000.v1.3.0-R.img",
+                "always-send": true
+            }
+        ]
+    } ]
+}</screen>
+      </para>
+
+      <para>
+        One aspect requires a bit broader comment. By default Kea sends back
+        only those options that are requested by a client, unless there are
+        protocol rules that tell DHCP server to always send an option. This
+        approach works nicely for most cases and avoids problems with clients
+        refusing responses with options they don't understand. Unfortunately,
+        this is more blurry when we consider vendor options. Some vendors (such
+        as docsis, identified by vendor options 4491) have a mechanism to
+        request specific vendor options and Kea is able to honor that.
+        Unfortunately, for many other vendors, such as Genexis (25167) discussed
+        here, Kea does not have such a mechanism, so it can't sent any
+        suboptions on its own. To solve this issue, we came up with a concept of
+        persistent options. Kea can be told to always send options, even if
+        client didn't request them. This can be achieved by adding
+        "always-send": true to your option definition. Note that in this
+        particular case an option is defined in a vendor space 25167. With the
+        "always-send" enabled, the option will be sent every time there is a
+        need to deal with vendor space 25167.
+      </para>
+
       <para>
       Another possibility, since Kea 1.3, is to redefine the option,
       see <xref linkend="dhcp4-private-opts"/>.