idnits 2.17.1 draft-ietf-dhc-option-guidelines-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC3315, updated by this document, for RFC5378 checks: 1995-02-03) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 9, 2013) is 3762 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3315 (Obsoleted by RFC 8415) == Outdated reference: A later version (-06) exists of draft-ietf-dhc-v4configuration-03 == Outdated reference: A later version (-10) exists of draft-ietf-softwire-4rd-07 == Outdated reference: A later version (-12) exists of draft-ietf-softwire-map-dhcp-06 -- Obsolete informational reference (is this intentional?): RFC 3633 (Obsoleted by RFC 8415) -- Obsolete informational reference (is this intentional?): RFC 4242 (Obsoleted by RFC 8415) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Dynamic Host Configuration Working Group D. Hankins 3 Internet-Draft Google 4 Updates: 3315 (if approved) T. Mrugalski 5 Intended status: Best Current Practice M. Siodelski 6 Expires: June 12, 2014 ISC 7 S. Jiang 8 Huawei Technologies Co., Ltd 9 S. Krishnan 10 Ericsson 11 December 9, 2013 13 Guidelines for Creating New DHCPv6 Options 14 draft-ietf-dhc-option-guidelines-15 16 Abstract 18 This document provides guidance to prospective DHCPv6 Option 19 developers to help them creating option formats that are easily 20 adoptable by existing DHCPv6 software. It also provides guidelines 21 for expert reviewers to evaluate new registrations. This document 22 updates RFC3315. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on June 12, 2014. 41 Copyright Notice 43 Copyright (c) 2013 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 59 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. When to Use DHCPv6 . . . . . . . . . . . . . . . . . . . . . 4 61 4. General Principles . . . . . . . . . . . . . . . . . . . . . 5 62 5. Reusing Other Options Formats . . . . . . . . . . . . . . . . 5 63 5.1. Option with IPv6 addresses . . . . . . . . . . . . . . . 6 64 5.2. Option with a single flag (boolean) . . . . . . . . . . . 7 65 5.3. Option with IPv6 prefix . . . . . . . . . . . . . . . . . 7 66 5.4. Option with 32-bit integer value . . . . . . . . . . . . 8 67 5.5. Option with 16-bit integer value . . . . . . . . . . . . 9 68 5.6. Option with 8-bit integer value . . . . . . . . . . . . . 9 69 5.7. Option with URI . . . . . . . . . . . . . . . . . . . . . 10 70 5.8. Option with Text String . . . . . . . . . . . . . . . . . 11 71 5.9. Option with variable length data . . . . . . . . . . . . 12 72 5.10. Option with DNS Wire Format Domain Name List . . . . . . 13 73 6. Avoid Conditional Formatting . . . . . . . . . . . . . . . . 13 74 7. Avoid Aliasing . . . . . . . . . . . . . . . . . . . . . . . 14 75 8. Choosing between FQDN and address . . . . . . . . . . . . . . 14 76 9. Encapsulated options in DHCPv6 . . . . . . . . . . . . . . . 17 77 10. Additional States Considered Harmful . . . . . . . . . . . . 18 78 11. Configuration changes occur at fixed times . . . . . . . . . 19 79 12. Multiple provisioning domains . . . . . . . . . . . . . . . . 19 80 13. Chartering Requirements and Advice for Responsible Area 81 Directors . . . . . . . . . . . . . . . . . . . . . . . . . . 20 82 14. Considerations for Creating New Formats . . . . . . . . . . . 21 83 15. Option Size . . . . . . . . . . . . . . . . . . . . . . . . . 21 84 16. Singleton options . . . . . . . . . . . . . . . . . . . . . . 22 85 17. Option Order . . . . . . . . . . . . . . . . . . . . . . . . 23 86 18. Relay Options . . . . . . . . . . . . . . . . . . . . . . . . 23 87 19. Clients Request their Options . . . . . . . . . . . . . . . . 24 88 20. Transition Technologies . . . . . . . . . . . . . . . . . . . 25 89 21. Recommended sections in the new document . . . . . . . . . . 25 90 21.1. DHCPv6 Client Behavior Text . . . . . . . . . . . . . . 26 91 21.2. DHCPv6 Server Behavior Text . . . . . . . . . . . . . . 26 92 21.3. DHCPv6 Relay Agent Behavior Text . . . . . . . . . . . . 27 93 22. Should the new document update existing RFCs? . . . . . . . . 27 94 23. Security Considerations . . . . . . . . . . . . . . . . . . . 28 95 24. Privacy considerations . . . . . . . . . . . . . . . . . . . 29 96 25. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 97 26. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 98 27. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 99 27.1. Normative References . . . . . . . . . . . . . . . . . . 30 100 27.2. Informative References . . . . . . . . . . . . . . . . . 30 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 103 1. Requirements Language 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in RFC 2119 [RFC2119]. 109 2. Introduction 111 Most protocol developers ask themselves if a protocol will work, or 112 work efficiently. These are important questions, but another less 113 frequently considered question is whether the proposed protocol 114 presents itself needless barriers to adoption by deployed software. 116 DHCPv6 [RFC3315] software implementors are not merely faced with the 117 task of handling a given option's format on the wire. The option 118 must fit into every stage of the system's process, starting with the 119 user interface used to enter the configuration up to the machine 120 interfaces where configuration is ultimately consumed. 122 Another frequently overlooked aspect of rapid adoption is whether the 123 option requires operators to be intimately familiar with the option's 124 internal format in order to use it? Most DHCPv6 software provides a 125 facility for handling unknown options at the time of publication. 126 The handling of such options usually needs to be manually configured 127 by the operator. But if doing so requires extensive reading (more 128 than can be covered in a simple FAQ for example), it inhibits 129 adoption. 131 So although a given solution would work, and might even be space, 132 time, or aesthetically optimal, a given option is presented with a 133 series of ever-worsening challenges to be adopted: 135 o If it doesn't fit neatly into existing config files. 137 o If it requires source code changes to be adopted, and hence 138 upgrades of deployed software. 140 o If it does not share its deployment fate in a general manner with 141 other options, standing alone in requiring code changes or 142 reworking configuration file syntaxes. 144 o If the option would work well in the particular deployment 145 environment the proponents currently envision, but has equally 146 valid uses in some other environment where the proposed option 147 format would fail or would produce inconsistent results. 149 There are many things DHCPv6 option creators can do to avoid the 150 pitfalls in this list entirely, or failing that, to make software 151 implementors lives easier and improve its chances for widespread 152 adoption. 154 This document is envisaged as a help for protocol developers that 155 define new options and for expert reviewers that review submitted 156 proposals. 158 3. When to Use DHCPv6 160 Principally, DHCPv6 carries configuration parameters for its clients. 161 Any knob, dial, slider, or checkbox on the client system, such as "my 162 domain name servers", "my hostname", or even "my shutdown 163 temperature" are candidates for being configured by DHCPv6. 165 The presence of such a knob isn't enough, because DHCPv6 also 166 presents the extension of an administrative domain - the operator of 167 the network to which the client is currently attached. Someone runs 168 not only the local switching network infrastructure that the client 169 is directly (or wirelessly) attached to, but the various methods of 170 accessing the external Internet via local assist services that the 171 network must also provide (such as domain name servers, or routers). 172 This means that, even if a configuration parameter can potentially 173 delivered by DHCPv6, it is necessary to evaluate whether it is 174 reasonable for this parameter to be under the control of the 175 administrator of whatever network a client is attached to at any 176 given time. 178 Note that the client is not required to configure any of these values 179 received via DHCPv6 (e.g., due to having these values locally 180 configured by its own administrator). But it needs to be noted that 181 overriding DHCPv6-provided values may cause the client to be denied 182 certain services in the network to which it has attached. The 183 possibility of having higher level of control over client node 184 configuration is one of the reasons that DHCPv6 is preferred in 185 enterprise networks. 187 4. General Principles 189 The primary guiding principle to follow in order to enhance an 190 option's adoptability is reuse. The option should be created in such 191 a way that does not require any new or special case software to 192 support. If old software currently deployed and in the field can 193 adopt the option through supplied configuration facilities then it's 194 fairly certain that new software can easily formally adopt it. 196 There are at least two classes of DHCPv6 options: simple options 197 which are provided explicitly to carry data from one side of the 198 DHCPv6 exchange to the other (such as nameservers, domain names, or 199 time servers), and a protocol class of options which require special 200 processing on the part of the DHCPv6 software or are used during 201 special processing (such as the Fully Qualified Domain Name (FQDN) 202 option [RFC4704]), and so forth; these options carry data that is the 203 result of a routine in some DHCPv6 software. 205 The guidelines laid out here should be applied in a relaxed manner 206 for the protocol class of options. Wherever special case code is 207 already required to adopt the DHCPv6 option, it is substantially more 208 reasonable to format the option in a less generic fashion, if there 209 are measurable benefits to doing so. 211 5. Reusing Other Options Formats 213 The easiest approach to manufacturing trivially deployable DHCPv6 214 Options is to assemble the option out of whatever common fragments 215 fit - possibly allowing a group of data elements to repeat to fill 216 the remaining space (if present) and so provide multiple values. 217 Place all fixed size values at the start of the option, and any 218 variable/indeterminate sized value at the tail end of the option. 220 This means that implementations will likely be able to reuse code 221 paths designed to support the other options. 223 There is a tradeoff between the adoptability of previously defined 224 option formats, and the advantages that new or specialized formats 225 can provide. In general, it is usually preferable to reuse 226 previously used option formats. 228 However, it isn't very practical to consider the bulk of DHCPv6 229 options already allocated, and consider which of those solve a 230 similar problem. So, the following list of common option format data 231 elements is provided as a shorthand. Please note that it is not 232 complete in terms of exampling every option format ever devised. 234 If more complex options are needed, those basic formats mentioned 235 here may be considered as primitives (or 'fragment types') that can 236 be used to build more complex formats. It should be noted that it is 237 often easier to implement two options with trivial formats than one 238 option with more complex format. That is not unconditional 239 requirement though. In some cases splitting one complex option into 240 two or more simple options introduces inter-option dependencies that 241 should be avoided. In such a case, it is usually better to keep one 242 complex option. 244 5.1. Option with IPv6 addresses 246 This option format is used to carry one or many IPv6 addresses. In 247 some cases the number of allowed address is limited (e.g. to one): 249 0 1 2 3 250 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 251 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 252 | option-code | option-len | 253 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 254 | | 255 | ipv6-address | 256 | | 257 | | 258 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 259 | | 260 | ipv6-address | 261 | | 262 | | 263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 264 | ... | 265 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 267 Figure 1: Option with IPv6 address 269 Examples of use: 271 o DHCPv6 server unicast address (a single address only) [RFC3315] 273 o SIP Servers IPv6 Address List [RFC3319] 275 o DNS Recursive Name Server [RFC3646] 277 o NIS Servers [RFC3898] 279 o SNTP Servers [RFC4075] 280 o Broadcast and Multicast Service Controller IPv6 Address Option for 281 DHCPv6 [RFC4280] 283 o MIPv6 Home Agent Address [RFC6610] (a single address only) 285 o NTP server [RFC5908] (a single address only) 287 o NTP Multicast address [RFC5908] (a single address only) 289 5.2. Option with a single flag (boolean) 291 Sometimes it is useful to convey a single flag that can take either 292 on or off values. Instead of specifying an option with one bit of 293 usable data and 7 bits of padding, it is better to define an option 294 without any content. It is the presence or absence of the option 295 that conveys the value. This approach has the additional benefit of 296 absent option designating the default, i.e. administrator has to take 297 explicit actions to deploy the opposite of the default value. 299 The absence of the option represents the default value and the 300 presence of the option represents the other value, but that this does 301 not necessarily mean that absence is "off" (or "false") and presence 302 is "on" (or "true"). That is, if it's desired that the default value 303 for a bistable option is "true"/"on", then the presence of that 304 option would turn it off (make it false). If the option presence 305 signifies off/false state, that should be reflected in the option 306 name, e.g. OPTION_DISABLE_FOO. 308 0 1 2 3 309 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 310 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 311 | option-code | option-len | 312 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 314 Figure 2: Option for conveying boolean 316 Examples of use: 318 o DHCPv6 rapid-commit [RFC3315] 320 5.3. Option with IPv6 prefix 322 Sometimes there is a need to convey an IPv6 prefix. The information 323 to be carried by such an option includes the 128-bit IPv6 prefix 324 together with a length of this prefix taking values from 0 to 128. 325 Using the simplest approach, the option could convey this data in two 326 fixed length fields: one carrying prefix length, another carrying the 327 prefix. However, in many cases /64 or shorter prefixes are used. 329 This implies that the large part of the prefix data carried by the 330 option would have its bits set to zero and would be unused. In order 331 to avoid carrying unused data, it is recommended to store prefix in 332 the variable length data field. The appropriate option format is 333 defined as follows: 335 0 1 2 3 336 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 337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 338 | option-code | option-length | 339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 340 | prefix6len | ipv6-prefix | 341 +-+-+-+-+-+-+-+-+ (variable length) | 342 . . 343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 345 Figure 3: Option with IPv6 Prefix 347 option-length is set to 1 + length of the IPv6 prefix. 349 prefix6len is one octet long and specifies the length in bits of the 350 IPv6 prefix. Typically allowed values are 0 to 128. 352 ipv6-prefix field is a variable length field that specifies the IPv6 353 prefix. The length is (prefix6len + 7) / 8. This field is padded 354 with zero bits up to the nearest octet boundary when prefix6len is 355 not divisible by 8. 357 Examples of use: 359 o Default Mapping Rule [I-D.ietf-softwire-map-dhcp] 361 For example, the prefix 2001:db8::/60 would be encoded with an 362 option-length of 9, prefix6-len would be set to 60, the ipv6-prefix 363 would be 8 octets and would contain octets 20 01 0d b8 00 00 00 00. 365 It should be noted that the IAPREFIX option defined by [RFC3633] uses 366 a full length 16-octet prefix field. The concern about option length 367 was not well understood at the time of its publication. 369 5.4. Option with 32-bit integer value 371 This option format can be used to carry 32 bit-signed or unsigned 372 integer value: 374 0 1 2 3 375 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 376 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 377 | option-code | option-len | 378 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 379 | 32-bit-integer | 380 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 382 Figure 4: Option with 32-bit-integer value 384 Examples of use: 386 o Information Refresh Time [RFC4242] 388 5.5. Option with 16-bit integer value 390 This option format can be used to carry 16-bit signed or unsigned 391 integer values: 393 0 1 2 3 394 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 395 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 396 | option-code | option-len | 397 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 398 | 16-bit-integer | 399 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 401 Figure 5: Option with 16-bit integer value 403 Examples of use: 405 o Elapsed Time [RFC3315] 407 5.6. Option with 8-bit integer value 409 This option format can be used to carry 8-bit integer values: 411 0 1 2 3 412 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 413 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 414 | option-code | option-len | 415 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 416 | 8-bit-integer | 417 +-+-+-+-+-+-+-+-+ 419 Figure 6: Option with 8-bit integer value 421 Examples of use: 423 o DHCPv6 Preference [RFC3315] 425 5.7. Option with URI 427 A Uniform Resource Identifier (URI) [RFC3986] is a compact sequence 428 of characters that identifies an abstract or physical resource. The 429 term "Uniform Resource Locator" (URL) refers to the subset of URIs 430 that, in addition to identifying a resource, provide a means of 431 locating the resource by describing its primary access mechanism 432 (e.g., its network "location"). This option format can be used to 433 carry a single URI: 435 0 1 2 3 436 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 437 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 438 | option-code | option-len | 439 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 440 . URI (variable length) . 441 | ... | 442 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 444 Figure 7: Option with URI 446 Examples of use: 448 o Boot File URL [RFC5970] 450 An alternate encoding to support multiple URIs is available. An 451 option must be defined to use either the single URI format above or 452 the multiple URI format below depending on whether a single is always 453 sufficient or if multiple URIs are possible. 455 0 1 2 3 456 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 457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 458 | option-code | option-len | 459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 460 . . 461 . uri-data . 462 . . . . . 463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 465 Figure 8: Option with multiple URIs 467 Each instance of the uri-data is formatted as follows: 469 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 470 | uri-len | URI | 471 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 473 The uri-len is two octets long and specifies the length of the uri 474 data. Although URI format in theory supports up to 64k of data, in 475 practice large chunks of data may be problematic. See Section 15 for 476 details. 478 5.8. Option with Text String 480 A text string is a sequence of characters that have no semantics. 481 The encoding of the text string MUST be specified. Unless otherwise 482 specified, all text strings in newly defined options are expected to 483 be Unicode strings that are encoded using UTF-8 [RFC3629] in Net- 484 Unicode form [RFC5198]. Please note that all strings containing only 485 7 bit ASCII characters are also valid UTF-8 Net-Unicode strings. 487 If a data format has semantics other than just being text, it is not 488 a string. E.g., a FQDN is not a string, and a URI is also not a 489 string, because they have different semantics. A string must not 490 include any terminator (such as a null byte). The null byte is 491 treated as any other character and does not have any special meaning. 492 This option format can be used to carry a text string: 494 0 1 2 3 495 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 496 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 497 | option-code | option-len | 498 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 499 . String . 500 | ... | 501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 503 Figure 9: Option with text string 505 Examples of use: 507 o Timezone Options for DHCPv6 [RFC4833] 509 An alternate encoding to support multiple text strings is available. 510 An option must be defined to use either the single text string format 511 above or the multiple text string format below depending on whether a 512 single is always sufficient or if multiple text strings are possible. 514 0 1 2 3 515 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 517 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 518 | option-code | option-len | 519 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 520 . . 521 . text-data . 522 . . . . . 523 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 525 Figure 10: Option with multiple text strings 527 Each instance of the text-data is formatted as follows: 529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 530 | text-len | String | 531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 533 The text-len is two octets long and specifies the length of the 534 string. 536 5.9. Option with variable length data 538 This option can be used to carry variable length data of any kind. 539 Internal representation of carried data is option specific. Whenever 540 this format is used by the new option being defined, the data 541 encoding should be documented. 543 This option format provides a lot of flexibility to pass data of 544 almost any kind. Though, whenever possible it is highly recommended 545 to use more specialized options, with field types better matching 546 carried data types. 548 0 1 2 3 549 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 550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 551 | option-code | option-len | 552 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 553 . . 554 . variable length data . 555 . . 556 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 558 Figure 11: Option with variable length data 560 Examples of use: 562 o Client Identifier [RFC3315] 564 o Server Identifier [RFC3315] 566 5.10. Option with DNS Wire Format Domain Name List 568 This option is used to carry 'domain search' lists or any host or 569 domain name. It uses the same format as described in Section 5.9, 570 but with the special data encoding, described in section 8 of 571 [RFC3315]. This data encoding supports carrying multiple instances 572 of hosts or domain names in a single option, by terminating each 573 instance with the byte value of 0. 575 0 1 2 3 576 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 577 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 578 | option-code | option-length | 579 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 580 | DNS Wire Format Domain Name List | 581 | ... | 582 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 584 Figure 12: Option with DNS Wire Format Domain Name List 586 Examples of use: 588 o SIP Servers Domain Name List [RFC3319] (many domains) 590 o NIS Domain Name (many domains) [RFC3898] (many domains) 592 o LoST Server Domain name [RFC5223] 594 o LIS Domain name [RFC5986] 596 o DS-Lite AFTR location [RFC6334] (a single FQDN) 598 o Home Network Identifier [RFC6610] (a single FQDN) 600 o Home Agent FQDN [RFC6610] (a single FQDN) 602 6. Avoid Conditional Formatting 604 Placing an octet at the start of the option which informs the 605 software how to process the remaining octets of the option may appear 606 simple to the casual observer. But the only conditional formatting 607 methods that are in widespread use today are 'protocol' class 608 options. Therefore conditional formatting requires new code to be 609 written and complicates future interoperability should new 610 conditional formats be added; and existing code has to ignore 611 conditional format that it does not support. 613 7. Avoid Aliasing 615 Options are said to be aliases of each other if they provide input to 616 the same configuration parameter. A commonly proposed example is to 617 configure the location of some new service ("my foo server") using a 618 binary IP address, a domain name field, and an URL. This kind of 619 aliasing is undesirable, and is not recommended. 621 In this case, where three different formats are supposed, it more 622 than triples the work of the software involved, requiring support for 623 not merely one format, but support to produce and digest all three. 624 Furthermore, code development and testing must cover all possible 625 combinations of defined formats. Since clients cannot predict what 626 values the server will provide, they must request all formats. So in 627 the case where the server is configured with all formats, DHCPv6 628 message bandwidth is wasted on option contents that are redundant. 629 Also, the DHCPv6 option number space is wasted, as three new option 630 codes are required, rather than one. 632 It also becomes unclear which types of values are mandatory, and how 633 configuring some of the options may influence the others. For 634 example, if an operator configures the URL only, should the server 635 synthesize a domain name and IP address? 637 A single configuration value on a host is probably presented to the 638 operator (or other software on the machine) in a single field or 639 channel. If that channel has a natural format, then any alternative 640 formats merely make more work for intervening software in providing 641 conversions. 643 So the best advice is to choose the one method that best fulfills the 644 requirements, be that for simplicity (such as with an IP address and 645 port pair), late binding (such as with DNS), or completeness (such as 646 with a URL). 648 8. Choosing between FQDN and address 650 Some parameters may be specified as FQDN or an address. In most 651 cases one or the other should be used. This section discusses pros 652 and cons of each approach and is intended to help make an informed 653 decision in that regard. It is strongly discouraged to define both 654 option types at the same time (see Section 7), unless there is 655 sufficient motivation to do so. 657 There is no single recommendation that works for every case. It very 658 much depends on the nature of the parameter being configured. For 659 parameters that are network specific or represent certain aspects of 660 network infrastructure, like NTP servers, available mobility services 661 etc., in most cases address is more usable choice. For parameters 662 that can be considered application specific configuration, like SIP 663 servers, it is usually better to use FQDN. 665 Applications are often better suited to deal with FQDN failures than 666 with address failures. Most operating systems provide a way to retry 667 FQDN resolution if the previous attempt fails. That type of error 668 recovery is supported by a great number of applications. On the 669 other hand, there is typically no API availble for applications to 670 reconfigure over DHCP to get a new address value if the one received 671 is no longer appropriate. This problem may be partially addressed by 672 providing a list of addresses, rather than just a single one. That, 673 on the other hand, complicates client operation, as some kind of 674 failover procedure has to be defined and implemented. 676 FQDN provide a higher level of indirection and ambiguity. In many 677 cases that may be considered a benefit, but can be considered a flaw 678 in others. For example, one operator suggested to have the same name 679 being resolved to different addresses depending on the point of 680 attachement of the host doing resolution. This allows pointing at 681 more localized services. However, such a practice requires violating 682 DNS principles ('split horizon'), and hence is not recommended. 684 The other type of ambiguity is related to multiple provisioning 685 domains (see Section 12), and may get a different answer from the DNS 686 depending on which interface or DNS server is used to do the 687 resolution. This is particularly a problem when the normal expected 688 use of the option makes sense with private DNS zone(s), as might be 689 the case with a corporate VPN. It may also be the case that the 690 client has explicit DNS server configured so may not be using the 691 corporate internal DNS server. 693 FQDN does require a resolution into an actual address. This implies 694 the question when the FQDN resolution should be conducted. There are 695 a couple of possible answers: a) by the server, when it is started, 696 b) by the server, when it is about to send an option, c) by the 697 client, immediately after receiving an option, d) by the client, when 698 the content of the option is actually consumed. For a), b) and 699 possibly c), the option should really convey an address, not FQDN. 700 The only real incentive to use FQDN is case d). It is the only case 701 that allows possible changes in the DNS to be picked up by clients. 702 It may be generalized that the preference for address or FQDN depends 703 on its envisaged usage. Short lived (immediately consumed) data 704 should be address based, while long timed information is better 705 served with FQDN. 707 If the parameter is expected to be used by constrained devices (low 708 power, battery operated, low capabilities) or in very lossy networks, 709 it may be appealing to drop the requirement of having DNS resolution 710 being performed and use addresses. Another example of a constrained 711 device is a network booted device, where despite the fact that the 712 node itself is very capable once it's booted, the boot prom is quite 713 constrained. 715 Another aspect that should be considered is time required for the 716 clients to notice any configuration changes. Consider a case where a 717 server configures a service A using address and service B using FQDN. 718 When an administrator decides to update the configuration, he or she 719 can update the DHCP server configuration to change both services. If 720 the clients do not support reconfigure (which is an optional feature 721 of RFC3315, but in some environments, e.g. cable modems, is 722 mandatory), the configuration will be updated on clients after T1 723 timer elapses. Depending on the nature of the change (is it a new 724 server added to a cluster of already operating servers or a new 725 server that replaces the only available server that crashed?), this 726 may be an issue. On the other hand, updating service B may be 727 achieved with DNS record update. That information may be cached by 728 caching DNS servers for up to TTL. Depending on the values of T1 and 729 TTL, one update may be faster than another. Furthermore, depending 730 on the nature of the change (planned modification or unexpected 731 failure), T1 or TTL may be lowered before the change to speed up new 732 configuration adoption. 734 Addresses have a benefit of being easier to implemented and handle by 735 the DHCP software. An address option is simpler to use, its 736 validation is trivial (multiple of 16 constitutes a valid option), is 737 explicit and does not allow any ambiguity. It is faster (does not 738 require extra round trip time), so it is more efficient, which can be 739 especially important for energy restricted devices. It also does not 740 require having resolution capability. 742 FQDN imposes a number of additional failure modes and issues that 743 should be dealt with: 745 1. The client must have a knowledge about available DNS servers. 746 That typically means that option DNS_SERVERS [RFC3646] is 747 mandatory. This should be mentioned in the draft that defines 748 new option. It is possible that the server will return FQDN 749 option, but not the DNS Servers option. There should be a brief 750 discussion about it; 752 2. The DNS may not be reachable; 754 3. DNS may be available, but may not have appropriate information 755 (e.g. no AAAA records for specified FQDN); 757 4. Address family must be specified (A, AAAA or any); the 758 information being configured may require specific address family 759 (e.g. IPv6), but there may be a DNS record only of another type 760 (e.g. A only with IPv4 address). 762 5. What should the client do if there are multiple records available 763 (use only the first one, use all, use one and switch to the 764 second if the first fails for whatever reason, etc.); This may be 765 an issue if there is an expectation that the parameter being 766 configured will need exactly one address; 768 6. Multi-homed devices may be connected to different administrative 769 domains with each domain providing different information in DNS 770 (e.g. an enterprise network exposing private domains). Client 771 may send DNS queries to a different DNS server; 773 7. It should be mentioned if Internationalized Domain Names are 774 allowed. If they are, DNS option encoding should be specified. 776 Address options that are used with overly long T1 (renew timer) 777 values have some characteristics of hardcoded values. That is 778 strongly discouraged. See [RFC4085] for an in depth discussion. If 779 the option may appear in Information-Request, its lifetime should be 780 controlled using information refresh time option [RFC4242]. 782 One specific case that makes the choice between address and FQDN not 783 obvious is a DNSSEC bootstrap scenario. DNSSEC validation imposes a 784 requirement for clock sync (to the accuracy reasonably required to 785 consider signature inception and expiry times). This often implies 786 usage of NTP configuration. However, if the NTP is provided as FQDN, 787 there is no way to validate its DNSSEC signature. This is somewhat 788 weak argument though, as providing NTP server as an address is also 789 not verifiable using DNSSEC. If the thrustworthiness of the 790 configuration provided by DHCP server is in question, DHCPv6 offers 791 authentication mechanisms that allow server authentication. 793 9. Encapsulated options in DHCPv6 795 Most options are conveyed in a DHCPv6 message directly. Although 796 there is no codified normative language for such options, they are 797 often referred to as top-level options. Many options may include 798 other options. Such inner options are often referred to as 799 encapsulated or nested options. Those options are sometimes called 800 sub-options, but this term actually means something else, and 801 therefore should never be used to describe encapsulated options. It 802 is recommended to use term "encapsulated" as this terminology is used 803 in [RFC3315]. The difference between encapsulated and sub-options 804 are that the former uses normal DHCPv6 option numbers, while the 805 latter uses option number space specific to a given parent option. 806 It should be noted that, contrary to DHCPv4, there is no shortage of 807 option numbers. Therefore almost all options share a common option 808 space. For example option type 1 meant different things in DHCPv4, 809 depending if it was located in top-level or inside of Relay Agent 810 Information option. There is no such ambiguity in DHCPv6 (with the 811 exception of [RFC5908], which SHOULD NOT be used as a template for 812 future DHCP option definitions). 814 From the implementation perspective, it is easier to implement 815 encapsulated options rather than sub-options, as the implementers do 816 not have to deal with separate option spaces and can use the same 817 buffer parser in several places throughout the code. 819 Such encapsulation is not limited to one level. There is at least 820 one defined option that is encapsulated twice: Identity Association 821 for Prefix Delegation (IA_PD, defined in [RFC3633], section 9) 822 conveys IA Prefix (IAPREFIX, defined in [RFC3633], section 10). Such 823 delegated prefix may contain an excluded prefix range that is 824 represented by PD_EXCLUDE option that is conveyed as encapsulated 825 inside IAPREFIX (PD_EXCLUDE, defined in [RFC6603]). It seems awkward 826 to refer to such options as sub-sub-option or doubly encapsulated 827 option, therefore "encapsulated option" term is typically used, 828 regardless of the nesting level. 830 When defining a DHCP-based configuration mechanism for a protocol 831 that requires something more complex than a single option, it may be 832 tempting to group configuration values using sub-options. That 833 should preferably be avoided, as it increases complexity of the 834 parser. It is much easier, faster and less error prone to parse a 835 large number of options on a single (top-level) scope, than parse 836 options on several scopes. The use of sub-options should be avoided 837 as much as possible, but it is better to use sub-options rather than 838 conditional formatting. 840 It should be noted that currently there is no clear way defined for 841 requesting sub-options. Most known implementations are simply using 842 top-level ORO for requesting both top-level options and encapsulated 843 options. 845 10. Additional States Considered Harmful 847 DHCP is a protocol designed for provisioning clients. Less 848 experienced protocol designers often assume that it is easy to define 849 an option that will convey a different parameter for each client in a 850 network. Such problems arose during designs of MAP 851 [I-D.ietf-softwire-map-dhcp] and 4rd [I-D.ietf-softwire-4rd]. While 852 it would be easier for provisioned clients to get ready to use per- 853 client option values, such requirement puts exceedingly large loads 854 on the server side. The new extensions may introduce new 855 implementation complexity and additional database state on the 856 server. Alternatives should be considered, if possible. As an 857 example, [I-D.ietf-softwire-map-dhcp] was designed in a way that all 858 clients are provisioned with the same set of MAP options and each 859 provisioned client uses its unique address and delegated prefix to 860 generate client-specific information. Such a solution does not 861 introduce any additional state for the server and therefore scales 862 better. 864 It also should be noted that contrary to DHCPv4, DHCPv6 keeps several 865 timers for renewals. Each IA_NA (addresses) and IA_PD (prefixes) 866 contains T1 and T2 timers that designate time after which client will 867 initiate renewal. Those timers apply only to its own IA containers. 868 Refreshing other parameters should be initiated after a time 869 specified in the Information Refresh Time Option (defined in 870 [RFC4242]), carried in the Reply message and returned in response to 871 Information-Request message. Introducing additional timers make 872 deployment unnecessarily complex and SHOULD be avoided. 874 11. Configuration changes occur at fixed times 876 In general, DHCPv6 clients only refresh configuration data from the 877 DHCP server when the T1 timer expires. Although there is a 878 RECONFIGURE mechanism that allows a DHCP server to request that 879 clients initiate reconfiguration, support for this mechanism is 880 optional and cannot be relied upon. 882 Even when DHCP clients refresh their configuration information, not 883 all consumers of DHCP-sourced configuration data notice these 884 changes. For instance, if a server is started using parameters 885 received in an early DHCP transaction, but does not check for updates 886 from DHCP, it may well continue to use the same parameter 887 indefinitely. There are a few operating systems that take care of 888 reconfiguring services when the client moves to a new network(e.g. 889 based on mechanisms like [RFC4436], [RFC4957] or [RFC6059]), but it's 890 worth bearing in mind that a renew may not always result in the 891 client taking up new configuration information that it receives. 893 In light of the above, when designing an option you should take into 894 consideration the fact that your option may hold stale data that will 895 only be updated at an arbitrary time in the future. 897 12. Multiple provisioning domains 899 In some cases there could be more than one DHCPv6 server on a link, 900 with each providing a different set of parameters. One notable 901 example of such a case is a home network with a connection to two 902 independent ISPs. 904 The DHCPv6 protocol specification does not provide clear advice on 905 how to handle multiple provisioning sources. Although [RFC3315] 906 states that a client that receives more than one ADVERTISE message, 907 may respond to one or more of them, such capability has not been 908 observed in existing implementations. Existing clients will pick one 909 server and will continue configuration process with that server, 910 ignoring all other servers. 912 In addition, a node that acts as a DHCPv6 client may be connected to 913 more than one physical network. In this case, it will in most cases 914 operate a separate DHCP client state machine on each interface, 915 acquiring different, possibly conflicting information through each. 916 This information will not be acquired in any synchronized way. 918 Existing nodes cannot be assumed to systematically segregate 919 configuration information on the basis of its source; as a result, it 920 is quite possible that a node may receive an FQDN on one network 921 interface, but do the DNS resolution on a different network 922 interface, using different DNS servers. As a consequence, DNS 923 resolution done by the DHCP server is more likely to behave 924 predictably than DNS resolution done on a multi-interface or multi- 925 homed client. 927 This is a generic DHCP protocol issue and should not be dealt within 928 each option separately. This issue is better dealt with using a 929 protocol-level solution and fixing this problem should not be 930 attempted on a per option basis. Work is ongoing in the IETF to 931 provide a systematic solution to this problem. 933 13. Chartering Requirements and Advice for Responsible Area Directors 935 Adding a simple DHCP option is straightforward, and generally 936 something that any working group can do, perhaps with some help from 937 designated DHCP experts. However, when new fragment types need to be 938 devised, this requires the attention of DHCP experts, and should not 939 be done in a working group that doesn't have a quorum of such 940 experts. This is true whether the new fragment type has the same 941 structure as an existing fragment type but has different semantics, 942 or the new format has a new structure. 944 Responsible Area Directors for working groups that wish to add a work 945 item to a working group charter to define a new DHCP option should 946 get clarity from the working group as to whether the new option will 947 require a new fragment type or new semantics, or whether it is a 948 simple DHCP option that fits existing definitions. 950 If a working group needs a new fragment type, it is preferable to see 951 if another working group exists whose members already have sufficient 952 expertise to evaluate the new work. If such a working group is 953 available, the work should be chartered in that working group 954 instead. If there is no other working group with DHCP expertise that 955 can define the new fragment type, the responsible AD should seek help 956 from known DHCP experts within the IETF to provide advice and 957 frequent early review as the original working group defines the new 958 fragment type. 960 In either case, the new option should be defined in a separate 961 document, and the work should focus on defining a new format that 962 generalizes well and can be reused, rather than a single-use fragment 963 type. The working group that needs the new fragment type can define 964 their new option referencing the new fragment type document, and the 965 work can generally be done in parallel, avoiding unnecessary delays. 966 Having the definition in its own document will foster reuse of the 967 new fragment type. 969 The responsible AD should work with all relevant working group chairs 970 and DHCP experts to ensure that the new fragment type document has in 971 fact been carefully reviewed by the experts and appears satisfactory. 973 Responsible area directors for working groups that are considering 974 defining options that actually update the DHCP protocol, as opposed 975 to simple options, should go through a process similar to that 976 described above when trying to determine where to do the work. Under 977 no circumstances should a working group be given a charter 978 deliverable to define a new DHCP option, and then on the basis of 979 that charter item actually make updates to the DHCP protocol. 981 14. Considerations for Creating New Formats 983 When defining new options, one specific consideration to evaluate is 984 whether or not options of a similar format would need to have 985 multiple or single values encoded (whatever differs from the current 986 option), and how that might be accomplished in a similar format. 988 When defining a new option, it is best to synthesize the option 989 format using fragment types already in use. However, in some cases 990 there may be no fragment type that accomplishes the intended purpose. 992 The matter of size considerations and option order are further 993 discussed in Section 15 and Section 17. 995 15. Option Size 996 DHCPv6 [RFC3315] allows for packet sizes up to 64KB. First, through 997 its use of link-local addresses, it avoids many of the deployment 998 problems that plague DHCPv4, and is actually an UDP over IPv6 based 999 protocol (compared to DHCPv4, which is mostly UDP over IPv4 protocol, 1000 but with layer 2 hacks). Second, RFC 3315 explicitly refers readers 1001 to RFC 2460 Section 5, which describes an MTU of 1280 octets and a 1002 minimum fragment reassembly of 1500 octets. It's feasible to suggest 1003 that DHCPv6 is capable of having larger options deployed over it, and 1004 at least no common upper limit is yet known to have been encoded by 1005 its implementors. It is not really possible to describe a fixed 1006 limit that cleanly divides workable option sizes from those that are 1007 too big. 1009 It is advantageous to prefer option formats which contain the desired 1010 information in the smallest form factor that satisfies the 1011 requirements. Common sense still applies here. It is better to 1012 split distinct values into separate octets rather than propose overly 1013 complex bit shifting operations to save several bits (or even an 1014 octet or two) that would be padded to the next octet boundary anyway. 1016 DHCPv6 does allow for multiple instances of a given option, and they 1017 are treated as distinct values following the defined format, however 1018 this feature is generally preferred to be restricted to protocol 1019 class features (such as the IA_* series of options). In such cases, 1020 it is better to define an option as an array if it is possible. It 1021 is recommended to clarify (with normative language) whether a given 1022 DHCPv6 option may appear once or multiple times. The default 1023 assumption is only once. 1025 In general, if a lot of data needs to be configured (for example, 1026 some option lengths are quite large), DHCPv6 may not be the best 1027 choice to deliver such configuration information and SHOULD simply be 1028 used to deliver a URI that specifies where to obtain the actual 1029 configuration information. 1031 16. Singleton options 1033 Although [RFC3315] states that each option type MAY appear more than 1034 once, the original idea was that multiple instances are reserved for 1035 stateful options, like IA_NA or IA_PD. For most other options it is 1036 usually expected that they will appear at most once. Such options 1037 are called singleton options. Sadly, RFCs have often failed to 1038 clearly specify whether a given option can appear more than once or 1039 not. 1041 Documents that define new options SHOULD state whether these options 1042 are singletons or not. Unless otherwise specified, newly defined 1043 options are considered to be singletons. If multiple instances are 1044 allowed, the document MUST explain how to use them. Care should be 1045 taken to not assume the they will be processed in the other they 1046 appear in the message. See Section 17 for more details. 1048 When deciding whether a single or multiple option instances are 1049 allowed in a message, take into consideration how the content of the 1050 option will be used. Depending on the service being configured it 1051 may or may not make sense to have multiple values configured. If 1052 multiple values make sense, it is better to explicitly allow that by 1053 using option format that allows multiple values within one option 1054 instance. 1056 Allowing multiple option instances often leads to confusion. 1057 Consider the following example. Basic DS-Lite architecture assumes 1058 that the B4 element (DHCPv6 client) will receive AFTR option and 1059 establish a single tunnel to configured tunnel termination point 1060 (AFTR). During standardization process of [RFC6334] there was a 1061 discussion whether multiple instances of DS-Lite tunnel option should 1062 be allowed. This created an unfounded expectation that the clients 1063 receiving multiple instances of the option will somehow know when one 1064 tunnel endpoint goes off-line and do some sort of failover between 1065 other values provided in other instances of the AFTR option. Others 1066 assumed that if there are multiple options, the client will somehow 1067 do a load balancing between provided tunnel endpoints. Neither 1068 failover nor load balancing was defined for DS-Lite architecture, so 1069 it caused confusion. It was eventually decided to allow only one 1070 instance of the AFTR option. 1072 17. Option Order 1074 Option order, either the order among many DHCPv6 options or the order 1075 of multiple instances of the same option, SHOULD NOT be significant. 1076 New documents MUST NOT assume any specific option processing order. 1078 As there is no explicit order for multiple instance of the same 1079 option, an option definition SHOULD instead restrict ordering by 1080 using a single option that contains ordered fields. 1082 As [RFC3315] does not impose option order, some implementations use 1083 hash tables to store received options (which is a conformant 1084 behavior). Depending on the hash implementation, the processing 1085 order is almost always different then the order in which options 1086 appeared in the packet on wire. 1088 18. Relay Options 1090 In DHCPv4, all relay options are organized as sub-options within DHCP 1091 Relay Agent Information Option[RFC3046]. And an independent number 1092 space called "DHCP Relay Agent Sub-options" is maintained by IANA. 1093 Different from DHCPv4, in DHCPv6, Relay options are defined in the 1094 same way as client/server options, and they too use the same number 1095 space as client/server options. Future DHCPv6 Relay options MUST be 1096 allocated from this single DHCPv6 Option number space. 1098 E.g. the Relay-Supplied Options Option [RFC6422] may also contain 1099 some DHCPv6 options as permitted, such as the EAP Re-authentication 1100 Protocol (ERP) Local Domain Name DHCPv6 Option [RFC6440]. 1102 19. Clients Request their Options 1104 The DHCPv6 Option Request Option (OPTION_ORO) [RFC3315], is an option 1105 that serves two purposes - to inform the server what options the 1106 client supports and to inform what options the client is willing to 1107 consume. 1109 For some options, such as the options required for the functioning of 1110 the DHCPv6 protocol itself, it doesn't make sense to require that 1111 they be explicitly requested using the Option Request Option. In all 1112 other cases, it is prudent to assume that any new option must be 1113 present on the relevant option request list if the client desires to 1114 receive it. 1116 It is tempting to add text that requires the client to include a new 1117 option in Option Request Option list, similar to this text: "Clients 1118 MUST place the foo option code on the Option Request Option list, 1119 clients MAY include option foo in their packets as hints for the 1120 server as values the desire, and servers MUST include option foo when 1121 the client requested it (and the server has been so configured)". 1122 Such text is discouraged as there are several issues with it. First, 1123 it assumes that client implementation that supports a given option 1124 will always want to use it. This is not true. The second and more 1125 important reason is that such text essentially duplicates mechanism 1126 already defined in [RFC3315]. It is better to simply refer to the 1127 existing mechanism rather than define it again. See Section 21 for 1128 proposed examples on how to do that. 1130 Creators of DHCPv6 options cannot not assume special ordering of 1131 options either as they appear in the option request option, or as 1132 they appear within the packet. Although it is reasonable to expect 1133 that options will be processed in the order they appear in ORO, 1134 server software is not required to sort DHCPv6 options into the same 1135 order in reply messages. 1137 It should also be noted that options values are never aligned within 1138 the DHCP packet, even the option code and option length may appear on 1139 odd byte boundaries. 1141 20. Transition Technologies 1143 Transition from IPv4 to IPv6 is progressing. Many transition 1144 technologies are proposed to speed it up. As a natural consequence 1145 there are also DHCP options proposed to provision those proposals. 1146 The inevitable question is whether the required parameters should be 1147 delivered over DHCPv4 or DHCPv6. Authors often don't give much 1148 thought about it and simply pick DHCPv6 without realizing the 1149 consequences. IPv6 is expected to stay with us for many decades, and 1150 so is DHCPv6. There is no mechanism available to deprecate an option 1151 in DHCPv6, so any options defined will stay with us as long as DHCPv6 1152 protocol itself. It seems likely that such options defined to 1153 transition from IPv4 will outlive IPv4 by many decades. From that 1154 perspective it is better to implement provisioning of the transition 1155 technologies in DHCPv4, which will be obsoleted together with IPv4. 1157 When the network infrastructure becomes IPv6-only, the support for 1158 IPv4-only nodes may still be needed. In such a scenario, a mechanism 1159 for providing IPv4 configuration information over IPv6-only networks 1160 such as [I-D.ietf-dhc-v4configuration] may be needed. 1162 21. Recommended sections in the new document 1164 There are three major entities in DHCPv6 protocol: server, relay 1165 agent, and client. It is very helpful for implementers to include 1166 separate sections that describe operation for those three major 1167 entities. Even when a given entity does not participate, it is 1168 useful to have a very short section stating that it must not send a 1169 given option and must ignore it when received. 1171 There is also a separate entity called requestor, which is a special 1172 client-like type that participates in leasequery protocol [RFC5007] 1173 and [RFC5460]. A similar section for the requestor is not required, 1174 unless the new option has anything to do with requestor (or it is 1175 likely that the reader may think that is has). It should be noted 1176 that while in the majority of deployments, requestor is co-located 1177 with relay agent, those are two separate entities from the protocol 1178 perspective and they may be used separately. There are stand-alone 1179 requestor implementations available. 1181 The following sections include proposed text for such sections. That 1182 text is not required to appear, but it is appropriate in most cases. 1183 Additional or modified text specific to a given option is often 1184 required. 1186 Although requestor is somewhat uncommon functionality, its existence 1187 should be noted, especially when allowing or disallowing options to 1188 appear in certain message or being sent by certain entities. 1190 Additional message types may appear in the future, besides types 1191 defined in [RFC3315]. Therefore authors are encouraged to 1192 familiarize themselves with a list of currently defined DHCPv6 1193 messages available on IANA website [iana]. 1195 Typically new options are requested by clients and assigned by the 1196 server, so there is no specific relay behavior. Nevertheless it is 1197 good to include a section for relay agent behavior and simply state 1198 that there are no additional requirements for relays. The same 1199 applies for client behavior if the options are to be exchanged 1200 between relay and server. 1202 Sections that contain option definitions MUST include formal 1203 verification procedure. Often it is very simple, e.g. option that 1204 conveys IPv6 address must be exactly 16 bytes long, but sometimes the 1205 rules are more complex. It is recommeded to refer to existing 1206 documents (e.g. section 8 of RFC3315 for domain name encoding) rather 1207 than trying to repeat such rules. 1209 21.1. DHCPv6 Client Behavior Text 1211 Clients MAY request option foo, as defined in [RFC3315], sections 1212 17.1.1, 18.1.1, 18.1.3, 18.1.4, 18.1.5 and 22.7. As a convenience to 1213 the reader, we mention here that the client includes requested option 1214 codes in Option Request Option. 1216 Optional text (if client's hints make sense): Client also MAY include 1217 option foo in its SOLICIT, REQUEST, RENEW, REBIND and INFORMATION- 1218 REQUEST messages as a hint for the server regarding preferred option 1219 values. 1221 Optional text (if the option contains FQDN): If the client requests 1222 an option that conveys an FQDN, it is expected that the contents of 1223 that option will be resolved using DNS. Hence the following text may 1224 be useful: Clients that request option foo SHOULD also request option 1225 OPTION_DNS_SERVERS specified in [RFC3646]. 1227 Clients MUST discard option foo if it is invalid (i.e. did not pass 1228 validation steps defined in Section X.Y). 1230 Optional text (if option foo in expected to be exchanged between 1231 relays and servers): Option foo is exchanged between relays and 1232 servers only. Clients are not aware of the usage of option foo. 1233 Clients MUST ignore received option foo. 1235 21.2. DHCPv6 Server Behavior Text 1236 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation in 1237 regards to option assignment. As a convenience to the reader, we 1238 mention here that the server will send option foo only if configured 1239 with specific values for foo and the client requested it. 1241 Optional text: Option foo is a singleton. Servers MUST NOT send more 1242 than one instance of foo option. 1244 Optional text (if server is never supposed to receive option foo): 1245 Servers MUST ignore incoming foo option. 1247 21.3. DHCPv6 Relay Agent Behavior Text 1249 It's never appropriate for a relay agent to add options to a message 1250 heading toward the client, and relay agents don't actually construct 1251 Relay-Reply messages anyway. 1253 Optional text (if foo option is exchanged between clients and server 1254 or between requestors and servers): There are no additional 1255 requirements for relays. 1257 Optional text (if relays are expected to insert or consume option 1258 foo): Relay agents MAY include option foo in a Relay-Forw when 1259 forwarding packets from clients to the servers. 1261 22. Should the new document update existing RFCs? 1263 Authors often ask themselves a question whether their proposal 1264 updates exist RFCs, especially 3315. In April 2013 there were about 1265 80 options defined. Had all documents that defined them also updated 1266 RFC3315, comprehension of such a document set would be extremely 1267 difficult. It should be noted that "extends" and "updates" are two 1268 very different verbs. If a new draft defines a new option that 1269 clients request and servers provide, it merely extends current 1270 standards, so "updates 3315" is not required in the new document 1271 header. On the other hand, if a new document replaces, modifies 1272 existing behavior, includes clarifications or other corrections, it 1273 should be noted that it updates the other document. For example, 1274 [RFC6644] clearly updates [RFC3315] as it replaces existing with new 1275 text. 1277 If in doubt, authors should try to answer a question whether 1278 implementor reading the base RFC alone (without reading the new 1279 draft) would be able to properly implement the software. If the base 1280 RFC is sufficient, that the new draft most probably does not update 1281 the base RFC. On the other hand, if reading your draft is necessary 1282 to properly implement the base RFC, then the new draft most likely 1283 updates the base RFC. 1285 23. Security Considerations 1287 DHCPv6 does have an Authentication mechanism ([RFC3315]) that makes 1288 it possible for DHCPv6 software to discriminate between authentic 1289 endpoints and man-in-the-middle. Other authentication mechanisms may 1290 optionally be deployed. Sadly, as of late 2013, the authentication 1291 in DHCPv6 is rarely used and support for it is not common in existing 1292 implementations. Some specific deployment types make it mandatory 1293 (or parts of thereof, e.g. DOCSIS3.0 compatible cable modems require 1294 reconfigure-key support), so in certain cases specific authentication 1295 aspects can be relied upon. That is not true in the generic case, 1296 though. 1298 So, while creating a new option, it is prudent to assume that the 1299 DHCPv6 packet contents are always transmitted in the clear, and 1300 actual production use of the software will probably be vulnerable at 1301 least to man-in-the-middle attacks from within the network, even 1302 where the network itself is protected from external attacks by 1303 firewalls. In particular, some DHCPv6 message exchanges are 1304 transmitted to multicast addresses that are likely broadcast anyway. 1306 If an option is of a specific fixed length, it is useful to remind 1307 the implementer of the option data's full length. This is easily 1308 done by declaring the specific value of the 'length' tag of the 1309 option. This helps to gently remind implementers to validate option 1310 length before digesting them into likewise fixed length regions of 1311 memory or stack. 1313 If an option may be of variable size (such as having indeterminate 1314 length fields, such as domain names or text strings), it is advisable 1315 to explicitly remind the implementor to be aware of the potential for 1316 long options. Either define a reasonable upper limit (and suggest 1317 validating it), or explicitly remind the implementor that an option 1318 may be exceptionally long (to be prepared to handle errors rather 1319 than truncate values). 1321 For some option contents, out of bound values may be used to breach 1322 security. An IP address field might be made to carry a loopback 1323 address, or local multicast address, and depending on the protocol 1324 this may lead to undesirable results. A domain name field may be 1325 filled with contrived contents that exceed the limitations placed 1326 upon domain name formatting - as this value is possibly delivered to 1327 "internal configuration" records of the system, it may be implicitly 1328 trusted without being validated. 1330 Authors of drafts defining new DHCP options are therefore strongly 1331 advised to explicitly define validation measures that recipients of 1332 such options are required to do before processing such options. 1334 However, validation measures already defined by RFC3315 or other 1335 specifications referenced by the new option document are redundant, 1336 and can introduce errors, so authors are equally strongly advised to 1337 refer to the base specification for any such validation language 1338 rather than copying it into the new specification. 1340 Also see Section 24. 1342 24. Privacy considerations 1344 As discussed in Section 23 the DHCPv6 packets are typically 1345 transmitted in the clear, so they are susceptible to eavesdropping. 1346 This should be considered when defining options that may convey 1347 personally identifying information (PII) or any other type of 1348 sensitive data. 1350 If the transmission of sensitive or confidential content is required, 1351 it is still possible to secure communication between relay agents and 1352 servers. Relay agents and servers communicating with relay agents 1353 must support the use of IPsec Encapsulating Security Payload (ESP) 1354 with encryption in transport mode, according to Section 3.1.1 of 1355 [RFC4303] and Section 21.1 of [RFC3315]. Sadly, this requirement is 1356 almost universally ignored in real deployments. Even if the 1357 communication path between relay agents and server is secured, the 1358 path between clients and relay agents or server is not. 1360 Unless underlying transmission technology provides a secure 1361 transmission channel, the DHCPv6 options SHOULD NOT include PII or 1362 other sensitive information. If there are special circumstances that 1363 warrant sending such information over unsecured DHCPv6, the dangers 1364 MUST be clearly discussed in security considerations. 1366 25. IANA Considerations 1368 This document has no actions for IANA. 1370 26. Acknowledgements 1372 Authors would like to thank Simon Perreault, Bernie Volz, Ted Lemon, 1373 Bud Millwood, Ralph Droms, Barry Leiba, Benoit Claise, Brian 1374 Haberman, Richard Barnes, Stephen Farrell and Steward Bryant for 1375 their comments. 1377 27. References 1379 27.1. Normative References 1381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1382 Requirement Levels", BCP 14, RFC 2119, March 1997. 1384 [RFC3315] Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., 1385 and M. Carney, "Dynamic Host Configuration Protocol for 1386 IPv6 (DHCPv6)", RFC 3315, July 2003. 1388 27.2. Informative References 1390 [I-D.ietf-dhc-v4configuration] 1391 Rajtar, B. and I. Farrer, "Provisioning IPv4 Configuration 1392 Over IPv6 Only Networks", draft-ietf-dhc- 1393 v4configuration-03 (work in progress), December 2013. 1395 [I-D.ietf-softwire-4rd] 1396 Despres, R., Jiang, S., Penno, R., Lee, Y., Chen, G., and 1397 M. Chen, "IPv4 Residual Deployment via IPv6 - a Stateless 1398 Solution (4rd)", draft-ietf-softwire-4rd-07 (work in 1399 progress), October 2013. 1401 [I-D.ietf-softwire-map-dhcp] 1402 Mrugalski, T., Troan, O., Dec, W., Bao, C., 1403 leaf.yeh.sdo@gmail.com, l., and X. Deng, "DHCPv6 Options 1404 for configuration of Softwire Address and Port Mapped 1405 Clients", draft-ietf-softwire-map-dhcp-06 (work in 1406 progress), November 2013. 1408 [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC 1409 3046, January 2001. 1411 [RFC3319] Schulzrinne, H. and B. Volz, "Dynamic Host Configuration 1412 Protocol (DHCPv6) Options for Session Initiation Protocol 1413 (SIP) Servers", RFC 3319, July 2003. 1415 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1416 10646", STD 63, RFC 3629, November 2003. 1418 [RFC3633] Troan, O. and R. Droms, "IPv6 Prefix Options for Dynamic 1419 Host Configuration Protocol (DHCP) version 6", RFC 3633, 1420 December 2003. 1422 [RFC3646] Droms, R., "DNS Configuration options for Dynamic Host 1423 Configuration Protocol for IPv6 (DHCPv6)", RFC 3646, 1424 December 2003. 1426 [RFC3898] Kalusivalingam, V., "Network Information Service (NIS) 1427 Configuration Options for Dynamic Host Configuration 1428 Protocol for IPv6 (DHCPv6)", RFC 3898, October 2004. 1430 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1431 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1432 3986, January 2005. 1434 [RFC4075] Kalusivalingam, V., "Simple Network Time Protocol (SNTP) 1435 Configuration Option for DHCPv6", RFC 4075, May 2005. 1437 [RFC4085] Plonka, D., "Embedding Globally-Routable Internet 1438 Addresses Considered Harmful", BCP 105, RFC 4085, June 1439 2005. 1441 [RFC4242] Venaas, S., Chown, T., and B. Volz, "Information Refresh 1442 Time Option for Dynamic Host Configuration Protocol for 1443 IPv6 (DHCPv6)", RFC 4242, November 2005. 1445 [RFC4280] Chowdhury, K., Yegani, P., and L. Madour, "Dynamic Host 1446 Configuration Protocol (DHCP) Options for Broadcast and 1447 Multicast Control Servers", RFC 4280, November 2005. 1449 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", RFC 1450 4303, December 2005. 1452 [RFC4436] Aboba, B., Carlson, J., and S. Cheshire, "Detecting 1453 Network Attachment in IPv4 (DNAv4)", RFC 4436, March 2006. 1455 [RFC4704] Volz, B., "The Dynamic Host Configuration Protocol for 1456 IPv6 (DHCPv6) Client Fully Qualified Domain Name (FQDN) 1457 Option", RFC 4704, October 2006. 1459 [RFC4833] Lear, E. and P. Eggert, "Timezone Options for DHCP", RFC 1460 4833, April 2007. 1462 [RFC4957] Krishnan, S., Montavont, N., Njedjou, E., Veerepalli, S., 1463 and A. Yegin, "Link-Layer Event Notifications for 1464 Detecting Network Attachments", RFC 4957, August 2007. 1466 [RFC5007] Brzozowski, J., Kinnear, K., Volz, B., and S. Zeng, 1467 "DHCPv6 Leasequery", RFC 5007, September 2007. 1469 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 1470 Interchange", RFC 5198, March 2008. 1472 [RFC5223] Schulzrinne, H., Polk, J., and H. Tschofenig, "Discovering 1473 Location-to-Service Translation (LoST) Servers Using the 1474 Dynamic Host Configuration Protocol (DHCP)", RFC 5223, 1475 August 2008. 1477 [RFC5460] Stapp, M., "DHCPv6 Bulk Leasequery", RFC 5460, February 1478 2009. 1480 [RFC5908] Gayraud, R. and B. Lourdelet, "Network Time Protocol (NTP) 1481 Server Option for DHCPv6", RFC 5908, June 2010. 1483 [RFC5970] Huth, T., Freimann, J., Zimmer, V., and D. Thaler, "DHCPv6 1484 Options for Network Boot", RFC 5970, September 2010. 1486 [RFC5986] Thomson, M. and J. Winterbottom, "Discovering the Local 1487 Location Information Server (LIS)", RFC 5986, September 1488 2010. 1490 [RFC6059] Krishnan, S. and G. Daley, "Simple Procedures for 1491 Detecting Network Attachment in IPv6", RFC 6059, November 1492 2010. 1494 [RFC6334] Hankins, D. and T. Mrugalski, "Dynamic Host Configuration 1495 Protocol for IPv6 (DHCPv6) Option for Dual-Stack Lite", 1496 RFC 6334, August 2011. 1498 [RFC6422] Lemon, T. and Q. Wu, "Relay-Supplied DHCP Options", RFC 1499 6422, December 2011. 1501 [RFC6440] Zorn, G., Wu, Q., and Y. Wang, "The EAP Re-authentication 1502 Protocol (ERP) Local Domain Name DHCPv6 Option", RFC 6440, 1503 December 2011. 1505 [RFC6603] Korhonen, J., Savolainen, T., Krishnan, S., and O. Troan, 1506 "Prefix Exclude Option for DHCPv6-based Prefix 1507 Delegation", RFC 6603, May 2012. 1509 [RFC6610] Jang, H., Yegin, A., Chowdhury, K., Choi, J., and T. 1510 Lemon, "DHCP Options for Home Information Discovery in 1511 Mobile IPv6 (MIPv6)", RFC 6610, May 2012. 1513 [RFC6644] Evans, D., Droms, R., and S. Jiang, "Rebind Capability in 1514 DHCPv6 Reconfigure Messages", RFC 6644, July 2012. 1516 [iana] IANA, , "DHCPv6 parameters (IANA webpage)", November 2003, 1517 . 1519 Authors' Addresses 1520 David W. Hankins 1521 Google, Inc. 1522 1600 Amphitheatre Parkway 1523 Mountain View, CA 94043 1524 USA 1526 Email: dhankins@google.com 1528 Tomek Mrugalski 1529 Internet Systems Consortium, Inc. 1530 950 Charter Street 1531 Redwood City, CA 94063 1532 USA 1534 Phone: +1 650 423 1345 1535 Email: tomasz.mrugalski@gmail.com 1537 Marcin Siodelski 1538 950 Charter Street 1539 Redwood City, CA 94063 1540 USA 1542 Phone: +1 650 423 1431 1543 Email: msiodelski@gmail.com 1545 Sheng Jiang 1546 Huawei Technologies Co., Ltd 1547 Q14, Huawei Campus, No.156 Beiqing Road 1548 Hai-Dian District, Beijing, 100095 1549 P.R. China 1551 Email: jiangsheng@huawei.com 1553 Suresh Krishnan 1554 Ericsson 1555 8400 Blvd Decarie 1556 Town of Mount Royal, Quebec 1557 Canada 1559 Email: suresh.krishnan@ericsson.com