mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
[2657] DHCPv6 Options described.
This commit is contained in:
Tomek Mrugalski
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="dhcp6-std-options">
|
||||
<title>Standard DHCPv6 options</title>
|
||||
<para>
|
||||
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.
|
||||
|
||||
<screen>
|
||||
1. > <userinput>config add Dhcp6/option-data</userinput>
|
||||
2. > <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
|
||||
3. > <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
|
||||
4. > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
|
||||
5. > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
|
||||
6. > <userinput>config set Dhcp6/option-data[0]/data "2001:db8::cafe, 2001:db8::babe"</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="dhcp6-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 "dhcp6" as these are standard DHCPv6 options. For
|
||||
other name spaces, including custom option spaces, see <xref
|
||||
linkend="dhcp6-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 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.
|
||||
<screen>
|
||||
> <userinput>config add Dhcp6/option-data</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/name "dns-servers"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/code 23</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/csv-format false</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/data "2001 0DB8 0001 0000 0000 0000</userinput>
|
||||
<userinput>0000 0001 2001 0DB8 0001 0000 0000 0000 0000 0002"</userinput>
|
||||
<userinput>0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE"</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, the whole
|
||||
lines in this document for clarity: when entering the command, all the
|
||||
string should be entered on the same line.)
|
||||
</para>
|
||||
<para>
|
||||
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".
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
<screen>
|
||||
|
||||
<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 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]).
|
||||
<screen>
|
||||
> <userinput>config add Dhcp6/subnet6[0]/option-data</userinput>
|
||||
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/name "dns-servers"</userinput>
|
||||
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/code 23</userinput>
|
||||
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/data "2001 0DB8 0001 0000</userinput>
|
||||
<userinput>0000 0000 0000 0003"</userinput>
|
||||
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/space "dhcp6"</userinput>
|
||||
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/csv-format true</userinput>
|
||||
> <userinput>config set Dhcp6/subnet6[0]/option-data[0]/data "2001:db8:1::3"</userinput>
|
||||
> <userinput>config commit</userinput></screen>
|
||||
(As before, the setting of the "data" element has been split across two
|
||||
lines for clarity.)
|
||||
</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 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.
|
||||
</para>
|
||||
|
||||
<!-- @todo: describe record types -->
|
||||
|
||||
<para>
|
||||
<itemizedlist id="dhcp6-std-options-list">
|
||||
<title>List of standard DHCPv6 options</title>
|
||||
<!-- Our engine uses those options on its own, admin must not configure them on his own
|
||||
<listitem><para>name: clientid, code: 1, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: serverid, code: 2, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: ia-na, code: 3, type: record, array false</para></listitem>
|
||||
<listitem><para>name: ia-ta, code: 4, type: uint32, array false</para></listitem>
|
||||
<listitem><para>name: iaaddr, code: 5, type: record, array false</para></listitem>
|
||||
<listitem><para>name: oro, code: 6, type: uint16, array true</para></listitem> -->
|
||||
<listitem><para>name: preference, code: 7, type: uint8, array false</para></listitem>
|
||||
|
||||
<!-- Our engine uses those options on its own, admin must not configure them on his own
|
||||
<listitem><para>name: elapsed-time, code: 8, type: uint16, array false</para></listitem>
|
||||
<listitem><para>name: relay-msg, code: 9, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: auth, code: 11, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: unicast, code: 12, type: ipv6-address, array false</para></listitem>
|
||||
<listitem><para>name: status-code, code: 13, type: record, array false</para></listitem>
|
||||
<listitem><para>name: rapid-commit, code: 14, type: empty, array false</para></listitem>
|
||||
<listitem><para>name: user-class, code: 15, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: vendor-class, code: 16, type: record, array false</para></listitem>
|
||||
<listitem><para>name: vendor-opts, code: 17, type: uint32, array false</para></listitem>
|
||||
<listitem><para>name: interface-id, code: 18, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: reconf-msg, code: 19, type: uint8, array false</para></listitem>
|
||||
<listitem><para>name: reconf-accept, code: 20, type: empty, array false</para></listitem> -->
|
||||
<listitem><para>name: sip-server-dns, code: 21, type: fqdn, array true</para></listitem>
|
||||
<listitem><para>name: sip-server-addr, code: 22, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: dns-servers, code: 23, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: domain-search, code: 24, type: fqdn, array true</para></listitem>
|
||||
<listitem><para>name: ia-pd, code: 25, type: record, array false</para></listitem>
|
||||
<listitem><para>name: iaprefix, code: 26, type: record, array false</para></listitem>
|
||||
<listitem><para>name: nis-servers, code: 27, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: nisp-servers, code: 28, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: nis-domain-name, code: 29, type: fqdn, array true</para></listitem>
|
||||
<listitem><para>name: nisp-domain-name, code: 30, type: fqdn, array true</para></listitem>
|
||||
<listitem><para>name: sntp-servers, code: 31, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: information-refresh-time, code: 32, type: uint32, array false</para></listitem>
|
||||
<listitem><para>name: bcmcs-server-dns, code: 33, type: fqdn, array true</para></listitem>
|
||||
<listitem><para>name: bcmcs-server-addr, code: 34, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: geoconf-civic, code: 36, type: record, array false</para></listitem>
|
||||
<listitem><para>name: remote-id, code: 37, type: record, array false</para></listitem>
|
||||
<listitem><para>name: subscriber-id, code: 38, type: binary, array false</para></listitem>
|
||||
<listitem><para>name: client-fqdn, code: 39, type: record, array false</para></listitem>
|
||||
<listitem><para>name: pana-agent, code: 40, type: ipv6-address, array true</para></listitem>
|
||||
<listitem><para>name: new-posix-timezone, code: 41, type: string, array false</para></listitem>
|
||||
<listitem><para>name: new-tzdb-timezone, code: 42, type: string, array false</para></listitem>
|
||||
<listitem><para>name: ero, code: 43, type: uint16, array true</para></listitem>
|
||||
<listitem><para>name: lq-query, code: 44, type: record, array false</para></listitem>
|
||||
<listitem><para>name: client-data, code: 45, type: empty, array false</para></listitem>
|
||||
<listitem><para>name: clt-time, code: 46, type: uint32, array false</para></listitem>
|
||||
<listitem><para>name: lq-relay-data, code: 47, type: record, array false</para></listitem>
|
||||
<listitem><para>name: lq-client-link, code: 48, type: ipv6-address, array true</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="dhcp6-custom-options">
|
||||
<title>Custom DHCPv6 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 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:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp6/option-def</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/code 100</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/type "uint32"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/record-types ""</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
|
||||
> <userinput>config set Dhcp6/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 Dhcp6/option-data</userinput>
|
||||
2. > <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
|
||||
3. > <userinput>config set Dhcp6/option-data[0]/code 100</userinput>
|
||||
4. > <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
|
||||
5. > <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
|
||||
6. > <userinput>config set Dhcp6/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, 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:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp6/option-def</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/name "bar"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/code 101</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/space "dhcp6"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/encapsulate ""</userinput>
|
||||
</screen>
|
||||
Its values can be later defined as follows:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp6/option-data</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/name "bar"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/space "dhcp6"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/code 101</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 123, Hello World"</userinput>
|
||||
7. > <userinput>config commit</userinput></screen>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="dhcp6-vendor-opts">
|
||||
<title>DHCPv6 vendor specific options</title>
|
||||
<para>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.
|
||||
<screen>
|
||||
> <userinput>config add Dhcp6/option-def</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/name "foo"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/code 1</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/space "vendor-opts-space"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/type "record"</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/array false</userinput>
|
||||
> <userinput>config set Dhcp6/option-def[0]/record-types "ipv6-address, uint16, string"</userinput>
|
||||
> <userinput>config set Dhcp6/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 Dhcp6/option-data</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/name "foo"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/space "vendor-opts-space"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/code 1</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/csv-format true</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[0]/data "2001:db8:1::10, 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 Dhcp6/option-data</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[1]/name "vendor-opts"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[1]/space "dhcp6"</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[1]/code 17</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[1]/csv-format true</userinput>
|
||||
> <userinput>config set Dhcp6/option-data[1]/data "12345"</userinput>
|
||||
> <userinput>config commit</userinput></screen>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="dhcp6-option-spaces">
|
||||
<title>Nested DHCPv6 options (custom option spaces)</title>
|
||||
<para>It is sometimes useful to define completely new option
|
||||
spaces. This is useful if the user wants his new option to
|
||||
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:
|
||||
<screen>
|
||||
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</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 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</screen>
|
||||
|
||||
Finally, we should specify values for those new options:
|
||||
<screen>
|
||||
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</screen>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
|
||||
<section id="dhcp6-config-subnets">
|
||||
<title>Subnet Selection</title>
|
||||
|
||||
Reference in New Issue
Block a user