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

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/