> <userinput>config add Dhcp6/subnet6[0]/option-data</userinput>
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers"</userinput>
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/code 23</userinput>
- > <userinput>config set Dhcp6/subnet6[0]/option-data[0]/data "2001 0DB8 0001 0000</userinput>
- <userinput>0000 0000 0000 0003"</userinput>
+ > <userinput>config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/subnet6[0]/option-data[0]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3"</userinput>
> <userinput>config commit</userinput></screen>
- (As before, the setting of the "data" element has been split across two
- lines for clarity.)
+ </para>
+
+ <note>
+ <para>
+ In future versions of BIND 10 DHCP, it will not be necessary to specify
+ option code, space and csv-format fields, as those fields will be set
+ automatically.
</para>
+ </note>
+
+
+ <para>
+ Below is a list of currently supported standard DHCPv6 options. The "Name" and "Code"
+ are the values that should be used as a name in the option-data
+ structures. "Type" designates the format of the data: the meanings of
+ the various types is given in <xref linkend="dhcp-types"/>.
+ </para>
+ <para>
+ Some options are designated as arrays, which means that more than one
+ value is allowed in such an option. For example the option dns-servers
+ allows the specification of more than one IPv6 address, so allowing
+ clients to obtain the the addresses of multiple DNS servers.
+ </para>
+
+ <!-- @todo: describe record types -->
+
+ <para>
+ <table border="1" cellpadding="5%" id="dhcp6-std-options-list">
+ <caption>List of standard DHCPv6 options</caption>
+ <thead>
+ <tr><th>Name</th><th>Code</th><th>Type</th><th>Array?</th></tr>
+ <tr></tr>
+ </thead>
+ <tbody>
+ <!-- Our engine uses those options on its own, admin must not configure them on his own
+ <tr><td>clientid</td><td>1</td><td>binary</td><td>false</td></tr>
+ <tr><td>serverid</td><td>2</td><td>binary</td><td>false</td></tr>
+ <tr><td>ia-na</td><td>3</td><td>record</td><td>false</td></tr>
+ <tr><td>ia-ta</td><td>4</td><td>uint32</td><td>false</td></tr>
+ <tr><td>iaaddr</td><td>5</td><td>record</td><td>false</td></tr>
+ <tr><td>oro</td><td>6</td><td>uint16</td><td>true</td></tr> -->
+ <tr><td>preference</td><td>7</td><td>uint8</td><td>false</td></tr>
+
+ <!-- Our engine uses those options on its own, admin must not configure them on his own
+ <tr><td>elapsed-time</td><td>8</td><td>uint16</td><td>false</td></tr>
+ <tr><td>relay-msg</td><td>9</td><td>binary</td><td>false</td></tr>
+ <tr><td>auth</td><td>11</td><td>binary</td><td>false</td></tr>
+ <tr><td>unicast</td><td>12</td><td>ipv6-address</td><td>false</td></tr>
+ <tr><td>status-code</td><td>13</td><td>record</td><td>false</td></tr>
+ <tr><td>rapid-commit</td><td>14</td><td>empty</td><td>false</td></tr>
+ <tr><td>user-class</td><td>15</td><td>binary</td><td>false</td></tr>
+ <tr><td>vendor-class</td><td>16</td><td>record</td><td>false</td></tr>
+ <tr><td>vendor-opts</td><td>17</td><td>uint32</td><td>false</td></tr>
+ <tr><td>interface-id</td><td>18</td><td>binary</td><td>false</td></tr>
+ <tr><td>reconf-msg</td><td>19</td><td>uint8</td><td>false</td></tr>
+ <tr><td>reconf-accept</td><td>20</td><td>empty</td><td>false</td></tr> -->
+ <tr><td>sip-server-dns</td><td>21</td><td>fqdn</td><td>true</td></tr>
+ <tr><td>sip-server-addr</td><td>22</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>dns-servers</td><td>23</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>domain-search</td><td>24</td><td>fqdn</td><td>true</td></tr>
+ <!-- <tr><td>ia-pd</td><td>25</td><td>record</td><td>false</td></tr> -->
+ <!-- <tr><td>iaprefix</td><td>26</td><td>record</td><td>false</td></tr> -->
+ <tr><td>nis-servers</td><td>27</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>nisp-servers</td><td>28</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>nis-domain-name</td><td>29</td><td>fqdn</td><td>true</td></tr>
+ <tr><td>nisp-domain-name</td><td>30</td><td>fqdn</td><td>true</td></tr>
+ <tr><td>sntp-servers</td><td>31</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>information-refresh-time</td><td>32</td><td>uint32</td><td>false</td></tr>
+ <tr><td>bcmcs-server-dns</td><td>33</td><td>fqdn</td><td>true</td></tr>
+ <tr><td>bcmcs-server-addr</td><td>34</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>geoconf-civic</td><td>36</td><td>record</td><td>false</td></tr>
+ <tr><td>remote-id</td><td>37</td><td>record</td><td>false</td></tr>
+ <tr><td>subscriber-id</td><td>38</td><td>binary</td><td>false</td></tr>
+ <tr><td>client-fqdn</td><td>39</td><td>record</td><td>false</td></tr>
+ <tr><td>pana-agent</td><td>40</td><td>ipv6-address</td><td>true</td></tr>
+ <tr><td>new-posix-timezone</td><td>41</td><td>string</td><td>false</td></tr>
+ <tr><td>new-tzdb-timezone</td><td>42</td><td>string</td><td>false</td></tr>
+ <tr><td>ero</td><td>43</td><td>uint16</td><td>true</td></tr>
+ <tr><td>lq-query</td><td>44</td><td>record</td><td>false</td></tr>
+ <tr><td>client-data</td><td>45</td><td>empty</td><td>false</td></tr>
+ <tr><td>clt-time</td><td>46</td><td>uint32</td><td>false</td></tr>
+ <tr><td>lq-relay-data</td><td>47</td><td>record</td><td>false</td></tr>
+ <tr><td>lq-client-link</td><td>48</td><td>ipv6-address</td><td>true</td></tr>
+ </tbody>
+ </table>
+ </para>
+ </section>
+
+ <section id="dhcp6-custom-options">
+ <title>Custom DHCPv6 options</title>
+ <para>It is also possible to define options other than the standard ones.
+ Assume that we want to define a new DHCPv6 option called "foo" which will have
+ code 100 and will convey a single unsigned 32 bit integer value. We can define
+ such an option by using the following commands:
+ <screen>
+ > <userinput>config add Dhcp6/option-def</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/code 100</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/type "uint32"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
+ > <userinput>config commit</userinput></screen>
+ The "false" value of the "array" parameter determines that the option
+ does NOT comprise an array of "uint32" values but rather a single value.
+ Two other parameters have been left blank: "record-types" and "encapsulate".
+ The former specifies the comma separated list of option data fields if the
+ option comprises a record of data fields. The "record-fields" value should
+ be non-empty if the "type" is set to "record". Otherwise it must be left
+ blank. The latter parameter specifies the name of the option space being
+ encapsulated by the particular option. If the particular option does not
+ encapsulate any option space it should be left blank.
+ Note that the above set of comments define the format of the new option and do not
+ set its values.
+ </para>
+ <para>Once the new option format is defined, its value is set
+ in the same way as for a standard option. For example the following
+ commands set a global value that applies to all subnets.
+ <screen>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/code 100</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/data "12345"</userinput>
+ > <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>New options can take more complex forms than simple use of
+ primitives (uint8, string, ipv6-address etc): it is possible to
+ define an option comprising a number of existing primitives.
+ </para>
+ <para>
+ Assume we
+ want to define a new option that will consist of an IPv6
+ address, followed by unsigned 16 bit integer, followed by a text
+ string. Such an option could be defined in the following way:
+ <screen>
+ > <userinput>config add Dhcp6/option-def</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/name "bar"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/code 101</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
+ </screen>
+ The "type" is set to "record" to indicate that the option contains
+ multiple values of different types. These types are given as a comma-separated
+ list in the "record-types" field and should be those listed in <xref linkend="dhcp-types"/>.
+ </para>
+ <para>
+ The values of the option are set as follows:
+ <screen>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/name "bar"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/code 101</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"</userinput>
+ > <userinput>config commit</userinput></screen>
+ </para>
+ "csv-format" is set "true" to indicate that the "data" field comprises a command-separated
+ list of values. The values in the "data" must correspond to the types set in
+ the "record-types" field of the option definition.
+ </section>
+
+ <section id="dhcp6-vendor-opts">
+ <title>DHCPv6 vendor specific options</title>
+ <para>
+ Currently there are three option spaces defined: dhcp4 (to be used
+ in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there is also
+ vendor-opts-space, which is empty by default, but options can be
+ defined in it. Those options are called vendor-specific information
+ options. The following examples show how to define an option "foo"
+ with code 1 that consists of an IPv6 address, an unsigned 16 bit integer
+ and a string. The "foo" option is conveyed in a vendor specific
+ information option. This option comprises a single uint32 value
+ that is set to "12345". The sub-option "foo" follows the data
+ field holding this value.
+ <screen>
+ > <userinput>config add Dhcp6/option-def</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/space "vendor-opts-space"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/encapsulates ""</userinput>
+ > <userinput>config commit</userinput>
+ </screen>
+ (Note that the option space is set to "vendor-opts-space".)
+ Once the option format is defined, the next step is to define actual values
+ for that option:
+ <screen>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/space "vendor-opts-space"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"</userinput>
+ > <userinput>config commit</userinput></screen>
+ We should also define values for the vendor-opts, that will convey our option foo.
+ <screen>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/name "vendor-opts"</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/code 17</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/data "12345"</userinput>
+ > <userinput>config commit</userinput></screen>
+ </para>
+ </section>
+
+ <section id="dhcp6-option-spaces">
+ <title>Nested DHCPv6 options (custom option spaces)</title>
+ <para>It is sometimes useful to define completely new option
+ spaces. This is useful if the user wants his new option to
+ convey sub-options that use separate numbering scheme, for
+ example sub-options with codes 1 and 2. Those option codes
+ conflict with standard DHCPv6 options, so a separate option
+ space must be defined.
+ </para>
+ <para>Note that it is not required to create new option space when
+ defining sub-options for a standard option because it is by
+ default created if the standard option is meant to convey
+ any sub-options (see <xref linkend="dhcp6-vendor-opts"/>).
+ </para>
+ <para>
+ Assume that we want to have a DHCPv6 option called "container"
+ with code 102 that conveys two sub-options with codes 1 and 2.
+ First we need to define the new sub-options:
+ <screen>
+ > <userinput>config add Dhcp6/option-def</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/name "subopt1"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/space "isc"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/type "ipv6-address"</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/array false</userinput>
+ > <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
+ > <userinput>config commit</userinput>
+ > <userinput></userinput>
+ > <userinput>config add Dhcp6/option-def</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/name "subopt2"</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/code 2</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/space "isc"</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/type "string"</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/record-types ""</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/array false</userinput>
+ > <userinput>config set Dhcp6/option-def[1]/encapsulate ""</userinput>
+ > <userinput>config commit</userinput>
+ </screen>
+ Note that we have defined the options to belong to a new option space
+ (in this case, "isc").
+ </para>
+ <para>
+ The next step is to define a regular DHCPv6 option and specify that it
+ should include options from the isc option space:
+ <screen>
+ > <userinput>config add Dhcp6/option-def</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/name "container"</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/code 102</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/type "empty"</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/array false</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/record-types ""</userinput>
+ > <userinput>config set Dhcp6/option-def[2]/encapsulate "isc"</userinput>
+ > <userinput>config commit</userinput>
+ </screen>
+ The name of the option space in which the sub-options are defined
+ is set in the "encapsulate" field. The "type" field is set to "empty"
+ which imposes that this option does not carry any data other than
+ sub-options.
+ </para>
+ <para>
+ Finally, we can set values for the new options:
+ <screen>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/name "subopt1"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/space "isc"</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[0]/data "2001:db8::abcd"</userinput>
+ > <userinput>config commit</userinput>
+ > <userinput></userinput>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/name "subopt2"</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/space "isc"</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/code 2</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[1]/data "Hello world"</userinput>
+ > <userinput>config commit</userinput>
+ > <userinput></userinput>
+ > <userinput>config add Dhcp6/option-data</userinput>
+ > <userinput>config set Dhcp6/option-data[2]/name "container"</userinput>
+ > <userinput>config set Dhcp6/option-data[2]/space "dhcp6"</userinput>
+ > <userinput>config set Dhcp6/option-data[2]/code 102</userinput>
+ > <userinput>config set Dhcp6/option-data[2]/csv-format true</userinput>
+ > <userinput>config set Dhcp6/option-data[2]/data ""</userinput>
+ > <userinput>config commit</userinput>
+ </screen>
+ Even though the "container" option does not carry any data except
+ sub-options, the "data" field must be explictly set to an empty value.
+ This is required because in the current version of BIND 10 DHCP, the
+ default configuration values are not propagated to the configuration parsers:
+ if the "data" is not set the parser will assume that this
+ parameter is not specified and an error will be reported.
+ </para>
+ <para>Note that it is possible to create an option which carries some data
+ in addition to the sub-options defined in the encapsulated option space. For example,
+ if the "container" option from the previous example was required to carry an uint16
+ value as well as the sub-options, the "type" value would have to be set to "uint16" in
+ the option definition. (Such an option would then have the following
+ data structure: DHCP header, uint16 value, sub-options.) The value specified
+ with the "data" parameter - which should be a valid integer enclosed in quotes,
+ e.g. "123" - would then be assigned to the uint16 field in the "container" option.
+ </para>
</section>
-
+
<section id="dhcp6-config-subnets">
<title>Subnet Selection</title>
<para>
projects / thirdparty / kea.git / commitdiff
