BIND 10 master, updated. 1d0c2004865d1bf322bf78d13630d992e39179fd [master] Merge branch 'trac2657'
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri Feb 8 17:32:13 UTC 2013
The branch, master has been updated
via 1d0c2004865d1bf322bf78d13630d992e39179fd (commit)
via b4de3233542a0c98c04c0cf730bd8222efe897b7 (commit)
via d85b2e22c5c45050d3191ee73c508bbd3cd1251f (commit)
via 8b2f7c325534431cb4f6cca82c5d314583e03248 (commit)
via 6dc113cc0e20a4781ad0f991871966d244371440 (commit)
via 28c7d972110b86833c31631d563b07a2824efbab (commit)
via 3c200a3decdd5bbc30bbdb9c81f9f206eda98ad9 (commit)
via 83b06fb184c17f70a28ab307347e9eb075ee048d (commit)
via 521189be3a1dc89fc9010dfa9fa13a31ee233a38 (commit)
via 1e2111996aa44a583fcdf0997a6aa170542f3ea2 (commit)
via fc03d665a777c47920a85bae41f3e359c61fa42e (commit)
via 2a9656fb9ac69e87273f14f4a6807986ee9739a8 (commit)
via 3d1ea31fe2461f28b7337c78623834eb987c73a5 (commit)
via 388c202a9b3c95f3d8d1aa0c76803b1f398974f3 (commit)
via 368ceac8bfb49a0bd4c0a0c98fe624d623de9c6d (commit)
from 59c744cf4838c919abe8763501208e02aff9526d (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 1d0c2004865d1bf322bf78d13630d992e39179fd
Merge: 59c744c b4de323
Author: Marcin Siodelski <marcin at isc.org>
Date: Fri Feb 8 18:29:27 2013 +0100
[master] Merge branch 'trac2657'
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 971 ++++++++++++++++++++++++++++++++++++++++----
1 file changed, 900 insertions(+), 71 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index a16bf3b..0d1913f 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -7,7 +7,7 @@
]>
<!--
- - Copyright (C) 2010-2012 Internet Systems Consortium, Inc. ("ISC")
+ - Copyright (C) 2010-2013 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
@@ -740,17 +740,13 @@ as a dependency earlier -->
</listitem>
</varlistentry>
- <varlistentry>
- <term>--with-dhcp-mysql</term>
- <listitem>
- <simpara>Enable MySQL support for BIND 10 DHCP. For notes on configuring
- and building DHCP with MySQL see <xref linkend="dhcp-install-configure">.</xref>
- </simpara>
- </listitem>
- </varlistentry>
-
</variablelist>
-
+ <note>
+ <para>
+ For additional instructions concerning the building and installation of
+ BIND 10 DHCP, see <xref linkend="dhcp-install-configure"/>.
+ </para>
+ </note>
</para>
<!-- TODO: lcov -->
@@ -3363,7 +3359,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
Build and install BIND 10 as described in <xref linkend="installation"/>, with
the following modification: to enable the MySQL database code, at the
"configure" step (see <xref linkend="configure"/>), specify the location of the
- MySQL configuration program "mysql_config" with the "--with-mysql-config" switch,
+ MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch,
i.e.
<screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
...if MySQL was installed in the default location, or:
@@ -3609,25 +3605,495 @@ Dhcp4/subnet4 [] list (default)
network configurations. If you want to avoid this, please use the "min-max" notation.
</para>
</section>
+
+ <section id="dhcp4-std-options">
+ <title>Standard DHCPv4 options</title>
+ <para>
+ One of the major features of DHCPv4 server is to provide configuration
+ options to clients. Although there are several options that require
+ special behavior, most options are sent by the server only if the client
+ explicitly requested them. The following example shows how to
+ configure DNS servers, which is one of the most frequently used
+ options. Options specified in this way are considered global and apply
+ to all configured subnets.
+
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ The first line creates new entry in option-data table. It
+ contains information on all global options that the server is
+ supposed to configure in all subnets. The second line specifies
+ option name. For a complete list of currently supported names,
+ see <xref linkend="dhcp4-std-options-list"/> below.
+ The third line specifies option code, which must match one of the
+ values from that list. Line 4 specifies option space, which must always
+ be set to "dhcp4" as these are standard DHCPv4 options. For
+ other option spaces, including custom option spaces, see <xref
+ linkend="dhcp4-option-spaces"/>. The fifth line specifies the format in
+ which the data will be entered: use of CSV (comma
+ separated values) is recommended. The sixth line gives the actual value to
+ be sent to clients. Data is specified as a normal text, with
+ values separated by commas if more than one value is
+ allowed.
+ </para>
+
+ <para>
+ Options can also be configured as hexadecimal values. If csv-format is
+ set to false, option data must be specified as a hex string. The
+ following commands configure the domain-name-servers option for all
+ subnets with the following addresses: 192.0.3.1 and 192.0.3.2.
+ Note that csv-format is set to false.
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format false</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02"</userinput>
+> <userinput>config commit</userinput>
+ </screen>
+ </para>
+
+ <para>
+ It is possible to override options on a per-subnet basis. If
+ clients connected to most of your subnets are expected to get the
+ same values of a given option, you should use global options: you
+ can then override specific values for a small number of subnets.
+ On the other hand, if you use different values in each subnet,
+ it does not make sense to specify global option values
+ (Dhcp4/option-data), rather you should set only subnet-specific values
+ (Dhcp4/subnet[X]/option-data[Y]).
+ </para>
+ <para>
+ The following commands override the global
+ DNS servers option for a particular subnet, setting a single DNS
+ server with address 2001:db8:1::3.
+ <screen>
+> <userinput>config add Dhcp4/subnet4[0]/option-data</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/code 6</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <note>
+ <para>In a future version of Kea, it will not be necessary to specify
+ the option code, space and csv-format fields as they will be set
+ automatically.</para>
+ </note>
+
+ <para>
+ Below is a list of currently supported standard DHCPv4 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 time-servers
+ allows the specification of more than one IPv4 address, so allowing
+ clients to obtain the the addresses of multiple NTP servers.
+ </para>
+ <!-- @todo: describe record types -->
+
+ <para>
+ <table border="1" cellpadding="5%" id="dhcp4-std-options-list">
+ <caption>List of standard DHCPv4 options</caption>
+ <thead>
+ <tr><th>Name</th><th>Code</th><th>Type</th><th>Array?</th></tr>
+ </thead>
+ <tbody>
+<tr><td>subnet-mask</td><td>1</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>time-offset</td><td>2</td><td>uint32</td><td>false</td></tr>
+<tr><td>routers</td><td>3</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>time-servers</td><td>4</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>name-servers</td><td>5</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>domain-name-servers</td><td>6</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>log-servers</td><td>7</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>cookie-servers</td><td>8</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>lpr-servers</td><td>9</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>impress-servers</td><td>10</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>resource-location-servers</td><td>11</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>host-name</td><td>12</td><td>string</td><td>false</td></tr>
+<tr><td>boot-size</td><td>13</td><td>uint16</td><td>false</td></tr>
+<tr><td>merit-dump</td><td>14</td><td>string</td><td>false</td></tr>
+<tr><td>domain-name</td><td>15</td><td>fqdn</td><td>false</td></tr>
+<tr><td>swap-server</td><td>16</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>root-path</td><td>17</td><td>string</td><td>false</td></tr>
+<tr><td>extensions-path</td><td>18</td><td>string</td><td>false</td></tr>
+<tr><td>ip-forwarding</td><td>19</td><td>boolean</td><td>false</td></tr>
+<tr><td>non-local-source-routing</td><td>20</td><td>boolean</td><td>false</td></tr>
+<tr><td>policy-filter</td><td>21</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>max-dgram-reassembly</td><td>22</td><td>uint16</td><td>false</td></tr>
+<tr><td>default-ip-ttl</td><td>23</td><td>uint8</td><td>false</td></tr>
+<tr><td>path-mtu-aging-timeout</td><td>24</td><td>uint32</td><td>false</td></tr>
+<tr><td>path-mtu-plateau-table</td><td>25</td><td>uint16</td><td>true</td></tr>
+<tr><td>interface-mtu</td><td>26</td><td>uint16</td><td>false</td></tr>
+<tr><td>all-subnets-local</td><td>27</td><td>boolean</td><td>false</td></tr>
+<tr><td>broadcast-address</td><td>28</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>perform-mask-discovery</td><td>29</td><td>boolean</td><td>false</td></tr>
+<tr><td>mask-supplier</td><td>30</td><td>boolean</td><td>false</td></tr>
+<tr><td>router-discovery</td><td>31</td><td>boolean</td><td>false</td></tr>
+<tr><td>router-solicitation-address</td><td>32</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>static-routes</td><td>33</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>trailer-encapsulation</td><td>34</td><td>boolean</td><td>false</td></tr>
+<tr><td>arp-cache-timeout</td><td>35</td><td>uint32</td><td>false</td></tr>
+<tr><td>ieee802-3-encapsulation</td><td>36</td><td>boolean</td><td>false</td></tr>
+<tr><td>default-tcp-ttl</td><td>37</td><td>uint8</td><td>false</td></tr>
+<tr><td>tcp-keepalive-internal</td><td>38</td><td>uint32</td><td>false</td></tr>
+<tr><td>tcp-keepalive-garbage</td><td>39</td><td>boolean</td><td>false</td></tr>
+<tr><td>nis-domain</td><td>40</td><td>string</td><td>false</td></tr>
+<tr><td>nis-servers</td><td>41</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>ntp-servers</td><td>42</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>vendor-encapsulated-options</td><td>43</td><td>empty</td><td>false</td></tr>
+<tr><td>netbios-name-servers</td><td>44</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>netbios-dd-server</td><td>45</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>netbios-node-type</td><td>46</td><td>uint8</td><td>false</td></tr>
+<tr><td>netbios-scope</td><td>47</td><td>string</td><td>false</td></tr>
+<tr><td>font-servers</td><td>48</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>x-display-manager</td><td>49</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>dhcp-requested-address</td><td>50</td><td>ipv4-address</td><td>false</td></tr>
+<!-- Lease time should not be configured by a user.
+<tr><td>dhcp-lease-time</td><td>51</td><td>uint32</td><td>false</td></tr>
+-->
+<tr><td>dhcp-option-overload</td><td>52</td><td>uint8</td><td>false</td></tr>
+<!-- Message Type, Server Identifier and Parameter Request List should not be configured by a user.
+<tr><td>dhcp-message-type</td><td>53</td><td>uint8</td><td>false</td></tr>
+<tr><td>dhcp-server-identifier</td><td>54</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>dhcp-parameter-request-list</td><td>55</td><td>uint8</td><td>true</td></tr>
+-->
+<tr><td>dhcp-message</td><td>56</td><td>string</td><td>false</td></tr>
+<tr><td>dhcp-max-message-size</td><td>57</td><td>uint16</td><td>false</td></tr>
+<!-- Renewal and rebinding time should not be configured by a user.
+<tr><td>dhcp-renewal-time</td><td>58</td><td>uint32</td><td>false</td></tr>
+<tr><td>dhcp-rebinding-time</td><td>59</td><td>uint32</td><td>false</td></tr>
+-->
+<tr><td>vendor-class-identifier</td><td>60</td><td>binary</td><td>false</td></tr>
+<!-- Client identifier should not be configured by a user.
+<tr><td>dhcp-client-identifier</td><td>61</td><td>binary</td><td>false</td></tr>
+-->
+<tr><td>nwip-domain-name</td><td>62</td><td>string</td><td>false</td></tr>
+<tr><td>nwip-suboptions</td><td>63</td><td>binary</td><td>false</td></tr>
+<tr><td>user-class</td><td>77</td><td>binary</td><td>false</td></tr>
+<tr><td>fqdn</td><td>81</td><td>record</td><td>false</td></tr>
+<tr><td>dhcp-agent-options</td><td>82</td><td>empty</td><td>false</td></tr>
+<tr><td>authenticate</td><td>90</td><td>binary</td><td>false</td></tr>
+<tr><td>client-last-transaction-time</td><td>91</td><td>uint32</td><td>false</td></tr>
+<tr><td>associated-ip</td><td>92</td><td>ipv4-address</td><td>true</td></tr>
+<tr><td>subnet-selection</td><td>118</td><td>ipv4-address</td><td>false</td></tr>
+<tr><td>domain-search</td><td>119</td><td>binary</td><td>false</td></tr>
+<tr><td>vivco-suboptions</td><td>124</td><td>binary</td><td>false</td></tr>
+<tr><td>vivso-suboptions</td><td>125</td><td>binary</td><td>false</td></tr>
+ </tbody>
+ </table>
+ </para>
+ <para>
+ <table border="1" cellpadding="5%" id="dhcp-types">
+ <caption>List of standard DHCP option types</caption>
+ <thead>
+ <tr><th>Name</th><th>Meaning</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>binary</td><td>An arbitrary string of bytes, specified as a set of hexadecimal digits.</td></tr>
+ <tr><td>boolean</td><td>Boolean value with allowed values true or false</td></tr>
+ <tr><td>empty</td><td>No value, data is carried in suboptions</td></tr>
+ <tr><td>fqdn</td><td>Fully qualified domain name (e.g. www.example.com)</td></tr>
+ <tr><td>ipv4-address</td><td>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</td></tr>
+ <tr><td>ipv6-address</td><td>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</td></tr>
+ <tr><td>record</td><td>Structured data that may comprise any types (except "record" and "empty")</td></tr>
+ <tr><td>string</td><td>Any text</td></tr>
+ <tr><td>uint8</td><td>8 bit unsigned integer with allowed values 0 to 255</td></tr>
+ <tr><td>uint16</td><td>16 bit unsinged integer with allowed values 0 to 65535</td></tr>
+ <tr><td>uint32</td><td>32 bit unsigned integer with allowed values 0 to 4294967295</td></tr>
+ </tbody>
+ </table>
+ </para>
</section>
+ <section id="dhcp4-custom-options">
+ <title>Custom DHCPv4 options</title>
+ <para>It is also possible to define options other than the standard ones.
+ Assume that we want to define a new DHCPv4 option called "foo" which will have
+ code 222 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 Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 222</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "uint32"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/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>
+ <note>
+ <para>
+ In the current release the default values are not propagated to the
+ parser when the new configuration is being set. Therefore, all
+ parameters must be specified at all times, even if their values are
+ left blank.
+ </para>
+ </note>
+
+ <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 Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 222</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/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, ipv4-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 IPv4
+ 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 Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "bar"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 223</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
+> <userinput>config set Dhcp4/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 Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "bar"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 223</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.100, 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="dhcp4-vendor-opts">
+ <title>DHCPv4 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-encapsulated-options-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 IPv4 address, an
+ unsigned 16 bit integer and a string. The "foo" option is conveyed
+ in a vendor specific information option.
+ </para>
+ <para>
+ The first step is to define the format of the option:
+<screen>
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/encapsulates ""</userinput>
+> <userinput>config commit</userinput>
+</screen>
+ (Note that the option space is set to "vendor-encapsulated-options-space".)
+ Once the option format is defined, the next step is to define actual values
+ for that option:
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World"</userinput>
+> <userinput>config commit</userinput></screen>
+ We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo".
+ This is required else the option will not be included in messages sent to the client.
+ <screen>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/code 43</userinput>
+> <userinput>config set Dhcp4/option-data[1]/csv-format false</userinput>
+> <userinput>config set Dhcp4/option-data[1]/data ""</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <note>
+ <para>
+ With this version of BIND 10, the "vendor-encapsulated-options" option
+ must be specified in the configuration although it has no configurable
+ parameters. If it is not specified, the server will assume that it is
+ not configured and will not send it to a client. In the future there
+ will be no need to include this option in the configuration.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="dhcp4-option-spaces">
+
+ <title>Nested DHCPv4 options (custom option spaces)</title>
+ <para>It is sometimes useful to define completely new option
+ space. This is the case when user creates new option in the
+ standard option space ("dhcp4 or "dhcp6") and wants this option
+ to convey sub-options. Thanks to being in the separate space,
+ sub-option codes will have a separate numbering scheme and may
+ overlap with codes of standard options.
+ </para>
+ <para>Note that creation of a new option space when defining
+ sub-options for a standard option is not required, because it is
+ created by default if the standard option is meant to convey any
+ sub-options (see <xref linkend="dhcp4-vendor-opts"/>).
+ </para>
+ <para>
+ Assume that we want to have a DHCPv4 option called "container" with
+ code 222 that conveys two sub-options with codes 1 and 2.
+ First we need to define the new sub-options:
+<screen>
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[0]/name "subopt1"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-def[0]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/type "ipv4-address"</userinput>
+> <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
+> <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
+> <userinput>config commit</userinput>
+
+> <userinput>config add Dhcp4/option-def</userinput>
+> <userinput>config set Dhcp4/option-def[1]/name "subopt2"</userinput>
+> <userinput>config set Dhcp4/option-def[1]/code 2</userinput>
+> <userinput>config set Dhcp4/option-def[1]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-def[1]/type "string"</userinput>
+> <userinput>config set Dhcp4/option-def[1]/record-types ""</userinput>
+> <userinput>config set Dhcp4/option-def[1]/array false</userinput>
+> <userinput>config set Dhcp4/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 DHCPv4 option with our desired
+ code and specify that it should include options from the new option space:
+<screen>
+> <userinput>add Dhcp4/option-def</userinput>
+> <userinput>set Dhcp4/option-def[2]/name "container"</userinput>
+> <userinput>set Dhcp4/option-def[2]/code 222</userinput>
+> <userinput>set Dhcp4/option-def[2]/space "dhcp4"</userinput>
+> <userinput>set Dhcp4/option-def[2]/type "empty"</userinput>
+> <userinput>set Dhcp4/option-def[2]/array false</userinput>
+> <userinput>set Dhcp4/option-def[2]/record-types ""</userinput>
+> <userinput>set Dhcp4/option-def[2]/encapsulate "isc"</userinput>
+> <userinput>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"
+ to indicate 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 Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[0]/name "subopt1"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
+> <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3"</userinput>
+> <userinput>config commit</userinput>
+<userinput></userinput>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[1]/name "subopt2"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/space "isc"</userinput>
+> <userinput>config set Dhcp4/option-data[1]/code 2</userinput>
+> <userinput>config set Dhcp4/option-data[1]/csv-format true</userinput>
+> <userinput>config set Dhcp4/option-data[1]/data "Hello world"</userinput>
+> <userinput>config commit</userinput>
+<userinput></userinput>
+> <userinput>config add Dhcp4/option-data</userinput>
+> <userinput>config set Dhcp4/option-data[2]/name "container"</userinput>
+> <userinput>config set Dhcp4/option-data[2]/space "dhcp4"</userinput>
+> <userinput>config set Dhcp4/option-data[2]/code 222</userinput>
+> <userinput>config set Dhcp4/option-data[2]/csv-format true</userinput>
+> <userinput>config set Dhcp4/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>
<section id="dhcp4-serverid">
<title>Server Identifier in DHCPv4</title>
- <para>The DHCPv4 protocol uses a "server identifier" for clients to be able
- to discriminate between several servers present on the same link: this
- value is an IPv4 address of the server. When started for the first time,
- the DHCPv4 server will choose one of its IPv4 addresses as its server-id,
- and store the chosen value to a file. (The file is named b10-dhcp4-serverid and is
- stored in the "local state directory". This is set during installation
- when "configure" is run, and can be changed by using "--localstatedir"
- on the "configure" command line.) That file will be read by the server
- and the contained value used whenever the server is subsequently started.
+ <para>
+ The DHCPv4 protocol uses a "server identifier" for clients to be able
+ to discriminate between several servers present on the same link: this
+ value is an IPv4 address of the server. When started for the first time,
+ the DHCPv4 server will choose one of its IPv4 addresses as its server-id,
+ and store the chosen value to a file. That file will be read by the server
+ and the contained value used whenever the server is subsequently started.
</para>
<para>
- It is unlikely that this parameter needs to be changed. If such a need
- arises, please stop the server, edit the file and restart the server.
- It is a text file that should contain an IPv4 address. Spaces are
- ignored. No extra characters are allowed in this file.
+ It is unlikely that this parameter should ever need to be changed.
+ However, if such a need arises, stop the server, edit the file and restart
+ the server. (The file is named b10-dhcp4-serverid and by default is
+ stored in the "var" subdirectory of the directory in which BIND 10 is installed.
+ This can be changed when BIND 10 is built by using "--localstatedir"
+ on the "configure" command line.) The file is a text file that should
+ contain an IPv4 address. Spaces are ignored, and no extra characters are allowed
+ in this file.
</para>
</section>
@@ -3705,7 +4171,9 @@ Dhcp4/renew-timer 1000 integer (default)
<simpara>Address rebinding (REBIND) and duplication report (DECLINE)
are not supported yet.</simpara>
</listitem>
-
+ <listitem>
+ <simpara>DNS Update is not yet supported.</simpara>
+ </listitem>
</itemizedlist>
</section>
@@ -3739,17 +4207,7 @@ Dhcp4/renew-timer 1000 integer (default)
> <userinput>config commit</userinput>
</screen>
</para>
- <para>
- To change one of the parameters, simply follow
- the usual <command>bindctl</command> procedure. For example, to make the
- leases longer, change their valid-lifetime parameter:
- <screen>
-> <userinput>config set Dhcp6/valid-lifetime 7200</userinput>
-> <userinput>config commit</userinput></screen>
- Please note that most Dhcp6 parameters are of global scope
- and apply to all defined subnets, unless they are overridden on a
- per-subnet basis.
- </para>
+
<para>
During start-up the server will detect available network interfaces
@@ -3921,51 +4379,420 @@ Dhcp6/subnet6/ list
2001:db8:: address may be assigned as well. If you want to avoid this,
please use the "min-max" notation.
</para>
+ </section>
+
+ <section id="dhcp6-std-options">
+ <title>Standard DHCPv6 options</title>
<para>
- Options can also be configured: the following commands configure
- the DNS-SERVERS option for all subnets with the following addresses:
- 2001:db8:1::1 and 2001:db8:1::2
+ One of the major features of DHCPv6 server is to provide configuration
+ options to clients. Although there are several options that require
+ special behavior, most options are sent by the server only if the client
+ explicitly requested them. The following example shows how to
+ configure DNS servers, which is one of the most frequently used
+ options. Numbers in the first column are added for easier reference and
+ will not appear on screen. Options specified in this way are considered
+ global and apply to all configured subnets.
+
<screen>
+1. > <userinput>config add Dhcp6/option-data</userinput>
+2. > <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
+3. > <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
+4. > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+5. > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
+6. > <userinput>config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe"</userinput>
+7. > <userinput>config commit</userinput>
+</screen>
+ </para>
+ <para>
+ The first line creates new entry in option-data table. It
+ contains information on all global options that the server is
+ supposed to configure in all subnets. The second line specifies
+ option name. For a complete list of currently supported names,
+ see <xref linkend="dhcp6-std-options-list"/> below.
+ The third line specifies option code, which must match one of the
+ values from that
+ list. Line 4 specifies option space, which must always
+ be set to "dhcp6" as these are standard DHCPv6 options. For
+ other name spaces, including custom option spaces, see <xref
+ linkend="dhcp6-option-spaces"/>. The fifth line specifies the format in
+ which the data will be entered: use of CSV (comma
+ separated values) is recommended. The sixth line gives the actual value to
+ be sent to clients. Data is specified as a normal text, with
+ values separated by commas if more than one value is
+ allowed.
+ </para>
+
+ <para>
+ Options can also be configured as hexadecimal values. If csv-format is
+ set to false, the option data must be specified as a string of hexadecimal
+ numbers. The
+ following commands configure the DNS-SERVERS option for all
+ subnets with the following addresses: 2001:db8:1::cafe and
+ 2001:db8:1::babe.
+ <screen>
> <userinput>config add Dhcp6/option-data</userinput>
> <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
> <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
+> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
+> <userinput>config set Dhcp6/option-data[0]/csv-format false</userinput>
> <userinput>config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000</userinput>
- <userinput>0000 0001 2001 0DB8 0001 0000 0000 0000 0000 0002"</userinput>
+ <userinput>0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE"</userinput>
> <userinput>config commit</userinput>
</screen>
(The value for the setting of the "data" element is split across two
- lines in this document for clarity: when entering the command, the whole
- string should be entered on the same line.)
+ lines in this document for clarity: when entering the command, the
+ whole string should be entered on the same line.)
</para>
- <para>
- Currently the only way to set option data is to specify the
- data as a string of hexadecimal digits. It is planned to allow
- alternative ways of specifying the data as a comma-separated list,
- e.g. "2001:db8:1::1,2001:db8:1::2".
- </para>
- <para>
- As with global settings, it is also possible to override options on a
- per-subnet basis, e.g. the following commands override the global DNS
- servers option for a particular subnet, setting a single DNS server with
- address 2001:db8:1::3.
- <screen>
+
+ <para>
+ It is possible to override options on a per-subnet basis. If
+ clients connected to most of your subnets are expected to get the
+ same values of a given option, you should use global options: you
+ can then override specific values for a small number of subnets.
+ On the other hand, if you use different values in each subnet,
+ it does not make sense to specify global option values
+ (Dhcp6/option-data), rather you should set only subnet-specific values
+ (Dhcp6/subnet[X]/option-data[Y]).
+ </para>
+ <para>
+ The following commands override the global
+ DNS servers option for a particular subnet, setting a single DNS
+ server with address 2001:db8:1::3.
+ <screen>
> <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>
- The DHCPv6 server may receive requests from local (connected to the same
- subnet as the server) and remote (connecting via relays)
- clients.
+ The DHCPv6 server may receive requests from local (connected
+ to the same subnet as the server) and remote (connecting via
+ relays) clients.
<note>
<para>
Currently relayed DHCPv6 traffic is not supported. The server will
@@ -4003,28 +4830,30 @@ Dhcp6/subnet6/ list
<para>The DHCPv6 protocol uses a "server identifier" (also known
as a DUID) for clients to be able to discriminate between several
servers present on the same link. There are several types of
- DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if
+ DUIDs defined, but <ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink> instructs servers to use DUID-LLT if
possible. This format consists of a link-layer (MAC) address and a
timestamp. When started for the first time, the DHCPv6 server will
automatically generate such a DUID and store the chosen value to
- a file (The file is named b10-dhcp6-serverid and is stored in the
- "local state directory". This is set during installation when
- "configure" is run, and can be changed by using "--localstatedir"
- on the "configure" command line.) That file will be read by the server
+ a file. That file is read by the server
and the contained value used whenever the server is subsequently started.
</para>
<para>
- It is unlikely that this parameter needs to be changed. If such a need
- arises, please stop the server, edit the file and start the server
- again. It is a text file that contains double digit hexadecimal values
+ It is unlikely that this parameter should ever need to be changed.
+ However, if such a need arises, stop the server, edit the file and restart
+ the server. (The file is named b10-dhcp6-serverid and by default is
+ stored in the "var" subdirectory of the directory in which BIND 10 is installed.
+ This can be changed when BIND 10 is built by using "--localstatedir"
+ on the "configure" command line.) The file is a text file that contains
+ double digit hexadecimal values
separated by colons. This format is similar to typical MAC address
format. Spaces are ignored. No extra characters are allowed in this
file.
</para>
+
</section>
<section id="dhcp6-std">
- <title>Supported DHCPv6 Standards</title>
+ <title>Supported Standards</title>
<para>The following standards and draft standards are currently
supported:</para>
<itemizedlist>
More information about the bind10-changes
mailing list