idnits 2.17.1 draft-ietf-nfsv4-versioning-06.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 (September 7, 2016) is 2788 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 normative reference: RFC 5661 (Obsoleted by RFC 8881) -- Obsolete informational reference (is this intentional?): RFC 3530 (Obsoleted by RFC 7530) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 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) September 7, 2016 5 Intended status: Standards Track 6 Expires: March 11, 2017 8 Rules for NFSv4 Extensions and Minor Versions. 9 draft-ietf-nfsv4-versioning-06 11 Abstract 13 This document describes the rules relating to the extension of the 14 NFSv4 family of protocols. It covers the creation of minor versions, 15 the 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 March 11, 2017. 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 3 58 2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 4 59 2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 5 60 3. Consolidation of Extension Rules . . . . . . . . . . . . . . 6 61 4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 7 63 4.2. Rules for XDR Extension within NFSv4 . . . . . . . . . . 8 64 4.3. Handling of Protocol Elements . . . . . . . . . . . . . . 9 65 4.4. Inter-version Interoperability . . . . . . . . . . . . . 10 66 4.4.1. Requirements for Knowledge of Protocol Elements . . . 10 67 4.4.2. Establishing Interoperability . . . . . . . . . . . . 12 68 4.4.3. Determining Knowledge of Protocol Elements . . . . . 13 69 4.5. XDR Overlay . . . . . . . . . . . . . . . . . . . . . . . 14 70 5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 14 71 5.1. Field Interpretation and Use . . . . . . . . . . . . . . 15 72 5.2. Behavioral Changes . . . . . . . . . . . . . . . . . . . 15 73 6. Extending Existing Minor Versions . . . . . . . . . . . . . . 16 74 7. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 16 75 7.1. Creation of New Minor Versions . . . . . . . . . . . . . 16 76 8. Minor Version Interaction Rules . . . . . . . . . . . . . . . 17 77 8.1. Minor Version Identifier Transfer Issues . . . . . . . . 17 78 8.2. Minor Version Compatibility . . . . . . . . . . . . . . . 17 79 9. Correction of Existing Minor Versions and Features . . . . . 18 80 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 19 81 10. Security Considerations . . . . . . . . . . . . . . . . . . . 20 82 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 83 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 84 12.1. Normative References . . . . . . . . . . . . . . . . . . 21 85 12.2. Informative References . . . . . . . . . . . . . . . . . 21 86 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 21 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 89 1. Introduction 91 To address the requirement for an NFS protocol that can evolve as the 92 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 93 provides a framework to allow for future changes via the creation of 94 new protocol versions including minor versions and certain forms of 95 modification of existing minor versions. The extension rules 96 contained in this document allow extensions and other changes to be 97 implemented in a way that maintains compatibility with existing 98 clients and servers. 100 Previously, all protocol changes had been part of new minor versions. 101 The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the 102 minor version being used by the client in making requests. The 103 CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) specifies the 104 minor version being used by the server on callback requests. 106 Creation of a new minor version is no longer the only way in which 107 protocol changes may be made. Optional features may be added as 108 extensions and protocol corrections can be proposed, specified and 109 implemented within the context of a single minor version. Creation 110 of new minor versions remains available to make other sorts of 111 changes. 113 The goal of allowing extensions within the context of a minor version 114 is provide more implementation flexibility while preserving 115 interoperability on protocol upgrade. As described in Section 4.4, 116 two implementations can each choose to implement a subset of 117 available extensions, enabling interoperation to proceed just as if 118 both implementations supported only the parts of the protocol they 119 both support. 121 2. Terminology 123 A basic familiarity with NFSv4 terminology is assumed in this 124 document and the reader is pointed to [RFC7530]. 126 In this document, the term "version" is not limited to minor 127 versions. When minor versions are meant, the term "minor version" is 128 used explicitly. For more discussion of this and related terms, see 129 Section 2.3 131 A "feature package" is a set of features that are defined together, 132 either as part of a minor version or as part of the same protocol 133 extension. 135 2.1. Use of Keywords Defined in RFC2119 137 The keywords defined by [RFC2119] have special meanings which this 138 document intends to adhere to. However, due to the nature of this 139 document and some special circumstances, there are some complexities 140 to take note of: 142 o Where this document does not directly specify implementation 143 requirements, use of these capitalized terms is often not 144 appropriate, since the guidance given in this document does not 145 directly affect interoperability. 147 o In this document, what authors of RFCs defining features and minor 148 versions need to do is stated without these specialized terms. 149 Although it is necessary to follow this guidance to provide 150 successful NFSv4 protocol extension, that sort of necessity is not 151 of the sort defined as applicable to the use of the keywords 152 defined in [RFC2119]. 154 The fact that these capitalized terms are not used should not be 155 interpreted as indicating that this guidance does not need to be 156 followed or is somehow not important. 158 o In speaking of the possible statuses of features and feature 159 elements, the terms "OPTIONAL" and "REQUIRED" are used. For 160 further discussion, see Section 2.2. 162 o When one of these upper-case keywords defined in [RFC2119] is used 163 in this document, it is in the context of a rule directed to an 164 implementer of NFSv4 minor versions, the status of a feature or 165 protocol element, or in a quotation, sometimes indirect, from 166 another document. 168 2.2. Use of Feature Statuses 170 There has been some confusion, during the history of NFSv4, about the 171 correct use of these terms, and instances in which the keywords 172 defined in [RFC2119] were used in ways that appear to be at variance 173 with the definitions in that document. 175 o In [RFC3530], the lower-case terms "optional", "recommended", and 176 "required" were used as feature statuses, Later, in [RFC5661] and 177 [RFC7530], the corresponding upper-case keywords were used. It is 178 not clear why this change was made. 180 o In the case of "RECOMMENDED", its use as a feature status is 181 inconsistent with [RFC2119] and it will not be used for this 182 purpose in this document. 184 o The word "RECOMMENDED" to denote the status of attributes in 185 [RFC7530] and [RFC5661] raises similar issues. This has been 186 recognized in [RFC7530] with regard to NFSV4.0, although the 187 situation with regard to NFSv4.1 remains unresolved. 189 In this document, the keywords "OPTIONAL" and "REQUIRED" and the 190 phrase "mandatory to not implement" are used to denote the status of 191 features within a given minor version. In using these terms, RFCs 192 which specify the status of features inform: 194 o client implementations whether they need to deal with the absence 195 of support for these features. 197 o server implementations whether they need to provide support for 198 these features. 200 2.3. NFSv4 Versions 202 The term "version" denotes any valid protocol variant constructed 203 according to the rules in this document. It includes minor versions, 204 but there are situations which allow multiple variant versions to be 205 associated with and co-exist within a single minor version: 207 o When there are feature specification documents published as 208 Proposed Standards extending a given minor version, then the 209 protocol defined by the minor version specification document, when 210 combined with any subset (not necessarily proper) of the feature 211 specification documents, is a valid NFSv4 version variant which is 212 part of the minor version in question. 214 o When there are protocol corrections published which update a given 215 minor version, each set of published updates, up to the date of 216 publication of the update, is a valid NFSv4 version variant which 217 is part of the minor version in question. 219 Because of the above, there can be multiple version variants that are 220 part of a given minor version. Two of these are worthy of special 221 terms: 223 o The term "base minor version" denotes the version variant that 224 corresponds to the minor version as originally defined, including 225 all protocol elements specified in the minor version definition 226 document but not incorporating any extensions or protocol 227 corrections published subsequently. 229 o At any given time, the term "current minor version" denotes the 230 minor version variant including all extensions of and corrections 231 to the minor version made by standard-track documents published 232 subsequently. 234 Each version variant which is part of a given minor version is a 235 subset of the current minor version and a superset of the base minor 236 version. When the term "minor version" is used without either of 237 these qualifiers, it should refer to something which is true of all 238 variants within that minor version. For example, one may refer to 239 the set of REQUIRED features in a given minor version since it is the 240 same for all variants within the minor version. 242 Each client and server which implements a specific minor version will 243 implement some particular variant of that minor version. Each of 244 these will be a superset of the appropriate base minor version. 246 3. Consolidation of Extension Rules 248 In the past, the only existing extension rules were the minor 249 versioning rules that were being maintained and specified in the 250 Standards Track RFCs which defined the individual minor versions. In 251 the past, these minor versioning rules were modified on an ad hoc 252 basis for each new minor version. 254 More recently, minor versioning rules were specified in [RFC5661] 255 while modifications to those rules were allowed in subsequent minor 256 versions. 258 This document defines a set of extension rules, including rules for 259 minor version construction. These rules apply to all future changes 260 to the NFSv4 protocol. The rules are subject to change but any such 261 change should be part of a standards track RFC obsoleting or updating 262 this document. 264 Rather than a single list of extension rules, as was done in the 265 minor versioning rules in [RFC5661], this document defines multiple 266 sets of rules that deal with the various forms of protocol change 267 provided for in the NFSv4 extension framework. 269 o The kinds of XDR changes that may be made to extend NFSv4 are 270 addressed in the rules in Section 4.2. 272 o Minor version construction, including rules applicable to changes 273 which cannot be made in extensions to existing minor versions are 274 addressed in Section 7.1 276 o Minor version interaction rules are discussed in Sections 8.1 and 277 8.2. 279 This document supersedes minor versioning rules appearing in the 280 minor version specification RFC's, including those in [RFC5661]. As 281 a result, potential conflicts among documents should be addressed as 282 follows: 284 o The specification of the actual protocols for minor versions 285 previously published as Proposed Standards take precedence over 286 minor versioning rules in either this document or in the minor 287 version specification RFC's. In other words, if the transition 288 from version A to version B violates a minor versioning rule, the 289 version B protocol stays as it is. 291 o Since minor versioning rules #11 and #13 from [RFC5661] deal with 292 the interactions between multiple minor versions, the situation is 293 more complicated. See Section 8 for a discussion of these issues, 294 including how potential conflicts between rules are to be 295 resolved. 297 o Otherwise, any conflict between the extension rules in this 298 document and those in minor version specification RFC's are to be 299 resolved based on the treatment in this document. In particular, 300 corrections may be made as specified in Section 9 for all 301 previously specified minor versions and the extensibility of 302 previously specified minor versions is to be handled in accord 303 with Section 6. 305 Future minor version specification documents should avoid specifying 306 rules relating to minor versioning and reference this document in 307 connection with rules for NFSv4 extension. 309 4. XDR Considerations 311 As an extensible XDR-based protocol, NFSv4 has to ensure interversion 312 compatibility in situations in which the client and server use 313 different XDR descriptions. For example, the client and server may 314 implement different variants of the same minor version, in that they 315 each might add different sets of extensions to the base minor 316 version. 318 The XDR extension paradigm, discussed in Section 4.1, assures that 319 these descriptions are compatible, with clients and servers able to 320 determine and use those portions of the protocol that they both share 321 according to the method described in Section 4.4.2. 323 4.1. XDR Extension 325 When an NFSv4 version change requires a modification to the protocol 326 XDR, this is effected within a framework based on the idea of XDR 327 extension. This is opposed to transitions between major NFS versions 328 (including that between NFSv3 and NFSv4.0) in which the XDR for one 329 version was replaced by a different XDR for a newer version. 331 The XDR extension approach allows an XDR description to be extended 332 in a way which retains the structure of all previously valid 333 messages. If a base XDR description is extended to create a second 334 XDR description, the following will be true for the second 335 description to be a valid extension of the first: 337 o The set of valid messages described by the extended definition is 338 a superset of that described by the first. 340 o Each message within the set of valid messages described by the 341 base definition is recognized as having exactly the same 342 structure/interpretation using the extended definition. 344 o Each message within the set of messages described as valid by the 345 extended definition but not the base definition must be 346 recognized, using the base definition, as part of an extension not 347 provided for. 349 The use of XDR extension can facilitate compatibility between 350 different versions of the NFSv4 protocol. When XDR extension is used 351 to implement OPTIONAL features, the greatest degree of inter-version 352 compatibility is obtained. In this case, no change in minor version 353 number is needed and the extension may be effected in the context of 354 a single minor version. 356 4.2. Rules for XDR Extension within NFSv4 358 In the context of NFSv4, an extension of a given XDR description 359 consists of one or more of the following: 361 o Addition of previously unspecified operation codes, within the 362 framework established by COMPOUND and CB_COMPOUND. 364 o Addition of previously unspecified attributes. 366 o Addition of new, previously unused, values to existing enums. 368 o Addition of previously unassigned bit values to a flag word. 370 o Addition of new cases to existing switches, provided that the 371 existing switch did not contain a default case. 373 However, none of the following is allowed to happen: 375 o Any change to the structure of existing requests or replies other 376 than those listed above. 378 o Addition of previously unspecified RPC operation codes, for either 379 the nfsv4 program or the callback program, is not allowed. 381 o Deletion of existing RPC operations, enum values, flag bit values 382 and switch cases. Note that changes may be made to define use of 383 any of these as causing an error, as long as the XDR is 384 unaffected. 386 o Similarly, none of these items may be reused for a new purpose. 388 4.3. Handling of Protocol Elements 390 Implementations handle protocol elements in one of three ways. Which 391 of the following ways are valid depends on the status of the protocol 392 element in the variant being implemented: 394 o The protocol element is not a part of definition of the variant in 395 question and so is "unknown". The responder, when it does not 396 report an RPC XDR decode error, reports an error indicative of the 397 element not being defined in the XDR such as NFS4ERR_OP_ILLEGAL, 398 NFS4ERR_BADXDR, or NFS4ERR_INVAL. See Section 4.4.3 for details. 400 o The protocol element is a known part of the variant but is not 401 supported by the particular implementation. The responder reports 402 an error indicative of the element being recognized as one which 403 is not supported such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, 404 or NFS4ERR_ATTRNOTSUPP. 406 o The protocol element is a known part of the variant which is 407 supported by the particular implementation. The responder reports 408 success or an error other than the special ones discussed above. 410 Which of these are validly returned by the responder depends on the 411 status of the protocol element in the minor version specified in the 412 COMPOUND or CB_COMPOUND. The possibilities which can exist are 413 listed below. 415 o The protocol element is not known in the minor version. In this 416 case all implementations of the minor version MUST indicate that 417 the protocol element is not known. 419 o The protocol element is part of a feature specified mandatory to 420 not implement in the minor version. In this case as well, all 421 implementations of the minor version MUST indicate that the 422 protocol element is not known. 424 o The protocol element is defined as part of the current variant of 425 the minor version but is not part of the corresponding base 426 variant. In this case, the requester can encounter situations in 427 which the protocol element is either not known to the responder, 428 is known to but not supported by the responder, or is both known 429 to and supported by the responder. 431 o The protocol element is defined as an OPTIONAL part of the base 432 minor version. In this case, the requester can expect the 433 protocol element to be known but must deal with cases in which it 434 is supported or is not supported. 436 o The protocol element is defined as a REQUIRED part of the base 437 minor version. In this case, the requester can expect the 438 protocol element to be both known and supported by the responder. 440 The listing of possibilities above does not mean that a requester 441 always needs to be prepared for all such possibilities. Often, 442 depending on the scope of the feature of which the protocol element 443 is a part, handling of a previous request using the same or related 444 protocol elements, will allow the requester to be sure that certain 445 of these possibilities cannot occur. 447 Requesters, typically clients, may test for knowledge of or support 448 for protocol elements as part of connection establishment. This may 449 allow the requester to be aware of responder lack of knowledge of or 450 support for problematic requests before they are actually used to 451 effect user requests. 453 4.4. Inter-version Interoperability 455 Because of NFSv4's use of XDR extension, any communicating client and 456 server versions have XDR definitions that are each valid extensions 457 of a third version. Once that version is determined, it may be used 458 by both client and server to communicate. Each party can 459 successfully use a subset of protocol elements that are both known 460 and supported by both parties. 462 4.4.1. Requirements for Knowledge of Protocol Elements 464 With regard to requirements for knowledge of protocol elements, the 465 following rules apply. These rules are the result of the use of the 466 XDR extension paradigm combined with the way in which extensions are 467 incorporated in existing minor versions (for details of which see 468 Section 6). 470 o Any protocol element defined as part of the base variant of 471 particular minor version is required to be known by that minor 472 version. This occurs whether the specification happens in the 473 body of the minor definition document or is in a feature 474 definition document that is made part of the minor version by 475 being normatively referenced by the minor version definition 476 document. 478 o Any protocol element required to be known in a given minor version 479 is required to be known in subsequent minor version, unless and 480 until a minor version has made that protocol element as mandatory 481 to not implement. 483 o When a protocol element is defined as part of an extension to an 484 extensible minor version, it is not required to be known in that 485 minor version but is required to be known by the next minor 486 version. In the earlier minor version, it might not be defined in 487 the XDR definition document, while in the later version it needs 488 to be defined in the XDR definition document. In either case, if 489 it is defined, it might or might not be supported. 491 o When knowledge of protocol elements is optional in a given minor 492 version, the responder's knowledge of such optional elements must 493 obey the rule that if one such element is known, then all the 494 protocol elements defined in the same minor version definition 495 document must be known as well. 497 For many minor versions, all existing protocol elements, are required 498 to be known by both the client and the server, and so requesters do 499 not have to test for the presence or absence of knowledge regarding 500 protocol elements for which knowledge might be optional. This is the 501 case if there has been no extension for the minor version in 502 question. Extensions can be added to extensible minor versions as 503 described in Section 6 and can be used to correct protocol flaws as 504 described in Section 9. 506 Requesters can ascertain the knowledge of the responder in two ways: 508 o By issuing a request using the protocol element and looking at the 509 response. Note that, even if the protocol element used is not 510 supported by the responder, the requester can still determine if 511 the element is known by the responder. 513 o By receiving a request from the responder, acting in the role of 514 requester. For example, a client may issue a request enabling the 515 server to infer that it is aware of a corresponding callback. 517 In making this determination, the requester can rely on two basic 518 facts: 520 o If the responder is aware of a single protocol element within a 521 feature package, it must be aware of all protocol elements within 522 that feature package 524 o If a protocol element is one defined by the minor version 525 specified by a request (and not in an extension), or in a previous 526 minor version, the responder must be aware of it. 528 4.4.2. Establishing Interoperability 530 When a client and a server interact, they need to able to take 531 advantage of the compatibility provided by NFSv4's use of XDR 532 extension. 534 In this context, the client and server would arrive at a common 535 variant which the client would uses to send requests which the server 536 would then accept. The server would use that variant to send 537 callbacks which the client would then accept. This state of affairs 538 could arise in a number of ways: 540 o Client and server have been built using XDR variants that belong 541 to the same minor version 543 o The client's minor version is lower than that of the server. In 544 this case the server, in accord with Section 8.2, accepts the 545 client's minor version, and acts as if it has no knowledge of 546 extensions made in subsequent minor versions. It has knowledge of 547 protocol elements within the current (i.e. effectively final) 548 variant of the lower minor version. 550 o The client's minor version is higher than that of the server. In 551 this case the client, in accord with Section 8.2, uses a lower 552 minor version that the server will accept. In this case, the 553 server has no knowledge of extensions made in subsequent minor 554 versions. 556 There are a number of cases to consider based on the characteristics 557 of the minor version chosen. 559 o The minor version consists of only a single variant (no extension 560 or XDR corrections), so the client and the server are using the 561 same XDR description and have knowledge of the same protocol 562 elements. 564 o When the minor version consists of multiple variants (i.e. there 565 are one or more XDR extensions or XDR corrections), the client and 566 the server are using compatible XDR descriptions. The client is 567 aware of some set of extensions while the server may be aware of a 568 different set. The client can determine which of the extensions 569 that he is aware of, are also known to the server by using the 570 approach described in Section 4.4.3. Once this is done, the 571 client and server will both be using a common variant. The 572 variants that the client and the server were built with will both 573 either be identical to this variant or a valid extension of it. 574 Similarly, the variants that the client and the server actually 575 use will be a subset of this variant, in that certain OPTIONAL 576 features will not be used. 578 In either case, the client must determine which of the OPTIONAL 579 protocol elements within the common version are supported by the 580 server, just as it does for OPTIONAL features introduced as part of a 581 minor version. 583 4.4.3. Determining Knowledge of Protocol Elements 585 A requester may test the responder's knowledge of particular protocol 586 elements as defined below, based on the type of protocol element. 588 o When a GETATTR request is made specifying an attribute bit to be 589 tested and that attribute is not a set-only attribute, if the 590 GETATTR returns with the error NFS4ERR_INVAL, then it can be 591 concluded that the responder has no knowledge of the attribute in 592 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 593 indicate that the responder is aware of the attribute in question. 595 o When a SETATTR request is made specifying the attribute bit to be 596 tested and that attribute is not a get-only attribute, if the 597 SETATTR returns with the error NFS4ERR_INVAL, then it can be 598 concluded that the responder has no knowledge of the attribute in 599 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 600 indicate that the responder is aware of the attribute in question. 602 o When a request is made including an operation with a new flag bit, 603 if the operation returns with the error NFS4ERR_INVAL,then it can 604 generally be concluded that the responder has no knowledge of the 605 flag bit in question, as long as the requester is careful to avoid 606 other error situations in which the operation in question is 607 defined as returning NFS4ERR_INVAL. Other responses indicate that 608 the responder is aware of the flag bit in question. 610 o When a request is made including the operation to be tested, if 611 the responder returns an RPC XDR decode error, or a response 612 indicating that the operation in question resulted in 613 NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded 614 that the responder has no knowledge of the operation in question. 615 Other responses, including NFS4ERR_NOTSUPP, indicate that the 616 responder is aware of the operation in question. 618 o When a request is made including the switch arm to be tested, if 619 the responder returns an RPC XDR decode error, or a response 620 indicating that the operation in question resulted in 621 NFS4ERR_BADXDR, then it can be concluded that the responder has no 622 knowledge of the operation in question. Other responses, 623 including NFS4ERR_UNION_NOTSUPP, indicate that the responder is 624 aware of the protocol element in question. 626 A determination of the knowledge or lack of knowledge of a particular 627 protocol element is expected to remain valid as long as the clientid 628 associated with the request remains valid. 630 The above assumes, as should be the case, that the server will accept 631 the minor version used by the client. For more detail regarding this 632 issue, see Section 8.2. 634 4.5. XDR Overlay 636 XDR additions may also be made by defining XDR structures that 637 overlay nominally opaque fields. defined to allow such incremental 638 extensions. 640 For example, each pNFS mapping type provides its own XDR definition 641 for various pNFS-related fields defined in [RFC5661] as opaque 642 arrays. 644 Because such additions provide new interpretations of existing 645 fields, they may be made outside of the extension framework as long 646 as they obey the rules previously established when the nominally 647 opaque protocol elements were added to the protocol. 649 5. Other NFSv4 Protocol Changes 651 There are a number of types of protocol changes that are outside the 652 XDR extension framework discussed in Section 4. These changes are 653 also managed within the NFSv4 versioning framework and may be of a 654 number of types, which are discussed in the sections below 656 Despite the previous emphasis on XDR changes, additions and changes 657 to the NFSv4 protocols have not been limited to those that involve 658 changes (in the form of extensions) to the protocol XDR. Examples of 659 other sorts of changes have been taken from NFSv4.1. 661 All such changes that have been made in the past have been made as 662 part of new minor version. Future change of these sorts may not be 663 done in an extension but can only be made in a new minor version. 665 5.1. Field Interpretation and Use 667 The XDR description of a protocol does not constitute a complete 668 description of the protocol. Therefore, versioning needs to consider 669 the role of changes in the use of fields, even when there is no 670 change to the underlying XDR. 672 Although any XDR element is potentially subject to a change in its 673 interpretation and use, the likelihood of such change will vary with 674 the XDR-specified type of the element, as discussed below: 676 o When XDR elements are defined as strings, rules regarding the 677 appropriate string values are specified in protocol specification 678 text with changes in such rules documented in minor version 679 definition documents. Some types of strings within NFS4 are used 680 in server names (in location-related attributes), user and group 681 names, and in the names of file objects within directories. Rules 682 regarding what strings are acceptable appear in [RFC7530] and 683 [RFC5661] with the role of the XDR limited to hints regarding 684 UTF-8 and capitalization issues via XDR typedefs. 686 o Fields that are XDR-defined as opaque elements and which are truly 687 opaque, do not raise versioning issues, except as regards inter- 688 version use, which is effectively foreclosed by the rules in 689 Section 8.1. 691 Note that sometimes a field will seem to be opaque but not 692 actually be fully opaque when considered carefully. For example, 693 the "other" field of stateids is defined as an opaque array, while 694 the specification text specially defines appropriate treatment 695 when the "other" field within it is either all zeros or all ones. 696 Given this context, creation or deletion of reserved values for 697 "special" stateids will be a protocol change which versioning 698 rules need to deal with. 700 o Some nominally opaque elements have external XDR definitions that 701 overlay the nominally opaque arrays. Such cases are discussed in 702 Section 4.5. 704 5.2. Behavioral Changes 706 Changes in the behavior of NFSv4 operations are possible, even if 707 there is no change in the underlying XDR or change to field 708 interpretation and use. 710 One class of behavioral change involves changes in the set of errors 711 to be returned in the event of various errors. When the set of valid 712 requests remain the same, and the behavior for each of them remains 713 the same, such changes can be implemented with only limited 714 disruption to existing clients. 716 Many more substantial behavioral changes have occurred in connection 717 with the addition of the session concept in NFSv4.1. Even though 718 there was no change to the XDR for existing operations, many existing 719 operations and COMPOUNDs consisting only of them became invalid. 721 Also, changes were made regarding the required server behavior as to 722 the interaction of the MODE and ACL attributes. 724 6. Extending Existing Minor Versions 726 Extensions to the most recently published NFSv4 minor version may be 727 made by publishing the extension as a Proposed Standard, unless the 728 minor version in question has been defined as non-extensible. A 729 document need not update the document defining the minor version, 730 which remains a valid description of the base variant of the minor 731 version in question. 733 Corrections to protocol errors (see Section 9) may be accomplished by 734 publishing an extension, including a compatible XDR change. Such 735 documents will update the defining documents for the corrected minor 736 version. 738 7. Minor Versions 740 7.1. Creation of New Minor Versions 742 It is important to note that this section, in describing situations 743 that would require new minor versions to be created, does not thereby 744 imply that situations will exist in the future. Judgments regarding 745 desirability of future changes will be made by the working group or 746 its successors and any guidance that can be offered at this point is 747 necessarily quite limited. 749 Creation of a new minor version is an option that the working group 750 retains. The listing of situations below that would prompt such 751 actions is not meant to be exhaustive. 753 The following sorts of features are not allowed as extensions and 754 would require creation of a new minor version: 756 o Features that incorporate any of the non-XDR-based changes 757 discussed in Sections 5.1 and 5.2. 759 o Addition of REQUIRED new features. 761 o Changes to the status of existing features including converting 762 features to be mandatory to not implement. 764 8. Minor Version Interaction Rules 766 This section addresses issues related to rules #11 and #13 in the 767 minor versioning rules in [RFC5661]. With regard to the supersession 768 of minor versioning rules, the treatment here overrides that in 769 [RFC5661] when either of the potentially interacting minor versions 770 has not yet been published as a Proposed Standard. 772 Note that these rules are the only ones directed to minor version 773 implementers, rather than to those specifying new minor versions. 775 8.1. Minor Version Identifier Transfer Issues 777 Each relationship between a client instance and a server instance, as 778 represented by a clientid, is to be devoted to a single minor 779 version. If a server detects that a COMPOUND with an inappropriate 780 minor version is being used, it MUST reject the request. In doing 781 so, it may return either NFS4ERR_BAD_CLIENTID or 782 NFS4RR_MINOR_VERS_MISMATCH. 784 As a result of the above, the client has the assurance that the set 785 of REQUIRED and OPTONAL features will not change within the context 786 of a single clientid. Server implementations MUST ensure that the 787 set of supported features and protocol elements does not change 788 within such a context. 790 8.2. Minor Version Compatibility 792 The goal of the NFSv4 extension model is to enable compatibility 793 including compatibility between clients and servers implementing 794 different minor versions. 796 Within a set of minor versions that define the same set of features 797 as REQUIRED and mandatory to not implement, it is relatively easy for 798 clients and servers to provide the needed compatibility by adhering 799 to the following practices. 801 o Servers supporting a given minor version should support earlier 802 minor versions within that set and return appropriate errors for 803 use of protocol elements that were not a valid part of that 804 earlier minor version. For details see below. 806 o Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by 807 searching for a lower minor version number that the server will 808 accept. 810 Servers supporting a given minor version MUST, in returning errors 811 for operation which were a valid part of the minor version, return 812 the errors allowed for the current operation in the minor version 813 actually being used. 815 With regard to protocol elements not known in a given minor version, 816 the appropriate error codes are given below. Essentially, the 817 server, although it has a more extensive XDR reflective of a newer 818 minor version, must act as a server with a more limited XDR would. 820 o When an operation is used which is not known in the specified 821 minor version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) 822 should be returned. 824 o When an attribute is used which is not known in the specified 825 minor version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) 826 should be returned. 828 o When a switch case is used which is not known in the specified 829 minor version, NFS4ERR_BADXDR (as opposed to 830 NFS4ERR_UNION_NOTSUPP) should be returned. Even though the 831 message may be XDR-decodable by the server's current XDR, it is 832 not so according to the minor version being used. 834 o When a flag bit is used which is not known in the specified minor 835 version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP Or any other 836 error defined as indicated non-support a flag bit) should be 837 returned. 839 9. Correction of Existing Minor Versions and Features 841 The possibility always exists that there will be a need to correct an 842 existing feature in some way, after the acceptance of that feature or 843 a minor version containing it, as a Proposed Standard. While the 844 working group can reduce the probability of such situations arising 845 by waiting for running code before considering a feature as done, it 846 cannot reduce the probability to zero. As features are used more 847 extensively and interact with other features, previously unseen flaws 848 may be discovered and will need to be corrected. 850 Such corrections are best done in a document obsoleting or updating 851 the RFC defining the relevant feature definition document or minor 852 version specification. In making such corrections, the working group 853 will have to carefully consider how to assure interoperability with 854 older clients and servers. 856 Often, corrections can be done without changing the protocol XDR. In 857 many cases, a change in client and server behavior can be implemented 858 without taking special provision with regard to interoperability with 859 earlier implementations. In those case, and in cases in which a 860 revision merely clarifies an earlier protocol definition document, a 861 new document can be published which simply updates the earlier 862 protocol definition document. 864 In other cases, it is best if client or server behavior needs to 865 change in a way which raises interoperability concerns. In such 866 cases, incompatible changes in server or client behavior should not 867 be mandated in order to avoid XDR changes. 869 9.1. XDR Changes to Implement Protocol Corrections 871 When XDR changes are necessary as part of correcting a flaw, these 872 should be done in a manner similar to that used when implementing new 873 minor versions or features within them. In particular, 875 o Existing XDR structures may not be modified or deleted. 877 o XDR extensions may be used to correct existing protocol facilities 878 in a manner similar to those used to add additional optional 879 features. Such corrections may be done in a minor version for 880 which optional features may no longer be added, if the working 881 group decides that it is an appropriate to compatibly effect a 882 correction. 884 o When a correction is made to an OPTIONAL feature, the result is 885 similar to a situation in which there are two independent OPTIONAL 886 features. A server may choose to implement either or both. 888 o When a correction is made to a required feature, the situation 889 becomes one in which neither the old nor the new version of the 890 feature is required. Instead, it is required that a server 891 support at least one of the two, while each is individually 892 OPTIONAL. Although use of the corrected version is ultimately 893 better, and may be recommended, it should not be described as 894 "RECOMMENDED", since the choice of which version to support if 895 only one is supported will depend on the needs of clients, which 896 may be slow to adopt the updated version. 898 o In all of the cases above, it is appropriate that the old version 899 of the feature, be considered obsolescent, with the expectation 900 that the working group might, in a later minor version, decide 901 that the older version is to become mandatory to not implement. 903 By doing things this way, the protocol with the XDR modification can 904 accommodate clients and servers that support either the corrected or 905 the uncorrected version of the protocol and also clients and servers 906 aware of and capable of supporting both alternatives. 908 o A client that supports only the earlier version of the feature 909 (i.e., an older unfixed client) can determine whether the server 910 it is connecting to supports the older version of feature. It is 911 capable of interoperating with older servers that support only the 912 unfixed protocol as well as ones that support both versions. 914 o A client that supports only the corrected version of the feature 915 (i.e., a new or updated client) can determine whether the server 916 it is connecting to supports the newer version of the feature. It 917 is capable of interoperating with newer servers that support only 918 the updated feature as well as ones that support both versions. 920 o A client that supports both the older and newer version of the 921 feature can determine which version of the particular feature is 922 supported by the server it is working with. 924 o A server that supports only the earlier version of the feature 925 (i.e., an older unfixed server) can only successfully interoperate 926 with older clients. However newer clients can easily determine 927 that the feature cannot be used on that server. 929 o A server that supports only the newer version of the feature 930 (i.e., a new or updated server) can only successfully interoperate 931 with newer clients. However, older clients can easily determine 932 that the feature cannot be used on that server. In the case of 933 OPTIONAL features, clients can be expected to deal with non- 934 support of that particular feature. 936 o A server that supports both the older and newer versions of the 937 feature can interoperate with all client variants. 939 By using extensions in this manner, the protocol creates a clear path 940 which preserves the functioning of existing clients and servers and 941 allows client and server implementers to adopt the new version of the 942 feature at a reasonable pace. 944 10. Security Considerations 946 Since no substantive protocol changes are proposed here, no security 947 considerations apply. 949 11. IANA Considerations 951 The current document does not require any actions by IANA. 953 12. References 955 12.1. Normative References 957 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 958 Requirement Levels", BCP 14, RFC 2119, 959 DOI 10.17487/RFC2119, March 1997, 960 . 962 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 963 "Network File System (NFS) Version 4 Minor Version 1 964 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, 965 . 967 [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 968 (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, 969 March 2015, . 971 12.2. Informative References 973 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 974 Beame, C., Eisler, M., and D. Noveck, "Network File System 975 (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530, 976 April 2003, . 978 Appendix A. Acknowledgements 980 The author wishes to thank Tom Haynes of Primary Data for his role in 981 getting this effort started and his work in co-authoring the first 982 version of the initial working group versioning document. 984 The author also wishes to thank Chuck Lever and Mike Kupfer of Oracle 985 and Bruce Fields of Red Hat for their helpful reviews of this and 986 other versioning-related documents. 988 Author's Address 989 David Noveck 990 Hewlett Packard Enterprise 991 165 Dascomb Road 992 Andover, MA 01810 993 US 995 Phone: +1 978 474 2011 996 Email: davenoveck@gmail.com