From: Tomek Mrugalski Date: Wed, 23 Jan 2013 12:56:48 +0000 (+0100) Subject: [2657] DHCPv6 Options described. X-Git-Tag: bind10-1.0.0-rc-release~29^2~1^2~12 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=368ceac8bfb49a0bd4c0a0c98fe624d623de9c6d;p=thirdparty%2Fkea.git [2657] DHCPv6 Options described. --- diff --git a/ChangeLog b/ChangeLog index e305569e55..2885576171 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +5XX. [func] tomek + Write new sections about DHCPv6 options in BIND10 Guide. + (Trac #2657, git TBD) + 557. [func] stephen Update DHCP sections of the BIND 10 guide. (Trac #2642, git e5faeb5fa84b7218fde486347359504cf692510e) diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 37934cd553..4dce832da4 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -3921,44 +3921,344 @@ Dhcp6/subnet6/ list 2001:db8:: address may be assigned as well. If you want to avoid this, please use the "min-max" notation. + + +
+ Standard DHCPv6 options - Options can also be configured: the following commands configure - the DNS-SERVERS option for all subnets with the following addresses: - 2001:db8:1::1 and 2001:db8:1::2 + One of the major features of DHCPv6 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. + +1. > config add Dhcp6/option-data +2. > config set Dhcp6/option-data[0]/name "dns-servers" +3. > config set Dhcp6/option-data[0]/code 23 +4. > config set Dhcp6/option-data[0]/space "dhcp6" +5. > config set Dhcp6/option-data[0]/csv-format true +6. > config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe" +7. > config commit + + + + 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 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 "dhcp6" as these are standard DHCPv6 options. For + other name spaces, including custom option spaces, see . 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. + + + + 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 DNS-SERVERS option for all + subnets with the following addresses: 2001:db8:1::cafe and + 2001:db8:1::babe. Note that csv-format is set to false. + > config add Dhcp6/option-data > config set Dhcp6/option-data[0]/name "dns-servers" > config set Dhcp6/option-data[0]/code 23 +> config set Dhcp6/option-data[0]/space "dhcp6" +> config set Dhcp6/option-data[0]/csv-format false > config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000 - 0000 0001 2001 0DB8 0001 0000 0000 0000 0000 0002" + 0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE" > config commit (The value for the setting of the "data" element is split across two - lines in this document for clarity: when entering the command, the whole + lines in this document for clarity: when entering the command, all the string should be entered on the same line.) - - Currently the only way to set option data is to specify the - data as a string of hexadecimal digits. It is planned to allow - alternative ways of specifying the data as a comma-separated list, - e.g. "2001:db8:1::1,2001:db8:1::2". - - - As with global settings, it is also possible to override options on a - per-subnet basis, e.g. the following commands override the global DNS - servers option for a particular subnet, setting a single DNS server with - address 2001:db8:1::3. - + + + 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 2001:db8:1::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 + (Dhcp6/option-data), but rather use only subnet-specific values + (Dhcp6/subnet[X]/option-data[Y]). + > config add Dhcp6/subnet6[0]/option-data > config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers" > config set Dhcp6/subnet6[0]/option-data[0]/code 23 -> config set Dhcp6/subnet6[0]/option-data[0]/data "2001 0DB8 0001 0000 - 0000 0000 0000 0003" +> config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6" +> config set Dhcp6/subnet6[0]/option-data[0]/csv-format true +> config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3" +> config commit + + + + 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. + + + + + This is the list of currently supported standard DHCPv6 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. ipv6-address means a normal IPv6 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 dns-servers allows conveying more than one IPv6 addresses, so clients will + get multiple DNS servers if needed. + + + + + + + List of standard DHCPv6 options + +name: preference, code: 7, type: uint8, array false + + +name: sip-server-dns, code: 21, type: fqdn, array true +name: sip-server-addr, code: 22, type: ipv6-address, array true +name: dns-servers, code: 23, type: ipv6-address, array true +name: domain-search, code: 24, type: fqdn, array true +name: ia-pd, code: 25, type: record, array false +name: iaprefix, code: 26, type: record, array false +name: nis-servers, code: 27, type: ipv6-address, array true +name: nisp-servers, code: 28, type: ipv6-address, array true +name: nis-domain-name, code: 29, type: fqdn, array true +name: nisp-domain-name, code: 30, type: fqdn, array true +name: sntp-servers, code: 31, type: ipv6-address, array true +name: information-refresh-time, code: 32, type: uint32, array false +name: bcmcs-server-dns, code: 33, type: fqdn, array true +name: bcmcs-server-addr, code: 34, type: ipv6-address, array true +name: geoconf-civic, code: 36, type: record, array false +name: remote-id, code: 37, type: record, array false +name: subscriber-id, code: 38, type: binary, array false +name: client-fqdn, code: 39, type: record, array false +name: pana-agent, code: 40, type: ipv6-address, array true +name: new-posix-timezone, code: 41, type: string, array false +name: new-tzdb-timezone, code: 42, type: string, array false +name: ero, code: 43, type: uint16, array true +name: lq-query, code: 44, type: record, array false +name: client-data, code: 45, type: empty, array false +name: clt-time, code: 46, type: uint32, array false +name: lq-relay-data, code: 47, type: record, array false +name: lq-client-link, code: 48, type: ipv6-address, array true + + +
+ +
+ Custom DHCPv6 options + 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 + such option format by using the following commands: + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "foo" +> config set Dhcp6/option-def[0]/code 100 +> config set Dhcp6/option-def[0]/type "uint32" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/record-types "" +> config set Dhcp6/option-def[0]/space "dhcp6" +> config set Dhcp6/option-def[0]/encapsulate "" +> config commit + Note that this specifies new option format, not the values conveyed in + that option. + + 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. + +1. > config add Dhcp6/option-data +2. > config set Dhcp6/option-data[0]/name "foo" +3. > config set Dhcp6/option-data[0]/code 100 +4. > config set Dhcp6/option-data[0]/space "dhcp6" +5. > config set Dhcp6/option-data[0]/csv-format true +6. > config set Dhcp6/option-data[0]/data "12345" +7. > config commit + + + New options can take more complex forms than simple use of + primitives (uint8, string, ipv6-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 IPv6 + address, followed by unsigned 16 bit integer, followed by a text + string. Such an option could be defined in the following way: + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "bar" +> config set Dhcp6/option-def[0]/code 101 +> config set Dhcp6/option-def[0]/space "dhcp6" +> config set Dhcp6/option-def[0]/type "record" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string" +> config set Dhcp6/option-def[0]/encapsulate "" + + Its values can be later defined as follows: + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "bar" +> config set Dhcp6/option-data[0]/space "dhcp6" +> config set Dhcp6/option-data[0]/code 101 +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World" +7. > config commit + +
+ +
+ DHCPv6 vendor specific options + Currently there are two option spaces defined: dhcp4 (to + be used in DHCPv4 daemon) and dhcp6. 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 IPv6 address, + unsigned 16 bit integer and a string. The foo option is conveyed in + vendor specific information option. + +> config add Dhcp6/option-def +> config set Dhcp6/option-def[0]/name "foo" +> config set Dhcp6/option-def[0]/code 1 +> config set Dhcp6/option-def[0]/space "vendor-opts-space" +> config set Dhcp6/option-def[0]/type "record" +> config set Dhcp6/option-def[0]/array false +> config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string" +> config set Dhcp6/option-def[0]/encapsulates "" > config commit - (As before, the setting of the "data" element has been split across two - lines for clarity.) + After option format is defined, the next step is to define actual values + for that option: + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "foo" +> config set Dhcp6/option-data[0]/space "vendor-opts-space" +> config set Dhcp6/option-data[0]/code 1 +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World" +> config commit + We should also define values for the vendor-opts, that will convey our option foo. + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[1]/name "vendor-opts" +> config set Dhcp6/option-data[1]/space "dhcp6" +> config set Dhcp6/option-data[1]/code 17 +> config set Dhcp6/option-data[1]/csv-format true +> config set Dhcp6/option-data[1]/data "12345" +> config commit + +
+ +
+ Nested DHCPv6 options (custom option spaces) + 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 DHCPv6 options, so a separate option + space must be defined. Let's assume that we want to have a + DHCPv6 option with code 102 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: + +config add Dhcp6/option-def +config set Dhcp6/option-def[0]/name "subopt1" +config set Dhcp6/option-def[0]/code 1 +config set Dhcp6/option-def[0]/space "isc" +config set Dhcp6/option-def[0]/type "ipv6-address" +config set Dhcp6/option-def[0]/record-types "" +config set Dhcp6/option-def[0]/array false +config set Dhcp6/option-def[0]/encapsulate "" +config commit + +config add Dhcp6/option-def +config set Dhcp6/option-def[1]/name "subopt2" +config set Dhcp6/option-def[1]/code 2 +config set Dhcp6/option-def[1]/space "isc" +config set Dhcp6/option-def[1]/type "string" +config set Dhcp6/option-def[1]/record-types "" +config set Dhcp6/option-def[1]/array false +config set Dhcp6/option-def[1]/encapsulate "" +config commit +The next step is to define a regular DHCPv6 option and specify that it +should include options from isc option space: + +config add Dhcp6/option-def +config set Dhcp6/option-def[2]/name "container" +config set Dhcp6/option-def[2]/code 102 +config set Dhcp6/option-def[2]/space "dhcp6" +config set Dhcp6/option-def[2]/type "uint16" +config set Dhcp6/option-def[2]/array false +config set Dhcp6/option-def[2]/record-types "" +config set Dhcp6/option-def[2]/encapsulate "isc" +config commit + +Finally, we should specify values for those new options: + +config add Dhcp6/option-data +config set Dhcp6/option-data[0]/name "subopt1" +config set Dhcp6/option-data[0]/space "isc" +config set Dhcp6/option-data[0]/code 1 +config set Dhcp6/option-data[0]/csv-format true +config set Dhcp6/option-data[0]/data "2001:db8::abcd" +config commit + +config add Dhcp6/option-data +config set Dhcp6/option-data[1]/name "subopt2" +config set Dhcp6/option-data[1]/space "isc" +config set Dhcp6/option-data[1]/code 2 +config set Dhcp6/option-data[1]/csv-format true +config set Dhcp6/option-data[1]/data "Hello world" +config commit + +config add Dhcp6/option-data +config set Dhcp6/option-data[2]/name "container" +config set Dhcp6/option-data[2]/space "dhcp6" +config set Dhcp6/option-data[2]/code 102 +config set Dhcp6/option-data[2]/csv-format true +config set Dhcp6/option-data[2]/data "123" +config commit
+ +
Subnet Selection