[2657] Changes as a result of the second review.

doc/guide/bind10-guide.xml

@@ -3619,18 +3619,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
+        options. Options specified in this way are considered global and apply
-        will not appear on screen. Options specified in this way are considered
+        to all configured subnets.
-        global and apply to all configured subnets.
 
         <screen>
-1. &gt; <userinput>config add Dhcp4/option-data</userinput>
+&gt; <userinput>config add Dhcp4/option-data</userinput>
-2. &gt; <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
+&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>
+&gt; <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
-4. &gt; <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
-5. &gt; <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+&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>
+&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 commit</userinput>
 </screen>
       </para>
     <para>
@@ -3842,9 +3841,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.
@@ -3898,13 +3915,17 @@ Dhcp4/subnet4	[]	list	(default)
 
     <section id="dhcp4-vendor-opts">
       <title>DHCPv4 vendor specific options</title>
-      <para>Currently there are three option spaces defined: dhcp4 (to
+      <para>Currently there are two major option spaces defined: "dhcp4" and "dhcp6".
-      be used in DHCPv4 daemon), dhcp6, and vendor-opts-space.  The last-mentioned
+      They group standard DHCPv4 and DHCPv6 options respectively. Some of the
-      is empty by default but options can be defined in it: those options
+      standard options may encapsulate other option spaces. Those options that
-      are called vendor-specific information options. The following examples
+      belong to the encapsulated option space are appended as sub-options to the
-      show how to define an option "foo" with code 1 that consists of IPv4 address,
+      option that encapsulates it. The name of the option space being encapsulated
-      unsigned 16 bit integer and a string. The "foo" option is conveyed in a
+      by the standard option is created as a result of the concatenation of the
-      vendor specific information option.
+      standard option's name and the postfix "-space". Thus the option space encapsulated
+      by the "vendor-enapsulated-options" option is named "vendor-encapsulated-options-space".
+      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.
       </para>
       <para>
       The first step is to define the format of the option:
@@ -3919,7 +3940,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>
@@ -3930,7 +3951,8 @@ Dhcp4/subnet4	[]	list	(default)
 &gt; <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
 &gt; <userinput>config set Dhcp4/option-data[0]/data "192.0.2.3, 123, Hello World"</userinput>
 &gt; <userinput>config commit</userinput></screen>
-    We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo".
+    We also set up a dummy value for "vendor-encapsulated-options", the option that conveys
+    our sub-option "foo".
      <screen>
 &gt; <userinput>config add Dhcp4/option-data</userinput>
 &gt; <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
@@ -3956,11 +3978,16 @@ Dhcp4/subnet4	[]	list	(default)
     <section id="dhcp4-option-spaces">
       <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
+      space. This is the case when user creates new option in the
-      convey sub-options that use separate numbering scheme, for
+      standard option space ("dhcp4 or "dhcp6") and wants this option
-      example sub-options with codes 1 and 2. Those option codes
+      to convey sub-options. Thanks to being in the separate space,
-      conflict with standard DHCPv4 options, so a separate option
+      sub-option codes will have a separate numbering scheme and may
-      space must be defined.
+      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
@@ -4005,7 +4032,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:
@@ -4034,9 +4061,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>
 
@@ -4451,10 +4475,10 @@ Dhcp6/subnet6/	list
 
 
     <para>
-      Below is a list of currently supported standard DHCPv6 options. The name and code
+      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
+      are the values that should be used as a name in the option-data
-      structures. Type designates the actual format of the data and is one of
+      structures. "Type" designates the format of the data: the meanings of
-      the types listed in <xref linkend="dhcp-types"/>.
+      the various types is given in <xref linkend="dhcp-types"/>.
     </para>
     <para>
       Some options are designated as arrays, which means that more than one
@@ -4529,10 +4553,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
+      <para>It is also possible to define options other than the standard ones.
-      currently not supported out of the box. Let's assume that we
+      Assume that we want to define a new DHCPv6 option called "foo" which will have
-      want to define a new DHCPv6 option called "foo". It will have code 100
+      code 100 and will convey a single unsigned 32 bit integer value. We can define
-      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>
@@ -4544,12 +4567,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
+      The "false" value of the "array" parameter determines that the option
-      that 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
+      <para>Once the new option format is defined, its value is set
-      be specified in the same way as standard options. For example the following
+      in the same way as for a standard option. For example the following
-      commands may be used to define global values that apply to all subnets.
+      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>
@@ -4561,7 +4593,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>
@@ -4579,7 +4611,12 @@ Dhcp6/subnet6/	list
 &gt; <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
 &gt; <userinput>config set Dhcp6/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>
+        Its values can be later defined as follows:
 <screen>
 &gt; <userinput>config add Dhcp6/option-data</userinput>
 &gt; <userinput>config set Dhcp6/option-data[0]/name "bar"</userinput>
@@ -4589,19 +4626,27 @@ Dhcp6/subnet6/	list
 &gt; <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"</userinput>
 &gt; <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
+      <para>Currently there are two major option spaces defined: "dhcp4" and "dhcp6".
-      be used in DHCPv4 daemon) and dhcp6; there is also vendor-opts-space,
+      They group standard DHCPv4 and DHCPv6 options respectively. Some of the
-      which is empty by default, but options can be defined in it. Those options
+      standard options may encapsulate other option spaces. Those options that
-      are called vendor-specific information options. The following examples
+      belong to the encapsulated option space are appended as sub-options to the
-      show how to define an option "foo" with code 1 that consists of IPv6 address,
+      option that encapsulates it. The name of the option space being encapsulated
-      unsigned 16 bit integer and a string. The "foo" option is conveyed in a
+      by the standard option is created as a result of the concatenation of the
-      vendor specific information option. This option comprises a single
+      standard option's name and the postfix "-space". Thus the option space encapsulated
-      uint32 value that is set to "12345". The sub-option "foo" follows
+      by the "vendor-opts" option is named "vendor-opts-space".
-      the data field holding this value.
+      The following examples show how to define an option "foo" with code 1 that
+      consists of IPv6 address, 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>
 &gt; <userinput>config add Dhcp6/option-def</userinput>
 &gt; <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
@@ -4611,8 +4656,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>
+&gt; <userinput>config commit</userinput>
-     After option format is defined, the next step is to define actual values
+</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>
@@ -4637,14 +4684,21 @@ Dhcp6/subnet6/	list
     <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
+      space. This is the case when user creates new option in the
-      convey sub-options that use separate numbering scheme, for
+      standard option space ("dhcp4 or "dhcp6") and wants this option
-      example sub-options with codes 1 and 2. Those option codes
+      to convey sub-options. Thanks to being in the separate space,
-      conflict with standard DHCPv6 options, so a separate option
+      sub-option codes will have a separate numbering scheme and may
-      space must be defined. Let's assume that we want to have a
+      overlap with codes of standard options.
-      DHCPv6 option with code 102 that conveys two sub-options with
+      </para>
-      codes 1 and 2. This could be achieved with the following examples.
+      <para>Note that it is not required to create new option space when
-      First we need to define those new sub-options:
+      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>
 &gt; <userinput>config add Dhcp6/option-def</userinput>
 &gt; <userinput>config set Dhcp6/option-def[0]/name "subopt1"</userinput>
@@ -4666,8 +4720,12 @@ Dhcp6/subnet6/	list
 &gt; <userinput>config set Dhcp6/option-def[1]/encapsulate ""</userinput>
 &gt; <userinput>config commit</userinput>
 </screen>
-The next step is to define a regular DHCPv6 option and specify that it
+    Note that we have defined the options to belong to a new option space
-should include options from isc option space:
+    (in this case, "isc").
+    </para>
+    <para>
+    The next step is to define a regular DHCPv6 option with our desired
+    code and specify that it should include options from the new option space:
 <screen>
 &gt; <userinput>config add Dhcp6/option-def</userinput>
 &gt; <userinput>config set Dhcp6/option-def[2]/name "container"</userinput>
@@ -4679,8 +4737,11 @@ should include options from isc option space:
 &gt; <userinput>config set Dhcp6/option-def[2]/encapsulate "isc"</userinput>
 &gt; <userinput>config commit</userinput>
 </screen>
-
+    The name of the option space in which the sub-options are defined
-Finally, we should specify values for those new options:
+    is set in the "encapsulate" field.
+    </para>
+    <para>
+    Finally, we can set values for the new options:
 <screen>
 &gt; <userinput>config add Dhcp6/option-data</userinput>
 &gt; <userinput>config set Dhcp6/option-data[0]/name "subopt1"</userinput>