One document matched: draft-ietf-dhc-option-guidelines-12.xml
<?xml version="1.0" encoding="US-ASCII"?>
<?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 rfc3046 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3046.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 rfc3986 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.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 rfc4833 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4833.xml">
<!ENTITY rfc5007 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5007.xml">
<!ENTITY rfc5460 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5460.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 rfc6422 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6422.xml">
<!ENTITY rfc6440 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6440.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">
<!ENTITY rfc6644 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6644.xml">
]>
<rfc category="bcp" docName="draft-ietf-dhc-option-guidelines-12"
ipr="trust200902" updates="3315">
<front>
<title abbrev="DHCPv6 Option Guidelines">Guidelines for Creating New
DHCPv6 Options</title>
<author fullname="David W. Hankins" initials="D." surname="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="Tomek 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>950 Charter Street</street>
<city>Redwood City</city>
<region>CA</region>
<code>94063</code>
<country>USA</country>
</postal>
<phone>+1 650 423 1431</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 fullname="Suresh Krishnan" initials="S." surname="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 requires 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>
<t>If the option would work well in the particular deployment
environment the proponents currently envision, but has equally valid
uses in some other environment where the proposed option format
would fail or would produce inconsistent results.</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 the 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 is not required to configure any of these 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
of the main reasons 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 reuse. 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: simple 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 data elements 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 means that implementations will likely 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 preferable 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 data elements is
provided as a shorthand. Please note that it is not complete in terms of
exampling every option format ever devised.</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 (a single
address only)</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 opposite 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 an IPv6 prefix. The information
to be carried by such an option includes the 128-bit IPv6 prefix
together with a length of this prefix taking values from 0 to 128.
Using the simplest approach, the option could convey this data in two
fixed length fields: one carrying prefix length, another carrying the
prefix. However, in many cases /64 or shorter prefixes are used. This
implies that the large part of the prefix data carried by the option
would have its bits set to zero and would be unused. In order to avoid
carrying unused data, it is recommended to store prefix in the
variable length data field. The appropriate option format is defined
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-code | option-length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| prefix6-len | ipv6-prefix |
+-+-+-+-+-+-+-+-+ (variable length) |
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure></t>
<t>option-length is set to 1 + length of the IPv6 prefix.</t>
<t>prefix6-len is one octet long and specifies the length in bits of the IPv6 prefix.
Typically allowed values are 0 to 128.</t>
<t>ipv6-prefix field is a variable length field that specifies the
IPv6 prefix. The length is (prefix6-len + 7) / 8. This field is padded
with zero bits 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>For example, the prefix 2001:db8::/60 would be encoded with an
option-length of 9, prefix6-len would be set to 60, the ipv6-prefix
would be 8 octets and would contain octets 20 01 0d b8 00 00 00
00.</t>
<t>It should be noted that the IAPREFIX option defined by <xref
target="RFC3633"></xref> uses a full length 16-octet prefix field. 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 URI">
<t>A Uniform Resource Identifier (URI) <xref target="RFC3986"></xref>
is a compact sequence of characters that identifies an abstract or
physical resource. The term "Uniform Resource Locator" (URL) refers to
the subset of URIs that, in addition to identifying a resource,
provide a means of locating the resource by describing its primary
access mechanism (e.g., its network "location"). This option format
can be used to carry a single URI:</t>
<figure align="center" anchor="option-with-URI"
title="Option with URI">
<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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. URI (variable length) .
| ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use: <list style="symbols">
<t><xref target="RFC5970">Boot File URL</xref></t>
</list></t>
<t>An alternate encoding to support multiple URIs is available. An
option must be defined to use either the single URI format above or
the multiple URL format below depending on whether a single is always
sufficient or if multiple URLs are possible.
</t>
<figure align="center" anchor="option-with-multiple-URIs"
title="Option with multiple URIs">
<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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. uri-data .
. . . . .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Each instance of the uri-data is formatted as follows:</t>
<figure>
<artwork><![CDATA[
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+
| uri-len | URI |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>The uri-len is two octets long and specifies the length of
the uri data.</t>
</section>
<section title="Option with Text String">
<t>A text string is a sequence of characters that have no semantics.
The encoding (such as 7-bit ASCII, NVT-ASCII, UTF-8) of the text
string MUST be specified.
If a data format has semantics other than just being text, it is not a
string. E.g., a FQDN is not a string, and a URI is also not a string,
because they have different semantics. A string must not enclude any
terminator (such as a null byte). This option format can be used
to carry a text string:</t>
<figure align="center" anchor="option-with-text-string"
title="Option with text string">
<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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. String .
| ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Examples of use: <list style="symbols">
<t><xref target="RFC4833">Timezone Options for DHCPv6 </xref></t>
</list></t>
<t>An alternate encoding to support multiple text strings is available. An
option must be defined to use either the single text string format above or
the multiple text string format below depending on whether a single is always
sufficient or if multiple text strings are possible.
</t>
<figure align="center" anchor="option-with-multiple-text-strings"
title="Option with multiple text strings">
<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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. text-data .
. . . . .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Each instance of the text-data is formatted as follows:</t>
<figure>
<artwork><![CDATA[
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+
| text-len | String |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>The text-len is two octets long and specifies the length of
the string.</t>
</section>
<section anchor="option-with-variable-length-data"
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.
Whenever this format is used by the
new option being defined, the data encoding should be documented.</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 variable 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>
</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. It uses the same format as described in <xref
target="option-with-variable-length-data"></xref>, but with the
special data encoding, described in section 8 of <xref
target="RFC3315"></xref>. This data encoding supports carrying
multiple instances of hosts or domain names in a single option, by
terminating each instance with the byte value of 0.</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>
<section title="Avoid Conditional Formatting">
<t>Placing an 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.
Therefore conditional formatting requires new code to be written and
complicates future interoperability should new conditional formats be
added; and existing code has to ignore conditional format that it does
not support.</t>
<!--
Bernie suggests that this paragraph is removed from the draft because
people will be tempted to experiment with conditional option formats
and then promote them as official options.
<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 an 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 message
bandwidth is wasted on option contents that are redundant. Also, the
DHCPv6 option space is wasted, as three new option codes are required,
rather than one.</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"></xref>), so one of them must be chosen. This section
is intended to help 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 options are discouraged for options intended to configure hosts,
because hosts may have multiple provisioning domains (see <xref
target="multpleProDomain"></xref>), and may get a different answer from
the DNS depending on the provisioning domain. This is particularly a
problem when the normal expected use of the option makes sense with
private DNS zone(s), as might be the case with a corporate VPN.</t>
<t>FQDN does require a resolution into an actual address. This implies
the question when the FQDN resolution should be taken. There are a
couple of 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 a number of additional failure modes and issues that
should be dealt with: <list style="numbers">
<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 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="Encapsulated options 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 encapsulated or
nested options. Those options are sometimes called sub-options, but this
term actually means something else, and therefore should never be
used to describe encapsulated options. It is recommended to use term
"encapsulated" as this terminology is used in <xref
target="RFC3315"></xref>. The difference between encapsulated and
sub-options are that the former uses normal DHCPv6 option space codes,
while the latter uses option space specific to a given parent option. It
should be noted that, contrary to DHCPv4, there is no shortage of option
numbers. Therefore almost 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 unfortunate exception of
<xref target="RFC5908"></xref>, which never got proper review from the
DHC working group and contains many errors, and should not under any
circumstances be used as a template for future DHCP option
definitions).</t>
<t>From the implementation perspective, it is easier to implement
encapsulated options rather than sub-options, as the implementers do not
have to deal with separate option spaces and can use the same buffer
parser in several places throughout the code.</t>
<t>Such encapsulation 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"></xref>,
section 9) conveys IA Prefix (IAPREFIX, defined in <xref
target="RFC3633"></xref>, section 10). Such delegated prefix may contain
an excluded prefix range that is represented by PD_EXCLUDE option that
is conveyed as encapsulated inside IAPREFIX (PD_EXCLUDE, defined in
<xref target="RFC6603"></xref>). It seems awkward to refer to such
options as sub-sub-option or doubly encapsulated option, therefore
"encapsulated 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 be avoided,
as it increases complexity of the parser. It is much easier, faster and
less error prone to parse a 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 encapsulated
options.</t>
</section>
<section title="Additional States Considered Harmful">
<t>DHCP is a protocol designed for provisioning clients. Less
experienced protocol designers often assume that it is easy to define an
option that will convey a different parameter for each client in a
network. Such problems arose during designs of MAP <xref
target="I-D.ietf-softwire-map-dhcp"></xref> and 4rd <xref
target="I-D.ietf-softwire-4rd"></xref>. While it would be easier for
provisioned clients to get ready to use per client option values, such
requirement puts exceedingly large loads on the server side. The new
extensions may introduce new implementation complexity and additional
database state on the server. Alternatives should be considered, if
possible. As an example, <xref
target="I-D.ietf-softwire-map-dhcp"></xref> was designed in a way that
all clients are provisioned with the same set of MAP options and each
provisioned client uses its unique address and delegated prefix to
generate client-specific information. Such a 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.
Refreshing other parameters should be initiated after a time specified
in the Information Refresh Time Option (defined in <xref
target="RFC4242"></xref>), carried in the Reply message and returned in
response to Information-Request message. Introducing additional timers
make deployment unnecessarily complex and SHOULD be avoided.</t>
</section>
<section title="Configuration changes occur at fixed times">
<t>In general, DHCPv6 clients only refresh configuration data from the
DHCP server when the T1 timer expires. Although there is a RECONFIGURE
mechanism that allows a DHCP server to request that clients initiate
reconfiguration, support for this mechanism is optional and cannot be
relied upon.</t>
<t>Even when DHCP clients refresh their configuration information, not
all consumers of DHCP-sourced configuration data notice these changes.
For instance, if a server is started using parameters received in an
early DHCP transaction, but does not check for updates from DHCP, it may
well continue to use the same parameter indefinitely. Modern
notification systems take care of reconfiguring services when the client
moves to a new network, but it's worth bearing in mind that a renew may
not actually result in the client taking up new configuration
information that it receives.</t>
<t>In light of the above, when designing an option you should take into
consideration the fact that your option may hold stale data that will
only be updated at an arbitrary time in the future.</t>
</section>
<section anchor="multpleProDomain" 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 a 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"></xref> states that a client that
receives more than one ADVERTISE message, may respond to one or more of
them, 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="Chartering Requirements and Advice for Responsible ADs">
<t>Adding a simple DHCP option is straightforward, and generally
something that any working group can do, perhaps with some help from
designated DHCP experts. However, when new fragment types need to be
devised, this requires the attention of DHCP experts, and should not be
done in a working group that doesn't have a quorum of such experts. This
is true whether the new fragment type has the same structure as an
existing fragment type, but has different semantics. It is equally true
when the new format has a new structure.</t>
<t>Responsible Area Directors for working groups that wish to add a work
item to a working group charter to define a new DHCP option should get
clarity from the working group as to whether the new option is a simple
DHCP option with no new fragment type or new fragment semantics, or
whether it in fact will require new fragment types. A working group
charter item should explicitly state which of these two types is
required; if it is not known at the time of chartering, the charter
should state that the working group will study the question and
recharter or seek help elsewhere if a new fragment type is to be
defined.</t>
<t>If a working group needs a new fragment type, it is preferable to
seek out a working group whose members already have sufficient expertise
to evaluate the new work and try to come up with a new format that
generalizes well and can be reused, rather than a single-use fragment
type. If such a working group is available, the work should be chartered
in that working group as a separate draft that documents the new
fragment type. The working group that needs the new fragment type can
then define their new option referencing the new fragment type document.
This work can generally be done in parallel so as not to delay the
process significantly.</t>
<t>In the event that there is no working group with DHCP expertise that
can define the new fragment type, the responsible AD should seek out
help from known DHCP experts within the IETF to provide advice and
frequent early review as the working group defines the new fragment
type. The new fragment type should still be done in a separate document,
even if it's done in the same working group, so as to foster reuse of
the new fragment type. The responsible AD should work with the working
group chairs and designated DHCP experts to ensure that new fragment
type document has in fact been carefully reviewed by the experts and
appears satisfactory.</t>
<t>Responsible area directors for working groups that are considering
defining options that actually update the DHCP protocol, as opposed to
simple options, should go through a process similar to that described
above when trying to determine where to do the work. Under no
circumstances should a working group be given a charter deliverable to
define a new DHCP option, and then on the basis of that charter item
actually make updates to the DHCP protocol.</t>
</section>
<section title="Considerations for Creating New Formats">
<t>When defining new options, 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>
<t>When defining a new option, it is best to synthesize the option
format using fragment types already in use. However, in some cases there
may be no fragment type that accomplishes the intended purpose.</t>
<t>The matter of size considerations and option order are further
discussed in <xref target="fragmentation"></xref> and <xref
target="optionOrder"></xref>.</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 avoids 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.
Common sense still applies here. It is better to split distinct values
into separate octets rather than propose overly complex bit shifting
operations to save several bits (or even an octet or two) that would be
padded to the next octet boundary anyway.</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. The default assumption is only
once.</t>
<t>Relay agents have to do fragment reassembly and fragmentation on
transmission. So while fragmentation is allowed, if a new option
results in significant fragmentation, it probably isn't a good choice for
DHCP configuration; instead DHCP should simply point to a URI where the
configuration information can be obtained.</t>
</section>
<section anchor="singleton" title="Singleton options">
<t>Although <xref target="RFC3315"/> states that each option
type MAY appear more than once, the original idea was that
multiple instances are reserved for stateful options, like IA_NA
or IA_PD. For most other options it is usually expected that
they will appear at most once. Such options are called singleton
options. Sadly, it is often not clearly specified in RFCs that
were published up to this date whether only one or more option
instances are allowed. Documents that define new defined options
SHOULD state whether new options are singletons or not. Unless
otherwise specified, new defined options are singletons.</t>
<t>When deciding whether a single or multiple option instances
are allowed in a message, take into consideration how the
content of the option will be used. Depending on the service
being configured it may or may not make sense to have multiple
values configured. If multiple values make sense, it is better
to explicitly allow that by using option format that allows
multiple values within one option instance.</t>
<t>Allowing multiple option instances often leads to confusion.
Consider the following example. Basic DS-Lite architecture
assumes that the B4 element (DHCPv6 client) will receive AFTR
option and establish a single tunnel to configured tunnel
termination point (AFTR). During standardization process of
<xref target="RFC6334"/> there was a discussion whether multiple
instances of DS-Lite tunnel option should be allowed. This
created an unfounded expectation that the clients receiving
multiple instances of the option will somehow know when one
tunnel endpoint goes off-line and do some sort of failover
between other values provided in other instances of the AFTR
option. Others assumed that if there are multiple options, the
client will somehow do a load balancing between provided tunnel
endpoints. Neither failover nor load balancing was defined for
DS-Lite architecture, so it caused confusion. It was eventually
decided to allow only one instance of the AFTR option.</t>
</section>
<section anchor="optionOrder" title="Option Order">
<t>Option order, either the order among many DHCPv6 options or the order
of multiple instances of the same option, SHOULD NOT be significant and
MUST NOT be assumed. An exception may be security relevant options,
which are often created last and put at the last position, or whose location
indicates the protected range.</t>
<t>As there is no explicit order for multiple instance of the same option,
an option definition SHOULD instead restrict the order within the option
by using a list of items rather than a single item.</t>
</section>
<section anchor="relayOptions" title="Relay Options">
<t>In DHCPv4, all relay options are organized as sub-options within DHCP
Relay Agent Information Option<xref target="RFC3046"></xref>. And an
independent number space called "DHCP Relay Agent Sub-options" is
maintained by IANA. Different from DHCPv4, in DHCPv6, Relay options are
defined in the same way as client/server options, and they too use the
same number space as client/server options. Future DHCPv6
Relay options MUST be allocated from this single DHCPv6 Option code
space.</t>
<t>However, the Relay-Supplied Options Option <xref
target="RFC6422"></xref> may also contain some DHCPv6 options as
permitted, such as the EAP Re-authentication Protocol (ERP) Local Domain
Name DHCPv6 Option <xref target="RFC6440"></xref>.</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 to inform what options
the client 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 be requested using 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>It is tempting to add text that requires the client to include a new
option in Option Request Option list, similar to this text: "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 MUST include option foo when the
client requested it (and the server has been so configured)". Such text
is discouraged as there are several issues with it. First, it assumes
that client implementation that supports a given option will always want
to use it. This is not true. The second and more important reason is
that such text essentially duplicates mechanism already defined in <xref
target="RFC3315"></xref>. It is better to simply refer to the existing
mechanism rather than define it again. See <xref
target="templates"></xref> for proposed examples on how to do that.</t>
<t>Creators of DHCPv6 options should 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.</t>
<t>It should also be noted that options values are never aligned within
the DHCP packet, even the option code and option length may appear on
odd byte boundaries.</t>
</section>
<section anchor="transition" title="Transition Technologies">
<t>Transition from IPv4 to IPv6 is progressing. 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 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>
<t>When the network infrastructure becomes IPv6-only, the support for
IPv4-only nodes may still be needed. In this scenario, provisioning IPv4
configuration over IPv6-only networks <xref
target="I-D.ietf-dhc-v4configuration"></xref> may be needed.</t>
</section>
<section anchor="templates"
title="Recommended sections in the new document">
<t>There are three major entities in DHCPv6 protocol: server, relay
agent, and client. It is very helpful for implementers to include
separate sections that describe operation for those three major
entities. Even when a given entity does not participate, it is useful to
have a very short section stating that it must not send a given option
and must ignore it when received.</t>
<t>There is also a separate entity called requestor, which is a special
client-like type that participates in leasequery protocol <xref
target="RFC5007"></xref> and <xref target="RFC5460"></xref>. A similar
section for the requestor is not required, unless the new option has
anything to do with requestor (or it is likely that the reader may think
that is has). It should be noted that while in the majority of
deployments, requestor is co-located with relay agent, those are two
separate entities from the protocol perspective and they may be used
separately. There are stand-alone requestor implementations
available.</t>
<t>The following sections include proposed text for such sections. That
text is not required to appear, but it is appropriate in most cases.
Additional or modified text specific to a given option is often
required.</t>
<t>Although requestor is somewhat uncommon functionality, its existence
should be noted, especially when allowing or disallowing options to
appear in certain message or being sent by certain entities. Additional
message types may appear in the future, besides types defined in <xref
target="RFC3315"></xref>. Therefore authors are encouraged to
familiarize themselves with a list of currently defined DHCPv6 messages
available on IANA website <xref target="iana"></xref>.</t>
<t>Typically new options are requested by clients and assigned by the
server, so there is no specific relay behavior. Nevertheless it is good
to include a section for relay agent behavior and simply state that
there are no additional requirements for relays. The same applies for
client behavior if the options are to be exchanged between relay and
server.</t>
<t>Sections that contain option definitions MUST include formal
verification procedure. Often it is very simple, e.g. option that
conveys IPv6 address must be exactly 16 bytes long, but sometimes the
rules are more complex. It is recommeded to refer to existing documents
(e.g. section 8 of RFC3315 for domain name encoding) rather than trying
to repeat such rules.</t>
<section anchor="template-client" title="DHCPv6 Client Behavior Text">
<t>Clients MAY request option foo, as defined in <xref
target="RFC3315"></xref>, sections 17.1.1, 18.1.1, 18.1.3, 18.1.4,
18.1.5 and 22.7. As a convenience to the reader, we mention here that
the client includes requested option codes in Option Request
Option.</t>
<t>Optional text (if client's hints make sense): Client also MAY
include option foo in its SOLICIT, REQUEST, RENEW, REBIND and
INFORMATION-REQUEST messages as a hint for the server regarding
preferred option values.</t>
<t>Optional text (if the option contains FQDN): If the client requests
an option that conveys an FQDN, it is expected that the contents of
that option will be resolved using DNS. Hence the following text may
be useful: Clients that request option foo SHOULD also request option
OPTION_DNS_SERVERS specified in <xref target="RFC3646"></xref>.</t>
<t>Clients MUST discard option foo if it is invalid (i.e. did not pass
validation steps defined in Section X.Y).</t>
<t>Optional text (if option foo in expected to be exchanged between
relays and servers): Option foo is exchanged between relays
and servers only. Clients are not aware of the usage of option foo.
Clients MUST ignore received option foo.</t>
</section>
<section anchor="template-server" title="DHCPv6 Server Behavior Text">
<t>Sections 17.2.2 and 18.2 of <xref target="RFC3315"></xref> govern
server operation in regards to option assignment. As a convenience to
the reader, we mention here that the server will send option foo only
if configured with specific values for foo and the client requested
it.</t>
<t>Optional text: Option foo is a singleton. Servers MUST NOT
send more than one instance of foo option.</t>
<t>Optional text (if server is never supposed to receive option foo):
Servers MUST ignore incoming foo option.</t>
</section>
<section anchor="template-relay"
title="DHCPv6 Relay Agent Behavior Text">
<t>It's never appropriate for a relay agent to add options to a
message heading toward the client, and relay agents don't actually
construct Relay-Reply messages anyway.</t>
<t>Optional text (if foo option is exchanged between clients and
server or between requestors and servers): There are no additional
requirements for relays.</t>
<t>Optional text (if relays are expected to insert or consume option
foo): Relay agents MAY include option foo in a Relay-Forw when
forwarding packets from clients to the servers.</t>
</section>
</section>
<section title="Should the new document update existing RFCs?">
<t>Authors often ask themselves a question whether their proposal
updates exist RFCs, especially 3315. In April 2013 there were about 80
options defined. Had all documents that defined them also updated
RFC3315, comprehension of such a document set would be extremely
difficult. It should be noted that "extends" and "updates" are two very
different verbs. If a new draft defines a new option that clients
request and servers provide, it merely extends current standards, so
"updates 3315" is not required in the new document header. On the other
hand, if a new document replaces or modifies existing behavior, it
should be noted that it updates the other document. For example, <xref
target="RFC6644"></xref> clearly updates <xref target="RFC3315"></xref>
as it replaces existing with new text.</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 man-in-the-middle. Other
authentication mechanisms may optionally be deployed.</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 multicast 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>Authors of drafts defining new DHCP options are therefore strongly
advised to explicitly define validation measures that recipients of such
options are required to do before processing such options. However,
validation measures already defined by RFC3315 or other
specifications referenced by the new option document are redundant, and
can introduce errors, so authors are equally strongly advised to refer
to the base specification for any such validation language rather than
copying it into the new specification.</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="Normative References">
&rfc2119;
&rfc3315;
</references>
<references title="Informative References">
&rfc3046;
&rfc3319;
&rfc3633;
&rfc3646;
&rfc3898;
&rfc3986;
&rfc4075;
&rfc4242;
&rfc4280;
&rfc4704;
&rfc4833;
&rfc5007;
&rfc5460;
&rfc5908;
&rfc5970;
&rfc6334;
&rfc6422;
&rfc6440;
&rfc6603;
&rfc6610;
&rfc6644;
<?rfc include='reference.I-D.ietf-softwire-map-dhcp'?>
<?rfc include='reference.I-D.ietf-softwire-4rd'?>
<?rfc include='reference.I-D.ietf-dhc-v4configuration'?>
<reference anchor="iana"
target="http://www.iana.org/assignments/dhcpv6-parameters/">
<front>
<title>DHCPv6 parameters (IANA webpage)</title>
<author fullname="IANA" surname="IANA"></author>
<date month="November" year="2003" />
</front>
</reference>
</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-24 01:20:03 |