idnits 2.17.1 draft-ietf-nfsv4-versioning-07.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 (October 22, 2016) is 2715 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, xxxx (if approved) October 22, 2016 5 Intended status: Standards Track 6 Expires: April 25, 2017 8 Rules for NFSv4 Extensions and Minor Versions. 9 draft-ietf-nfsv4-versioning-07 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 April 25, 2017. 39 Copyright Notice 41 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 3 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 . . . . . . . . . . . . . . . . . . . . . . 7 64 4.2. Rules for XDR Extension within NFSv4 . . . . . . . . . . 8 65 4.3. Handling of Protocol Elements . . . . . . . . . . . . . . 9 66 4.4. Inter-version Interoperability . . . . . . . . . . . . . 10 67 4.4.1. Requirements for Knowledge of Protocol Elements . . . 10 68 4.4.2. Establishing Interoperability . . . . . . . . . . . . 12 69 4.4.3. Determining Knowledge of Protocol Elements . . . . . 13 70 4.5. XDR Overlay . . . . . . . . . . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . 16 75 7. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 16 76 7.1. Creation of New Minor Versions . . . . . . . . . . . . . 16 77 8. Minor Version Interaction Rules . . . . . . . . . . . . . . . 17 78 8.1. Minor Version Identifier Transfer Issues . . . . . . . . 17 79 8.2. Minor Version Compatibility . . . . . . . . . . . . . . . 18 80 9. Correction of Existing Minor Versions and Features . . . . . 19 81 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 19 82 9.2. XDR Corrections to required features . . . . . . . . . . 21 83 10. Security Considerations . . . . . . . . . . . . . . . . . . . 22 84 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 85 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 86 12.1. Normative References . . . . . . . . . . . . . . . . . . 22 87 12.2. Informative References . . . . . . . . . . . . . . . . . 23 88 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 23 89 Appendix B. Instructions for RFC Editor . . . . . . . . . . . . 23 90 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23 92 1. Introduction 94 To address the requirement for an NFS protocol that can evolve as the 95 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 96 provides a framework to allow for future changes via the creation of 97 new protocol versions including minor versions and certain forms of 98 modification of existing minor versions. The extension rules 99 contained in this document allow extensions and other changes to be 100 implemented in a way that maintains compatibility with existing 101 clients and servers. 103 Previously, all protocol changes had been part of new minor versions. 104 The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the 105 minor version being used by the client in making requests. The 106 CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) specifies the 107 minor version being used by the server on callback requests. 109 Creation of a new minor version is no longer the only way in which 110 protocol changes may be made. Optional features may be added as 111 extensions and protocol corrections can be proposed, specified and 112 implemented within the context of a single minor version. Creation 113 of new minor versions remains available to make other sorts of 114 changes. 116 The goal of allowing extensions within the context of a minor version 117 is provide more implementation flexibility while preserving 118 interoperability on protocol upgrade. As described in Section 4.4, 119 two implementations can each choose to implement a subset of 120 available extensions, enabling interoperation to proceed just as if 121 both implementations supported only the parts of the protocol they 122 both support. 124 2. Terminology 126 A basic familiarity with NFSv4 terminology is assumed in this 127 document and the reader is pointed to [RFC7530]. 129 In this document, the term "version" is not limited to minor 130 versions. When minor versions are meant, the term "minor version" is 131 used explicitly. For more discussion of this and related terms, see 132 Section 2.3 134 A "feature package" is a set of features that are defined together, 135 either as part of a minor version or as part of the same protocol 136 extension. 138 2.1. Use of Keywords Defined in RFC2119 140 The keywords defined by [RFC2119] have special meanings which this 141 document intends to adhere to. However, due to the nature of this 142 document and some special circumstances, there are some complexities 143 to take note of: 145 o Where this document does not directly specify implementation 146 requirements, use of these capitalized terms is often not 147 appropriate, since the guidance given in this document does not 148 directly affect interoperability. 150 o In this document, what authors of RFCs defining features and minor 151 versions need to do is stated without these specialized terms. 152 Although it is necessary to follow this guidance to provide 153 successful NFSv4 protocol extension, that sort of necessity is not 154 of the sort defined as applicable to the use of the keywords 155 defined in [RFC2119]. 157 The fact that these capitalized terms are not used should not be 158 interpreted as indicating that this guidance does not need to be 159 followed or is somehow not important. 161 o In speaking of the possible statuses of features and feature 162 elements, the terms "OPTIONAL" and "REQUIRED" are used. For 163 further discussion, see Section 2.2. 165 o When one of these upper-case keywords defined in [RFC2119] is used 166 in this document, it is in the context of a rule directed to an 167 implementer of NFSv4 minor versions, the status of a feature or 168 protocol element, or in a quotation, sometimes indirect, from 169 another document. 171 2.2. Use of Feature Statuses 173 There has been some confusion, during the history of NFSv4, about the 174 correct use of these terms, and instances in which the keywords 175 defined in [RFC2119] were used in ways that appear to be at variance 176 with the definitions in that document. 178 o In [RFC3530], the lower-case terms "optional", "recommended", and 179 "required" were used as feature statuses, Later, in [RFC5661] and 180 [RFC7530], the corresponding upper-case keywords were used. It is 181 not clear why this change was made. 183 o In the case of "RECOMMENDED", its use as a feature status is 184 inconsistent with [RFC2119] and it will not be used for this 185 purpose in this document. 187 o The word "RECOMMENDED" to denote the status of attributes in 188 [RFC7530] and [RFC5661] raises similar issues. This has been 189 recognized in [RFC7530] with regard to NFSV4.0, although the 190 situation with regard to NFSv4.1 remains unresolved. 192 In this document, the keywords "OPTIONAL" and "REQUIRED" and the 193 phrase "mandatory to not implement" are used to denote the status of 194 features within a given minor version. In using these terms, RFCs 195 which specify the status of features inform: 197 o client implementations whether they need to deal with the absence 198 of support for these features. 200 o server implementations whether they need to provide support for 201 these features. 203 2.3. NFSv4 Versions 205 The term "version" denotes any valid protocol variant constructed 206 according to the rules in this document. It includes minor versions, 207 but there are situations which allow multiple variant versions to be 208 associated with and co-exist within a single minor version: 210 o When there are feature specification documents published as 211 Proposed Standards extending a given minor version, then the 212 protocol defined by the minor version specification document, when 213 combined with any subset (not necessarily proper) of the feature 214 specification documents, is a valid NFSv4 version variant which is 215 part of the minor version in question. 217 o When there are protocol corrections published which update a given 218 minor version, each set of published updates, up to the date of 219 publication of the update, is a valid NFSv4 version variant which 220 is part of the minor version in question. 222 Because of the above, there can be multiple version variants that are 223 part of a given minor version. Two of these are worthy of special 224 terms: 226 o The term "base minor version" denotes the version variant that 227 corresponds to the minor version as originally defined, including 228 all protocol elements specified in the minor version definition 229 document but not incorporating any extensions or protocol 230 corrections published subsequently. 232 o At any given time, the term "current minor version" denotes the 233 minor version variant including all extensions of and corrections 234 to the minor version made by standard-track documents published 235 subsequently. 237 Each version variant which is part of a given minor version is a 238 subset of the current minor version and a superset of the base minor 239 version. When the term "minor version" is used without either of 240 these qualifiers, it should refer to something which is true of all 241 variants within that minor version. For example, in the case of a 242 minor version that has not had a protocol correction, one may refer 243 to the set of REQUIRED features for that minor version since it is 244 the set is the same for all variants within the minor version. See 245 Section 9 for a discussion of correcting an existing minor version. 247 Each client and server which implements a specific minor version will 248 implement some particular variant of that minor version. Each of 249 these will be a superset of the appropriate base 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 [RFCv42]. 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 interversion 318 compatibility in situations in which the client and server use 319 different XDR descriptions. For example, the client and server may 320 implement different variants of the same minor version, in that they 321 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, no change in minor version 359 number is needed and the extension may be effected in the context of 360 a single minor version. 362 4.2. Rules for XDR Extension within NFSv4 364 In the context of NFSv4, an extension of a given XDR description 365 consists of one or more of the following: 367 o Addition of previously unspecified operation codes, within the 368 framework established by COMPOUND and CB_COMPOUND. 370 o Addition of previously unspecified attributes. 372 o Addition of new, previously unused, values to existing enums. 374 o Addition of previously unassigned bit values to a flag word. 376 o Addition of new cases to existing switches, provided that the 377 existing switch did not contain a default case. 379 However, none of the following is allowed to happen: 381 o Any change to the structure of existing requests or replies other 382 than those listed above. 384 o Addition of previously unspecified RPC operation codes, for either 385 the nfsv4 program or the callback program. 387 o Deletion of existing RPC operations, enum values, flag bit values 388 and switch cases. Note that changes may be made to define use of 389 any of these as causing an error, as long as the XDR is 390 unaffected. 392 o Similarly, none of these items may be reused for a new purpose. 394 4.3. Handling of Protocol Elements 396 Implementations handle protocol elements in one of three ways. Which 397 of the following ways are valid depends on the status of the protocol 398 element in the variant being implemented: 400 o The protocol element is not a part of definition of the variant in 401 question and so is "unknown". The responder, when it does not 402 report an RPC XDR decode error, reports an error indicative of the 403 element not being defined in the XDR such as NFS4ERR_OP_ILLEGAL, 404 NFS4ERR_BADXDR, or NFS4ERR_INVAL. See Section 4.4.3 for details. 406 o The protocol element is a known part of the variant but is not 407 supported by the particular implementation. The responder reports 408 an error indicative of the element being recognized as one which 409 is not supported such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, 410 or NFS4ERR_ATTRNOTSUPP. 412 o The protocol element is a known part of the variant which is 413 supported by the particular implementation. The responder reports 414 success or an error other than the special ones discussed above. 416 Which of these are validly returned by the responder depends on the 417 status of the protocol element in the minor version specified in the 418 COMPOUND or CB_COMPOUND. The possibilities which can exist when 419 dealing with minor versions that have not been subject to corrections 420 are listed below. See Sections 9.1 and 9.2 for a discussion of the 421 effects of protocol correction. 423 o The protocol element is not known in the minor version. In this 424 case all implementations of the minor version MUST indicate that 425 the protocol element is not known. 427 o The protocol element is part of a feature specified mandatory to 428 not implement in the minor version. In this case as well, all 429 implementations of the minor version MUST indicate that the 430 protocol element is not known. 432 o The protocol element is defined as part of the current variant of 433 the minor version but is not part of the corresponding base 434 variant. In this case, the requester can encounter situations in 435 which the protocol element is either not known to the responder, 436 is known to but not supported by the responder, or is both known 437 to and supported by the responder. 439 o The protocol element is defined as an OPTIONAL part of the base 440 minor version. In this case, the requester can expect the 441 protocol element to be known but must deal with cases in which it 442 is supported or is not supported. 444 o The protocol element is defined as a REQUIRED part of the base 445 minor version. In this case, the requester can expect the 446 protocol element to be both known and supported by the responder. 448 The listing of possibilities above does not mean that a requester 449 always needs to be prepared for all such possibilities. Often, 450 depending on the scope of the feature of which the protocol element 451 is a part, handling of a previous request using the same or related 452 protocol elements, will allow the requester to be sure that certain 453 of these possibilities cannot occur. 455 Requesters, typically clients, may test for knowledge of or support 456 for protocol elements as part of connection establishment. This may 457 allow the requester to be aware of responder lack of knowledge of or 458 support for problematic requests before they are actually used to 459 effect user requests. 461 4.4. Inter-version Interoperability 463 Because of NFSv4's use of XDR extension, any communicating client and 464 server versions have XDR definitions that are each valid extensions 465 of a third version. Once that version is determined, it may be used 466 by both client and server to communicate. Each party can 467 successfully use a subset of protocol elements that are both known 468 and supported by both parties. 470 4.4.1. Requirements for Knowledge of Protocol Elements 472 With regard to requirements for knowledge of protocol elements, the 473 following rules apply. These rules are the result of the use of the 474 XDR extension paradigm combined with the way in which extensions are 475 incorporated in existing minor versions (for details of which see 476 Section 6). 478 o Any protocol element defined as part of the base variant of 479 particular minor version is required to be known by that minor 480 version. This occurs whether the specification happens in the 481 body of the minor definition document or is in a feature 482 definition document that is made part of the minor version by 483 being normatively referenced by the minor version definition 484 document. 486 o Any protocol element required to be known in a given minor version 487 is required to be known in subsequent minor version, unless and 488 until a minor version has made that protocol element as mandatory 489 to not implement. 491 o When a protocol element is defined as part of an extension to an 492 extensible minor version, it is not required to be known in that 493 minor version but is required to be known by the next minor 494 version. In the earlier minor version, it might not be defined in 495 the XDR definition document, while in the later version it needs 496 to be defined in the XDR definition document. In either case, if 497 it is defined, it might or might not be supported. 499 o When knowledge of protocol elements is optional in a given minor 500 version, the responder's knowledge of such optional elements must 501 obey the rule that if one such element is known, then all the 502 protocol elements defined in the same minor version definition 503 document must be known as well. 505 For many minor versions, all existing protocol elements, are required 506 to be known by both the client and the server, and so requesters do 507 not have to test for the presence or absence of knowledge regarding 508 protocol elements for which knowledge might be optional. This is the 509 case if there has been no extension for the minor version in 510 question. Extensions can be added to extensible minor versions as 511 described in Section 6 and can be used to correct protocol flaws as 512 described in Section 9. 514 Requesters can ascertain the knowledge of the responder in two ways: 516 o By issuing a request using the protocol element and looking at the 517 response. Note that, even if the protocol element used is not 518 supported by the responder, the requester can still determine if 519 the element is known by the responder. 521 o By receiving a request from the responder, acting in the role of 522 requester. For example, a client may issue a request enabling the 523 server to infer that it is aware of a corresponding callback. 525 In making this determination, the requester can rely on two basic 526 facts: 528 o If the responder is aware of a single protocol element within a 529 feature package, it must be aware of all protocol elements within 530 that feature package 532 o If a protocol element is one defined by the minor version 533 specified by a request (and not in an extension), or in a previous 534 minor version, the responder must be aware of it. 536 4.4.2. Establishing Interoperability 538 When a client and a server interact, they need to able to take 539 advantage of the compatibility provided by NFSv4's use of XDR 540 extension. 542 In this context, the client and server would arrive at a common 543 variant which the client would uses to send requests which the server 544 would then accept. The server would use that variant to send 545 callbacks which the client would then accept. This state of affairs 546 could arise in a number of ways: 548 o Client and server have been built using XDR variants that belong 549 to the same minor version 551 o The client's minor version is lower than that of the server. In 552 this case the server, in accord with Section 8.2, accepts the 553 client's minor version, and acts as if it has no knowledge of 554 extensions made in subsequent minor versions. It has knowledge of 555 protocol elements within the current (i.e. effectively final) 556 variant of the lower minor version. 558 o The client's minor version is higher than that of the server. In 559 this case the client, in accord with Section 8.2, uses a lower 560 minor version that the server will accept. In this case, the 561 server has no knowledge of extensions made in subsequent minor 562 versions. 564 There are a number of cases to consider based on the characteristics 565 of the minor version chosen. 567 o The minor version consists of only a single variant (no extension 568 or XDR corrections), so the client and the server are using the 569 same XDR description and have knowledge of the same protocol 570 elements. 572 o When the minor version consists of multiple variants (i.e. there 573 are one or more XDR extensions or XDR corrections), the client and 574 the server are using compatible XDR descriptions. The client is 575 aware of some set of extensions while the server may be aware of a 576 different set. The client can determine which of the extensions 577 that he is aware of, are also known to the server by using the 578 approach described in Section 4.4.3. Once this is done, the 579 client and server will both be using a common variant. The 580 variants that the client and the server were built with will both 581 either be identical to this variant or a valid extension of it. 582 Similarly, the variants that the client and the server actually 583 use will be a subset of this variant, in that certain OPTIONAL 584 features will not be used. 586 In either case, the client must determine which of the OPTIONAL 587 protocol elements within the common version are supported by the 588 server, just as it does for OPTIONAL features introduced as part of a 589 minor version. 591 It is best if client implementations make the determination as to the 592 support provided by the server before acting on user requests. This 593 includes the determination of the common protocol variant and the 594 level of support for OPTIONAL protocol elements. 596 4.4.3. Determining Knowledge of Protocol Elements 598 A requester may test the responder's knowledge of particular protocol 599 elements as defined below, based on the type of protocol element. 600 Note that in the case of attribute or flag bits, use of a request 601 that refers to 2 or more bits of undetermined status (known versus 602 unknown) may return results which are not particularly helpful. In 603 such cases, when the response is NFS4ERR_INVAL, the requester can 604 only conclude that at least one of the bits is unknown. 606 o When a GETATTR request is made specifying an attribute bit to be 607 tested and that attribute is not a set-only attribute, if the 608 GETATTR returns with the error NFS4ERR_INVAL, then it can be 609 concluded that the responder has no knowledge of the attribute in 610 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 611 indicate that the responder is aware of the attribute in question. 613 o When a SETATTR request is made specifying the attribute bit to be 614 tested and that attribute is not a get-only attribute, if the 615 SETATTR returns with the error NFS4ERR_INVAL, then it can be 616 concluded that the responder has no knowledge of the attribute in 617 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 618 indicate that the responder is aware of the attribute in question. 620 o When a request is made including an operation with a new flag bit, 621 if the operation returns with the error NFS4ERR_INVAL,then it can 622 generally be concluded that the responder has no knowledge of the 623 flag bit in question, as long as the requester is careful to avoid 624 other error situations in which the operation in question is 625 defined as returning NFS4ERR_INVAL. Other responses indicate that 626 the responder is aware of the flag bit in question. 628 o When a request is made including the operation to be tested, if 629 the responder returns an RPC XDR decode error, or a response 630 indicating that the operation in question resulted in 631 NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded 632 that the responder has no knowledge of the operation in question. 633 Other responses, including NFS4ERR_NOTSUPP, indicate that the 634 responder is aware of the operation in question. 636 o When a request is made including the switch arm to be tested, if 637 the responder returns an RPC XDR decode error, or a response 638 indicating that the operation in question resulted in 639 NFS4ERR_BADXDR, then it can be concluded that the responder has no 640 knowledge of the operation in question. Other responses, 641 including NFS4ERR_UNION_NOTSUPP, indicate that the responder is 642 aware of the protocol element in question. 644 A determination of the knowledge or lack of knowledge of a particular 645 protocol element is expected to remain valid as long as the clientid 646 associated with the request remains valid. 648 The above assumes, as should be the case, that the server will accept 649 the minor version used by the client. For more detail regarding this 650 issue, see Section 8.2. 652 4.5. XDR Overlay 654 XDR additions may also be made by defining XDR structures that 655 overlay nominally opaque fields. defined to allow such incremental 656 extensions. 658 For example, each pNFS mapping type provides its own XDR definition 659 for various pNFS-related fields defined in [RFC5661] as opaque 660 arrays. 662 Because such additions provide new interpretations of existing 663 fields, they may be made outside of the extension framework as long 664 as they obey the rules previously established when the nominally 665 opaque protocol elements were added to the protocol. 667 5. Other NFSv4 Protocol Changes 669 There are a number of types of protocol changes that are outside the 670 XDR extension framework discussed in Section 4. These changes are 671 also managed within the NFSv4 versioning framework and may be of a 672 number of types, which are discussed in the sections below 674 Despite the previous emphasis on XDR changes, additions and changes 675 to the NFSv4 protocols have not been limited to those that involve 676 changes (in the form of extensions) to the protocol XDR. Examples of 677 other sorts of changes have been taken from NFSv4.1. 679 All such changes that have been made in the past have been made as 680 part of new minor version. Future change of these sorts may not be 681 done in an extension but can only be made in a new minor version. 683 5.1. Field Interpretation and Use 685 The XDR description of a protocol does not constitute a complete 686 description of the protocol. Therefore, versioning needs to consider 687 the role of changes in the use of fields, even when there is no 688 change to the underlying XDR. 690 Although any XDR element is potentially subject to a change in its 691 interpretation and use, the likelihood of such change will vary with 692 the XDR-specified type of the element, as discussed below: 694 o When XDR elements are defined as strings, rules regarding the 695 appropriate string values are specified in protocol specification 696 text with changes in such rules documented in minor version 697 definition documents. Some types of strings within NFS4 are used 698 in server names (in location-related attributes), user and group 699 names, and in the names of file objects within directories. Rules 700 regarding what strings are acceptable appear in [RFC7530] and 701 [RFC5661] with the role of the XDR limited to hints regarding 702 UTF-8 and capitalization issues via XDR typedefs. 704 o Fields that are XDR-defined as opaque elements and which are truly 705 opaque, do not raise versioning issues, except as regards inter- 706 version use, which is effectively foreclosed by the rules in 707 Section 8.1. 709 Note that sometimes a field will seem to be opaque but not 710 actually be fully opaque when considered carefully. For example, 711 the "other" field of stateids is defined as an opaque array, while 712 the specification text specially defines appropriate treatment 713 when the "other" field within it is either all zeros or all ones. 714 Given this context, creation or deletion of reserved values for 715 "special" stateids will be a protocol change which versioning 716 rules need to deal with. 718 o Some nominally opaque elements have external XDR definitions that 719 overlay the nominally opaque arrays. Such cases are discussed in 720 Section 4.5. 722 5.2. Behavioral Changes 724 Changes in the behavior of NFSv4 operations are possible, even if 725 there is no change in the underlying XDR or change to field 726 interpretation and use. 728 One class of behavioral change involves changes in the set of errors 729 to be returned in the event of various errors. When the set of valid 730 requests remain the same, and the behavior for each of them remains 731 the same, such changes can be implemented with only limited 732 disruption to existing clients. 734 Many more substantial behavioral changes have occurred in connection 735 with the addition of the session concept in NFSv4.1. Even though 736 there was no change to the XDR for existing operations, many existing 737 operations and COMPOUNDs consisting only of them became invalid. 739 Also, changes were made regarding the required server behavior as to 740 the interaction of the MODE and ACL attributes. 742 6. Extending Existing Minor Versions 744 Extensions to the most recently published NFSv4 minor version may be 745 made by publishing the extension as a Proposed Standard, unless the 746 minor version in question has been defined as non-extensible. A 747 document need not update the document defining the minor version, 748 which remains a valid description of the base variant of the minor 749 version in question. 751 Corrections to protocol errors (see Section 9) may be accomplished by 752 publishing an extension, including a compatible XDR change. Such 753 documents will update the defining documents for the corrected minor 754 version. 756 7. Minor Versions 758 7.1. Creation of New Minor Versions 760 It is important to note that this section, in describing situations 761 that would require new minor versions to be created, does not thereby 762 imply that situations will exist in the future. Judgments regarding 763 desirability of future changes will be made by the working group or 764 its successors and any guidance that can be offered at this point is 765 necessarily quite limited. 767 Creation of a new minor version is an option that the working group 768 retains. The listing of situations below that would prompt such 769 actions is not meant to be exhaustive. 771 The following sorts of features are not allowed as extensions and 772 would require creation of a new minor version: 774 o Features that incorporate any of the non-XDR-based changes 775 discussed in Sections 5.1 and 5.2. 777 o Addition of REQUIRED new features. 779 o Changes to the status of existing features including converting 780 features to be mandatory to not implement. 782 8. Minor Version Interaction Rules 784 This section addresses issues related to rules #11 and #13 in the 785 minor versioning rules in [RFC5661]. With regard to the supersession 786 of minor versioning rules, the treatment here overrides that in 787 [RFC5661] when either of the potentially interacting minor versions 788 has not yet been published as a Proposed Standard. 790 Note that these rules are the only ones directed to minor version 791 implementers, rather than to those specifying new minor versions. 793 8.1. Minor Version Identifier Transfer Issues 795 Each relationship between a client instance and a server instance, as 796 represented by a clientid, is to be devoted to a single minor 797 version. If a server detects that a COMPOUND with an inappropriate 798 minor version is being used, it MUST reject the request. In doing 799 so, it may return either NFS4ERR_BAD_CLIENTID or 800 NFS4RR_MINOR_VERS_MISMATCH. 802 As a result of the above, the client has the assurance that the set 803 of REQUIRED and OPTONAL features will not change within the context 804 of a single clientid. Server implementations MUST ensure that the 805 set of supported features and protocol elements does not change 806 within such a context. 808 8.2. Minor Version Compatibility 810 The goal of the NFSv4 extension model is to enable compatibility 811 including compatibility between clients and servers implementing 812 different minor versions. 814 Within a set of minor versions that define the same set of features 815 as REQUIRED and mandatory to not implement, it is relatively easy for 816 clients and servers to provide the needed compatibility by adhering 817 to the following practices. 819 o Servers supporting a given minor version should support earlier 820 minor versions within that set and return appropriate errors for 821 use of protocol elements that were not a valid part of that 822 earlier minor version. For details see below. 824 o Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by 825 searching for a lower minor version number that the server will 826 accept. 828 Servers supporting a given minor version MUST, in returning errors 829 for operations which were a valid part of the minor version, return 830 the errors allowed for the current operation in the minor version 831 actually being used. 833 With regard to protocol elements not known in a given minor version, 834 the appropriate error codes are given below. Essentially, the 835 server, although it has a more extensive XDR reflective of a newer 836 minor version, must act as a server with a more limited XDR would. 838 o When an operation is used which is not known in the specified 839 minor version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) 840 should be returned. 842 o When an attribute is used which is not known in the specified 843 minor version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) 844 should be returned. 846 o When a switch case is used which is not known in the specified 847 minor version, NFS4ERR_BADXDR (as opposed to 848 NFS4ERR_UNION_NOTSUPP) should be returned. Even though the 849 message may be XDR-decodable by the server's current XDR, it is 850 not so according to the minor version being used. 852 o When a flag bit is used which is not known in the specified minor 853 version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP or any other 854 error defined as indicated non-support a flag bit) should be 855 returned. 857 9. Correction of Existing Minor Versions and Features 859 The possibility always exists that there will be a need to correct an 860 existing feature in some way, after the acceptance of that feature or 861 a minor version containing it, as a Proposed Standard. While the 862 working group can reduce the probability of such situations arising 863 by waiting for running code before considering a feature as done, it 864 cannot reduce the probability to zero. As features are used more 865 extensively and interact with other features, previously unseen flaws 866 may be discovered and will need to be corrected. 868 Such corrections are best done in a document obsoleting or updating 869 the RFC defining the relevant feature definition document or minor 870 version specification. In making such corrections, the working group 871 will have to carefully consider how to assure interoperability with 872 older clients and servers. 874 Often, corrections can be done without changing the protocol XDR. In 875 many cases, a change in client and server behavior can be implemented 876 without taking special provision with regard to interoperability with 877 earlier implementations. In those case, and in cases in which a 878 revision merely clarifies an earlier protocol definition document, a 879 new document can be published which simply updates the earlier 880 protocol definition document. 882 In other cases, it is best if client or server behavior needs to 883 change in a way which raises interoperability concerns. In such 884 cases, incompatible changes in server or client behavior should not 885 be mandated in order to avoid XDR changes. 887 9.1. XDR Changes to Implement Protocol Corrections 889 When XDR changes are necessary as part of correcting a flaw, these 890 should be done in a manner similar to that used when implementing new 891 minor versions or features within them. In particular, 893 o Existing XDR structures may not be modified or deleted. 895 o XDR extensions may be used to correct existing protocol facilities 896 in a manner similar to those used to add additional optional 897 features. Such corrections may be done in a minor version for 898 which optional features may no longer be added, if the working 899 group decides that it is an appropriate to compatibly effect a 900 correction. 902 o When a correction is made to an OPTIONAL feature, the result is 903 similar to a situation in which there are two independent OPTIONAL 904 features. A server may choose to implement either or both. 906 o When a correction is made to a required feature, the situation 907 becomes one in which neither the old nor the new version of the 908 feature is required. Instead, it is required that a server 909 support at least one of the two, while each is individually 910 OPTIONAL. Although use of the corrected version is ultimately 911 better, and may be recommended, it should not be described as 912 "RECOMMENDED", since the choice of which version to support if 913 only one is supported will depend on the needs of clients, which 914 may be slow to adopt the updated version. The nature of such 915 corrections is such that it may result in situations in which 916 different variants of the same minor version may not support the 917 same set of REQUIRED protocol elements. See Section 9.2 for 918 details. 920 o In all of the cases above, it is appropriate that the old version 921 of the feature, be considered obsolescent, with the expectation 922 that the working group might, in a later minor version, decide 923 that the older version is to become mandatory to not implement. 925 By doing things this way, the protocol with the XDR modification can 926 accommodate clients and servers that support either the corrected or 927 the uncorrected version of the protocol and also clients and servers 928 aware of and capable of supporting both alternatives. 930 o A client that supports only the earlier version of the feature 931 (i.e., an older unfixed client) can determine whether the server 932 it is connecting to supports the older version of feature. It is 933 capable of interoperating with older servers that support only the 934 unfixed protocol as well as ones that support both versions. 936 o A client that supports only the corrected version of the feature 937 (i.e., a new or updated client) can determine whether the server 938 it is connecting to supports the newer version of the feature. It 939 is capable of interoperating with newer servers that support only 940 the updated feature as well as ones that support both versions. 942 o A client that supports both the older and newer version of the 943 feature can determine which version of the particular feature is 944 supported by the server it is working with. 946 o A server that supports only the earlier version of the feature 947 (i.e., an older unfixed server) can only successfully interoperate 948 with older clients. However newer clients can easily determine 949 that the feature cannot be used on that server. 951 o A server that supports only the newer version of the feature 952 (i.e., a new or updated server) can only successfully interoperate 953 with newer clients. However, older clients can easily determine 954 that the feature cannot be used on that server. In the case of 955 OPTIONAL features, clients can be expected to deal with non- 956 support of that particular feature. 958 o A server that supports both the older and newer versions of the 959 feature can interoperate with all client variants. 961 By using extensions in this manner, the protocol creates a clear path 962 which preserves the functioning of existing clients and servers and 963 allows client and server implementers to adopt the new version of the 964 feature at a reasonable pace. 966 9.2. XDR Corrections to required features 968 When protocol corrections are made to REQUIRED features, there can be 969 situations in which different implementations of the minor version 970 may implement distinct variants of that minor version. As a result, 971 they might not support (or have knowledge of) the same set of 972 REQUIRED protocol elements. In such situations, client and server 973 implementations might: 975 o Implement only the earlier uncorrected version of the REQUIRED 976 feature. 978 o Implement only the newer, corrected version of the REQUIRED 979 feature. 981 o Implement both the uncorrected and corrected versions of the 982 REQUIRED feature. 984 In such situations, clients can attempt to use the techniques 985 described in Sections 4.4.2 and 4.4.3 to arrive at a common protocol 986 variant to serve as a basis for interoperation. The fact that the 987 set of REQUIRED protocol elements might not be the same gives rise to 988 additional issues, since there might be cases in which the client and 989 server do not share a common version of the REQUIRED feature being 990 corrected. 992 o When the client implements only the uncorrected version of the 993 feature, it can successfully interoperate with servers which 994 support only the uncorrected version or both the corrected and 995 uncorrected versions. 997 o When the client implements only the corrected version of the 998 feature, it can successfully interoperate with servers which 999 support only the corrected version or both the corrected and 1000 uncorrected versions. 1002 o When the client is able to use both the uncorrected and corrected 1003 versions of the feature, it can successfully interoperate with 1004 servers which support either version or both versions. 1006 o When the client implements only the uncorrected version of the 1007 feature, it cannot successfully interoperate with servers which 1008 support only the corrected version. In this situation, it can 1009 determine that the implementations are incompatible just as it 1010 would have done if the server did not support the minor version in 1011 question. 1013 o When the client implements only the uncorrected version of the 1014 feature, it cannot successfully interoperate with servers which 1015 support only the uncorrected version. In this situation, it can 1016 determine that the implementations are incompatible just as it 1017 would have done if the server did not support the minor version in 1018 question. 1020 In such situations, clients and servers implemented after the 1021 corrected version is defined are well advised to support both the 1022 corrected and uncorrected versions. Nevertheless, once uncorrected 1023 implementations become uncommon, implementers have the option of only 1024 supporting the corrected version. 1026 10. Security Considerations 1028 Since no substantive protocol changes are proposed here, no security 1029 considerations apply. 1031 11. IANA Considerations 1033 The current document does not require any actions by IANA. 1035 12. References 1037 12.1. Normative References 1039 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1040 Requirement Levels", BCP 14, RFC 2119, 1041 DOI 10.17487/RFC2119, March 1997, 1042 . 1044 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 1045 "Network File System (NFS) Version 4 Minor Version 1 1046 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, 1047 . 1049 [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 1050 (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, 1051 March 2015, . 1053 [RFCv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", January 1054 2016, . 1057 12.2. Informative References 1059 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 1060 Beame, C., Eisler, M., and D. Noveck, "Network File System 1061 (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530, 1062 April 2003, . 1064 Appendix A. Acknowledgements 1066 The author wishes to thank Tom Haynes of Primary Data for his role in 1067 getting this effort started and his work in co-authoring the first 1068 version of the initial working group versioning document. 1070 The author also wishes to thank Chuck Lever and Mike Kupfer of Oracle 1071 and Bruce Fields of Red Hat for their helpful reviews of this and 1072 other versioning-related documents. 1074 Appendix B. Instructions for RFC Editor 1076 In a number of places, this document needs to refer to the RFC for 1077 NFSv4.2, which is in the process of being published as a Proposed 1078 Standard. Because this process is not yet complete, the following 1079 changes need to be made to adapt to the eventual assignment of an RFC 1080 number for that document. 1082 o Replacement of the string "xxxx" by the RFC number assigned, in 1083 the list of RFC's to be updated 1085 o Replacement of the reference anchor "RFCv42" by a string which 1086 reflects the RFC number assigned. Also, the bibliographic 1087 information associated with that reference will need to reflect 1088 the RFC publication. 1090 Author's Address 1091 David Noveck 1092 Hewlett Packard Enterprise 1093 165 Dascomb Road 1094 Andover, MA 01810 1095 US 1097 Phone: +1 978 474 2011 1098 Email: davenoveck@gmail.com