BIND 10 trac2657, updated. 521189be3a1dc89fc9010dfa9fa13a31ee233a38 [2657] Edits to the DHCP section of the guide as part of the review
BIND 10 source code commits
bind10-changes at lists.isc.org
Thu Jan 24 12:58:00 UTC 2013
The branch, trac2657 has been updated
via 521189be3a1dc89fc9010dfa9fa13a31ee233a38 (commit)
from 1e2111996aa44a583fcdf0997a6aa170542f3ea2 (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 521189be3a1dc89fc9010dfa9fa13a31ee233a38
Author: Stephen Morris <stephen at isc.org>
Date: Thu Jan 24 12:57:23 2013 +0000
[2657] Edits to the DHCP section of the guide as part of the review
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 249 ++++++++++++++++++++++++++------------------
1 file changed, 147 insertions(+), 102 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index d2e1a6a..8b4fc21 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -3643,7 +3643,7 @@ Dhcp4/subnet4 [] list (default)
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 specfies the format in
+ 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
@@ -3663,13 +3663,9 @@ Dhcp4/subnet4 [] list (default)
> <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</userinput>
- <userinput> C0 00 03 02"</userinput>
+> <userinput>config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02"</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
- string should be entered on the same line.)
</para>
<para>
@@ -3697,30 +3693,35 @@ Dhcp4/subnet4 [] list (default)
</para>
<note>
- <para>In upcoming Kea versions, it will not be required anymore to specify
- option code, space and csv-format fields as those fields will be filled
+ <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
- specify name and code that should be used as a name in option-data
- structures. Type designates the actual format of the data:
+ 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">
+ <para>
+ <table border="1" cellpadding="5%" id="dhcp4-std-options-list">
<caption>List of standard DHCPv4 options</caption>
<thead>
- <tr><td>Name</td><td>Code</td><td>Type</td><td>Array?</td></tr>
- <tr></tr>
+ <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></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>
@@ -3799,17 +3800,37 @@ Dhcp4/subnet4 [] list (default)
<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>
+ </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 new options that are
- currently not supported out of the box. Let's assume that we
- want to define a new DHCPv4 option called "foo". It will have code 222
- and will convey a single unsigned 32 bit integer value. We can define
+ <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>
@@ -3821,12 +3842,12 @@ Dhcp4/subnet4 [] list (default)
> <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
> <userinput>config commit</userinput></screen>
- Note that this specifies new option format, not the values conveyed in
- that option.
+ 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, concrete values can then
- be specified in the same way as standard options. For example the following
- commands may be used to define global values that apply to all subnets.
+ <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>
@@ -3838,7 +3859,7 @@ Dhcp4/subnet4 [] list (default)
</para>
<para>New options can take more complex forms than simple use of
- primitives (uint8, string, ipv4-address etc). It is possible to
+ primitives (uint8, string, ipv4-address etc): it is possible to
define an option comprising a number of existing primitives.
</para>
<para>Assume we
@@ -3855,7 +3876,12 @@ Dhcp4/subnet4 [] list (default)
> <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
> <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
</screen>
- Its values can be later defined as follows:
+ 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>
@@ -3865,19 +3891,24 @@ Dhcp4/subnet4 [] list (default)
> <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 dhcp4; there is also vendor-opts-space,
- which is empty by default, but options can be defined in it. Those options
+ be used in DHCPv4 daemon), dhcp6, and vendor-opts-space. The last-mentioned
+ 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 IPv4 address,
unsigned 16 bit integer and a string. The "foo" option is conveyed in a
vendor specific information option.
- <screen>
+ </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>
@@ -3886,8 +3917,10 @@ Dhcp4/subnet4 [] list (default)
> <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>
- After option format is defined, the next step is to define actual values
+> <userinput>config commit</userinput>
+</screen>
+ (Note that the option space is set to "vendor-encapsulated-option-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>
@@ -3897,7 +3930,7 @@ Dhcp4/subnet4 [] list (default)
> <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 should also define values for the vendor-opts, that will convey our option foo.
+ We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo".
<screen>
> <userinput>config add Dhcp4/option-data</userinput>
> <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
@@ -3927,10 +3960,12 @@ Dhcp4/subnet4 [] list (default)
convey sub-options that use separate numbering scheme, for
example sub-options with codes 1 and 2. Those option codes
conflict with standard DHCPv4 options, so a separate option
- space must be defined. Let's assume that we want to have a
- DHCPv4 option with code 222 that conveys two sub-options with
- codes 1 and 2. This could be achieved with the following examples.
- First we need to define those new sub-options:
+ space must be defined.
+ </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>
@@ -3952,8 +3987,12 @@ Dhcp4/subnet4 [] list (default)
> <userinput>config set Dhcp4/option-def[1]/encapsulate ""</userinput>
> <userinput>config commit</userinput>
</screen>
-The next step is to define a regular DHCPv6 option and specify that it
-should include options from isc option space:
+ 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>
@@ -3965,8 +4004,11 @@ should include options from isc option space:
> <userinput>set Dhcp4/option-def[2]/encapsulate "isc"</userinput>
> <userinput>commit</userinput>
</screen>
-
-Finally, we should specify values for those new options:
+ The name of the option space in which the sub-options are defined
+ is set in the "encapsulates" field.
+ </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>
@@ -3992,26 +4034,31 @@ Finally, we should specify values for those new options:
> <userinput>config set Dhcp4/option-data[2]/data "123"</userinput>
> <userinput>config commit</userinput>
</screen>
+ Even though the "container" option comprises sub-options, we need to
+ set dummy values for it so that it is included in the data sent to a
+ client.
</para>
</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>
@@ -4340,7 +4387,7 @@ Dhcp6/subnet6/ list
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 specfies the format in
+ 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
@@ -4394,42 +4441,38 @@ Dhcp6/subnet6/ list
> <userinput>config commit</userinput></screen>
</para>
-<note>
- <para>In future version of Kea versions, 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
- specify name and code that should be used as a name in option-data
- structures. Type designates the actual format of the data:
-
- <itemizedlist id="dhcp6-option-types">
- <listitem><simpara>uint8 means 8 bit unsigned integer with allowed values 0 to 255.</simpara></listitem>
- <listitem><simpara>uint16 means 16 bit unsinged integer with allowed values 0 to 65535.</simpara></listitem>
- <listitem><simpara>uint32 means 32 bit unsigned integer with allowed values 0 to 4294967295.</simpara></listitem>
- <listitem><simpara>ipv6-address means a normal IPv6 address.</simpara></listitem>
- <listitem><simpara>fqdn means fully qualified domain name.</simpara></listitem>
- <listitem><simpara>String means any text.</simpara></listitem>
- </itemizedlist>
- 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>
+ <note>
+ <para>
+ In future version of Kea versions, 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
+ specify name and code that should be used as a name in option-data
+ structures. Type designates the actual format of the data and is one of
+ the types listed 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><td>Name</td><td>Code</td><td>Type</td><td>Array?</td></tr>
+ <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>
+ </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>
@@ -4479,9 +4522,9 @@ Dhcp6/subnet6/ list
<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>
+ </tbody>
+ </table>
+ </para>
</section>
<section id="dhcp6-custom-options">
@@ -4715,20 +4758,22 @@ Finally, we should specify values for those new options:
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">
More information about the bind10-changes
mailing list