[master] Merge branch 'trac5068' (options update in docs)

doc/examples/kea4/multiple-options.json

@@ -38,7 +38,6 @@
   "subnet4": [
     {
        "subnet": "192.0.2.0/24",
-       "interface": "ethX",
        "option-data": [
             // When specifying options, you typically need to specify
             // one of (name or code) and data. The full option specification
@@ -51,7 +50,7 @@
             // {
             //     "name": "domain-name-servers",
             //     "code": 6,
-            //     "csv-format": "true",
+            //     "csv-format": true,
             //     "space": "dhcp4",
             //     "data": "192.0.2.1, 192.0.2.2"
             // }
@@ -100,6 +99,16 @@
              "name": "domain-search",
              "data": "mydomain.example.com, example.com"
          },
+
+           // Options can also be specified using hexadecimal format.
+           // This should be avoided if possible, because Kea ability to
+           // validate correctness is limited when using hex values.
+         {
+             "name": "broadcast-address",
+             "csv-format": false,
+             "data": "ffff8000"
+         },
+
             // String options that have a comma in their values need to have
             // it escaped (i.e. each comma is preceded by two backslashes).
             // That's because commas are reserved for separating fields in

doc/examples/kea6/multiple-options.json

@@ -56,7 +56,7 @@
             // {
             //     "name": "dns-servers",
             //     "code": 23,
-            //     "csv-format": "true",
+            //     "csv-format": true,
             //     "space": "dhcp6",
             //     "data": "2001:db8:2::45, 2001:db8:2::100"
             // }
@@ -78,6 +78,15 @@
                 "data": "2001:db8:1:0:ff00::1"
             },
 
+            // Options can also be specified using hexadecimal format.
+            // This should be avoided if possible, because Kea ability to
+            // validate correctness is limited when using hex values.
+            {
+                "name": "sntp-servers",
+                "csv-format": false,
+                "data": "20010db8000000000000000000000001"
+            },
+
             // String options that have a comma in their values need to have
             // it escaped (i.e. each comma is preceded by two backslashes).
             // That's because commas are reserved for separating fields in
@@ -144,7 +153,7 @@
              "option-data": [
                {
                    "code": 12,
-                   "data": "3001:cafe::12:"
+                   "data": "3001:cafe::12"
                }
              ]
          }

doc/guide/dhcp4-srv.xml

@@ -1102,6 +1102,12 @@ temporarily override a list of interface names and listen on all interfaces.
     ],
     ...
 }</screen>
+    </para>
+
+       <para>
+       Care should be taken
+       to use proper encoding when using hexadecimal format as Kea's ability
+       to validate data correctness in hexadecimal is limited.
       </para>
 
       <para>
@@ -1341,12 +1347,12 @@ This rather belong to the DDNS configuration
 <row><entry>dhcp-renewal-time</entry><entry>58</entry><entry>uint32</entry><entry>false</entry><entry>true</entry></row>
 <row><entry>dhcp-rebinding-time</entry><entry>59</entry><entry>uint32</entry><entry>false</entry><entry>true</entry></row>
 -->
-<row><entry>vendor-class-identifier</entry><entry>60</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>vendor-class-identifier</entry><entry>60</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
 <!-- Client identifier should not be configured by a user.
-<row><entry>dhcp-client-identifier</entry><entry>61</entry><entry>binary</entry><entry>false</entry><entry>true</entry></row>
+<row><entry>dhcp-client-identifier</entry><entry>61</entry><entry>hex</entry><entry>false</entry><entry>true</entry></row>
 -->
 <row><entry>nwip-domain-name</entry><entry>62</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
-<row><entry>nwip-suboptions</entry><entry>63</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>nwip-suboptions</entry><entry>63</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>nisplus-domain-name</entry><entry>64</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>nisplus-servers</entry><entry>65</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>tftp-server-name</entry><entry>66</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
@@ -1360,7 +1366,7 @@ This rather belong to the DDNS configuration
 <row><entry>irc-server</entry><entry>74</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>streettalk-server</entry><entry>75</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>streettalk-directory-assistance-server</entry><entry>76</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
-<row><entry>user-class</entry><entry>77</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>user-class</entry><entry>77</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>slp-directory-agent</entry><entry>78</entry><entry>record (boolean, ipv4-address)</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>slp-service-scope</entry><entry>79</entry><entry>record (boolean, string)</entry><entry>false</entry><entry>false</entry></row>
 <!-- The Client FQDN option value is not explicitly configured.
@@ -1377,7 +1383,7 @@ It is merely echoed by the server
 <row><entry>bcms-controller-names</entry><entry>88</entry><entry>fqdn</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>bcms-controller-address</entry><entry>89</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
 <!-- Authentication option requires special processing
-<row><entry>authenticate</entry><entry>90</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>authenticate</entry><entry>90</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
 -->
 <!-- Last transaction time and associated IP is dynamically calculated
 <row><entry>client-last-transaction-time</entry><entry>91</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
@@ -1385,9 +1391,9 @@ It is merely echoed by the server
 -->
 <row><entry>client-system</entry><entry>93</entry><entry>uint16</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>client-ndi</entry><entry>94</entry><entry>record (uint8, uint8, uint8)</entry><entry>false</entry><entry>false</entry></row>
-<row><entry>uuid-guid</entry><entry>97</entry><entry>record (uint8, binary)</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>uuid-guid</entry><entry>97</entry><entry>record (uint8, hex)</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>uap-servers</entry><entry>98</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
-<row><entry>geoconf-civic</entry><entry>99</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>geoconf-civic</entry><entry>99</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>pcode</entry><entry>100</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>tcode</entry><entry>101</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>netinfo-server-address</entry><entry>112</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
@@ -1397,8 +1403,8 @@ It is merely echoed by the server
 <row><entry>name-service-search</entry><entry>117</entry><entry>uint16</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>subnet-selection</entry><entry>118</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>domain-search</entry><entry>119</entry><entry>fqdn</entry><entry>true</entry><entry>false</entry></row>
-<row><entry>vivco-suboptions</entry><entry>124</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
-<row><entry>vivso-suboptions</entry><entry>125</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>vivco-suboptions</entry><entry>124</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
+<row><entry>vivso-suboptions</entry><entry>125</entry><entry>hex</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>pana-agent</entry><entry>136</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
 <row><entry>v4-lost</entry><entry>137</entry><entry>fqdn</entry><entry>false</entry><entry>false</entry></row>
 <row><entry>capwap-ac-v4</entry><entry>138</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
@@ -1423,7 +1429,7 @@ It is merely echoed by the server
             <row><entry>Name</entry><entry>Meaning</entry></row>
           </thead>
           <tbody>
-            <row><entry>binary</entry><entry>An arbitrary string of bytes, specified as a set of hexadecimal digits.</entry></row>
+            <row><entry>hex</entry><entry>An arbitrary string of bytes, specified as a set of hexadecimal digits.</entry></row>
             <row><entry>boolean</entry><entry>Boolean value with allowed values true or false</entry></row>
             <row><entry>empty</entry><entry>No value, data is carried in suboptions</entry></row>
             <row><entry>fqdn</entry><entry>Fully qualified domain name (e.g. www.example.com)</entry></row>
@@ -2563,13 +2569,15 @@ It is merely echoed by the server
         If the client sent no name, generate one for the client.
       </para></listitem>
       </itemizedlist>
-    <note>
+      <note>
+        <para>
     Note that formerly, this parameter was a boolean and permitted only values
     of <command>true</command> and <command>false</command>.  Boolean values
     have been deprecated and are no longer accepted.  If you are currently using
     booleans, you must replace them with the desired mode name. A value of
     <command>true</command> maps to <command>"when-present"</command>, while
     <command>false</command> maps to <command>"never"</command>.
+        </para>
     </note>
 
       For example, To instruct kea-dhcp4 to always generate the FQDN for a
@@ -2616,7 +2624,6 @@ It is merely echoed by the server
     ...
 }
 </screen>
-      </section>
       <para>
       When generating a name, kea-dhcp4 will construct name of the format:
       </para>
@@ -2632,6 +2639,7 @@ It is merely echoed by the server
       <para>
         myhost-172-16-1-10.example.com.
       </para>
+      </section>
     </section>
 
     <section id="dhcp4-next-server">
@@ -2875,9 +2883,10 @@ It is merely echoed by the server
       (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: both the
-      DHCPv4 and DHCPv6 sides should be running the same version of Kea.
+        <para>DHCPv4-over-DHCPv6 support is experimental and the
+        details of the inter-process communication can change: both
+        the DHCPv4 and DHCPv6 sides should be running the same version
+        of Kea.</para>
       </note>
       <para>
       The <command>dhcp4o6-port</command> global parameter specifies

doc/guide/dhcp6-srv.xml

@@ -986,7 +986,7 @@ temporarily override a list of interface names and listen on all interfaces.
         ...
     ]
 }
-</screen>
+        </screen>
        </para>
        <note><para>
        The value for the setting of the "data" element is split across two
@@ -1231,8 +1231,8 @@ temporarily override a list of interface names and listen on all interfaces.
         </thead>
         <tbody>
 <!-- Our engine uses those options on its own, admin must not configure them on his own
-<row><entry>clientid</entry><entry>1</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>serverid</entry><entry>2</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>clientid</entry><entry>1</entry><entry>hex</entry><entry>false</entry></row>
+<row><entry>serverid</entry><entry>2</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>ia-na</entry><entry>3</entry><entry>record</entry><entry>false</entry></row>
 <row><entry>ia-ta</entry><entry>4</entry><entry>uint32</entry><entry>false</entry></row>
 <row><entry>iaaddr</entry><entry>5</entry><entry>record</entry><entry>false</entry></row>
@@ -1241,20 +1241,20 @@ temporarily override a list of interface names and listen on all interfaces.
 
 <!-- Our engine uses those options on its own, admin must not configure them on his own
 <row><entry>elapsed-time</entry><entry>8</entry><entry>uint16</entry><entry>false</entry></row>
-<row><entry>relay-msg</entry><entry>9</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>auth</entry><entry>11</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>relay-msg</entry><entry>9</entry><entry>hex</entry><entry>false</entry></row>
+<row><entry>auth</entry><entry>11</entry><entry>hex</entry><entry>false</entry></row>
 -->
 <row><entry>unicast</entry><entry>12</entry><entry>ipv6-address</entry><entry>false</entry></row>
 <!--
 <row><entry>status-code</entry><entry>13</entry><entry>record</entry><entry>false</entry></row>
 <row><entry>rapid-commit</entry><entry>14</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>user-class</entry><entry>15</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>user-class</entry><entry>15</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>vendor-class</entry><entry>16</entry><entry>record</entry><entry>false</entry></row>
 -->
 <!-- Vendor-specific Information is configurable by the administrator -->
 <row><entry>vendor-opts</entry><entry>17</entry><entry>uint32</entry><entry>false</entry></row>
 <!--
-<row><entry>interface-id</entry><entry>18</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>interface-id</entry><entry>18</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>reconf-msg</entry><entry>19</entry><entry>uint8</entry><entry>false</entry></row>
 <row><entry>reconf-accept</entry><entry>20</entry><entry>empty</entry><entry>false</entry></row> -->
 -->
@@ -1272,22 +1272,22 @@ temporarily override a list of interface names and listen on all interfaces.
 <row><entry>information-refresh-time</entry><entry>32</entry><entry>uint32</entry><entry>false</entry></row>
 <row><entry>bcmcs-server-dns</entry><entry>33</entry><entry>fqdn</entry><entry>true</entry></row>
 <row><entry>bcmcs-server-addr</entry><entry>34</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>geoconf-civic</entry><entry>36</entry><entry>record (uint8, uint16, binary)</entry><entry>false</entry></row>
-<row><entry>remote-id</entry><entry>37</entry><entry>record (uint32, binary)</entry><entry>false</entry></row>
-<row><entry>subscriber-id</entry><entry>38</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>geoconf-civic</entry><entry>36</entry><entry>record (uint8, uint16, hex)</entry><entry>false</entry></row>
+<row><entry>remote-id</entry><entry>37</entry><entry>record (uint32, hex)</entry><entry>false</entry></row>
+<row><entry>subscriber-id</entry><entry>38</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>client-fqdn</entry><entry>39</entry><entry>record (uint8, fqdn)</entry><entry>false</entry></row>
 <row><entry>pana-agent</entry><entry>40</entry><entry>ipv6-address</entry><entry>true</entry></row>
 <row><entry>new-posix-timezone</entry><entry>41</entry><entry>string</entry><entry>false</entry></row>
 <row><entry>new-tzdb-timezone</entry><entry>42</entry><entry>string</entry><entry>false</entry></row>
 <row><entry>ero</entry><entry>43</entry><entry>uint16</entry><entry>true</entry></row>
-<row><entry>lq-query</entry><entry>44</entry><entry>record (uint8, ipv6-address)</entry><entry>false</entry></row>
-<row><entry>client-data</entry><entry>45</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>clt-time</entry><entry>46</entry><entry>uint32</entry><entry>false</entry></row>
-<row><entry>lq-relay-data</entry><entry>47</entry><entry>record (ipv6-address, binary)</entry><entry>false</entry></row>
-<row><entry>lq-client-link</entry><entry>48</entry><entry>ipv6-address</entry><entry>true</entry></row>
+<row><entry>lq-query (1)</entry><entry>44</entry><entry>record (uint8, ipv6-address)</entry><entry>false</entry></row>
+<row><entry>client-data (1)</entry><entry>45</entry><entry>empty</entry><entry>false</entry></row>
+<row><entry>clt-time (1)</entry><entry>46</entry><entry>uint32</entry><entry>false</entry></row>
+<row><entry>lq-relay-data (1)</entry><entry>47</entry><entry>record (ipv6-address, hex)</entry><entry>false</entry></row>
+<row><entry>lq-client-link (1)</entry><entry>48</entry><entry>ipv6-address</entry><entry>true</entry></row>
 <row><entry>v6-lost</entry><entry>51</entry><entry>fqdn</entry><entry>false</entry></row>
 <row><entry>capwap-ac-v6</entry><entry>52</entry><entry>ipv6-address</entry><entry>true</entry></row>
-<row><entry>relay-id</entry><entry>53</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>relay-id</entry><entry>53</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>v6-access-domain</entry><entry>57</entry><entry>fqdn</entry><entry>false</entry></row>
 <row><entry>sip-ua-cs-list</entry><entry>58</entry><entry>fqdn</entry><entry>true</entry></row>
 <row><entry>bootfile-url</entry><entry>59</entry><entry>string</entry><entry>false</entry></row>
@@ -1297,19 +1297,26 @@ temporarily override a list of interface names and listen on all interfaces.
 <row><entry>aftr-name</entry><entry>64</entry><entry>fqdn</entry><entry>false</entry></row>
 <row><entry>erp-local-domain-name</entry><entry>65</entry><entry>fqdn</entry><entry>false</entry></row>
 <row><entry>rsoo</entry><entry>66</entry><entry>empty</entry><entry>false</entry></row>
-<row><entry>pd-exclude</entry><entry>67</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>pd-exclude</entry><entry>67</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>rdnss-selection</entry><entry>74</entry><entry>record (ipv6-address, uint8, fqdn)</entry><entry>true</entry></row>
-<row><entry>client-linklayer-addr</entry><entry>79</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>client-linklayer-addr</entry><entry>79</entry><entry>hex</entry><entry>false</entry></row>
 <row><entry>link-address</entry><entry>80</entry><entry>ipv6-address</entry><entry>false</entry></row>
 <row><entry>solmax-rt</entry><entry>82</entry><entry>uint32</entry><entry>false</entry></row>
 <row><entry>inf-max-rt</entry><entry>83</entry><entry>uint32</entry><entry>false</entry></row>
-<!-- <row><entry>dhcpv4-message</entry><entry>87</entry><entry>binary</entry><entry>false</entry></row> -->
+<!-- <row><entry>dhcpv4-message</entry><entry>87</entry><entry>hex</entry><entry>false</entry></row> -->
 <row><entry>dhcp4o6-server-addr</entry><entry>88</entry><entry>ipv6-address</entry><entry>true</entry></row>
 <row><entry>v6-captive-portal</entry><entry>103</entry><entry>string</entry><entry>false</entry></row>
 <row><entry>ipv6-address-andsf</entry><entry>143</entry><entry>ipv6-address</entry><entry>true</entry></row>
         </tbody>
         </tgroup>
       </table>
+      Options marked with (1) have option definitions, but the logic
+      behind them is not implemented. That means that technically Kea
+      knows how to parse them in incoming message or how to send them
+      if configured to do so, but not what to do with them. Since the
+      related RFCs require certain processing, the support for those
+      options is non-functional. However, it may be useful in some
+      limited lab testing, hence the definition formats are listed here.
     </para>
 
     <para>
@@ -1324,10 +1331,10 @@ temporarily override a list of interface names and listen on all interfaces.
           <row><entry>Name</entry><entry>Code</entry><entry>Type</entry><entry>Array?</entry></row>
         </thead>
         <tbody>
-<row><entry>public-key</entry><entry>701</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>certificate</entry><entry>702</entry><entry>binary</entry><entry>false</entry></row>
-<row><entry>signature</entry><entry>703</entry><entry>record (uint8, uint8, binary)</entry><entry>false</entry></row>
-<row><entry>timestamp</entry><entry>704</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>public-key</entry><entry>701</entry><entry>hex</entry><entry>false</entry></row>
+<row><entry>certificate</entry><entry>702</entry><entry>hex</entry><entry>false</entry></row>
+<row><entry>signature</entry><entry>703</entry><entry>record (uint8, uint8, hex)</entry><entry>false</entry></row>
+<row><entry>timestamp</entry><entry>704</entry><entry>hex</entry><entry>false</entry></row>
         </tbody>
         </tgroup>
       </table>