idnits 2.17.1 draft-dnoveck-nfsv4-extension-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC5661, but the abstract doesn't seem to directly say this. It does mention RFC5661 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (Using the creation date from RFC5661, updated by this document, for RFC5378 checks: 2005-10-21) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 23, 2016) is 2856 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5661 (Obsoleted by RFC 8881) -- Obsolete informational reference (is this intentional?): RFC 3530 (Obsoleted by RFC 7530) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 D. Noveck 3 Internet-Draft HPE 4 Updates: 5661 (if approved) June 23, 2016 5 Intended status: Standards Track 6 Expires: December 25, 2016 8 Rules for NFSv4 Extensions and Minor Versions. 9 draft-dnoveck-nfsv4-extension-00 11 Abstract 13 This document describes the rules relating to the extension of the 14 NFSv4 family of protocols. It covers the creation of minor versions, 15 the addition of optional features to existing minor versions, and the 16 correction of flaws in features already published as Proposed 17 Standards. The rules relating to the construction of minor versions 18 and the interaction of minor version implementations that appear in 19 this document supersede the minor versioning rules in RFC5661. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 25, 2016. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 3 58 2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 4 59 2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 5 60 3. Consolidation of Extension Rules . . . . . . . . . . . . . . 6 61 4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 7 63 4.2. Rules for XDR Extension within NFSv4 . . . . . . . . . . 8 64 4.3. Handling of Protocol Elements . . . . . . . . . . . . . . 9 65 4.4. Inter-version Interoperability . . . . . . . . . . . . . 10 66 4.4.1. Requirements for Knowledge of Protocol Elements . . . 10 67 4.4.2. Establishing Interoperability . . . . . . . . . . . . 12 68 4.4.3. Determining Knowledge of Protocol Elements . . . . . 13 69 4.5. XDR Overlay . . . . . . . . . . . . . . . . . . . . . . . 14 70 5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 14 71 5.1. Field Interpretation and Use . . . . . . . . . . . . . . 14 72 5.2. Behavioral Changes . . . . . . . . . . . . . . . . . . . 15 73 6. Extending Existing Minor Versions . . . . . . . . . . . . . . 16 74 7. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 16 75 7.1. Creation of New Minor Versions . . . . . . . . . . . . . 16 76 8. Minor Version Interaction Rules . . . . . . . . . . . . . . . 16 77 8.1. Minor Version Identifier Transfer Issues . . . . . . . . 17 78 8.2. Minor Version Compatibility . . . . . . . . . . . . . . . 17 79 9. Correction of Existing Minor Versions and Features . . . . . 18 80 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 19 81 10. Security Considerations . . . . . . . . . . . . . . . . . . . 20 82 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 83 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 84 12.1. Normative References . . . . . . . . . . . . . . . . . . 21 85 12.2. Informative References . . . . . . . . . . . . . . . . . 21 86 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 21 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 89 1. Introduction 91 To address the requirement for an NFS protocol that can evolve as the 92 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 93 provides a framework to allow for future changes via the creation of 94 new protocol versions including minor versions and certain forms of 95 modification of existing minor versions. The extension rules 96 contained in this document allow extensions and other changes to be 97 implemented in a way that maintains compatibility with existing 98 clients and servers. 100 Previously, all protocol changes had been part of new minor versions. 101 The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the 102 minor version being used by the client in making requests. The 103 CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) specifies the 104 minor version being used by the server on callback requests. 106 Creation of a new minor version is no longer the only way in which 107 protocol changes may be made. Added optional features and protocol 108 corrections can be proposed, specified and implemented within the 109 context of a single minor version. Creation of new minor versions 110 remains available to make other sorts of changes. 112 2. Terminology 114 A basic familiarity with NFSv4 terminology is assumed in this 115 document and the reader is pointed to [RFC7530]. 117 In this document, the term "version" is not limited to minor 118 versions. When minor versions are meant, the term "minor version" is 119 used explicitly. For more discussion of this and related terms, see 120 Section 2.3 122 A "feature package" is a set of features that are defined together, 123 either as part of a minor version or as part of the same protocol 124 extension. 126 2.1. Use of Keywords Defined in RFC2119 128 The keywords defined by [RFC2119] have special meanings which this 129 document intends to adhere to. However, due to the nature of this 130 document and some special circumstances, there are some complexities 131 to take note of: 133 o Where this document does not directly specify implementation 134 requirements, use of these capitalized terms is often not 135 appropriate, since the guidance given in this document does not 136 directly affect interoperability. 138 o In this document, what authors of RFCs defining features and minor 139 versions need to do is stated without these specialized terms. 140 Although it is necessary to follow this guidance to provide 141 successful NFSv4 protocol extension, that sort of necessity is not 142 of the sort defined as applicable to the use of the keywords 143 defined in [RFC2119]. 145 The fact that these capitalized terms are not used should not be 146 interpreted as indicating that this guidance does not need to be 147 followed or is somehow not important. 149 o In speaking of the possible statuses of features and feature 150 elements, the terms "OPTIONAL" and "REQUIRED" are used. For 151 further discussion, see Section 2.2. 153 o When one of these upper-case keywords defined in [RFC2119] is used 154 in this document, it is in the context of a rule directed to an 155 implementer of NFSv4 minor versions, the status of a feature or 156 protocol element, or in a quotation, sometimes indirect, from 157 another document. 159 2.2. Use of Feature Statuses 161 There has been some confusion, during the history of NFSv4, about the 162 correct use of these terms, and instances in which the keywords 163 defined in [RFC2119] were used in ways that appear to be at variance 164 with the definitions in that document. 166 o In [RFC3530], the lower-case terms "optional", "recommended", and 167 "required" were used as feature statuses, Later, in [RFC5661] and 168 [RFC7530], the corresponding upper-case keywords were used. It is 169 not clear why this change was made. 171 o In the case of "RECOMMENDED", its use as a feature status is 172 inconsistent with [RFC2119] and it will not be used for this 173 purpose in this document. 175 o The word "RECOMMENDED" to denote the status of attributes in 176 [RFC7530] and [RFC5661] raises similar issues. This has been 177 recognized in [RFC7530] with regard to NFSV4.0, although the 178 situation with regard to NFSv4.1 remains unresolved. 180 In this document, the keywords "OPTIONAL" and "REQUIRED" and the 181 phrase "mandatory to not implement" are used to denote the status of 182 features within a given minor version. In using these terms, RFCs 183 which specify the status of features inform: 185 o client implementations whether they need to deal with the absence 186 of support for these features. 188 o server implementations whether they need to provide support for 189 these features. 191 2.3. NFSv4 Versions 193 The term "version" denotes any valid protocol variant constructed 194 according to the rules in this document. It includes minor versions, 195 but there are situations which allow multiple variant versions to be 196 associated with and co-exist within a single minor version: 198 o When there are feature specification documents published as 199 Proposed Standards extending a given minor version, then the 200 protocol defined by the minor version specification document, when 201 combined with any subset (not necessarily proper) of the feature 202 specification documents, is a valid NFSv4 version variant which is 203 part of the minor version in question. 205 o When there are protocol corrections published which update a given 206 minor version, each set of published updates, up to the date of 207 publication of the update, is a valid NFSv4 version variant which 208 is part of the minor version in question. 210 Because of the above, there can be multiple version variants that are 211 part of a given minor version. Two of these are worthy of special 212 terms: 214 o The term "base minor version" denotes the version variant that 215 corresponds to the minor version as originally defined, including 216 all protocol elements specified in the minor version definition 217 document but not incorporating any extensions or protocol 218 corrections published subsequently. 220 o At any given time, the term "current minor version" denotes the 221 minor version variant including all extensions of and corrections 222 to the minor version made by standard-track documents published 223 subsequently. 225 Each version variant which is part of a given minor version is a 226 subset of the current minor version and a superset of the base minor 227 version. When the term "minor version" is used without either of 228 these qualifiers, it should refer to something which is true of all 229 variants within that minor version. For example, one may refer to 230 the set of REQUIRED features in a given minor version since it is the 231 same for all variants within the minor version. 233 Each client and server which implements a specific minor version will 234 implement some particular variant of that minor version. Each of 235 these will be a superset of the appropriate base minor version. 237 3. Consolidation of Extension Rules 239 In the past, the only existing extension rules were the minor 240 versioning rules that were being maintained and specified in the 241 Standards Track RFCs which defined the individual minor versions. In 242 the past, these minor versioning rules were modified on an ad hoc 243 basis for each new minor version. 245 More recently, minor versioning rules were specified in [RFC5661] 246 while modifications to those rules were allowed in subsequent minor 247 versions. 249 This document defines a set of extension rules, including rules for 250 minor version construction. These rules apply to all future changes 251 to the NFSv4 protocol. The rules are subject to change but any such 252 change should be part of a standards track RFC obsoleting or updating 253 this document. 255 Rather than a single list of extension rules, as was done in the 256 minor versioning rules in [RFC5661], this document defines multiple 257 sets of rules that deal with the various forms of protocol change 258 provided for in the NFSv4 extension framework. 260 o The kinds of XDR changes that may be made to extend NFSv4 are 261 addressed in the rules in Section 4.2. 263 o Minor version construction, including rules applicable to changes 264 which cannot be made in extensions to existing minor versions are 265 addressed in Section 7.1 267 o Minor version interaction rules are discussed in Sections 8.1 and 268 8.2. 270 This document supersedes minor versioning rules appearing in the 271 minor version specification RFC's, including those in [RFC5661]. As 272 a result, potential conflicts among documents should be addressed as 273 follows: 275 o The specification of the actual protocols for minor versions 276 previously published as Proposed Standards take precedence over 277 minor versioning rules in either this document or in the minor 278 version specification RFC's. In other words, if the transition 279 from version A to version B violates a minor versioning rule, the 280 version B protocol stays as it is. 282 o Since minor versioning rules #11 and #13 from [RFC5661] deal with 283 the interactions between multiple minor versions, the situation is 284 more complicated. See Section 8 for a discussion of these issues, 285 including how potential conflicts between rules are to be 286 resolved. 288 o Otherwise, any conflict between the extension rules in this 289 document and those in minor version specification RFC's are to be 290 resolved based on the treatment in this document. In particular, 291 corrections may be made as specified in Section 9 for all 292 previously specified minor versions and the extensibility of 293 previously specified minor versions is to be handled in accord 294 with Section 6. 296 Future minor version specification documents should avoid specifying 297 rules relating to minor versioning and reference this document in 298 connection with rules for NFSv4 extension. 300 4. XDR Considerations 302 As an extensible XDR-based protocol, NFSv4 has to ensure interversion 303 compatibility in situations in which the client and server use 304 different XDR descriptions. For example, the client and server may 305 implement different variants of the same minor version, in that they 306 each might add different sets of extensions to the base minor 307 version. 309 The XDR extension paradigm, discussed in Section 4.1, assures that 310 these descriptions are compatible, with clients and servers able to 311 determine and use those portions of the protocol that they both share 312 according to the method described in Section 4.4.2. 314 4.1. XDR Extension 316 When an NFSv4 version change requires a modification to the protocol 317 XDR, this is effected within a framework based on the idea of XDR 318 extension. This is opposed to transitions between major NFS versions 319 (including that between NFSv3 and NFSv4.0) in which the XDR for one 320 version was replaced by a different XDR for a newer version. 322 The XDR extension approach allows an XDR description to be extended 323 in a way which retains the structure of all previously valid 324 messages. If a base XDR description is extended to create a second 325 XDR description, the following will be true for the second 326 description to be a valid extension of the first: 328 o The set of valid messages described by the extended definition is 329 a superset of that described by the first. 331 o Each message within the set of valid messages described by the 332 base definition is recognized as having exactly the same 333 structure/interpretation using the extended definition. 335 o Each message within the set of messages described as valid by the 336 extended definition but not the base definition must be 337 recognized, using the base definition, as part of an extension not 338 provided for. 340 The use of XDR extension can facilitate compatibility between 341 different versions of the NFSv4 protocol. When XDR extension is used 342 to implement OPTIONAL features, the greatest degree of inter-version 343 compatibility is obtained. In this case, no change in minor version 344 number is needed and the extension may be effected in the context of 345 a single minor version. 347 4.2. Rules for XDR Extension within NFSv4 349 In the context of NFSv4, an extension of a given XDR description 350 consists of one or more of the following: 352 o Addition of previously unspecified operation codes, within the 353 framework established by COMPOUND and CB_COMPOUND. 355 o Addition of previously unspecified attributes. 357 o Addition of new, previously unused, values to existing enums. 359 o Addition of previously unassigned bit values to a flag word. 361 o Addition of new cases to existing switches, provided that the 362 existing switch did not contain a default case. 364 However, none of the following is allowed to happen: 366 o Any change to the structure of existing requests or replies other 367 than those listed above. 369 o Addition of previously unspecified RPC operation codes, for either 370 the nfsv4 program or the callback program, is not allowed. 372 o Deletion of existing RPC operations, enum values, flag bit values 373 and switch cases. Note that changes may be made to define use of 374 any of these as causing an error, as long as the XDR is 375 unaffected. 377 o Similarly, none of these items may be reused for a new purpose. 379 4.3. Handling of Protocol Elements 381 Implementations handle protocol elements in one of three ways. Which 382 of the following ways are valid depends on the status of the protocol 383 element in the variant being implemented: 385 o The protocol element is not a part of definition of the variant in 386 question and so is "unknown". The responder, when it does not 387 report an RPC XDR decode error, reports an error indicative of the 388 element not being defined in the XDR such as NFS4ERR_OP_ILLEGAL, 389 NFS4ERR_BADXDR, or NFS4ERR_INVAL. See Section 4.4.3 for details. 391 o The protocol element is a known part of the variant but is not 392 supported by the particular implementation. The responder reports 393 an error indicative of the element being recognized as one which 394 is not supported such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, 395 or NFS4ERR_ATTRNOTSUPP. 397 o The protocol element is a known part of the variant which is 398 supported by the particular implementation. The responder reports 399 success or an error other than the special ones discussed above. 401 Which of these are validly returned by the responder depends on the 402 status of the protocol element in the minor version specified in the 403 COMPOUND or CB_COMPOUND. The possibilities which can exist are 404 listed below. 406 o The protocol element is not known in the minor version. In this 407 case all implementations of the minor version MUST indicate that 408 the protocol element is not known. 410 o The protocol element is part of a feature specified mandatory to 411 not implement in the minor version. In this case as well, all 412 implementations of the minor version MUST indicate that the 413 protocol element is not known. 415 o The protocol element is defined as part of the current variant of 416 the minor version but is not part of the corresponding base 417 variant. In this case, the requester can encounter situations in 418 which the protocol element is either not known to the responder, 419 is known to but not supported by the responder, or is both known 420 to and supported by the responder. 422 o The protocol element is defined as an OPTIONAL part of the base 423 minor version. In this case, the requester can expect the 424 protocol element to be known but must deal with cases in which it 425 is supported or is not supported. 427 o The protocol element is defined as a REQUIRED part of the base 428 minor version. In this case, the requester can expect the 429 protocol element to be both known and supported by the responder. 431 The listing of possibilities above does not mean that a requester 432 always needs to be prepared for all such possibilities. Often, 433 depending on the scope of the feature of which the protocol element 434 is a part, handling of a previous request using the same or related 435 protocol elements, will allow the requester to be sure that certain 436 of these possibilities cannot occur. 438 Requesters, typically clients, may test for knowledge of or support 439 for protocol elements as part of connection establishment. This may 440 allow the requester to be aware of responder lack of knowledge of or 441 support for problematic requests before they are actually used to 442 effect user requests. 444 4.4. Inter-version Interoperability 446 Because of NFSv4's use of XDR extension, any communicating client and 447 server versions have XDR definitions that are each valid extensions 448 of a third version. Once that version is determined, it may be used 449 by both client and server to communicate. Each party can 450 successfully use a subset of protocol elements that are both known 451 and supported by both parties. 453 4.4.1. Requirements for Knowledge of Protocol Elements 455 With regard to requirements for knowledge of protocol elements, the 456 following rules apply. These rules are the result of the use of the 457 XDR extension paradigm combined with the way in which extensions are 458 incorporated in existing minor versions (for details of which see 459 Section 6). 461 o Any protocol element defined as part of the base variant of 462 particular minor version is required to be known by that minor 463 version. This occurs whether the specification happens in the 464 body of the minor definition document or is in a feature 465 definition document that is made part of the minor version by 466 being normatively referenced by the minor version definition 467 document. 469 o Any protocol element required to be known in a given minor version 470 is required to be known in subsequent minor version, unless and 471 until a minor version has made that protocol element as mandatory 472 to not implement. 474 o When a protocol element is defined as part of an extension to an 475 extensible minor version, it is not required to be known in that 476 minor version but is required to be known by the next minor 477 version. In the earlier minor version, it might not be defined in 478 the XDR definition document, while in the later version it needs 479 to be defined in the XDR definition document. In either case, if 480 it is defined, it might or might not be supported. 482 o When knowledge of protocol elements is optional in a given minor 483 version, the responder's knowledge of such optional elements must 484 obey the rule that if one such element is known, then all the 485 protocol elements defined in the same minor version definition 486 document must be known as well. 488 For many minor versions, all existing protocol elements, are required 489 to be known by both the client and the server, and so requesters do 490 not have to test for the presence or absence of knowledge regarding 491 protocol elements for which knowledge might be optional. This is the 492 case if there has been no extension for the minor version in 493 question. Extensions can be added to extensible minor versions as 494 described in Section 6 and can be used to correct protocol flaws as 495 described in Section 9. 497 Requesters can ascertain the knowledge of the responder in two ways: 499 o By issuing a request using the protocol element and looking at the 500 response. Note that, even if the protocol element used is not 501 supported by the responder, the requester can still determine if 502 the element is known by the responder. 504 o By receiving a request from the responder, acting in the role of 505 requester. For example, a client may issue a request enabling the 506 server to infer that it is aware of a corresponding callback. 508 In making this determination, the requester can rely on two basic 509 facts: 511 o If the responder is aware of a single protocol element within a 512 feature package, it must be aware of all protocol elements within 513 that feature package 515 o If a protocol element is one defined by the minor version 516 specified by a request (and not in an extension), or in a previous 517 minor version, the responder must be aware of it. 519 4.4.2. Establishing Interoperability 521 When a client and a server interact, they need to able to take 522 advantage of the compatibility provided by NFSv4's use of XDR 523 extension. 525 In this context, the client and server would arrive at a common 526 variant which the client would uses to send requests which the server 527 would then accept. The server would use that variant to send 528 callbacks which the client would then accept. This state of affairs 529 could arise in a number of ways: 531 o Client and server have been built using XDR variants that belong 532 to the same minor version 534 o The client's minor version is lower than that of the server. In 535 this case the server, in accord with Section 8.2, accepts the 536 client's minor version, and acts as if it has no knowledge of 537 extensions made in subsequent minor versions. It has knowledge of 538 protocol elements within the current (i.e. effectively final) 539 variant of the lower minor version. 541 o The client's minor version is higher than that of the server. In 542 this case the client, in accord with Section 8.2, uses a lower 543 minor version that the server will accept. In this case, the 544 server has no knowledge of extensions made in subsequent minor 545 versions. 547 There are a number of cases to consider based on the characteristics 548 of the minor version chosen. 550 o The minor version consists of only a single variant (no extension 551 or XDR corrections), so the client and the server are using the 552 same XDR description and have knowledge of the same protocol 553 elements. 555 o When the minor version consists of multiple variants (i.e. there 556 are one or more XDR extensions or XDR corrections), the client and 557 the server are using compatible XDR descriptions. The client is 558 aware of some set of extensions while the server may be aware of a 559 different set. The client can determine which of the extensions 560 that he is aware of, are also known to the server by using the 561 approach described in Section 4.4.3. Once this is done, the 562 client and server will both be using a common variant. The 563 variants that the client and the server were built with will both 564 either be identical to this variant or a valid extension of it. 565 Similarly, the variants that the client and the server actually 566 use will be a subset of this variant, in that certain OPTIONAL 567 features will not be used. 569 In either case, the client must determine which of the OPTIONAL 570 protocol elements within the common version are supported by the 571 server, just as it does for OPTIONAL features introduced as part of a 572 minor version. 574 4.4.3. Determining Knowledge of Protocol Elements 576 A requester may test the responder's knowledge of particular protocol 577 elements as defined below, based on the type of protocol element. 579 o When a GETATTR request is made specifying an attribute bit to be 580 tested and that attribute is not a set-only attribute, if the 581 GETATTR returns with the error NFS4ERR_INVAL, then it can be 582 concluded that the responder has no knowledge of the attribute in 583 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 584 indicate that the responder is aware of the attribute in question. 586 o When a SETATTR request is made specifying the attribute bit to be 587 tested and that attribute is not a get-only attribute, if the 588 SETATTR returns with the error NFS4ERR_INVAL, then it can be 589 concluded that the responder has no knowledge of the attribute in 590 question. Other responses, including NFS4ERR_ATTRNOTSUPP, 591 indicate that the responder is aware of the attribute in question. 593 o When a request is made including an operation with a new flag bit, 594 if the operation returns with the error NFS4ERR_INVAL,then it can 595 generally be concluded that the responder has no knowledge of the 596 flag bit in question, as long as the requester is careful to avoid 597 other error situations in which the operation in question is 598 defined as returning NFS4ERR_INVAL. Other responses indicate that 599 the responder is aware of the flag bit in question. 601 o When a request is made including the operation to be tested, if 602 the responder returns an RPC XDR decode error, or a response 603 indicating that the operation in question resulted in 604 NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded 605 that the responder has no knowledge of the operation in question. 606 Other responses, including NFS4ERR_NOTSUPP, indicate that the 607 responder is aware of the operation in question. 609 o When a request is made including the switch arm to be tested, if 610 the responder returns an RPC XDR decode error, or a response 611 indicating that the operation in question resulted in 612 NFS4ERR_BADXDR, then it can be concluded that the responder has no 613 knowledge of the operation in question. Other responses, 614 including NFS4ERR_UNION_NOTSUPP, indicate that the responder is 615 aware of the protocol element in question. 617 A determination of the knowledge or lack of knowledge of a particular 618 protocol element is expected to remain valid as long as the clientid 619 associated with the request remains valid. 621 The above assumes, as should be the case, that the server will accept 622 the minor version used by the client. For more detail regarding this 623 issue, see Section 8.2. 625 4.5. XDR Overlay 627 XDR additions may also be made by defining XDR structures that 628 overlay nominally opaque fields. defined to allow such incremental 629 extensions. 631 For example, each pNFS mapping type provides its own XDR definition 632 for various pNFS-related fields defined in [RFC5661] as opaque 633 arrays. 635 Because such additions provide new interpretations of existing 636 fields, they may be made outside of the extension framework as long 637 as they obey the rules previously established when the nominally 638 opaque protocol elements were added to the protocol. 640 5. Other NFSv4 Protocol Changes 642 There are a number of types of protocol changes that are outside the 643 XDR extension framework discussed in Section 4. These changes are 644 also managed within the NFSv4 versioning framework and may be of a 645 number of types, which are discussed in the sections below 647 Despite the previous emphasis on XDR changes, additions and changes 648 to the NFSv4 protocols have not been limited to those that involve 649 changes (in the form of extensions) to the protocol XDR. Examples of 650 other sorts of changes have been taken from NFSv4.1. 652 All such changes that have been made in the past have been made as 653 part of new minor version. Future change of these sorts may not be 654 done in an extension but can only be made in a new minor version. 656 5.1. Field Interpretation and Use 658 The XDR description of a protocol does not constitute a complete 659 description of the protocol. Therefore, versioning needs to consider 660 the role of changes in the use of fields, even when there is no 661 change to the underlying XDR. 663 Although any XDR element is potentially subject to a change in its 664 interpretation and use, the likelihood of such change will vary with 665 the XDR-specified type of the element, as discussed below: 667 o When XDR elements are defined as strings, rules regarding the 668 appropriate string values are specified in protocol specification 669 text with changes in such rules documented in minor version 670 definition documents. Some types of strings within NFS4 are used 671 in server names (in location-related attributes), user and group 672 names, and in the names of file objects within directories. Rules 673 regarding what strings are acceptable appear in [RFC7530] and 674 [RFC5661] with the role of the XDR limited to hints regarding 675 UTF-8 and capitalization issues via XDR typedefs. 677 o Fields that are XDR-defined as opaque elements and which are truly 678 opaque, do not raise versioning issues, except as regards inter- 679 version use, which is effectively foreclosed by the rules in 680 Section 8.1. 682 Note that sometimes a field will seem to be opaque but not 683 actually be fully opaque when considered carefully. For example, 684 the "other" field of stateids is defined as an opaque array, while 685 the specification text specially defines appropriate treatment 686 when the "other" field within it is either all zeros or all ones. 687 Given this context, creation or deletion of reserved values for 688 "special" stateids will be a protocol change which versioning 689 rules need to deal with. 691 o Some nominally opaque elements have external XDR definitions that 692 overlay the nominally opaque arrays. Such cases are discussed in 693 Section 4.5. 695 5.2. Behavioral Changes 697 Changes in the behavior of NFSv4 operations are possible, even if 698 there is no change in the underlying XDR or change to field 699 interpretation and use. 701 One class of behavioral change involves changes in the set of errors 702 to be returned in the event of various errors. When the set of valid 703 requests remain the same, and the behavior for each of them remains 704 the same, such changes can be implemented with only limited 705 disruption to existing clients. 707 Many more substantial behavioral changes have occurred in connection 708 with the addition of the session concept in NFSv4.1. Even though 709 there was no change to the XDR for existing operations, many existing 710 operations and COMPOUUNDs consisting only of them became invalid. 712 Also, changes were made regarding the required server behavior as to 713 the interaction of the MODE and ACL attributes. 715 6. Extending Existing Minor Versions 717 Extensions to the most recently published NFSv4 minor version may be 718 made by publishing the extension as a Proposed Standard, unless the 719 minor version in question has been defined as non-extensible. A 720 document need not update the document defining the minor version, 721 which remains a valid description of the base variant of the minor 722 version in question. 724 Corrections to protocol errors (see Section 9) may be accomplished by 725 publishing an extension, including a compatible XDR change. Such 726 documents will update the defining documents for the corrected minor 727 version. 729 7. Minor Versions 731 7.1. Creation of New Minor Versions 733 It is important to note that this section, in describing situations 734 that would require new minor versions or minor version groups to be 735 created, does not thereby imply that situations will exist in the 736 future. Judgments regarding desirability of future changes will be 737 made by the working group or its successors and any guidance that can 738 be offered at this point is necessarily quite limited. 740 Creation of a new minor version or minor version group is an option 741 that the working group retains. The listing of situations below that 742 would prompt such actions is not meant to be exhaustive. 744 The following sorts of features are not allowed as extensions and 745 would require creation of a new minor version: 747 o Features that incorporate any of the non-XDR-based changes 748 discussed in Sections 5.1 and 5.2. 750 o Addition of REQUIRED new features. 752 o Changes to the status of existing features including converting 753 features to be mandatory to not implement. 755 8. Minor Version Interaction Rules 757 This section addresses issues related to rules #11 and #13 in the 758 minor versioning rules in [RFC5661]. With regard to the supersession 759 of minor versioning rules, the treatment here overrides that in 761 [RFC5661] when either of the potentially interacting minor versions 762 has not yet been published as a Proposed Standard. 764 Note that these rules are the only ones directed to minor version 765 implementers, rather than to those specifying new minor versions. 767 8.1. Minor Version Identifier Transfer Issues 769 Each relationship between a client instance and a server instance, as 770 represented by a clientid, is to be devoted to a single minor 771 version. If a server detects that a COMPOUND with an inappropriate 772 minor version is being used, it MUST reject the request. In doing 773 so, it may return either NFS4ERR_BAD_CLIENTID or 774 NFS4RR_MINOR_VERS_MISMATCH. 776 As a result of the above, the client has the assurance that the set 777 of REQUIRED and OPTONAL features will not change within the context 778 of a single clientid. Server implementations MUST ensure that the 779 set of supported features and protocol elements does not change 780 within such a context. 782 8.2. Minor Version Compatibility 784 The goal of the NFSv4 extension model is to enable compatibility 785 including compatibility between clients and servers implementing 786 different minor versions. 788 Within a set of minor versions that define the same set of features 789 as REQUIRED and mandatory to not implement, it is relatively easy for 790 clients and servers to provides the needed compatibility by adhering 791 to the following practices. 793 o Servers supporting a given minor version should support earlier 794 minor versions in the same minor version group. and return 795 appropriate errors for use of protocol elements that were not a 796 valid part of that earlier minor version. For details see below. 798 o Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by a 799 searching for a lower minor version number that the server will 800 accept. 802 Servers supporting a given minor version MUST, in returning errors 803 for operation which were a valid part of the minor version, return 804 the errors allowed for the current operation in the minor version 805 actually being used. 807 With regard to protocol elements not known in a given minor version, 808 the appropriate error codes are given below. Essentially, the 809 server, although it has a more extensive XDR reflective of a newer 810 minor version, must act as a server with a more limited XDR would. 812 o When an operation is used which is not known in the specified 813 minor version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) 814 should be returned. 816 o When an attribute is used which is not known in the specified 817 minor version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) 818 should be returned. 820 o When a switch case is used which is not known in the specified 821 minor version, NFS4ERR_BADXDR (as opposed to 822 NFS4ERR_UNION_NOTSUPP) should be returned. Even though the 823 message may be XDR-decodable by the server's current XDR, it is 824 not so according to the minor version being used. 826 o When a flag bit is used which is not known in the specified minor 827 version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP Or any other 828 error defined as indicated non-support a flag bit) should be 829 returned. 831 9. Correction of Existing Minor Versions and Features 833 The possibility always exists that there will be a need to correct an 834 existing feature in some way, after the acceptance of that feature or 835 a minor version containing it, as a Proposed Standard. While the 836 working group can reduce the probability of such situations arising 837 by waiting for running code before considering a feature as done, it 838 cannot reduce the probability to zero. As features are used more 839 extensively and interact with other features, previously unseen flaws 840 may be discovered and will need to be corrected. 842 Such corrections are best done in a document obsoleting or updating 843 the RFC defining the relevant feature definition document or minor 844 version specification. In making such corrections, the working will 845 have to carefully consider how to assure interoperability with older 846 clients and servers. 848 Often, corrections can be done without changing the protocol XDR. In 849 many cases, a change in client and server behavior can be implemented 850 without taking special provision with regard to interoperability with 851 earlier implementations. In those case, and in cases in which a 852 revision merely clarifies an earlier protocol definition document, a 853 new document can be published which simply updates the earlier 854 protocol definition document. Subsequently, the indexing material 855 would be updated to reflect the existence of the newer document. 857 In other cases, it is best if client or server behavior needs to 858 change in a way which raises interoperability concerns. In such 859 cases, incompatible changes in server or client behavior should not 860 be mandated in order to avoid XDR changes. 862 9.1. XDR Changes to Implement Protocol Corrections 864 When XDR changes are necessary as part of correcting a flaw, these 865 should be done in a manner similar to that used when implementing new 866 minor versions or features within them. In particular, 868 o Existing XDR structures may not be modified or deleted. 870 o XDR extensions may be used to correct existing protocol facilities 871 in a manner similar to those used to add additional optional 872 features. Such corrections may be done in a minor version for 873 which optional features may no longer be added, if the working 874 group decides that it is an appropriate to compatibly effect a 875 correction. 877 o When a correction is made to an OPTIONAL feature, the result is 878 similar to a situation in which there are two independent OPTIONAL 879 features. A server may choose to implement either or both. 881 o When a correction is made to a required feature, the situation 882 becomes one in which neither the old nor the new version of the 883 feature is required. Instead, it is required that a server 884 support at least one of the two, while each is individually 885 OPTIONAL. Although use of the corrected version is ultimately 886 better, and may be recommended, it should not be described as 887 "RECOMMENDED", since the choice of which version to support if 888 only one is supported will depend on the needs of clients, which 889 may be slow to adopt the updated version. 891 o In all of the cases above, it is appropriate that the old version 892 of the feature, be considered obsolescent, with the expectation 893 that the working group might, in a later minor version, decide 894 that the older version is to become mandatory to not implement. 896 By doing things this way, the protocol with the XDR modification can 897 accommodate clients and servers that support either the corrected or 898 the uncorrected version of the protocol and also clients and servers 899 aware of and capable of supporting both alternatives. 901 o A client that supports only the earlier version of the feature 902 (i.e., an older unfixed client) can determine whether the server 903 it is connecting to supports the older version of feature. It is 904 capable of interoperating with older servers that support only the 905 unfixed protocol as well as ones that support both versions. 907 o A client that supports only the corrected version of the feature 908 (i.e., a new or updated client) can determine whether the server 909 it is connecting to supports the newer version of the feature. It 910 is capable of interoperating with newer servers that support only 911 the updated feature as well as ones that support both versions. 913 o A client that supports both the older and newer version of the 914 feature can determine which version of the particular feature is 915 supported by the server it is working with. 917 o A server that supports only the earlier version of the feature 918 (i.e., an older unfixed server) can only successfully interoperate 919 with older clients. However newer clients can easily determine 920 that the feature cannot be used on that server. 922 o A server that supports only the newer version of the feature 923 (i.e., a new or updated server) can only successfully interoperate 924 with newer clients. However, older clients can easily determine 925 that the feature cannot be used on that server. In the case of 926 OPTIONAL features, clients can be expected to deal with non- 927 support of that particular feature. 929 o A server that supports both the older and newer versions of the 930 feature can interoperate with all client variants. 932 By using extensions in this manner, the protocol creates a clear path 933 which preserves the functioning of existing clients and servers and 934 allows client and server implementers to adopt the new version of the 935 feature at a reasonable pace. 937 10. Security Considerations 939 Since no substantive protocol changes are proposed here, no security 940 considerations apply. 942 11. IANA Considerations 944 The current document does not require any actions by IANA. 946 12. References 947 12.1. Normative References 949 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 950 Requirement Levels", BCP 14, RFC 2119, 951 DOI 10.17487/RFC2119, March 1997, 952 . 954 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 955 "Network File System (NFS) Version 4 Minor Version 1 956 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, 957 . 959 [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 960 (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, 961 March 2015, . 963 12.2. Informative References 965 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 966 Beame, C., Eisler, M., and D. Noveck, "Network File System 967 (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530, 968 April 2003, . 970 Appendix A. Acknowledgements 972 The author wishes to thank Tom Haynes of Primary Data for his role in 973 getting this effort started and his work in co-authoring the first 974 version of the initial working group versioning document. 976 The author also wishes to thank Chuck Lever and Mike Kepfer of Oracle 977 for their thorough document reviews and many helpful suggestions with 978 regard to versioning issues. 980 Author's Address 982 David Noveck 983 Hewlett Packard Enterprise 984 165 Dascomb Road 985 Andover, MA 01810 986 US 988 Phone: +1 978 474 2011 989 Email: davenoveck@gmail.com