BIND 10 trac2657, updated. 3d1ea31fe2461f28b7337c78623834eb987c73a5 [2657] DHCPv4 options described.
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Jan 23 15:26:01 UTC 2013
The branch, trac2657 has been updated
via 3d1ea31fe2461f28b7337c78623834eb987c73a5 (commit)
from 388c202a9b3c95f3d8d1aa0c76803b1f398974f3 (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 3d1ea31fe2461f28b7337c78623834eb987c73a5
Author: Marcin Siodelski <marcin at isc.org>
Date: Wed Jan 23 16:23:38 2013 +0100
[2657] DHCPv4 options described.
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 358 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 358 insertions(+)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 6b40c36..d606f78 100644
--- a/doc/guide/bind10-guide.xml
+++ b/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. > <userinput>config add Dhcp4/option-data</userinput>
+2. > <userinput>config set Dhcp4/option-data[0]/name "domain-name-servers"</userinput>
+3. > <userinput>config set Dhcp4/option-data[0]/code 6</userinput>
+4. > <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+5. > <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+6. > <userinput>config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2"</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 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>
+> <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</userinput>
+ <userinput> 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, 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>
+> <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 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>
+> <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>
+ 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. > <userinput>config add Dhcp4/option-data</userinput>
+2. > <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
+3. > <userinput>config set Dhcp4/option-data[0]/code 222</userinput>
+4. > <userinput>config set Dhcp4/option-data[0]/space "dhcp4"</userinput>
+5. > <userinput>config set Dhcp4/option-data[0]/csv-format true</userinput>
+6. > <userinput>config set Dhcp4/option-data[0]/data "12345"</userinput>
+7. > <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>
+> <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>
+ Its values can be later defined 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>
+7. > <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>
+> <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>
+ After 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 should also define values for the vendor-opts, that will convey our option foo.
+ <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 true</userinput>
+> <userinput>config set Dhcp4/option-data[1]/data "12345"</userinput>
+> <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
More information about the bind10-changes
mailing list