Guidelines for Creating New DHCP Options
draft-ietf-dhc-option-guidelines-02

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on March 12, 2009.

Abstract

This document seeks to provide guidance to prospective DHCP Option authors, to help them in producing option formats that are easily adoptable.

Table of Contents

1.  Introduction
2.  When to Use DHCP
3.  General Principles
4.  Reusing Other Options
5.  Conditional Formatting is Hard
6.  Avoid Aliasing
7.  New Formats
8.  Option Size
9.  Clients Request their Options
10.  Security Considerations
11.  IANA Considerations
Appendix A.  Background on ISC DHCP
Appendix A.1.  Atomic DHCP
12.  Informative References
§  Author's Address
§  Intellectual Property and Copyright Statements

1.  Introduction

Most protocol developers ask themselves if a protocol will work, or work efficiently. These are important questions, but another less frequently considered is whether the proposed protocol presents itself needless barriers to adoption by deployed software.

DHCPv4 (Droms, R., “Dynamic Host Configuration Protocol,” March 1997.) [RFC2131] and DHCPv6 (Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., and M. Carney, “Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” July 2003.) [RFC3315] software implementors are not merely faced with the task of a given option's format on the wire. The option must 'fit' into every stage of the system's process, which includes user interface considerations. As an aide to understanding the potential implementation challenges of any new DHCP Option, one implementation's approach to tackling DHCP Option formats (Background on ISC DHCP) has been included in an Appendix.

Another, and more frequently overlooked, aspect of rapid adoption is whether or not the option would require operators to be intimately familiar with the option's internal format in order to make use of it. Most DHCP software provides a facility for "unknown options" at the time of publication to be configured by hand by an operator. But if doing so requires extensive reading (more than can be covered in a simple FAQ for example), it inhibits adoption.

So although a given solution would work, and might even be space, time, or aesthetically optimal, a given option is going to have a rough time being adopted by deployed software if it requires code changes. A rougher time still, if it does not share its deployment fate in a general manner with other options of pressing need.

There are many things DHCP option authors can do to form DHCP Options to make software implementors lives easier, and improve the chances that the Option is formally adopted in deployed software after it has been assigned an Option Code.

2.  When to Use DHCP

Principally, DHCP 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 DHCP.

The presence of such a knob isn't enough, however, because secondarily, DHCP also presents the extension of an administrative domain - that of the systems 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 reasoanble for this parameter to be set by the DHCP server operator.

Bear in mind that the client still reserves the right to over-ride or ignore values received via DHCP (for example, due to having a manually configured value by its operator), and that at least one main use case for DHCP is the corporate enterprise - so even if the local Net Cafe is not a suitable source of this configuration, it is likely that the client will at some point return to a network whose operator is also the system's rightful master.

3.  General Principles

The primary principle to follow in order to enhance an option's adoptability is certainly simplification. But more specifically, to create the option in such a way that it should 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 conveniences then it's fairly well assured that new software can easily formally adopt it.

There are at least two classes of DHCP options. A bulk class of options which are provided explicitly to carry data from one side of the DHCP 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 DHCP software or are used during special processing (such as the FQDN options ([RFC4702] (Stapp, M., Volz, B., and Y. Rekhter, “The Dynamic Host Configuration Protocol (DHCP) Client Fully Qualified Domain Name (FQDN) Option,” October 2006.), [RFC4704] (Volz, B., “The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Client Fully Qualified Domain Name (FQDN) Option,” October 2006.)), DHCPv4 message type option (Alexander, S. and R. Droms, “DHCP Options and BOOTP Vendor Extensions,” March 1997.) [RFC2132], link selection options ([RFC3011] (Waters, G., “The IPv4 Subnet Selection Option for DHCP,” November 2000.), [RFC3527] (Kinnear, K., Stapp, M., Johnson, R., and J. Kumarasamy, “Link Selection sub-option for the Relay Agent Information Option for DHCPv4,” April 2003.)), and so forth).

The guidelines laid out here should be understood to be relaxed for the protocol class of options. Wherever special-case-code is already required to adopt the DHCP option, it is substantially more reasonable to format the option in a less generic fashion, if there are measurable benefits to doing so.

4.  Reusing Other Options

In DHCPv4, there are now nearly one hundred and thirty options, at least as IETF standards, which might be used as an example. There is also one handy document (Alexander, S. and R. Droms, “DHCP Options and BOOTP Vendor Extensions,” March 1997.) [RFC2132] containing many option definitions.

Although some may not like the way an old option that solves a similar problem was approached, and it may waste space or processing time or have ugly characteristics, it can usually be said that duplicating that which has already been adopted has the greatest chance of being adopted quickly and easily.

So it is preferrable to consider the bulk of DHCP options already allocated, and consider which of those solve a similar problem. It may even be that an option that solves the problem already exists.

But as there are so many options to choose from, this isn't entirely practical. So, the following list of common option formats 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.

Common Option Fragments

One approach to manufacturing simple DHCP Options is to assemble the option out of whatever common fragments fit - possibly allowing one or more 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 values at the tail end of the option. If there are more than one variable/indeterminate length values, consider the use of multiple options or suboptions.

This estimates that implementations will be able to reuse code paths designed to support the other options.

5.  Conditional Formatting is Hard

Placing a byte at the start of the option which informs the software how to process the remaining bytes of the option may appear simple to the casual observer. But there are no such conditional formatting methods in existence today, so it must therefore require new, special case code, be written for this purpose.

Wherever possible, used fixed length buffers to carry the information desired. Obviously, this becomes less possible as the fixed length buffer approaches large sizes, at least in DHCPv4, where DHCP packet space is limited.

6.  Avoid Aliasing

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 best avoided.

In this case, where three different formats are supposed, it triples the work of the software involved, requiring support for not merely one format, but support to produce and digest all three. 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, DHCP option space is wasted on option contents that are redundant.

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?

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.

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), late binding (such as with DNS), or completeness (such as with a URL).

7.  New Formats

If the Option simply will not fit into any existing work, the last recourse is to contrive a new format to fit.

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 might reasonably have any other uses, and if so, to create the option with the foreknowledge that it may later become a common fragment.

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.

8.  Option Size

DHCPv4 (Droms, R., “Dynamic Host Configuration Protocol,” March 1997.) [RFC2131] options payload space is limited, as there are a number of unaddressed deployment problems with DHCPv4 packet sizes. The end result is that you should build your option to the assumption that the packet will be no larger than 576 bytes. This means that the options payload space will be 312 bytes, which you will have to share with other options. This space can be extended by making use of Option Overloading (Alexander, S. and R. Droms, “DHCP Options and BOOTP Vendor Extensions,” March 1997.) [RFC2132], which allows the use of the BOOTP FILE and SNAME header fields for carrying DHCPv4 options (adding 192 bytes), but these header fields will not be available for overloading if they have been configured to carry a value.

DHCPv6 (Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., and M. Carney, “Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” July 2003.) [RFC3315] is much better off. First, through its use of link-local addresses, it steps aside many of the deployment problems that plague DHCPv4, and looks a great deal more like any other UDP based application; oblivious to packet sizes up to 64KB. Second, RFC3315 explicitly refers readers to RFC2460 Section 5, which describes an MTU of 1280 octets and a minimum fragment reassembly of 1500 octets. It's much more 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.

So in either protocol, it is advantageous to prefer option formats which contain the desired information in the smallest form factor that solves the requirements. One example is to use a 4-octet IPv4 address rather than a fully qualified domain name, because many DHCP servers will perform DNS resolution on configured FQDN's (so the DNS recursive lookup is performed anyway). There may be motivations to use the fully qualified domain name anyway, such as if the intended RRSET is not an address, or if the client must refresh the name more frequently than common lease renewal periods.

When it is not possible to compress the configuration contents either because of the simple size of the parameters, or because it is expected that very large configurations are valid, it may be preferrable to use a second stage configuration. Some examples of this are to provide TFTP server and pathnames, or a URL, which the client will load and process externally to the DHCP protocol.

In the case where a DHCPv4 option may, or will, exceed 255 bytes in length (and thus exceed the 'length' field's ability to contain it), a DHCPv4 option will simply be fragmented into multiple options within the packet. DHCP software processing these fragments will concatenate them, in the order they appear as defined by RFC2131 (Droms, R., “Dynamic Host Configuration Protocol,” March 1997.) [RFC2131], prior to evaluating their contents. This is an important distinction that is sometimes overlooked by authors - these multiple options do not represent multiple options formatted precisely as you have defined, but rather one option that has been split along any arbitrary point into multiple containers. When documenting an example, then, try to make sure that the division point you select as an example does not lie on a clean division of your option contents - place it at an offset so as to reinforce that these values must be concatenated rather than processed individually.

DHCPv4 option fragments are a basic protocol feature, so there usually is no reason to mention this feature in new option definitions, unless of course the option is very likely to exceed 255 bytes, or the documented example(s) are this big.

Note that option fragmentation is also a very common side-effect of running out of options space, and moving to overloaded FILE or SNAME fields. Although the option may be considerably shorter than 255 bytes, if it does not fit in the remaining space then software may consume all remaining options space with one option fragment, and place the remainder in an overloaded field.

9.  Clients Request their Options

The DHCPv4 Parameter Request List (Alexander, S. and R. Droms, “DHCP Options and BOOTP Vendor Extensions,” March 1997.) [RFC2132], and the DHCPv6 Option Request Option (OPTION_ORO) (Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., and M. Carney, “Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” July 2003.) [RFC3315], are both optoins that serve two purposes - to inform the server what option(s) the client supports and is willing to digest, 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).

It doesn't make sense for some options to appear on this parameter request list, such as those are formed by elements of the protocol's internal workings, or are formed on either end by DHCP-level software engaged in some exchange of information. When in any form of doubt, assume that any new option must be present on the relevant option request list if the client desires it.

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 relevant list option, clients MAY include the new option in their packets to servers with hints as to values they desire, and servers MAY respond with the option contents (if they have been so configured).

Under only the most dire of circumstances should a new option definition require special ordering of options either in the relevant request option, or in the order of packets returned on the server's reply. Although the request option does display a preferred priority, which implies an order, a server may shuffle options around in a DHCPv4 packet in order to make them fit, and server software may sort DHCPv6 options into strange orders. There is not one universal approach.

10.  Security Considerations

DHCP does have an Authentication mechanism ([RFC3118] (Droms, R. and W. Arbaugh, “Authentication for DHCP Messages,” June 2001.), [RFC3315] (Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., and M. Carney, “Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” July 2003.), [RFC4030] (Stapp, M. and T. Lemon, “The Authentication Suboption for the Dynamic Host Configuration Protocol (DHCP) Relay Agent Option,” March 2005.)), where it is possible for DHCP software to discriminate between authentic endpoints and men in the middle.

However, at this date the mechanism is poorly deployed. It also does not provide end-to-end encryption.

So, while creating a new option, bear in mind that DHCP packet contents are always transmitted in the clear, and actual production use of the software will probably be vulnerable at least to men in the middle attacks from within the network, even where the network itself is protected from external attacks by firewalls. In particular, some DHCP message exchanges are transmitted to broadcast or multicast addresses that are likely broadcast anyway.

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.

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 by defining a reasonable upper limit, or explicitly reminding the implementor that an option may be exceptionally long.

For some option contents, "insane 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 trusted, rather than validated.

So it behooves an option's definition to contain any validation measures as can reasonably be made.

11.  IANA Considerations

This document has no actions for IANA.

Appendix A.  Background on ISC DHCP

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.

It includes a DHCP Server, Relay, and Client implementation, with a common library of DHCP protocol handling procedures.

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.

The DHCP Server implementation is known to be in wide use by many Unix-based servers, and comes pre-installed on most Linux distributions.

The ISC DHCP Software Suite has to allow:

• 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 'Site-Local' (Volz, B., “Reclassifying Dynamic Host Configuration Protocol version 4 (DHCPv4) Options,” November 2004.) [RFC3942] options), or finally were of Vendor design (Vendor Encapsulated Options (Alexander, S. and R. Droms, “DHCP Options and BOOTP Vendor Extensions,” March 1997.) [RFC2132] or similar).
• Pre-defined names and formats of options allocated by IANA and defined by the IETF Standards body.
• 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'.

So, one can imagine that this would require a number of software functions:

1. To read operator-written configuration value into memory.
2. To write the in-memory representation into protocol wire format.
3. To read the protocol wire format into memory.
4. To write the in-memory format to persistent storage (to cache across reboots for example).
5. To write the in-memory format to a format that can be consumed by applications.

If every option were formatted differently and uniquely, then we would have to write 6 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.

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 4. This is not always workable - sometimes an intermediary format is required, but it is a good general case.

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 4 to 3.

This is still an intractable number of functions per each DHCP option. So, we need a way to reduce this to small orders.

Appendix A.1.  Atomic DHCP

To accomplish these goals, a common "Format String" is used to describe, in abstract, all of the above. Each byte in this format string represents a "DHCP Atom". We chain these 'atoms' together, forming a sort of molecular structure for a particular DHCP Option.

Configuration Syntax language 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.

You can reasonably imagine that the various common formats of DHCP options described above 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.

As the software encounters a format string, it processes each Atom individually to read, formulate in memory, or write to output the various option contents.

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.

        option [space].[option] code [number] = [definition];

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.

The "option" refers to the option's symbolic name within that space.

The code number refers to the binary code assigned to this option.

The definition is a complex statement that brings together DHCP Atoms, many of which are the aforementioned common formats, that compose this option. For example, here are two predefined options, as they might have been configured for use by an operator if the software did not already support them.

     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 };

     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;

12. Informative References

Author's Address

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.