idnits 2.17.1 draft-ietf-nfsv4-versioning-01.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 == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 2, 2015) is 3221 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-41) exists of draft-ietf-nfsv4-minorversion2-38 == Outdated reference: A later version (-41) exists of draft-ietf-nfsv4-minorversion2-dot-x-38 -- Obsolete informational reference (is this intentional?): RFC 3530 (Obsoleted by RFC 7530) -- Obsolete informational reference (is this intentional?): RFC 5661 (Obsoleted by RFC 8881) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 D. Noveck 3 Internet-Draft HP 4 Intended status: Standards Track July 2, 2015 5 Expires: January 3, 2016 7 NFSv4 Version Management 8 draft-ietf-nfsv4-versioning-01 10 Abstract 12 This document describes the management of versioning within the NFSv4 13 family of protocols. It covers the creation of minor versions, the 14 addition of optional features to existing minor versions, and the 15 correction of flaws in features already published as Proposed 16 Standards. The rules relating to the construction of minor versions 17 and the interaction of minor version implementations that appear in 18 this document supersede the minor versioning rules in RFC5661. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 3, 2016. 37 Copyright Notice 39 Copyright (c) 2015 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Existing Minor Versions . . . . . . . . . . . . . . . . . 3 56 1.2. Updated NFSv4 Version Management Framework . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Consolidation of Version Management Rules . . . . . . . . . . 6 59 4. NFSv4 Protocol Changes . . . . . . . . . . . . . . . . . . . 7 60 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 7 61 4.1.1. XDR Extension in General . . . . . . . . . . . . . . 8 62 4.1.2. Particulars of XDR Extension within NFSv4 . . . . . . 9 63 4.1.3. Rules for XDR Extension within NFSv4 . . . . . . . . 9 64 4.2. Non-XDR Protocol Changes . . . . . . . . . . . . . . . . 10 65 4.2.1. Field Interpretation and Use . . . . . . . . . . . . 10 66 4.2.2. Behavioral Changes . . . . . . . . . . . . . . . . . 11 67 4.2.3. Rules for non-XDR changes . . . . . . . . . . . . . . 11 68 4.3. Specification of Associated Protocols . . . . . . . . . . 12 69 4.3.1. Associated Protocols via pNFS Mapping Types . . . . . 12 70 4.3.2. Additional Forms of Associated Protocols . . . . . . 13 71 5. Documentation Approach . . . . . . . . . . . . . . . . . . . 14 72 5.1. Indexing material . . . . . . . . . . . . . . . . . . . . 14 73 6. NFSv4 Features . . . . . . . . . . . . . . . . . . . . . . . 14 74 6.1. Rules for Feature Construction . . . . . . . . . . . . . 15 75 6.2. Feature Statuses . . . . . . . . . . . . . . . . . . . . 15 76 6.3. Feature Discovery . . . . . . . . . . . . . . . . . . . . 16 77 6.4. Feature Specification Documents . . . . . . . . . . . . . 16 78 6.5. Feature Incorporation . . . . . . . . . . . . . . . . . . 17 79 7. Extensions within Minor Versions . . . . . . . . . . . . . . 18 80 8. Adding Features to Extensible Minor Versions . . . . . . . . 18 81 8.1. Use of Feature Specification Documents . . . . . . . . . 18 82 8.2. Compatibility Issues . . . . . . . . . . . . . . . . . . 19 83 8.2.1. Compatibility Issues for Messages Sent to Servers . . 19 84 8.2.2. Compatibility Issues for Messages Sent to Clients . . 21 85 8.3. Additional Documents to be Produced . . . . . . . . . . . 22 86 8.3.1. Minor Version Indexing Document . . . . . . . . . . . 22 87 8.3.2. Consolidated XDR Document . . . . . . . . . . . . . . 22 88 8.3.3. XDR Assignment Document . . . . . . . . . . . . . . . 23 89 8.3.4. Transition of Documents to RFC's . . . . . . . . . . 24 90 8.4. Relationship Between Minor Versioning and Extensions 91 within a Minor Version . . . . . . . . . . . . . . . . . 24 92 9. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 25 93 9.1. Minor Version Construction . . . . . . . . . . . . . . . 25 94 9.2. Minor Version Interaction . . . . . . . . . . . . . . . . 26 95 9.2.1. Minor Version Identifier Transfer Issues . . . . . . 26 96 9.2.2. Minor Version Compatibility Issues . . . . . . . . . 26 98 9.3. Minor Version Documentation . . . . . . . . . . . . . . . 27 99 10. Correction of Existing Minor Versions and Features . . . . . 27 100 10.1. Documentation of XDR Changes . . . . . . . . . . . . . . 29 101 11. Security Considerations . . . . . . . . . . . . . . . . . . . 30 102 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 103 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 104 13.1. Normative References . . . . . . . . . . . . . . . . . . 31 105 13.2. Informative References . . . . . . . . . . . . . . . . . 31 106 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 32 108 1. Introduction 110 To address the requirement for an NFS protocol that can evolve as the 111 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 112 provides rules and a framework to allow for future changes via the 113 creation of new protocol versions and certain forms of modification 114 of existing versions. These version management rules allow changes 115 to be implemented in a way that maintains compatibility with existing 116 clients and servers. 118 1.1. Existing Minor Versions 120 Previously, all such changes had been part of new minor versions. 121 The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the 122 minor version being used by the client in making requests. The 123 CB_COMPOUND (see Section 15.2 of [RFC7530]) procedure specifies the 124 minor version being used by the server on callback requests. 126 Each existing minor version has been specified by one or more 127 standards track RFCs: 129 o Minor version 0 is specified by [RFC7530] with the XDR description 130 appearing in [RFC7531]. 132 o Minor version 1 is specified by [RFC5661]) with the XDR 133 description appearing in [RFC5662]. 135 o Minor version 2 is specified by [NFSv42] (in terms of changes from 136 [RFC5661]). The XDR description appears in [NFSv42-dot-x] 138 1.2. Updated NFSv4 Version Management Framework 140 A number of significant changes from previous version management 141 practices should be noted here: 143 o Creation of a new minor version is no longer the only way in which 144 protocol changes may be made. Many changes can be done within the 145 context of a single minor version. Creation of new minor versions 146 remains available to make other sorts of changes. 148 o Specification of future minor versions in the way that was done 149 for NFSv4.0 and NFSv4.1 (i.e. as a single document defining the 150 entire protocol) is no longer practical and should not be 151 attempted. All future minor versions will be documented by 152 specifying the differences between the minor version being 153 documented and the previous minor version. The documentation 154 framework discussed in Section 5 should be used. 156 This document starts by presenting the conceptual framework on which 157 NFSv4 versioning is built. 159 o First we discuss (in Section 4) the range of protocol changes that 160 NFSv4 versioning is to deal with. 162 o Then we discuss (in Section 6) how those changes are organized 163 into features. 165 Using this framework, we then look at the ways the NFSv4 protocol can 166 be changed. 168 o The addition of new features to existing minor versions is 169 discussed in Sections 7 and 8. 171 o New Minor versions can be constructed, as described in Section 9. 173 o Issues relating to the correction of protocol errors in existing 174 features and minor versions are discussed in Section 10. 176 2. Terminology 178 A basic familiarity with the NFSv4 terminology is assumed in this 179 document and the reader is pointed to [RFC7530]. 181 The word "feature" has been used inconsistently in previous 182 treatments of NFSv4 versioning. Sometimes it is used to indicate a 183 specific XDR extension, while at other times it has been used to 184 indicate a set of multiple such extensions which are either supported 185 or not supported together. 187 In this document, we use the word "feature" in the second sense, 188 while individual protocol extensions which are incorporated in a 189 feature are referred to as "protocol elements." The term "feature 190 elements" is similar but it differs in that it includes changes in 191 field interpretation and use (Section 4.2.1) and protocol behavior 192 (See Section 4.2.2). See Section 6 for more details. 194 We also need to introduce our vocabulary regarding specification of 195 features and minor versions. Given the ongoing shift to a finer- 196 grained documentation model, it is important to be clear here. 198 o The term "minor version definition document" denotes the principal 199 document defining a specific NFSv4 minor version. It may be in 200 the form of a complete protocol definition (e.g. [RFC7530], 201 [RFC5661]), a specification of changes relative to the previous 202 minor version (e.g. [NFSv42]), or in a document that specifies 203 the features to be included, either by referencing their 204 definition document normatively (see Section 9.3) or implicitly 205 (see Section 8). 207 o The term "minor version documentation" includes the minor version 208 definition document but also includes any corresponding XDR 209 definition documents if they are published separately (e.g. 210 [RFC7531], [RFC5662]), [NFSv42-dot-x]). Also included are 211 documents separately specifying features newly incorporated in the 212 minor version and the ancillary documents described in 213 Section 8.3. 215 o The term "feature definition document" denotes a document 216 describing a single feature or a set of closely related features. 218 As noted above, the keywords defined by [RFC2119] have special 219 meanings which this document intends to adhere to. However, due to 220 the nature of this document and some special circumstances, there are 221 some complexities to take note of: 223 o Where this document does not directly specify implementation 224 requirements, use of these capitalized term is often not 225 appropriate. Instead, what document writers need to do is stated 226 without these specialized terms. In any case, one should not 227 conclude that the normative character of this document is 228 compromised by this. 230 o In speaking of the previously existing possible statuses of 231 feature elements, the lower-case versions of these terms are used, 232 following the practice of [RFC3530]. This is despite the fact 233 that the corresponding uses of these terms in [RFC5661] was 234 switched to upper-case, for no clear reason, and similarly in the 235 case [RFC7530], presumably due to inertia. 237 o In speaking of the potential statuses of features, the words 238 "required" and "non-required" are used. By using the latter term, 239 we focus on the fact that the feature in question is not required 240 to be supported, while treating any potential recommendation for 241 support as out-of-scope. 243 o When one of these upper-case keywords defined in [RFC2119] is used 244 in this document, it is in the context of a rule directed to an 245 implementer of NFSV4 minor versions, or in a quotation, sometimes 246 indirect, from another document. 248 3. Consolidation of Version Management Rules 250 In the past, the only existing version management rules were the 251 minor versioning rules that had been being maintained and specified 252 in the Standards Track RFCs which defined the individual minor 253 versions. As a result, these minor versioning rules were modified on 254 an ad hoc basis for each new minor version. 256 More recently, minor versioning rules were specified in [RFC5661] 257 while modifications to those rules were allowed in subsequent minor 258 versions. 260 This document defines a set of version management rules, including 261 rules for minor version construction. These rules apply to all 262 future changes to the NFSv4 protocol. The rules are subject to 263 change but any such change should be part of a standards track RFC 264 obsoleting or updating this document. 266 Rather than a single list of minor versioning rules, as in [RFC5661], 267 this document defines multiple sets of rules that deal with the 268 various forms of versioning provided for in the NFSv4 version 269 management framework. 271 o The kinds of changes that may be made are addressed in the rules 272 in Sections 4.1.3, 4.2.3, 4.3.1, and 4.3.2. 274 o Rules relating to the composition of changes into features are 275 addressed in Section 6.1 277 o Minor version construction, including rules applicable to features 278 which cannot be used as extensions to existing minor versions are 279 addressed in Section 9.1 281 o Minor version interaction rules are discussed in Sections 9.2.2 282 and 9.2.1. 284 This document supersedes minor versioning rules appearing in the 285 minor version specification RFC's, including those in [RFC5661]. As 286 a result, potential conflicts among these documents should be 287 addressed as follows: 289 o The specification of the actual protocols for minor versions 290 previously published as Proposed Standards take precedence over 291 minor versioning rules in either this document or in the minor 292 version specification RFC's. In other words, if the transition 293 from version A to version B violates a minor versioning rule, the 294 version B protocol stays as it is. In particular, many of the 295 changes made for NFSV4.1 would not be allowed in the version 296 management framework defined here. See Section 4.2.3 for details. 298 o Since minor versioning rules #11 and #13 from [RFC5661] deal with 299 the interactions between multiple minor versions, the situation is 300 more complicated. See Section 9.2 for a discussion of these 301 issues, including how potential conflicts between rules are to be 302 resolved. 304 o Otherwise, any conflict between the version management rules in 305 this document and those in minor version specification RFC's are 306 to be resolved based on the treatment in this document. In 307 particular, corrections may be made as specified in Section 10 for 308 all previously specified minor versions and extensibility of 309 previously specified minor versions is to be handled in accord 310 with Section 8. 312 Future minor version specification documents should avoid specifying 313 minor versioning rules and reference this document in connection with 314 rules for NFSv4 version management. 316 4. NFSv4 Protocol Changes 318 Protocol changes that are to be managed within the NFSv4 versioning 319 framework may be of a number of types, which are discussed in the 320 sections below. Such changes include, but are not limited to, 321 changes in the underlying protocol XDR. 323 Each such change will be organized, documented and effected as part 324 of a given feature. The way this will be done depends on a number of 325 factors, including the types of changes included in the feature. 326 This subject is discussed in Section 6.5. 328 4.1. XDR Extension 330 When an NFSv4 version change requires a modification to the protocol 331 XDR, this is effected within a framework based on the idea of XDR 332 extension. This is opposed to transitions between major NFS versions 333 (including that between NFSv3 and NFSv4.0) in which the XDR for one 334 version was replaced by a different XDR for a newer version. 336 The use of XDR extension can facilitate compatibility between 337 different versions of the NFSv4 protocol. When XDR extension is used 338 to implement non-required features, the greatest degree of inter- 339 version compatibility is obtained. For specifics regarding rules for 340 interversion compatibility, see Section 9.2.2. 342 4.1.1. XDR Extension in General 344 XDR extension allows an XDR description to be extended in a way which 345 retains the structure of all previously valid messages. If a base 346 XDR description is extended to create a second XDR description, the 347 following will be true for the second description to be a valid 348 extension of the first: 350 o The set of valid messages described by the extended definition is 351 a superset of that described by the first. 353 o Each message within the set of valid messages described by the 354 base definition is recognized as having exactly the same 355 structure/interpretation using the extended definition. 357 o Each message within the set of messages described as valid by the 358 extended definition but not the base definition must be 359 recognized, using the base definition, as part of an unsupported 360 extension. 362 An extension of a given XDR description consists of any of the 363 following: 365 o Addition of previously unspecified RPC operation codes. 367 o Addition of new, previously unused, values to existing enums. 369 o Addition of previously unassigned bit values to a flag word. 371 o Addition of new cases to existing switches, provided that the 372 existing switch did not contain a default case. 374 However, none of the following may happen: 376 o Deletion of existing RPC operations, enum values, flag bit values 377 and switch cases. Note that changes may be made to define use of 378 any of these as causing an error, as long as the XDR is 379 unaffected. 381 o Similarly, none of these items may be reused for a new purpose. 383 o Any change to the XDR-defined structure of existing requests or 384 replies other than those listed above. 386 4.1.2. Particulars of XDR Extension within NFSv4 388 There are issues, particular to NFSv4, that affect the definition of 389 a valid XDR extension within NFSv4. 391 o Because NFSv4 has chosen to structure itself around compound 392 requests and callbacks, addition of previously unspecified RPC 393 operation codes is not allowed. 395 o Although they fit under the general category of enumerations, 396 operation codes (including those for callbacks) are so central to 397 the structure of NFSv4, that they merit special treatment. 399 o The fact that attribute sets are represented within nominally 400 opaque arrays calls for special handling. 402 4.1.3. Rules for XDR Extension within NFSv4 404 In the context of NFSv4, an extension of a given XDR description 405 consists of one or more of the following: 407 o Addition of previously unspecified operation codes, within the 408 framework established by COMPOUND and CB_COMPOUND. 410 o Addition of previously unspecified attributes. 412 o Addition of new, previously unused, values to existing enums. 414 o Addition of previously unassigned bit values to a flag word. 416 o Addition of new cases to existing switches, provided that the 417 existing switch did not contain a default case. 419 However, none of the following is allowed to happen: 421 o Deletion of existing RPC operations, enum values, flag bit values 422 and switch cases. Note that changes may be made to define use of 423 any of these as causing an error, as long as the XDR is 424 unaffected. 426 o Similarly, none of these items may be reused for a new purpose. 428 o Any change to the structure of existing requests or replies other 429 than those listed above. 431 4.2. Non-XDR Protocol Changes 433 Despite the previous emphasis on XDR changes, additions and changes 434 to the NFSv4 protocols have not been limited to those that involve 435 changes (in the form of extensions) to the protocol XDR. Examples of 436 other sorts of changes have been taken from NFSv4.1. 438 4.2.1. Field Interpretation and Use 440 The XDR description of a protocol does not constitute a complete 441 description of the protocol. Therefore, versioning needs to consider 442 the role of changes in the use of fields, even when there is no 443 change to the underlying XDR. 445 Although any XDR element is potentially subject to a change in its 446 interpretation and use the likelihood of such change will vary with 447 the XDR type, as discussed below:. 449 o When XDR elements are defined as strings, rules regarding the 450 appropriate string values are specified in protocol specification 451 text with changes in such rules documented in minor version 452 definition documents. 454 Some types of strings within NFS4 are used in server names (in 455 location-related attributes), user and group names, and in the 456 names of file object within directories. Rules regarding what 457 strings are acceptable appear in [RFC7530] and [RFC5661] with the 458 role of the XDR limited to hints regarding UTF-8 and 459 capitalization issues via XDR typedefs. 461 o Fields that are XDR-defined as opaque elements and which are truly 462 opaque, do not raise versioning issues, except as regards inter- 463 version use, which is effectively foreclosed by the rules in 464 Section 9.2. 466 Note that sometimes a field will seem to be opaque but not 467 actually be fully opaque when considered carefully. For example, 468 the "other" field of stateids is defined as an opaque array, while 469 the specification text specially defines appropriate treatment 470 when the "other" field within it is either all zeros or all ones. 471 Given this context, creation or deletion of reserved values for 472 "special" stateids will be a protocol change which versioning 473 rules need to deal with. 475 o Some nominally opaque elements have external XDR definitions that 476 overlay the nominally opaque arrays. This technique is useful 477 when the same element may be used in several ways when a switched 478 union is not appropriate. 480 For example, each pNFS mapping type provides its own XDR 481 definition for various pNFS-related fields defined in [RFC5661] as 482 opaque arrays. For more information about the handling of pNFS 483 within the NFSv4 versioning framework, see Section 4.3.1. 485 Another form of protocol change that changes how fields are 486 presented, without affecting the XDR occurs when there is a change in 487 the data elements which may be presented as RDMA chunks. 489 4.2.2. Behavioral Changes 491 Changes in the behavior of NFSv4 operations are possible, even if 492 there is no change in the underlying XDR or change to field 493 interpretation and use. 495 Many such behavioral changes have occurred in connection with the 496 addition of the session concept in NFSv4.1. 498 o Because exactly-once is semantics provided by sessions, the use of 499 owner-based sequence values in such operations as OPEN, LOCK, 500 LOCKU are now longer needed and the server is to ignore them. 502 o Because of the requirement to begin almost all COMPOUNDs with a 503 SEQUENCE operation, the semantics of previously defined operations 504 was changed and all formerly valid COMPOUNDs were defined as 505 resulting in errors. 507 o Because the clientid is inferable from a previous SEQUENCE 508 operation, the clientid is not needed in operations such as OPEN 509 and LOCK, and the client is required to pass a value of zero. 511 Also changes were made regarding the required server behavior as to 512 the interaction of the MODE and ACL attributes. 514 4.2.3. Rules for non-XDR changes 516 In the past (e.g. in [RFC5661]) there was often uncertainty about 517 whether any particular difference from NFSv4.0 was: 519 o A purely editorial change, which may be relevant to other minor 520 versions. 522 o The correction of a protocol mistake, best handled as described in 523 Section 10. 525 o A protocol improvement relevant to a new minor version or feature, 526 to be documented as described in Section 6.4. 528 In order to avoid such situations, all such changes will be 529 documented as part of a feature, specifying the specific changes 530 relative to protocol versions that do not incorporate that new 531 feature. Also, to provide greater clarity about such changes, the 532 following rules apply: 534 o Any such change must be part of a feature in which there is also 535 an XDR extension present, to enable testing for presence of the 536 feature. 538 o No feature including such a change can be made required at initial 539 introduction. 541 o No feature including such a change can be introduced as an 542 extension. While the feature may be documented in a separate 543 feature definition document in such cases, that document should be 544 referenced normatively by the minor version specification. 546 o While it is allowed to include multiple such changes in the same 547 feature this should only be done if there is a good reason for all 548 of these to be included or not included together. Such changes 549 should not be included in the same feature simply because all such 550 changes were introduced in the same minor version. 552 4.3. Specification of Associated Protocols 554 The definition of ancillary protocols is a form of protocol extension 555 that is provided as part of pNFS and might be made available for 556 other uses in the future. 558 As in the case of pNFS, the NFSv4 protocol proper would provide the 559 basic framework for performing some protocol-related task, while 560 allowing multiple independent means of performing that task to be 561 defined. The version management considerations appropriate to 562 creating such additional forms of protocol extension are discussed in 563 Section 4.3.2 565 4.3.1. Associated Protocols via pNFS Mapping Types 567 pNFS is structured around the ability to define alternate mapping 568 types in addition to the one defined in [RFC5661], (e.g. [RFC5663], 569 [RFC5664]). Each mapping type specifies the data-transfer protocol 570 to be used to access data represented by layouts as well as mapping- 571 type-specific XDR definitions of layout-related data structures. 573 Specifying a new mapping type is an additional form of protocol 574 change within the NFSv4 version management framework. A feature 575 consisting of the new mapping type is not tied to a specific minor 576 version. As explained in Section 7, it is available in multiple 577 minor versions upon publication. 579 4.3.2. Additional Forms of Associated Protocols 581 The same sort of approach used for pNFS might be used in other 582 circumstances where there is a clear need to standardize a set of 583 protocol-related requirements and where it is desirable, for various 584 reasons, to leave open the choice of mechanism by which those 585 requirements might be met. 587 Such cases might arise where the function to be performed is likely 588 to be too enmeshed with the structure of the file system 589 implementation to allow a single protocol mechanism to be specified. 590 In such cases, multiple approaches might themselves be standardized, 591 each fitting into a template established previously using any or all 592 of the elements used by pNFS: 594 o The establishment of a registry of identifiers for the 595 standardized mechanisms to satisfy the established requirements. 597 o Definition of data structures related to the function to be 598 performed to include both a mechanism identifier, and a nominally 599 opaque portion, the real format of which is to have a mechanism- 600 specific definition. 602 o The ability to specify multiple protocols to perform the same 603 function, which may include a minor version of NFSv4, a particular 604 use an established protocol, or a new protocol designed for the 605 purpose. 607 New instances of such a two-level approach might be established in 608 the future, subject to the following restrictions: 610 o That there is a feature establishing the requirements that the 611 associated protocols are to meet. 613 o That that feature is defined as an integral feature of a 614 particular minor version and not as an extension. This does not 615 exclude the feature being defined in a separate document to which 616 the minor version specification has a normative reference. 618 o That there be at least one instance of a specific protocol 619 mechanism meeting the established requirements. To limit 620 confusion, the requirements and the initial mechanism should be 621 defined in separate documents. 623 The above are a minimal set of restrictions for establishing such an 624 additional extension mechanism. The working group may, as part of 625 defining the core feature establishing the extension mechanism may 626 specify further restrictions governing when minor versions may 627 incorporate particular instances of that extension mechanism. 629 5. Documentation Approach 631 Documentation of future changes to the NFSv4 protocol will use 632 feature specification documents as described in Section 6.4. There 633 are a number of ways in which such documents may be used, as 634 discussed in Section 6.5 636 5.1. Indexing material 638 The following items, referred to collectively as "Indexing material" 639 will be useful in many contexts. The reason for frequently 640 publishing such material is to prevent a situation in which large 641 numbers of documents must be scanned to find the most current 642 description of a particular protocol element. 644 o A table mapping operations and callbacks to the most recent 645 document containing a description of that operation. 647 o A table mapping attributes to the most recent document containing 648 a description of that attribute. 650 o A table giving, for each operation in the protocol, the errors 651 that may validly be returned for that operation. If possible, it 652 would be desirable to give, as does [RFC5661], the operations 653 which may validly return each particular error. 655 o A table giving for each operation, callback, and attribute and for 656 each feature element in a published extension giving its status 657 (required or not, or mandatory-to-not implement), and its 658 relationship to the feature which allows its inclusion (i.e., 659 required for every implementation of the feature, or optional in 660 the presence of the feature). This would be similar to the 661 material in Section 14 of [NFSv42], expanded in scope to include 662 all feature elements. 664 6. NFSv4 Features 666 Individual changes, whether they are XDR extensions or other sorts of 667 changes, are organized in term of features. This is in order to 669 o allow the protocol documentation to more clearly specify what XDR 670 extensions and other changes must be supported together. 672 o help the client determine which particular changes are present and 673 implemented by the server. 675 o to support the independent development and specification of 676 changes to the protocol, without artificially tying features 677 together in a paradigm based on minor versions. 679 o provide support for a feature-based documentation structure, as 680 described in Section 6.4. 682 6.1. Rules for Feature Construction 684 A feature consists of one or more valid NFSv4 changes, which work 685 together as a functional whole. The change elements may be of any of 686 the types described in Section 4 although the specific types of 687 changes will affect how the feature can be integrated in the NFSv4 688 protocol. 690 6.2. Feature Statuses 692 Each feature has one of three statuses with regard to each minor 693 version of which it might be a part. 695 o The feature is a required part of the minor version. 697 o The feature is not a required part of the minor version, but may 698 be implemented as part of that version.. 700 o The feature is not a valid part of the minor version. 702 For features which have been previously defined as valid, this is 703 represented as being "mandatory to not implement" as opposed to 704 simply being undefined. 706 These statuses define whether a client implementing the minor version 707 has to be prepared for the existence of the feature and/or its non- 708 support by the server. 710 The working group is still free to make recommendations regarding the 711 desirability of server and client support for particular features in 712 particular minor versions in the minor version definition document, 713 or in other, presumably informational, documents. 715 In addition to feature status, there may be other constraints that 716 define when an implementation must or may support a feature. In 717 particular, support for one feature may require support for another, 718 or the presence of one feature may require that another feature not 719 be supported. 721 6.3. Feature Discovery 723 The presence or absence of particular features may be determined in a 724 number of ways: 726 o For features which are required within a given minor version, a 727 client can determine whether the feature is supported by seeing if 728 the minor version is supported. 730 o For non-required features that contain an XDR-extending protocol 731 element, a client can try to use techniques described in 732 Section 8.2.1 to determine what features the server supports. 734 o For non-required features that do not contain an XDR-extending 735 protocol element, appropriate feature discovery facilities can be 736 constructed on an ad hoc basis by defining a non-required per- 737 server or per-fs boolean attribute to serve as an indication of 738 support. To address compatibility issues with earlier servers, an 739 appropriate default value to assume when the attribute is not 740 supported should be specified. 742 6.4. Feature Specification Documents 744 Features will be documented in the form of a working-group standards- 745 track document which define one or more features. Generally, only 746 closely related features should be defined in the same document. 748 The definition of each of the new features may include one or more 749 "feature elements" which change the protocol in any of the ways 750 discussed in Section 4. Feature elements include new operations, 751 callbacks, attributes, and enumeration values. The functionality of 752 some existing operations may be extended by the addition of new flags 753 bits in existing flag words, by new cases in existing switched 754 unions, and by valid semantic changes to existing operations. 756 Such feature definition documents would contain a number of items, 757 following the pattern of the NFSv4.2 specification. The only 758 difference would be that while the NFSv4.2 specification defines a 759 number of features to be incorporated into NFSv4.2, the feature 760 definition documents would each define a single feature, or a small 761 set of closely related features. 763 In addition to a general explanation of the feature in question, the 764 items to be included in such feature definition documents would be: 766 o Description of new operations (corresponding to Sections 16 and 17 767 of [NFSv42]). 769 o Description of any modified operations (corresponding to 770 Section 15 of [NFSv42]). 772 o Description of new attributes (corresponding to Section 13 of 773 [NFSv42]). 775 o Description of any added error codes (corresponding to 776 Section 12.1 of [NFSv42]). 778 o All operation descriptions, whether for new or modified 779 operations, should indicate when operations or the corresponding 780 results may be presented as RDMA chunks. 782 o A summary description of all changes made by this feature to the 783 XDR definition of the protocol, including operation codes, 784 attribute numbers, added flag bits and enumeration values, and 785 request and response structures for new operations together with 786 the other XDR extensions needed to support them. 788 o A listing giving the valid errors for each new operation and 789 callback (corresponds to Sections 12.2 and 12.3 of [NFSv42]). 791 o A table giving for each new feature element its status (required 792 or not) and its relationship to the feature(s) being described 793 (i.e., required for every implementation of the feature, or 794 optional in the presence of the feature). This would be similar 795 to the material in Section 14 of [NFSv42] but restricted to the 796 feature(s) defined in the document and expanded in scope to 797 include all feature elements. 799 o All of the additional Sections required for RFC publication, such 800 as "Security Considerations", "IANA considerations", etc. 802 6.5. Feature Incorporation 804 All protocol changes will be organized, documented and effected as 805 part of a given feature. This includes XDR extension and the various 806 sorts of non-XDR-based changes allowed. 808 Such features may be made part of the protocol in a number of ways: 810 o In new minor versions, as discussed in Section 9. 812 o In separately documented new features. When new features are non- 813 required and do not include any non-XDR-based changes, they may be 814 incorporated in an extensible minor version under construction. 815 See Section 8 for details. 817 o When appropriate compatibility arrangement are in effect, they may 818 be used to correct protocol problems in already approved minor 819 versions and features. See Section 10 for details. 821 7. Extensions within Minor Versions 823 The NFSv4 version management framework allows, with certain 824 restrictions, features to be added to existing minor versions 826 o In the case of features which consist only of a pNFS mapping type, 827 the protocol may be extended by publishing the new mapping type 828 definition as a Proposed Standard. This effects an extension to 829 all minor versions in which pNFS is a valid feature. 831 Similar extension facilities could be made available if additional 832 pNFS-like extension frameworks were created (See Section 4.3.2). 834 o Minor versions designated as extensible (see Section 8) may be 835 extended by the publication of a standards-track document defining 836 the additional feature. Details are set out in Section 8. The 837 features to be added are considered non-required in the extensible 838 minor version and must consist only of valid XDR-based extensions 840 8. Adding Features to Extensible Minor Versions 842 Addition of features to an extensible minor version will take 843 advantage of the existing NFSv4 infrastructure that allows optional 844 features to be added to new minor versions, but without in this case 845 requiring any change in the minor version number. Adding features in 846 this way will enable compatibility with existing clients and servers, 847 who may be unaware of the new feature. 849 8.1. Use of Feature Specification Documents 851 Each such extension will be in the form of a working-group standards- 852 track document which defines one or more new non-required features. 853 The definition of each of the new feature may include one or more 854 "protocol elements" which extend the existing XDR as already 855 discussed (in Section 4.1). Other sorts of XDR modification are not 856 allowed. Protocol elements include new operations, callbacks, 857 attributes, and enumeration values. The functionality of some 858 existing operations may be extended by the addition of new flags bits 859 in existing flag words and new cases in existing switched unions. 860 New error codes may be added but the set of valid error codes to be 861 returned by an operation is fixed, except that existing operations 862 may return new errors to respond to situations that only arise when 863 previously unused flag bits are set or when extensions to a switched 864 union are used. 866 Each such additional feature will become, for all intents and 867 purposes, part of the current NFSv4 minor version upon publication of 868 the description as a Proposed Standard, enabling such extensions to 869 be used by new client and server implementations without, as 870 previously required, a change in the value of the minor version field 871 within the COMPOUND operation. 873 The working group has two occasions to make sure that such features 874 are appropriate ones: 876 o At the time the feature definition document becomes a working 877 group document, the working group needs to determine, in addition 878 to the feature's general compatibility with NFSv4, that the XDR 879 assignments (i.e. additional values for operation callback and 880 attribute numbers, and for new flags and switch values to be added 881 to existing operations) associated with the new feature are 882 complete and do not conflict with those in the existing protocol 883 or those currently under development. 885 o At the time the working group document is complete, the working 886 group, in addition to normal document review, can and should look 887 at what prototype implementations of the feature have been done 888 and use that information to determine the work-ability and 889 maturity of the feature. 891 8.2. Compatibility Issues 893 Because the receiver of a message may be unaware of the existence of 894 a specific extension, certain compatibility rules need to be 895 observed. In some cases (e.g., addition of new operations or 896 callbacks or addition of new arms to an existing switched union) 897 older clients or servers may be unable to do XDR parsing on an 898 extension of whose existence they are unaware. In other cases (e.g., 899 error returns) there are no XDR parsing issues but existing clients 900 and servers may have expectations as to what may validly be returned. 901 Detailed discussion of these compatibility issues appears below: 903 o Issues related to messages sent to the server are discussed in 904 Section 8.2.1. 906 o Issues related to messages sent to the client are discussed in 907 Section 8.2.2. 909 8.2.1. Compatibility Issues for Messages Sent to Servers 911 This section deals with compatibility issues that relate to messages 912 sent to the server, i.e., requests and replies to callbacks. In the 913 case of requests, it is the responsibility of the client to determine 914 whether the server supports the extension in question before sending 915 a request containing it for any purpose other than determining 916 whether the server is aware of the extension. In the case of 917 callback replies, the server demonstrates its awareness of proper 918 parsing for callback replies by sending the associated callback. 920 Regarding the handling of requests: 922 o Existing server implementations will return NFS4ERR_NOTSUPP or 923 NFS4ERR_OP_ILLEGAL in response to any use of a new operation, 924 allowing the client to determine that the requested operation (and 925 potentially the feature in question) is not supported by the 926 server. 928 o Clients can determine whether particular new attributes are 929 supported by a given server by examining the value returned when 930 the supported_attr attribute is interrogated. Clients need to do 931 this before attempting to use attributes defined in an extension 932 since they cannot depend on the server returning 933 NFS4ERRATTRNOTSUPP for requests which include a mask bit 934 corresponding to a previously unspecified attribute number (as 935 opposed to one which is defined but unsupported). 937 o Existing server implementations that do not recognize new flag 938 bits will return NFS4ERR_INVAL, enabling the client to determine 939 that the new flag value is not supported by the server. 941 o Existing server implementations that do not recognize the new arm 942 of a switched union in a request will return NFS4ERR_INVAL or 943 NFS4ERR_UNION_NOTSUPP, enabling the client to determine that the 944 new union arm is not supported by the server. 946 Regarding the handling of responses to callbacks: 948 o Error values returned to the server for all callbacks that do not 949 use new features will only be those previously allowed. Only when 950 the server uses a new extension feature can a previously invalid 951 error value be returned. 953 o Callback replies may only include a new arm of an existing 954 switched union when the server, typically in the callback being 955 responded to, has used a feature element associated with the 956 feature that defined the new switched union arm. 958 8.2.2. Compatibility Issues for Messages Sent to Clients 960 This sections deals with compatibility issues that relate to messages 961 sent to clients, i.e., request replies and callbacks. In both cases, 962 extensions are only sent to clients that have demonstrated awareness 963 of the extensions in question by using an extension associated with 964 the same feature. 966 Regarding the handling of request replies: 968 o Error values returned to the client for all requests that do not 969 use new features will only be those previously allowed. Only when 970 the server uses a new extension feature can a previously invalid 971 error value be returned. 973 o Replies may only include a new arm of an existing switched union 974 when the server, typically in the request being responded to, has 975 used a feature element associated with the feature that defined 976 the new switched union arm. 978 Regarding the handling of callback requests, the server needs to be 979 sure that it only sends callbacks to those clients prepared to 980 receive and parse them. 982 o In most cases, the new callback will be part of a feature that 983 contains new (forward) operations as well. When this is the case, 984 the feature specification will specify the operations whose 985 receipt by a server is sufficient to indicate that the client 986 issuing them is prepared to accept and parse the associated 987 callbacks. 989 o For callbacks associated with features that have no new operations 990 defined, the feature specification should define some way for a 991 client to indicate that it is prepared to accept and parse 992 callbacks that are part of the extension. For example, a flag bit 993 in the EXCHANGE_ID request may serve this purpose. 995 o In both of the above cases, the ability to accept and parse the 996 specified callback is considered separate from support for the 997 callback. The feature specification will indicate whether support 998 for the callback is required whenever the feature is used by the 999 client. In cases in which support is not required, the client is 1000 free to return NFS4ERR_NOTSUPP upon receiving the callback. 1002 8.3. Additional Documents to be Produced 1004 Additional documents will be required from time to time. These 1005 documents will eventually become RFC's (informational or standards 1006 track as described below), but the work of the working group and of 1007 implementers developing features will be facilitated by a progression 1008 of document drafts that incorporate information about new features 1009 that are being developed or have been approved as Proposed Standards. 1011 8.3.1. Minor Version Indexing Document 1013 One document will organize existing material for a minor version 1014 undergoing extension so that implementers will not have to scan a 1015 large set of feature definition documents or minor version 1016 specifications to find information being sought. Successive drafts 1017 of this document will serve as an index to the current state of the 1018 extensible minor version. Some desirable elements of this indexing 1019 document would include: 1021 o A list of all feature definition documents that have been approved 1022 as working group documents but have not yet been approved as 1023 Proposed Standards. 1025 o All of the items of indexing material (see Section 5.1) 1026 appropriately adjusted to reflect the contents of all extensions 1027 accepted as Proposed Standards. 1029 The frequency of updates for this document will be affected by 1030 implementer needs and the ability to easily generate document drafts, 1031 preferably by automated means. The most desirable situation is one 1032 in which a new draft is available soon after each feature reaches the 1033 status of a Proposed Standard. 1035 8.3.2. Consolidated XDR Document 1037 This document will consist of an updated XDR for the protocol as a 1038 whole including feature elements from all features and minor versions 1039 accepted as Proposed Standards. 1041 A new draft should be prepared whenever a new feature within an 1042 extensible minor version is accepted as a Proposed Standard. In most 1043 cases, feature developers will be using a suitable XDR which can then 1044 be reviewed and published. In cases in which multiple features reach 1045 Proposed Standard status at approximately the same time, a merge of 1046 the XDR changes made by each feature may be necessary. 1048 8.3.3. XDR Assignment Document 1050 This document will contain consolidated lists of XDR value 1051 assignments that are relevant to the protocol extension process. It 1052 should contain lists of assignments for: 1054 o operation codes (separate lists for forward operations and for 1055 callbacks) 1057 o attribute numbers 1059 o error codes 1061 o bits within flag words that have been extended since they were 1062 first introduced. 1064 o enumeration values for enumerations which have been extended since 1065 they were first introduced. 1067 For each set of assignments, the individual assignments may be of 1068 three types: 1070 1. permanent assignments associated with a minor version or a 1071 feature extension that has achieved Proposed Standard status. 1073 These assignments are permanent in that the assigned value will 1074 never be re-used. However, a subsequent minor version may define 1075 some or all feature elements associated with a feature to be 1076 Mandatory to NOT support. 1078 2. provisional assignments associated with a feature under 1079 development (i.e., one which has been approved as a working group 1080 document but has not been approved as a Proposed Standard). 1082 Provisional assignments are not are not permanent and the values 1083 assigned can be re-used in certain circumstances. In particular, 1084 when a feature with provisional assignments is not progressing 1085 toward the goal of eventual Proposed Standard status, the working 1086 group can judge the feature effort to have been abandoned, 1087 allowing the codes formerly provisionally allocated to be 1088 reclaimed and reassigned. 1090 3. definition of individual assignments or ranges reserved for 1091 experimental use. 1093 A new draft of this document should be produced, whenever: 1095 o A minor version or feature specification is accepted as a Proposed 1096 Standard. 1098 o A new feature is accepted for development and a draft of the 1099 corresponding working-group standards-track document is produced 1101 o A feature previously accepted for development is abandoned. 1103 o The working group decides to make some change in assignments for 1104 experimental use. 1106 8.3.4. Transition of Documents to RFC's 1108 Each of these documents should be published as an RFC soon after the 1109 minor version in question ceases to be considered extensible. 1110 Typically this will happen when the working group makes the 1111 specification for the subsequent minor version into a working group 1112 document. Some specifics about the individual documents are listed 1113 below: 1115 o The most current draft of the indexing document for the minor 1116 version would be published as an informational RFC. 1118 o The most current draft of the consolidated XDR document should be 1119 published as a standards-track RFC. It would update the initial 1120 specification of the minor version 1122 o The most recent draft of the XDR assignment document should be 1123 published as an informational RFC. 1125 Handling of these documents in the event of a post-approval XDR 1126 correction is discussed in Section 10.1 1128 8.4. Relationship Between Minor Versioning and Extensions within a 1129 Minor Version 1131 Extensibility of minor versions are governed by the following rules: 1133 o Minor versions zero and one are not extensible. Each has a fixed 1134 set of non-required features as described in [RFC7530] and 1135 [RFC5661]. 1137 o Minor versions beyond one are presumed extensible as discussed 1138 herein. However, any statement within the minor version 1139 specification disallowing extension will cause that minor version 1140 to be considered non-extensible. 1142 o No new feature may be added to a minor version may be made once 1143 the specification document for a subsequent minor version becomes 1144 a working group standards-track document. 1146 Even when a minor version is non-extensible, or when a previous minor 1147 version is closed to further extension, the features that it contains 1148 are still subject to updates to effect protocol corrections. In many 1149 cases, making an XDR change, in the form of an extension will be the 1150 best way of correcting an issue. See Section 10 for details. 1152 While making minor versions extensible will decrease the frequency of 1153 new minor versions, it will not eliminate the need for them. In 1154 particular: 1156 o A new minor version will be required for any change in the status 1157 of a feature element (i.e., an operation, callback, attribute, 1158 added flag or switch case). For example, changes which make 1159 feature elements Recommended, Required or Mandatory to Not 1160 Implement will require a minor version. 1162 o Any incompatible semantic change in the required or allowed 1163 processing of an existing operation or attribute will require a 1164 minor version. 1166 o Any change that extends the set of errors returned that an 1167 existing operation, with the exception noted above. New errors 1168 may be added when the conditions that give rise to these new 1169 errors cannot arise as long as new flag bits or switched union 1170 arms are not used. In these cases, it is clear that existing 1171 clients cannot receive these errors. 1173 o Any change in the mapping of feature elements to features will 1174 require a minor version. For example, if a feature is to be split 1175 into two separate features clients would no longer be able to 1176 infer support for one operation from support for the other, in the 1177 same way that had been done previously, invalidating logic in 1178 existing clients 1180 9. Minor Versions 1182 9.1. Minor Version Construction 1184 In addition to the sorts of non-required features that may be made in 1185 the context of extensible minor version, a number of other sorts of 1186 changes may be made in a new minor version. Because such changes 1187 have the potential to disrupt inter-version such changes should only 1188 be made after careful consideration of the effects on interversion 1189 interoperability. 1191 o Addition of new features that incorporate any of the non-XDR-based 1192 changes discussed in Sections 4.2.1 and 4.2.2. Such features must 1193 always be introduced as non-required. 1195 o Addition of required new features. 1197 o Changes to the status of existing features or to inter-feature 1198 constraints. 1200 o Changes to feature organization. Such changes may have the effect 1201 of making support for some change element obligatory in 1202 circumstances when it had not been previously. 1204 9.2. Minor Version Interaction 1206 This section addresses issues related to rules #11 and #13 in the 1207 minor versioning rules in [RFC5661]. With regard to the supersession 1208 of minor versioning rules, the treatment here overrides that in 1209 [RFC5661] when either of the potentially interacting minor versions 1210 has not yet been published as a Proposed Standard. 1212 Note that these rules are the only ones directed to minor version 1213 implementers, rather than to those specifying new minor versions. 1215 9.2.1. Minor Version Identifier Transfer Issues 1217 Each relationship between a client instance and a server instance, as 1218 represented by a clientid, is to be devoted to a single minor 1219 version. If a server detects that a COMPOUND with an inappropriate 1220 minor version is being used, it MUST reject the request. In doing 1221 so, it may return either NFS4ERR_BAD_CLIENTID or 1222 NFS4RR_MINOR_VERS_MISMATCH. 1224 As a result of the above, the client has the assurance that the set 1225 of required and allowed features will not change within the context 1226 of a single clientid. Server implementations MUST ensure that the 1227 set of supported features does not change within such a context. 1229 9.2.2. Minor Version Compatibility Issues 1231 It is desirable for client and server implementations to support a 1232 wide range of minor versions. The difficulty of doing so can be 1233 affected by choices made by the working group in defining those minor 1234 versions. 1236 Within a set of minor versions that have exactly the same set of 1237 required features, it is relatively easy for clients and servers to 1238 provide appropriate compatibility and they are well-advised to do so. 1240 Servers SHOULD accept any minor version number within the range and 1241 return NFS4ERR_OPNOTSUPP or NFS4ERR_OP_ILLEGAL for non-supported 1242 operations based on the version number. 1244 Clients SHOULD deal with an NFS4ERR_MINOR_VERS_MISMATCH error by 1245 searching the appropriate minor version range for one the server will 1246 accept. 1248 Servers and clients MAY deal with changes in the set of required 1249 features by supporting at least the union of the set of required 1250 features for all minor versions within the range to be supported. 1251 This may involve logic to specifically withhold support for features 1252 when not allowed for a particular minor version. 1254 9.3. Minor Version Documentation 1256 Minor versions should be documented by specifying and explaining the 1257 changes made relative to the previous minor version. 1259 Features added to the minor version should be documented in their own 1260 feature specification documents and normatively referenced. 1262 Changes to the status or organization of existing features should be 1263 documented by presenting a summary of the status of all existing 1264 protocol elements, their relationship to non-required features, and 1265 any relevant feature dependencies. 1267 In addition, to avoid situation where a large number of minor 1268 versions must be scanned to find the most recent valid treatment of a 1269 specific protocol element, minor version definition documents will 1270 contain the indexing material described in Section 5.1. 1272 10. Correction of Existing Minor Versions and Features 1274 The possibility always exists that there will be a need to correct an 1275 existing feature in some way, after the acceptance of that feature or 1276 a minor version containing it, as a Proposed Standard. While the 1277 working group can reduce the probability of such situations arising 1278 by waiting for running code before considering a feature as done, it 1279 cannot reduce the probability to zero. As features are used more 1280 extensively and interact with other features, previously unseen flaws 1281 may be discovered and will need to be corrected. 1283 Such corrections are best done in a bis document updating the RFC 1284 defining the relevant feature definition document or minor version 1285 specification. In making such a correction, the working will have to 1286 carefully consider how to assure interoperability with older clients 1287 and servers. 1289 Often, corrections can be done without changing the protocol XDR. 1290 However, incompatible changes in server or client behavior should not 1291 be mandated in order to avoid XDR changes. When XDR changes are 1292 necessary as part of correcting a flaw, these should be done in a 1293 manner similar to that used when implementing new minor versions or 1294 features within them. In particular, 1296 o Existing XDR structures may not be modified or deleted. 1298 o XDR extensions may be used to correct existing protocol facilities 1299 in a manner similar to those used to add additional optional 1300 features. Such corrections may be done in an otherwise non- 1301 extensible minor version, if the working group judges it 1302 appropriate. 1304 o When a correction is made to a non-required feature, the result is 1305 similar to a situation in which there are two independent non- 1306 required features. A server may choose to implement either or 1307 both. 1309 o When a correction is made to a required feature, the situation 1310 becomes one in which neither the old nor the new version of the 1311 feature is required. Instead, it is required that a server 1312 support at least one of the two, while each is individually non- 1313 required. Although use of the corrected version is ultimately 1314 better, and may be recommended, it should not be described as 1315 "RECOMMENDED", since the choice of which version to support if 1316 only one is supported will depend on the needs of clients, which 1317 may be slow to adopt the updated version. 1319 o In all of the cases above, it is appropriate that the old version 1320 of the feature, be considered obsolescent, with the expectation 1321 that the working group might, in a later minor version, decide 1322 that the older version is to become mandatory to not implement. 1324 Issues related to the effect of XDR corrections on existing 1325 documents, including co-ordination with other minor versions, are 1326 discussed in Section 10.1. 1328 By doing things this way, the protocol with the XDR modification can 1329 accommodate clients and servers that support either the corrected or 1330 the uncorrected version of the protocol and also clients and servers 1331 aware of and capable of supporting both alternatives. 1333 o A client that supports only the earlier version of the feature 1334 (i.e., an older unfixed client) can determine whether the server 1335 it is connecting to supports the older version of feature. It is 1336 capable of interoperating with older servers that support only the 1337 unfixed protocol as well as ones that support both versions. 1339 o A client that supports only the corrected version of the feature 1340 (i.e., a new or updated client) can determine whether the server 1341 it is connecting to supports the newer version of the feature. It 1342 is capable of interoperating with newer servers that support only 1343 the updated feature as well as ones that support both versions. 1345 o A client that supports both the older and newer version of the 1346 feature can determine which version of the particular feature is 1347 supported by the server it is working with. 1349 o A server that supports only the earlier version of the feature 1350 (i.e., an older unfixed server) can only successfully interoperate 1351 with older clients. However newer clients can easily determine 1352 that the feature cannot be used on that server. 1354 o A server that supports only the newer version of the feature 1355 (i.e., a new or updated server) can only successfully interoperate 1356 with newer clients. However, older clients can easily determine 1357 that the feature cannot be used on that server. In the case of 1358 non-required features, clients can be expected to deal with non- 1359 support of that particular feature. 1361 o A server that supports both the older and newer versions of the 1362 feature can interoperate with all client variants. 1364 By using extensions in this manner, the protocol creates a clear path 1365 which preserves the functioning of existing clients and servers and 1366 allowing client and server implementers to adopt the new version of 1367 the feature at a reasonable pace. 1369 10.1. Documentation of XDR Changes 1371 In the event of an XDR correction, as discussed above, some document 1372 updates will be required. For the purposes of this discussion we 1373 call the minor version for which XDR correction is required minor 1374 version X and the minor version on which development is occurring 1375 minor version Y. 1377 The following discusses the specific updated documents which could be 1378 required: 1380 o The specification of the feature in question will have to be 1381 updated to explain the issue, how it was fixed, and the 1382 compatibility and upgrade strategy. Normally this will require an 1383 RFC updating the associated feature specification document. 1385 However, in the case of a correction to a feature documented in a 1386 minor version definition document, the RFC will update that 1387 document instead. 1389 o An updated XDR for minor version X will be produced and will be 1390 published as a updated to the minor version specification RFC for 1391 minor version X. 1393 When the correction is to feature documented in a minor version 1394 definition, a single RFC will contain both updates to the minor 1395 version specification RFC. 1397 o An updated minor version indexing document for minor version X is 1398 desirable but not absolutely necessary. 1400 The question of updated minor version indexing documents for minor 1401 versions between X and Y should be addressed by the working group 1402 on a case-by-case basis. 1404 o An updated XDR assignment document will be required. It should be 1405 based on the most recent such document associated with minor 1406 version Y and will serve as the basis for later XDR assignment 1407 drafts for minor version Y. 1409 The informational RFC's associated with minor version Y (version 1410 indexing document and XDR assignment document) will contain the 1411 effects of the correction when published. Similarly, the minor 1412 version specification RFC will contain the XDR changes associated 1413 with the correction. 1415 11. Security Considerations 1417 Since no substantive protocol changes are proposed here, no security 1418 considerations apply. 1420 As features and minor versions are designed and specified in 1421 standards-track documents, their security issues will be addressed 1422 and each RFC candidate will receive the appropriate security review 1423 from the NFSv4 working group and IESG. 1425 12. IANA Considerations 1427 The current document does not require any actions by IANA. 1429 Depending on decisions that the working group makes about how to 1430 address the issues raised in this document, future documents may 1431 require actions by IANA. 1433 13. References 1435 13.1. Normative References 1437 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1438 Requirement Levels", BCP 14, RFC 2119, March 1997. 1440 13.2. Informative References 1442 [NFSv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", April 1443 2015, . 1446 Work in progress. 1448 [NFSv42-dot-x] 1449 Haynes, T., Ed., "NFS Version 4 Minor Version 2 Protocol 1450 External Data Representation Standard (XDR) Description", 1451 April 2015, . 1454 Work in progress. 1456 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 1457 Beame, C., Eisler, M., and D. Noveck, "Network File System 1458 (NFS) version 4 Protocol", RFC 3530, April 2003. 1460 [RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File 1461 System (NFS) Version 4 Minor Version 1 Protocol", RFC 1462 5661, January 2010. 1464 [RFC5662] Shepler, S., Eisler, M., and D. Noveck, "Network File 1465 System (NFS) Version 4 Minor Version 1 External Data 1466 Representation Standard (XDR) Description", RFC 5662, 1467 January 2010. 1469 [RFC5663] Black, D., Fridella, S., and J. Glasgow, "Parallel NFS 1470 (pNFS) Block/Volume Layout", RFC 5663, January 2010. 1472 [RFC5664] Halevy, B., Welch, B., and J. Zelenka, "Object-Based 1473 Parallel NFS (pNFS) Operations", RFC 5664, January 2010. 1475 [RFC7530] Haynes, T. and D. Noveck, "Network File System (NFS) 1476 Version 4 Protocol", RFC 7530, March 2015. 1478 [RFC7531] Haynes, T. and D. Noveck, "Network File System (NFS) 1479 Version 4 External Data Representation Standard (XDR) 1480 Description", RFC 7531, March 2015. 1482 Author's Address 1484 David Noveck 1485 Hewlett-Packard 1486 165 Dascomb Road 1487 Andover, MA 01810 1488 US 1490 Phone: +1 978 474 2011 1491 Email: davenoveck@gmail.com