idnits 2.17.1 draft-ietf-nfsv4-versioning-04.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC5661, but the abstract doesn't seem to directly say this. It does mention RFC5661 though, so this could be OK. 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). (Using the creation date from RFC5661, updated by this document, for RFC5378 checks: 2005-10-21) -- 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 (June 2, 2016) is 2884 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) -- 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 (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 D. Noveck 3 Internet-Draft HPE 4 Updates: 5661 (if approved) June 2, 2016 5 Intended status: Standards Track 6 Expires: December 4, 2016 8 NFSv4 Version Management 9 draft-ietf-nfsv4-versioning-04 11 Abstract 13 This document describes the management of versioning within the NFSv4 14 family of protocols. It covers the creation of minor versions, the 15 addition of optional features to existing minor versions, and the 16 correction of flaws in features already published as Proposed 17 Standards. The rules relating to the construction of minor versions 18 and the interaction of minor version implementations that appear in 19 this document supersede the minor versioning rules in RFC5661. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 4, 2016. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Existing Minor Versions . . . . . . . . . . . . . . . . . 4 57 1.2. Updated NFSv4 Version Management Framework . . . . . . . 4 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 6 60 2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 7 61 2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 8 62 3. Consolidation of Version Management Rules . . . . . . . . . . 9 63 4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 11 64 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 11 65 4.1.1. XDR Extension in General . . . . . . . . . . . . . . 11 66 4.1.2. Particulars of XDR Extension within NFSv4 . . . . . . 12 67 4.1.3. Rules for XDR Extension within NFSv4 . . . . . . . . 13 68 4.2. Handling of Protocol Elements . . . . . . . . . . . . . . 13 69 4.3. Organization of Protocol Elements . . . . . . . . . . . . 15 70 4.4. Inter-version Interoperability . . . . . . . . . . . . . 15 71 4.4.1. Requirements for Knowledge of Protocol Elements . . . 15 72 4.4.2. Establishing Interoperability . . . . . . . . . . . . 16 73 4.4.3. Determining Knowledge of Protocol Elements . . . . . 18 74 4.4.4. Interoperability Between Version Groups . . . . . . . 19 75 5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 19 76 5.1. Non-XDR Protocol Changes . . . . . . . . . . . . . . . . 19 77 5.1.1. Field Interpretation and Use . . . . . . . . . . . . 20 78 5.1.2. Behavioral Changes . . . . . . . . . . . . . . . . . 21 79 5.1.3. Rules for non-XDR changes . . . . . . . . . . . . . . 21 80 5.2. Specification of Associated Protocols . . . . . . . . . . 22 81 5.2.1. Associated Protocols via pNFS Mapping Types . . . . . 23 82 5.2.2. Additional Forms of Associated Protocols . . . . . . 23 83 6. NFSv4 Protocol Features . . . . . . . . . . . . . . . . . . . 24 84 6.1. Previous Uses of the Feature Concept . . . . . . . . . . 25 85 6.2. Rules for Protocol Feature Construction . . . . . . . . . 26 86 6.3. Statuses of Features . . . . . . . . . . . . . . . . . . 26 87 6.4. Statuses of Protocol Elements Within Features . . . . . . 27 88 6.5. Determining Protocol Element Support . . . . . . . . . . 29 89 6.6. Feature Discovery . . . . . . . . . . . . . . . . . . . . 30 90 6.7. Feature Incorporation . . . . . . . . . . . . . . . . . . 32 91 7. Extensions within Minor Versions . . . . . . . . . . . . . . 32 92 7.1. Adding Features to Extensible Minor Versions . . . . . . 32 93 7.2. Use of Feature Specification Documents . . . . . . . . . 33 94 7.3. Compatibility Issues . . . . . . . . . . . . . . . . . . 34 95 7.3.1. Compatibility Issues for Messages Sent to Servers . . 34 96 7.3.2. Compatibility Issues for Messages Sent to Clients . . 35 98 7.4. Relationship Between Minor Versioning and Extensions 99 within a Minor Version . . . . . . . . . . . . . . . . . 36 100 8. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 37 101 8.1. Creation of New Minor Versions . . . . . . . . . . . . . 37 102 8.1.1. New Minor Versions within an Existing Group . . . . . 37 103 8.1.2. New Minor Version Groups . . . . . . . . . . . . . . 37 104 8.1.3. Limits on Minor Version Groups . . . . . . . . . . . 40 105 8.2. Role of Minor Versions . . . . . . . . . . . . . . . . . 41 106 8.3. Minor Version Interaction Rules . . . . . . . . . . . . . 41 107 8.3.1. Minor Version Identifier Transfer Issues . . . . . . 42 108 8.3.2. Minor Version Intra-Group Compatibility . . . . . . . 42 109 8.3.3. Minor Version Inter-Group Compatibility . . . . . . . 43 110 9. Correction of Existing Minor Versions and Features . . . . . 44 111 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 45 112 10. Documentation of Features, Extensions, Minor Versions, and 113 Protocol Corrections . . . . . . . . . . . . . . . . . . . . 47 114 10.1. Documentation Approach . . . . . . . . . . . . . . . . . 47 115 10.2. Indexing material . . . . . . . . . . . . . . . . . . . 47 116 10.3. Feature Specification Documents . . . . . . . . . . . . 48 117 10.4. XDR File Considerations . . . . . . . . . . . . . . . . 50 118 10.5. Additional Documents to Support Protocol Extension . . . 51 119 10.5.1. Minor Version Indexing Document . . . . . . . . . . 51 120 10.5.2. Consolidated XDR Document . . . . . . . . . . . . . 52 121 10.5.3. XDR Assignment Document . . . . . . . . . . . . . . 52 122 10.5.4. Transition of Documents to RFC's . . . . . . . . . . 53 123 10.6. Documentation of New Minor Versions . . . . . . . . . . 54 124 10.7. Documentation of XDR Changes for Corrections . . . . . . 54 125 11. Security Considerations . . . . . . . . . . . . . . . . . . . 55 126 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 127 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 128 13.1. Normative References . . . . . . . . . . . . . . . . . . 55 129 13.2. Informative References . . . . . . . . . . . . . . . . . 56 130 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 57 131 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 57 133 1. Introduction 135 To address the requirement for an NFS protocol that can evolve as the 136 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 137 provides a framework to allow for future changes via the creation of 138 new protocol versions including minor versions and certain forms of 139 modification of existing minor versions. The version management 140 rules contained in this document allow extensions and other changes 141 to be implemented in a way that maintains compatibility with existing 142 clients and servers. 144 1.1. Existing Minor Versions 146 Previously, all protocol changes had been part of new minor versions. 147 The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the 148 minor version being used by the client in making requests. The 149 CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) specifies the 150 minor version being used by the server on callback requests. 152 Each existing minor version has been specified by one or more 153 standards track RFCs: 155 o Minor version 0 (NFSv4.0) is specified by [RFC7530] with the XDR 156 description appearing in [RFC7531]. 158 o Minor version 1 (NFSv4.1) is specified by [RFC5661] with the XDR 159 description appearing in [RFC5662]. 161 o Minor version 2 (NFSv4.2) is specified by [NFSv42] (in terms of 162 changes from [RFC5661]). The XDR description appears in 163 [NFSv42-dot-x] 165 Existing minor versions can be divided into two groups, based on 166 compatibility considerations. NFSv4.0 is one group, while NFSv4.1, 167 NFSv4.2, and potentially other minor versions, form a second group. 168 The definition of NFSv4 minor version groups is explained in more 169 detail in Section 2.3, as is the concept of variants within minor 170 versions and version groups. 172 1.2. Updated NFSv4 Version Management Framework 174 A number of significant changes from previous version management 175 practices should be noted here: 177 o Creation of a new minor version is no longer the only way in which 178 protocol changes may be made. Added optional features and 179 protocol corrections can be proposed, specified and implemented 180 within the context of a single minor version. Creation of new 181 minor versions remains available to make other sorts of changes. 183 o Specification of future minor versions in the way that was done 184 for NFSv4.0 and NFSv4.1 (i.e. as a single document defining the 185 entire protocol) is no longer practical and should not be 186 attempted. All future minor versions will be documented by 187 specifying the differences between the minor version being 188 documented and the previous minor version. The documentation 189 framework discussed in Section 10 should be used. 191 After dealing with some preliminary matters, this document focuses on 192 presenting the conceptual framework on which NFSv4 versioning is 193 built. 195 o First we discuss (in Section 4) how the XDR descriptions for 196 various NFSv4 versions can be extended to produce the XDR 197 descriptions for other versions while allowing clients and servers 198 using the XDR descriptions associated with different versions to 199 communicate. 201 o We then complete the discussion (in Section 5) of the range of 202 protocol changes that NFSv4 versioning is to deal with. 204 o Then we discuss (in Section 6) how those changes are organized 205 into features and feature packages. 207 Using this framework, we look at the ways that those changes can be 208 incorporated into the NFSv4 protocol. 210 o The addition of new feature packages to existing minor versions is 211 discussed in Section 7. 213 o New Minor versions can be constructed, as described in Section 8. 215 o Issues relating to the correction of protocol errors in existing 216 features and minor versions are discussed in Section 9. 218 We then discuss (in Section 10) how features, minor versions, and 219 protocol corrections will be documented. 221 2. Terminology 223 A basic familiarity with NFSv4 terminology is assumed in this 224 document and the reader is pointed to [RFC7530]. 226 In this document, the term "version" is not limited to minor 227 versions. When minor versions are meant, the term "minor version" is 228 used explicitly. For more discussion of this and related terms, see 229 Section 2.3 231 In this document, the word "feature" is used , except in the case of 232 quotations, to denote a key structuring concept. By organizing 233 changes into features, defining RFCs can clearly specify what 234 protocol elements a server must be able to recognize and what 235 protocol elements a server must support. See Section 6 for more 236 which allows the defining RFCs to clearly specify what protocol 237 elements must be supported together by the server and when a given 238 server must be able to correctly interpret the corresponding 239 associated protocol constructs. See Section 6 for more details. 241 A feature contains one or more "feature elements". Often, at least 242 one feature element will be a protocol extension that can help a 243 sender determine whether the receiver supports a given feature. See 244 Section 4.1.3 for more details. A feature element may also be one of 245 a set of other types of protocol change as described in Section 5. 247 A "feature package" is a set of features that are defined together, 248 either as part of a minor version or as part of the same protocol 249 extension. 251 We also need to introduce our vocabulary regarding specification of 252 features and minor versions. Given the ongoing shift to a finer- 253 grained documentation model, it is important to be clear here. 255 o The term "minor version definition document" denotes the principal 256 document defining a specific NFSv4 minor version. It may be in 257 the form of a complete protocol definition (e.g. [RFC7530], 258 [RFC5661]), a specification of changes relative to the previous 259 minor version (e.g. [NFSv42]), or in a document that specifies 260 the features to be included, either by referencing their 261 definition document normatively (see Section 10.6) or implicitly 262 (see Section 7.1). 264 o The term "minor version documentation" includes the minor version 265 definition document but also includes any corresponding XDR 266 definition documents if they are published separately (e.g. 267 [RFC7531], [RFC5662], [NFSv42-dot-x]). Also included are 268 documents separately specifying features newly incorporated in the 269 minor version and the ancillary documents described in 270 Section 10.5. 272 o The term "feature definition document" denotes a document 273 describing a single feature or a set of closely related features, 274 forming a feature package. 276 o The term "protocol definition document" denotes a minor version 277 definition document, a feature definition document or any 278 standards-track document updating one of these. 280 2.1. Use of Keywords Defined in RFC2119 282 The keywords defined by [RFC2119] have special meanings which this 283 document intends to adhere to. However, due to the nature of this 284 document and some special circumstances, there are some complexities 285 to take note of: 287 o Where this document does not directly specify implementation 288 requirements, use of these capitalized terms is often not 289 appropriate, since the guidance given in this document does not 290 directly affect interoperability. 292 o In this document, what authors of RFCs defining features and minor 293 versions need to do is stated without these specialized terms. 294 Although it is necessary to follow this guidance to provide 295 successful NFSv4 version management, that sort of necessity is not 296 of the sort defined as applicable to the use of the keywords 297 defined in [RFC2119]. 299 The fact that these capitalized terms are not used should not be 300 interpreted as indicating that this guidance does not need to be 301 followed or is somehow not important. 303 o In speaking of the possible statuses of features and feature 304 elements, the terms "OPTIONAL" and "REQUIRED" are used. For 305 further discussion, see Section 2.2. 307 o When one of these upper-case keywords defined in [RFC2119] is used 308 in this document, it is in the context of a rule directed to an 309 implementer of NFSv4 minor versions, the status of a feature or 310 protocol element, or in a quotation, sometimes indirect, from 311 another document. 313 2.2. Use of Feature Statuses 315 There has been some confusion, during the history of NFSv4, about the 316 correct use of these terms, and instances in which the keywords 317 defined in [RFC2119] were used in ways that appear to be at variance 318 with the definitions in that document. 320 o In [RFC3530], the lower-case terms "optional", "recommended", and 321 "required" were used as feature statuses, Later, in [RFC5661] and 322 [RFC7530], the corresponding upper-case keywords were used. 323 However, it is not clear why this change was made. 325 o In the case of "RECOMMENDED", its use as a feature status is 326 inconsistent with [RFC2119] and it will not be used for this 327 purpose in this document. 329 o The word "RECOMMENDED" to denote the status of attributes in 330 [RFC3530] and [RFC5661] raises similar issues. This has been 331 recognized in [RFC7530] with regard to NFSV4.0, although the 332 situation with regard to NFSv4.1 remains unresolved. 334 In this document, the keywords "OPTIONAL" and "REQUIRED" and the 335 phrase "mandatory to not implement" are used to denote the status of 336 features and individual protocol elements within a given minor 337 version. In using these terms, RFCs which specify the status of 338 features or protocol elements inform: 340 o client implementations whether they need to deal with the absence 341 of support for the protocol elements 343 o server implementations whether they need to provide support for 344 the protocol elements 346 When the status of a protocol feature is specified, the support 347 requirements for associated protocol elements are defined by the 348 status of the protocol elements with regard to the feature in 349 question as described in Section 6.4. 351 The fact that such statuses and the organization of protocol features 352 may change between minor version groups may raise interoperability 353 issues which the authors of minor version RFCs and the working group 354 need to carefully consider. See Section 8.1.2 for guidance in this 355 regard. 357 2.3. NFSv4 Versions 359 The term "version" denotes any valid protocol variant constructed 360 according to the rules in this document. It includes minor versions, 361 but there are situations which allow multiple variant versions to be 362 associated with and co-exist within a single minor version: 364 o When there are feature specification documents published as 365 Proposed Standards extending a given minor version, then the 366 protocol defined by the minor version specification document, when 367 combined with any subset (not necessarily proper) of the feature 368 specification documents, is a valid NFSv4 version variant which is 369 part of the minor version in question. 371 o When there are protocol corrections published which update a given 372 minor version, each set of published updates, up to the date of 373 publication of the update, is a valid NFSv4 version variant which 374 is part of the minor version in question. 376 Because of the above, there can be multiple version variants that are 377 part of a given minor version. Two of these are worthy of special 378 terms: 380 o The term "base minor version" denotes the version variant that 381 corresponds to the minor version as originally defined, including 382 all protocol elements specified in the minor version definition 383 document but not incorporating any extensions or protocol 384 corrections published subsequently. 386 o At any given time, the term "current minor version" denotes the 387 minor version variant including all extensions of and corrections 388 to the minor version made by standard-track documents published 389 subsequently. 391 Each version variant which is part of a given minor version is a 392 subset of the current minor version and a superset of the base minor 393 version. When the term "minor version" is used without either of 394 these qualifiers, it should refer to something which is true of all 395 variants within that minor version. For example, one may refer the 396 set of REQUIRED features in a given minor version since it is the 397 same for all variants within the minor version. 399 Each client and server which implements a specific minor version will 400 implement some particular variant of that minor version. Each of 401 these will be a superset of the appropriate base minor version. 403 A minor version group is defined as a successive set of minor 404 versions having exactly the same set of REQUIRED and mandatory to not 405 implement protocol elements. The union of the sets of variants for 406 all these minor versions provides a high degree of inter-variant 407 compatibility. Clients and servers which implement variants within 408 this group should be compatible as long as each takes proper care, as 409 it should, to properly deal with the case in which the other party 410 does not know of or has no support for OPTIONAL protocol elements. 412 3. Consolidation of Version Management Rules 414 In the past, the only existing version management rules were the 415 minor versioning rules that had been being maintained and specified 416 in the Standards Track RFCs which defined the individual minor 417 versions. In the past, these minor versioning rules were modified on 418 an ad hoc basis for each new minor version. 420 More recently, minor versioning rules were specified in [RFC5661] 421 while modifications to those rules were allowed in subsequent minor 422 versions. 424 This document defines a set of version management rules, including 425 rules for minor version construction. These rules apply to all 426 future changes to the NFSv4 protocol. The rules are subject to 427 change but any such change should be part of a standards track RFC 428 obsoleting or updating this document. 430 Rather than a single list of minor versioning rules, as in [RFC5661], 431 this document defines multiple sets of rules that deal with the 432 various forms of versioning provided for in the NFSv4 version 433 management framework. 435 o The kinds of changes that may be made are addressed in the rules 436 in Sections 4.1.3, 5.1.3, 5.2.1, and 5.2.2. 438 o Rules relating to the composition of changes into protocol 439 features are addressed in Section 6.2 441 o Rules limiting the protocol features which may be effected as an 442 extension to an existing minor version appear in Section 7. 444 o Minor version construction, including rules applicable to protocol 445 features which cannot be used as extensions to existing minor 446 versions are addressed in Sections 8.1.1 and 8.1.2. 448 o Minor version interaction rules are discussed in Sections 8.3.2, 449 8.3.3, and 8.3.1. 451 This document supersedes minor versioning rules appearing in the 452 minor version specification RFC's, including those in [RFC5661]. As 453 a result, potential conflicts among these documents should be 454 addressed as follows: 456 o The specification of the actual protocols for minor versions 457 previously published as Proposed Standards take precedence over 458 minor versioning rules in either this document or in the minor 459 version specification RFC's. In other words, if the transition 460 from version A to version B violates a minor versioning rule, the 461 version B protocol stays as it is. In particular, many of the 462 changes made for NFSV4.1 would not be allowed in the version 463 management framework defined here. See Section 5.1.3 for details. 465 o Since minor versioning rules #11 and #13 from [RFC5661] deal with 466 the interactions between multiple minor versions, the situation is 467 more complicated. See Section 8.3 for a discussion of these 468 issues, including how potential conflicts between rules are to be 469 resolved. 471 o Otherwise, any conflict between the version management rules in 472 this document and those in minor version specification RFC's are 473 to be resolved based on the treatment in this document. In 474 particular, corrections may be made as specified in Section 9 for 475 all previously specified minor versions and the extensibility of 476 previously specified minor versions is to be handled in accord 477 with Section 7.1. 479 Future minor version specification documents should avoid specifying 480 minor versioning rules and reference this document in connection with 481 rules for NFSv4 version management. 483 4. XDR Considerations 485 As an extensible XDR-based protocol, NFSv4 has to ensure interversion 486 compatibility, in situations in which the client and server use 487 different XDR descriptions. For example, the client may implement 488 different variants of the same minor version or different variants 489 that are part of the same minor version group. The XDR extension 490 paradigm, discussed in Section 4.1, assures that these descriptions 491 are compatible, with clients and servers able to determine and use 492 those portions of the protocol that they both share according to the 493 methods described in Sections 4.4.2 and 4.4.4. 495 4.1. XDR Extension 497 When an NFSv4 version change requires a modification to the protocol 498 XDR, this is effected within a framework based on the idea of XDR 499 extension. This is opposed to transitions between major NFS versions 500 (including that between NFSv3 and NFSv4.0) in which the XDR for one 501 version was replaced by a different XDR for a newer version. 503 The use of XDR extension can facilitate compatibility between 504 different versions of the NFSv4 protocol. When XDR extension is used 505 to implement OPTIONAL features, the greatest degree of inter-version 506 compatibility is obtained. For specifics regarding rules for 507 interversion compatibility, see Section 8.3.2. For a discussion of 508 compatibility issues that might arise between different version 509 groups, see Sections 8.1.2 and 8.3.3. 511 4.1.1. XDR Extension in General 513 The XDR extension approach provides a way for an XDR description to 514 be extended in a way which retains the structure of all previously 515 valid messages. If a base XDR description is extended to create a 516 second XDR description, the following will be true for the second 517 description to be a valid extension of the first: 519 o The set of valid messages described by the extended definition is 520 a superset of that described by the first. 522 o Each message within the set of valid messages described by the 523 base definition is recognized as having exactly the same 524 structure/interpretation using the extended definition. 526 o Each message within the set of messages described as valid by the 527 extended definition but not the base definition must be 528 recognized, using the base definition, as part of an unsupported 529 extension. 531 In general, an extension of a given XDR description consists of any 532 set of the following changes: 534 o Addition of previously unspecified RPC operation codes. 536 o Addition of new, previously unused, values to existing enums. 538 o Addition of previously unassigned bit values to a flag word. 540 o Addition of new cases to existing switches, provided that the 541 existing switch did not contain a default case. 543 However, none of the following may happen: 545 o Deletion of existing RPC operations, enum values, flag bit values 546 and switch cases. Note that changes may be made to define use of 547 any of these as causing an error, as long as the XDR is 548 unaffected. 550 o Similarly, none of these items may be reused for a new purpose. 552 o Any change to the XDR-defined structure of existing requests or 553 replies other than those listed above. 555 4.1.2. Particulars of XDR Extension within NFSv4 557 There are issues, particular to NFSv4, that affect the definition of 558 a valid XDR extension within NFSv4. 560 o Because NFSv4 has been structured around compound requests and 561 callbacks, addition of previously unspecified RPC operation codes 562 is not allowed. 564 o Although they fit under the general category of enumerations, 565 operation codes (including those for callbacks) are so central to 566 the structure of NFSv4, that they merit special treatment. 568 o The fact that attribute value sets are represented within NFSv4 by 569 nominally opaque arrays calls for special handling. 571 4.1.3. Rules for XDR Extension within NFSv4 573 In the context of NFSv4, an extension of a given XDR description 574 consists of one or more of the following: 576 o Addition of previously unspecified operation codes, within the 577 framework established by COMPOUND and CB_COMPOUND. 579 o Addition of previously unspecified attributes. 581 o Addition of new, previously unused, values to existing enums. 583 o Addition of previously unassigned bit values to a flag word. 585 o Addition of new cases to existing switches, provided that the 586 existing switch did not contain a default case. 588 However, none of the following is allowed to happen: 590 o Any change to the structure of existing requests or replies other 591 than those listed above. 593 o Addition of previously unspecified RPC operation codes, for either 594 the nfsv4 program or the callback program, is not allowed. 596 o Deletion of existing RPC operations, enum values, flag bit values 597 and switch cases. Note that changes may be made to define use of 598 any of these as causing an error, as long as the XDR is 599 unaffected. 601 o Similarly, none of these items may be reused for a new purpose. 603 4.2. Handling of Protocol Elements 605 Implementations handle protocol elements in one of three ways. Which 606 of the following ways are valid depends on the status of the protocol 607 element in the variant being implemented: 609 o The protocol element is not a part of definition of the variant in 610 question and so is "unknown". The responder, when it does not 611 report an RPC XDR decode error. reports an error indicative of 612 the element not being defined in the XDR such as 613 NFS4ERR_OP_ILLEGAL, NFS4ERR_BADXDR, or NFS4ERR_INVAL. See 614 Section 4.4.3 for details. 616 o The protocol element is a known part of the variant but is not 617 supported by the particular implementation. The responder reports 618 an error indicative of the element being recognized as one which 619 is not supported such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, 620 or NFS4ERR_ATTRNOTSUPP. See Section 6.5 for details. 622 o The protocol element is a known part of the variant which is 623 supported by the particular implementation. The responder reports 624 success or an error other than the special ones discussed above. 626 Which of these are validly returned by the responder depends on the 627 status of the feature element in the minor version specified in the 628 COMPOUND or CB_COMPOUND. The possibilities which can exist are 629 listed below. 631 o The protocol element is not known in the current variant of minor 632 version. In this case all implementations of the minor version 633 MUST indicate that the protocol element is not known. 635 o The protocol element is specified mandatory to not implement in 636 the minor version. In this case as well, all implementations of 637 the minor version MUST indicate that the protocol element is not 638 known. 640 o The protocol element is defined as part of the current variant of 641 the minor version but is not part of the corresponding base 642 variant. In this case, the requester can encounter situations in 643 which the protocol element is either not known to the responder , 644 is known but not supported by the responder, or is both known to 645 and supported by the responder. 647 o The protocol element is defined as an OPTIONAL part of the base 648 minor version. In this case, the requester can expect the 649 protocol element to be known but must deal with cases in which it 650 is supported or is not supported. 652 o The protocol element is defined as a REQUIRED part of the base 653 minor version. In this case, the requester can expect the 654 protocol element to be both known and supported by the responder. 656 The listing of possibilities above does not mean that a requester 657 always needs to be prepared for all such possibilities. Often, 658 depending on the scope of the feature of which the protocol element 659 is a part, handling of a previous request using the same or related 660 protocol elements, will allow the requester to be sure that certain 661 of these possibilities cannot occur. 663 Requesters, typically clients, may test for knowledge of or support 664 for protocol elements as part of connection establishment. This may 665 allow the requester to be aware of responder lack of knowledge of or 666 support for problematic requests before they are actually issued. 668 4.3. Organization of Protocol Elements 670 To enable compatible operation within a version group, all of the 671 protocol elements within an NFSv4 minor version are organized as 672 follows: 674 o Each protocol element is defined as a member of exactly one 675 feature. One important reason for this organization (see 676 Section 6 for others) is to regularize and simplify the 677 determination by the client and server as to what protocol 678 elements the other party supports. 680 o Each feature is defined as a member of a feature package, based on 681 how it was defined. Features established as part of a minor 682 version at the same time belong to the same feature package. 684 4.4. Inter-version Interoperability 686 Because of NFSv4's use of XDR extension, any communicating client and 687 server versions have XDR definitions that are each valid extensions 688 of a third version. Once that version is determined, it may be used 689 by both client and server to communicate. Each party can 690 successfully use a subset of protocol elements that are both known 691 and supported by both parties. 693 4.4.1. Requirements for Knowledge of Protocol Elements 695 With regard to requirements for knowledge of protocol elements, the 696 following rules apply. These rules are the result of the use of XDR 697 extension paradigm combined with the way in which extensions are 698 incorporated in existing minor versions (for details of which see 699 Section 7.1). 701 o Any protocol element defined as part of the base variant of 702 particular minor version is required to be known by that minor 703 version. This occurs whether the specification happens in the 704 body of the minor definition document or is in a feature 705 definition document that is made part of the minor version by 706 being normatively referenced by the minor version definition 707 document. 709 o Any protocol element required to be known in a given minor version 710 is required to be known in subsequent minor version, unless and 711 until a minor version has made that protocol element as mandatory 712 to not implement. 714 o When a protocol element is defined as part of an extension to an 715 extensible minor version, it is not required to be known in that 716 minor version but is required to be known by the next minor 717 version. In the earlier minor version, it might not be defined in 718 the XDR definition document for that minor, while in the later 719 version it needs to be defined in the XDR definition document. In 720 either case, if it is defined, it might or might not be supported. 722 o When knowledge of protocol elements is optional in a given minor 723 version, the responder's knowledge of such optional elements must 724 obey the rule that if one such element is known, then all the 725 protocol elements defined in the same minor version definition 726 document must be known as well. 728 For many minor versions, all existing protocol elements, are required 729 to be known by both the client and the server, and so requesters do 730 not have to test for the presence or absence of knowledge regarding 731 protocol elements for which knowledge might be optional. This is the 732 case if there has been no extension for the minor version in 733 question. Extensions can be added to extensible minor versions as 734 described in Section 7.1 and can be used to correct protocol flaws as 735 described in Section 9. 737 Requesters can ascertain the knowledge of the responder in two ways: 739 o By issuing a request using the protocol element and looking at the 740 response. Note that, even if the protocol element used is not 741 supported by the responder, the requester can still determine if 742 the element is known by the responder. 744 o By receiving a request from the responder, acting in the role of 745 requester. For example, a client may issue a request enabling the 746 server to infer that it is aware of a corresponding callback. 748 In making this determination, the requester can rely on two basic 749 facts: 751 o If the responder is aware of a single protocol element within a 752 feature package, it must be aware of all protocol elements within 753 that feature package 755 o If a protocol element is one defined by the minor version 756 specified by a request (and not in an extension), or in a previous 757 minor version, the responder must be aware of it. 759 4.4.2. Establishing Interoperability 761 When a client and a server interact, they need to able to take 762 advantage of the compatibility provided by NFSv4's use of XDR 763 extension. 765 In this section, we will deal with situation in which the client and 766 server are of the same version group. Later, in Section 4.4.4, we 767 will discuss possible extensions to the inter-version-group case. 769 In this context, the client and server would arrive at a common 770 variant which the client would uses to send requests which the server 771 would then accept. The server would use that variant to send 772 callbacks which the client would then accept. This state of affairs 773 could arise in a number of ways: 775 o Client and server have been built using XDR variants that belong 776 to the same minor version 778 o The client's minor version is lower than that of the server. In 779 this case the server, in accord with Section 8.3.2, accepts the 780 client's minor version, and acts as if it has no knowledge of 781 extensions made in subsequent minor versions. It has knowledge of 782 protocol elements within the current (i.e. effectively final) 783 variant of the lower minor version. 785 o The client's minor version is higher than that of the server. In 786 this case the client, in accord with Section 8.3.2, uses a lower 787 minor version that the server will accept. In this case, the 788 server has no knowledge of extensions made in subsequent minor 789 versions. 791 There are a number of cases to consider based on the characteristics 792 of the minor version chosen. 794 o The minor version consists of only a single variant (no extension 795 or XDR corrections), so the client and the server are using the 796 same XDR description and have knowledge of the same protocol 797 elements. 799 o When the minor version consists of multiple variants (i.e. there 800 are one or more XDR extensions or XDR corrections), the client and 801 the server are using compatible XDR descriptions. The client is 802 aware of some set of extensions while the server may be aware of a 803 different set. The client can determine which of the extensions 804 that he is aware of, are also known to the server by using the 805 approach described in Section 4.4.3. Once this is done, the 806 client and server will both be using a common variant. The 807 variants that the client and the server were built with will both 808 either be identical to this variant or a valid extension of it. 809 Similarly, the variants that the client and the server actually 810 use will be a subset of this variant, in that certain OPTIONAL 811 features will not be used. 813 In either case, the client must determine which of the OPTIONAL 814 protocol elements within the common version are supported by the 815 server as described in Section 6.6. 817 4.4.3. Determining Knowledge of Protocol Elements 819 A requester may test the responder's knowledge of particular protocol 820 elements as defined below, based on the type of protocol element. 822 o When a GETATTR request is made specifying an attribute bit to be 823 tested and that attribute is not a set-only attribute, if the 824 GETATTR returns with the error NFS4ERR_INVAL, then it can be 825 concluded that the responder has no knowledge of the attribute in 826 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 827 indicate that the responder is aware of the attribute in question. 829 o When a SETATTR request is made specifying the attribute bit to be 830 tested and that attribute is not a get-only attribute, if the 831 SETATTR returns with the error NFS4ERR_INVAL, then it can be 832 concluded that the responder has no knowledge of the attribute in 833 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 834 indicate that the responder is aware of the attribute in question. 836 o When a request is made including an operation with a new flag bit, 837 if the operation returns with the error NFS4ERR_INVAL, then it can 838 generally be concluded that the responder has no knowledge of the 839 flag bit in question, as long as the requester is careful to avoid 840 other error situations in which the operation in question is 841 defined as returning NFS4ERR_INVAL. Other responses indicate that 842 the responder is aware of the flag bit in question. 844 o When a request is made including the operation to be tested, if 845 the responder returns an RPC XDR decode error, or a response 846 indicating that the operation in question resulted in 847 NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded 848 that the responder has no knowledge of the operation in question. 849 Other responses, including NFS4ERR_NOTSUPP, indicate that the 850 responder is aware of the operation in question. 852 o When a request is made including the switch arm to be tested, if 853 the responder returns an RPC XDR decode error, or a response 854 indicating that the operation in question resulted in 855 NFS4ERR_BADXDR, then it can be concluded that the responder has no 856 knowledge of the operation in question. Other responses, 857 including NFS4ERR_UNION_NOTSUPP, indicate that the responder is 858 aware of the protocol element in question. 860 A determination of the knowledge or lack of knowledge of a particular 861 protocol element is expected to remain valid as long as the clientid 862 associated with the request remains valid. 864 The above assumes, as should be the case, that the server will accept 865 the minor version used by the client. For more detail regarding this 866 issue, see Section 8.3.2. 868 4.4.4. Interoperability Between Version Groups 870 Within a minor version group, we have complete compatibility in the 871 sense that: 873 o Servers are REQUIRED to implement a core set of features which 874 cannot change within the minor version group, allowing clients to 875 depend on the continued existence of and support for these 876 features as long as one remains within the minor version group. 878 o The set of OPTIONAL features supported or known by servers may 879 change but clients, in using such OPTIONAL features need to be 880 prepared for the fact that they might not be implemented on all 881 servers implementing a minor version within the same version 882 group. 884 The same level of compatibility is not provided between different 885 minor version groups. Nevertheless, the same guarantees of inter-XDR 886 comprehensibility apply across minor version groups. For a 887 discussion of how this comprehensibility can be used between minor 888 version groups, see Section 8.3.3. 890 5. Other NFSv4 Protocol Changes 892 There are a number of types of protocol changes that are outside the 893 XDR extension framework discussed in Section 4. These changes are 894 also managed within the NFSv4 versioning framework and may be of a 895 number of types, which are discussed in the sections below 897 Each such change will be organized, documented and effected as part 898 of a given feature, just as changes discussed in Section 4 are. The 899 way such features will be incorporated in the NFSv4 protocol depends 900 on a number of factors, including the types of changes included in 901 the feature. This subject is discussed in Sections 6.7 and 7. 903 5.1. Non-XDR Protocol Changes 905 Despite the previous emphasis on XDR changes, additions and changes 906 to the NFSv4 protocols have not been limited to those that involve 907 changes (in the form of extensions) to the protocol XDR. Examples of 908 other sorts of changes have been taken from NFSv4.1. 910 Because these sorts of changes do not involve XDR extensions, it is 911 not possible to use the techniques discussed in Section 4.4.3 to 912 distinguish responders which have the change those which do not. To 913 avoid this situation resulting in implementation incompatibility, all 914 such changes need to be made in a minor version, rather than in an 915 extension with to an existing minor version. 917 5.1.1. Field Interpretation and Use 919 The XDR description of a protocol does not constitute a complete 920 description of the protocol. Therefore, versioning needs to consider 921 the role of changes in the use of fields, even when there is no 922 change to the underlying XDR. 924 Although any XDR element is potentially subject to a change in its 925 interpretation and use, the likelihood of such change will vary with 926 the XDR-specified type of the element, as discussed below: 928 o When XDR elements are defined as strings, rules regarding the 929 appropriate string values are specified in protocol specification 930 text with changes in such rules documented in minor version 931 definition documents. Some types of strings within NFS4 are used 932 in server names (in location-related attributes), user and group 933 names, and in the names of file objects within directories. Rules 934 regarding what strings are acceptable appear in [RFC7530] and 935 [RFC5661] with the role of the XDR limited to hints regarding 936 UTF-8 and capitalization issues via XDR typedefs. 938 o Fields that are XDR-defined as opaque elements and which are truly 939 opaque, do not raise versioning issues, except as regards inter- 940 version use, which is effectively foreclosed by the rules in 941 Section 8.3.1. 943 Note that sometimes a field will seem to be opaque but not 944 actually be fully opaque when considered carefully. For example, 945 the "other" field of stateids is defined as an opaque array, while 946 the specification text specially defines appropriate treatment 947 when the "other" field within it is either all zeros or all ones. 948 Given this context, creation or deletion of reserved values for 949 "special" stateids will be a protocol change which versioning 950 rules need to deal with. 952 o Some nominally opaque elements have external XDR definitions that 953 overlay the nominally opaque arrays. This technique is useful 954 when the same element may be used in several ways when a switched 955 union is not appropriate. 957 For example, each pNFS mapping type provides its own XDR 958 definition for various pNFS-related fields defined in [RFC5661] as 959 opaque arrays. For more information about the handling of pNFS 960 within the NFSv4 versioning framework, see Section 5.2.1. 962 Another form of protocol change that changes how fields are 963 presented, without affecting the XDR occurs when there is a change in 964 the data elements which may be presented as RDMA chunks. 966 5.1.2. Behavioral Changes 968 Changes in the behavior of NFSv4 operations are possible, even if 969 there is no change in the underlying XDR or change to field 970 interpretation and use. 972 One class of behavioral change involves changes in the set of errors 973 to be returned in the event of various errors. When the set of valid 974 requests remain the same, and the behavior for each of them remains 975 the same, such changes can be implemented with only limited 976 disruption to existing clients. 978 Many more substantial behavioral changes have occurred in connection 979 with the addition of the session concept in NFSv4.1. 981 o Because exactly-once is semantics provided by sessions, the use of 982 owner-based sequence values in such operations as OPEN, LOCK, 983 LOCKU are now longer needed and the server is to ignore them. 985 o Because of the requirement to begin almost all COMPOUNDs with a 986 SEQUENCE operation, the semantics of previously defined operations 987 was changed and all formerly valid COMPOUNDs were defined as 988 resulting in errors. 990 o Because the clientid is inferable from a previous SEQUENCE 991 operation, the clientid is not needed in operations such as OPEN 992 and LOCK, and the client is required to pass a value of zero. 994 Also, changes were made regarding the required server behavior as to 995 the interaction of the MODE and ACL attributes. 997 5.1.3. Rules for non-XDR changes 999 In the past (e.g. in [RFC5661]) there was often uncertainty about 1000 whether any particular difference from NFSv4.0 was: 1002 o A purely editorial change, which may be relevant to other minor 1003 versions. 1005 o The correction of a protocol mistake, best handled as described in 1006 Section 9. 1008 o A protocol improvement relevant to a new minor version or feature, 1009 to be documented as described in Section 10.3. 1011 In order to avoid such situations, all such changes will be 1012 documented as part of a feature, specifying the specific changes 1013 relative to protocol versions that do not incorporate that new 1014 feature. As specified in Section 5.1, such changes may not be made 1015 in an extension. 1017 Also, to provide greater clarity about such changes, the following 1018 rules apply to features which include the sort non-XDR changes 1019 described in Sections 5.1.1 and 5.1.2. 1021 o Except for features that only change the set of valid error codes 1022 or prescribe that different error codes are to be returned in 1023 particular situations, feature that include such non-XDR changes 1024 cannot be made REQUIRED at initial introduction. 1026 Since such features are to be OPTIONAL, there needs to be some way 1027 that requester can determine whether the feature is supported by 1028 the responder. This normally take the form of an associated XDR 1029 change, such as an attribute which can be interrogated to 1030 determine if support is present. 1032 o While it is allowed to include multiple such changes in the same 1033 feature this should only be done if there is a good reason for all 1034 of these to be included or not included together. Such changes 1035 should not be included in the same feature simply because all such 1036 changes were introduced in the same minor version. 1038 5.2. Specification of Associated Protocols 1040 The definition of ancillary protocols is a form of protocol extension 1041 that is provided as part of pNFS and might be made available for 1042 other uses in the future. 1044 As in the case of pNFS, the NFSv4 protocol proper would provide the 1045 basic framework for performing some protocol-related task, while 1046 allowing multiple independent means of performing that task to be 1047 defined. The version management considerations appropriate to 1048 creating such additional forms of protocol extension are discussed in 1049 Section 5.2.2 1051 5.2.1. Associated Protocols via pNFS Mapping Types 1053 pNFS is structured around the ability to define alternative mapping 1054 types in addition to the one defined in [RFC5661], (e.g. [RFC5663], 1055 [RFC5664]). Each mapping type specifies the data-transfer protocol 1056 to be used to access data represented by layouts as well as mapping- 1057 type-specific XDR definitions of layout-related data structures. 1059 Specifying a new mapping type is an additional form of protocol 1060 change within the NFSv4 version management framework. A feature 1061 consisting of the new mapping type is not tied to a specific minor 1062 version. As explained in Section 7, if a feature consists only of 1063 that single change, it is available in multiple minor versions upon 1064 publication. 1066 Such a feature has a file system scope and the attribute 1067 fs_layout_type can used to determine whether support is present. 1069 5.2.2. Additional Forms of Associated Protocols 1071 The same sort of approach used for pNFS might be used in other 1072 circumstances where there is a clear need to standardize a set of 1073 protocol-related requirements and where it is desirable, for various 1074 reasons, to leave open the choice of mechanism by which those 1075 requirements might be met. 1077 Such cases might arise where the function to be performed is likely 1078 to be too enmeshed with the structure of the file system 1079 implementation to allow a single protocol mechanism to be specified. 1080 In such cases, multiple approaches might themselves be standardized, 1081 each fitting into a template established previously using any or all 1082 of the elements used by pNFS: 1084 o The establishment of a registry of identifiers for the 1085 standardized mechanisms to satisfy the established requirements. 1087 o Definition of data structures related to the function to be 1088 performed to include both a mechanism identifier, and a nominally 1089 opaque portion, the real format of which is to have a mechanism- 1090 specific definition. 1092 o The ability to specify multiple protocols to perform the same 1093 function, which may include a minor version of NFSv4, a particular 1094 use of an established protocol, or a new protocol designed for the 1095 purpose. 1097 New instances of such a two-level approach might be established in 1098 the future, subject to the following restrictions: 1100 o That there is a template feature establishing the requirements 1101 that the associated protocols are to meet. 1103 o That the template feature is defined as an integral part of a 1104 particular minor version and not as an extension. This does not 1105 exclude this feature being defined in a separate document to which 1106 the minor version specification has a normative reference. 1108 o The template feature defines the scope that the individual feature 1109 instances will have. 1111 o The template feature defines a means by which support for 1112 particular feature instances might be determined by a client. 1114 o That there be at least one instance of a specific protocol 1115 mechanism meeting the established requirements. To limit 1116 confusion, the requirements and the initial mechanism (an instance 1117 of the template feature) should be defined in separate documents. 1119 The above are a minimal set of restrictions for establishing such an 1120 additional extension mechanism. The working group may, as part of 1121 defining the core feature establishing the extension mechanism 1122 specify further restrictions governing as to when minor versions are 1123 allowed to incorporate particular instances of that extension 1124 mechanism. In the absence of such restrictions, particular 1125 extensions will be incorporated, as is the case with pNFS mapping 1126 types, in all minor versions upon publication of the instance as a 1127 Proposed Standard. 1129 6. NFSv4 Protocol Features 1131 Individual changes, whether they are XDR extensions or other sorts of 1132 changes, are organized in term of protocol features. This is in 1133 order to 1135 o allow the protocol documentation to more clearly specify what XDR 1136 extensions and other changes must be supported together. 1138 o help the client determine which particular changes are present and 1139 implemented by the server. 1141 o support the independent development and specification of changes 1142 to the protocol, without artificially tying features together in a 1143 paradigm solely based on minor versions. 1145 o provide support for a feature-based documentation structure, as 1146 described in Section 10.3. 1148 In contrast with some previous uses of the feature concept, every 1149 protocol element is defined as a member of exactly one protocol 1150 feature. 1152 Because support for particular protocol features may depend on 1153 facilities provided by the underlying file systems, or may vary based 1154 on characteristics of the session within which communication is 1155 occurring, each protocol feature will be defined as having a 1156 particular scope, which may be any of the following: 1158 o Client scope in which case support for a given feature is assumed 1159 to be uniform between given client and server as long as neither 1160 reboots. 1162 o Session scope in which case different sessions associated with the 1163 same client may have differences as to feature support but 1164 otherwise support is uniform. 1166 o file system scope in which case different file systems may have 1167 differences as to feature support but otherwise support is 1168 uniform. 1170 6.1. Previous Uses of the Feature Concept 1172 The word "feature" has been used inconsistently in previous documents 1173 bearing on issues related NFSv4 versioning, making it necessary to 1174 offer some clarification here. 1176 o In some cases, the term "feature" is used colloquially 1178 o In some cases, the word "feature" is used to refer to protocol 1179 extensions which are incorporated in the protocol that we refer to 1180 as "protocol elements." The term "feature elements" is similar 1181 but it differs in that it includes changes in field interpretation 1182 and use (Section 5.1.1) and protocol behavior (See Section 5.1.2). 1184 o In some cases the word is used to refer to groups of feature 1185 elements, as defined by tables in [RFC5661] and [NFSv42]. This is 1186 similar to, but not exactly the same as the way we use the word 1187 "feature" is used in this document. 1189 Often, as in previous minor versioning rules, it is not always clear 1190 which sense of the word "feature" is meant. 1192 6.2. Rules for Protocol Feature Construction 1194 A protocol feature consists of one or more valid NFSv4 changes, which 1195 work together as a functional whole. The change elements may be of 1196 any of the types described in Section 5 although the specific types 1197 of changes will affect how the feature can be integrated in the NFSv4 1198 protocol. 1200 A critical distinction in this regard is the one between features 1201 which can added to the protocol without a new minor version and those 1202 which require a new minor version. In this document: 1204 o Features which do not require a new minor version are discussed in 1205 Section 7, while the process of incorporation depends on the type 1206 of features and is discussed in Sections 7.1, 9, 5.2.1, and 5.2.2, 1208 o For handling of the remaining features which do require a new 1209 minor version, see Section 8. 1211 6.3. Statuses of Features 1213 Each feature has one of three statuses with regard to each minor 1214 version of which it might be a part. 1216 o The feature is a REQUIRED part of the minor version. 1218 o The feature is not a REQUIRED part of the minor version, but may 1219 be implemented as part of that version, i.e. it is OPTIONAL 1221 o The feature is not a valid part of the minor version. 1223 For features which have been previously defined as valid, this is 1224 represented as being "mandatory to not implement" as opposed to 1225 simply not being undefined. 1227 These statuses define whether a client implementing the minor version 1228 has to be prepared for the protocol feature's non-support by a server 1229 implementation, even if the feature in question is known by the 1230 server. 1232 The working group is still free to make recommendations regarding the 1233 desirability of server and client support for particular features in 1234 particular minor versions in the minor version definition document, 1235 or in other, presumably informational, documents. 1237 Particular protocol elements have similar statuses, which are derived 1238 from a combination of the status of feature of which the protocol 1239 element, the status of that protocol element within its feature, and, 1240 in some cases, within other supported features. See Section 6.4 for 1241 details. 1243 In addition to feature status, there may be other constraints that 1244 define when an implementation must or may support a feature. In 1245 particular, support for one feature may require support for another, 1246 or the presence of one feature may require that another feature not 1247 be supported. 1249 6.4. Statuses of Protocol Elements Within Features 1251 This section discusses three classes of information that a requester 1252 might use in order to allow it to avoid individually testing the 1253 responder's knowledge of and support for each possible protocol 1254 element. This information includes: 1256 o The grouping of feature elements within features and features 1257 within feature packages. If two feature elements are part of the 1258 same feature or of features within the same feature package, then 1259 each responder which is aware of one must be aware of the other, 1261 o The assignment of status values that allow support for the feature 1262 in which the feature element is defined to be inferred based on 1263 support for the protocol element. This is referred to as the 1264 protocol element's E-to-F status. 1266 o The assignment of status values that allows support for a feature 1267 element to be inferred based on support for the feature. This is 1268 referred to as the protocol element's F-to-E status with regard to 1269 the feature. 1271 The purpose of specifying this information is to allow the knowledge 1272 of and support for one protocol element to be determined based on 1273 responses for others, avoiding the complexity that a client would 1274 have to deal with if each such support decision were independent. A 1275 simpler model would have been to simply assign protocol elements to 1276 feature-based support equivalence classes and require all protocol 1277 elements in a feature to be supported or not supported together. 1278 This approach was not adopted because it is not compatible with many 1279 current and expected feature patterns: 1281 o Many existing protocol features contain protocol elements that are 1282 optional in the context of the feature. 1284 o Some existing protocol elements are used by more than one feature. 1286 o Boolean attributes that indicate the presence of support for a 1287 given feature are tied to that feature, even though the attribute 1288 can be supported when the feature is not, in which case the 1289 attribute is supported and has the value FALSE. 1291 The following are noteworthy E-to-F statuses. 1293 o Support or non-support for the feature is always the same as that 1294 for the protocol element. This is represented as an "IFF" value. 1296 o Lack of support for the feature can be inferred from lack of 1297 support for the protocol element but the reverse can be determined 1298 by using the protocol element to determine whether support for the 1299 feature is present. An example would be a Boolean attribute 1300 indicating whether support for the feature is present. This is 1301 represented as an "SVAL" value. 1303 It needs to be clear how a client may determine whether any 1304 particular OPTIONAL feature is supported. Typically there will be 1305 one or more protocol elements belonging to the feature whose E-F 1306 status is "IFF" or "SVAL". In these cases, support for the protocol 1307 elements in question can be determined as described in Section 6.5 1309 In more complicated cases, the feature specification should clearly 1310 specify how to determine whether support is present. 1312 The following are possible F-to-E statuses. 1314 o Support for the protocol element is REQUIRED when support for the 1315 feature is present. 1317 o Support for the protocol element is OPTIONAL when support for the 1318 feature is present. 1320 o Support for the protocol element is unaffected by the presence of 1321 support for the feature. 1323 The overall status of a feature element within a minor version is 1324 generally determined as follows: 1326 o If there are one or more REQUIRED features which give the protocol 1327 element an F-to-E status of REQUIRED, then the overall status of 1328 the protocol element within the minor version is REQUIRED. 1330 o Otherwise, if there are one or more REQUIRED or OPTIONAL features 1331 which give the protocol element an F-to-E status of REQUIRED or 1332 OPTIONAL, then the overall status of the protocol element within 1333 the minor version is OPTIONAL. 1335 o If neither of the above is true, the protocol element is treated 1336 as not a part of the minor version. That is, it is treated as 1337 mandatory to not implement. 1339 In some cases the overall status may be different from that specified 1340 above. For example, it could be that there were two features, each 1341 of which is OPTIONAL, and it is specified that exactly one of these 1342 must always me supported. In such a case, if both features assign a 1343 protocol element an F-to-E status of REQUIRED, then the overall 1344 status of the protocol element is REQUIRED. 1346 6.5. Determining Protocol Element Support 1348 If it has already been determined that a particular protocol element 1349 is known to the server, the client can determine whether it is 1350 supported based on its type, as follows: 1352 o If the protocol element is an attribute, the supported_attr 1353 attribute can be interrogated to determine if support is present. 1355 o If the protocol element is an operation, the operation can be 1356 attempted, with an error of NFS4ERR_NOTSUPP indicating the 1357 operation is known but not supported. 1359 o If the protocol element is a switch case, use of that case can be 1360 attempted, with an error of NFS4ERR_UNION_NOTSUPP indicating t the 1361 operation is known but not supported. 1363 o If the protocol element is an operation flag bit and the operation 1364 is REQUIRED, use of that flag bit can be attempted with an error 1365 of NFS4ERR_NOTSUPP indicating the protocol element is known but 1366 not supported. 1368 o If the protocol element is an operation flag bit and the operation 1369 defines an error to return in the case of unsupported flag bits, 1370 use if that flag bit can be attempted with the specified error 1371 indicating the operation is known but not supported. 1373 Once this is done, all of the protocol elements the client is aware 1374 of can be divided into three sets: 1376 o Those that the server is unaware of and thus cannot support. 1378 o Those that the server knows about but does not support. 1380 o Those that the server supports. 1382 Information obtained in the process of determining knowledge of 1383 protocol elements (see Section 4.4.3) may be saved and used in 1384 connection with the interrogations above. For example, in testing 1385 for knowledge of a given operation, the specific error code returned 1386 will indicate support or non-support as well as indicating support or 1387 non-support, as well as knowledge of the corresponding operation. 1389 Note that in doing so care needs to be taken regarding protocol 1390 elements associated with features whose scope is more limited than 1391 that of an entire client, since support may be different for 1392 different sessions or different file systems. 1394 6.6. Feature Discovery 1396 In many cases, a client will need to determine whether particular 1397 features are supported before using protocol elements that are part 1398 of those features. While some clients may choose to defer this 1399 determination until the features in question are actually needed, 1400 others may make the determination as part of first connecting with a 1401 server, using a session or accessing a file system, depending on the 1402 scope of the feature in question. 1404 Once such a determination of feature support or non-support are made, 1405 the client may assume that it remains valid and will not change so 1406 long as the object defining the feature scope remains valid. 1408 o For features of client scope as long as the clientid remains 1409 valid. 1411 o For features of session scope as long as the sessionid remains 1412 valid. 1414 o For features of file system scope as long as the clientid and fsid 1415 both remain valid. 1417 In making this determination, the client is entitled to rely on, and 1418 the server is REQUIRED to obey any inter-feature constraints that are 1419 specified as applying to the minor version being used. 1421 The presence or absence of particular features may be determined in a 1422 number of ways: 1424 o For features which are REQUIRED within a given minor version, the 1425 client can treat the fact that the server accepted a request with 1426 that minor version (and did not return 1427 NFS4ERR_MINOR_VERSION_MISMATCH) as indicating that support is 1428 present. 1430 o For features which consist only of the addition of a pNFS layout 1431 type, the fs_layout_type attribute for the fs in question can be 1432 interrogated and scanned for the layout type. 1434 o For features which consist only of the addition of an instance of 1435 a feature template as defined in Section 5.2.2, the template 1436 feature definition will describe the means by which the presence 1437 of support for particular feature instances is to be determined. 1439 For the remaining features, which are all OPTIONAL and contain an 1440 XDR-extending protocol element, the E-to-F statuses of the 1441 constituent protocol elements (see Section 6.4) can be used to 1442 determine if support is present within the scope defined by the 1443 feature in question. In most cases, support for the protocol element 1444 is tested as described in Section 6.5. 1446 o If there are one or more protocol elements whose status is "IFF", 1447 support for any of these may be tested, with the result 1448 determining support for the feature 1450 o If there are one or more protocol elements whose status is "SVAL", 1451 support for it can be tested, and if present the value returned 1452 can be tested as described by the feature specification, resulting 1453 in a determination of support for the feature. 1455 o If there are protocol elements with statuses of "SINF" and 1456 "NSINF", testing of these protocol elements can be used, although, 1457 it is not always certain that testing all such will always resolve 1458 the question. 1460 o If none of these approaches are determinative, the feature 1461 specification should define a method of resolving the question. 1463 Once the set of supported features is determined: 1465 o For protocol elements which have an F-to-E status of REQUIRED for 1466 at least one supported feature, it can be assumed that support is 1467 present. 1469 o For other protocol elements which have an F-to-E status of 1470 OPTIONAL for at least one supported feature, support needs to be 1471 tested for as described in Section 6.5. 1473 o For the remaining protocol elements, it can be assumed that 1474 support is not present. 1476 6.7. Feature Incorporation 1478 All protocol changes will be organized, documented and effected as 1479 part of a given feature. This includes XDR extension and the various 1480 sorts of non-XDR-based changes allowed. 1482 Such features may be made part of the protocol in a number of ways: 1484 o In new minor versions, as discussed in Section 8. 1486 o In separately documented new features. When new features are 1487 OPTIONAL and do not include any non-XDR-based changes, they may be 1488 incorporated in an extensible minor version under construction. 1489 See Section 7.1 for details. 1491 o When appropriate compatibility arrangement are in effect, they may 1492 be used to correct protocol problems in already approved minor 1493 versions and features. See Section 9 for details. 1495 7. Extensions within Minor Versions 1497 The NFSv4 version management framework allows, with certain 1498 restrictions, features to be added to existing minor versions 1500 o In the case of features which consist only of a pNFS mapping type, 1501 the protocol may be extended by publishing the new mapping type 1502 definition as a Proposed Standard. This effects an extension to 1503 all minor versions in which pNFS is a valid feature. 1505 Similar extension facilities could be made available if additional 1506 pNFS-like extension frameworks were created (See Section 5.2.2). 1508 o Minor versions designated as extensible (see Section 7.1) may be 1509 extended by the publication of a standards-track document defining 1510 the additional feature. Details are set out below. The features 1511 to be added are considered OPTIONAL in the extensible minor 1512 version and must consist only of valid XDR-based extensions 1514 7.1. Adding Features to Extensible Minor Versions 1516 Addition of features to an extensible minor version will take 1517 advantage of the existing NFSv4 infrastructure that allows optional 1518 features to be added to new minor versions, but without in this case 1519 requiring any change in the minor version number. Adding features in 1520 this way will enable compatibility with existing clients and servers, 1521 who may be unaware of the new feature. 1523 7.2. Use of Feature Specification Documents 1525 Each such extension will be in the form of a working-group standards- 1526 track document which defines one or more new OPTIONAL features. The 1527 definition of each of the new feature may include one or more 1528 "protocol elements" which extend the existing XDR as already 1529 discussed (in Section 4.1). Other sorts of XDR modification are not 1530 allowed. Protocol elements include new operations, callbacks, 1531 attributes, and enumeration values. The functionality of some 1532 existing operations may be extended by the addition of new flags bits 1533 in existing flag words and new cases in existing switched unions. 1534 New error codes may be added but the set of valid error codes to be 1535 returned by an operation is fixed, except that existing operations 1536 may return new errors to respond to situations that only arise when 1537 previously unused flag bits are set or when extensions to a switched 1538 union are used. 1540 Also, certain additional documents may be produced at this time to 1541 simplify the process of using new versions that contain the 1542 extension, and to help co-ordinate the process of making further 1543 extensions. See Section 10.5 for details. 1545 Each such additional feature will become, for all intents and 1546 purposes, part of the current NFSv4 minor version upon publication of 1547 the description as a Proposed Standard, enabling such extensions to 1548 be used by new client and server implementations without, as 1549 previously required, a change in the value of the minor version field 1550 within the COMPOUND operation. 1552 The working group has two occasions to make sure that such features 1553 are appropriate ones: 1555 o At the time the feature definition document becomes a working 1556 group document, the working group needs to determine, in addition 1557 to the feature's general compatibility with NFSv4, that the XDR 1558 assignments (i.e. additional values for operation callback and 1559 attribute numbers, and for new flags and switch values to be added 1560 to existing operations) associated with the new feature are 1561 complete and do not conflict with those in the existing protocol 1562 or those currently under development. 1564 o At the time the working group document is complete, the working 1565 group, in addition to normal document review, can and should look 1566 at what prototype implementations of the feature have been done 1567 and use that information to determine the work-ability and 1568 maturity of the feature. 1570 7.3. Compatibility Issues 1572 Because the receiver of a message may be unaware of the existence of 1573 a specific extension, certain compatibility rules need to be 1574 observed. In some cases (e.g., addition of new operations or 1575 callbacks or addition of new arms to an existing switched union) 1576 older clients or servers may be unable to do XDR parsing on an 1577 extension of whose existence they are unaware. In other cases (e.g., 1578 error returns) there are no XDR parsing issues but existing clients 1579 and servers may have expectations as to what may validly be returned. 1580 Detailed discussion of these compatibility issues appears below: 1582 o Issues related to messages sent to the server are discussed in 1583 Section 7.3.1. 1585 o Issues related to messages sent to the client are discussed in 1586 Section 7.3.2. 1588 7.3.1. Compatibility Issues for Messages Sent to Servers 1590 This section deals with compatibility issues that relate to messages 1591 sent to the server, i.e., requests and replies to callbacks. In the 1592 case of requests, it is the responsibility of the client to determine 1593 whether the server supports the extension in question before sending 1594 a request containing it for any purpose other than determining 1595 whether the server is aware of the extension. In the case of 1596 callback replies, the server demonstrates its awareness of proper 1597 parsing for callback replies by sending the associated callback. 1599 Regarding the handling of requests: 1601 o Existing server implementations will return NFS4ERR_NOTSUPP or 1602 NFS4ERR_OP_ILLEGAL in response to any use of a new operation, 1603 allowing the client to determine that the requested operation (and 1604 potentially the feature in question) is not known or known but not 1605 supported by the server. 1607 o Clients can determine whether particular new attributes are 1608 supported by a given server by examining the value returned when 1609 the supported_attr attribute is interrogated. Clients need to do 1610 this before attempting to use attributes defined in an extension 1611 since they cannot depend on the server returning 1612 NFS4ERR_ATTRNOTSUPP for requests which include a mask bit 1613 corresponding to a previously unspecified attribute number (as 1614 opposed to one which is defined but unsupported). 1616 o Existing server implementations that do not recognize new flag 1617 bits will return NFS4ERR_INVAL, enabling the client to determine 1618 that the new flag value is not supported by the server. 1620 o Existing server implementations that do not recognize the new arm 1621 of a switched union in a request will return NFS4ERR_INVAL or 1622 NFS4ERR_UNION_NOTSUPP, enabling the client to determine that the 1623 new union arm is not supported by the server. 1625 Regarding the handling of responses to callbacks: 1627 o Error values returned to the server for all callbacks that do not 1628 use new features will only be those previously allowed. Only when 1629 the server uses a new extension feature can a previously invalid 1630 error value be returned. 1632 o Callback replies may only include a new arm of an existing 1633 switched union when the server, typically in the callback being 1634 responded to, has used a feature element associated with the 1635 feature that defined the new switched union arm. 1637 7.3.2. Compatibility Issues for Messages Sent to Clients 1639 This sections deals with compatibility issues that relate to messages 1640 sent to clients, i.e., request replies and callbacks. In both cases, 1641 extensions are only sent to clients that have demonstrated awareness 1642 of the extensions in question by using an extension associated with 1643 the same feature. 1645 Regarding the handling of request replies: 1647 o Error values returned to the client for all requests that do not 1648 use new features will only be those previously allowed. Only when 1649 the server uses a new extension feature can a previously invalid 1650 error value be returned. 1652 o Replies may only include a new arm of an existing switched union 1653 when the server, typically in the request being responded to, has 1654 used a feature element associated with the feature that defined 1655 the new switched union arm. 1657 Regarding the handling of callback requests, the server needs to be 1658 sure that it only sends callbacks to those clients prepared to 1659 receive and parse them. 1661 o In most cases, the new callback will be part of a feature that 1662 contains new (forward) operations as well. When this is the case, 1663 the feature specification will specify the operations whose 1664 receipt by a server is sufficient to indicate that the client 1665 issuing them is prepared to accept and parse the associated 1666 callbacks. 1668 o For callbacks associated with features that have no new operations 1669 defined, the feature specification should define some way for a 1670 client to indicate that it is prepared to accept and parse 1671 callbacks that are part of the extension. For example, a flag bit 1672 in the EXCHANGE_ID request may serve this purpose. 1674 o In both of the above cases, the ability to accept and parse the 1675 specified callback is considered separate from support for the 1676 callback. The feature specification will indicate whether support 1677 for the callback is required whenever the feature is used by the 1678 client. In cases in which support is not required, the client is 1679 free to return NFS4ERR_NOTSUPP upon receiving the callback. 1681 7.4. Relationship Between Minor Versioning and Extensions within a 1682 Minor Version 1684 Extensibility of minor versions are governed by the following rules: 1686 o Minor versions zero and one are not extensible. Each has a fixed 1687 set of OPTIONAL features as described in [RFC7530] and [RFC5661]. 1689 o Minor versions beyond one are presumed extensible as discussed 1690 herein. However, any statement within the minor version 1691 specification disallowing extension will cause that minor version 1692 to be considered non-extensible. 1694 o No new feature may be added to a minor version once the 1695 specification document for a subsequent minor version becomes a 1696 working group standards-track document. 1698 Even when a minor version is non-extensible, or when a previous minor 1699 version is closed to further extension, the features that it contains 1700 are still subject to updates to effect protocol corrections. In many 1701 cases, making an XDR change, in the form of an extension will be the 1702 best way of correcting an issue. See Section 9 for details. 1704 While making minor versions extensible will decrease the frequency of 1705 new minor versions, it will not eliminate the need for them. 1706 Protocol features that cannot be used as extensions (see 1707 Section 8.1.1 require a new minor version. 1709 In addition, change which involve modifications to the set of 1710 protocol elements which are REQUIRED or mandatory to not implement 1711 require a new minor version which starts a new minor version group. 1713 Changes to the organization of protocol features are treated 1714 similarly, since they have a similar potential to cause interversion 1715 incompatibility. See Section 8.1.2 for details. 1717 8. Minor Versions 1719 8.1. Creation of New Minor Versions 1721 It is important to note that this section, in describing situations 1722 that would require new minor versions or minor version groups to be 1723 created, does not thereby imply that situations will exist in the 1724 future. Judgments regarding desirability of future changes will be 1725 made by the working group or its successors and any guidance that can 1726 be offered at this point is necessarily quite limited. 1728 Creation of a new minor version or minor version group is an option 1729 that the working group retains. The listing of situations below that 1730 would prompt such actions is not meant to be exhaustive. 1732 New minor versions are to be documented as described in Section 10.6. 1734 8.1.1. New Minor Versions within an Existing Group 1736 The following sorts of features are not allowed as extensions and 1737 would require creation of a new minor version: 1739 o Features that incorporate any of the non-XDR-based changes 1740 discussed in Sections 5.1.1 and 5.1.2. 1742 o Any feature which includes a new mapping type (as described in 1743 Section 5.2.1) and includes any other change. 1745 To prevent new mapping types from evading this restriction by 1746 splitting the mapping type and other changes into two separate 1747 changes, if new mapping type makes a reference to protocol changes 1748 in an extension, it may not be incorporated in minor versions in 1749 which that extension is defined but only in later minor versions. 1751 o Any feature that creates a new expansion mechanism as described in 1752 in Section 5.2.2. 1754 8.1.2. New Minor Version Groups 1756 The following sorts of changes can only occur in the context of a new 1757 minor version group: 1759 o Addition of REQUIRED new features. 1761 o Changes to the status of existing features including converting 1762 features to be mandatory to not implement. 1764 o Changes to the status of existing feature elements within 1765 features, causing those feature elements to be required or 1766 optional when they previously had not been. 1768 o Changes to the scope of existing features. 1770 o Changes to feature organization or to inter-feature constraints. 1771 Such changes may have the effect of making support for some change 1772 element required or optional in circumstances in which it 1773 previously had not been 1775 Changes to the status or organization of features will, in most case, 1776 result in changes to the status of individual protocol elements, 1777 changing them between REQUIRED and OPTIONAL, or making them mandatory 1778 to not implement. 1780 Conversion of protocol elements to be mandatory to not implement, 1781 will not, as had previously been the practice, result in their 1782 deletion from the protocol XDR. However, the server will be REQUIRED 1783 to treat such protocol elements as not known when responding to 1784 requests within minor versions in which they are not to be 1785 implemented. See Sections 4.4.3 and 8.3.2 for details. 1787 Such changes give rise to potential compatibility issues. In most 1788 cases in which such changes will actually be made, careful 1789 consideration of compatibility issues can limit the scope of such 1790 issues or ensure that compatibility issues actually experienced are 1791 quite limited. 1793 This is opposed to the first new minor version group, that associated 1794 with minor version one, which resulted in a situation in which 1795 clients for minor version zero could not interoperate with servers 1796 for minor version one and vice versa. Issues related to the question 1797 of what to do about such situations are discussed in Section 8.1.3 1799 The addition of REQUIRED features may serve to illustrate the issues. 1800 Such additions pose no compatibility issue for existing clients. On 1801 the other hand, all servers will need to be updated to support the 1802 new features. The effort required and any potential for disruption 1803 depend on the scope of the feature being added. 1805 A number of features introduced as REQUIRED in NFSv4.1 can serve to 1806 illustrate the issues. 1808 o suppattr_exclattr was added as a REQUIRED attribute. This was 1809 very simple for servers to implement. 1811 o RECLAIM_COMPLETE was added as a REQUIRED operation. 1813 o TEST_STATEID and FREE_STATEID were added as REQUIRED operations. 1815 Some examples of potential feature status changes may be helpful in 1816 illustrating compatibility issues 1818 o Converting a REQUIRED feature to be mandatory to not implement 1819 poses the greatest level of difficulty from an interoperability 1820 point of view. Clients need to change to use an alternative means 1821 of providing the functionality provided by the feature. Existing 1822 servers need to be updated, even if there is a replacement feature 1823 available. 1825 Such a transition is only possible without disruption if the 1826 feature in question has already fallen into disuse. 1828 o Converting an OPTIONAL feature to be mandatory to not implement 1829 poses similar difficulties. If clients have ceased to use the 1830 feature, after they have become aware, formally or informally, 1831 that it is moribund, the difficulties can be quite limited. 1833 o Converting a REQUIRED feature to be OPTIONAL poses no difficulty 1834 for existing server implementations. It may pose difficulties for 1835 clients who have not made preparations for server non-support of 1836 the feature. 1838 The degree of such difficulties and the readiness of clients to 1839 make such changes should be key considerations in making such a 1840 state transition. 1842 o Converting an OPTIONAL feature to be REQUIRED poses no difficulty 1843 for existing client implementations. The difficulties for 1844 existing server implementations depend on the scope of the feature 1845 involved and the set of implementations without support for the 1846 feature in question. The degree of such difficulties and the 1847 readiness of servers to make such changes should be key 1848 considerations in making such a state transition. Nevertheless, 1849 it should not be the only consideration. If all existing servers 1850 support the feature, it does not thereby follow that the 1851 transition should be made. The possible effect of making server 1852 development more complicated should also be considered. 1854 A number of other changes allowed only in a new minor version group, 1855 raise analogous issues. 1857 o In the case of inter-feature constraints or similar 1858 reorganizations, the basic issue is whether the client has to deal 1859 with the absence of a protocol element when it previously had not 1860 had to deal with that or the server has to provide support for a 1861 protocol element in situations in which it previously had not had 1862 to. When a set of changes cause both sorts of issues, the 1863 greatest interoperability difficulties arise, making such a set of 1864 changes hard to implement. 1866 o If a feature scope is changed to be more fine-grained, the client 1867 has to deal with combinations of support and non-support it 1868 previously had not had to deal with, while the reverse forces the 1869 server to maintain a unity of support it had previously not had 1870 to. The unlikely case of conversion between session and file 1871 system scope causes difficulties for both parties. 1873 The tradeoff between interoperability issues and desirable changes to 1874 the protocol is one for the working group to make. If the decision 1875 is made to create a new minor version group, the working group has 1876 decided that absolute compatibility is not required. Nevertheless, 1877 it should strive to make necessary changes as non-disruptive as 1878 possible. 1880 8.1.3. Limits on Minor Version Groups 1882 The guidance that needs to be offered with regard to appropriate 1883 limits on changes that form new version groups does not appear 1884 reducible to specific rules. 1886 Instead it is appropriate to return to the basic goal of allowing the 1887 NFSv4 protocol to adapt to future circumstances as they develop. 1888 Although this was not explicitly stated, it seems to be intended that 1889 this would not involve generation of an essentially a new protocol, 1890 even if that were, in some sense, a better one. 1892 So the best way we can address the question of limits on new version 1893 groups is to state that the purpose of the rules in this document, 1894 including the creation of new minor version groups is not the 1895 creation of a successor protocol to NFSv4. 1897 If this or a future working group does find itself defining a new 1898 file access protocol, it would be helpful if proper care were taken 1899 to retain what is valuable in the intellectual heritage of NFSv4. 1900 Nevertheless, in doing so, it is important not to assume that 1901 adherence to the rules in this document, is, in and of itself, a 1902 guarantee that the new protocol is thereby a version of NFSv4. 1904 In dealing with such a future changed situation, the better option 1905 would be to face the issue of necessary change forthrightly and 1906 acknowledge that such a large change creates a fundamentally new 1907 situation. Appropriate responses might include replacing the XDR in 1908 whole or in part, using a successor to XDR, or other means. 1910 8.2. Role of Minor Versions 1912 Clearly, the ability to provide protocol extensions without creation 1913 of a new minor version, has lessened the role of minor versions in 1914 extending the NFSv4 protocol to meet future needs. 1916 We have gone from a situation in which there was a single mechanism, 1917 creation of a new minor version, to extend the protocol, to a three- 1918 level approach: 1920 o OPTIONAL features which extend but do not change protocol 1921 semantics may be added without creating a new minor version. 1923 o Other OPTIONAL features may be added by creating a new minor 1924 version within an existing version group, as long as the sets of 1925 protocol elements which are REQUIRED and mandatory to not 1926 implement. 1928 o Changes which do as the sets of protocol elements which are 1929 REQUIRED and mandatory to not implement are only allowed in a new 1930 minor version group. 1932 This document does explore the situations that, if they arise, would 1933 require the creation of new minor versions or version groups. This 1934 does not imply that such situations will exist or that the working 1935 will choose to address things in that way. Such choices are left for 1936 future decision by the working group and the IESG. 1938 The discussion in Section 8.1.3 raises similar issues. It is 1939 possible that situations might arise that would cause NFSv4 1940 development to be done outside the framework established here. 1941 Nevertheless, this does not imply that such situations will arise. 1943 8.3. Minor Version Interaction Rules 1945 This section addresses issues related to rules #11 and #13 in the 1946 minor versioning rules in [RFC5661]. With regard to the supersession 1947 of minor versioning rules, the treatment here overrides that in 1948 [RFC5661] when either of the potentially interacting minor versions 1949 has not yet been published as a Proposed Standard. 1951 Note that these rules are the only ones directed to minor version 1952 implementers, rather than to those specifying new minor versions. 1954 8.3.1. Minor Version Identifier Transfer Issues 1956 Each relationship between a client instance and a server instance, as 1957 represented by a clientid, is to be devoted to a single minor 1958 version. If a server detects that a COMPOUND with an inappropriate 1959 minor version is being used, it MUST reject the request. In doing 1960 so, it may return either NFS4ERR_BAD_CLIENTID or 1961 NFS4RR_MINOR_VERS_MISMATCH. 1963 As a result of the above, the client has the assurance that the set 1964 of REQUIRED and OPTONAL features will not change within the context 1965 of a single clientid. Server implementations MUST ensure that the 1966 set of supported features and protocol elements does not change 1967 within such a context. 1969 8.3.2. Minor Version Intra-Group Compatibility 1971 Within a set of minor versions that belong to the same minor version 1972 group, it is relatively easy for clients and servers to provides the 1973 needed compatibility by following the following rules. 1975 o Servers supporting a given minor version SHOULD support any 1976 earlier minor version in the same minor version group. If a 1977 server does not do so it will be unable to interoperate with 1978 clients built to interoperate with servers supporting earlier 1979 minor versions, despite the fact that all features expected by the 1980 client are still required of the server and the client is unaware 1981 of added OPTIONAL server added since then. 1983 Servers that do so MUST return appropriate errors for use of 1984 protocol elements that were not a valid part of that earlier minor 1985 version. For details see below. 1987 o Servers supporting a given minor version MUST, in returning errors 1988 for operation which were a valid part of the minor version, return 1989 the errors allowed for the current operation in the minor version 1990 actually being used. 1992 o Clients MUST deal with an NFS4ERR_MINOR_VERS_MISMATCH error by a 1993 searching for a lower minor version number in the same minor 1994 version group that the server will accept. 1996 With regard to protocol elements not known in a given minor version, 1997 the appropriate error codes are given below. Essentially, the 1998 server, although it has a more extensive XDR reflective of a newer 1999 minor version, must act as a server with a more limited XDR would. 2001 o When an operation is used which is not known in the specified 2002 minor version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) 2003 should be returned. 2005 o When an attribute is used which is not known in the specified 2006 minor version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) 2007 should be returned. 2009 o When a switch case is used which is not known in the specified 2010 minor version, NFS4ERR_BADXDR (as opposed to 2011 NFS4ERR_UNION_NOTSUPP) should be returned. Even though the 2012 message may be XDR-decodable by the server's current XDR, it is 2013 not so according to the minor version being used. 2015 o When a flag bit is used which is not known in the specified minor 2016 version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP Or any other 2017 error defined as indicated non-support a flag bit) should be 2018 returned. 2020 8.3.3. Minor Version Inter-Group Compatibility 2022 It is desirable for client and server implementations to support a 2023 wide range of minor versions. The difficulty of doing so can be 2024 affected by choices made by the working group in defining those minor 2025 versions, and the particulars of the changes made which establish new 2026 version groups. 2028 Options for compatibility are affected by the scale and frequency of 2029 the changes which require a new minor version group and the working 2030 group needs to take needs for inter-group compatibility into account 2031 when making such changes. In all cases, the following rules apply: 2033 o Servers supporting a given minor version SHOULD support minor 2034 versions in earlier minor version groups. When doing so, it MUST 2035 behave appropriately given the definition of the minor version 2036 used. For details see below. 2038 o Clients SHOULD deal with an NFS4ERR_MINOR_VERS_MISMATCH error by a 2039 searching for a lower minor version number within the appropriate 2040 minor version range until it finds one that the server will 2041 accept. 2043 In some cases, the server needs to behave as a more restricted one 2044 for an earlier minor version might, despite it having extensions for 2045 protocol elements added in later minor versions. In these cases, the 2046 errors described in Section 8.3.2 should be returned in this case as 2047 well. 2049 In the case in which the earlier version contains protocol elements 2050 subsequently made mandatory to not implement, the server needs to 2051 know of those protocol elements and not return the errors that would 2052 appropriate if the most up-to-date minor version were used. In cases 2053 in which support for these protocol elements is REQUIRED, support 2054 will have to be provided by the server and if it cannot do that, it 2055 MUST return NFS4ERR_MINOR_VERS_MISMATCH for any requests using that 2056 minor version. 2058 In addition to using an appropriate subset of the protocol XDR 2059 definition, the server needs to respect the non-XDR elements of the 2060 earlier minor version group as well. In particular, the serve needs 2061 to: 2063 o Support REQUIRED features as specified by the earlier minor 2064 version group. 2066 o Support (or not) features according to E-to-F statuses specified 2067 by the earlier minor version group. 2069 o Respect the inter-feature constraints specified by the earlier 2070 minor version group. 2072 o Respect the feature scopes specified by the earlier minor version 2073 group. 2075 o Support (or not) protocol elements according to the F-to-E 2076 statuses specified in the earlier minor version group. 2078 9. Correction of Existing Minor Versions and Features 2080 The possibility always exists that there will be a need to correct an 2081 existing feature in some way, after the acceptance of that feature or 2082 a minor version containing it, as a Proposed Standard. While the 2083 working group can reduce the probability of such situations arising 2084 by waiting for running code before considering a feature as done, it 2085 cannot reduce the probability to zero. As features are used more 2086 extensively and interact with other features, previously unseen flaws 2087 may be discovered and will need to be corrected. 2089 Such corrections are best done in a document obsoleting or updating 2090 the RFC defining the relevant feature definition document or minor 2091 version specification. In making such corrections, the working will 2092 have to carefully consider how to assure interoperability with older 2093 clients and servers. 2095 Often, corrections can be done without changing the protocol XDR. In 2096 many cases, a change in client and server behavior can be implemented 2097 without taking special provision with regard to interoperability with 2098 earlier implementations. In those case, and in cases in which a 2099 revision merely clarifies an earlier protocol definition document, a 2100 new document can be published which simply updates the earlier 2101 protocol definition document. Subsequently, the indexing material 2102 would be updated to reflect the existence of the newer document. 2104 In other cases, it is best if client or server behavior needs to 2105 change in a way which raises interoperability concerns. In such 2106 cases, incompatible changes in server or client behavior should not 2107 be mandated in order to avoid XDR changes. 2109 9.1. XDR Changes to Implement Protocol Corrections 2111 When XDR changes are necessary as part of correcting a flaw, these 2112 should be done in a manner similar to that used when implementing new 2113 minor versions or features within them. In particular, 2115 o Existing XDR structures may not be modified or deleted. 2117 o XDR extensions may be used to correct existing protocol facilities 2118 in a manner similar to those used to add additional optional 2119 features. Such corrections may be done in an otherwise non- 2120 extensible minor version, if the working group judges it 2121 appropriate. 2123 o When a correction is made to an OPTIONAL feature, the result is 2124 similar to a situation in which there are two independent OPTIONAL 2125 features. A server may choose to implement either or both. 2127 o When a correction is made to a required feature, the situation 2128 becomes one in which neither the old nor the new version of the 2129 feature is required. Instead, it is required that a server 2130 support at least one of the two, while each is individually 2131 OPTIONAL. Although use of the corrected version is ultimately 2132 better, and may be recommended, it should not be described as 2133 "RECOMMENDED", since the choice of which version to support if 2134 only one is supported will depend on the needs of clients, which 2135 may be slow to adopt the updated version. 2137 o In all of the cases above, it is appropriate that the old version 2138 of the feature, be considered obsolescent, with the expectation 2139 that the working group might, in a later minor version, decide 2140 that the older version is to become mandatory to not implement. 2142 Issues related to the effect of XDR corrections on existing 2143 documents, including co-ordination with other minor versions, are 2144 discussed in Section 10.7. 2146 By doing things this way, the protocol with the XDR modification can 2147 accommodate clients and servers that support either the corrected or 2148 the uncorrected version of the protocol and also clients and servers 2149 aware of and capable of supporting both alternatives. 2151 o A client that supports only the earlier version of the feature 2152 (i.e., an older unfixed client) can determine whether the server 2153 it is connecting to supports the older version of feature. It is 2154 capable of interoperating with older servers that support only the 2155 unfixed protocol as well as ones that support both versions. 2157 o A client that supports only the corrected version of the feature 2158 (i.e., a new or updated client) can determine whether the server 2159 it is connecting to supports the newer version of the feature. It 2160 is capable of interoperating with newer servers that support only 2161 the updated feature as well as ones that support both versions. 2163 o A client that supports both the older and newer version of the 2164 feature can determine which version of the particular feature is 2165 supported by the server it is working with. 2167 o A server that supports only the earlier version of the feature 2168 (i.e., an older unfixed server) can only successfully interoperate 2169 with older clients. However newer clients can easily determine 2170 that the feature cannot be used on that server. 2172 o A server that supports only the newer version of the feature 2173 (i.e., a new or updated server) can only successfully interoperate 2174 with newer clients. However, older clients can easily determine 2175 that the feature cannot be used on that server. In the case of 2176 OPTIONAL features, clients can be expected to deal with non- 2177 support of that particular feature. 2179 o A server that supports both the older and newer versions of the 2180 feature can interoperate with all client variants. 2182 By using extensions in this manner, the protocol creates a clear path 2183 which preserves the functioning of existing clients and servers and 2184 allows client and server implementers to adopt the new version of the 2185 feature at a reasonable pace. 2187 10. Documentation of Features, Extensions, Minor Versions, and Protocol 2188 Corrections 2190 As mentioned previously, NFSv4 is evolving towards a finer-grained 2191 documentation model. This trend will be continued by: 2193 o The use of extensions within minor versions. 2195 o Features that are added by a minor version being documented in 2196 feature definition documents rather than within the minor version 2197 specification itself. 2199 10.1. Documentation Approach 2201 Documentation of future changes to the NFSv4 protocol will use 2202 feature specification documents as described in Section 10.3. There 2203 are a number of ways in which such documents may be used, which 2204 reflect the different ways in which features are incorporated in the 2205 NFSv4 protocol, as discussed in Section 6.7 2207 This documentation approach is intended to avoid the unnecessary 2208 production of large documents in which many unrelated features are 2209 tied together because either: 2211 o The entire protocol is described in a single document, as happened 2212 with NFSv4.0 (in [RFC7530]) and NFSv4.1 (in [RFC5661]). 2214 o Many unrelated features are described in a single document as 2215 occurred with NFSv4.2 (in [NFSv42]). 2217 The production of a larger number of smaller documents will 2218 streamline document production and review. A potential problem is 2219 that a profusion of smaller documents might cause difficulty for 2220 those learning about and implementing the protocol. 2222 The production of indexing material described in Section 10.2 is 2223 intended to limit such difficulties. The result will be that, for 2224 operations and attributes, we will have essentially a single table of 2225 contents, referencing material from multiple minor version definition 2226 documents and feature specification documents. 2228 10.2. Indexing material 2230 The items listed below, referred to collectively as "Indexing 2231 material" will be useful in many contexts. The reason for frequently 2232 publishing such material is to prevent a situation in which large 2233 numbers of documents must be scanned to find the most current 2234 description of a particular protocol element. 2236 o A table mapping operations and callbacks to the most recent 2237 protocol definition document containing a description of that 2238 operation. 2240 o A table mapping attributes to the most recent protocol definition 2241 document containing a description of that attribute. 2243 o A table giving, for each operation in the protocol, the errors 2244 that may validly be returned for that operation. If possible, it 2245 would be desirable to give, as does [RFC5661], the operations 2246 which may validly return each particular error. 2248 o A table giving for each operation, callback, and attribute and for 2249 each feature element in a published extension giving its status 2250 (REQUIRED, OPTIONAL, or mandatory-to-not implement), the name of 2251 the feature of which it is a part, its associated E-to-F and 2252 F-to-E status values and information about other features for 2253 which it has a non-empty F-to-E status value. This would be 2254 similar to the material in Section 14 of [NFSv42], expanded to 2255 include all feature elements. 2257 10.3. Feature Specification Documents 2259 Features will be documented in the form of a working-group standards- 2260 track document which define one or more features. Generally, only 2261 closely related features should be defined in the same document. 2263 The definition of each of the new features may include one or more 2264 "feature elements" which change the protocol in any of the ways 2265 discussed in Section 5. Feature elements include new operations, 2266 attributes, and enumeration values. Note that in this context, 2267 "Operations" include both forward and callback operations. The 2268 functionality of some existing operations may be extended by the 2269 addition of new flags bits in existing flag words, by new cases in 2270 existing switched unions, and by valid semantic changes to existing 2271 operations. 2273 Such feature definition documents would contain a number of items, 2274 following the pattern of the NFSv4.2 specification. The only 2275 difference would be that while the NFSv4.2 specification defines a 2276 number of features to be incorporated into NFSv4.2, the feature 2277 definition documents would each define a single feature, or a small 2278 set of closely related features. 2280 In addition to a general explanation of the feature(s) in question, 2281 the items to be included in such feature definition documents would 2282 be as listed below. In some cases these items, in addition to 2283 descriptive text, would contain fragments of XDR code, to aid in 2284 preparation of XDR files that include the additions defined by the 2285 feature added to the base protocol that is being extended. For 2286 information regarding preparation of such XDR files, see 2287 Section 10.4. 2289 o Description of new operations (corresponding to Sections 15 and 16 2290 of [NFSv42]). Such descriptions will contain XDR code defining 2291 the structure the arguments and results of the new operation along 2292 with preparatory XDR definitions used only by that operation. 2294 o Description of any modified operations (corresponding to 2295 Section 15 of [NFSv42]). Such description may contain XDR code 2296 defining the new flag bits, enum values, and cases to be added to 2297 existing switched unions. Note that addition of new attributes is 2298 not considered an extension of GETATTR, SETATTR, VERIFY, or 2299 NVERIFY. 2301 o Description of new attributes (corresponding to Section 13 of 2302 [NFSv42]). XDR code defining the types of the attributes would be 2303 part of this description. 2305 o Description of any added error codes (corresponding to 2306 Section 12.1 of [NFSv42]). 2308 o All operation descriptions, whether for new or modified 2309 operations, should indicate when operations or the corresponding 2310 results may be presented as RDMA chunks. 2312 o A set of XDR code fragments giving the numeric values of added 2313 operation codes, attribute numbers, and error codes. 2315 o Descriptions of all other extensions made to existing flag words, 2316 enums and switched unions used by existing operations. Such 2317 descriptions will contain XDR code defining the new flag bits, 2318 enum values, and cases to be added to existing switched unions. 2320 o Descriptions of all new structures, enums, flag words, and 2321 switched unions that are used by more than one new operation, or 2322 which are available for future use by multiple operations. Such 2323 descriptions will contain XDR code defining the new structures/ 2324 union and assigning the new numeric values for enum and flag bits. 2326 o A listing giving the valid errors for each new operation and 2327 callback (corresponds to Sections 12.2 and 12.3 of [NFSv42]). 2329 o For each feature, a table giving for each feature element that is 2330 part of the feature, its overall status within the minor version 2331 and its E-to-F and F-to-E status values. This would be similar to 2332 the material in Section 14 of [NFSv42] but restricted to the 2333 feature(s) defined in the document and expanded to include all 2334 feature elements. 2336 o A table presenting support requirement for each protocol element 2337 which is either a part of a feature defined in the document or has 2338 an F-to-E status with relation with a feature defined in the 2339 document. This could present the F-to-E status value for each 2340 relevant combination of feature element and feature. An 2341 alternative presentation would give, for each protocol element, 2342 boolean expressions in term of supported features, that allows or 2343 that guarantees support for the specified element. 2345 o All of the additional Sections required for RFC publication, such 2346 as "Security Considerations", "IANA considerations", etc. 2348 Note that the listing above is not intended to define, in detail, the 2349 structure of the specification. Rather, the intention is to define 2350 the things it needs to contain. If there would be no content for a 2351 particular element, there is no need for an empty section 2352 corresponding to that list element. If it makes more sense to 2353 describe a new structure together with an extended one, then the need 2354 for a readily understandable document is primary. 2356 10.4. XDR File Considerations 2358 As mentioned previously, feature specification documents will 2359 contain, in addition to description of XDR extensions, XDR code 2360 fragments that embody those extensions. There will be various 2361 occasions on which people will have occasion to produce XDR files 2362 that combine one or more extensions together with the XDR for an 2363 existing minor version. 2365 o When a minor version is specified by a number of feature 2366 specification documents, there will be a need to produce, in as 2367 simple fashion as possible, the corresponding XDR specification 2368 document for the new minor version. 2370 o Within an extensible minor version, there will be a need for those 2371 developing and testing the feature to have an XDR file that 2372 incorporates XDR definitions from early drafts of the feature 2373 specification document. 2375 o Also, for an extensible minor version, there will be a need to 2376 periodically produce Consolidated XDR documents that reflect all 2377 features approved as Proposed Standards and thus incorporated in 2378 the current minor version. 2380 o Developers may need to be able to produce XDR files that reflect 2381 particular combination of approved features, features under 2382 development or experimental features not yet ready for working 2383 group consideration. 2385 We are assuming here that the primary task is producing XDR files and 2386 that corresponding XDR documents can be produced relatively easily if 2387 there is a well understood process to produce the underlying XDR 2388 files. 2390 The Feature specification document should contain all of the 2391 necessary lines of XDR codes to be added to a base XDR file to effect 2392 the extension. The only remaining issue is where to place each 2393 addition to arrive at the correct consolidated file. 2395 o One could rely on those preparing updated XDR file to place the 2396 additional XDR code lines in the appropriate place, based on 2397 inference from the document text. 2399 o One could rely on the Feature Specification Document to indicate, 2400 in the descriptive text, where each XDR extension is to be placed. 2402 o One could formalize a set of conventions whereby the appropriate 2403 placements are indicated by specific instructions embedded within 2404 comments within the XDR code fragments to be placed. 2406 10.5. Additional Documents to Support Protocol Extension 2408 Additional documents will be required from time to time. These 2409 documents will eventually become RFC's (informational or standards 2410 track as described below), but the work of the working group and of 2411 implementers developing features will be facilitated by a progression 2412 of document drafts that incorporate information about new features 2413 that are being developed or have been approved as Proposed Standards. 2415 10.5.1. Minor Version Indexing Document 2417 One document will organize existing material for a minor version 2418 undergoing extension so that implementers will not have to scan a 2419 large set of feature definition documents or minor version 2420 specifications to find information being sought. Successive drafts 2421 of this document will serve as an index to the current state of the 2422 extensible minor version. Some desirable elements of this indexing 2423 document would include: 2425 o A list of all feature definition documents that have been approved 2426 as working group documents but have not yet been approved as 2427 Proposed Standards. 2429 o All of the items of indexing material (see Section 10.2) 2430 appropriately adjusted to reflect the contents of all extensions 2431 accepted as Proposed Standards. 2433 The frequency of updates for this document will be affected by 2434 implementer needs and the ability to easily generate document drafts, 2435 preferably by automated means. The most desirable situation is one 2436 in which a new draft is available soon after each feature reaches the 2437 status of a Proposed Standard. 2439 10.5.2. Consolidated XDR Document 2441 This document will consist of an updated XDR for the protocol as a 2442 whole including feature elements from all features and minor versions 2443 accepted as Proposed Standards. 2445 A new draft should be prepared whenever a new feature within an 2446 extensible minor version is accepted as a Proposed Standard. In most 2447 cases, feature developers will be using a suitable XDR which can then 2448 be reviewed and published. In cases in which multiple features reach 2449 Proposed Standard status at approximately the same time, a merge of 2450 the XDR changes made by each feature may be necessary. 2452 10.5.3. XDR Assignment Document 2454 This document will contain consolidated lists of XDR value 2455 assignments that are relevant to the protocol extension process. It 2456 should contain lists of assignments for: 2458 o operation codes (separate lists for forward operations and for 2459 callbacks) 2461 o attribute numbers 2463 o error codes 2465 o bits within flag words that have been extended since they were 2466 first introduced. 2468 o enumeration values for enumerations which have been extended since 2469 they were first introduced. 2471 For each set of assignments, the individual assignments may be of 2472 three types: 2474 1. permanent assignments associated with a minor version or a 2475 feature extension that has achieved Proposed Standard status. 2477 These assignments are permanent in that the assigned value will 2478 never be re-used. However, a subsequent minor version may define 2479 some or all feature elements associated with a feature to be 2480 mandatory to not implement. 2482 2. provisional assignments associated with a feature under 2483 development (i.e., one which has been approved as a working group 2484 document but has not been approved as a Proposed Standard). 2486 Provisional assignments are not are not permanent and the values 2487 assigned can be re-used in certain circumstances. In particular, 2488 when a feature with provisional assignments is not progressing 2489 toward the goal of eventual Proposed Standard status, the working 2490 group can judge the feature effort to have been abandoned, 2491 allowing the codes formerly provisionally allocated to be 2492 reclaimed and reassigned. 2494 3. definition of individual assignments or ranges reserved for 2495 experimental use. 2497 A new draft of this document should be produced, whenever: 2499 o A minor version or feature specification is accepted as a Proposed 2500 Standard. 2502 o A new feature is accepted for development and a draft of the 2503 corresponding working-group standards-track document is produced 2505 o A feature previously accepted for development is abandoned. 2507 o The working group decides to make some change in assignments for 2508 experimental use. 2510 10.5.4. Transition of Documents to RFC's 2512 Each of these documents should be published as an RFC soon after the 2513 minor version in question ceases to be considered extensible. 2514 Typically this will happen when the working group makes the 2515 specification for the subsequent minor version into a working group 2516 document. Some specifics about the individual documents are listed 2517 below: 2519 o The most current draft of the indexing document for the minor 2520 version would be published as an informational RFC. 2522 o The most current draft of the consolidated XDR document should be 2523 published as a standards-track RFC. It would update the initial 2524 specification of the minor version 2526 o The most recent draft of the XDR assignment document should be 2527 published as an informational RFC. 2529 Handling of these documents in the event of a post-approval XDR 2530 correction is discussed in Section 10.7 2532 10.6. Documentation of New Minor Versions 2534 Minor versions should be documented by specifying and explaining the 2535 changes made relative to the previous minor version. 2537 Features added to the minor version should be documented in their own 2538 feature specification documents and normatively referenced. 2540 Changes to the status or organization of existing features should be 2541 documented by presenting a summary of the status of all existing 2542 protocol elements, their relationship to OPTIONAL features, and any 2543 relevant feature dependencies. 2545 In addition, to avoid situation where a large number of minor 2546 versions must be scanned to find the most recent valid treatment of a 2547 specific protocol element, minor version definition documents will 2548 contain the indexing material described in Section 10.2. 2550 10.7. Documentation of XDR Changes for Corrections 2552 In the event of an XDR correction, as discussed above, some document 2553 updates will be required. For the purposes of this discussion we 2554 call the minor version for which XDR correction is required minor 2555 version X and the minor version on which development is occurring 2556 minor version Y. 2558 The following discusses the specific updated documents which could be 2559 required: 2561 o The specification of the feature in question will have to be 2562 updated to explain the issue, how it was fixed, and the 2563 compatibility and upgrade strategy. Normally this will require an 2564 RFC updating the associated feature specification document. 2565 However, in the case of a correction to a feature documented in a 2566 minor version definition document, the RFC will update that 2567 document instead. 2569 o An updated XDR for minor version X will be produced and will be 2570 published as a updated to the minor version specification RFC for 2571 minor version X. 2573 When the correction is to feature documented in a minor version 2574 definition, a single RFC will contain both updates to the minor 2575 version specification RFC. 2577 o An updated minor version indexing document for minor version X is 2578 desirable but not absolutely necessary. 2580 The question of updated minor version indexing documents for minor 2581 versions between X and Y should be addressed by the working group 2582 on a case-by-case basis. 2584 o An updated XDR assignment document will be required. It should be 2585 based on the most recent such document associated with minor 2586 version Y and will serve as the basis for later XDR assignment 2587 drafts for minor version Y. 2589 The informational RFC's associated with minor version Y (version 2590 indexing document and XDR assignment document) will contain the 2591 effects of the correction when published. Similarly, the minor 2592 version specification RFC will contain the XDR changes associated 2593 with the correction. 2595 11. Security Considerations 2597 Since no substantive protocol changes are proposed here, no security 2598 considerations apply. 2600 As features and minor versions are designed and specified in 2601 standards-track documents, their security issues will be addressed 2602 and each RFC candidate will receive the appropriate security review 2603 from the NFSv4 working group and IESG. 2605 12. IANA Considerations 2607 The current document does not require any actions by IANA. 2609 Depending on decisions that the working group makes about how to 2610 address the issues raised in this document, future documents may 2611 require actions by IANA. 2613 13. References 2615 13.1. Normative References 2617 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2618 Requirement Levels", BCP 14, RFC 2119, 2619 DOI 10.17487/RFC2119, March 1997, 2620 . 2622 13.2. Informative References 2624 [NFSv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", January 2625 2016, . 2628 Work in progress. 2630 [NFSv42-dot-x] 2631 Haynes, T., Ed., "NFS Version 4 Minor Version 2 Protocol 2632 External Data Representation Standard (XDR) Description", 2633 January 2016, . 2636 Work in progress. 2638 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2639 Beame, C., Eisler, M., and D. Noveck, "Network File System 2640 (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530, 2641 April 2003, . 2643 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 2644 "Network File System (NFS) Version 4 Minor Version 1 2645 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, 2646 . 2648 [RFC5662] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 2649 "Network File System (NFS) Version 4 Minor Version 1 2650 External Data Representation Standard (XDR) Description", 2651 RFC 5662, DOI 10.17487/RFC5662, January 2010, 2652 . 2654 [RFC5663] Black, D., Fridella, S., and J. Glasgow, "Parallel NFS 2655 (pNFS) Block/Volume Layout", RFC 5663, 2656 DOI 10.17487/RFC5663, January 2010, 2657 . 2659 [RFC5664] Halevy, B., Welch, B., and J. Zelenka, "Object-Based 2660 Parallel NFS (pNFS) Operations", RFC 5664, 2661 DOI 10.17487/RFC5664, January 2010, 2662 . 2664 [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 2665 (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, 2666 March 2015, . 2668 [RFC7531] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 2669 (NFS) Version 4 External Data Representation Standard 2670 (XDR) Description", RFC 7531, DOI 10.17487/RFC7531, March 2671 2015, . 2673 Appendix A. Acknowledgements 2675 The author wishes to thank Tom Haynes of Primary Data for his role in 2676 getting this effort started and his work in co-authoring the first 2677 version of this document. 2679 The author also wishes to thank Chuck Lever and Mike Kepfer of Oracle 2680 for their thorough document reviews and many helpful suggestions. 2682 Author's Address 2684 David Noveck 2685 Hewlett Packard Enterprise 2686 165 Dascomb Road 2687 Andover, MA 01810 2688 US 2690 Phone: +1 978 474 2011 2691 Email: davenoveck@gmail.com