idnits 2.17.1 draft-ietf-dhc-option-guidelines-13.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 (July 29, 2013) is 3921 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-01 == Outdated reference: A later version (-10) exists of draft-ietf-softwire-4rd-06 == Outdated reference: A later version (-12) exists of draft-ietf-softwire-map-dhcp-04 -- 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: January 30, 2014 ISC 7 S. Jiang 8 Huawei Technologies Co., Ltd 9 S. Krishnan 10 Ericsson 11 July 29, 2013 13 Guidelines for Creating New DHCPv6 Options 14 draft-ietf-dhc-option-guidelines-13 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. This document updates 21 RFC3315. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on January 30, 2014. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 58 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. When to Use DHCPv6 . . . . . . . . . . . . . . . . . . . . . 4 60 4. General Principles . . . . . . . . . . . . . . . . . . . . . 4 61 5. Reusing Other Options Formats . . . . . . . . . . . . . . . . 5 62 5.1. Option with IPv6 addresses . . . . . . . . . . . . . . . 5 63 5.2. Option with a single flag (boolean) . . . . . . . . . . . 6 64 5.3. Option with IPv6 prefix . . . . . . . . . . . . . . . . . 7 65 5.4. Option with 32-bit integer value . . . . . . . . . . . . 8 66 5.5. Option with 16-bit integer value . . . . . . . . . . . . 8 67 5.6. Option with 8-bit integer value . . . . . . . . . . . . . 9 68 5.7. Option with URI . . . . . . . . . . . . . . . . . . . . . 9 69 5.8. Option with Text String . . . . . . . . . . . . . . . . . 10 70 5.9. Option with variable length data . . . . . . . . . . . . 11 71 5.10. Option with DNS Wire Format Domain Name List . . . . . . 12 72 6. Avoid Conditional Formatting . . . . . . . . . . . . . . . . 12 73 7. Avoid Aliasing . . . . . . . . . . . . . . . . . . . . . . . 13 74 8. Choosing between FQDN and address . . . . . . . . . . . . . . 13 75 9. Encapsulated options in DHCPv6 . . . . . . . . . . . . . . . 15 76 10. Additional States Considered Harmful . . . . . . . . . . . . 16 77 11. Configuration changes occur at fixed times . . . . . . . . . 17 78 12. Multiple provisioning domains . . . . . . . . . . . . . . . . 17 79 13. Chartering Requirements and Advice for Responsible ADs . . . 17 80 14. Considerations for Creating New Formats . . . . . . . . . . . 19 81 15. Option Size . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 16. Singleton options . . . . . . . . . . . . . . . . . . . . . . 20 83 17. Option Order . . . . . . . . . . . . . . . . . . . . . . . . 20 84 18. Relay Options . . . . . . . . . . . . . . . . . . . . . . . . 21 85 19. Clients Request their Options . . . . . . . . . . . . . . . . 21 86 20. Transition Technologies . . . . . . . . . . . . . . . . . . . 22 87 21. Recommended sections in the new document . . . . . . . . . . 22 88 21.1. DHCPv6 Client Behavior Text . . . . . . . . . . . . . . 23 89 21.2. DHCPv6 Server Behavior Text . . . . . . . . . . . . . . 24 90 21.3. DHCPv6 Relay Agent Behavior Text . . . . . . . . . . . . 24 91 22. Should the new document update existing RFCs? . . . . . . . . 24 92 23. Security Considerations . . . . . . . . . . . . . . . . . . . 25 93 24. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 94 25. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26 95 26. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 96 26.1. Normative References . . . . . . . . . . . . . . . . . . 26 97 26.2. Informative References . . . . . . . . . . . . . . . . . 26 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 100 1. Requirements Language 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in RFC 2119 [RFC2119]. 106 2. Introduction 108 Most protocol developers ask themselves if a protocol will work, or 109 work efficiently. These are important questions, but another less 110 frequently considered question is whether the proposed protocol 111 presents itself needless barriers to adoption by deployed software. 113 DHCPv6 [RFC3315] software implementors are not merely faced with the 114 task of handling a given option's format on the wire. The option 115 must fit into every stage of the system's process, starting with the 116 user interface used to enter the configuration up to the machine 117 interfaces where configuration is ultimately consumed. 119 Another frequently overlooked aspect of rapid adoption is whether the 120 option requires operators to be intimately familiar with the option's 121 internal format in order to use it? Most DHCPv6 software provides a 122 facility for handling unknown options at the time of publication. 123 The handling of such options usually needs to be manually configured 124 by the operator. But if doing so requires extensive reading (more 125 than can be covered in a simple FAQ for example), it inhibits 126 adoption. 128 So although a given solution would work, and might even be space, 129 time, or aesthetically optimal, a given option is presented with a 130 series of ever-worsening challenges to be adopted: 132 o If it doesn't fit neatly into existing config files. 134 o If it requires source code changes to be adopted, and hence 135 upgrades of deployed software. 137 o If it does not share its deployment fate in a general manner with 138 other options, standing alone in requiring code changes or 139 reworking configuration file syntaxes. 141 o If the option would work well in the particular deployment 142 environment the proponents currently envision, but has equally 143 valid uses in some other environment where the proposed option 144 format would fail or would produce inconsistent results. 146 There are many things DHCPv6 option creators can do to avoid the 147 pitfalls in this list entirely, or failing that, to make software 148 implementors lives easier and improve its chances for widespread 149 adoption. 151 3. When to Use DHCPv6 153 Principally, DHCPv6 carries configuration parameters for its clients. 154 Any knob, dial, slider, or checkbox on the client system, such as "my 155 domain name servers", "my hostname", or even "my shutdown 156 temperature" are candidates for being configured by DHCPv6. 158 The presence of such a knob isn't enough, because DHCPv6 also 159 presents the extension of an administrative domain - the operator of 160 the network to which the client is currently attached. Someone runs 161 not only the local switching network infrastructure that the client 162 is directly (or wirelessly) attached to, but the various methods of 163 accessing the external Internet via local assist services that the 164 network must also provide (such as domain name servers, or routers). 165 This means that in addition to the existence of a configuration 166 parameter, one must also ask themselves if it is reasonable for this 167 parameter to be set by the directly attached network's 168 administrators. 170 Note that the client is not required to configure any of these values 171 received via DHCPv6 (for example, due to having a value manually 172 configured by its own operator). Bear in mind that doing so might 173 cause the client to be rejected network attachment privileges, and 174 this is one of the main reasons for the use of DHCPv6 in corporate 175 enterprises. 177 4. General Principles 179 The primary guiding principle to follow in order to enhance an 180 option's adoptability is reuse. The option should be created in such 181 a way that does not require any new or special case software to 182 support. If old software currently deployed and in the field can 183 adopt the option through supplied configuration facilities then it's 184 fairly certain that new software can easily formally adopt it. 186 There are at least two classes of DHCPv6 options: simple options 187 which are provided explicitly to carry data from one side of the 188 DHCPv6 exchange to the other (such as nameservers, domain names, or 189 time servers), and a protocol class of options which require special 190 processing on the part of the DHCPv6 software or are used during 191 special processing (such as the Fully Qualified Domain Name (FQDN) 192 option [RFC4704]), and so forth; these options carry data that is the 193 result of a routine in some DHCPv6 software. 195 The guidelines laid out here should be applied in a relaxed manner 196 for the protocol class of options. Wherever special case code is 197 already required to adopt the DHCPv6 option, it is substantially more 198 reasonable to format the option in a less generic fashion, if there 199 are measurable benefits to doing so. 201 5. Reusing Other Options Formats 203 The easiest approach to manufacturing trivially deployable DHCPv6 204 Options is to assemble the option out of whatever common fragments 205 fit - possibly allowing a group of data elements to repeat to fill 206 the remaining space (if present) and so provide multiple values. 207 Place all fixed size values at the start of the option, and any 208 variable/indeterminate sized value at the tail end of the option. 210 This means that implementations will likely be able to reuse code 211 paths designed to support the other options. 213 There is a tradeoff between the adoptability of previously defined 214 option formats, and the advantages that new or specialized formats 215 can provide. In general, it is usually preferable to reuse 216 previously used option formats. 218 However, it isn't very practical to consider the bulk of DHCPv6 219 options already allocated, and consider which of those solve a 220 similar problem. So, the following list of common option format data 221 elements is provided as a shorthand. Please note that it is not 222 complete in terms of exampling every option format ever devised. 224 If more complex options are needed, those basic formats mentioned 225 here may be considered privimites (or 'fragment types') that can be 226 used to build more complex formats. It should be noted that it is 227 often easier to implement two options with trivial formats than one 228 option with more complex format. That is not unconditional 229 requirement though. In some cases splitting one complex option into 230 two or more simple options introduces inter-option dependencies that 231 should be avoided. In such a case, it is usually better to keep one 232 complex option. 234 5.1. Option with IPv6 addresses 236 This option format is used to carry one or many IPv6 addresses. In 237 some cases the number of allowed address is limited (e.g. to one): 239 0 1 2 3 240 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 241 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 242 | option-code | option-len | 243 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 244 | | 245 | ipv6-address | 246 | | 247 | | 248 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 249 | | 250 | ipv6-address | 251 | | 252 | | 253 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 254 | ... | 255 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 257 Figure 1: Option with IPv6 address 259 Examples of use: 261 o DHCPv6 server unicast address (a single address only) [RFC3315] 263 o SIP Servers IPv6 Address List [RFC3319] 265 o DNS Recursive Name Server [RFC3646] 267 o NIS Servers [RFC3898] 269 o SNTP Servers [RFC4075] 271 o Broadcast and Multicast Service Controller IPv6 Address Option for 272 DHCPv6 [RFC4280] 274 o MIPv6 Home Agent Address [RFC6610] (a single address only) 276 o NTP server [RFC5908] (a single address only) 278 o NTP Multicast address [RFC5908] (a single address only) 280 5.2. Option with a single flag (boolean) 282 Sometimes it is useful to convey a single flag that can either take 283 on or off values. Instead of specifying an option with one bit of 284 usable data and 7 bits of padding, it is better to define an option 285 without any content. It is the presence or absence of the option 286 that conveys the value. This approach has the additional benefit of 287 absent option designating the default, i.e. administrator has to take 288 explicit actions to deploy the opposite of the default value. 290 0 1 2 3 291 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 292 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 293 | option-code | option-len | 294 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 296 Figure 2: Option for conveying boolean 298 Examples of use: 300 o DHCPv6 rapid-commit [RFC3315] 302 5.3. Option with IPv6 prefix 304 Sometimes there is a need to convey an IPv6 prefix. The information 305 to be carried by such an option includes the 128-bit IPv6 prefix 306 together with a length of this prefix taking values from 0 to 128. 307 Using the simplest approach, the option could convey this data in two 308 fixed length fields: one carrying prefix length, another carrying the 309 prefix. However, in many cases /64 or shorter prefixes are used. 310 This implies that the large part of the prefix data carried by the 311 option would have its bits set to zero and would be unused. In order 312 to avoid carrying unused data, it is recommended to store prefix in 313 the variable length data field. The appropriate option format is 314 defined as follows: 316 0 1 2 3 317 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 318 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 319 | option-code | option-length | 320 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 321 | prefix6-len | ipv6-prefix | 322 +-+-+-+-+-+-+-+-+ (variable length) | 323 . . 324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 326 Figure 3: Option with IPv6 Prefix 328 option-length is set to 1 + length of the IPv6 prefix. 330 prefix6-len is one octet long and specifies the length in bits of the 331 IPv6 prefix. Typically allowed values are 0 to 128. 333 ipv6-prefix field is a variable length field that specifies the IPv6 334 prefix. The length is (prefix6-len + 7) / 8. This field is padded 335 with zero bits up to the nearest octet boundary when prefix6-len is 336 not divisible by 8. 338 Examples of use: 340 o Default Mapping Rule [I-D.ietf-softwire-map-dhcp] 342 For example, the prefix 2001:db8::/60 would be encoded with an 343 option-length of 9, prefix6-len would be set to 60, the ipv6-prefix 344 would be 8 octets and would contain octets 20 01 0d b8 00 00 00 00. 346 It should be noted that the IAPREFIX option defined by [RFC3633] uses 347 a full length 16-octet prefix field. The concern about option length 348 was not well understood at the time of its publication. 350 5.4. Option with 32-bit integer value 352 This option format can be used to carry 32 bit-signed or unsigned 353 integer value: 355 0 1 2 3 356 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 357 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 358 | option-code | option-len | 359 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 360 | 32-bit-integer | 361 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 363 Figure 4: Option with 32-bit-integer value 365 Examples of use: 367 o Information Refresh Time [RFC4242] 369 5.5. Option with 16-bit integer value 371 This option format can be used to carry 16-bit signed or unsigned 372 integer values: 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 | 16-bit-integer | 380 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 382 Figure 5: Option with 16-bit integer value 384 Examples of use: 386 o Elapsed Time [RFC3315] 388 5.6. Option with 8-bit integer value 390 This option format can be used to carry 8-bit integer values: 392 0 1 2 3 393 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 394 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 395 | option-code | option-len | 396 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 397 | 8-bit-integer | 398 +-+-+-+-+-+-+-+-+ 400 Figure 6: Option with 8-bit integer value 402 Examples of use: 404 o DHCPv6 Preference [RFC3315] 406 5.7. Option with URI 408 A Uniform Resource Identifier (URI) [RFC3986] is a compact sequence 409 of characters that identifies an abstract or physical resource. The 410 term "Uniform Resource Locator" (URL) refers to the subset of URIs 411 that, in addition to identifying a resource, provide a means of 412 locating the resource by describing its primary access mechanism 413 (e.g., its network "location"). This option format can be used to 414 carry a single URI: 416 0 1 2 3 417 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 418 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 419 | option-code | option-len | 420 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 421 . URI (variable length) . 422 | ... | 423 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 425 Figure 7: Option with URI 427 Examples of use: 429 o Boot File URL [RFC5970] 430 An alternate encoding to support multiple URIs is available. An 431 option must be defined to use either the single URI format above or 432 the multiple URL format below depending on whether a single is always 433 sufficient or if multiple URLs are possible. 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 . . 441 . uri-data . 442 . . . . . 443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 445 Figure 8: Option with multiple URIs 447 Each instance of the uri-data is formatted as follows: 449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 450 | uri-len | URI | 451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 453 The uri-len is two octets long and specifies the length of the uri 454 data. 456 5.8. Option with Text String 458 A text string is a sequence of characters that have no semantics. 459 The encoding (such as 7-bit ASCII, NVT-ASCII, UTF-8) of the text 460 string MUST be specified. If a data format has semantics other than 461 just being text, it is not a string. E.g., a FQDN is not a string, 462 and a URI is also not a string, because they have different 463 semantics. A string must not enclude any terminator (such as a null 464 byte). This option format can be used to carry a text string: 466 0 1 2 3 467 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 468 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 469 | option-code | option-len | 470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 471 . String . 472 | ... | 473 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 475 Figure 9: Option with text string 477 Examples of use: 479 o Timezone Options for DHCPv6 [RFC4833] 481 An alternate encoding to support multiple text strings is available. 482 An option must be defined to use either the single text string format 483 above or the multiple text string format below depending on whether a 484 single is always sufficient or if multiple text strings are possible. 486 0 1 2 3 487 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 488 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 489 | option-code | option-len | 490 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 491 . . 492 . text-data . 493 . . . . . 494 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 496 Figure 10: Option with multiple text strings 498 Each instance of the text-data is formatted as follows: 500 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 501 | text-len | String | 502 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ 504 The text-len is two octets long and specifies the length of the 505 string. 507 5.9. Option with variable length data 509 This option can be used to carry variable length data of any kind. 510 Internal representation of carried data is option specific. Whenever 511 this format is used by the new option being defined, the data 512 encoding should be documented. 514 This option format provides a lot of flexibility to pass data of 515 almost any kind. Though, whenever possible it is highly recommended 516 to use more specialized options, with field types better matching 517 carried data types. 519 0 1 2 3 520 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 521 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 522 | option-code | option-len | 523 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 524 . . 525 . variable length data . 526 . . 527 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 529 Figure 11: Option with variable length data 531 Examples of use: 533 o Client Identifier [RFC3315] 535 o Server Identifier [RFC3315] 537 5.10. Option with DNS Wire Format Domain Name List 539 This option is used to carry 'domain search' lists or any host or 540 domain name. It uses the same format as described in Section 5.9, 541 but with the special data encoding, described in section 8 of 542 [RFC3315]. This data encoding supports carrying multiple instances 543 of hosts or domain names in a single option, by terminating each 544 instance with the byte value of 0. 546 0 1 2 3 547 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 548 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 549 | option-code | option-length | 550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 551 | DNS Wire Format Domain Name List | 552 | ... | 553 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 555 Figure 12: Option with DNS Wire Format Domain Name List 557 Examples of use: 559 o SIP Servers Domain Name List [RFC3319] (many domains) 561 o NIS Domain Name (many domains) [RFC3898] (many domains) 563 o DS-Lite AFTR location [RFC6334] (a single FQDN) 565 o Home Network Identifier [RFC6610] (a single FQDN) 567 o Home Agent FQDN [RFC6610] (a single FQDN) 569 6. Avoid Conditional Formatting 570 Placing an octet at the start of the option which informs the 571 software how to process the remaining octets of the option may appear 572 simple to the casual observer. But the only conditional formatting 573 methods that are in widespread use today are 'protocol' class 574 options. Therefore conditional formatting requires new code to be 575 written and complicates future interoperability should new 576 conditional formats be added; and existing code has to ignore 577 conditional format that it does not support. 579 7. Avoid Aliasing 581 Options are said to be aliases of each other if they provide input to 582 the same configuration parameter. A commonly proposed example is to 583 configure the location of some new service ("my foo server") using a 584 binary IP address, a domain name field, and an URL. This kind of 585 aliasing is undesirable, and is not recommended. 587 In this case, where three different formats are supposed, it more 588 than triples the work of the software involved, requiring support for 589 not merely one format, but support to produce and digest all three. 590 Furthermore, code development and testing must cover all possible 591 combinations of defined formats. Since clients cannot predict what 592 values the server will provide, they must request all formats. So in 593 the case where the server is configured with all formats, DHCPv6 594 message bandwidth is wasted on option contents that are redundant. 595 Also, the DHCPv6 option space is wasted, as three new option codes 596 are required, rather than one. 598 It also becomes unclear which types of values are mandatory, and how 599 configuring some of the options may influence the others. For 600 example, if an operator configures the URL only, should the server 601 synthesize a domain name and IP address? 603 A single configuration value on a host is probably presented to the 604 operator (or other software on the machine) in a single field or 605 channel. If that channel has a natural format, then any alternative 606 formats merely make more work for intervening software in providing 607 conversions. 609 So the best advice is to choose the one method that best fulfills the 610 requirements, be that for simplicity (such as with an IP address and 611 port pair), late binding (such as with DNS), or completeness (such as 612 with a URL). 614 8. Choosing between FQDN and address 616 Some parameters may be specified as FQDN or an address. It is not 617 allowed to define both option types at the same time (see section 618 Section 7), so one of them must be chosen. This section is intended 619 to help make an informed decision in that regard. 621 On the specific subject of desiring to configure a value using a FQDN 622 instead of a binary IP address, note that most DHCPv6 server 623 implementations will happily accept a Domain Name entered by the 624 administrator, and use DNS resolution to render binary IP addresses 625 in DHCPv6 replies to clients. Consequently, consider the extra 626 packet overhead incurred on the client's end to perform DNS 627 resolution itself. The client may be operating on a battery and 628 packet transmission is a non-trivial use of power, and the extra RTT 629 delays the client must endure before the service is configured are at 630 least two factors to consider in making a decision on format. 632 Unless there are specific reasons to do otherwise, address should be 633 used. It is simpler to use, its validation is trivial (length of 16 634 constitutes a valid option), is explicit and does not allow any 635 ambiguity. It is faster (does not require extra resolution efforts), 636 so it is more efficient, which can be especially important for energy 637 restricted devices. 639 FQDN options are discouraged for options intended to configure hosts, 640 because hosts may have multiple provisioning domains (see 641 Section 12), and may get a different answer from the DNS depending on 642 the provisioning domain. This is particularly a problem when the 643 normal expected use of the option makes sense with private DNS 644 zone(s), as might be the case with a corporate VPN. 646 FQDN does require a resolution into an actual address. This implies 647 the question when the FQDN resolution should be taken. There are a 648 couple of possible answers: a) by the server, when it is started, b) 649 by the server, when it is about to send an option, c) by the client, 650 immediately after receiving an option, d) by the client, when the 651 content of the option is actually consumed. For a), b) and possibly 652 c), the option should really convey an address, not FQDN. The only 653 real incentive to use FQDN is case d). It is the only case that 654 allows possible changes in the DNS to be picked up by clients. 656 FQDN imposes a number of additional failure modes and issues that 657 should be dealt with: 659 1. The client must have a knowledge about available DNS servers. 660 That typically means that option DNS_SERVERS is mandatory. This 661 should be mentioned in the draft that defines new option. It is 662 possible that the server will return FQDN option, but not the DNS 663 Servers option. There should be a brief discussion about it; 665 2. The DNS may not be reachable; 666 3. DNS may be available, but may not have appropriate information 667 (e.g. no AAAA records for specified FQDN); 669 4. Address family must be specified (A, AAAA or any); 671 5. What should the client do if there are multiple records available 672 (use only the first one, use all, use one and switch to the 673 second if the first fails for whatever reason, etc.); 675 6. Multi-homed devices may be connected to different administrative 676 domains with each domain providing different information in DNS 677 (e.g. an enterprise network exposing private domains). Client 678 may send DNS queries to a different DNS server; 680 7. It should be mentioned if Internationalized Domain Names are 681 allowed. If they are, what kind of DNS option encoding should be 682 specified. 684 9. Encapsulated options in DHCPv6 686 Most options are conveyed in a DHCPv6 message directly. Although 687 there is no codified normative language for such options, they are 688 often referred to as top-level options. Many options may include 689 other options. Such inner options are often referred to as 690 encapsulated or nested options. Those options are sometimes called 691 sub-options, but this term actually means something else, and 692 therefore should never be used to describe encapsulated options. It 693 is recommended to use term "encapsulated" as this terminology is used 694 in [RFC3315]. The difference between encapsulated and sub-options 695 are that the former uses normal DHCPv6 option space codes, while the 696 latter uses option space specific to a given parent option. It 697 should be noted that, contrary to DHCPv4, there is no shortage of 698 option numbers. Therefore almost all options share a common option 699 space. For example option type 1 meant different things in DHCPv4, 700 depending if it was located in top-level or inside of Relay Agent 701 Information option. There is no such ambiguity in DHCPv6 (with the 702 unfortunate exception of [RFC5908], which never got proper review 703 from the DHC working group and contains many errors, and should not 704 under any circumstances be used as a template for future DHCP option 705 definitions). 707 From the implementation perspective, it is easier to implement 708 encapsulated options rather than sub-options, as the implementers do 709 not have to deal with separate option spaces and can use the same 710 buffer parser in several places throughout the code. 712 Such encapsulation is not limited to one level. There is at least 713 one defined option that is encapsulated twice: Identity Association 714 for Prefix Delegation (IA_PD, defined in [RFC3633], section 9) 715 conveys IA Prefix (IAPREFIX, defined in [RFC3633], section 10). Such 716 delegated prefix may contain an excluded prefix range that is 717 represented by PD_EXCLUDE option that is conveyed as encapsulated 718 inside IAPREFIX (PD_EXCLUDE, defined in [RFC6603]). It seems awkward 719 to refer to such options as sub-sub-option or doubly encapsulated 720 option, therefore "encapsulated option" term is typically used, 721 regardless of the nesting level. 723 When defining configuration means for more complex mechanisms, it may 724 be tempting to simply use sub-options. That should be avoided, as it 725 increases complexity of the parser. It is much easier, faster and 726 less error prone to parse a larger number of options on a single 727 (top-level) scope, than parse options on several scopes. The use of 728 sub-options should be avoided as much as possible, but it is better 729 to use sub-options rather than conditional formatting. 731 It should be noted that currently there is no clear way defined for 732 requesting sub-options. Most known implementations are simply using 733 top-level ORO for requesting both top-level options and encapsulated 734 options. 736 10. Additional States Considered Harmful 738 DHCP is a protocol designed for provisioning clients. Less 739 experienced protocol designers often assume that it is easy to define 740 an option that will convey a different parameter for each client in a 741 network. Such problems arose during designs of MAP 742 [I-D.ietf-softwire-map-dhcp] and 4rd [I-D.ietf-softwire-4rd]. While 743 it would be easier for provisioned clients to get ready to use per 744 client option values, such requirement puts exceedingly large loads 745 on the server side. The new extensions may introduce new 746 implementation complexity and additional database state on the 747 server. Alternatives should be considered, if possible. As an 748 example, [I-D.ietf-softwire-map-dhcp] was designed in a way that all 749 clients are provisioned with the same set of MAP options and each 750 provisioned client uses its unique address and delegated prefix to 751 generate client-specific information. Such a solution does not 752 introduce any additional state for the server and therefore scales 753 better. 755 It also should be noted that contrary to DHCPv4, DHCPv6 keeps several 756 timers for renewals. Each IA_NA (addresses) and IA_PD (prefixes) 757 contains T1 and T2 timers that designate time after which client will 758 initiate renewal. Those timers apply only to its own IA containers. 759 Refreshing other parameters should be initiated after a time 760 specified in the Information Refresh Time Option (defined in 761 [RFC4242]), carried in the Reply message and returned in response to 762 Information-Request message. Introducing additional timers make 763 deployment unnecessarily complex and SHOULD be avoided. 765 11. Configuration changes occur at fixed times 767 In general, DHCPv6 clients only refresh configuration data from the 768 DHCP server when the T1 timer expires. Although there is a 769 RECONFIGURE mechanism that allows a DHCP server to request that 770 clients initiate reconfiguration, support for this mechanism is 771 optional and cannot be relied upon. 773 Even when DHCP clients refresh their configuration information, not 774 all consumers of DHCP-sourced configuration data notice these 775 changes. For instance, if a server is started using parameters 776 received in an early DHCP transaction, but does not check for updates 777 from DHCP, it may well continue to use the same parameter 778 indefinitely. Modern notification systems take care of reconfiguring 779 services when the client moves to a new network, but it's worth 780 bearing in mind that a renew may not actually result in the client 781 taking up new configuration information that it receives. 783 In light of the above, when designing an option you should take into 784 consideration the fact that your option may hold stale data that will 785 only be updated at an arbitrary time in the future. 787 12. Multiple provisioning domains 789 In some cases there could be more than one DHCPv6 server on a link, 790 with each provisioning a different set of parameters. One notable 791 example of such a case is a home network with a connection to two 792 independent ISPs. 794 DHCPv6 was not initially designed with multiple provisioning domains. 795 Although [RFC3315] states that a client that receives more than one 796 ADVERTISE message, may respond to one or more of them, such 797 capability was never observed in any known implementations. Existing 798 clients will pick one server and will continue configuration process 799 with that server, ignoring all other servers. 801 This is a generic DHCP protocol issue and should not be dealt within 802 each option separately. This issue is better dealt with using a 803 protocol-level solution and fixing this problem should not be 804 attempted on a per option basis. 806 13. Chartering Requirements and Advice for Responsible ADs 808 Adding a simple DHCP option is straightforward, and generally 809 something that any working group can do, perhaps with some help from 810 designated DHCP experts. However, when new fragment types need to be 811 devised, this requires the attention of DHCP experts, and should not 812 be done in a working group that doesn't have a quorum of such 813 experts. This is true whether the new fragment type has the same 814 structure as an existing fragment type, but has different semantics. 815 It is equally true when the new format has a new structure. 817 Responsible Area Directors for working groups that wish to add a work 818 item to a working group charter to define a new DHCP option should 819 get clarity from the working group as to whether the new option is a 820 simple DHCP option with no new fragment type or new fragment 821 semantics, or whether it in fact will require new fragment types. A 822 working group charter item should explicitly state which of these two 823 types is required; if it is not known at the time of chartering, the 824 charter should state that the working group will study the question 825 and recharter or seek help elsewhere if a new fragment type is to be 826 defined. 828 If a working group needs a new fragment type, it is preferable to 829 seek out a working group whose members already have sufficient 830 expertise to evaluate the new work and try to come up with a new 831 format that generalizes well and can be reused, rather than a single- 832 use fragment type. If such a working group is available, the work 833 should be chartered in that working group as a separate draft that 834 documents the new fragment type. The working group that needs the 835 new fragment type can then define their new option referencing the 836 new fragment type document. This work can generally be done in 837 parallel so as not to delay the process significantly. 839 In the event that there is no working group with DHCP expertise that 840 can define the new fragment type, the responsible AD should seek out 841 help from known DHCP experts within the IETF to provide advice and 842 frequent early review as the working group defines the new fragment 843 type. The new fragment type should still be done in a separate 844 document, even if it's done in the same working group, so as to 845 foster reuse of the new fragment type. The responsible AD should 846 work with the working group chairs and designated DHCP experts to 847 ensure that new fragment type document has in fact been carefully 848 reviewed by the experts and appears satisfactory. 850 Responsible area directors for working groups that are considering 851 defining options that actually update the DHCP protocol, as opposed 852 to simple options, should go through a process similar to that 853 described above when trying to determine where to do the work. Under 854 no circumstances should a working group be given a charter 855 deliverable to define a new DHCP option, and then on the basis of 856 that charter item actually make updates to the DHCP protocol. 858 14. Considerations for Creating New Formats 860 When defining new options, one specific consideration to evaluate is 861 whether or not options of a similar format would need to have 862 multiple or single values encoded (whatever differs from the current 863 option), and how that might be accomplished in a similar format. 865 When defining a new option, it is best to synthesize the option 866 format using fragment types already in use. However, in some cases 867 there may be no fragment type that accomplishes the intended purpose. 869 The matter of size considerations and option order are further 870 discussed in Section 15 and Section 17. 872 15. Option Size 874 DHCPv6 [RFC3315] allows for packet sizes up to 64KB. First, through 875 its use of link-local addresses, it avoids many of the deployment 876 problems that plague DHCPv4, and is actually an UDP over IPv6 based 877 protocol (compared to DHCPv4, which is mostly UDP over IPv4 protocol, 878 but with layer 2 hacks). Second, RFC 3315 explicitly refers readers 879 to RFC 2460 Section 5, which describes an MTU of 1280 octets and a 880 minimum fragment reassembly of 1500 octets. It's feasible to suggest 881 that DHCPv6 is capable of having larger options deployed over it, and 882 at least no common upper limit is yet known to have been encoded by 883 its implementors. It is impossible to describe any fixed limit that 884 cleanly divides those too big from the workable. 886 It is advantageous to prefer option formats which contain the desired 887 information in the smallest form factor that satisfies the 888 requirements. Common sense still applies here. It is better to 889 split distinct values into separate octets rather than propose overly 890 complex bit shifting operations to save several bits (or even an 891 octet or two) that would be padded to the next octet boundary anyway. 893 DHCPv6 does allow for multiple instances of a given option, and they 894 are treated as distinct values following the defined format, however 895 this feature is generally preferred to be restricted to protocol 896 class features (such as the IA_* series of options). In such cases, 897 it is better to define an option as an array if it is possible. It 898 is recommended to clarify (with normative language) whether a given 899 DHCPv6 option may appear once or multiple times. The default 900 assumption is only once. 902 Relay agents have to do fragment reassembly and fragmentation on 903 transmission. So while fragmentation is allowed, if a new option 904 results in significant fragmentation, it probably isn't a good choice 905 for DHCP configuration; instead DHCP should simply point to a URI 906 where the configuration information can be obtained. 908 16. Singleton options 910 Although [RFC3315] states that each option type MAY appear more than 911 once, the original idea was that multiple instances are reserved for 912 stateful options, like IA_NA or IA_PD. For most other options it is 913 usually expected that they will appear at most once. Such options 914 are called singleton options. Sadly, it is often not clearly 915 specified in RFCs that were published up to this date whether only 916 one or more option instances are allowed. Documents that define new 917 defined options SHOULD state whether new options are singletons or 918 not. Unless otherwise specified, new defined options are singletons. 920 When deciding whether a single or multiple option instances are 921 allowed in a message, take into consideration how the content of the 922 option will be used. Depending on the service being configured it 923 may or may not make sense to have multiple values configured. If 924 multiple values make sense, it is better to explicitly allow that by 925 using option format that allows multiple values within one option 926 instance. 928 Allowing multiple option instances often leads to confusion. 929 Consider the following example. Basic DS-Lite architecture assumes 930 that the B4 element (DHCPv6 client) will receive AFTR option and 931 establish a single tunnel to configured tunnel termination point 932 (AFTR). During standardization process of [RFC6334] there was a 933 discussion whether multiple instances of DS-Lite tunnel option should 934 be allowed. This created an unfounded expectation that the clients 935 receiving multiple instances of the option will somehow know when one 936 tunnel endpoint goes off-line and do some sort of failover between 937 other values provided in other instances of the AFTR option. Others 938 assumed that if there are multiple options, the client will somehow 939 do a load balancing between provided tunnel endpoints. Neither 940 failover nor load balancing was defined for DS-Lite architecture, so 941 it caused confusion. It was eventually decided to allow only one 942 instance of the AFTR option. 944 17. Option Order 945 Option order, either the order among many DHCPv6 options or the order 946 of multiple instances of the same option, SHOULD NOT be significant 947 and MUST NOT be assumed. An exception may be security relevant 948 options, which are often created last and put at the last position, 949 or whose location indicates the protected range. 951 As there is no explicit order for multiple instance of the same 952 option, an option definition SHOULD instead restrict the order within 953 the option by using a list of items rather than a single item. 955 18. Relay Options 957 In DHCPv4, all relay options are organized as sub-options within DHCP 958 Relay Agent Information Option[RFC3046]. And an independent number 959 space called "DHCP Relay Agent Sub-options" is maintained by IANA. 960 Different from DHCPv4, in DHCPv6, Relay options are defined in the 961 same way as client/server options, and they too use the same number 962 space as client/server options. Future DHCPv6 Relay options MUST be 963 allocated from this single DHCPv6 Option code space. 965 However, the Relay-Supplied Options Option [RFC6422] may also contain 966 some DHCPv6 options as permitted, such as the EAP Re-authentication 967 Protocol (ERP) Local Domain Name DHCPv6 Option [RFC6440]. 969 19. Clients Request their Options 971 The DHCPv6 Option Request Option (OPTION_ORO) [RFC3315], is an option 972 that serves two purposes - to inform the server what options the 973 client supports and to inform what options the client is willing to 974 consume. 976 It doesn't make sense for some options to be requested using Option 977 Request Option, such as those formed by elements of the protocol's 978 internal workings, or are formed on either end by DHCPv6-level 979 software engaged in some exchange of information. When in doubt, it 980 is prudent to assume that any new option must be present on the 981 relevant option request list if the client desires to receive it. 983 It is tempting to add text that requires the client to include a new 984 option in Option Request Option list, similar to this text: "Clients 985 MUST place the foo option code on the Option Request Option list, 986 clients MAY include option foo in their packets as hints for the 987 server as values the desire, and servers MUST include option foo when 988 the client requested it (and the server has been so configured)". 989 Such text is discouraged as there are several issues with it. First, 990 it assumes that client implementation that supports a given option 991 will always want to use it. This is not true. The second and more 992 important reason is that such text essentially duplicates mechanism 993 already defined in [RFC3315]. It is better to simply refer to the 994 existing mechanism rather than define it again. See Section 21 for 995 proposed examples on how to do that. 997 Creators of DHCPv6 options should not require special ordering of 998 options either in the relevant request option, or in the order of 999 options within the packet. Although it is reasonable to expect that 1000 options will be processed in the order they appear in ORO, server 1001 software is not required to sort DHCPv6 options into the same order 1002 in reply messages. 1004 It should also be noted that options values are never aligned within 1005 the DHCP packet, even the option code and option length may appear on 1006 odd byte boundaries. 1008 20. Transition Technologies 1010 Transition from IPv4 to IPv6 is progressing. Many transition 1011 technologies are proposed to speed it up. As a natural consequence 1012 there are also DHCP options proposed to provision those proposals. 1013 The inevitable question is whether the required parameters should be 1014 delivered over DHCPv4 or DHCPv6. Authors often don't give much 1015 thought about it and simply pick DHCPv6 without realizing the 1016 consequences. IPv6 is expected to stay with us for many decades, and 1017 so is DHCPv6. There is no mechanism available to deprecate an option 1018 in DHCPv6, so any options defined will stay with us as long as DHCPv6 1019 protocol itself. It seems likely that such options defined to 1020 transition from IPv4 will outlive IPv4 by many decades. From that 1021 perspective it is better to implement provisioning of the transition 1022 technologies in DHCPv4, which will be obsoleted together with IPv4. 1024 When the network infrastructure becomes IPv6-only, the support for 1025 IPv4-only nodes may still be needed. In this scenario, provisioning 1026 IPv4 configuration over IPv6-only networks 1027 [I-D.ietf-dhc-v4configuration] may be needed. 1029 21. Recommended sections in the new document 1031 There are three major entities in DHCPv6 protocol: server, relay 1032 agent, and client. It is very helpful for implementers to include 1033 separate sections that describe operation for those three major 1034 entities. Even when a given entity does not participate, it is 1035 useful to have a very short section stating that it must not send a 1036 given option and must ignore it when received. 1038 There is also a separate entity called requestor, which is a special 1039 client-like type that participates in leasequery protocol [RFC5007] 1040 and [RFC5460]. A similar section for the requestor is not required, 1041 unless the new option has anything to do with requestor (or it is 1042 likely that the reader may think that is has). It should be noted 1043 that while in the majority of deployments, requestor is co-located 1044 with relay agent, those are two separate entities from the protocol 1045 perspective and they may be used separately. There are stand-alone 1046 requestor implementations available. 1048 The following sections include proposed text for such sections. That 1049 text is not required to appear, but it is appropriate in most cases. 1050 Additional or modified text specific to a given option is often 1051 required. 1053 Although requestor is somewhat uncommon functionality, its existence 1054 should be noted, especially when allowing or disallowing options to 1055 appear in certain message or being sent by certain entities. 1056 Additional message types may appear in the future, besides types 1057 defined in [RFC3315]. Therefore authors are encouraged to 1058 familiarize themselves with a list of currently defined DHCPv6 1059 messages available on IANA website [iana]. 1061 Typically new options are requested by clients and assigned by the 1062 server, so there is no specific relay behavior. Nevertheless it is 1063 good to include a section for relay agent behavior and simply state 1064 that there are no additional requirements for relays. The same 1065 applies for client behavior if the options are to be exchanged 1066 between relay and server. 1068 Sections that contain option definitions MUST include formal 1069 verification procedure. Often it is very simple, e.g. option that 1070 conveys IPv6 address must be exactly 16 bytes long, but sometimes the 1071 rules are more complex. It is recommeded to refer to existing 1072 documents (e.g. section 8 of RFC3315 for domain name encoding) rather 1073 than trying to repeat such rules. 1075 21.1. DHCPv6 Client Behavior Text 1077 Clients MAY request option foo, as defined in [RFC3315], sections 1078 17.1.1, 18.1.1, 18.1.3, 18.1.4, 18.1.5 and 22.7. As a convenience to 1079 the reader, we mention here that the client includes requested option 1080 codes in Option Request Option. 1082 Optional text (if client's hints make sense): Client also MAY include 1083 option foo in its SOLICIT, REQUEST, RENEW, REBIND and INFORMATION- 1084 REQUEST messages as a hint for the server regarding preferred option 1085 values. 1087 Optional text (if the option contains FQDN): If the client requests 1088 an option that conveys an FQDN, it is expected that the contents of 1089 that option will be resolved using DNS. Hence the following text may 1090 be useful: Clients that request option foo SHOULD also request option 1091 OPTION_DNS_SERVERS specified in [RFC3646]. 1093 Clients MUST discard option foo if it is invalid (i.e. did not pass 1094 validation steps defined in Section X.Y). 1096 Optional text (if option foo in expected to be exchanged between 1097 relays and servers): Option foo is exchanged between relays and 1098 servers only. Clients are not aware of the usage of option foo. 1099 Clients MUST ignore received option foo. 1101 21.2. DHCPv6 Server Behavior Text 1103 Sections 17.2.2 and 18.2 of [RFC3315] govern server operation in 1104 regards to option assignment. As a convenience to the reader, we 1105 mention here that the server will send option foo only if configured 1106 with specific values for foo and the client requested it. 1108 Optional text: Option foo is a singleton. Servers MUST NOT send more 1109 than one instance of foo option. 1111 Optional text (if server is never supposed to receive option foo): 1112 Servers MUST ignore incoming foo option. 1114 21.3. DHCPv6 Relay Agent Behavior Text 1116 It's never appropriate for a relay agent to add options to a message 1117 heading toward the client, and relay agents don't actually construct 1118 Relay-Reply messages anyway. 1120 Optional text (if foo option is exchanged between clients and server 1121 or between requestors and servers): There are no additional 1122 requirements for relays. 1124 Optional text (if relays are expected to insert or consume option 1125 foo): Relay agents MAY include option foo in a Relay-Forw when 1126 forwarding packets from clients to the servers. 1128 22. Should the new document update existing RFCs? 1130 Authors often ask themselves a question whether their proposal 1131 updates exist RFCs, especially 3315. In April 2013 there were about 1132 80 options defined. Had all documents that defined them also updated 1133 RFC3315, comprehension of such a document set would be extremely 1134 difficult. It should be noted that "extends" and "updates" are two 1135 very different verbs. If a new draft defines a new option that 1136 clients request and servers provide, it merely extends current 1137 standards, so "updates 3315" is not required in the new document 1138 header. On the other hand, if a new document replaces or modifies 1139 existing behavior, it should be noted that it updates the other 1140 document. For example, [RFC6644] clearly updates [RFC3315] as it 1141 replaces existing with new text. 1143 23. Security Considerations 1145 DHCPv6 does have an Authentication mechanism ([RFC3315]) that makes 1146 it possible for DHCPv6 software to discriminate between authentic 1147 endpoints and man-in-the-middle. Other authentication mechanisms may 1148 optionally be deployed. 1150 So, while creating a new option, it is prudent to assume that the 1151 DHCPv6 packet contents are always transmitted in the clear, and 1152 actual production use of the software will probably be vulnerable at 1153 least to man-in-the-middle attacks from within the network, even 1154 where the network itself is protected from external attacks by 1155 firewalls. In particular, some DHCPv6 message exchanges are 1156 transmitted to multicast addresses that are likely broadcast anyway. 1158 If an option is of a specific fixed length, it is useful to remind 1159 the implementer of the option data's full length. This is easily 1160 done by declaring the specific value of the 'length' tag of the 1161 option. This helps to gently remind implementers to validate option 1162 length before digesting them into likewise fixed length regions of 1163 memory or stack. 1165 If an option may be of variable size (such as having indeterminate 1166 length fields, such as domain names or text strings), it is advisable 1167 to explicitly remind the implementor to be aware of the potential for 1168 long options. Either define a reasonable upper limit (and suggest 1169 validating it), or explicitly remind the implementor that an option 1170 may be exceptionally long (to be prepared to handle errors rather 1171 than truncate values). 1173 For some option contents, out of bound values may be used to breach 1174 security. An IP address field might be made to carry a loopback 1175 address, or local multicast address, and depending on the protocol 1176 this may lead to undesirable results. A domain name field may be 1177 filled with contrived contents that exceed the limitations placed 1178 upon domain name formatting - as this value is possibly delivered to 1179 "internal configuration" records of the system, it may be implicitly 1180 trusted without being validated. 1182 Authors of drafts defining new DHCP options are therefore strongly 1183 advised to explicitly define validation measures that recipients of 1184 such options are required to do before processing such options. 1186 However, validation measures already defined by RFC3315 or other 1187 specifications referenced by the new option document are redundant, 1188 and can introduce errors, so authors are equally strongly advised to 1189 refer to the base specification for any such validation language 1190 rather than copying it into the new specification. 1192 24. IANA Considerations 1194 This document has no actions for IANA. 1196 25. Acknowledgements 1198 Authors would like to thank Simon Perreault, Bernie Volz, Ted Lemon, 1199 Bud Millwood and Ralph Droms for their comments. 1201 26. References 1203 26.1. Normative References 1205 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1206 Requirement Levels", BCP 14, RFC 2119, March 1997. 1208 [RFC3315] Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., 1209 and M. Carney, "Dynamic Host Configuration Protocol for 1210 IPv6 (DHCPv6)", RFC 3315, July 2003. 1212 26.2. Informative References 1214 [I-D.ietf-dhc-v4configuration] 1215 Rajtar, B. and I. Farrer, "Provisioning IPv4 Configuration 1216 Over IPv6 Only Networks", draft-ietf-dhc- 1217 v4configuration-01 (work in progress), May 2013. 1219 [I-D.ietf-softwire-4rd] 1220 Despres, R., Jiang, S., Penno, R., Lee, Y., Chen, G., and 1221 M. Chen, "IPv4 Residual Deployment via IPv6 - a Stateless 1222 Solution (4rd)", draft-ietf-softwire-4rd-06 (work in 1223 progress), July 2013. 1225 [I-D.ietf-softwire-map-dhcp] 1226 Mrugalski, T., Deng, X., Troan, O., Bao, C., Dec, W., and 1227 l. leaf.yeh.sdo@gmail.com, "DHCPv6 Options for 1228 configuration of Softwire Address and Port Mapped 1229 Clients", draft-ietf-softwire-map-dhcp-04 (work in 1230 progress), July 2013. 1232 [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC 1233 3046, January 2001. 1235 [RFC3319] Schulzrinne, H. and B. Volz, "Dynamic Host Configuration 1236 Protocol (DHCPv6) Options for Session Initiation Protocol 1237 (SIP) Servers", RFC 3319, July 2003. 1239 [RFC3633] Troan, O. and R. Droms, "IPv6 Prefix Options for Dynamic 1240 Host Configuration Protocol (DHCP) version 6", RFC 3633, 1241 December 2003. 1243 [RFC3646] Droms, R., "DNS Configuration options for Dynamic Host 1244 Configuration Protocol for IPv6 (DHCPv6)", RFC 3646, 1245 December 2003. 1247 [RFC3898] Kalusivalingam, V., "Network Information Service (NIS) 1248 Configuration Options for Dynamic Host Configuration 1249 Protocol for IPv6 (DHCPv6)", RFC 3898, October 2004. 1251 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1252 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1253 3986, January 2005. 1255 [RFC4075] Kalusivalingam, V., "Simple Network Time Protocol (SNTP) 1256 Configuration Option for DHCPv6", RFC 4075, May 2005. 1258 [RFC4242] Venaas, S., Chown, T., and B. Volz, "Information Refresh 1259 Time Option for Dynamic Host Configuration Protocol for 1260 IPv6 (DHCPv6)", RFC 4242, November 2005. 1262 [RFC4280] Chowdhury, K., Yegani, P., and L. Madour, "Dynamic Host 1263 Configuration Protocol (DHCP) Options for Broadcast and 1264 Multicast Control Servers", RFC 4280, November 2005. 1266 [RFC4704] Volz, B., "The Dynamic Host Configuration Protocol for 1267 IPv6 (DHCPv6) Client Fully Qualified Domain Name (FQDN) 1268 Option", RFC 4704, October 2006. 1270 [RFC4833] Lear, E. and P. Eggert, "Timezone Options for DHCP", RFC 1271 4833, April 2007. 1273 [RFC5007] Brzozowski, J., Kinnear, K., Volz, B., and S. Zeng, 1274 "DHCPv6 Leasequery", RFC 5007, September 2007. 1276 [RFC5460] Stapp, M., "DHCPv6 Bulk Leasequery", RFC 5460, February 1277 2009. 1279 [RFC5908] Gayraud, R. and B. Lourdelet, "Network Time Protocol (NTP) 1280 Server Option for DHCPv6", RFC 5908, June 2010. 1282 [RFC5970] Huth, T., Freimann, J., Zimmer, V., and D. Thaler, "DHCPv6 1283 Options for Network Boot", RFC 5970, September 2010. 1285 [RFC6334] Hankins, D. and T. Mrugalski, "Dynamic Host Configuration 1286 Protocol for IPv6 (DHCPv6) Option for Dual-Stack Lite", 1287 RFC 6334, August 2011. 1289 [RFC6422] Lemon, T. and Q. Wu, "Relay-Supplied DHCP Options", RFC 1290 6422, December 2011. 1292 [RFC6440] Zorn, G., Wu, Q., and Y. Wang, "The EAP Re-authentication 1293 Protocol (ERP) Local Domain Name DHCPv6 Option", RFC 6440, 1294 December 2011. 1296 [RFC6603] Korhonen, J., Savolainen, T., Krishnan, S., and O. Troan, 1297 "Prefix Exclude Option for DHCPv6-based Prefix 1298 Delegation", RFC 6603, May 2012. 1300 [RFC6610] Jang, H., Yegin, A., Chowdhury, K., Choi, J., and T. 1301 Lemon, "DHCP Options for Home Information Discovery in 1302 Mobile IPv6 (MIPv6)", RFC 6610, May 2012. 1304 [RFC6644] Evans, D., Droms, R., and S. Jiang, "Rebind Capability in 1305 DHCPv6 Reconfigure Messages", RFC 6644, July 2012. 1307 [iana] IANA, ., "DHCPv6 parameters (IANA webpage)", November 1308 2003, 1309 . 1311 Authors' Addresses 1313 David W. Hankins 1314 Google, Inc. 1315 1600 Amphitheatre Parkway 1316 Mountain View, CA 94043 1317 USA 1319 Email: dhankins@google.com 1321 Tomek Mrugalski 1322 Internet Systems Consortium, Inc. 1323 950 Charter Street 1324 Redwood City, CA 94063 1325 USA 1327 Phone: +1 650 423 1345 1328 Email: tomasz.mrugalski@gmail.com 1329 Marcin Siodelski 1330 950 Charter Street 1331 Redwood City, CA 94063 1332 USA 1334 Phone: +1 650 423 1431 1335 Email: msiodelski@gmail.com 1337 Sheng Jiang 1338 Huawei Technologies Co., Ltd 1339 Q14, Huawei Campus, No.156 Beiqing Road 1340 Hai-Dian District, Beijing, 100095 1341 P.R. China 1343 Email: jiangsheng@huawei.com 1345 Suresh Krishnan 1346 Ericsson 1347 8400 Blvd Decarie 1348 Town of Mount Royal, Quebec 1349 Canada 1351 Email: suresh.krishnan@ericsson.com