| NFSv4 | D. Noveck |
| Internet-Draft | NetApp |
| Updates: 5661, 7862 (if approved) | May 25, 2017 |
| Intended status: Standards Track | |
| Expires: November 26, 2017 |
Rules for NFSv4 Extensions and Minor Versions
draft-ietf-nfsv4-versioning-10
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 RFC5661 and other RFCs defining minor versions.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 26, 2017.
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.
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, two implementations can each choose a subset of available extensions, with the client able to use the subset of the extensions that it is prepared to use that the server supports as well. 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.
The rules in this document supersede previous rules regarding minor versions. The new rules concerning protocol extension and minor versions are summarized in Section 3 while rules regarding the interaction of minor versions appear in Section 8.
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.
The keywords defined by [RFC2119] have special meanings which 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:
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] were used in ways that appear to be at variance with the definitions in that document.
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 which specify the status of features inform:
The term "version" denotes any valid protocol variant constructed according to the rules in this document. It includes minor versions, but there are situations which allow multiple variant versions to be associated with and co-exist within a single minor version:
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:
Each client and server which 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 which 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.
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.
This document supersedes minor versioning rules appearing in the minor version specification RFC's, 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:
Future minor version specification documents should avoid specifying rules relating to minor versioning and reference this document in connection with rules for NFSv4 extension.
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.
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 opposed 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 which 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:
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.
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, callbacks), and responders (i.e. replies, callback replies).
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).
None of the following is allowed to happen:
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:
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 which 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.
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.
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 effect user requests.
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.
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 of which see Section 6).
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:
In making this determination, the requester can rely on two basic facts:
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 would uses to send requests which the server would then accept. The server would use that variant to send callbacks which the client would then accept. This state of affairs could arise in a number of ways:
There are a number of cases to consider based on the characteristics of the minor version chosen.
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.
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 which 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.
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.
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 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.
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.
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.
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:
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 in the event of various errors. 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.
Also, changes were made regarding the required server behavior as to the interaction of the MODE and ACL attributes.
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 defining 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:
Corrections to protocol errors (see Section 9) may be accomplished by publishing an extension, including a compatible XDR change which follows the rules above. Such documents will update the defining documents for the minor version to be corrected.
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:
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.
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.
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.
Servers supporting a given minor version MUST, in returning errors for operations which 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.
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 which simply updates the earlier protocol definition document.
In other cases, it is best if client or server behavior needs to change in a way which raises interoperability concerns. In such cases, incompatible changes in server or client behavior should not be mandated in order to avoid XDR changes.
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,
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.
Based on the type of client:
Based on the type of server:
By using extensions in this manner, the protocol creates a clear path which 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.
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 version, while maintaining necessary interoperability with earlier implementations.
The following types of servers can exist:
With the exception of clients which do not use the feature in question, the following sorts of clients may exist:
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:
In making such changes, interoperability issues would need to be carefully considered.
Since no substantive protocol changes are proposed here, no security considerations apply.
The current document does not require any actions by IANA.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC5661] | Shepler, S., Eisler, M. and D. Noveck, "Network File System (NFS) Version 4 Minor Version 1 Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010. |
| [RFC7530] | Haynes, T. and D. Noveck, "Network File System (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, March 2015. |
| [RFC7862] | Haynes, T., "Network File System (NFS) Version 4 Minor Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862, November 2016. |
| [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. |
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 co-authoring the first 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.