mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-30 21:45:37 +00:00
[2657] Edits to the DHCP section of the guide as part of the review
This commit is contained in:
Stephen Morris
@@ -3643,7 +3643,7 @@ Dhcp4/subnet4 [] list (default)
|
||||
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 <xref
|
||||
linkend="dhcp4-option-spaces"/>. The fifth line specfies the format in
|
||||
linkend="dhcp4-option-spaces"/>. 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
|
||||
@@ -3663,13 +3663,9 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <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 set Dhcp4/option-data[0]/data "C0 00 03 01 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, the
|
||||
string should be entered on the same line.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -3697,30 +3693,35 @@ Dhcp4/subnet4 [] list (default)
|
||||
</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
|
||||
<para>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.</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Below is a list of currently supported standard DHCPv4 options. The 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:
|
||||
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 <xref linkend="dhcp-types"/>.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<!-- @todo: describe record types -->
|
||||
|
||||
<para>
|
||||
<table border="1" cellpadding="5%" id="dhcp4-std-options-list">
|
||||
<para>
|
||||
<table border="1" cellpadding="5%" id="dhcp4-std-options-list">
|
||||
<caption>List of standard DHCPv4 options</caption>
|
||||
<thead>
|
||||
<tr><td>Name</td><td>Code</td><td>Type</td><td>Array?</td></tr>
|
||||
<tr></tr>
|
||||
<tr><th>Name</th><th>Code</th><th>Type</th><th>Array?</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>subnet-mask</td><td>1</td><td>ipv4-address</td><td>false</td></tr>
|
||||
<tr><td>time-offset</td><td>2</td><td>uint32</td><td>false</td></tr>
|
||||
<tr><td>routers</td><td>3</td><td>ipv4-address</td></tr>
|
||||
<tr><td>routers</td><td>3</td><td>ipv4-address</td><td>true</td></tr>
|
||||
<tr><td>time-servers</td><td>4</td><td>ipv4-address</td><td>true</td></tr>
|
||||
<tr><td>name-servers</td><td>5</td><td>ipv4-address</td><td>false</td></tr>
|
||||
<tr><td>domain-name-servers</td><td>6</td><td>ipv4-address</td><td>true</td></tr>
|
||||
@@ -3799,17 +3800,37 @@ Dhcp4/subnet4 [] list (default)
|
||||
<tr><td>domain-search</td><td>119</td><td>binary</td><td>false</td></tr>
|
||||
<tr><td>vivco-suboptions</td><td>124</td><td>binary</td><td>false</td></tr>
|
||||
<tr><td>vivso-suboptions</td><td>125</td><td>binary</td><td>false</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</para>
|
||||
</tbody>
|
||||
</table>
|
||||
</para>
|
||||
<para>
|
||||
<table border="1" cellpadding="5%" id="dhcp-types">
|
||||
<caption>List of standard DHCP option types</caption>
|
||||
<thead>
|
||||
<tr><th>Name</th><th>Meaning</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>binary</td><td>An arbitrary string of bytes, specified as a set of hexadecimal digits.</td></tr>
|
||||
<tr><td>boolean</td><td>Boolean value with allowed values true or false</td></tr>
|
||||
<tr><td>empty</td><td>No value, data is carried in suboptions</td></tr>
|
||||
<tr><td>fqdn</td><td>Fully qualified domain name (e.g. www.example.com)</td></tr>
|
||||
<tr><td>ipv4-address</td><td>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</td></tr>
|
||||
<tr><td>ipv6-address</td><td>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</td></tr>
|
||||
<tr><td>record</td><td>Structured data that may comprise any types (except "record" and "empty")</td></tr>
|
||||
<tr><td>string</td><td>Any text</td></tr>
|
||||
<tr><td>uint8</td><td>8 bit unsigned integer with allowed values 0 to 255</td></tr>
|
||||
<tr><td>uint16</td><td>16 bit unsinged integer with allowed values 0 to 65535</td></tr>
|
||||
<tr><td>uint32</td><td>32 bit unsigned integer with allowed values 0 to 4294967295</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</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
|
||||
<para>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:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-def</userinput>
|
||||
@@ -3821,12 +3842,12 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <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.
|
||||
Note that the above set of comments define the format of the new option and do not
|
||||
set its values.
|
||||
</para>
|
||||
<para>Once the new option format is defined, 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.
|
||||
<para>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.
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-data</userinput>
|
||||
> <userinput>config set Dhcp4/option-data[0]/name "foo"</userinput>
|
||||
@@ -3838,7 +3859,7 @@ Dhcp4/subnet4 [] list (default)
|
||||
</para>
|
||||
|
||||
<para>New options can take more complex forms than simple use of
|
||||
primitives (uint8, string, ipv4-address etc). It is possible to
|
||||
primitives (uint8, string, ipv4-address etc): it is possible to
|
||||
define an option comprising a number of existing primitives.
|
||||
</para>
|
||||
<para>Assume we
|
||||
@@ -3855,7 +3876,12 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <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:
|
||||
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 <xref linkend="dhcp-types"/>.
|
||||
</para>
|
||||
<para>
|
||||
The values of the option are set as follows:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-data</userinput>
|
||||
> <userinput>config set Dhcp4/option-data[0]/name "bar"</userinput>
|
||||
@@ -3865,19 +3891,24 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <userinput>config set Dhcp4/option-data[0]/data "192.0.2.100, 123, Hello World"</userinput>
|
||||
> <userinput>config commit</userinput></screen>
|
||||
</para>
|
||||
|
||||
"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.
|
||||
</section>
|
||||
|
||||
<section id="dhcp4-vendor-opts">
|
||||
<title>DHCPv4 vendor specific options</title>
|
||||
<para>Currently there are three 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
|
||||
be used in DHCPv4 daemon), dhcp6, and vendor-opts-space. The last-mentioned
|
||||
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 a
|
||||
vendor specific information option.
|
||||
<screen>
|
||||
</para>
|
||||
<para>
|
||||
The first step is to define the format of the 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>
|
||||
@@ -3886,8 +3917,10 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <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
|
||||
> <userinput>config commit</userinput>
|
||||
</screen>
|
||||
(Note that the option space is set to "vendor-encapsulated-option-space".)
|
||||
Once the option format is defined, the next step is to define actual values
|
||||
for that option:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-data</userinput>
|
||||
@@ -3897,7 +3930,7 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <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.
|
||||
We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo".
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-data</userinput>
|
||||
> <userinput>config set Dhcp4/option-data[1]/name "vendor-encapsulated-options"</userinput>
|
||||
@@ -3927,10 +3960,12 @@ Dhcp4/subnet4 [] list (default)
|
||||
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:
|
||||
space must be defined.
|
||||
</para>
|
||||
<para>
|
||||
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:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-def</userinput>
|
||||
> <userinput>config set Dhcp4/option-def[0]/name "subopt1"</userinput>
|
||||
@@ -3952,8 +3987,12 @@ Dhcp4/subnet4 [] list (default)
|
||||
> <userinput>config set Dhcp4/option-def[1]/encapsulate ""</userinput>
|
||||
> <userinput>config commit</userinput>
|
||||
</screen>
|
||||
The next step is to define a regular DHCPv6 option and specify that it
|
||||
should include options from isc option space:
|
||||
Note that we have defined the options to belong to a new option space
|
||||
(in this case, "isc").
|
||||
</para>
|
||||
<para>
|
||||
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:
|
||||
<screen>
|
||||
> <userinput>add Dhcp4/option-def</userinput>
|
||||
> <userinput>set Dhcp4/option-def[2]/name "container"</userinput>
|
||||
@@ -3965,8 +4004,11 @@ should include options from isc option space:
|
||||
> <userinput>set Dhcp4/option-def[2]/encapsulate "isc"</userinput>
|
||||
> <userinput>commit</userinput>
|
||||
</screen>
|
||||
|
||||
Finally, we should specify values for those new options:
|
||||
The name of the option space in which the sub-options are defined
|
||||
is set in the "encapsulates" field.
|
||||
</para>
|
||||
<para>
|
||||
Finally, we can set values for the new options:
|
||||
<screen>
|
||||
> <userinput>config add Dhcp4/option-data</userinput>
|
||||
> <userinput>config set Dhcp4/option-data[0]/name "subopt1"</userinput>
|
||||
@@ -3992,26 +4034,31 @@ Finally, we should specify values for those new options:
|
||||
> <userinput>config set Dhcp4/option-data[2]/data "123"</userinput>
|
||||
> <userinput>config commit</userinput>
|
||||
</screen>
|
||||
Even though the "container" option comprises sub-options, we need to
|
||||
set dummy values for it so that it is included in the data sent to a
|
||||
client.
|
||||
</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
|
||||
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.
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
@@ -4340,7 +4387,7 @@ Dhcp6/subnet6/ list
|
||||
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 <xref
|
||||
linkend="dhcp6-option-spaces"/>. The fifth line specfies the format in
|
||||
linkend="dhcp6-option-spaces"/>. 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
|
||||
@@ -4394,42 +4441,38 @@ Dhcp6/subnet6/ list
|
||||
> <userinput>config commit</userinput></screen>
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>In future version of Kea versions, it will not be necessary to specify
|
||||
option code, space and csv-format fields as those fields will be set
|
||||
automatically.</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
In future version of Kea versions, it will not be necessary to specify
|
||||
option code, space and csv-format fields as those fields will be set
|
||||
automatically.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
|
||||
<para>
|
||||
Below is a list of currently supported standard DHCPv6 options. The 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:
|
||||
|
||||
<itemizedlist id="dhcp6-option-types">
|
||||
<listitem><simpara>uint8 means 8 bit unsigned integer with allowed values 0 to 255.</simpara></listitem>
|
||||
<listitem><simpara>uint16 means 16 bit unsinged integer with allowed values 0 to 65535.</simpara></listitem>
|
||||
<listitem><simpara>uint32 means 32 bit unsigned integer with allowed values 0 to 4294967295.</simpara></listitem>
|
||||
<listitem><simpara>ipv6-address means a normal IPv6 address.</simpara></listitem>
|
||||
<listitem><simpara>fqdn means fully qualified domain name.</simpara></listitem>
|
||||
<listitem><simpara>String means any text.</simpara></listitem>
|
||||
</itemizedlist>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Below is a list of currently supported standard DHCPv6 options. The 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 and is one of
|
||||
the types listed in <xref linkend="dhcp-types"/>.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<!-- @todo: describe record types -->
|
||||
|
||||
<para>
|
||||
<table border="1" cellpadding="5%" id="dhcp6-std-options-list">
|
||||
<caption>List of standard DHCPv6 options</caption>
|
||||
<thead>
|
||||
<tr><td>Name</td><td>Code</td><td>Type</td><td>Array?</td></tr>
|
||||
<para>
|
||||
<table border="1" cellpadding="5%" id="dhcp6-std-options-list">
|
||||
<caption>List of standard DHCPv6 options</caption>
|
||||
<thead>
|
||||
<tr><th>Name</th><th>Code</th><th>Type</th><th>Array?</th></tr>
|
||||
<tr></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
</thead>
|
||||
<tbody>
|
||||
<!-- Our engine uses those options on its own, admin must not configure them on his own
|
||||
<tr><td>clientid</td><td>1</td><td>binary</td><td>false</td></tr>
|
||||
<tr><td>serverid</td><td>2</td><td>binary</td><td>false</td></tr>
|
||||
@@ -4479,9 +4522,9 @@ Dhcp6/subnet6/ list
|
||||
<tr><td>clt-time</td><td>46</td><td>uint32</td><td>false</td></tr>
|
||||
<tr><td>lq-relay-data</td><td>47</td><td>record</td><td>false</td></tr>
|
||||
<tr><td>lq-client-link</td><td>48</td><td>ipv6-address</td><td>true</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</para>
|
||||
</tbody>
|
||||
</table>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="dhcp6-custom-options">
|
||||
@@ -4715,20 +4758,22 @@ Finally, we should specify values for those new options:
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section id="dhcp6-std">
|
||||
|
||||
Reference in New Issue
Block a user