Commit 98dc6997 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[5068] Doc updated

 - added examples for binary options
 - binary renamed to hex
 - leasequery options clearly marked as not really supported
parent 7feedc09
......@@ -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
......
......@@ -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"
}
]
}
......
......@@ -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">
......@@ -2865,9 +2873,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
......
......@@ -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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment