Commit 28c7d972 authored by Stephen Morris's avatar Stephen Morris
Browse files

[2657] Merge branch 'trac2657' of ssh://git.bind10.isc.org/var/bind10/git/bind10 into trac2657

Conflicts:
	doc/guide/bind10-guide.xml
parents 3c200a3d 83b06fb1
......@@ -3618,18 +3618,17 @@ Dhcp4/subnet4 [] list (default)
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.
options. Options specified in this way are considered global and apply
to all configured subnets.
<screen>
1. &gt; <userinput>config add Dhcp4/option-data</userinput>
2. &gt; <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
3. &gt; <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
4. &gt; <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
5. &gt; <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
6. &gt; <userinput>config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"</userinput>
7. &gt; <userinput>config commit</userinput>
&gt; <userinput>config add Dhcp4/option-data</userinput>
&gt; <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
&gt; <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
&gt; <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
&gt; <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
&gt; <userinput>config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para>
<para>
......@@ -3841,9 +3840,27 @@ Dhcp4/subnet4 [] list (default)
&gt; <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
&gt; <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
&gt; <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.
......@@ -3920,7 +3937,7 @@ Dhcp4/subnet4 [] list (default)
&gt; <userinput>config set Dhcp4/option-def[0]/encapsulates ""</userinput>
&gt; <userinput>config commit</userinput>
</screen>
(Note that the option space is set to "vendor-encapsulated-option-space".)
(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>
......@@ -3959,11 +3976,16 @@ Dhcp4/subnet4 [] list (default)
<title>Nested DHCPv4 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 DHCPv4 options, so a separate option
space must be defined.
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 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="dhcp4-vendor-opts"/>).
</para>
<para>
Assume that we want to have a DHCPv4 option called "container" with
......@@ -4008,7 +4030,7 @@ Dhcp4/subnet4 [] list (default)
&gt; <userinput>commit</userinput>
</screen>
The name of the option space in which the sub-options are defined
is set in the "encapsulates" field.
is set in the "encapsulate" field.
</para>
<para>
Finally, we can set values for the new options:
......@@ -4037,9 +4059,6 @@ Dhcp4/subnet4 [] list (default)
&gt; <userinput>config set Dhcp4/option-data[2]/data "123"</userinput>
&gt; <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>
......@@ -4446,10 +4465,10 @@ Dhcp6/subnet6/ list
<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"/>.
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
......@@ -4524,10 +4543,9 @@ Dhcp6/subnet6/ list
<section id="dhcp6-custom-options">
<title>Custom DHCPv6 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 DHCPv6 option called "foo". It will have code 100
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 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>
&gt; <userinput>config add Dhcp6/option-def</userinput>
......@@ -4539,12 +4557,21 @@ Dhcp6/subnet6/ list
&gt; <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
&gt; <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
&gt; <userinput>config commit</userinput></screen>
Note that this specifies new option format, not the values conveyed in
that option.
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, 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>
&gt; <userinput>config add Dhcp6/option-data</userinput>
&gt; <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
......@@ -4556,7 +4583,7 @@ Dhcp6/subnet6/ list
</para>
<para>New options can take more complex forms than simple use of
primitives (uint8, string, ipv6-address etc). It is possible to
primitives (uint8, string, ipv6-address etc): it is possible to
define an option comprising a number of existing primitives.
</para>
<para>
......@@ -4616,8 +4643,10 @@ Dhcp6/subnet6/ list
&gt; <userinput>config set Dhcp6/option-def[0]/array false</userinput>
&gt; <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
&gt; <userinput>config set Dhcp6/option-def[0]/encapsulates ""</userinput>
&gt; <userinput>config commit</userinput></screen>
After option format is defined, the next step is to define actual values
&gt; <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>
&gt; <userinput>config add Dhcp6/option-data</userinput>
......@@ -4648,6 +4677,11 @@ Dhcp6/subnet6/ list
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.
......@@ -4678,7 +4712,7 @@ Dhcp6/subnet6/ list
</para>
<para>
The next step is to define a regular DHCPv6 option and specify that it
should include options from isc option space:
should include options from the isc option space:
<screen>
&gt; <userinput>config add Dhcp6/option-def</userinput>
&gt; <userinput>config set Dhcp6/option-def[2]/name "container"</userinput>
......@@ -4691,7 +4725,7 @@ should include options from isc option space:
&gt; <userinput>config commit</userinput>
</screen>
The name of the option space in which the sub-options are defined
is set in the "encapsulates" field.
is set in the "encapsulate" field.
</para>
<para>
Finally, we can set values for the new options:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment