[2657] DHCPv4 options described.

doc/guide/bind10-guide.xml

@@ -3611,6 +3611,364 @@ Dhcp4/subnet4	[]	list	(default)
       </section>
     </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
+        explicitely 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. &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>
+</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 the list <xref linkend="dhcp4-std-options-list"/> below.
+      The third line specified option code. It must match values from
+      the list. Fourth line 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"/>. Fifth line specifies format in
+      which data will be specified. It is recommended to use CSV (coma
+      separated values). The sixth list specifies the actual value to
+      be sent to clients. Data is specified as a normal text with
+      values separated with comas, if more than one value is
+      allowed.
+    </para>
+
+    <para>
+      Options can also be configured as hex 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>
+&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 false</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/data "C0 00 03 01</userinput>
+         <userinput> C0 00 03 02"</userinput>
+&gt; <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, all the
+        string should be entered on the same line.)
+      </para>
+
+      <para>
+        As with global settings, it is also possible to override options
+        on a per-subnet basis. The following commands override the
+        global DNS servers option for a particular subnet, setting a
+        single DNS server with address 192.0.2.3. It is convenient
+        to use global options when clients connected to most of your
+        subnets are expected to get the same values of a given
+        option. You can then override specific values for small number
+        of subnets. If you use different values in each subnet, it does
+        not make sense to specify global option values
+        (Dhcp4/option-data), but rather use only subnet-specific values
+        (Dhcp4/subnet[X]/option-data[Y]).
+        <screen>
+&gt; <userinput>config add Dhcp4/subnet4[0]/option-data</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers"</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/option-data[0]/code 6</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4"</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/option-data[0]/csv-format true</userinput>
+&gt; <userinput>config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3"</userinput>
+&gt; <userinput>config commit</userinput></screen>
+      </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
+        automatically.</para>
+      </note>
+
+      <para>
+        This is the list of currently supported standard DHCPv4 options. 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. Uint8 means 8 bit
+        unsigned integer with allowed values 0 to 255. Uint16 means 16 bit unsinged
+        integer with allowed values 0 to 65535. Uint32 means 32 bit unsigned integer with
+        allowed values 0 to 4294967295. ipv4-address means a normal IPv4 address. Fqdn means
+        fully qualified domain name. String means any text. Some options are designated
+        as arrays. This means that more than one value is allowed in such an option. For example
+        the option domain-name-servers allows conveying more than one IPv4 addresses,
+        so clients will get multiple DNS servers if needed.
+      </para>
+
+      <!-- @todo: describe record types -->
+
+<para>
+        <itemizedlist id="dhcp4-std-options-list">
+          <title>List of standard DHCPv4 options</title>
+<listitem><para>name: subnet-mask, code: 1, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: time-offset, code: 2, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: routers, code: 3, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: time-servers, code: 4, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: name-servers, code: 5, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: domain-name-servers, code: 6, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: log-servers, code: 7, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: cookie-servers, code: 8, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: lpr-servers, code: 9, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: impress-servers, code: 10, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: resource-location-servers, code: 11, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: host-name, code: 12, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: boot-size, code: 13, csv-format: true, type: uint16, array: false</para></listitem>
+<listitem><para>name: merit-dump, code: 14, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: domain-name, code: 15, csv-format: true, type: fqdn, array: false</para></listitem>
+<listitem><para>name: swap-server, code: 16, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: root-path, code: 17, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: extensions-path, code: 18, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: ip-forwarding, code: 19, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: non-local-source-routing, code: 20, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: policy-filter, code: 21, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: max-dgram-reassembly, code: 22, csv-format: true, type: uint16, array: false</para></listitem>
+<listitem><para>name: default-ip-ttl, code: 23, csv-format: true, type: uint8, array: false</para></listitem>
+<listitem><para>name: path-mtu-aging-timeout, code: 24, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: path-mtu-plateau-table, code: 25, csv-format: true, type: uint16, array true</para></listitem>
+<listitem><para>name: interface-mtu, code: 26, csv-format: true, type: uint16, array: false</para></listitem>
+<listitem><para>name: all-subnets-local, code: 27, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: broadcast-address, code: 28, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: perform-mask-discovery, code: 29, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: mask-supplier, code: 30, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: router-discovery, code: 31, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: router-solicitation-address, code: 32, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: static-routes, code: 33, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: trailer-encapsulation, code: 34, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: arp-cache-timeout, code: 35, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: ieee802-3-encapsulation, code: 36, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: default-tcp-ttl, code: 37, csv-format: true, type: uint8, array: false</para></listitem>
+<listitem><para>name: tcp-keepalive-internal, code: 38, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: tcp-keepalive-garbage, code: 39, csv-format: true, type: boolean, array: false</para></listitem>
+<listitem><para>name: nis-domain, code: 40, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: nis-servers, code: 41, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: ntp-servers, code: 42, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: vendor-encapsulated-options, code: 43, csv-format: true, type: empty, array: false</para></listitem>
+<listitem><para>name: netbios-name-servers, code: 44, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: netbios-dd-server, code: 45, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: netbios-node-type, code: 46, csv-format: true, type: uint8, array: false</para></listitem>
+<listitem><para>name: netbios-scope, code: 47, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: font-servers, code: 48, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: x-display-manager, code: 49, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: dhcp-requested-address, code: 50, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: dhcp-lease-time, code: 51, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: dhcp-option-overload, code: 52, csv-format: true, type: uint8, array: false</para></listitem>
+<listitem><para>name: dhcp-message-type, code: 53, csv-format: true, type: uint8, array: false</para></listitem>
+<listitem><para>name: dhcp-server-identifier, code: 54, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: dhcp-parameter-request-list, code: 55, csv-format: true, type: uint8, array true</para></listitem>
+<listitem><para>name: dhcp-message, code: 56, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: dhcp-max-message-size, code: 57, csv-format: true, type: uint16, array: false</para></listitem>
+<listitem><para>name: dhcp-renewal-time, code: 58, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: dhcp-rebinding-time, code: 59, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: vendor-class-identifier, code: 60, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: dhcp-client-identifier, code: 61, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: nwip-domain-name, code: 62, csv-format: true, type: string, array: false</para></listitem>
+<listitem><para>name: nwip-suboptions, code: 63, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: user-class, code: 77, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: fqdn, code: 81, csv-format: true, type: record, array: false</para></listitem>
+<listitem><para>name: dhcp-agent-options, code: 82, csv-format: true, type: empty, array: false</para></listitem>
+<listitem><para>name: authenticate, code: 90, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: client-last-transaction-time, code: 91, csv-format: true, type: uint32, array: false</para></listitem>
+<listitem><para>name: associated-ip, code: 92, csv-format: true, type: ipv4-address, array true</para></listitem>
+<listitem><para>name: subnet-selection, code: 118, csv-format: true, type: ipv4-address, array: false</para></listitem>
+<listitem><para>name: domain-search, code: 119, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: vivco-suboptions, code: 124, csv-format: true, type: binary, array: false</para></listitem>
+<listitem><para>name: vivso-suboptions, code: 125, csv-format: true, type: binary, array: false</para></listitem>
+</itemizedlist></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
+      such option format by using the following commands:
+      <screen>
+&gt; <userinput>config add Dhcp4/option-def</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/code 222</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/type "uint32"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/record-types ""</userinput>
+&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>
+      Note that this specifies new option format, not the values conveyed in
+      that option.
+      </para>
+      <para>Once the new option format is specified, 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.
+        <screen>
+1. &gt; <userinput>config add Dhcp4/option-data</userinput>
+2. &gt; <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+3. &gt; <userinput>config set Dhcp4/option-data[0]/code 222</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 "12345"</userinput>
+7. &gt; <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 composition of existing primitives. Let's assume that 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>
+&gt; <userinput>config add Dhcp4/option-def</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/name "bar"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/code 223</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/space "dhcp4"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/encapsulate ""</userinput>
+</screen>
+     Its values can be later defined as follows:
+<screen>
+&gt; <userinput>config add Dhcp4/option-data</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/name "bar"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/code 223</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/data "192.0.2.100, 123, Hello World"</userinput>
+7. &gt; <userinput>config commit</userinput></screen>
+      </para>
+
+    </section>
+
+    <section id="dhcp4-vendor-opts">
+      <title>DHCPv4 vendor specific options</title>
+      <para>Currently there are two 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
+      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
+      vendor specific information option.
+      <screen>
+&gt; <userinput>config add Dhcp4/option-def</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/name "foo"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/code 1</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/type "record"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/array false</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string"</userinput>
+&gt; <userinput>config set Dhcp4/option-def[0]/encapsulates ""</userinput>
+&gt; <userinput>config commit</userinput></screen>
+     After option format is defined, the next step is to define actual values
+     for that option:
+     <screen>
+&gt; <userinput>config add Dhcp4/option-data</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[0]/code 1</userinput>
+&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 should also define values for the vendor-opts, that will convey our option foo.
+     <screen>
+&gt; <userinput>config add Dhcp4/option-data</userinput>
+&gt; <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[1]/space "dhcp4"</userinput>
+&gt; <userinput>config set Dhcp4/option-data[1]/code 43</userinput>
+&gt; <userinput>config set Dhcp4/option-data[1]/csv-format true</userinput>
+&gt; <userinput>config set Dhcp4/option-data[1]/data "12345"</userinput>
+&gt; <userinput>config commit</userinput></screen>
+      </para>
+    </section>
+
+    <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
+      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:
+<screen>
+config add Dhcp4/option-def
+config set Dhcp4/option-def[0]/name "subopt1"
+config set Dhcp4/option-def[0]/code 1
+config set Dhcp4/option-def[0]/space "isc"
+config set Dhcp4/option-def[0]/type "ipv4-address"
+config set Dhcp4/option-def[0]/record-types ""
+config set Dhcp4/option-def[0]/array false
+config set Dhcp4/option-def[0]/encapsulate ""
+config commit
+
+config add Dhcp4/option-def
+config set Dhcp4/option-def[1]/name "subopt2"
+config set Dhcp4/option-def[1]/code 2
+config set Dhcp4/option-def[1]/space "isc"
+config set Dhcp4/option-def[1]/type "string"
+config set Dhcp4/option-def[1]/record-types ""
+config set Dhcp4/option-def[1]/array false
+config set Dhcp4/option-def[1]/encapsulate ""
+config commit</screen>
+The next step is to define a regular DHCPv6 option and specify that it
+should include options from isc option space:
+<screen>
+config add Dhcp4/option-def
+config set Dhcp4/option-def[2]/name "container"
+config set Dhcp4/option-def[2]/code 222
+config set Dhcp4/option-def[2]/space "dhcp4"
+config set Dhcp4/option-def[2]/type "uint16"
+config set Dhcp4/option-def[2]/array false
+config set Dhcp4/option-def[2]/record-types ""
+config set Dhcp4/option-def[2]/encapsulate "isc"
+config commit</screen>
+
+Finally, we should specify values for those new options:
+<screen>
+config add Dhcp4/option-data
+config set Dhcp4/option-data[0]/name "subopt1"
+config set Dhcp4/option-data[0]/space "isc"
+config set Dhcp4/option-data[0]/code 1
+config set Dhcp4/option-data[0]/csv-format true
+config set Dhcp4/option-data[0]/data "192.0.2.3"
+config commit
+
+config add Dhcp4/option-data
+config set Dhcp4/option-data[1]/name "subopt2"
+config set Dhcp4/option-data[1]/space "isc"
+config set Dhcp4/option-data[1]/code 2
+config set Dhcp4/option-data[1]/csv-format true
+config set Dhcp4/option-data[1]/data "Hello world"
+config commit
+
+config add Dhcp4/option-data
+config set Dhcp4/option-data[2]/name "container"
+config set Dhcp4/option-data[2]/space "dhcp4"
+config set Dhcp4/option-data[2]/code 222
+config set Dhcp4/option-data[2]/csv-format true
+config set Dhcp4/option-data[2]/data "123"
+config commit</screen>
+      </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