diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index a16bf3b5bf..0d1913f4e4 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -7,7 +7,7 @@ ]> - - --with-dhcp-mysql - - Enable MySQL support for BIND 10 DHCP. For notes on configuring - and building DHCP with MySQL see . - - - - - + + + For additional instructions concerning the building and installation of + BIND 10 DHCP, see . + + @@ -3363,7 +3359,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address Build and install BIND 10 as described in , with the following modification: to enable the MySQL database code, at the "configure" step (see ), specify the location of the - MySQL configuration program "mysql_config" with the "--with-mysql-config" switch, + MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch, i.e. ./configure [other-options] --with-dhcp-mysql ...if MySQL was installed in the default location, or: @@ -3609,25 +3605,495 @@ Dhcp4/subnet4 [] list (default) network configurations. If you want to avoid this, please use the "min-max" notation. - -
- Server Identifier in DHCPv4 - The DHCPv4 protocol uses a "server identifier" for clients to be able - to discriminate between several servers present on the same link: this - value is an IPv4 address of the server. When started for the first time, - the DHCPv4 server will choose one of its IPv4 addresses as its server-id, - and store the chosen value to a file. (The file is named b10-dhcp4-serverid and is - stored in the "local state directory". This is set during installation - when "configure" is run, and can be changed by using "--localstatedir" - on the "configure" command line.) That file will be read by the server - and the contained value used whenever the server is subsequently started. +
+ Standard DHCPv4 options + + 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 + explicitly requested them. The following example shows how to + configure DNS servers, which is one of the most frequently used + options. Options specified in this way are considered global and apply + to all configured subnets. + + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "domain-name-servers" +> config set Dhcp4/option-data[0]/code 6 +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "192.0.3.1, 192.0.3.2" +> 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 below. + The third line specifies option code, which must match one of the + values from that list. Line 4 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 . The fifth line specifies the format in + which the data will be entered: use of CSV (comma + separated values) is recommended. The sixth line gives the actual value to + be sent to clients. Data is specified as a normal text, with + values separated by commas if more than one value is + allowed. + + + + Options can also be configured as hexadecimal 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. + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "domain-name-servers" +> config set Dhcp4/option-data[0]/code 6 +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/csv-format false +> config set Dhcp4/option-data[0]/data "C0 00 03 01 C0 00 03 02" +> config commit + + + + + It is possible to override options on a per-subnet basis. If + clients connected to most of your subnets are expected to get the + same values of a given option, you should use global options: you + can then override specific values for a small number of subnets. + On the other hand, if you use different values in each subnet, + it does not make sense to specify global option values + (Dhcp4/option-data), rather you should set only subnet-specific values + (Dhcp4/subnet[X]/option-data[Y]). - It is unlikely that this parameter needs to be changed. If such a need - arises, please stop the server, edit the file and restart the server. - It is a text file that should contain an IPv4 address. Spaces are - ignored. No extra characters are allowed in this file. + The following commands override the global + DNS servers option for a particular subnet, setting a single DNS + server with address 2001:db8:1::3. + +> config add Dhcp4/subnet4[0]/option-data +> config set Dhcp4/subnet4[0]/option-data[0]/name "domain-name-servers" +> config set Dhcp4/subnet4[0]/option-data[0]/code 6 +> config set Dhcp4/subnet4[0]/option-data[0]/space "dhcp4" +> config set Dhcp4/subnet4[0]/option-data[0]/csv-format true +> config set Dhcp4/subnet4[0]/option-data[0]/data "192.0.2.3" +> config commit + + + + In a future version of Kea, it will not be necessary to specify + the option code, space and csv-format fields as they will be set + automatically. + + + + Below is a list of currently supported standard DHCPv4 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 . + + + Some options are designated as arrays, which means that more than one + value is allowed in such an option. For example the option time-servers + allows the specification of more than one IPv4 address, so allowing + clients to obtain the the addresses of multiple NTP servers. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
List of standard DHCPv4 options
NameCodeTypeArray?
subnet-mask1ipv4-addressfalse
time-offset2uint32false
routers3ipv4-addresstrue
time-servers4ipv4-addresstrue
name-servers5ipv4-addressfalse
domain-name-servers6ipv4-addresstrue
log-servers7ipv4-addresstrue
cookie-servers8ipv4-addresstrue
lpr-servers9ipv4-addresstrue
impress-servers10ipv4-addresstrue
resource-location-servers11ipv4-addresstrue
host-name12stringfalse
boot-size13uint16false
merit-dump14stringfalse
domain-name15fqdnfalse
swap-server16ipv4-addressfalse
root-path17stringfalse
extensions-path18stringfalse
ip-forwarding19booleanfalse
non-local-source-routing20booleanfalse
policy-filter21ipv4-addresstrue
max-dgram-reassembly22uint16false
default-ip-ttl23uint8false
path-mtu-aging-timeout24uint32false
path-mtu-plateau-table25uint16true
interface-mtu26uint16false
all-subnets-local27booleanfalse
broadcast-address28ipv4-addressfalse
perform-mask-discovery29booleanfalse
mask-supplier30booleanfalse
router-discovery31booleanfalse
router-solicitation-address32ipv4-addressfalse
static-routes33ipv4-addresstrue
trailer-encapsulation34booleanfalse
arp-cache-timeout35uint32false
ieee802-3-encapsulation36booleanfalse
default-tcp-ttl37uint8false
tcp-keepalive-internal38uint32false
tcp-keepalive-garbage39booleanfalse
nis-domain40stringfalse
nis-servers41ipv4-addresstrue
ntp-servers42ipv4-addresstrue
vendor-encapsulated-options43emptyfalse
netbios-name-servers44ipv4-addresstrue
netbios-dd-server45ipv4-addresstrue
netbios-node-type46uint8false
netbios-scope47stringfalse
font-servers48ipv4-addresstrue
x-display-manager49ipv4-addresstrue
dhcp-requested-address50ipv4-addressfalse
dhcp-option-overload52uint8false
dhcp-message56stringfalse
dhcp-max-message-size57uint16false
vendor-class-identifier60binaryfalse
nwip-domain-name62stringfalse
nwip-suboptions63binaryfalse
user-class77binaryfalse
fqdn81recordfalse
dhcp-agent-options82emptyfalse
authenticate90binaryfalse
client-last-transaction-time91uint32false
associated-ip92ipv4-addresstrue
subnet-selection118ipv4-addressfalse
domain-search119binaryfalse
vivco-suboptions124binaryfalse
vivso-suboptions125binaryfalse
+ + + + + + + + + + + + + + + + + + + + +
List of standard DHCP option types
NameMeaning
binaryAn arbitrary string of bytes, specified as a set of hexadecimal digits.
booleanBoolean value with allowed values true or false
emptyNo value, data is carried in suboptions
fqdnFully qualified domain name (e.g. www.example.com)
ipv4-addressIPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)
ipv6-addressIPv6 address in the usual colon notation (e.g. 2001:db8::1)
recordStructured data that may comprise any types (except "record" and "empty")
stringAny text
uint88 bit unsigned integer with allowed values 0 to 255
uint1616 bit unsinged integer with allowed values 0 to 65535
uint3232 bit unsigned integer with allowed values 0 to 4294967295
+ +
+ +
+ Custom DHCPv4 options + It is also possible to define options other than the standard ones. + Assume that we want to define a new DHCPv4 option called "foo" which will have + code 222 and will convey a single unsigned 32 bit integer value. We can define + such an option by using the following commands: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "foo" +> config set Dhcp4/option-def[0]/code 222 +> config set Dhcp4/option-def[0]/type "uint32" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/record-types "" +> config set Dhcp4/option-def[0]/space "dhcp4" +> config set Dhcp4/option-def[0]/encapsulate "" +> config commit + 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. + + + + 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. + + + + 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. + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "foo" +> config set Dhcp4/option-data[0]/code 222 +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "12345" +> config commit + + + New options can take more complex forms than simple use of + primitives (uint8, string, ipv4-address etc): it is possible to + define an option comprising a number of existing primitives. + + Assume 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: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "bar" +> config set Dhcp4/option-def[0]/code 223 +> config set Dhcp4/option-def[0]/space "dhcp4" +> config set Dhcp4/option-def[0]/type "record" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string" +> config set Dhcp4/option-def[0]/encapsulate "" + + 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 . + + + The values of the option are set as follows: + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "bar" +> config set Dhcp4/option-data[0]/space "dhcp4" +> config set Dhcp4/option-data[0]/code 223 +> config set Dhcp4/option-data[0]/csv-format true +> config set Dhcp4/option-data[0]/data "192.0.2.100, 123, Hello World" +> config commit + + "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. +
+ +
+ DHCPv4 vendor specific options + + Currently there are three option spaces defined: dhcp4 (to + be used in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there + is also vendor-encapsulated-options-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 an IPv4 address, an + unsigned 16 bit integer and a string. The "foo" option is conveyed + in a vendor specific information option. + + + The first step is to define the format of the option: + +> config add Dhcp4/option-def +> config set Dhcp4/option-def[0]/name "foo" +> config set Dhcp4/option-def[0]/code 1 +> config set Dhcp4/option-def[0]/space "vendor-encapsulated-options-space" +> config set Dhcp4/option-def[0]/type "record" +> config set Dhcp4/option-def[0]/array false +> config set Dhcp4/option-def[0]/record-types "ipv4-address, uint16, string" +> config set Dhcp4/option-def[0]/encapsulates "" +> config commit + + (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: + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[0]/name "foo" +> config set Dhcp4/option-data[0]/space "vendor-encapsulated-options-space" +> 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, 123, Hello World" +> config commit + We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo". + This is required else the option will not be included in messages sent to the client. + +> config add Dhcp4/option-data +> config set Dhcp4/option-data[1]/name "vendor-encapsulated-options" +> config set Dhcp4/option-data[1]/space "dhcp4" +> config set Dhcp4/option-data[1]/code 43 +> config set Dhcp4/option-data[1]/csv-format false +> config set Dhcp4/option-data[1]/data "" +> config commit + + + + + With this version of BIND 10, the "vendor-encapsulated-options" option + must be specified in the configuration although it has no configurable + parameters. If it is not specified, the server will assume that it is + not configured and will not send it to a client. In the future there + will be no need to include this option in the configuration. + + + +
+ +
+ + Nested DHCPv4 options (custom option spaces) + It is sometimes useful to define completely new option + 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. + + Note that creation of a new option space when defining + sub-options for a standard option is not required, because it is + created by default if the standard option is meant to convey any + sub-options (see ). + + + Assume that we want to have a DHCPv4 option called "container" with + code 222 that conveys two sub-options with codes 1 and 2. + First we need to define the new sub-options: + +> 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 + + Note that we have defined the options to belong to a new option space + (in this case, "isc"). + + + The next step is to define a regular DHCPv4 option with our desired + code and specify that it should include options from the new option space: + +> add Dhcp4/option-def +> set Dhcp4/option-def[2]/name "container" +> set Dhcp4/option-def[2]/code 222 +> set Dhcp4/option-def[2]/space "dhcp4" +> set Dhcp4/option-def[2]/type "empty" +> set Dhcp4/option-def[2]/array false +> set Dhcp4/option-def[2]/record-types "" +> set Dhcp4/option-def[2]/encapsulate "isc" +> commit + + The name of the option space in which the sub-options are defined + is set in the "encapsulate" field. The "type" field is set to "empty" + to indicate that this option does not carry any data other than + sub-options. + + + Finally, we can set values for the new options: + +> 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 "" +> config commit + + Even though the "container" option does not carry any data except + sub-options, the "data" field must be explictly set to an empty value. + This is required because in the current version of BIND 10 DHCP, the + default configuration values are not propagated to the configuration parsers: + if the "data" is not set the parser will assume that this + parameter is not specified and an error will be reported. + + Note that it is possible to create an option which carries some data + in addition to the sub-options defined in the encapsulated option space. For example, + if the "container" option from the previous example was required to carry an uint16 + value as well as the sub-options, the "type" value would have to be set to "uint16" in + the option definition. (Such an option would then have the following + data structure: DHCP header, uint16 value, sub-options.) The value specified + with the "data" parameter - which should be a valid integer enclosed in quotes, + e.g. "123" - would then be assigned to the uint16 field in the "container" option. + +
+
+
+ Server Identifier in DHCPv4 + + The DHCPv4 protocol uses a "server identifier" for clients to be able + to discriminate between several servers present on the same link: this + value is an IPv4 address of the server. When started for the first time, + the DHCPv4 server will choose one of its IPv4 addresses as its server-id, + and store the chosen value to a file. That file will be read by the server + and the contained value used whenever the server is subsequently started. + + + It is unlikely that this parameter should ever need to be changed. + However, if such a need arises, stop the server, edit the file and restart + the server. (The file is named b10-dhcp4-serverid and by default is + stored in the "var" subdirectory of the directory in which BIND 10 is installed. + This can be changed when BIND 10 is built by using "--localstatedir" + on the "configure" command line.) The file is a text file that should + contain an IPv4 address. Spaces are ignored, and no extra characters are allowed + in this file.
@@ -3705,7 +4171,9 @@ Dhcp4/renew-timer 1000 integer (default) Address rebinding (REBIND) and duplication report (DECLINE) are not supported yet. - + + DNS Update is not yet supported. + @@ -3739,17 +4207,7 @@ Dhcp4/renew-timer 1000 integer (default) > config commit - - To change one of the parameters, simply follow - the usual bindctl procedure. For example, to make the - leases longer, change their valid-lifetime parameter: - -> config set Dhcp6/valid-lifetime 7200 -> config commit - Please note that most Dhcp6 parameters are of global scope - and apply to all defined subnets, unless they are overridden on a - per-subnet basis. - + During start-up the server will detect available network interfaces @@ -3921,51 +4379,420 @@ 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 + 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. + +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 below. + The third line specifies option code, which must match one of the + values from that + list. Line 4 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 . The fifth line specifies the format in + which the data will be entered: use of CSV (comma + separated values) is recommended. The sixth line gives the actual value to + be sent to clients. Data is specified as a normal text, with + values separated by commas if more than one value is + allowed. + + + + Options can also be configured as hexadecimal values. If csv-format is + set to false, the option data must be specified as a string of hexadecimal + numbers. The + following commands configure the DNS-SERVERS option for all + subnets with the following addresses: 2001:db8:1::cafe and + 2001:db8:1::babe. + > 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 - string should be entered on the same line.) + lines in this document for clarity: when entering the command, the + whole 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. - + + + It is possible to override options on a per-subnet basis. If + clients connected to most of your subnets are expected to get the + same values of a given option, you should use global options: you + can then override specific values for a small number of subnets. + On the other hand, if you use different values in each subnet, + it does not make sense to specify global option values + (Dhcp6/option-data), rather you should set only subnet-specific values + (Dhcp6/subnet[X]/option-data[Y]). + + + The following commands override the global + DNS servers option for a particular subnet, setting a single DNS + server with address 2001:db8:1::3. + > 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 - (As before, the setting of the "data" element has been split across two - lines for clarity.) + + + + + In future versions of BIND 10 DHCP, it will not be necessary to specify + option code, space and csv-format fields, as those fields will be set + automatically. + + + + + 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 . + + + Some options are designated as arrays, which means that more than one + value is allowed in such an option. For example the option dns-servers + allows the specification of more than one IPv6 address, so allowing + clients to obtain the the addresses of multiple DNS servers. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
List of standard DHCPv6 options
NameCodeTypeArray?
preference7uint8false
sip-server-dns21fqdntrue
sip-server-addr22ipv6-addresstrue
dns-servers23ipv6-addresstrue
domain-search24fqdntrue
nis-servers27ipv6-addresstrue
nisp-servers28ipv6-addresstrue
nis-domain-name29fqdntrue
nisp-domain-name30fqdntrue
sntp-servers31ipv6-addresstrue
information-refresh-time32uint32false
bcmcs-server-dns33fqdntrue
bcmcs-server-addr34ipv6-addresstrue
geoconf-civic36recordfalse
remote-id37recordfalse
subscriber-id38binaryfalse
client-fqdn39recordfalse
pana-agent40ipv6-addresstrue
new-posix-timezone41stringfalse
new-tzdb-timezone42stringfalse
ero43uint16true
lq-query44recordfalse
client-data45emptyfalse
clt-time46uint32false
lq-relay-data47recordfalse
lq-client-link48ipv6-addresstrue
+ +
+ +
+ Custom DHCPv6 options + 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: + +> 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 + 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. + + 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. + +> config add Dhcp6/option-data +> config set Dhcp6/option-data[0]/name "foo" +> config set Dhcp6/option-data[0]/code 100 +> config set Dhcp6/option-data[0]/space "dhcp6" +> config set Dhcp6/option-data[0]/csv-format true +> config set Dhcp6/option-data[0]/data "12345" +> config commit + + + New options can take more complex forms than simple use of + primitives (uint8, string, ipv6-address etc): it is possible to + define an option comprising a number of existing primitives. + + + Assume 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 "" + + 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 . + + + The values of the option are set 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" +> config commit + + "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. +
+ +
+ DHCPv6 vendor specific options + + Currently there are three option spaces defined: dhcp4 (to be used + in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); 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 an IPv6 address, an unsigned 16 bit integer + and a string. The "foo" option is conveyed in a vendor specific + information option. This option comprises a single uint32 value + that is set to "12345". The sub-option "foo" follows the data + field holding this value. + +> 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 + + (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: + +> 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. + + 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 ). + + + 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: + +> 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 + + Note that we have defined the options to belong to a new option space + (in this case, "isc"). + + +The next step is to define a regular DHCPv6 option and specify that it +should include options from the 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 "empty" +> 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 + + The name of the option space in which the sub-options are defined + is set in the "encapsulate" field. The "type" field is set to "empty" + which imposes that this option does not carry any data other than + sub-options. + + + Finally, we can set values for the 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 "" +> config commit + + Even though the "container" option does not carry any data except + sub-options, the "data" field must be explictly set to an empty value. + This is required because in the current version of BIND 10 DHCP, the + default configuration values are not propagated to the configuration parsers: + if the "data" is not set the parser will assume that this + parameter is not specified and an error will be reported. + + Note that it is possible to create an option which carries some data + in addition to the sub-options defined in the encapsulated option space. For example, + if the "container" option from the previous example was required to carry an uint16 + value as well as the sub-options, the "type" value would have to be set to "uint16" in + the option definition. (Such an option would then have the following + data structure: DHCP header, uint16 value, sub-options.) The value specified + with the "data" parameter - which should be a valid integer enclosed in quotes, + e.g. "123" - would then be assigned to the uint16 field in the "container" option. +
Subnet Selection - The DHCPv6 server may receive requests from local (connected to the same - subnet as the server) and remote (connecting via relays) - clients. + The DHCPv6 server may receive requests from local (connected + to the same subnet as the server) and remote (connecting via + relays) clients. Currently relayed DHCPv6 traffic is not supported. The server will @@ -4003,28 +4830,30 @@ Dhcp6/subnet6/ list The DHCPv6 protocol uses a "server identifier" (also known as a DUID) for clients to be able to discriminate between several servers present on the same link. There are several types of - DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if + DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if possible. This format consists of a link-layer (MAC) address and a timestamp. When started for the first time, the DHCPv6 server will automatically generate such a DUID and store the chosen value to - a file (The file is named b10-dhcp6-serverid and is stored in the - "local state directory". This is set during installation when - "configure" is run, and can be changed by using "--localstatedir" - on the "configure" command line.) That file will be read by the server + a file. That file is read by the server and the contained value used whenever the server is subsequently started. - It is unlikely that this parameter needs to be changed. If such a need - arises, please stop the server, edit the file and start the server - again. It is a text file that contains double digit hexadecimal values + It is unlikely that this parameter should ever need to be changed. + However, if such a need arises, stop the server, edit the file and restart + the server. (The file is named b10-dhcp6-serverid and by default is + stored in the "var" subdirectory of the directory in which BIND 10 is installed. + This can be changed when BIND 10 is built by using "--localstatedir" + on the "configure" command line.) The file is a text file that contains + double digit hexadecimal values separated by colons. This format is similar to typical MAC address format. Spaces are ignored. No extra characters are allowed in this file. +
- Supported DHCPv6 Standards + Supported Standards The following standards and draft standards are currently supported: