idnits 2.17.1 draft-ietf-nfsv4-versioning-11.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. -- The draft header indicates that this document updates RFC7862, but the abstract doesn't seem to mention this, which it should. 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 (May 30, 2017) is 2516 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 (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 D. Noveck 3 Internet-Draft NetApp 4 Updates: 5661, 7862 (if approved) May 30, 2017 5 Intended status: Standards Track 6 Expires: December 1, 2017 8 Rules for NFSv4 Extensions and Minor Versions 9 draft-ietf-nfsv4-versioning-11 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 and 20 other RFCs defining minor versions. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 1, 2017. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 4 59 2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 4 60 2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 5 61 3. Consolidation of Extension Rules . . . . . . . . . . . . . . 6 62 4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 8 64 4.2. Rules for XDR Extension within NFSv4 . . . . . . . . . . 8 65 4.3. Handling of Protocol Elements by Responders . . . . . . . 9 66 4.4. Inter-version Interoperability . . . . . . . . . . . . . 11 67 4.4.1. Requirements for Knowledge of Protocol Elements . . . 11 68 4.4.2. Establishing Interoperability . . . . . . . . . . . . 12 69 4.4.3. Determining Knowledge of Protocol Elements . . . . . 14 70 4.5. XDR Overlay . . . . . . . . . . . . . . . . . . . . . . . 15 71 5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 15 72 5.1. Field Interpretation and Use . . . . . . . . . . . . . . 15 73 5.2. Behavioral Changes . . . . . . . . . . . . . . . . . . . 16 74 6. Extending Existing Minor Versions . . . . . . . . . . . . . . 17 75 7. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 18 76 7.1. Creation of New Minor Versions . . . . . . . . . . . . . 18 77 8. Minor Version Interaction Rules . . . . . . . . . . . . . . . 18 78 8.1. Minor Version Identifier Transfer Issues . . . . . . . . 18 79 8.2. Minor Version Compatibility . . . . . . . . . . . . . . . 19 80 9. Correction of Existing Minor Versions and Features . . . . . 20 81 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 20 82 9.2. XDR Corrections to OPTIONAL Features . . . . . . . . . . 21 83 9.3. XDR Corrections to REQUIRED Features . . . . . . . . . . 22 84 9.4. Addressing XDR Corrections in Later Minor Versions . . . 23 85 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 86 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 87 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 88 12.1. Normative References . . . . . . . . . . . . . . . . . . 25 89 12.2. Informative References . . . . . . . . . . . . . . . . . 25 90 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 25 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 93 1. Introduction 95 To address the requirement for an NFS protocol that can evolve as the 96 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 97 provides a framework to allow for future changes via the creation of 98 new protocol versions including minor versions and certain forms of 99 modification of existing minor versions. The extension rules 100 contained in this document allow extensions and other changes to be 101 implemented in a way that maintains compatibility with existing 102 clients and servers. 104 Previously, all protocol changes had been part of new minor versions. 105 The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the 106 minor version being used by the client in making requests. The 107 CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) specifies the 108 minor version being used by the server on callback requests. 110 Creation of a new minor version is no longer the only way in which 111 protocol changes may be made. Optional features may be added as 112 extensions and protocol corrections can be proposed, specified and 113 implemented within the context of a single minor version. Creation 114 of new minor versions remains available when needed. 116 The goal of allowing extensions within the context of a minor version 117 is to provide more implementation flexibility while preserving 118 interoperability on protocol upgrade. As described in Section 4.4, 119 two implementations can each choose a subset of available extensions, 120 with the client able to use the subset of the extensions that it is 121 prepared to use that the server supports as well. Support for this 122 common subset is not affected by the fact that extensions outside 123 this common subset may be supported by the server or potentially used 124 by the client. 126 2. Terminology 128 A basic familiarity with NFSv4 terminology is assumed in this 129 document and the reader is pointed to [RFC7530]. 131 In this document, the term "version" is not limited to minor 132 versions. When minor versions are meant, the term "minor version" is 133 used explicitly. For more discussion of this and related terms, see 134 Section 2.3 136 A "feature package" is a set of features that are defined together, 137 either as part of a minor version or as part of the same protocol 138 extension. 140 2.1. Use of Keywords Defined in RFC2119 142 The keywords defined by [RFC2119] have special meanings which this 143 document intends to adhere to. However, due to the nature of this 144 document and some special circumstances, there are some complexities 145 to take note of: 147 o Where this document does not directly specify implementation 148 requirements, use of these capitalized terms is often not 149 appropriate, since the guidance given in this document does not 150 directly affect interoperability. 152 o In this document, what authors of RFCs defining features and minor 153 versions need to do is stated without these specialized terms. 154 Although it is necessary to follow this guidance to provide 155 successful NFSv4 protocol extension, that sort of necessity is not 156 of the sort defined as applicable to the use of the keywords 157 defined in [RFC2119]. 159 The fact that these capitalized terms are not used should not be 160 interpreted as indicating that this guidance does not need to be 161 followed or is somehow not important. 163 o In speaking of the possible statuses of features and feature 164 elements, the terms "OPTIONAL" and "REQUIRED" are used. For 165 further discussion, see Section 2.2. 167 o When one of these upper-case keywords defined in [RFC2119] is used 168 in this document, it is in the context of a rule directed to an 169 implementer of NFSv4 minor versions, the status of a feature or 170 protocol element, or in a quotation, sometimes indirect, from 171 another document. 173 2.2. Use of Feature Statuses 175 There has been some confusion, during the history of NFSv4, about the 176 correct use of these terms, and instances in which the keywords 177 defined in [RFC2119] were used in ways that appear to be at variance 178 with the definitions in that document. 180 o In [RFC3530], the lower-case terms "optional", "recommended", and 181 "required" were used as feature statuses, Later, in [RFC5661] and 182 [RFC7530], the corresponding upper-case keywords were used. It is 183 not clear why this change was made. 185 o In the case of "RECOMMENDED", its use as a feature status is 186 inconsistent with [RFC2119] and it will not be used for this 187 purpose in this document. 189 o The word "RECOMMENDED" to denote the status of attributes in 190 [RFC7530] and [RFC5661] raises similar issues. This has been 191 recognized in [RFC7530] with regard to NFSV4.0, although the 192 situation with regard to NFSv4.1 remains unresolved. 194 In this document, the keywords "OPTIONAL" and "REQUIRED" and the 195 phrase "mandatory to not implement" are used to denote the status of 196 features within a given minor version. In using these terms, RFCs 197 which specify the status of features inform: 199 o client implementations whether they need to deal with the absence 200 of support for these features. 202 o server implementations whether they need to provide support for 203 these features. 205 2.3. NFSv4 Versions 207 The term "version" denotes any valid protocol variant constructed 208 according to the rules in this document. It includes minor versions, 209 but there are situations which allow multiple variant versions to be 210 associated with and co-exist within a single minor version: 212 o When there are feature specification documents published as 213 Proposed Standards extending a given minor version, then the 214 protocol defined by the minor version specification document, when 215 combined with any subset (not necessarily a proper subset) of the 216 feature specification documents, is a valid NFSv4 version variant 217 which is part of the minor version in question. 219 o When there are protocol corrections published which update a given 220 minor version, each set of published updates, up to the date of 221 publication of the update, is a valid NFSv4 version variant which 222 is part of the minor version in question. 224 Because of the above, there can be multiple version variants that are 225 part of a given minor version. Two of these are worthy of special 226 terms: 228 o The term "base minor version" denotes the version variant that 229 corresponds to the minor version as originally defined, including 230 all protocol elements specified in the minor version definition 231 document but not incorporating any extensions or protocol 232 corrections published after that original definition. 234 o At any given time, the term "current minor version" denotes the 235 minor version variant including all extensions of and corrections 236 to the minor version made by standard-track documents published up 237 to that time. 239 Each client and server which implements a specific minor version will 240 implement some particular variant of that minor version. Each 241 variant is a subset of the current minor version and a superset of 242 the base minor version. When the term "minor version" is used 243 without either of these qualifiers, it should refer to something 244 which is true of all variants within that minor version. For 245 example, in the case of a minor version that has not had a protocol 246 correction, one may refer to the set of REQUIRED features for that 247 minor version since it is the same for all variants within the minor 248 version. See Section 9 for a discussion of correcting an existing 249 minor version. 251 3. Consolidation of Extension Rules 253 In the past, the only existing extension rules were the minor 254 versioning rules that were being maintained and specified in the 255 Standards Track RFCs which defined the individual minor versions. In 256 the past, these minor versioning rules were modified on an ad hoc 257 basis for each new minor version. 259 More recently, minor versioning rules were specified in [RFC5661] 260 while modifications to those rules were allowed in subsequent minor 261 versions. 263 This document defines a set of extension rules, including rules for 264 minor version construction. These rules apply to all future changes 265 to the NFSv4 protocol. The rules are subject to change but any such 266 change should be part of a standards track RFC obsoleting or updating 267 this document. 269 Rather than a single list of extension rules, as was done in the 270 minor versioning rules in [RFC5661], this document defines multiple 271 sets of rules that deal with the various forms of protocol change 272 provided for in the NFSv4 extension framework. 274 o The kinds of XDR changes that may be made to extend NFSv4 are 275 addressed in the rules in Section 4.2. 277 o Minor version construction, including rules applicable to changes 278 which cannot be made in extensions to existing minor versions are 279 addressed in Section 7.1. 281 o Minor version interaction rules are discussed in Sections 8.1 and 282 8.2. 284 This document supersedes minor versioning rules appearing in the 285 minor version specification RFC's, including those in [RFC5661] and 286 also the modification to those rules mentioned in [RFC7862]. As a 287 result, potential conflicts among documents should be addressed as 288 follows: 290 o The specification of the actual protocols for minor versions 291 previously published as Proposed Standards take precedence over 292 minor versioning rules in either this document or in the minor 293 version specification RFC's. In other words, if the transition 294 from version A to version B violates a minor versioning rule, the 295 version B protocol stays as it is. 297 o Since minor versioning rules #11 and #13 from [RFC5661] deal with 298 the interactions between multiple minor versions, the situation is 299 more complicated. See Section 8 for a discussion of these issues, 300 including how potential conflicts between rules are to be 301 resolved. 303 o Otherwise, any conflict between the extension rules in this 304 document and those in minor version specification RFC's are to be 305 resolved based on the treatment in this document. In particular, 306 corrections may be made as specified in Section 9 for all 307 previously specified minor versions, and the extensibility of 308 previously specified minor versions is to be handled in accord 309 with Section 6. 311 Future minor version specification documents should avoid specifying 312 rules relating to minor versioning and reference this document in 313 connection with rules for NFSv4 extension. 315 4. XDR Considerations 317 As an extensible XDR-based protocol, NFSv4 has to ensure inter- 318 version compatibility in situations in which the client and server 319 use different XDR descriptions. For example, the client and server 320 may implement different variants of the same minor version, in that 321 they each might add different sets of extensions to the base minor 322 version. 324 The XDR extension paradigm, discussed in Section 4.1, assures that 325 these descriptions are compatible, with clients and servers able to 326 determine and use those portions of the protocol that they both share 327 according to the method described in Section 4.4.2. 329 4.1. XDR Extension 331 When an NFSv4 version change requires a modification to the protocol 332 XDR, this is effected within a framework based on the idea of XDR 333 extension. This is opposed to transitions between major NFS versions 334 (including that between NFSv3 and NFSv4.0) in which the XDR for one 335 version was replaced by a different XDR for a newer version. 337 The XDR extension approach allows an XDR description to be extended 338 in a way which retains the structure of all previously valid 339 messages. If a base XDR description is extended to create a second 340 XDR description, the following will be true for the second 341 description to be a valid extension of the first: 343 o The set of valid messages described by the extended definition is 344 a superset of that described by the first. 346 o Each message within the set of valid messages described by the 347 base definition is recognized as having exactly the same 348 structure/interpretation using the extended definition. 350 o Each message within the set of messages described as valid by the 351 extended definition but not the base definition must be 352 recognized, using the base definition, as part of an extension not 353 provided for. 355 The use of XDR extension can facilitate compatibility between 356 different versions of the NFSv4 protocol. When XDR extension is used 357 to implement OPTIONAL features, the greatest degree of inter-version 358 compatibility is obtained. In this case, as long as the rules in 359 Section 6 are followed, no change in minor version number is needed 360 and the extension may be effected in the context of a single minor 361 version. 363 4.2. Rules for XDR Extension within NFSv4 365 In the context of NFSv4, given the central role of COMPOUND and 366 CB_COMPOUND, addition of new RPC procedures is not allowed and the 367 enumeration of operations and callback operations have a special 368 role. 370 The following XDR extensions, by their nature, affect both messages 371 sent by requesters (i.e. requests, callbacks), and responders (i.e. 372 replies, callback replies). 374 o Addition of previously unspecified operation codes, within the 375 framework established by COMPOUND and CB_COMPOUND. These extend 376 the appropriate enumeration and the corresponding switches devoted 377 to requests and responses for the associated direction of 378 operation. 380 o Addition of previously unspecified attributes. These add 381 additional numeric constants that define each attribute's bit 382 position within the attribute bit map, together with XDR typedefs 383 that specify the attributes' format within the nominally opaque 384 arrays specifying sets of attributes. 386 Other sorts of changes will generally affect one of requests, 387 replies, callback, or callback replies. Although all are valid XDR 388 extensions, the messages that are affected may determine whether the 389 extension requires a new minor version (see Section 7) or can be made 390 as an extension within an existing minor version (see Section 6). 392 o Addition of new, previously unused, values to existing enums. 394 o Addition of previously unassigned bit values to a flag word. 396 o Addition of new cases to existing switches, provided that the 397 existing switch did not contain a default case. 399 None of the following is allowed to happen: 401 o Any change to the structure of existing requests or replies other 402 than those listed above. 404 o Addition of previously unspecified RPC procedures, for either the 405 nfsv4 program or the callback program. 407 o Deletion of existing RPC procedures, operation codes, enum values, 408 flag bit values and switch cases. Note that changes may be made 409 to define use of any of these as causing an error, as long as the 410 XDR is unaffected. Similarly, none of these items may be reused 411 for a new purpose. 413 4.3. Handling of Protocol Elements by Responders 415 Implementations handle protocol elements received in requests and 416 callbacks in one of three ways. Which of the following ways are 417 valid depends on the status of the protocol element in the variant 418 being implemented: 420 o The protocol element is not a part of definition of the variant in 421 question and so is "unknown". The responder, when it does not 422 report an RPC XDR decode error, reports an error indicative of the 423 element not being defined in the XDR such as NFS4ERR_OP_ILLEGAL, 424 NFS4ERR_BADXDR, or NFS4ERR_INVAL. See Section 4.4.3 for details. 426 o The protocol element is a known part of the variant but is not 427 supported by the particular implementation. The responder reports 428 an error indicative of the element being recognized as one which 429 is not supported such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, 430 or NFS4ERR_ATTRNOTSUPP. 432 o The protocol element is a known part of the variant which is 433 supported by the particular implementation. The responder reports 434 success or an error other than the special ones discussed above. 436 Which of these are validly returned by the responder depends on the 437 status of the protocol element in the minor version specified in the 438 COMPOUND or CB_COMPOUND. The possibilities which can exist when 439 dealing with minor versions that have not been subject to corrections 440 are listed below. See Sections 9.1 and 9.3 for a discussion of the 441 effects of protocol correction. 443 o The protocol element is not known in the minor version. In this 444 case all implementations of the minor version MUST indicate that 445 the protocol element is not known. 447 o The protocol element is part of a feature specified mandatory to 448 not implement in the minor version. In this case as well, all 449 implementations of the minor version MUST indicate that the 450 protocol element is not known. 452 o The protocol element is defined as part of the current variant of 453 the minor version but is not part of the corresponding base 454 variant. In this case, the requester can encounter situations in 455 which the protocol element is either not known to the responder, 456 is known to but not supported by the responder, or is both known 457 to and supported by the responder. 459 o The protocol element is defined as an OPTIONAL part of the base 460 minor version. In this case, the requester can expect the 461 protocol element to be known but must deal with cases in which it 462 is supported or is not supported. 464 o The protocol element is defined as a REQUIRED part of the base 465 minor version. In this case, the requester can expect the 466 protocol element to be both known and supported by the responder. 468 The listing of possibilities above does not mean that a requester 469 always needs to be prepared for all such possibilities. Often, 470 depending on the scope of the feature of which the protocol element 471 is a part, handling of a previous request using the same or related 472 protocol elements will allow the requester to be sure that certain of 473 these possibilities cannot occur. 475 Requesters, typically clients, may test for knowledge of or support 476 for protocol elements as part of connection establishment. This may 477 allow the requester to be aware of a responder's lack of knowledge of 478 or support for problematic requests before they are actually used to 479 effect user requests. 481 4.4. Inter-version Interoperability 483 Because of NFSv4's use of XDR extension, any communicating client and 484 server versions have XDR definitions such that each is a valid 485 extension of a third version. Once that version is determined, it 486 may be used by both client and server to communicate. Each party can 487 successfully use a subset of protocol elements that are both known to 488 and supported by both parties. 490 4.4.1. Requirements for Knowledge of Protocol Elements 492 With regard to requirements for knowledge of protocol elements, the 493 following rules apply. These rules are the result of the use of the 494 XDR extension paradigm combined with the way in which extensions are 495 incorporated in existing minor versions (for details of which see 496 Section 6). 498 o Any protocol element defined as part of the base variant of 499 particular minor version is required to be known by that minor 500 version. This occurs whether the specification happens in the 501 body of the minor definition document or is in a feature 502 definition document that is made part of the minor version by 503 being normatively referenced by the minor version definition 504 document. 506 o Any protocol element required to be known in a given minor version 507 is required to be known in subsequent minor versions, unless and 508 until a minor version has made that protocol element as mandatory 509 to not implement. 511 o When a protocol element is defined as part of an extension to an 512 extensible minor version, it is not required to be known in that 513 minor version but is required to be known by the next minor 514 version. In the earlier minor version, it might not be defined in 515 the XDR definition document, while in the later version it needs 516 to be defined in the XDR definition document. In either case, if 517 it is defined, it might or might not be supported. 519 o When knowledge of protocol elements is optional in a given minor 520 version, the responder's knowledge of such optional elements must 521 obey the rule that if one such element is known, then all the 522 protocol elements defined in the same minor version definition 523 document must be known as well. 525 For many minor versions, all existing protocol elements are required 526 to be known by both the client and the server, and so requesters do 527 not have to test for the presence or absence of knowledge regarding 528 protocol elements. This is the case if there has been no extension 529 for the minor version in question. Extensions can be added to 530 extensible minor versions as described in Section 6 and can be used 531 to correct protocol flaws as described in Section 9. 533 Requesters can ascertain the knowledge of the responder in two ways: 535 o By issuing a request using the protocol element and looking at the 536 response. Note that, even if the protocol element used is not 537 supported by the responder, the requester can still determine if 538 the element is known by the responder. 540 o By receiving a request from the responder, acting in the role of 541 requester. For example, a client may issue a request enabling the 542 server to infer that it is aware of a corresponding callback. 544 In making this determination, the requester can rely on two basic 545 facts: 547 o If the responder is aware of a single protocol element within a 548 feature package, it must be aware of all protocol elements within 549 that feature package. 551 o If a protocol element is one defined by the minor version 552 specified by a request (and not in an extension), or in a previous 553 minor version, the responder must be aware of it. 555 4.4.2. Establishing Interoperability 557 When a client and a server interact, they need to able to take 558 advantage of the compatibility provided by NFSv4's use of XDR 559 extension. 561 In this context, the client and server would arrive at a common 562 variant which the client uses to send requests which the server would 563 then accept. The server would use that variant to send callbacks 564 which the client would then accept. This state of affairs could 565 arise in a number of ways: 567 o Client and server have been built using XDR variants that belong 568 to the same minor version. 570 o The client's minor version is lower than that of the server. In 571 this case the server, in accord with Section 8.2, accepts the 572 client's minor version, and acts as if it has no knowledge of 573 extensions made in subsequent minor versions. It has knowledge of 574 protocol elements within the current (i.e. effectively final) 575 variant of the lower minor version. 577 o The client's minor version is higher than that of the server. In 578 this case the client, in accord with Section 8.2, uses a lower 579 minor version that the server will accept. In this case, the 580 server has no knowledge of extensions made in subsequent minor 581 versions. 583 There are a number of cases to consider based on the characteristics 584 of the minor version chosen. 586 o When the minor version consists of only a single variant (no 587 extension or XDR corrections), the client and the server are using 588 the same XDR description and have knowledge of the same protocol 589 elements. 591 o When the minor version consists of multiple variants (i.e. there 592 are one or more XDR extensions or XDR corrections), the client and 593 the server are using compatible XDR descriptions. The client is 594 aware of some set of extensions while the server may be aware of a 595 different set. The client can use the approach described in 596 Section 4.4.3 to determine which of the extensions it knows about 597 are also known by the server. Once this is done, the client and 598 server will both be using a common variant. The variants that the 599 client and the server were built with will both either be 600 identical to this variant or a valid extension of it. Similarly, 601 the variants that the client and the server actually use will be a 602 subset of this variant, in that certain OPTIONAL features will not 603 be used. 605 In either case, the client must determine which of the OPTIONAL 606 protocol elements within the common version are supported by the 607 server, just as it does for OPTIONAL features introduced as part of a 608 minor version. 610 It is best if client implementations make the determination as to the 611 support provided by the server before acting on user requests. This 612 includes the determination of the common protocol variant and the 613 level of support for OPTIONAL protocol elements. 615 4.4.3. Determining Knowledge of Protocol Elements 617 A requester may test the responder's knowledge of particular protocol 618 elements as defined below, based on the type of protocol element. 619 Note that in the case of attribute or flag bits, use of a request 620 that refers to 2 or more bits of undetermined status (known versus 621 unknown) may return results which are not particularly helpful. In 622 such cases, when the response is NFS4ERR_INVAL, the requester can 623 only conclude that at least one of the bits is unknown. 625 o When a GETATTR request is made specifying an attribute bit to be 626 tested and that attribute is not a set-only attribute, if the 627 GETATTR returns with the error NFS4ERR_INVAL, then it can be 628 concluded that the responder has no knowledge of the attribute in 629 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 630 indicate that the responder is aware of the attribute in question. 632 o When a SETATTR request is made specifying the attribute bit to be 633 tested and that attribute is not a get-only attribute, if the 634 SETATTR returns with the error NFS4ERR_INVAL, then it can be 635 concluded that the responder has no knowledge of the attribute in 636 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 637 indicate that the responder is aware of the attribute in question. 639 o When a request is made including an operation with a new flag bit, 640 if the operation returns with the error NFS4ERR_INVAL,then it can 641 generally be concluded that the responder has no knowledge of the 642 flag bit in question, as long as the requester is careful to avoid 643 other error situations in which the operation in question is 644 defined as returning NFS4ERR_INVAL. Other responses indicate that 645 the responder is aware of the flag bit in question. 647 o When a request is made including the operation to be tested, if 648 the responder returns an RPC XDR decode error, or a response 649 indicating that the operation in question resulted in 650 NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded 651 that the responder has no knowledge of the operation in question. 652 Other responses, including NFS4ERR_NOTSUPP, indicate that the 653 responder is aware of the operation in question. 655 o When a request is made including the switch arm to be tested, if 656 the responder returns an RPC XDR decode error, or a response 657 indicating that the operation in question resulted in 658 NFS4ERR_BADXDR, then it can be concluded that the responder has no 659 knowledge of the operation in question. Other responses, 660 including NFS4ERR_UNION_NOTSUPP, indicate that the responder is 661 aware of the protocol element in question. 663 A determination of the knowledge or lack of knowledge of a particular 664 protocol element is expected to remain valid as long as the clientid 665 associated with the request remains valid. 667 The above assumes, as should be the case, that the server will accept 668 the minor version used by the client. For more detail regarding this 669 issue, see Section 8.2. 671 4.5. XDR Overlay 673 XDR additions may also be made by defining XDR structures that 674 overlay nominally opaque fields that are defined to allow such 675 incremental extensions. 677 For example, each pNFS mapping type provides its own XDR definition 678 for various pNFS-related fields defined in [RFC5661] as opaque 679 arrays. 681 Because such additions provide new interpretations of existing 682 fields, they may be made outside of the extension framework as long 683 as they obey the rules previously established when the nominally 684 opaque protocol elements were added to the protocol. 686 5. Other NFSv4 Protocol Changes 688 There are a number of types of protocol changes that are outside the 689 XDR extension framework discussed in Section 4. These changes are 690 also managed within the NFSv4 versioning framework and may be of a 691 number of types, which are discussed in the sections below. 693 Despite the previous emphasis on XDR changes, additions and changes 694 to the NFSv4 protocols have not been limited to those that involve 695 changes (in the form of extensions) to the protocol XDR. Examples of 696 other sorts of changes have been taken from NFSv4.1. 698 All such changes that have been made in the past have been made as 699 part of new minor version. Future change of these sorts may not be 700 done in an extension but can only be made in a new minor version. 702 5.1. Field Interpretation and Use 704 The XDR description of a protocol does not constitute a complete 705 description of the protocol. Therefore, versioning needs to consider 706 the role of changes in the use of fields, even when there is no 707 change to the underlying XDR. 709 Although any XDR element is potentially subject to a change in its 710 interpretation and use, the likelihood of such change will vary with 711 the XDR-specified type of the element, as discussed below: 713 o When XDR elements are defined as strings, rules regarding the 714 appropriate string values are specified in protocol specification 715 text with changes in such rules documented in minor version 716 definition documents. Some types of strings within NFS4 are used 717 in server names (in location-related attributes), user and group 718 names, and in the names of file objects within directories. Rules 719 regarding what strings are acceptable appear in [RFC7530] and 720 [RFC5661] with the role of the XDR limited to hints regarding 721 UTF-8 and capitalization issues via XDR typedefs. 723 o Fields that are XDR-defined as opaque elements and which are truly 724 opaque, do not raise versioning issues, except as regards inter- 725 version use, which is effectively foreclosed by the rules in 726 Section 8.1. 728 Note that sometimes a field will seem to be opaque but not 729 actually be fully opaque when considered carefully. For example, 730 the "other" field of stateids is defined as an opaque array, while 731 the specification text specially defines appropriate treatment 732 when the "other" field within it is either all zeros or all ones. 733 Given this context, creation or deletion of reserved values for 734 "special" stateids will be a protocol change which versioning 735 rules need to deal with. 737 o Some nominally opaque elements have external XDR definitions that 738 overlay the nominally opaque arrays. Such cases are discussed in 739 Section 4.5. 741 5.2. Behavioral Changes 743 Changes in the behavior of NFSv4 operations are possible, even if 744 there is no change in the underlying XDR or change to field 745 interpretation and use. 747 One class of behavioral change involves changes in the set of errors 748 to be returned when various failure conditions occur. When the set 749 of valid requests remain the same, and the behavior for each of them 750 remains the same, such changes can be implemented with only limited 751 disruption to existing clients. 753 Many more substantial behavioral changes have occurred in connection 754 with the addition of the session concept in NFSv4.1. Even though 755 there was no change to the XDR for existing operations, many existing 756 operations and COMPOUNDs consisting only of them became invalid. 758 Also, changes were made regarding the required server behavior as to 759 the interaction of the MODE and ACL attributes. 761 6. Extending Existing Minor Versions 763 Extensions to the most recently published NFSv4 minor version may be 764 made by publishing the extension as a Proposed Standard, unless the 765 minor version in question has been defined as non-extensible. A 766 document need not use the "Updates" header specifying the RFC that 767 defines the minor version, which remains a valid description of the 768 base variant of the minor version in question. 770 In addition to following the rules for XDR extensions in Section 4.2, 771 such extensions must also obey the rules listed below in order to 772 allow interoperability to be established, as described in 773 Section 4.4: 775 o Additions to the set of callback requests and extensions to the 776 XDR for existing callback operations can only be made if the 777 server can determine, based on the client's actions, that that 778 client is aware of the changes. This determination, for any 779 particular client (as defined by its clientid), is made before 780 sending those new or extended callbacks. 782 o XDR extensions that affect the structures of responses to existing 783 operations can only be made if the server can determine, based on 784 the client's actions, that it is aware of the existence of XDR 785 changes, before sending responses containing those extensions. 786 This determination can be based on the request being responded to, 787 but that is not required. Use of any protocol element defined in 788 the extension can be the basis of the determination, provided that 789 the requirements for determining client awareness are clearly 790 stated. 792 Corrections to protocol errors (see Section 9) may be accomplished by 793 publishing an extension, including a compatible XDR change which 794 follows the rules above. Such documents will update the defining 795 documents for the minor version to be corrected. 797 In some cases extensions will contain elements such as new operations 798 or previously invalid switch cases. Although it is possible to 799 determine whether these OPTIONAL elements are supported using the 800 rules described above, those defining an extension that contains such 801 elements have the choice of defining a new attribute that indicates 802 whether the feature is present and supported. Since it is easy to 803 determine whether a new attribute is supported using the 804 supported_attrs attribute, this can make it simple and convenient for 805 clients to determine whether support is present, particularly when a 806 feature involves support for multiple such elements. 808 7. Minor Versions 810 7.1. Creation of New Minor Versions 812 It is important to note that this section, in describing situations 813 that would require new minor versions to be created, does not thereby 814 imply that situations will exist in the future. Judgments regarding 815 desirability of future changes will be made by the working group or 816 its successors and any guidance that can be offered at this point is 817 necessarily quite limited. 819 Creation of a new minor version is an option that the working group 820 retains. The listing of situations below that would prompt such 821 actions is not meant to be exhaustive. 823 The following sorts of features are not allowed as extensions and 824 would require creation of a new minor version: 826 o Features that incorporate any of the non-XDR-based changes 827 discussed in Sections 5.1 and 5.2. 829 o Features whose XDR changes do not follow the rules in Section 6. 831 o Addition of REQUIRED new features. 833 o Changes to the status of existing features including converting 834 features to be mandatory to not implement. 836 8. Minor Version Interaction Rules 838 This section addresses issues related to rules #11 and #13 in the 839 minor versioning rules in [RFC5661]. With regard to the supersession 840 of minor versioning rules, the treatment here overrides that in 841 [RFC5661] when either of the potentially interacting minor versions 842 has not yet been published as a Proposed Standard. 844 Note that these rules are the only ones directed to minor version 845 implementers, rather than to those specifying new minor versions. 847 8.1. Minor Version Identifier Transfer Issues 849 Each relationship between a client instance and a server instance, as 850 represented by a clientid, is to be devoted to a single minor 851 version. If a server detects that a COMPOUND with an inappropriate 852 minor version is being used, it MUST reject the request. In doing 853 so, it may return either NFS4ERR_BAD_CLIENTID or 854 NFS4RR_MINOR_VERS_MISMATCH. 856 As a result of the above, the client has the assurance that the set 857 of REQUIRED and OPTIONAL features will not change within the context 858 of a single clientid. Server implementations MUST ensure that the 859 set of supported features and protocol elements does not change 860 within such a context. 862 8.2. Minor Version Compatibility 864 The goal of the NFSv4 extension model is to enable compatibility 865 including compatibility between clients and servers implementing 866 different minor versions. 868 Within a set of minor versions that define the same set of features 869 as REQUIRED and mandatory to not implement, it is relatively easy for 870 clients and servers to provide the needed compatibility by adhering 871 to the following practices. 873 o Servers supporting a given minor version should support earlier 874 minor versions within that set and return appropriate errors for 875 use of protocol elements that were not a valid part of that 876 earlier minor version. For details see below. 878 o Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by 879 searching for a lower minor version number that the server will 880 accept. 882 Servers supporting a given minor version MUST, in returning errors 883 for operations which were a valid part of the minor version, return 884 the errors allowed for the current operation in the minor version 885 actually being used. 887 With regard to protocol elements not known in a given minor version, 888 the appropriate error codes are given below. Essentially, the 889 server, although it has a more extensive XDR reflective of a newer 890 minor version, must act as a server with a more limited XDR would. 892 o When an operation is used which is not known in the specified 893 minor version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) 894 should be returned. 896 o When an attribute is used which is not known in the specified 897 minor version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) 898 should be returned. 900 o When a switch case is used which is not known in the specified 901 minor version, NFS4ERR_BADXDR (as opposed to 902 NFS4ERR_UNION_NOTSUPP) should be returned. Even though the 903 message may be XDR-decodable by the server's current XDR, it is 904 not so according to the minor version being used. 906 o When a flag bit is used which is not known in the specified minor 907 version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP or any other 908 error defined as indicating non-support of a flag bit) should be 909 returned. 911 9. Correction of Existing Minor Versions and Features 913 The possibility always exists that there will be a need to correct an 914 existing feature in some way, after the acceptance of that feature, 915 or a minor version containing it, as a Proposed Standard. While the 916 working group can reduce the probability of such situations arising 917 by waiting for running code before considering a feature as done, it 918 cannot reduce the probability to zero. As features are used more 919 extensively and interact with other features, previously unseen flaws 920 may be discovered and will need to be corrected. 922 Such corrections are best done in a document obsoleting or updating 923 the RFC defining the relevant feature or minor version. In making 924 such corrections, the working group will have to carefully consider 925 how to assure interoperability with older clients and servers. 927 Often, corrections can be done without changing the protocol XDR. In 928 many cases, a change in client and server behavior can be implemented 929 without taking special provision with regard to interoperability with 930 earlier implementations. In those cases, and in cases in which a 931 revision merely clarifies an earlier protocol definition document, a 932 new document can be published which simply updates the earlier 933 protocol definition document. 935 In other cases, it is best if client or server behavior needs to 936 change in a way which raises interoperability concerns. In such 937 cases, incompatible changes in server or client behavior should not 938 be mandated in order to avoid XDR changes. 940 9.1. XDR Changes to Implement Protocol Corrections 942 When XDR changes are necessary as part of correcting a flaw, these 943 should be done in a manner similar to that used when implementing new 944 minor versions or features within them. In particular, 946 o Existing XDR structures may not be modified or deleted. 948 o XDR extensions may be used to correct existing protocol facilities 949 in a manner similar to those used to add additional optional 950 features. Such corrections may be done in a minor version for 951 which optional features may no longer be added, if the working 952 group decides that it is an appropriate way to compatibly effect a 953 correction. 955 o When a correction is made to an OPTIONAL feature, the result is 956 similar to a situation in which there are two independent OPTIONAL 957 features. A server may choose to implement either or both. See 958 Section 9.2 for a detailed discussion of interoperability issues. 960 o When a correction is made to a REQUIRED feature, the situation 961 becomes one in which the old version of the feature remains 962 REQUIRED while the corrected version, while OPTIONAL, in intended 963 to be adopted to provide correct operation. Although use of the 964 corrected version is ultimately better, and may be recommended, it 965 should not be described as "RECOMMENDED", since the choice of 966 versions to support will depend on the needs of clients, which may 967 be slow to adopt the updated version. The nature of such 968 corrections is such that it may result in situations in which 969 different variants of the same minor version may not both support 970 the corrected version. See Section 9.3 for details. 972 o In all of the cases above, it is appropriate that the old version 973 of the feature be considered obsolescent, with the expectation 974 that the working group might, in a later minor version, change the 975 status of the uncorrected version. See Section 9.4 for more 976 detail. 978 9.2. XDR Corrections to OPTIONAL Features 980 By defining the corrected and uncorrected version as independent 981 OPTIONAL features, the protocol with the XDR modification can 982 accommodate clients and servers that support either the corrected or 983 the uncorrected version of the protocol and also clients and servers 984 aware of and capable of supporting both alternatives. 986 Based on the type of client: 988 o A client that uses only the earlier version of the feature (i.e., 989 an older unfixed client) can determine whether the server it is 990 connecting to supports the older version of feature. It is 991 capable of interoperating with older servers that support only the 992 unfixed protocol as well as ones that support both versions. 994 o A client that supports only the corrected version of the feature 995 (i.e., a new or updated client) can determine whether the server 996 it is connecting to supports the newer version of the feature. It 997 is capable of interoperating with newer servers that support only 998 the updated feature as well as ones that support both versions. 1000 o A client that supports both the older and newer version of the 1001 feature can determine which version of the particular feature is 1002 supported by the server it is working with. 1004 Based on the type of server: 1006 o A server that supports only the earlier version of the feature 1007 (i.e., an older unfixed server) can only successfully interoperate 1008 with clients implementing the older version. However, clients 1009 that do not implement the older version of the feature can easily 1010 determine that the feature cannot be used on that server. 1012 o A server that supports only the newer version of the feature 1013 (i.e., a new or updated server) can only successfully interoperate 1014 with newer clients. However, older clients can easily determine 1015 that the feature cannot be used on that server. In the case of 1016 OPTIONAL features, clients can be expected to deal with non- 1017 support of that particular feature. 1019 o A server that supports both the older and newer versions of the 1020 feature can interoperate with all client variants. 1022 By using extensions in this manner, the protocol creates a clear path 1023 which preserves the functioning of existing clients and servers and 1024 allows client and server implementers to adopt the new version of the 1025 feature at a reasonable pace. 1027 9.3. XDR Corrections to REQUIRED Features 1029 Interoperability issues in this case are similar to those for the 1030 OPTIONAL case described above (in Section 9.2). However, because the 1031 use of the uncorrected version is REQUIRED, servers have to support 1032 this until there is a minor version change. Nevertheless, there is 1033 the opportunity for clients and servers to implement the corrected 1034 version, while maintaining necessary interoperability with earlier 1035 implementations. 1037 The following types of servers can exist: 1039 o Servers only aware of and supporting the uncorrected version, such 1040 as servers developed before the issue requiring correction was 1041 known. 1043 o Servers aware of both versions while only supporting the 1044 uncorrected version. 1046 o Servers aware of and supporting both versions. 1048 With the exception of clients which do not use the feature in 1049 question, the following sorts of clients may exist: 1051 o Clients only aware of and prepared to use the uncorrected version, 1052 such as those developed before the issue requiring correction was 1053 known. 1055 Clients developed before the correction was defined would be of 1056 this type. They would be capable of interoperating with all of 1057 the types of servers listed above, but could not use the corrected 1058 version. 1060 o Clients aware of both versions while only prepared to use the 1061 uncorrected version. 1063 Some clients developed or modified after the correction was 1064 defined would be of this type, until they were modified to support 1065 the corrected version. They would also be capable of 1066 interoperating with all of the types of servers listed above, but 1067 could not use the corrected version. 1069 o Clients aware of and prepared to use either version. 1071 Such clients would be capable of interoperating with all of the 1072 types of servers listed above, and could use the corrected version 1073 with servers that supported it. 1075 o Clients aware of both versions while only prepared to use the 1076 newer, corrected, version. 1078 Such clients would only be capable of interoperating with servers 1079 that supported the corrected version. With other types of 1080 servers, they could determine the absence of appropriate support 1081 at an early stage and treat the minor version in question as 1082 unsupported by the server. Such clients are only likely to be 1083 deployed when the majority of servers support the corrected 1084 version. 1086 9.4. Addressing XDR Corrections in Later Minor Versions 1088 As described in Sections 9.2 and 9.3, a corrected XDR can be 1089 incorporated in an existing minor version and be used, while an 1090 existing uncorrected version is still supported. Nevertheless, the 1091 uncorrected version will remain part of the protocol until its status 1092 is changed in a later minor version. 1094 One possible change that could be made in a later minor version is to 1095 define the uncorrected version as mandatory to not implement. 1096 Because of the difficulty of determining that no clients depend on 1097 support for the uncorrected version, it is unlikely that this step 1098 would be appropriate for a considerable time. 1100 In the case of a correction to a REQUIRED feature, there are a number 1101 of less disruptive changes that could be made earlier: 1103 o Changing the uncorrected version from REQUIRED to OPTIONAL while 1104 REQUIRING that servers support at least one of the two versions. 1106 This would allow new server implementations to avoid support for 1107 the uncorrected version. 1109 o Changing the corrected version from OPTIONAL to REQUIRED, making 1110 both versions REQUIRED. 1112 This would allow new clients to depend on support for the 1113 corrected version being present. 1115 o Changing the uncorrected version from REQUIRED to OPTIONAL while 1116 changing the corrected version from OPTIONAL to REQUIRED. 1118 This would complete the shift to the corrected version once 1119 clients are prepared to use the corrected version. 1121 In making such changes, interoperability issues would need to be 1122 carefully considered. 1124 10. Security Considerations 1126 Since no substantive protocol changes are proposed here, no security 1127 considerations apply. 1129 11. IANA Considerations 1131 The current document does not require any actions by IANA. 1133 12. References 1134 12.1. Normative References 1136 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1137 Requirement Levels", BCP 14, RFC 2119, 1138 DOI 10.17487/RFC2119, March 1997, 1139 . 1141 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 1142 "Network File System (NFS) Version 4 Minor Version 1 1143 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, 1144 . 1146 [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 1147 (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, 1148 March 2015, . 1150 [RFC7862] Haynes, T., "Network File System (NFS) Version 4 Minor 1151 Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862, 1152 November 2016, . 1154 12.2. Informative References 1156 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 1157 Beame, C., Eisler, M., and D. Noveck, "Network File System 1158 (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530, 1159 April 2003, . 1161 Appendix A. Acknowledgements 1163 The author wishes to thank Tom Haynes of Primary Data for his role in 1164 getting the effort to revise NFSV4 version management started and for 1165 his work in co-authoring the first version of this document. 1167 The author also wishes to thank Chuck Lever and Mike Kupfer of Oracle 1168 and Bruce Fields of Red Hat for their helpful reviews of this and 1169 other versioning-related documents. 1171 Author's Address 1173 David Noveck 1174 NetApp 1175 1601 Trapelo Road 1176 Waltham, MA 02451 1177 US 1179 Phone: +1 781 572 8038 1180 Email: davenoveck@gmail.com