One document matched: draft-ietf-dhc-option-guidelines-09.xml
<?xml version='1.0' ?>
<?rfc toc="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc3315 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3315.xml">
<!ENTITY rfc3319 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3319.xml">
<!ENTITY rfc3633 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3633.xml">
<!ENTITY rfc3646 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3646.xml">
<!ENTITY rfc3898 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3898.xml">
<!ENTITY rfc3972 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3972.xml">
<!ENTITY rfc4075 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4075.xml">
<!ENTITY rfc4242 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4242.xml">
<!ENTITY rfc4280 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4280.xml">
<!ENTITY rfc4704 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4704.xml">
<!ENTITY rfc5908 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5908.xml">
<!ENTITY rfc5970 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5970.xml">
<!ENTITY rfc6334 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6334.xml">
<!ENTITY rfc6603 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6603.xml">
<!ENTITY rfc6610 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6610.xml">
]>
<rfc category="std" docName="draft-ietf-dhc-option-guidelines-09"
updates="3315" ipr="trust200902">
<front>
<title abbrev="DHCPv6 Option Guidelines">Guidelines for Creating New
DHCPv6 Options</title>
<author initials="D." surname="Hankins" fullname="David W. Hankins">
<organization abbrev="Google">Google, Inc.</organization>
<address>
<postal>
<street>1600 Amphitheatre Parkway</street>
<city>Mountain View</city>
<code>94043</code>
<region>CA</region>
<country>USA</country>
</postal>
<email>dhankins@google.com</email>
</address>
</author>
<author fullname="Tomasz Mrugalski" initials="T." surname="Mrugalski">
<organization abbrev="ISC">Internet Systems Consortium,
Inc.</organization>
<address>
<postal>
<street>950 Charter Street</street>
<city>Redwood City</city>
<region>CA</region>
<code>94063</code>
<country>USA</country>
</postal>
<phone>+1 650 423 1345</phone>
<email>tomasz.mrugalski@gmail.com</email>
</address>
</author>
<author fullname="Marcin Siodelski" initials="M." surname="Siodelski">
<organization abbrev="ISC"></organization>
<address>
<postal>
<street></street>
<city></city>
<region></region>
<code></code>
<country></country>
</postal>
<phone></phone>
<email>msiodelski@gmail.com</email>
</address>
</author>
<author fullname="Sheng Jiang" initials="S." surname="Jiang">
<organization>Huawei Technologies Co., Ltd</organization>
<address>
<postal>
<street>Q14, Huawei Campus, No.156 Beiqing Road</street>
<city>Hai-Dian District, Beijing, 100095</city>
<country>P.R. China</country>
</postal>
<email>jiangsheng@huawei.com</email>
</address>
</author>
<author initials="S.K." surname="Krishnan" fullname="Suresh Krishnan">
<organization>Ericsson</organization>
<address>
<postal>
<street>8400 Blvd Decarie</street>
<city>Town of Mount Royal</city>
<region>Quebec</region>
<country>Canada</country>
</postal>
<email>suresh.krishnan@ericsson.com</email>
</address>
</author>
<date />
<area>Internet</area>
<workgroup>Dynamic Host Configuration Working Group</workgroup>
<keyword>DHCPv6</keyword>
<keyword>option guidelines</keyword>
<keyword>option guidance</keyword>
<keyword>option format</keyword>
<abstract>
<t>This document provides guidance to prospective DHCPv6 Option
developers to help them creating option formats that are easily
adoptable by existing DHCPv6 software. This document updates
RFC3315.</t>
</abstract>
</front>
<middle>
<section title="Requirements Language">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
<xref target="RFC2119">RFC 2119</xref>.</t>
</section>
<section title="Introduction">
<t>Most protocol developers ask themselves if a protocol will work, or
work efficiently. These are important questions, but another less
frequently considered question is whether the proposed protocol presents
itself needless barriers to adoption by deployed software.</t>
<t><xref target="RFC3315">DHCPv6</xref> software implementors
are not merely faced with the task of handling a given option's
format on the wire. The option must fit into every stage of
the system's process, starting with the user interface used to
enter the configuration up to the machine interfaces where
configuration is ultimately consumed. <!-- To help understand the potential
implementation challenges of any new DHCP Option, <xref
target="isc">one implementation's approach to tackling DHCP
Option formats</xref> has been included as an Appendix.--></t>
<t>Another frequently overlooked aspect of rapid adoption is
whether the option requires operators to be intimately familiar
with the option's internal format in order to use it? Most
DHCPv6 software provides a facility for handling unknown options
at the time of publication. The handling of such options usually
needs to be manually configured by the operator. But if doing so
requires extensive reading (more than can be covered in a simple
FAQ for example), it inhibits adoption.</t>
<t>So although a given solution would work, and might even be space,
time, or aesthetically optimal, a given option is presented with a
series of ever-worsening challenges to be adopted;
<list style="symbols">
<t>If it doesn't fit neatly into existing config files.</t>
<t>If it requries new source code changes to be adopted, and
hence upgrades of deployed software.</t>
<t>If it does not share its deployment fate in a general manner with
other options, standing alone in requiring code changes or
reworking configuration file syntaxes.</t>
</list>
</t>
<t>There are many things DHCPv6 option creators can do to avoid
the pitfalls in this list entirely, or failing that, to make
software implementors lives easier and improve its chances for
widespread adoption.</t>
</section>
<section title="When to Use DHCPv6">
<t>Principally, DHCPv6 carries configuration parameters for its clients.
Any knob, dial, slider, or checkbox on the client system, such as
"my domain name servers", "my hostname", or even "my shutdown
temperature" are candidates for being configured by DHCPv6.</t>
<t>The presence of such a knob isn't enough, because DHCPv6 also presents
the extension of an administrative domain - the operator of the network
to which the client is currently attached. Someone runs not only
the local switching network infrastructure that the client is
directly (or wirelessly) attached to, but the various methods of
accessing the external Internet via local assist services that
network must also provide (such as domain name servers, or routers).
This means that in addition to the existence of a configuration
parameter, one must also ask themselves if it is reasonable for
this parameter to be set by the directly attached network's
administrators.</t>
<t>Note that the client still reserves the right to ignore
values received via DHCPv6 (for example, due to having a value
manually configured by its own operator). Bear in mind that
doing so might cause the client to be rejected network
attachment privileges, and this is one main reason for the use
of DHCPv6 in corporate enterprises. </t>
</section>
<section title="General Principles">
<t>The primary guiding principle to follow in order to enhance
an option's adoptability is simplification. More specifically,
the option should be created in such a way that does not require
any new or special case software to support. If old software
currently deployed and in the field can adopt the option through
supplied configuration facilities then it's fairly certain that
new software can easily formally adopt it.</t>
<t>There are at least two classes of DHCPv6 options: A bulk class of
options which are provided explicitly to carry data from one side of the
DHCPv6 exchange to the other (such as nameservers, domain names, or time
servers), and a protocol class of options which require special
processing on the part of the DHCPv6 software or are used during special
processing (such as the Fully Qualified Domain Name (FQDN) option <xref
target="RFC4704"></xref>), and so forth; these options carry data that
is the result of a routine in some DHCPv6 software.</t>
<t>The guidelines laid out here should be applied in a relaxed
manner for the protocol class of options. Wherever
special case code is already required to adopt the DHCPv6
option, it is substantially more reasonable to format the option
in a less generic fashion, if there are measurable benefits to
doing so.</t>
</section>
<section title="Reusing Other Options">
<t>The easiest approach to manufacturing trivially deployable DHCPv6
Options is to assemble the option out of whatever common fragments fit -
possibly allowing a group of fragments to repeat to fill the remaining
space (if present) and so provide multiple values. Place all fixed size
values at the start of the option, and any variable/indeterminate sized
value at the tail end of the option.</t>
<t>This estimates that implementations will be able to reuse code paths
designed to support the other options.</t>
<t>There is a tradeoff between the adoptability of previously defined
option formats, and the advantages that new or specialized formats can
provide. In general, it is usually preferrable to reuse previously
used option formats.</t>
<t>However, it isn't very practical to consider the bulk of DHCPv6
options already allocated, and consider which of those solve a similar
problem. So, the following list of common option format fragments is
provided as a shorthand. Please note that it is not complete in terms of
exampling every option format ever devised...it is only a list of option
format fragments which are used in two or more options.</t>
<section title="Option with IPv6 addresses">
<t>This option format is used to carry one or many IPv6
addresses. In some cases the number of allowed address is limited
(e.g. to one):</t>
<figure align="center" anchor="option-with-ipv6-address-format"
title="Option with IPv6 address">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| ipv6-address |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| ipv6-address |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC3315">DHCPv6 server unicast address</xref></t>
<t><xref target="RFC3319">SIP Servers IPv6 Address List</xref></t>
<t><xref target="RFC3646">DNS Recursive Name Server</xref></t>
<t><xref target="RFC3898">NIS Servers</xref></t>
<t><xref target="RFC4075">SNTP Servers</xref></t>
<t><xref target="RFC4280">Broadcast and Multicast Service
Controller IPv6 Address Option for DHCPv6</xref></t>
<t><xref target="RFC6610">MIPv6 Home Agent Address</xref> (a single
address only)</t>
<t><xref target="RFC5908">NTP server</xref> (a single
address only)</t>
<t><xref target="RFC5908">NTP Multicast address</xref> (a single
address only)</t>
</list>
</t>
</section>
<section title="Option with a single flag (boolean)">
<t>Sometimes it is useful to convey a single flag that can either
take on or off values. Instead of specifying an option with one
bit of usable data and 7 bits of padding, it is better to define
an option without any content. It is the presence or absence of
the option that conveys the value. This approach has the additional
benefit of absent option designating the default, i.e. administrator
has to take explicit actions to deploy the oposite of the default
value.</t>
<figure align="center" anchor="option-with-boolean-format"
title="Option for conveying boolean">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC3315">DHCPv6 rapid-commit</xref></t>
</list>
</t>
</section>
<section title="Option with IPv6 prefix">
<t>Sometimes there is a need to convey IPv6 prefix. The information that
should be delivered to the user is a 128-bit IPv6 prefix together with a
prefix length that takes values from 0 to 128. Using the simplest
approach, the option would convey that information as is. However, in
many cases /64 or shorter prefixes are used. That means that remaining
128 - prefix length bits are zeros. That means that in typical case case
of /64 prefixes the option would contains at least 8 bytes of useless
zeros. That should be avoided. For that reason the recommended format
for storing prefixes is as follows:</t>
<t><figure align="center" anchor="option-with-prefix-format"
title="Option with IPv6 Prefix">
<preamble></preamble>
<artwork align="center"><![CDATA[
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| OPTION_MAP_DMR | option-length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| prefix6-len | ipv6-prefix |
+-+-+-+-+-+-+-+-+ (variable length) |
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure></t>
<t>Option-length is set to 1 + length of the IPv6 prefix. Prefix6-len
it one octet long and specifies prefix length of the IPv6 prefix
expressed in bits. Typically allowed values are 0 to 128.</t>
<t>ipv6-prefix field is a variable length field that specifies the
IPv6 prefix. This field is padded with zeros up to the nearest octet
boundary when prefix6-len is not divisible by 8.</t>
<t>Examples of use:
<list style="symbols">
<t><xref target="I-D.ietf-softwire-map-dhcp">Default Mapping Rule</xref></t>
</list>
</t>
<t>It should be noted that Prefix Delegation mechanism used in <xref
target="RFC3633" /> uses constant length prefixes. The concern about
option length was not well understood at the time of its publication.
</t>
</section>
<section title="Option with 32-bit integer value">
<t>This option format can be used to carry 32 bit-signed or unsigned
integer value:</t>
<figure align="center" anchor="option-with-32-bit-integer-format"
title="Option with 32-bit-integer value">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32-bit-integer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC4242">Information Refresh Time</xref></t>
</list>
</t>
</section>
<section title="Option with 16-bit integer value">
<t>This option format can be used to carry 16-bit signed or unsigned
integer values:</t>
<figure align="center" anchor="option-with-16-bit-integer-format"
title="Option with 16-bit integer value">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 16-bit-integer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC3315">Elapsed Time</xref></t>
</list>
</t>
</section>
<section title="Option with 8-bit integer value">
<t>This option format can be used to carry 8-bit integer values:</t>
<figure align="center" anchor="option-with-8-bit-integer-format"
title="Option with 8-bit integer value">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 8-bit-integer |
+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC3315">DHCPv6 Preference</xref></t>
</list>
</t>
</section>
<section title="Option with variable length data">
<t>This option can be used to carry variable length data of
any kind. Internal representation of carried data is option
specific. Some of the existing DHCPv6 options use NVT-ASCII
strings to encode: filenames, host or domain names, protocol
features or textual messages such as verbose error indicators.</t>
<t>This option format provides a lot of flexibility to pass
data of almost any kind. Though, whenever possible it is highly
recommended to use more specialized options, with field types
better matching carried data types.</t>
<figure align="center" anchor="option-with-variable-length-data-format"
title="Option with variale length data">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. variable length data .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC3315">Client Identifier</xref></t>
<t><xref target="RFC3315">Server Identifier</xref></t>
<t><xref target="RFC5970">Boot File URL</xref></t>
</list>
</t>
</section>
<section title="Option with DNS Wire Format Domain Name List">
<t>This option is used to carry 'domain search' lists or any
host or domain name:</t>
<figure align="center" anchor="option-with-dns-domain-name-list-format"
title="Option with DNS Wire Format Domain Name List">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| DNS Wire Format Domain Name List |
| ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use:
<list style="symbols">
<t><xref target="RFC3319">SIP Servers Domain Name List</xref>
(many domains)</t>
<t><xref target="RFC3898">NIS Domain Name (many domains)</xref>
(many domains)</t>
<t><xref target="RFC6334">DS-Lite AFTR location</xref>
(a single FQDN)</t>
<t><xref target="RFC6610">Home Network Identifier</xref>
(a single FQDN)</t>
<t><xref target="RFC6610">Home Agent FQDN</xref> (a single FQDN)</t>
</list>
</t>
</section>
<section title="Option with IPv6 Prefix">
<t>Some options need to convey IPv6 prefix. Such a prefix includes
the prefix itself and a prefix length. The simple approach would be to
define a 128 bit field denoting a prefix, followed by a 8 bit field that
specifies prefix length. This approach was used in OPTION_IAPREFIX,
defined in <xref target="RFC3633"/>. That approach is no longer
recommended and should not be used anymore.</t>
<t>In many cases configured prefix lengths are /64 or even shorter. That means that
every option conveys many zeroes bits that are useless. For example
for /48 there are 10 bytes of useless data. This waste is mulitpled
by the number of option instances in a message. Therefore a different
approach should be used. Prefixes should be conveyed as 8 bit prefix length
field that is followed by variable length prefix.</t>
<figure align="center" anchor="option-with-ipv6-prefix-format"
title="Option with IPv6 Prefix">
<artwork><![CDATA[ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| option-code | option-length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| prefix6-len | |
+-+-+-+-+-+-+-+-+ ipv6-prefix |
| (variable length) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>The following description of the fields can be included in
the draft:
<list style="symbols">
<t>prefix6-len: 8 bits long field expressing the bit mask length
of the IPv6 prefix specified in the ipv6-prefix field.</t>
<t>ipv6-prefix: a variable length field that specifies the
IPv6 prefix for (explain purpose of the prefix). The field
is padded with zeros up to the nearest octet boundary when
prefix6-len is not divisible by 8.</t>
</list>
</t>
<t>It should be pointed out that similar optimization does
not provide useful savings in case of IPv4 prefixes. IPv4 prefixes
should be sent as a 32 bits fields.</t>
</section>
</section>
<section title="Avoid Conditional Formatting">
<t>Placing a octet at the start of the option which informs the software
how to process the remaining octets of the option may appear simple to
the casual observer. But the only conditional formatting methods that
are in widespread use today are 'protocol' class options. So conditional
formatting requires new code to be written, as well as introduces an
implementation problem; as it requires that all speakers implement all
current and future conditional formats.</t>
<t>Conditional formatting is not recommended, except in cases
where the DHCPv6 option has already been deployed
experimentally, and all but one conditional format is
deprecated.</t>
</section>
<section anchor="aliasing" title="Avoid Aliasing">
<t>Options are said to be aliases of each other if they provide input to
the same configuration parameter. A commonly proposed example is to
configure the location of some new service ("my foo server") using a
binary IP address, a domain name field, and a URL. This kind of aliasing
is undesirable, and is not recommended.</t>
<t>In this case, where three different formats are supposed, it
more than triples the work of the software involved, requiring
support for not merely one format, but support to produce and
digest all three. Furthermore, code development and testing must
cover all possible combinations of defined formats. Since
clients cannot predict what values the server will provide, they
must request all formats... so in the case where the server is
configured with all formats, DHCPv6 option space is wasted on
option contents that are redundant.</t>
<t>It also becomes unclear which types of values are mandatory, and how
configuring some of the options may influence the others. For example,
if an operator configures the URL only, should the server synthesize a
domain name and IP address?</t>
<t>A single configuration value on a host is probably presented to the
operator (or other software on the machine) in a single field or
channel. If that channel has a natural format, then any alternative
formats merely make more work for intervening software in providing
conversions.</t>
<t>So the best advice is to choose the one method that best fulfills the
requirements, be that for simplicity (such as with an IP address and
port pair), late binding (such as with DNS), or completeness (such as
with a URL).</t>
</section>
<section title="Choosing between FQDN and address">
<t>Some parameters may be specified as FQDN or an address. It is not
allowed to define both option types at the same time (see section
<xref target="aliasing"/>), so one of them must be chosen. This
section is intended as a help to make an informed decision in that
regard.</t>
<t>On the specific subject of desiring to configure a value using a FQDN
instead of a binary IP address, note that most DHCPv6 server
implementations will happily accept a Domain Name entered by the
administrator, and use DNS resolution to render binary IP addresses in
DHCPv6 replies to clients. Consequently, consider the extra packet
overhead incurred on the client's end to perform DNS resolution itself.
The client may be operating on a battery and packet transmission is a
non-trivial use of power, and the extra RTT delays the client must
endure before the service is configured are at least two factors to
consider in making a decision on format.</t>
<t>Unless there are specific reasons to do otherwise, address should
be used. It is simpler to use, its validation is trivial (length
of 16 constitutes a valid option), is explicit and does not allow
any ambiguity. It is faster (does not require extra resolution efforts),
so it is more efficient, which can be especially important for
energy restricted devices.</t>
<t>FQDN does require a resolution into an actual address. This implies
number of questions that should be answered. First is when should
the resolution be taken. There are couple possible answers: a) by the
server, when it is started, b) by the server, when it
is about to send an option, c) by the client, immediately after
receiving an option, d) by the client, when the content of the option
is actually consumed. For a), b) and possibly c), the option should really
convey an address, not FQDN. The only real incentive to use FQDN is
case d). It is the only case that allows possible changes in the DNS to
be picked up by clients.</t>
<t>FQDN imposes number of additional failure modes and issues that
should be dealt with:
<list>
<t>The client must have a knowledge about available DNS servers. That
typically means that option DNS_SERVERS is mandatory. This should be
mentioned in the draft that defines new option. It is possible
that the server will return FQDN option, but not the DNS Servers option.
There should be a brief discussion about it;</t>
<t>The DNS may not be reachable;</t>
<t>DNS may be available, but may not have appropriate information
(e.g. no AAAA records for specified FQDN)</t>
<t>Address family must be specified (A, AAAA or any);</t>
<t>What should the client do if there are multiple records available
(use only the first one, use all, use one and switch to the second
if the first fails for whatever reason, etc.);</t>
<t>Multi-homed devices may be connected to different administrative
domains with each domain providing a different information in DNS (e.g.
an enterprise network exposing private domains). Client may send
DNS queries to a different DNS server;</t>
<t>It should be mentioned if Internationalized Domain Names are allowed.
If they are, what kind of DNS option encoding should be specified.</t>
</list></t>
</section>
<section title="Suboptions in DHCPv6">
<t>Most options are conveyed in a DHCPv6 message
directly. Although there is no codified normative language for
such options, they are often referred to as top-level
options. Many options may include other options. Such inner
options are often referred to as sub-options. It should be noted
that, contrary to DHCPv4, there is no shortage of option
numbers. Therefore all options share a common option space. For
example option type 1 meant different things in DHCPv4,
depending if it was located in top-level or inside of Relay
Agent Information option. There is no such ambiguity in
DHCPv6 (with the exception of <xref target="RFC5908"/>).</t>
<t>Such encapsulation mechanism is not limited to one
level. There is at least one defined option that is encapsulated
twice: Identity Association for Prefix Delegation (IA_PD,
defined in <xref target="RFC3633"/>, section 9) conveys IA
Prefix (IAPREFIX, defined in <xref target="RFC3633"/>, section
10). Such delegated prefix may contain an excluded prefix range
that is represented by PD_EXCLUDE option that is conveyed as
sub-option inside IAPREFIX (PD_EXCLUDE, defined in <xref
target="RFC6603"/>). It seems awkward to refer to such options
as sub-sub-option, therefore "sub-option" term is typically
used, regardless of the nesting level.</t>
<t>When defining configuration means for more complex
mechanisms, it may be tempting to simply use sub-options. That
should usually be avoided, as it increases complexity of the
parser. It is much easier, faster and less error prone to parse
larger number of options on a single (top-level) scope, than
parse options on several scopes. The use of sub-options should
be avoided as much as possible but it is better to use
sub-options rather than conditional formatting.</t>
<t>It should be noted that currently there is no clear way
defined for requesting sub-options. Most known implementations
are simply using top-level ORO for requesting both top-level
options and sub-options.</t>
</section>
<section title="Additional States Considered Harmful">
<t>DHCP is a protocol designed for provisioning nodes. Less
experienced protocol designers often assume that it is easy to
define an option that will convey a different parameter for each
node in a network. Such problems arose during designs of MAP
<xref target="I-D.ietf-softwire-map-dhcp"/>
and 4rd <xref target="I-D.ietf-softwire-4rd"/>. While it
would be easier for provisioned nodes to get ready to use per
node option values, such requirement puts exceedingly large
loads on the server side. Alternatives should be considered,
if possible. As an example, <xref
target="I-D.ietf-softwire-map-dhcp"/> was designed in a
way that all nodes are provisioned with the same set of MAP
options and each provisioned node uses its unique address and
delegated prefix to generate node-specific information. Such
solution does not introduce any additional state for the server
and therefore scales better.</t>
<t>It also should be noted that contrary to DHCPv4, DHCPv6 keeps
several timers for renewals. Each IA_NA (addresses) and IA_PD
(prefixes) contains T1 and T2 timers that designate time after
which client will initiate renewal. Those timers apply only to
its own IA containers. For renewing other parameters, please use
Information Refresh Time Option (defined in <xref
target="RFC4242"/>). Introducing additional timers make
deployment unnecessarily complex. Please try to avoid it.</t>
</section>
<section title="Is DHCPv6 dynamic?">
<t>DHCPv6 stands for Dynamic Host Configuration Protocol for
IPv6. Contrary to its name, is many contexts it is not
dynamic. While designing DHCPv6 options, it is worth noting that
there is no reliable way to instantly notify clients that
something has happened, e.g. parameter value has changed. There
is a RECONFIGURE mechanism, but it has several serious drawbacks
that makes its use difficult. First, its support is optional and
many client implementations do not support it. To use
reconfigure mechanism, server must use its secret nonce. That
means that provisioning server is the only one that can initiate
reconfiguration. Other servers do not know it and cannot trigger
reconfiguration. Therefore the only reliable way for clients to
refresh their configuration is to wait till T1 expires.</t>
</section>
<section title="Multiple provisioning domains">
<t>In some cases there could be more than one DHCPv6 server on a
link, with each provisioning a different set of parameters. One
notable example of such case is a home network with a connection
to two independent ISPs.</t>
<t>DHCPv6 was not initially designed with multiple provisioning
domains. Although <xref target="RFC3315"/> states that a client
that receives more than one ADVERTISE message, may respond to
one or more, such capability was never observed in any known
implementations. Existing clients will pick one server and will
continue configuration process with that server, ignoring all
other servers.</t>
<t>This is a generic DHCP protocol issue and should not be dealt
within each option separately. This issue is better dealt with
using a protocol-level solution and fixing this problem should not
be attempted on a per option basis.</t>
</section>
<section title="Considerations for Creating New Formats">
<t>If the option simply will not fit into any existing work by using
fragments, the last recourse is to create a new format to fit.</t>
<t>When doing so, it is not enough to gauge whether or not the option
format will work in the context of the option presently being
considered. It is equally important to consider if the new format's
fragments might reasonably have any other uses, and if so, to create
the option with the foreknowledge that its parts may later become a
common fragment.</t>
<t>One specific consideration to evaluate is whether or not options
of a similar format would need to have multiple or single values
encoded (whatever differs from the current option), and how that
might be accomplished in a similar format.</t>
</section>
<!-- <section title="The Dangers of Sub Options">
<t>Some DHCP options, such as the <xref target="RFC3046">DHCPv4 Relay
Agent Information Option</xref> are defined to contain a series of DHCP
options, possibly using code tags specific to that option (but not in
some limited "protocol feature" cases in <xref
target="RFC3315">DHCPv6</xref>). These are commonly referred to as
Encapsulated Option Spaces or more simply, Sub Options.</t>
<t>Sub options seem very attractive, because they allow the encoding of
multiple variable length fields within the single "parent" option.
However, DHCP software will only include these options on an "all or
nothing" basis, there is no well deployed mechanism for "Sub Option
Parameter Request Lists" (although some defined sub-option spaces, such
as for DOCSIS, do describe sub-option scoped PRL analogues), and the
software will not include the entire option if there is not sufficient
space.</t>
<t>Consequently, it is not advisable to group options that may not be
requested at the same time by the same client under an encapsulated
space.</t>
<t>Another attraction sub options present is ease of extending the
configuration value for later, related configuration. This must be
weighed against the cost associated with asking IANA to maintain the
space's internally assigned option codes. Generally, the cost to IANA is
greater, as it is unlikely that options will be later extended.</t>
<t>The use of sub-options is not a solution to aliasing problems.
Sub-options that contain multiple configuration values that alias the
same configuration element actually makes matters worse. The only
solution to aliasing problems is to select a single option format, or
where that is literally impossible, to use multiple DHCP options. In
this way, clients may place only the options they support on their
parameter request list, in the order they support them. Later protocol
maintenance may incorporate a means to select a single DHCP option code
out of a list of aliased options, so do not concern yourself with packet
space issues arising from receiving all the aliases.</t>
<t>Additionally, DHCPv4 <xref target="fragmentation">option
concatenation </xref> has not been defined in any DHCPv4 sub-options
space. Currently there is some DHCP software which does concatenate
multiple DHCP options present in a sub-option space. There is also
software that treats multiple DHCP option codes present in a sub-option
as individual single options. So there is no reliably predictable
default behaviour.</t>
<t>Because no sub-options space has yet been defined that includes the
possibility of having more than one instance of an option of the same
code, any attempt to do so is discouraged.</t>
</section> -->
<section anchor="fragmentation" title="Option Size">
<t><xref target="RFC3315">DHCPv6</xref> allows for packet sizes up to 64KB.
First, through its use of link-local addresses, it steps aside many of
the deployment problems that plague DHCPv4, and is actually an UDP over
IPv6 based protocol (compared to DHCPv4, which is mostly UDP over IPv4
protocol, but with layer 2 hacks). Second, RFC 3315 explicitly refers
readers to RFC 2460 Section 5, which describes an MTU of 1280 octets and
a minimum fragment reassembly of 1500 octets. It's feasible to suggest
that DHCPv6 is capable of having larger options deployed over it, and at
least no common upper limit is yet known to have been encoded by its
implementors. It is impossible to describe any fixed limit that cleanly
divides those too big from the workable.</t>
<t>It is advantageous to prefer option formats which contain the desired
information in the smallest form factor that satisfies the
requirements.</t>
<t>DHCPv6 does allow for multiple instances of a given option,
and they are treated as distinct values following the defined
format, however this feature is generally preferred to be
restricted to protocol class features (such as the IA_* series
of options). In such cases, it is better to define an option as
an array if it is possible. It is recommended to clarify (with
normative language) whether a given DHCPv6 option may appear
once or multiple times.</t>
</section>
<section title="Clients Request their Options">
<t>The <xref target="RFC3315">DHCPv6 Option Request Option
(OPTION_ORO)</xref>, is an option that serves two purposes - to
inform the server what options the client supports and is
willing to consume.
<!-- tomek: order is not important in DHCPv6; there are no concerns
with options not fitting in the packet in sane v6 implementations -->
<!--, and in what order of priority the client places those option
contents (in the event that they will not fit in the packet, later
options are to be dropped).--></t>
<t>It doesn't make sense for some options to appear on this
Option Request Option, such as those formed by elements of the
protocol's internal workings, or are formed on either end by
DHCPv6-level software engaged in some exchange of
information. When in doubt, it is prudent to assume that any new
option must be present on the relevant option request list if
the client desires to receive it.</t>
<t>It is a frequent mistake of option draft authors, then, to create
text that implies that a server will simply provide the new option,
and clients will digest it. Generally, it's best to also specify
that clients MUST place the new option code on the Option Request
Option list, clients MAY include the new option in their packets to
servers with hints as values they desire, and server MAY include
the option when the client requested it (and the server has been so
configured).</t>
<t>Example: Clients MUST place the foo option code on the Option Request
Option list, clients MAY include option foo in their packets as
hints for the server as values the desire, and servers MAY include
option foo when the client requested it (and the server has been
so configured).</t>
<t>Creators of DHCPv6 options MUST NOT require special ordering
of options either in the relevant request option, or in the
order of options within the packet. Although it is reasonable to
expect that options will be processed in the order they appear
in ORO, server software is not required to sort DHCPv6 options
into the same order in reply messages. It should be noted that
any requirement regarding option ordering will break down most
existing implementations, as "order is not important" was one of
the design priciples of DHCPv6 and many implementations follow
it. For example, there are existing implementations that use
hash maps for storing options, so forcing any particular order
is not feasible without great deal of work. If options must be
processed in any specific order (e.g. due to inter-dependency),
use of option encapsulation should be considered.</t>
</section>
<section title="Transition Technologies">
<t>Transition from IPv4 to IPv6 is progressing, albeit at somewhat
disappointing pace. Many transition technologies are proposed
to speed it up. As a natural consequence there are also DHCP
options proposed to provision those proposals. The inevitable
question is that whether the required parameters should be
delivered over DHCPv4 or DHCPv6. Authors often don't give
much thought about it and simply pick DHCPv6 without realizing
the consequences. IPv6 is expected to stay with us for many
decades, and so is DHCPv6. There is no mechanism available
to deprecate an option in DHCPv6, so any options defined
will stay with us as long as DHCPv6 protocol itself. It seems
likely that such options defined to transition from IPv4 will
outlive IPv4 by many decades. From that perspective it is better
to implement provisioning of the transition technologies in
DHCPv4, which will be obsoleted together with IPv4.</t>
</section>
<section title="Security Considerations">
<t>DHCPv6 does have an Authentication mechanism (<xref
target="RFC3315"></xref>) that makes it possible for DHCPv6
software to discriminate between authentic endpoints and men in
the middle. Other authentication mechanisms may optionally be
deployed. For example, the Secure DHCPv6 <xref
target="I-D.ietf-dhc-secure-dhcpv6"></xref>, based on
Cryptographically Generated Addresses (CGA) <xref
target="RFC3972"></xref>, can provide source address ownership
validation, message origin authentication and message integrity
without requiring symmetric key pairs or supporting from any key
management system. However, as of now, the mechanism is not
widely deployed. It also does not provide end-to-end
encryption.</t>
<t>So, while creating a new option, it is prudent to assume that
the DHCPv6 packet contents are always transmitted in the clear,
and actual production use of the software will probably be
vulnerable at least to man-in-the-middle attacks from within the
network, even where the network itself is protected from
external attacks by firewalls. In particular, some DHCPv6
message exchanges are transmitted to multicast addresses that
are likely broadcast anyway.</t>
<t>If an option is of a specific fixed length, it is useful to remind
the implementer of the option data's full length. This is easily done by
declaring the specific value of the 'length' tag of the option. This
helps to gently remind implementers to validate option length before
digesting them into likewise fixed length regions of memory or
stack.</t>
<t>If an option may be of variable size (such as having indeterminate
length fields, such as domain names or text strings), it is
advisable to explicitly remind the implementor to be aware of
the potential for long options. Either define a reasonable upper
limit (and suggest validating it), or explicitly remind the
implementor that an option may be exceptionally long (to be prepared
to handle errors rather than truncate values).</t>
<t>For some option contents, out of bound values may be used to breach
security. An IP address field might be made to carry a loopback
address, or local broadcast address, and depending on the protocol
this may lead to undesirable results. A domain name field may
be filled with contrived contents that exceed the limitations
placed upon domain name formatting... as this value is possibly
delivered to "internal configuration" records of the system, it
may be implicitly trusted without being validated.</t>
<t>So it behooves an option's definition to contain any validation
measures as can reasonably be made.</t>
</section>
<section title="IANA Considerations">
<t>This document has no actions for IANA.</t>
</section>
<section title="Acknowledgements">
<t>Authors would like to thank Simon Perreault, Bernie Volz and
Ted Lemon for their comments.</t>
</section>
</middle>
<back>
<!-- tomek: why do we have informative references 2 times, but
no normative ones? -->
<references title="Informative References">
&rfc2119;
&rfc3315;
&rfc3319;
&rfc3633;
&rfc3646;
&rfc3898;
&rfc3972;
&rfc4075;
&rfc4242;
&rfc4280;
&rfc4704;
&rfc5908;
&rfc5970;
&rfc6334;
&rfc6603;
&rfc6610;
<?rfc include='reference.I-D.ietf-dhc-secure-dhcpv6'?>
<?rfc include='reference.I-D.ietf-softwire-map-dhcp'?>
<?rfc include='reference.I-D.ietf-softwire-4rd'?>
</references>
<!--
<section anchor="isc" title="Background on ISC DHCP">
<t>The ISC DHCP software package was mostly written by Ted Lemon in
cooperation with Nominum, Inc. Since then, it has been given to Internet
Systems Consortium, Inc. ("ISC") where it has been maintained in the
public interest by contributors and ISC employees.</t>
<t>It includes a DHCP Server, Relay, and Client implementation, with a
common library of DHCP protocol handling procedures.</t>
<t>The DHCP Client may be found on some Linux distributions, and FreeBSD
5 and earlier. Variations ("Forks") of older versions of the client may
be found on several BSDs, including FreeBSD 6 and later.</t>
<t>The DHCP Server implementation is known to be in wide use by many
Unix-based servers, and comes pre-installed on most Linux
distributions.</t>
<t>The ISC DHCP Software Suite has to allow: <list style="symbols">
<t>Administrators to configure arbitrary DHCP Option Wire Formats
for options that either were not published at the time the software
released, or are of the System Administrator's invention (such as
<xref target="RFC3942">'Site-Local'</xref> options), or finally were
of Vendor design (<xref target="RFC2132">Vendor Encapsulated
Options</xref> or similar).</t>
<t>Pre-defined names and formats of options allocated by IANA and
defined by the IETF Standards body.</t>
<t>Applications deriving their configuration parameters from values
provided by these options to receive and understand their content.
Often, the binary format on the wire is not helpful or digestable
by, for example, 'ifconfig' or '/etc/resolv.conf'.</t>
</list></t>
<t>So, one can imagine that this would require a number of software
functions:
<list style="numbers">
<t>To read operator-written configuration value into memory.</t>
<t>To write the in-memory representation into protocol wire
format.</t>
<t>To read the protocol wire format into memory.</t>
<t>To write the in-memory format to persistent storage (to cache
across reboots for example).</t>
<t>To write the in-memory format to a format that can be consumed
by applications.</t>
</list>
</t>
<t>If every option were formatted differently and uniquely, then we
would have to write 5 functions for every option. As there is
the potential for as many as 254 DHCPv4 options, or 65536 DHCPv6
options, not to mention the various encapsulated spaces
("suboptions"), this is not scalable.</t>
<t>One simple trick is to make the in-memory format the same as
the wire format. This reduces the number of functions required
from 5 to 3. This is not always workable - sometimes an
intermediate format is required, but it is a good general case.</t>
<t>Another simple trick is to use the same (or very nearly the same)
format for persistent storage as is used to convey parameters to
applications. This reduces the number of functions again from 3
to 2.</t>
<t>This is still an intractable number of functions per each DHCP
option, even without the entire DHCP option space populated. So, we
need a way to reduce this to small orders.</t>
<section title="Atomic DHCP">
<t>To accomplish these goals, a common "Format String" is used to
describe, in abstract, all of the above. Each octet in this format
string represents a "DHCP Atom". We chain these 'atoms' together,
forming a sort of molecular structure for a particular DHCP option's
defined format.</t>
<t>The Configuration Syntax allows the user to construct such a format
string without having to understand how the Atom is encoded on the
wire, and how it is configured or presented.</t>
<t>You can reasonably imagine that the <xref
target="fragments">various common formats of DHCP options described
above</xref> each have an Atom associated with it. There are special
use Atoms, such as one to repeat the previous Atoms indefinitely (for
example, for options with multiple IPv4 addresses one after the
other), and one which makes the previous Atom optional.</t>
<t>As the software encounters a format string, it processes each Atom
individually to read from configuration into wire format, and also to
validate and convert wire format into output format (which with some
small exclusions is identical to the configuration format).</t>
<t>The format strings themselves are either hard coded by the software
in a table of option definitions, or are compiled at runtime through
configuration syntax generated by the operator.</t>
<figure>
<artwork><![CDATA[
option <space>.<option> code <number> = <definition>;
]]></artwork>
</figure>
<t>The <space> refers to the option space, which may be the
DHCPv4 option space, the DHCPv6 option space, or any suboption space
such as the DHCPv4 Relay Agent Information suboptions or similar.</t>
<t>The <option> refers to the option's symbolic name within that
space.</t>
<t>The code <number> refers to the binary code assigned to this
option.</t>
<t>The <definition> is a complex statement that brings together
DHCP Atoms, many of which are the aforementioned common formats, that
compose this option.</t>
<t>Below is a sample configuration for two options, whose wire formats
are defined in <xref target="RFC2132"></xref>. The Path MTU Plateau
Table option, and the Static Routes option.</t>
<figure>
<artwork><![CDATA[
option dhcp.path-mtu-plateau-table code 25 =
array of unsigned integer 16;
option dhcp.static-routes code 33 = array of { ip-address,
ip-address };
]]></artwork>
</figure>
<t>Once the options' syntax configuration is out of the way, values
to be carried in the options may be configured. These acts are
distinct; the previous configuration only prepares the parser system
to accept the configuration below. The below configuration actually
supplies a value to be transmitted on the wire, relying on the above
format definition.</t>
<figure>
<artwork><![CDATA[
option dhcp.path-mtu-plataeu-table 4352, 1500, 576;
option dhcp.static-routes 10.10.10.10 10.10.10.9,
10.10.10.11 10.10.10.9;
]]></artwork>
</figure>
</section>
</section> -->
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 19:43:18 |