From 80360862bc89acbe4fbb8d2a9294ae2518be4944 Mon Sep 17 00:00:00 2001
From: Francis Dupont <fdupont@isc.org>
Date: Mon, 25 Sep 2017 20:12:33 +0200
Subject: [PATCH] [5073a] Attempt to resolve last review comments

---
 doc/examples/kea4/advanced.json | 10 +++-
 doc/guide/dhcp4-srv.xml         | 97 ++++++++++++++++++++++++++++++++-
 2 files changed, 103 insertions(+), 4 deletions(-)

diff --git a/doc/examples/kea4/advanced.json b/doc/examples/kea4/advanced.json
index 77a097140f..2a8b76f144 100644
--- a/doc/examples/kea4/advanced.json
+++ b/doc/examples/kea4/advanced.json
@@ -36,9 +36,13 @@
         "re-detect": true
     },
 
-    // Option 43 last resort definition can make legal messages to be
-    // rejected because they use not compatible "raw" value.
-    // The option definition can be applied to avoid this problem.
+    // Option 43 last resort definition can make well-formed messages
+    // to be rejected because they use not compatible "raw" value,
+    // and different vendors may define different sub-options.
+    // The option definition should be applied to avoid these problems,
+    // for instance by defining at the global scope the option as binary.
+    // In client-classes the option may be redefined as carrying vendor
+    // dependent sub-options.
     "option-def": [ {
         "name": "vendor-encapsulated-options",
         "code": 43,
diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml
index 1d3b06e729..cd1e6b3455 100644
--- a/doc/guide/dhcp4-srv.xml
+++ b/doc/guide/dhcp4-srv.xml
@@ -1527,10 +1527,105 @@ It is merely echoed by the server
       Options with code between 224 and 254 are reserved for private use.
       They can be defined at the global scope or at client class local
       scope: this allows to use option definitions depending on context
-      and to set option data accordingly.
+      and to set option data accordingly. For instance to configure
+      an old PXEClient vendor:
+<screen>
+"Dhcp4": {
+    "client-class": [
+        {
+            <userinput>"name": "pxeclient",
+            "test": "option[vendor-class-identifier].text == 'PXEClient'",
+            "option-def": [
+                {
+                    "name": "configfile",
+                    "code": 209,
+                    "type": "string"
+                }
+            ],</userinput>
+            ...
+        }, ...
+    ],
+    ...
+}
+</screen>
+      </para>
+      <para>
       As the Vendor Specific Information option (code 43) has vendor
       specific format, i.e. can carry either raw binary value or
       sub-options, this mechanism is available for this option too.
+      </para>
+      <para>
+      In the following example taken from a real configuration two vendor
+      classes use the option 43 for different and incompatible purposes:
+<screen>
+"Dhcp4": {
+    "option-def": [
+        {
+            <userinput>"name": "cookie",
+            "code": 1,
+            "type": "string",
+            "space": "APC"
+        },
+        {
+            "name": "mtftp-ip",
+            "code": 1,
+            "type": "ipv4-address",
+            "space": "PXE"
+        },</userinput>
+        ...
+    ],
+    "client-class": [
+        {
+            <userinput>"name": "APC",
+            "test": "(option[vendor-class-identifier].text == 'APC'",
+            "option-def": [
+                {
+                    "name": "vendor-encapsulated-options",
+                    "type": "empty",
+                    "encapsulate": "APC"
+                }
+            ],
+            "option-data": [
+                {
+                    "name": "cookie",
+                    "space": "APC",
+                    "data": "1APC"
+                },
+                {
+                    "name": "vendor-encapsulated-options"
+                },</userinput>
+                ...
+            ],
+            ...
+        },
+        {
+            <userinput>"name": "PXE",
+            "test": "(option[vendor-class-identifier].text == 'PXE'",
+            "option-def": [
+                {
+                    "name": "vendor-encapsulated-options",
+                    "type": "empty",
+                    "encapsulate": "PXE"
+                }
+            ],
+            "option-data": [
+                {
+                    "name": "mtftp-ip",
+                    "space": "PXE",
+                    "data": "0.0.0.0"
+                },
+                {
+                    "name": "vendor-encapsulated-options"
+                },</userinput>
+                ...
+            ],
+            ...
+        },
+        ...
+    ],
+    ...
+}
+</screen>
       </para>
       <para>
       The definition used to decode a VSI option is:
-- 
2.47.2