diff options
Diffstat (limited to 'doc/rfc/rfc8178.txt')
| -rw-r--r-- | doc/rfc/rfc8178.txt | 1459 |
1 files changed, 1459 insertions, 0 deletions
diff --git a/doc/rfc/rfc8178.txt b/doc/rfc/rfc8178.txt new file mode 100644 index 0000000..d31b38a --- /dev/null +++ b/doc/rfc/rfc8178.txt @@ -0,0 +1,1459 @@ + + + + + + +Internet Engineering Task Force (IETF) D. Noveck +Request for Comments: 8178 NetApp +Updates: 5661, 7862 July 2017 +Category: Standards Track +ISSN: 2070-1721 + + + Rules for NFSv4 Extensions and Minor Versions + +Abstract + + This document describes the rules relating to the extension of the + NFSv4 family of protocols. It covers the creation of minor versions, + the addition of optional features to existing minor versions, and the + correction of flaws in features already published as Proposed + Standards. The rules relating to the construction of minor versions + and the interaction of minor version implementations that appear in + this document supersede the minor versioning rules in RFC 5661 and + other RFCs defining minor versions. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc8178. + +Copyright Notice + + Copyright (c) 2017 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + +Noveck Standards Track [Page 1] + +RFC 8178 NFSv4 Extension July 2017 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.1. Use of Keywords Defined in RFCs 2119 and 8174 . . . . . . 4 + 2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 4 + 2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 5 + 3. Consolidation of Extension Rules . . . . . . . . . . . . . . 6 + 4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 7 + 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 8 + 4.2. Rules for XDR Extension within NFSv4 . . . . . . . . . . 8 + 4.3. Handling of Protocol Elements by Responders . . . . . . . 9 + 4.4. Inter-version Interoperability . . . . . . . . . . . . . 11 + 4.4.1. Requirements for Knowledge of Protocol Elements . . . 11 + 4.4.2. Establishing Interoperability . . . . . . . . . . . . 12 + 4.4.3. Determining Knowledge of Protocol Elements . . . . . 14 + 4.5. XDR Overlay . . . . . . . . . . . . . . . . . . . . . . . 15 + 5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 15 + 5.1. Field Interpretation and Use . . . . . . . . . . . . . . 15 + 5.2. Behavioral Changes . . . . . . . . . . . . . . . . . . . 16 + 6. Extending Existing Minor Versions . . . . . . . . . . . . . . 17 + 7. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 18 + 7.1. Creation of New Minor Versions . . . . . . . . . . . . . 18 + 8. Minor Version Interaction Rules . . . . . . . . . . . . . . . 18 + 8.1. Minor Version Identifier Transfer Issues . . . . . . . . 19 + 8.2. Minor Version Compatibility . . . . . . . . . . . . . . . 19 + 9. Correction of Existing Minor Versions and Features . . . . . 20 + 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 21 + 9.2. XDR Corrections to OPTIONAL Features . . . . . . . . . . 21 + 9.3. XDR Corrections to REQUIRED Features . . . . . . . . . . 22 + 9.4. Addressing XDR Corrections in Later Minor Versions . . . 24 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 12.1. Normative References . . . . . . . . . . . . . . . . . . 25 + 12.2. Informative References . . . . . . . . . . . . . . . . . 25 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 25 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 + + + + + + + + + + + + + +Noveck Standards Track [Page 2] + +RFC 8178 NFSv4 Extension July 2017 + + +1. Introduction + + To address the requirement for an NFS protocol that can evolve as the + need arises, the Network File System (NFS) version 4 (NFSv4) protocol + provides a framework to allow for future changes via the creation of + new protocol versions, including minor versions and certain forms of + modification of existing minor versions. The extension rules + contained in this document allow extensions and other changes to be + implemented in a way that maintains compatibility with existing + clients and servers. + + Previously, all protocol changes had been part of new minor versions. + The COMPOUND procedure (see Section 14.2 of [RFC7530]) specifies the + minor version being used by the client in making requests. The + CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) specifies the + minor version being used by the server on callback requests. + + Creation of a new minor version is no longer the only way in which + protocol changes may be made. Optional features may be added as + extensions and protocol corrections can be proposed, specified, and + implemented within the context of a single minor version. Creation + of new minor versions remains available when needed. + + The goal of allowing extensions within the context of a minor version + is to provide more implementation flexibility while preserving + interoperability on protocol upgrade. As described in Section 4.4, a + client and server may each choose a subset of available extensions. + Each party can successfully use a subset of protocol elements that + are known to and supported by both the client and server. Support + for this common subset is not affected by the fact that extensions + outside this common subset may be supported by the server or + potentially used by the client. + +2. Terminology + + A basic familiarity with NFSv4 terminology is assumed in this + document and the reader is pointed to [RFC7530]. + + In this document, the term "version" is not limited to minor + versions. When minor versions are meant, the term "minor version" is + used explicitly. For more discussion of this and related terms, see + Section 2.3. + + A "feature package" is a set of features that are defined together, + either as part of a minor version or as part of the same protocol + extension. + + + + + +Noveck Standards Track [Page 3] + +RFC 8178 NFSv4 Extension July 2017 + + +2.1. Use of Keywords Defined in RFCs 2119 and 8174 + + The keywords defined by [RFC2119] [RFC8174] have special meanings + that this document intends to adhere to. However, due to the nature + of this document and some special circumstances, there are some + complexities to take note of: + + o Where this document does not directly specify implementation + requirements, use of these capitalized terms is often not + appropriate since the guidance given in this document does not + directly affect interoperability. + + o In this document, what authors of RFCs defining features and minor + versions need to do is stated without these specialized terms. + Although it is necessary to follow this guidance to provide + successful NFSv4 protocol extension, that sort of necessity is not + of the sort defined as applicable to the use of the keywords + defined in [RFC2119] [RFC8174]. + + The fact that these capitalized terms are not used should not be + interpreted as indicating that this guidance does not need to be + followed or is somehow not important. + + o In speaking of the possible statuses of features and feature + elements, the terms "OPTIONAL" and "REQUIRED" are used. For + further discussion, see Section 2.2. + + o When one of these upper-case keywords defined in [RFC2119] + [RFC8174] is used in this document, it is in the context of a rule + directed to an implementer of NFSv4 minor versions, the status of + a feature or protocol element, or in a quotation, sometimes + indirect, from another document. + +2.2. Use of Feature Statuses + + There has been some confusion during the history of NFSv4 about the + correct use of these terms, and instances in which the keywords + defined in [RFC2119] [RFC8174] were used in ways that appear to be at + variance with the definitions in that document. + + o In [RFC3530], the lower-case terms "optional", "recommended", and + "required" were used as feature statuses, Later, in [RFC5661] and + [RFC7530], the corresponding upper-case keywords were used. It is + not clear why this change was made. + + o In the case of "RECOMMENDED", its use as a feature status is + inconsistent with [RFC2119] [RFC8174] and it will not be used for + this purpose in this document. + + + +Noveck Standards Track [Page 4] + +RFC 8178 NFSv4 Extension July 2017 + + + o The word "RECOMMENDED" to denote the status of attributes in + [RFC7530] and [RFC5661] raises similar issues. This has been + recognized in [RFC7530] with regard to NFSV4.0, although the + situation with regard to NFSv4.1 remains unresolved. + + In this document, the keywords "OPTIONAL" and "REQUIRED" and the + phrase "mandatory to not implement" are used to denote the status of + features within a given minor version. In using these terms, RFCs + that specify the status of features inform: + + o client implementations whether they need to deal with the absence + of support for these features. + + o server implementations whether they need to provide support for + these features. + +2.3. NFSv4 Versions + + The term "version" denotes any valid protocol variant constructed + according to the rules in this document. It includes minor versions, + but there are situations that allow multiple variant versions to be + associated with and coexist within a single minor version: + + o When there are feature specification documents published as + Proposed Standards extending a given minor version, then the + protocol defined by the minor version specification document, when + combined with any subset (not necessarily a proper subset) of the + feature specification documents, is a valid NFSv4 version variant + that is part of the minor version in question. + + o When there are protocol corrections published that update a given + minor version, each set of published updates, up to the date of + publication of the update, is a valid NFSv4 version variant that + is part of the minor version in question. + + Because of the above, there can be multiple version variants that are + part of a given minor version. Two of these are worthy of special + terms: + + o The term "base minor version" denotes the version variant that + corresponds to the minor version as originally defined, including + all protocol elements specified in the minor version definition + document but not incorporating any extensions or protocol + corrections published after that original definition. + + + + + + + +Noveck Standards Track [Page 5] + +RFC 8178 NFSv4 Extension July 2017 + + + o At any given time, the term "current minor version" denotes the + minor version variant including all extensions of and corrections + to the minor version made by Standards Track documents published + up to that time. + + Each client and server that implements a specific minor version will + implement some particular variant of that minor version. Each + variant is a subset of the current minor version and a superset of + the base minor version. When the term "minor version" is used + without either of these qualifiers, it should refer to something that + is true of all variants within that minor version. For example, in + the case of a minor version that has not had a protocol correction, + one may refer to the set of REQUIRED features for that minor version + since it is the same for all variants within the minor version. See + Section 9 for a discussion of correcting an existing minor version. + +3. Consolidation of Extension Rules + + In the past, the only existing extension rules were the minor + versioning rules that were being maintained and specified in the + Standards Track RFCs, which defined the individual minor versions. + In the past, these minor versioning rules were modified on an ad hoc + basis for each new minor version. + + More recently, minor versioning rules were specified in [RFC5661] + while modifications to those rules were allowed in subsequent minor + versions. + + This document defines a set of extension rules, including rules for + minor version construction. These rules apply to all future changes + to the NFSv4 protocol. The rules are subject to change but any such + change should be part of a Standards Track RFC obsoleting or updating + this document. + + Rather than a single list of extension rules, as was done in the + minor versioning rules in [RFC5661], this document defines multiple + sets of rules that deal with the various forms of protocol change + provided for in the NFSv4 extension framework. + + o The kinds of changes in External Data Representation (XDR) + definitions that may be made to extend NFSv4 are addressed in the + rules in Section 4.2. + + o Minor version construction, including rules applicable to changes + that cannot be made in extensions to existing minor versions are + addressed in Section 7.1. + + + + + +Noveck Standards Track [Page 6] + +RFC 8178 NFSv4 Extension July 2017 + + + o Minor version interaction rules are discussed in Sections 8.1 and + 8.2. + + This document supersedes minor versioning rules appearing in the + minor version specification RFCs, including those in [RFC5661] and + also the modification to those rules mentioned in [RFC7862]. As a + result, potential conflicts among documents should be addressed as + follows: + + o The specification of the actual protocols for minor versions + previously published as Proposed Standards take precedence over + minor versioning rules in either this document or in the minor + version specification RFCs. In other words, if the transition + from version A to version B violates a minor versioning rule, the + version B protocol stays as it is. + + o Since minor versioning rules #11 and #13 from [RFC5661] deal with + the interactions between multiple minor versions, the situation is + more complicated. See Section 8 for a discussion of these issues, + including how potential conflicts between rules are to be + resolved. + + o Otherwise, any conflict between the extension rules in this + document and those in minor version specification RFCs are to be + resolved based on the treatment in this document. In particular, + corrections may be made as specified in Section 9 for all + previously specified minor versions, and the extensibility of + previously specified minor versions is to be handled in accord + with Section 6. + + Future minor version specification documents should avoid specifying + rules relating to minor versioning and reference this document in + connection with rules for NFSv4 extension. + +4. XDR Considerations + + As an extensible XDR-based protocol, NFSv4 has to ensure inter- + version compatibility in situations in which the client and server + use different XDR descriptions. For example, the client and server + may implement different variants of the same minor version, in that + they each might add different sets of extensions to the base minor + version. + + The XDR extension paradigm, discussed in Section 4.1, assures that + these descriptions are compatible, with clients and servers able to + determine and use those portions of the protocol that they both share + according to the method described in Section 4.4.2. + + + + +Noveck Standards Track [Page 7] + +RFC 8178 NFSv4 Extension July 2017 + + +4.1. XDR Extension + + When an NFSv4 version change requires a modification to the protocol + XDR, this is effected within a framework based on the idea of XDR + extension. This is in contrast to transitions between major NFS + versions (including that between NFSv3 and NFSv4.0) in which the XDR + for one version was replaced by a different XDR for a newer version. + + The XDR extension approach allows an XDR description to be extended + in a way that retains the structure of all previously valid messages. + If a base XDR description is extended to create a second XDR + description, the following will be true for the second description to + be a valid extension of the first: + + o The set of valid messages described by the extended definition is + a superset of that described by the first. + + o Each message within the set of valid messages described by the + base definition is recognized as having exactly the same + structure/interpretation using the extended definition. + + o Each message within the set of messages described as valid by the + extended definition but not the base definition must be + recognized, using the base definition, as part of an unknown + extension. + + The use of XDR extension can facilitate compatibility between + different versions of the NFSv4 protocol. When XDR extension is used + to implement OPTIONAL features, the greatest degree of inter-version + compatibility is obtained. In this case, as long as the rules in + Section 6 are followed, no change in minor version number is needed + and the extension may be effected in the context of a single minor + version. + +4.2. Rules for XDR Extension within NFSv4 + + In the context of NFSv4, given the central role of COMPOUND and + CB_COMPOUND, addition of new RPC procedures is not allowed and the + enumeration of operations and callback operations have a special + role. + + The following XDR extensions, by their nature, affect both messages + sent by requesters (i.e., requests and callbacks), and responders + (i.e., replies and callback replies). + + o Addition of previously unspecified operation codes, within the + framework established by COMPOUND and CB_COMPOUND. These extend + the appropriate enumeration and the corresponding switches devoted + + + +Noveck Standards Track [Page 8] + +RFC 8178 NFSv4 Extension July 2017 + + + to requests and responses for the associated direction of + operation. + + o Addition of previously unspecified attributes. These add + additional numeric constants that define each attribute's bit + position within the attribute bitmap, together with XDR typedefs + that specify the attributes' format within the nominally opaque + arrays specifying sets of attributes. + + Other sorts of changes will generally affect one of requests, + replies, callback, or callback replies. Although all are valid XDR + extensions, the messages that are affected may determine whether the + extension requires a new minor version (see Section 7) or can be made + as an extension within an existing minor version (see Section 6). + + o Addition of new, previously unused, values to existing enums. + + o Addition of previously unassigned bit values to a flag word. + + o Addition of new cases to existing switches, provided that the + existing switch did not contain a default case. + + None of the following is allowed to happen: + + o Any change to the structure of existing requests or replies other + than those listed above. + + o Addition of previously unspecified RPC procedures for either the + NFSv4 program or the callback program. + + o Deletion of existing RPC procedures, operation codes, enum values, + flag bit values, and switch cases. Note that changes may be made + to define use of any of these as causing an error, as long as the + XDR is unaffected. Similarly, none of these items may be reused + for a new purpose. + +4.3. Handling of Protocol Elements by Responders + + Implementations handle protocol elements received in requests and + callbacks in one of three ways. Which of the following ways are + valid depends on the status of the protocol element in the variant + being implemented: + + o The protocol element is not a part of definition of the variant in + question and so is "unknown". The responder, when it does not + report an RPC XDR decode error, reports an error indicative of the + element not being defined in the XDR such as NFS4ERR_OP_ILLEGAL, + NFS4ERR_BADXDR, or NFS4ERR_INVAL. See Section 4.4.3 for details. + + + +Noveck Standards Track [Page 9] + +RFC 8178 NFSv4 Extension July 2017 + + + o The protocol element is a known part of the variant but is not + supported by the particular implementation. The responder reports + an error indicative of the element being recognized as one which + is not supported such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, + or NFS4ERR_ATTRNOTSUPP. + + o The protocol element is a known part of the variant that is + supported by the particular implementation. The responder reports + success or an error other than the special ones discussed above. + + Which of these are validly returned by the responder depends on the + status of the protocol element in the minor version specified in the + COMPOUND or CB_COMPOUND. The possibilities that can exist when + dealing with minor versions that have not been subject to corrections + are listed below. See Sections 9.1 and 9.3 for a discussion of the + effects of protocol correction. + + o The protocol element is not known in the minor version. In this + case, all implementations of the minor version MUST indicate that + the protocol element is not known. + + o The protocol element is part of a feature specified as mandatory + to not implement in the minor version. In this case as well, all + implementations of the minor version MUST indicate that the + protocol element is not known. + + o The protocol element is defined as part of the current variant of + the minor version but is not part of the corresponding base + variant. In this case, the requester can encounter situations in + which the protocol element is either not known to the responder, + is known to but not supported by the responder, or is both known + to and supported by the responder. + + o The protocol element is defined as an OPTIONAL part of the base + minor version. In this case, the requester can expect the + protocol element to be known but must deal with cases in which it + is supported or is not supported. + + o The protocol element is defined as a REQUIRED part of the base + minor version. In this case, the requester can expect the + protocol element to be both known and supported by the responder. + + The listing of possibilities above does not mean that a requester + always needs to be prepared for all such possibilities. Often, + depending on the scope of the feature of which the protocol element + is a part, handling of a previous request using the same or related + protocol elements will allow the requester to be sure that certain of + these possibilities cannot occur. + + + +Noveck Standards Track [Page 10] + +RFC 8178 NFSv4 Extension July 2017 + + + Requesters, typically clients, may test for knowledge of, or support + for, protocol elements as part of connection establishment. This may + allow the requester to be aware of a responder's lack of knowledge of + or support for problematic requests before they are actually used to + affect user requests. + +4.4. Inter-version Interoperability + + Because of NFSv4's use of XDR extension, any communicating client and + server versions have XDR definitions such that each is a valid + extension of a third version. Once that version is determined, it + may be used by both client and server to communicate. Each party can + successfully use a subset of protocol elements that are both known to + and supported by both parties. + +4.4.1. Requirements for Knowledge of Protocol Elements + + With regard to requirements for knowledge of protocol elements, the + following rules apply. These rules are the result of the use of the + XDR extension paradigm combined with the way in which extensions are + incorporated in existing minor versions (for details, see Section 6). + + o Any protocol element defined as part of the base variant of a + particular minor version is required to be known by that minor + version. This occurs whether the specification happens in the + body of the minor definition document or is in a feature + definition document that is made part of the minor version by + being normatively referenced by the minor version definition + document. + + o Any protocol element required to be known in a given minor version + is required to be known in subsequent minor versions, unless and + until a minor version has made that protocol element as mandatory + to not implement. + + o When a protocol element is defined as part of an extension to an + extensible minor version, it is not required to be known in that + minor version but is required to be known by the next minor + version. In the earlier minor version, it might not be defined in + the XDR definition document, while in the later version it needs + to be defined in the XDR definition document. In either case, if + it is defined, it might or might not be supported. + + o When knowledge of protocol elements is optional in a given minor + version, the responder's knowledge of such optional elements must + obey the rule that if one such element is known, then all the + protocol elements defined in the same minor version definition + document must be known as well. + + + +Noveck Standards Track [Page 11] + +RFC 8178 NFSv4 Extension July 2017 + + + For many minor versions, all existing protocol elements are required + to be known by both the client and the server, and so requesters do + not have to test for the presence or absence of knowledge regarding + protocol elements. This is the case if there has been no extension + for the minor version in question. Extensions can be added to + extensible minor versions as described in Section 6 and can be used + to correct protocol flaws as described in Section 9. + + Requesters can ascertain the knowledge of the responder in two ways: + + o By issuing a request using the protocol element and looking at the + response. Note that, even if the protocol element used is not + supported by the responder, the requester can still determine if + the element is known by the responder. + + o By receiving a request from the responder, acting in the role of + requester. For example, a client may issue a request enabling the + server to infer that it is aware of a corresponding callback. + + In making this determination, the requester can rely on two basic + facts: + + o If the responder is aware of a single protocol element within a + feature package, it must be aware of all protocol elements within + that feature package. + + o If a protocol element is one defined by the minor version + specified by a request (and not in an extension), or in a previous + minor version, the responder must be aware of it. + +4.4.2. Establishing Interoperability + + When a client and a server interact, they need to able to take + advantage of the compatibility provided by NFSv4's use of XDR + extension. + + In this context, the client and server would arrive at a common + variant, which the client uses to send requests that the server would + then accept. The server would use that variant to send callbacks + that the client would then accept. This state of affairs could arise + in a number of ways: + + o Client and server have been built using XDR variants that belong + to the same minor version. + + + + + + + +Noveck Standards Track [Page 12] + +RFC 8178 NFSv4 Extension July 2017 + + + o The client's minor version is lower than that of the server. In + this case the server, in accord with Section 8.2, accepts the + client's minor version, and acts as if it has no knowledge of + extensions made in subsequent minor versions. It has knowledge of + protocol elements within the current (i.e., effectively final) + variant of the lower minor version. + + o The client's minor version is higher than that of the server. In + this case the client, in accord with Section 8.2, uses a lower + minor version that the server will accept. In this case, the + server has no knowledge of extensions made in subsequent minor + versions. + + There are a number of cases to consider based on the characteristics + of the minor version chosen. + + o When the minor version consists of only a single variant (no + extension or XDR corrections), the client and the server are using + the same XDR description and have knowledge of the same protocol + elements. + + o When the minor version consists of multiple variants (i.e., there + are one or more XDR extensions or XDR corrections), the client and + the server are using compatible XDR descriptions. The client is + aware of some set of extensions while the server may be aware of a + different set. The client can use the approach described in + Section 4.4.3 to determine which of the extensions it knows about + are also known by the server. Once this is done, the client and + server will both be using a common variant. The variants that the + client and the server were built with will both either be + identical to this variant or a valid extension of it. Similarly, + the variants that the client and the server actually use will be a + subset of this variant, in that certain OPTIONAL features will not + be used. + + In either case, the client must determine which of the OPTIONAL + protocol elements within the common version are supported by the + server, just as it does for OPTIONAL features introduced as part of a + minor version. + + It is best if client implementations make the determination as to the + support provided by the server before acting on user requests. This + includes the determination of the common protocol variant and the + level of support for OPTIONAL protocol elements. + + + + + + + +Noveck Standards Track [Page 13] + +RFC 8178 NFSv4 Extension July 2017 + + +4.4.3. Determining Knowledge of Protocol Elements + + A requester may test the responder's knowledge of particular protocol + elements as defined below, based on the type of protocol element. + Note that in the case of attribute or flag bits, use of a request + that refers to 2 or more bits of undetermined status ("known" versus + "unknown") may return results that are not particularly helpful. In + such cases, when the response is NFS4ERR_INVAL, the requester can + only conclude that at least one of the bits is unknown. + + o When a GETATTR request is made specifying an attribute bit to be + tested and that attribute is not a set-only attribute, if the + GETATTR returns with the error NFS4ERR_INVAL, then it can be + concluded that the responder has no knowledge of the attribute in + question. Other responses, including NFS4ERR_ATTRNOTSUPP, + indicate that the responder is aware of the attribute in question. + + o When a SETATTR request is made specifying the attribute bit to be + tested and that attribute is not a get-only attribute, if the + SETATTR returns with the error NFS4ERR_INVAL, then it can be + concluded that the responder has no knowledge of the attribute in + question. Other responses, including NFS4ERR_ATTRNOTSUPP, + indicate that the responder is aware of the attribute in question. + + o When a request is made including an operation with a new flag bit, + if the operation returns with the error NFS4ERR_INVAL, then it can + generally be concluded that the responder has no knowledge of the + flag bit in question, as long as the requester is careful to avoid + other error situations in which the operation in question is + defined as returning NFS4ERR_INVAL. Other responses indicate that + the responder is aware of the flag bit in question. + + o When a request is made including the operation to be tested, if + the responder returns an RPC XDR decode error, or a response + indicating that the operation in question resulted in + NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded + that the responder has no knowledge of the operation in question. + Other responses, including NFS4ERR_NOTSUPP, indicate that the + responder is aware of the operation in question. + + o When a request is made including the switch arm to be tested, if + the responder returns an RPC XDR decode error, or a response + indicating that the operation in question resulted in + NFS4ERR_BADXDR, then it can be concluded that the responder has no + knowledge of the operation in question. Other responses, + including NFS4ERR_UNION_NOTSUPP, indicate that the responder is + aware of the protocol element in question. + + + + +Noveck Standards Track [Page 14] + +RFC 8178 NFSv4 Extension July 2017 + + + A determination of the knowledge or lack of knowledge of a particular + protocol element is expected to remain valid as long as the clientid + associated with the request remains valid. + + The above assumes, as should be the case, that the server will accept + the minor version used by the client. For more detail regarding this + issue, see Section 8.2. + +4.5. XDR Overlay + + XDR additions may also be made by defining XDR structures that + overlay nominally opaque fields that are defined to allow such + incremental extensions. + + For example, each parallel NFS (pNFS) mapping type provides its own + XDR definition for various pNFS-related fields defined in [RFC5661] + as opaque arrays. + + Because such additions provide new interpretations of existing + fields, they may be made outside of the extension framework as long + as they obey the rules previously established when the nominally + opaque protocol elements were added to the protocol. + +5. Other NFSv4 Protocol Changes + + There are a number of types of protocol changes that are outside the + XDR extension framework discussed in Section 4. These changes are + also managed within the NFSv4 versioning framework and may be of a + number of types, which are discussed in the sections below. + + Despite the previous emphasis on XDR changes, additions and changes + to the NFSv4 protocols have not been limited to those that involve + changes (in the form of extensions) to the protocol XDR. Examples of + other sorts of changes have been taken from NFSv4.1. + + All such changes that have been made in the past have been made as + part of new minor version. Future change of these sorts may not be + done in an extension but can only be made in a new minor version. + +5.1. Field Interpretation and Use + + The XDR description of a protocol does not constitute a complete + description of the protocol. Therefore, versioning needs to consider + the role of changes in the use of fields, even when there is no + change to the underlying XDR. + + + + + + +Noveck Standards Track [Page 15] + +RFC 8178 NFSv4 Extension July 2017 + + + Although any XDR element is potentially subject to a change in its + interpretation and use, the likelihood of such change will vary with + the XDR-specified type of the element, as discussed below: + + o When XDR elements are defined as strings, rules regarding the + appropriate string values are specified in protocol specification + text with changes in such rules documented in minor version + definition documents. Some types of strings within NFS4 are used + in server names (in location-related attributes), user and group + names, and in the names of file objects within directories. Rules + regarding what strings are acceptable appear in [RFC7530] and + [RFC5661] with the role of the XDR limited to hints regarding + UTF-8 and capitalization issues via XDR typedefs. + + o Fields that are XDR-defined as opaque elements and that are truly + opaque, do not raise versioning issues, except as regards inter- + version use, which is effectively foreclosed by the rules in + Section 8.1. + + Note that sometimes a field will seem to be opaque but not + actually be fully opaque when considered carefully. For example, + the "other" field of stateids is defined as an opaque array, while + the specification text specially defines appropriate treatment + when the "other" field within it is either all zeros or all ones. + Given this context, creation or deletion of reserved values for + "special" stateids will be a protocol change that versioning rules + need to deal with. + + o Some nominally opaque elements have external XDR definitions that + overlay the nominally opaque arrays. Such cases are discussed in + Section 4.5. + +5.2. Behavioral Changes + + Changes in the behavior of NFSv4 operations are possible, even if + there is no change in the underlying XDR or change to field + interpretation and use. + + One class of behavioral change involves changes in the set of errors + to be returned when various failure conditions occur. When the set + of valid requests remain the same, and the behavior for each of them + remains the same, such changes can be implemented with only limited + disruption to existing clients. + + Many more substantial behavioral changes have occurred in connection + with the addition of the session concept in NFSv4.1. Even though + there was no change to the XDR for existing operations, many existing + operations and COMPOUNDs consisting only of them became invalid. + + + +Noveck Standards Track [Page 16] + +RFC 8178 NFSv4 Extension July 2017 + + + Also, changes were made regarding the required server behavior as to + the interaction of the MODE and Access Control List (ACL) attributes. + +6. Extending Existing Minor Versions + + Extensions to the most recently published NFSv4 minor version may be + made by publishing the extension as a Proposed Standard, unless the + minor version in question has been defined as non-extensible. A + document need not use the "Updates" header specifying the RFC that + defines the minor version, which remains a valid description of the + base variant of the minor version in question. + + In addition to following the rules for XDR extensions in Section 4.2, + such extensions must also obey the rules listed below in order to + allow interoperability to be established, as described in + Section 4.4: + + o Additions to the set of callback requests and extensions to the + XDR for existing callback operations can only be made if the + server can determine, based on the client's actions, that the + client is aware of the changes. This determination, for any + particular client (as defined by its clientid), is made before + sending those new or extended callbacks. + + o XDR extensions that affect the structures of responses to existing + operations can only be made if the server can determine, based on + the client's actions, that it is aware of the existence of XDR + changes, before sending responses containing those extensions. + This determination can be based on the request being responded to, + but that is not required. Use of any protocol element defined in + the extension can be the basis of the determination, provided that + the requirements for determining client awareness are clearly + stated. + + Corrections to protocol errors (see Section 9) may be accomplished by + publishing an extension, including a compatible XDR change that + follows the rules above. Such documents will update the defining + documents for the minor version to be corrected. + + In some cases, extensions will contain elements such as new + operations or previously invalid switch cases. Although it is + possible to determine whether these OPTIONAL elements are supported + using the rules described above, those defining an extension that + contains such elements have the choice of defining a new attribute + that indicates whether the feature is present and supported. Since + it is easy to determine whether a new attribute is supported using + + + + + +Noveck Standards Track [Page 17] + +RFC 8178 NFSv4 Extension July 2017 + + + the supported_attrs attribute, this can make it simple and convenient + for clients to determine whether support is present, particularly + when a feature involves support for multiple such elements. + +7. Minor Versions + +7.1. Creation of New Minor Versions + + It is important to note that this section, in describing situations + that would require new minor versions to be created, does not thereby + imply that situations will exist in the future. Judgments regarding + desirability of future changes will be made by the working group or + its successors and any guidance that can be offered at this point is + necessarily quite limited. + + Creation of a new minor version is an option that the working group + retains. The listing of situations below that would prompt such + actions is not meant to be exhaustive. + + The following sorts of features are not allowed as extensions and + would require creation of a new minor version: + + o Features that incorporate any of the non-XDR-based changes + discussed in Sections 5.1 and 5.2. + + o Features whose XDR changes do not follow the rules in Section 6. + + o Addition of REQUIRED new features. + + o Changes to the status of existing features including converting + features to be mandatory to not implement. + +8. Minor Version Interaction Rules + + This section addresses issues related to rules #11 and #13 in the + minor versioning rules in [RFC5661]. With regard to the supersession + of minor versioning rules, the treatment here overrides that in + [RFC5661] when either of the potentially interacting minor versions + has not yet been published as a Proposed Standard. + + Note that these rules are the only ones directed to minor version + implementers, rather than to those specifying new minor versions. + + + + + + + + + +Noveck Standards Track [Page 18] + +RFC 8178 NFSv4 Extension July 2017 + + +8.1. Minor Version Identifier Transfer Issues + + Each relationship between a client instance and a server instance, as + represented by a clientid, is to be devoted to a single minor + version. If a server detects that a COMPOUND with an inappropriate + minor version is being used, it MUST reject the request. In doing + so, it may return either NFS4ERR_BAD_CLIENTID or + NFS4RR_MINOR_VERS_MISMATCH. + + As a result of the above, the client has the assurance that the set + of REQUIRED and OPTIONAL features will not change within the context + of a single clientid. Server implementations MUST ensure that the + set of supported features and protocol elements does not change + within such a context. + +8.2. Minor Version Compatibility + + The goal of the NFSv4 extension model is to enable compatibility + including compatibility between clients and servers implementing + different minor versions. + + Within a set of minor versions that define the same set of features + as REQUIRED and mandatory to not implement, it is relatively easy for + clients and servers to provide the needed compatibility by adhering + to the following practices: + + o Servers supporting a given minor version should support earlier + minor versions within that set and return appropriate errors for + use of protocol elements that were not a valid part of that + earlier minor version. For details, see below. + + o Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by + searching for a lower minor version number that the server will + accept. + + Servers supporting a given minor version MUST, in returning errors + for operations that were a valid part of the minor version, return + the errors allowed for the current operation in the minor version + actually being used. + + With regard to protocol elements not known in a given minor version, + the appropriate error codes are given below. Essentially, the + server, although it has a more extensive XDR reflective of a newer + minor version, must act as a server with a more limited XDR would. + + o When an operation is used that is not known in the specified minor + version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) should + be returned. + + + +Noveck Standards Track [Page 19] + +RFC 8178 NFSv4 Extension July 2017 + + + o When an attribute is used that is not known in the specified minor + version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) should + be returned. + + o When a switch case is used that is not known in the specified + minor version, NFS4ERR_BADXDR (as opposed to + NFS4ERR_UNION_NOTSUPP) should be returned. Even though the + message may be XDR-decodable by the server's current XDR, it is + not so according to the minor version being used. + + o When a flag bit is used that is not known in the specified minor + version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP or any other + error defined as indicating non-support of a flag bit) should be + returned. + +9. Correction of Existing Minor Versions and Features + + The possibility always exists that there will be a need to correct an + existing feature in some way after the acceptance of that feature, or + a minor version containing it, as a Proposed Standard. While the + working group can reduce the probability of such situations arising + by waiting for running code before considering a feature as done, it + cannot reduce the probability to zero. As features are used more + extensively and interact with other features, previously unseen flaws + may be discovered and will need to be corrected. + + Such corrections are best done in a document obsoleting or updating + the RFC defining the relevant feature or minor version. In making + such corrections, the working group will have to carefully consider + how to assure interoperability with older clients and servers. + + Often, corrections can be done without changing the protocol XDR. In + many cases, a change in client and server behavior can be implemented + without taking special provision with regard to interoperability with + earlier implementations. In those cases, and in cases in which a + revision merely clarifies an earlier protocol definition document, a + new document can be published that simply updates the earlier + protocol definition document. + + In other cases, it is best if client or server behavior needs to + change in a way that raises interoperability concerns. In such + cases, incompatible changes in server or client behavior should not + be mandated in order to avoid XDR changes. + + + + + + + + +Noveck Standards Track [Page 20] + +RFC 8178 NFSv4 Extension July 2017 + + +9.1. XDR Changes to Implement Protocol Corrections + + When XDR changes are necessary as part of correcting a flaw, these + should be done in a manner similar to that used when implementing new + minor versions or features within them. In particular: + + o Existing XDR structures may not be modified or deleted. + + o XDR extensions may be used to correct existing protocol facilities + in a manner similar to those used to add additional optional + features. Such corrections may be done in a minor version for + which optional features may no longer be added, if the working + group decides that it is an appropriate way to compatibly effect a + correction. + + o When a correction is made to an OPTIONAL feature, the result is + similar to a situation in which there are two independent OPTIONAL + features. A server may choose to implement either or both. See + Section 9.2 for a detailed discussion of interoperability issues. + + o When a correction is made to a REQUIRED feature, the situation + becomes one in which the old version of the feature remains + REQUIRED while the corrected version, while OPTIONAL, is intended + to be adopted to provide correct operation. Although use of the + corrected version is ultimately better and may be recommended, it + should not be described as "RECOMMENDED" since the choice of + versions to support will depend on the needs of clients, which may + be slow to adopt the updated version. The nature of such + corrections is such that it may result in situations in which + different variants of the same minor version may not both support + the corrected version. See Section 9.3 for details. + + o In all of the cases above, it is appropriate that the old version + of the feature be considered obsolescent, with the expectation + that the working group might, in a later minor version, change the + status of the uncorrected version. See Section 9.4 for more + detail. + +9.2. XDR Corrections to OPTIONAL Features + + By defining the corrected and uncorrected version as independent + OPTIONAL features, the protocol with the XDR modification can + accommodate clients and servers that support either the corrected or + the uncorrected version of the protocol, and also clients and servers + aware of and capable of supporting both alternatives. + + + + + + +Noveck Standards Track [Page 21] + +RFC 8178 NFSv4 Extension July 2017 + + + Based on the type of client: + + o A client that uses only the earlier version of the feature (i.e., + an older unfixed client) can determine whether the server it is + connecting to supports the older version of feature. It is + capable of interoperating with older servers that support only the + unfixed protocol as well as ones that support both versions. + + o A client that supports only the corrected version of the feature + (i.e., a new or updated client) can determine whether the server + it is connecting to supports the newer version of the feature. It + is capable of interoperating with newer servers that support only + the updated feature as well as ones that support both versions. + + o A client that supports both the older and newer version of the + feature can determine which version of the particular feature is + supported by the server it is working with. + + Based on the type of server: + + o A server that supports only the earlier version of the feature + (i.e., an older unfixed server) can only successfully interoperate + with clients implementing the older version. However, clients + that do not implement the older version of the feature can easily + determine that the feature cannot be used on that server. + + o A server that supports only the newer version of the feature + (i.e., a new or updated server) can only successfully interoperate + with newer clients. However, older clients can easily determine + that the feature cannot be used on that server. In the case of + OPTIONAL features, clients can be expected to deal with non- + support of that particular feature. + + o A server that supports both the older and newer versions of the + feature can interoperate with all client variants. + + By using extensions in this manner, the protocol creates a clear path + that preserves the functioning of existing clients and servers and + allows client and server implementers to adopt the new version of the + feature at a reasonable pace. + +9.3. XDR Corrections to REQUIRED Features + + Interoperability issues in this case are similar to those for the + OPTIONAL case described above (in Section 9.2). However, because the + use of the uncorrected version is REQUIRED, servers have to support + this until there is a minor version change. Nevertheless, there is + the opportunity for clients and servers to implement the corrected + + + +Noveck Standards Track [Page 22] + +RFC 8178 NFSv4 Extension July 2017 + + + version, while maintaining necessary interoperability with earlier + implementations. + + The following types of servers can exist: + + o Servers only aware of and supporting the uncorrected version, such + as servers developed before the issue requiring correction was + known. + + o Servers aware of both versions while only supporting the + uncorrected version. + + o Servers aware of and supporting both versions. + + With the exception of clients that do not use the feature in + question, the following sorts of clients may exist: + + o Clients only aware of and prepared to use the uncorrected version, + such as those developed before the issue requiring correction was + known. + + Clients developed before the correction was defined would be of + this type. They would be capable of interoperating with all of + the types of servers listed above, but could not use the corrected + version. + + o Clients aware of both versions while only prepared to use the + uncorrected version. + + Some clients developed or modified after the correction was + defined would be of this type, until they were modified to support + the corrected version. They would also be capable of + interoperating with all of the types of servers listed above, but + could not use the corrected version. + + o Clients aware of and prepared to use either version. + + Such clients would be capable of interoperating with all of the + types of servers listed above, and could use the corrected version + with servers that supported it. + + o Clients aware of both versions while only prepared to use the + newer, corrected version. + + Such clients would only be capable of interoperating with servers + that supported the corrected version. With other types of + servers, they could determine the absence of appropriate support + at an early stage and treat the minor version in question as + + + +Noveck Standards Track [Page 23] + +RFC 8178 NFSv4 Extension July 2017 + + + unsupported by the server. Such clients are only likely to be + deployed when the majority of servers support the corrected + version. + +9.4. Addressing XDR Corrections in Later Minor Versions + + As described in Sections 9.2 and 9.3, a corrected XDR can be + incorporated in an existing minor version and be used, while an + existing uncorrected version is still supported. Nevertheless, the + uncorrected version will remain part of the protocol until its status + is changed in a later minor version. + + One possible change that could be made in a later minor version is to + define the uncorrected version as mandatory to not implement. + Because of the difficulty of determining that no clients depend on + support for the uncorrected version, it is unlikely that this step + would be appropriate for a considerable time. + + In the case of a correction to a REQUIRED feature, there are a number + of less disruptive changes that could be made earlier: + + o Changing the uncorrected version from REQUIRED to OPTIONAL while + REQUIRING that servers support at least one of the two versions. + + This would allow new server implementations to avoid support for + the uncorrected version. + + o Changing the corrected version from OPTIONAL to REQUIRED, making + both versions REQUIRED. + + This would allow new clients to depend on support for the + corrected version being present. + + o Changing the uncorrected version from REQUIRED to OPTIONAL while + changing the corrected version from OPTIONAL to REQUIRED. + + This would complete the shift to the corrected version once + clients are prepared to use the corrected version. + + In making such changes, interoperability issues would need to be + carefully considered. + +10. Security Considerations + + Since no substantive protocol changes are proposed here, no security + considerations apply. + + + + + +Noveck Standards Track [Page 24] + +RFC 8178 NFSv4 Extension July 2017 + + +11. IANA Considerations + + The current document does not require any IANA actions. + +12. References + +12.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <http://www.rfc-editor.org/info/rfc2119>. + + [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., + "Network File System (NFS) Version 4 Minor Version 1 + Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010, + <http://www.rfc-editor.org/info/rfc5661>. + + [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System + (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, + March 2015, <http://www.rfc-editor.org/info/rfc7530>. + + [RFC7862] Haynes, T., "Network File System (NFS) Version 4 Minor + Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862, + November 2016, <http://www.rfc-editor.org/info/rfc7862>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <http://www.rfc-editor.org/info/rfc8174>. + +12.2. Informative References + + [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., + Beame, C., Eisler, M., and D. Noveck, "Network File System + (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530, + April 2003, <http://www.rfc-editor.org/info/rfc3530>. + +Acknowledgements + + The author wishes to thank Tom Haynes of Primary Data for his role in + getting the effort to revise NFSV4 version management started and for + his work in coauthoring the first draft version of this document. + + The author also wishes to thank Chuck Lever and Mike Kupfer of + Oracle, and Bruce Fields of Red Hat for their helpful reviews of this + and other versioning-related documents. + + + + + +Noveck Standards Track [Page 25] + +RFC 8178 NFSv4 Extension July 2017 + + +Author's Address + + David Noveck + NetApp + 1601 Trapelo Road + Waltham, MA 02451 + United States of America + + Phone: +1 781 572 8038 + Email: davenoveck@gmail.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Noveck Standards Track [Page 26] + |