draft-ietf-nfsv4-versioning-02.txt   draft-ietf-nfsv4-versioning-03.txt 
NFSv4 D. Noveck NFSv4 D. Noveck
Internet-Draft HP Internet-Draft HPE
Updates: 5661 (if approved) October 10, 2015 Updates: 5661 (if approved) January 15, 2016
Intended status: Standards Track Intended status: Standards Track
Expires: April 12, 2016 Expires: July 18, 2016
NFSv4 Version Management NFSv4 Version Management
draft-ietf-nfsv4-versioning-02 draft-ietf-nfsv4-versioning-03
Abstract Abstract
This document describes the management of versioning within the NFSv4 This document describes the management of versioning within the NFSv4
family of protocols. It covers the creation of minor versions, the family of protocols. It covers the creation of minor versions, the
addition of optional features to existing minor versions, and 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. this document supersede the minor versioning rules in RFC5661.
skipping to change at page 1, line 37 skipping to change at page 1, line 37
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 12, 2016. This Internet-Draft will expire on July 18, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2016 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
skipping to change at page 2, line 18 skipping to change at page 2, line 18
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Existing Minor Versions . . . . . . . . . . . . . . . . . 4 1.1. Existing Minor Versions . . . . . . . . . . . . . . . . . 4
1.2. Updated NFSv4 Version Management Framework . . . . . . . 4 1.2. Updated NFSv4 Version Management Framework . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 6 2.1. Use of Keywords Defined in RFC2119 . . . . . . . . . . . 6
2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 7 2.2. Use of Feature Statuses . . . . . . . . . . . . . . . . . 7
2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 8 2.3. NFSv4 Versions . . . . . . . . . . . . . . . . . . . . . 8
3. Consolidation of Version Management Rules . . . . . . . . . . 9 3. Consolidation of Version Management Rules . . . . . . . . . . 9
4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 10 4. XDR Considerations . . . . . . . . . . . . . . . . . . . . . 11
4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 10 4.1. XDR Extension . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. XDR Extension in General . . . . . . . . . . . . . . 11 4.1.1. XDR Extension in General . . . . . . . . . . . . . . 11
4.1.2. Particulars of XDR Extension within NFSv4 . . . . . . 12 4.1.2. Particulars of XDR Extension within NFSv4 . . . . . . 12
4.1.3. Rules for XDR Extension within NFSv4 . . . . . . . . 12 4.1.3. Rules for XDR Extension within NFSv4 . . . . . . . . 13
4.2. Handling of Protocol Elements . . . . . . . . . . . . . . 13 4.2. Handling of Protocol Elements . . . . . . . . . . . . . . 13
4.3. Organization of Protocol Elements . . . . . . . . . . . . 14 4.3. Organization of Protocol Elements . . . . . . . . . . . . 15
4.4. Inter-version Interoperability . . . . . . . . . . . . . 14 4.4. Inter-version Interoperability . . . . . . . . . . . . . 15
4.4.1. Requirements for Knowledge of Protocol Elements . . . 14 4.4.1. Requirements for Knowledge of Protocol Elements . . . 15
4.4.2. Establishing Interoperability . . . . . . . . . . . . 16 4.4.2. Establishing Interoperability . . . . . . . . . . . . 16
4.4.3. Determining Knowledge of Protocol Elements . . . . . 17 4.4.3. Determining Knowledge of Protocol Elements . . . . . 18
4.4.4. Interoperability Between Version Groups . . . . . . . 18 4.4.4. Interoperability Between Version Groups . . . . . . . 19
5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 18 5. Other NFSv4 Protocol Changes . . . . . . . . . . . . . . . . 19
5.1. Non-XDR Protocol Changes . . . . . . . . . . . . . . . . 19 5.1. Non-XDR Protocol Changes . . . . . . . . . . . . . . . . 19
5.1.1. Field Interpretation and Use . . . . . . . . . . . . 19 5.1.1. Field Interpretation and Use . . . . . . . . . . . . 20
5.1.2. Behavioral Changes . . . . . . . . . . . . . . . . . 20 5.1.2. Behavioral Changes . . . . . . . . . . . . . . . . . 21
5.1.3. Rules for non-XDR changes . . . . . . . . . . . . . . 20 5.1.3. Rules for non-XDR changes . . . . . . . . . . . . . . 21
5.2. Specification of Associated Protocols . . . . . . . . . . 21 5.2. Specification of Associated Protocols . . . . . . . . . . 22
5.2.1. Associated Protocols via pNFS Mapping Types . . . . . 22 5.2.1. Associated Protocols via pNFS Mapping Types . . . . . 22
5.2.2. Additional Forms of Associated Protocols . . . . . . 22 5.2.2. Additional Forms of Associated Protocols . . . . . . 23
6. NFSv4 Protocol Features . . . . . . . . . . . . . . . . . . . 23 6. NFSv4 Protocol Features . . . . . . . . . . . . . . . . . . . 24
6.1. Previous Uses of the Feature Concept . . . . . . . . . . 24 6.1. Previous Uses of the Feature Concept . . . . . . . . . . 25
6.2. Rules for Protocol Feature Construction . . . . . . . . . 25 6.2. Rules for Protocol Feature Construction . . . . . . . . . 25
6.3. Statuses of Features . . . . . . . . . . . . . . . . . . 25 6.3. Statuses of Features . . . . . . . . . . . . . . . . . . 26
6.4. Statuses of Protocol Elements Within Features . . . . . . 26 6.4. Statuses of Protocol Elements Within Features . . . . . . 27
6.5. Determining Protocol Element Support . . . . . . . . . . 28 6.5. Determining Protocol Element Support . . . . . . . . . . 29
6.6. Feature Discovery . . . . . . . . . . . . . . . . . . . . 29 6.6. Feature Discovery . . . . . . . . . . . . . . . . . . . . 30
7. Documentation of Protocol Changes . . . . . . . . . . . . . . 31 6.7. Feature Incorporation . . . . . . . . . . . . . . . . . . 31
7.1. Documentation Approach . . . . . . . . . . . . . . . . . 31 7. Extensions within Minor Versions . . . . . . . . . . . . . . 32
7.2. Indexing material . . . . . . . . . . . . . . . . . . . . 31 7.1. Adding Features to Extensible Minor Versions . . . . . . 32
7.3. Feature Specification Documents . . . . . . . . . . . . . 32 7.2. Use of Feature Specification Documents . . . . . . . . . 32
7.4. Feature Incorporation . . . . . . . . . . . . . . . . . . 34 7.3. Compatibility Issues . . . . . . . . . . . . . . . . . . 33
7.5. XDR File Considerations . . . . . . . . . . . . . . . . . 34 7.3.1. Compatibility Issues for Messages Sent to Servers . . 34
8. Extensions within Minor Versions . . . . . . . . . . . . . . 35 7.3.2. Compatibility Issues for Messages Sent to Clients . . 35
9. Adding Features to Extensible Minor Versions . . . . . . . . 36
9.1. Use of Feature Specification Documents . . . . . . . . . 36 7.4. Relationship Between Minor Versioning and Extensions
9.2. Compatibility Issues . . . . . . . . . . . . . . . . . . 37 within a Minor Version . . . . . . . . . . . . . . . . . 36
9.2.1. Compatibility Issues for Messages Sent to Servers . . 37 8. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 36
9.2.2. Compatibility Issues for Messages Sent to Clients . . 38 8.1. Creation of New Minor Versions . . . . . . . . . . . . . 36
9.3. Additional Documents to be Produced . . . . . . . . . . . 39 8.1.1. New Minor Versions within an Existing Group . . . . . 37
9.3.1. Minor Version Indexing Document . . . . . . . . . . . 39 8.1.2. New Minor Version Groups . . . . . . . . . . . . . . 37
9.3.2. Consolidated XDR Document . . . . . . . . . . . . . . 40 8.1.3. Limits on Minor Version Groups . . . . . . . . . . . 40
9.3.3. XDR Assignment Document . . . . . . . . . . . . . . . 40 8.2. Role of Minor Versions . . . . . . . . . . . . . . . . . 41
9.3.4. Transition of Documents to RFC's . . . . . . . . . . 41 8.3. Minor Version Interaction Rules . . . . . . . . . . . . . 41
9.4. Relationship Between Minor Versioning and Extensions 8.3.1. Minor Version Identifier Transfer Issues . . . . . . 42
within a Minor Version . . . . . . . . . . . . . . . . . 42 8.3.2. Minor Version Intra-Group Compatibility . . . . . . . 42
10. Minor Versions . . . . . . . . . . . . . . . . . . . . . . . 43 8.3.3. Minor Version Inter-Group Compatibility . . . . . . . 43
10.1. Reasons for New Minor Versions . . . . . . . . . . . . . 43 9. Correction of Existing Minor Versions and Features . . . . . 44
10.1.1. New Minor Versions within an Existing Group . . . . 43 9.1. XDR Changes to Implement Protocol Corrections . . . . . . 45
10.1.2. New Minor Version Groups . . . . . . . . . . . . . . 43 10. Documentation of Features, Extensions, Minor Versions, and
10.1.3. Limits on Minor Version Groups . . . . . . . . . . . 46 Protocol Corrections . . . . . . . . . . . . . . . . . . . . 46
10.2. Role of Minor Versions . . . . . . . . . . . . . . . . . 47 10.1. Documentation Approach . . . . . . . . . . . . . . . . . 47
10.3. Minor Version Interaction Rules . . . . . . . . . . . . 47 10.2. Indexing material . . . . . . . . . . . . . . . . . . . 47
10.3.1. Minor Version Identifier Transfer Issues . . . . . . 48 10.3. Feature Specification Documents . . . . . . . . . . . . 48
10.3.2. Minor Version Intra-Group Compatibility . . . . . . 48 10.4. XDR File Considerations . . . . . . . . . . . . . . . . 50
10.3.3. Minor Version Inter-Group Compatibility . . . . . . 49 10.5. Additional Documents to Support Protocol Extension . . . 51
10.4. Minor Version Documentation . . . . . . . . . . . . . . 50 10.5.1. Minor Version Indexing Document . . . . . . . . . . 51
11. Correction of Existing Minor Versions and Features . . . . . 50 10.5.2. Consolidated XDR Document . . . . . . . . . . . . . 52
11.1. XDR Changes to Implement Protocol Corrections . . . . . 51 10.5.3. XDR Assignment Document . . . . . . . . . . . . . . 52
11.2. Documentation of XDR Changes . . . . . . . . . . . . . . 53 10.5.4. Transition of Documents to RFC's . . . . . . . . . . 53
12. Security Considerations . . . . . . . . . . . . . . . . . . . 54 10.6. Documentation of New Minor Versions . . . . . . . . . . 54
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 10.7. Documentation of XDR Changes for Corrections . . . . . . 54
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 11. Security Considerations . . . . . . . . . . . . . . . . . . . 55
14.1. Normative References . . . . . . . . . . . . . . . . . . 54 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
14.2. Informative References . . . . . . . . . . . . . . . . . 54 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 55
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 55 13.1. Normative References . . . . . . . . . . . . . . . . . . 55
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 55 13.2. Informative References . . . . . . . . . . . . . . . . . 55
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 57
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 57
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 version management modification of existing minor versions. The version management
rules contained in this document allow extensions and other changes rules contained in this document allow extensions and other changes
to be implemented in a way that maintains compatibility with existing to be implemented in a way that maintains compatibility with existing
skipping to change at page 4, line 28 skipping to change at page 4, line 28
o Minor version 1 (NFSv4.1) is specified by [RFC5661] with the XDR o Minor version 1 (NFSv4.1) is specified by [RFC5661] with the XDR
description appearing in [RFC5662]. description appearing in [RFC5662].
o Minor version 2 (NFSv4.2) is specified by [NFSv42] (in terms of o Minor version 2 (NFSv4.2) is specified by [NFSv42] (in terms of
changes from [RFC5661]). The XDR description appears in changes from [RFC5661]). The XDR description appears in
[NFSv42-dot-x] [NFSv42-dot-x]
Existing minor versions can be divided into two groups, based on Existing minor versions can be divided into two groups, based on
compatibility considerations. NFSv4.0 is one group, while NFSv4.1, compatibility considerations. NFSv4.0 is one group, while NFSv4.1,
NFSv4.2, and potentially other minor versions form a second group. NFSv4.2, and potentially other minor versions, form a second group.
The definition of NFSv4 minor version groups is explained in more The definition of NFSv4 minor version groups is explained in more
detail in Section 2.3, as are the concepts of NFSv4 versions and detail in Section 2.3, as is the concept of variants within minor
version groups. versions and version groups.
1.2. Updated NFSv4 Version Management Framework 1.2. Updated NFSv4 Version Management Framework
A number of significant changes from previous version management A number of significant changes from previous version management
practices should be noted here: practices should be noted here:
o Creation of a new minor version is no longer the only way in which o Creation of a new minor version is no longer the only way in which
protocol changes may be made. Added optional features and protocol changes may be made. Added optional features and
protocol corrections can be proposed, specified and implemented protocol corrections can be proposed, specified and implemented
within the context of a single minor version. Creation of new within the context of a single minor version. Creation of new
minor versions remains available to make other sorts of changes. minor versions remains available to make other sorts of changes.
o Specification of future minor versions in the way that was done o Specification of future minor versions in the way that was done
for NFSv4.0 and NFSv4.1 (i.e. as a single document defining the for NFSv4.0 and NFSv4.1 (i.e. as a single document defining the
entire protocol) is no longer practical and should not be entire protocol) is no longer practical and should not be
attempted. All future minor versions will be documented by attempted. All future minor versions will be documented by
specifying the differences between the minor version being specifying the differences between the minor version being
documented and the previous minor version. The documentation documented and the previous minor version. The documentation
framework discussed in Section 7 should be used. framework discussed in Section 10 should be used.
After dealing with some preliminary matters, this document focuses on After dealing with some preliminary matters, this document focuses on
presenting the conceptual framework on which NFSv4 versioning is presenting the conceptual framework on which NFSv4 versioning is
built. built.
o First we discuss (in Section 4) how the XDR descriptions for o First we discuss (in Section 4) how the XDR descriptions for
various NFSv4 versions can be extended to produce the XDR various NFSv4 versions can be extended to produce the XDR
descriptions for other versions while allowing clients and servers descriptions for other versions while allowing clients and servers
using the XDR descriptions associated with different versions to using the XDR descriptions associated with different versions to
communicate. communicate.
o We then complete the discussion (in Section 5) of the range of o We then complete the discussion (in Section 5) of the range of
protocol changes that NFSv4 versioning is to deal with. protocol changes that NFSv4 versioning is to deal with.
o Then we discuss (in Section 6) how those changes are organized o Then we discuss (in Section 6) how those changes are organized
into features and feature packages. into features and feature packages.
Using this framework, we then discuss how changes are documented and Using this framework, we look at the ways that those changes can be
look at the ways that those changes can be incorporated into the incorporated into the NFSv4 protocol.
NFSv4 protocol.
o The addition of new feature packages to existing minor versions is o The addition of new feature packages to existing minor versions is
discussed in Sections 8 and 9. discussed in Section 7.
o New Minor versions can be constructed, as described in Section 10. o New Minor versions can be constructed, as described in Section 8.
o Issues relating to the correction of protocol errors in existing o Issues relating to the correction of protocol errors in existing
features and minor versions are discussed in Section 11. features and minor versions are discussed in Section 9.
We then discuss (in Section 10) how features, minor versions, and
protocol corrections will be documented.
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
In this document, the word "feature" is used , except in the case of In this document, the word "feature" is used , except in the case of
quotations, to denote a key structuring concept which allows the quotations, to denote a key structuring concept. By organizing
defining RFCs to clearly specify what protocol elements must be changes into features, defining RFCs can clearly specify what
supported together by the server and when a given server must be able protocol elements a server must be able to recognize and what
to correctly interpret the corresponding associated protocol protocol elements a server must support. See Section 6 for more
constructs. See Section 6 for more details. which allows the defining RFCs to clearly specify what protocol
elements must be supported together by the server and when a given
In previous NFSv4 documents, the word "features" has been used in a server must be able to correctly interpret the corresponding
number of different senses, as discussed in Section 6.1. associated protocol constructs. See Section 6 for more details.
Two important terms related to the feature concept need to be
introduced here:
o A "feature package" is a set of features defined together, either A feature contains one or more "feature elements". Often, at least
because they were defined together as part of a minor version or one feature element will be a protocol extension that can help a
as part of the same protocol extension. sender determine whether the receiver supports a given feature. See
Section 4.1.3 for more details. A feature element may also be one of
a set of other types of protocol change as described in Section 5.
o A "feature element" is one of the constituent changes which is A "feature package" is a set of features that are defined together,
part of a given feature. This can include the addition of the either as part of a minor version or as part of the same protocol
protocol elements described in Section 4.1.3 but also the other extension.
sorts of allowed protocol changes described in Section 5.
We also need to introduce our vocabulary regarding specification of We also need to introduce our vocabulary regarding specification of
features and minor versions. Given the ongoing shift to a finer- features and minor versions. Given the ongoing shift to a finer-
grained documentation model, it is important to be clear here. grained documentation model, it is important to be clear here.
o The term "minor version definition document" denotes the principal o The term "minor version definition document" denotes the principal
document defining a specific NFSv4 minor version. It may be in document defining a specific NFSv4 minor version. It may be in
the form of a complete protocol definition (e.g. [RFC7530], the form of a complete protocol definition (e.g. [RFC7530],
[RFC5661]), a specification of changes relative to the previous [RFC5661]), a specification of changes relative to the previous
minor version (e.g. [NFSv42]), or in a document that specifies minor version (e.g. [NFSv42]), or in a document that specifies
the features to be included, either by referencing their the features to be included, either by referencing their
definition document normatively (see Section 10.4) or implicitly definition document normatively (see Section 10.6) or implicitly
(see Section 9). (see Section 7.1).
o The term "minor version documentation" includes the minor version o The term "minor version documentation" includes the minor version
definition document but also includes any corresponding XDR definition document but also includes any corresponding XDR
definition documents if they are published separately (e.g. definition documents if they are published separately (e.g.
[RFC7531], [RFC5662], [NFSv42-dot-x]). Also included are [RFC7531], [RFC5662], [NFSv42-dot-x]). Also included are
documents separately specifying features newly incorporated in the documents separately specifying features newly incorporated in the
minor version and the ancillary documents described in minor version and the ancillary documents described in
Section 9.3. Section 10.5.
o The term "feature definition document" denotes a document o The term "feature definition document" denotes a document
describing a single feature or a set of closely related features, describing a single feature or a set of closely related features,
forming a feature package. forming a feature package.
o The term "protocol definition document" denotes a minor version o The term "protocol definition document" denotes a minor version
definition document, a feature definition document or any definition document, a feature definition document or any
standards-track document updating one of these. standards-track document updating one of these.
2.1. Use of Keywords Defined in RFC2119 2.1. Use of Keywords Defined in RFC2119
skipping to change at page 8, line 25 skipping to change at page 8, line 25
the protocol elements the protocol elements
When the status of a protocol feature is specified, the support When the status of a protocol feature is specified, the support
requirements for associated protocol elements are defined by the requirements for associated protocol elements are defined by the
status of the protocol elements with regard to the feature in status of the protocol elements with regard to the feature in
question as described in Section 6.4. question as described in Section 6.4.
The fact that such statuses and the organization of protocol features The fact that such statuses and the organization of protocol features
may change between minor version groups may raise interoperability may change between minor version groups may raise interoperability
issues which the authors of minor version RFCs and the working group issues which the authors of minor version RFCs and the working group
need to carefully consider. See Section 10.1.2 for guidance in this need to carefully consider. See Section 8.1.2 for guidance in this
regard. regard.
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 versions to be but there are situations which allow multiple variant versions to be
associated with and co-exist within a single minor version: associated with and co-exist 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 proper) of the feature combined with any subset (not necessarily proper) of the feature
specification documents, is a valid NFSv4 version which is part of specification documents, is a valid NFSv4 version variant which is
the minor version in question. 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 which 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 which is part publication of the update, is a valid NFSv4 version variant which
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
part of a given minor version. Two of these are worthy of special
terms:
o The term "base minor version" denotes the version variant that
corresponds to the minor version as originally defined, including
all protocol elements specified in the minor version definition
document but not incorporating any extensions or protocol
corrections published subsequently.
o At any given time, the term "current minor version" denotes the
minor version variant including all extensions of and corrections
to the minor version made by standard-track documents published
subsequently.
Each version variant which is part of a given minor version 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, one may refer the
set of REQUIRED features in a given minor version since it is the
same for all variants within the minor version.
Each client and server which implements a specific minor version will
implement some particular variant of that minor version. Each of
these will be a superset of the appropriate base minor version.
A minor version group is defined as a set of minor versions having A minor version group is defined as a set of minor versions having
exactly the same set of REQUIRED and mandatory to not implement exactly the same set of REQUIRED and mandatory to not implement
protocol elements. Clients and servers which implement minor protocol elements. The union of the sets of variants for all these
versions within the same group should be compatible as long as each minor versions provides a high degree of inter-variant compatibility.
takes proper care, as it should, to properly deal with the case in Clients and servers which implement variants within this group should
which the other party does not know of or has no support for OPTIONAL be compatible as long as each takes proper care, as it should, to
protocol elements. The associated set of versions is referred to as properly deal with the case in which the other party does not know of
a "version group". or has no support for OPTIONAL protocol elements.
3. Consolidation of Version Management Rules 3. Consolidation of Version Management Rules
In the past, the only existing version management rules were the In the past, the only existing version management rules were the
minor versioning rules that had been being maintained and specified minor versioning rules that had been being maintained and specified
in the Standards Track RFCs which defined the individual minor in the Standards Track RFCs which defined the individual minor
versions. In the past, these minor versioning rules were modified on versions. In the past, these minor versioning rules were modified on
an ad hoc basis for each new minor version. an ad hoc basis for each new minor version.
More recently, minor versioning rules were specified in [RFC5661] More recently, minor versioning rules were specified in [RFC5661]
skipping to change at page 9, line 37 skipping to change at page 10, line 17
various forms of versioning provided for in the NFSv4 version various forms of versioning provided for in the NFSv4 version
management framework. management framework.
o The kinds of changes that may be made are addressed in the rules o The kinds of changes that may be made are addressed in the rules
in Sections 4.1.3, 5.1.3, 5.2.1, and 5.2.2. in Sections 4.1.3, 5.1.3, 5.2.1, and 5.2.2.
o Rules relating to the composition of changes into protocol o Rules relating to the composition of changes into protocol
features are addressed in Section 6.2 features are addressed in Section 6.2
o Rules limiting the protocol features which may be effected as an o Rules limiting the protocol features which may be effected as an
extension to an existing minor version appear in Section 8. extension to an existing minor version appear in Section 7.
o Minor version construction, including rules applicable to protocol o Minor version construction, including rules applicable to protocol
features which cannot be used as extensions to existing minor features which cannot be used as extensions to existing minor
versions are addressed in Sections 10.1.1 and 10.1.2. versions are addressed in Sections 8.1.1 and 8.1.2.
o Minor version interaction rules are discussed in Sections 10.3.2, o Minor version interaction rules are discussed in Sections 8.3.2,
10.3.3, and 10.3.1. 8.3.3, and 8.3.1.
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]. As minor version specification RFC's, including those in [RFC5661]. As
a result, potential conflicts among these documents should be a result, potential conflicts among these documents should be
addressed as follows: addressed as 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 RFC's. 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. In particular, many of the version B protocol stays as it is. In particular, many of the
changes made for NFSV4.1 would not be allowed in the version changes made for NFSV4.1 would not be allowed in the version
management framework defined here. See Section 5.1.3 for details. management framework defined here. See Section 5.1.3 for details.
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 10.3 for a discussion of these more complicated. See Section 8.3 for a discussion of these
issues, including how potential conflicts between rules are to be issues, including how potential conflicts between rules are to be
resolved. resolved.
o Otherwise, any conflict between the version management rules in o Otherwise, any conflict between the version management rules in
this document and those in minor version specification RFC's are this document and those in minor version specification RFC's are
to be resolved based on the treatment in this document. In to be resolved based on the treatment in this document. In
particular, corrections may be made as specified in Section 11 for particular, corrections may be made as specified in Section 9 for
all previously specified minor versions and the extensibility of all 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 9. with Section 7.1.
Future minor version specification documents should avoid specifying Future minor version specification documents should avoid specifying
minor versioning rules and reference this document in connection with minor versioning rules and reference this document in connection with
rules for NFSv4 version management. rules for NFSv4 version management.
4. XDR Considerations 4. XDR Considerations
As an extensible XDR-based protocol, NFSv4 has to ensure interversion As an extensible XDR-based protocol, NFSv4 has to ensure interversion
compatibility, in situations in which the client and server use compatibility, in situations in which the client and server use
different XDR descriptions. The XDR extension paradigm, discussed in different XDR descriptions. For example, the client may implement
Section 4.1, assures that these descriptions are compatible, with different variants of the same minor version or different variants
clients and servers able to determine and use those portions of the that are part of the same minor version group. The XDR extension
protocol that they both share according to the methods described in paradigm, discussed in Section 4.1, assures that these descriptions
Sections 4.4.2 and 4.4.4. are compatible, with clients and servers able to determine and use
those portions of the protocol that they both share according to the
methods described in Sections 4.4.2 and 4.4.4.
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 opposed to transitions between major NFS versions
(including that between NFSv3 and NFSv4.0) in which the XDR for one (including that between NFSv3 and NFSv4.0) in which the XDR for one
version was replaced by a different XDR for a newer version. version was replaced by a different XDR for a newer version.
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. For specifics regarding rules for compatibility is obtained. For specifics regarding rules for
interversion compatibility, see Section 10.3.2. For a discussion of interversion compatibility, see Section 8.3.2. For a discussion of
compatibility issues that might arise between different version compatibility issues that might arise between different version
groups, see Sections 10.1.2 and 10.3.3. groups, see Sections 8.1.2 and 8.3.3.
4.1.1. XDR Extension in General 4.1.1. XDR Extension in General
The XDR extension approach provides a way for an XDR description to The XDR extension approach provides a way for an XDR description to
be extended in a way which retains the structure of all previously be extended in a way which retains the structure of all previously
valid messages. If a base XDR description is extended to create a valid messages. If a base XDR description is extended to create a
second XDR description, the following will be true for the second second XDR description, the following will be true for the second
description to be a valid extension of the first: description to 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
skipping to change at page 11, line 29 skipping to change at page 12, line 10
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 unsupported recognized, using the base definition, as part of an unsupported
extension. extension.
An extension of a given XDR description consists of any of the In general, an extension of a given XDR description consists of any
following: set of the following changes:
o Addition of previously unspecified RPC operation codes. o Addition of previously unspecified RPC operation codes.
o Addition of new, previously unused, values to existing enums. o Addition of new, previously unused, values to existing enums.
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.
skipping to change at page 12, line 10 skipping to change at page 12, line 39
o Similarly, none of these items may be reused for a new purpose. o Similarly, none of these items may be reused for a new purpose.
o Any change to the XDR-defined structure of existing requests or o Any change to the XDR-defined structure of existing requests or
replies other than those listed above. replies other than those listed above.
4.1.2. Particulars of XDR Extension within NFSv4 4.1.2. Particulars of XDR Extension within NFSv4
There are issues, particular to NFSv4, that affect the definition of There are issues, particular to NFSv4, that affect the definition of
a valid XDR extension within NFSv4. a valid XDR extension within NFSv4.
o Because NFSv4 has chosen to structure itself around compound o Because NFSv4 has been structured around compound requests and
requests and callbacks, addition of previously unspecified RPC callbacks, addition of previously unspecified RPC operation codes
operation codes is not allowed. is not allowed.
o Although they fit under the general category of enumerations, o Although they fit under the general category of enumerations,
operation codes (including those for callbacks) are so central to operation codes (including those for callbacks) are so central to
the structure of NFSv4, that they merit special treatment. the structure of NFSv4, that they merit special treatment.
o The fact that attribute value sets are represented within NFSv4 by o The fact that attribute value sets are represented within NFSv4 by
nominally opaque arrays calls for special handling. nominally opaque arrays calls for special handling.
4.1.3. Rules for XDR Extension within NFSv4 4.1.3. Rules for XDR Extension within NFSv4
skipping to change at page 12, line 40 skipping to change at page 13, line 24
o Addition of new, previously unused, values to existing enums. o Addition of new, previously unused, values to existing enums.
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.
However, none of the following is allowed to happen: However, none of the following is allowed to happen:
o Any change to the structure of existing requests or replies other
than those listed above.
o Addition of previously unspecified RPC operation codes, for either
the nfsv4 program or the callback program, is not allowed.
o Deletion of existing RPC operations, enum values, flag bit values o Deletion of existing RPC operations, enum values, flag bit values
and switch cases. Note that changes may be made to define use of and switch cases. Note that changes may be made to define use of
any of these as causing an error, as long as the XDR is any of these as causing an error, as long as the XDR is
unaffected. unaffected.
o Similarly, none of these items may be reused for a new purpose. o Similarly, none of these items may be reused for a new purpose.
o Any change to the structure of existing requests or replies other
than those listed above.
4.2. Handling of Protocol Elements 4.2. Handling of Protocol Elements
Implementations handle protocol elements in one of three ways. Which Implementations handle protocol elements in one of three ways. Which
of the following ways are valid depends on the status of the protocol of the following ways are valid depends on the status of the protocol
element in the minor version being implemented: element in the variant being implemented:
o The protocol element is not a part of definition of the version in o The protocol element is not a part of definition of the variant in
question and so is "unknown". The responder, when it does not question and so is "unknown". The responder, when it does not
report an RPC XDR decode error. reports an error indicative of report an RPC XDR decode error. reports an error indicative of
the element not being defined in the XDR such as the element not being defined in the XDR such as
NFS4ERR_OP_ILLEGAL, NFS4ERR_BADXDR, or NFS4ERR_INVAL. See NFS4ERR_OP_ILLEGAL, NFS4ERR_BADXDR, or NFS4ERR_INVAL. See
Section 4.4.3 for details. Section 4.4.3 for details.
o The protocol element is a known part of the version 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. See Section 6.5 for details. or NFS4ERR_ATTRNOTSUPP. See Section 6.5 for details.
o The protocol element is a known part of the version which is o The protocol element is a known part of the variant which 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 feature element in the minor version. The following status of the feature element in the minor version specified in the
possibilities exist: COMPOUND or CB_COMPOUND. The possibilities which can exist are
listed below.
o The protocol element is not known in the minor version. In this o The protocol element is not known in the current variant of minor
case all implementations of the minor version MUST indicate that version. In this case all implementations of the minor version
the protocol element is not known. MUST indicate that the protocol element is not known.
o The protocol element is specified mandatory to not implement in o The protocol element is specified mandatory to not implement in
the minor version. In this case as well, all implementations of the minor version. In this case as well, all implementations of
the minor version MUST indicate that the protocol element is not the minor version MUST indicate that the protocol element is not
known. known.
o The protocol element is defined as part of an extension in the o The protocol element is defined as part of the current variant of
minor version. In this case, the requester can encounter the minor version but is not part of the corresponding base
situations in which the protocol element is not known, is known variant. In this case, the requester can encounter situations in
but not supported, or is supported. which the protocol element is either not known to the responder ,
is known but not supported by the responder, or is both known to
and supported by the responder.
o The protocol element is defined as an OPTIONAL part of the minor o The protocol element is defined as an OPTIONAL part of the base
version and not part of an extension to the minor version. In minor version. In this case, the requester can expect the
this case, the requester can expect the protocol element to be protocol element to be known but must deal with cases in which it
known but must deal with cases in which it is supported or not. is supported or is not supported.
o The protocol element is defined as a REQUIRED part of the minor o The protocol element is defined as a REQUIRED part of the base
version. In this case, the requester can expect the protocol minor version. In this case, the requester can expect the
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 protocol elements, will allow the requester to be sure that certain
of these possibilities cannot occur. of 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
skipping to change at page 14, line 29 skipping to change at page 15, line 13
support for problematic requests before they are actually issued. support for problematic requests before they are actually issued.
4.3. Organization of Protocol Elements 4.3. Organization of Protocol Elements
To enable compatible operation within a version group, all of the To enable compatible operation within a version group, all of the
protocol elements within an NFSv4 minor version are organized as protocol elements within an NFSv4 minor version are organized as
follows: follows:
o Each protocol element is defined as a member of exactly one o Each protocol element is defined as a member of exactly one
feature. One important reason for this organization (see feature. One important reason for this organization (see
Section 6) for others is to regularize and simplify the Section 6 for others) is to regularize and simplify the
determination by the client/server as to what protocol elements determination by the client and server as to what protocol
the other party supports. elements the other party supports.
o Each feature is defined as a member of a feature package, based on o Each feature is defined as a member of a feature package, based on
how it was defined. Features established as part of a minor how it was defined. Features established as part of a minor
version at the same time belong to the same feature package. version at the same time belong to the same feature package.
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 that are each valid extensions server versions have XDR definitions that are each valid extensions
of a third version. Once that version is determined, it may be used of a third version. Once that version is determined, it may be used
by both client and server to communicate. Each party can by both client and server to communicate. Each party can
successfully use a subset of protocol elements that are both known successfully use a subset of protocol elements that are both known
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 XDR following rules apply. These rules are the result of the use of XDR
extension paradigm combined with the way in which extensions are 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 of which see
Section 9). Section 7.1).
o Any protocol element initially defined as part of a particular o Any protocol element defined as part of the base variant of
minor version is required to be known by that minor version. This particular minor version is required to be known by that minor
occurs whether the specification happens in the body of the minor version. This occurs whether the specification happens in the
definition document or is in a feature definition document that is body of the minor definition document or is in a feature
made part of the minor version by being normatively referenced by definition document that is made part of the minor version by
the minor version definition document. being normatively referenced by the minor version definition
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 version, unless and is required to be known in subsequent minor version, unless and
until a minor version has made that protocol element as mandatory until a minor version has made that protocol element as mandatory
to not implement. to not implement.
o When a protocol element is defined as part of an extension to an o When a protocol element is defined as part of an extension to an
extensible minor version, it is not required to be known in that extensible minor version, it is not required to be known in that
minor version but is required to be known by the next minor minor version but is required to be known by the next minor
version. In the earlier minor version, it might not might not be version. In the earlier minor version, it might not be defined in
defined in the XDR, while in the later version it needs to be the XDR definition document for that minor, while in the later
defined in the XDR. In either case, if it is defined, it might or version it needs to be defined in the XDR definition document. In
might not be supported. either case, if it is defined, it might or might not be supported.
o When knowledge of protocol elements is optional in a given minor o When knowledge of protocol elements is optional in a given minor
version, the responder's knowledge of such optional elements must version, the responder's knowledge of such optional elements must
obey the rule that if one such element is known, then all the obey the rule that if one such element is known, then all the
protocol elements defined in the same minor version definition protocol elements defined in the same minor version definition
document must be known as well. document must be known as well.
For many minor versions, all existing protocol elements, are required For many minor versions, all existing protocol elements, are required
to be known by both the client and the server, and so requesters do 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 not have to test for the presence or absence of knowledge regarding
protocol elements for which knowledge might be optional. This is the protocol elements for which knowledge might be optional. This is the
case if there has been no extension for the minor version in case if there has been no extension for the minor version in
question. Extensions can be added to extensible minor versions as question. Extensions can be added to extensible minor versions as
described in Section 9 and can be used to correct protocol flaws as described in Section 7.1 and can be used to correct protocol flaws as
described in Section 11. described in Section 9.
Requesters can ascertain the knowledge of the responder in two ways: Requesters can ascertain the knowledge of the responder in two ways:
o By issuing a request using the protocol element and looking at the o By issuing a request using the protocol element and looking at the
response. Note that, even if the protocol element used is not response. Note that, even if the protocol element used is not
supported by the responder can still determine if the element is supported by the responder, the requester can still determine if
known by the responder. the element is known by the responder.
o By receiving a request from the responder, acting in the role of o By receiving a request from the responder, acting in the role of
requester. For example, a client may issue a request enabling the requester. For example, a client may issue a request enabling the
server to infer that it is aware of a corresponding callback. server to infer that it is aware of a corresponding callback.
In making this determination, the requester can rely on two basic In making this determination, the requester can rely on two basic
facts: facts:
o If the responder is aware of a single protocol element within a o If the responder is aware of a single protocol element within a
feature package, it must be aware of all protocol elements within feature package, it must be aware of all protocol elements within
skipping to change at page 16, line 23 skipping to change at page 17, line 9
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 section, we will deal with situation in which the client and In this section, we will deal with situation in which the client and
server are of the same version group. Later, in Section 4.4.4, we server are of the same version group. Later, in Section 4.4.4, we
will discuss possible extensions to the inter-version-group case. will discuss possible extensions to the inter-version-group case.
In this context, the client and server would be using a common minor In this context, the client and server would arrive at a common
version which the client uses to send requests and the server variant which the client would uses to send requests which the server
accepts. The server would use that minor version to send callbacks would then accept. The server would use that variant to send
which the client would then accept. This state of affairs could callbacks which the client would then accept. This state of affairs
arise in a number of ways: could arise in a number of ways:
o Client and server have been built using XDR versions 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 10.3.2, accepts the this case the server, in accord with Section 8.3.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. extensions made in subsequent minor versions. It has knowledge of
protocol elements within the current (i.e. effectively final)
variant of the lower minor version.
o The client's minor version is higher than that of the server. In o The client's minor version is higher than that of the server. In
this case the client, in accord with Section 10.3.2, uses a lower this case the client, in accord with Section 8.3.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 The minor version consists of only a single version (no extension o The minor version consists of only a single variant (no extension
or XDR corrections), so the client and the server are using the or XDR corrections), so the client and the server are using the
same XDR description and have knowledge of the same protocol same XDR description and have knowledge of the same protocol
elements. elements.
o When the minor version consists of multiple versions (one or more o When the minor version consists of multiple variants (i.e. there
XDR extensions or XDR corrections), the client and the server are are one or more XDR extensions or XDR corrections), the client and
using compatible XDR descriptions. The client is aware of some the server are using compatible XDR descriptions. The client is
set of extensions while he server may be aware of a different set. aware of some set of extensions while the server may be aware of a
The client can determine which of the extensions that he is aware different set. The client can determine which of the extensions
of, are also known to the server by using the approach described that he is aware of, are also known to the server by using the
in Section 4.4.3. Once this is done, the client and server will approach described in Section 4.4.3. Once this is done, the
both be using a common version. The versions that the client and client and server will both be using a common variant. The
server were built with will both either be identical to this variants that the client and the server were built with will both
version or a valid extension of it. either be identical to this variant or a valid extension of it.
Similarly, the variants that the client and the server actually
use will be a subset of this variant, in that certain OPTIONAL
features will not be used.
In either case, the client must determine which of the OPTIONAL In either case, the client must determine which of the OPTIONAL
protocol elements within the common version are supported by the protocol elements within the common version are supported by the
server as described in Section 6.6. server as described in Section 6.6.
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.
skipping to change at page 18, line 16 skipping to change at page 19, line 7
knowledge of the operation in question. Other responses, knowledge of the operation in question. Other responses,
including NFS4ERR_UNION_NOTSUPP, indicate that the responder is including NFS4ERR_UNION_NOTSUPP, indicate that the responder is
aware of the protocol element in question. aware of the protocol element in question.
A determination of the knowledge or lack of knowledge of a particular A determination of the knowledge or lack of knowledge of a particular
protocol element is expected to remain valid as long as the clientid protocol element is expected to remain valid as long as the clientid
associated with the request remains valid. associated with the request remains valid.
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 10.3.2. issue, see Section 8.3.2.
4.4.4. Interoperability Between Version Groups 4.4.4. Interoperability Between Version Groups
Within a minor version, we have complete compatibility in the sense Within a minor version group, we have complete compatibility in the
that: sense that:
o Servers are REQUIRED to implement a core set of feature which o Servers are REQUIRED to implement a core set of features which
cannot change within the minor version group, allowing clients to cannot change within the minor version group, allowing clients to
depend on the continued existence of and support for these depend on the continued existence of and support for these
features as long as one remains within the minor version group. features as long as one remains within the minor version group.
o The set of OPTIONAL features supported or known by servers may o The set of OPTIONAL features supported or known by servers may
change but clients, in using such OPTIONAL features need to be change but clients, in using such OPTIONAL features need to be
prepared for the fact that they might not be implemented on all prepared for the fact that they might not be implemented on all
servers implementing a minor version within the same version servers implementing a minor version within the same version
group. group.
The same level of compatibility is not provided between different The same level of compatibility is not provided between different
minor version groups. Nevertheless, the same guarantees of inter-XDR minor version groups. Nevertheless, the same guarantees of inter-XDR
comprehensibility apply across minor version groups. For a comprehensibility apply across minor version groups. For a
discussion of how this comprehensibility can be used between minor discussion of how this comprehensibility can be used between minor
version groups, see Section 10.3.3. version groups, see Section 8.3.3.
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
also managed within the NFSv4 versioning framework and may be of a also managed within the NFSv4 versioning framework and may be of a
number of types, which are discussed in the sections below number of types, which are discussed in the sections below
Each such change will be organized, documented and effected as part Each such change will be organized, documented and effected as part
of a given feature, just as changes discussed in Section 4 are. The of a given feature, just as changes discussed in Section 4 are. The
way such features will be incorporated in the NFSv4 protocol depends way such features will be incorporated in the NFSv4 protocol depends
on a number of factors, including the types of changes included in on a number of factors, including the types of changes included in
the feature. This subject is discussed in Sections 7.4 and 8. the feature. This subject is discussed in Sections 6.7 and 7.
5.1. Non-XDR Protocol Changes 5.1. Non-XDR Protocol Changes
Despite the previous emphasis on XDR changes, additions and changes Despite the previous emphasis on XDR changes, additions and changes
to the NFSv4 protocols have not been limited to those that involve to the NFSv4 protocols have not been limited to those that involve
changes (in the form of extensions) to the protocol XDR. Examples of changes (in the form of extensions) to the protocol XDR. Examples of
other sorts of changes have been taken from NFSv4.1. other sorts of changes have been taken from NFSv4.1.
5.1.1. Field Interpretation and Use 5.1.1. Field Interpretation and Use
The XDR description of a protocol does not constitute a complete The XDR description of a protocol does not constitute a complete
description of the protocol. Therefore, versioning needs to consider description of the protocol. Therefore, versioning needs to consider
the role of changes in the use of fields, even when there is no the role of changes in the use of fields, even when there is no
change to the underlying XDR. change to the underlying XDR.
Although any XDR element is potentially subject to a change in its Although any XDR element is potentially subject to a change in its
interpretation and use, the likelihood of such change will vary with interpretation and use, the likelihood of such change will vary with
the XDR type, as discussed below:. the XDR-specified type of the element, as discussed below:
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 which 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 10.3.1. Section 8.3.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 which versioning
rules need to deal with. rules need to deal with.
skipping to change at page 21, line 6 skipping to change at page 21, line 45
5.1.3. Rules for non-XDR changes 5.1.3. Rules for non-XDR changes
In the past (e.g. in [RFC5661]) there was often uncertainty about In the past (e.g. in [RFC5661]) there was often uncertainty about
whether any particular difference from NFSv4.0 was: whether any particular difference from NFSv4.0 was:
o A purely editorial change, which may be relevant to other minor o A purely editorial change, which may be relevant to other minor
versions. versions.
o The correction of a protocol mistake, best handled as described in o The correction of a protocol mistake, best handled as described in
Section 11. Section 9.
o A protocol improvement relevant to a new minor version or feature, o A protocol improvement relevant to a new minor version or feature,
to be documented as described in Section 7.3. to be documented as described in Section 10.3.
In order to avoid such situations, all such changes will be In order to avoid such situations, all such changes will be
documented as part of a feature, specifying the specific changes documented as part of a feature, specifying the specific changes
relative to protocol versions that do not incorporate that new relative to protocol versions that do not incorporate that new
feature. Also, to provide greater clarity about such changes, the feature. Also, to provide greater clarity about such changes, the
following sets of rules apply. following sets of rules apply.
The following rules apply to "substantive behavior changes", i.e. The following rules apply to "substantive behavior changes", i.e.
all changes in which there is a substantive change to non-error all changes in which there is a substantive change to non-error
behavior. In other words, the change is not one which only changes behavior. In other words, the change is not one which only changes
skipping to change at page 22, line 18 skipping to change at page 23, line 10
pNFS is structured around the ability to define alternative mapping pNFS is structured around the ability to define alternative mapping
types in addition to the one defined in [RFC5661], (e.g. [RFC5663], types in addition to the one defined in [RFC5661], (e.g. [RFC5663],
[RFC5664]). Each mapping type specifies the data-transfer protocol [RFC5664]). Each mapping type specifies the data-transfer protocol
to be used to access data represented by layouts as well as mapping- to be used to access data represented by layouts as well as mapping-
type-specific XDR definitions of layout-related data structures. type-specific XDR definitions of layout-related data structures.
Specifying a new mapping type is an additional form of protocol Specifying a new mapping type is an additional form of protocol
change within the NFSv4 version management framework. A feature change within the NFSv4 version management framework. A feature
consisting of the new mapping type is not tied to a specific minor consisting of the new mapping type is not tied to a specific minor
version. As explained in Section 8, if a feature consists only of version. As explained in Section 7, if a feature consists only of
that single change, it is available in multiple minor versions upon that single change, it is available in multiple minor versions upon
publication. publication.
Such a feature has a file system scope and the attribute Such a feature has a file system scope and the attribute
fs_layout_type can used to determine whether support is present. fs_layout_type can used to determine whether support is present.
5.2.2. Additional Forms of Associated Protocols 5.2.2. Additional Forms of Associated Protocols
The same sort of approach used for pNFS might be used in other The same sort of approach used for pNFS might be used in other
circumstances where there is a clear need to standardize a set of circumstances where there is a clear need to standardize a set of
skipping to change at page 24, line 6 skipping to change at page 24, line 48
extensions and other changes must be supported together. extensions and other changes must be supported together.
o help the client determine which particular changes are present and o help the client determine which particular changes are present and
implemented by the server. implemented by the server.
o support the independent development and specification of changes o support the independent development and specification of changes
to the protocol, without artificially tying features together in a to the protocol, without artificially tying features together in a
paradigm solely based on minor versions. paradigm solely based on minor versions.
o provide support for a feature-based documentation structure, as o provide support for a feature-based documentation structure, as
described in Section 7.3. described in Section 10.3.
In contrast with some previous uses of the feature concept, every In contrast with some previous uses of the feature concept, every
protocol element is defined as a member of exactly one protocol protocol element is defined as a member of exactly one protocol
feature. feature.
Because support for particular protocol features may depend on Because support for particular protocol features may depend on
facilities provided by the underlying file systems, or may vary based facilities provided by the underlying file systems, or may vary based
on characteristics of the session within which communication is on characteristics of the session within which communication is
occurring, each protocol feature will be defined as having a occurring, each protocol feature will be defined as having a
particular scope, which may be any of the following: particular scope, which may be any of the following:
o Client scope in which case support for a given feature is assumed o Client scope in which case support for a given feature is assumed
to be uniform between given client and server as long as neither to be uniform between given client and server as long as neither
reboots. reboots.
o Session scope in which case different sessions associated with the o Session scope in which case different sessions associated with the
same client may have difference as to feature support but same client may have differences as to feature support but
otherwise support is uniform. otherwise support is uniform.
o file system scope in which case different file systems may have o file system scope in which case different file systems may have
differences as to feature support but otherwise support is differences as to feature support but otherwise support is
uniform. uniform.
6.1. Previous Uses of the Feature Concept 6.1. Previous Uses of the Feature Concept
The word "feature" has been used inconsistently in previous documents The word "feature" has been used inconsistently in previous documents
bearing on issues related NFSv4 versioning, making it necessary to bearing on issues related NFSv4 versioning, making it necessary to
offer some clarification here. offer some clarification here.
o In some cases, the term "feature" is used colloquially o In some cases, the term "feature" is used colloquially
o In some cases, the word "feature" is used to refer to protocol o In some cases, the word "feature" is used to refer to protocol
extensions which are incorporated in the protocol are referred to extensions which are incorporated in the protocol that we refer to
as "protocol elements." The term "feature elements" is similar as "protocol elements." The term "feature elements" is similar
but it differs in that it includes changes in field interpretation but it differs in that it includes changes in field interpretation
and use (Section 5.1.1) and protocol behavior (See Section 5.1.2). and use (Section 5.1.1) and protocol behavior (See Section 5.1.2).
o In some cases the word is used to refer to groups of feature o In some cases the word is used to refer to groups of feature
elements, as defined by tables in [RFC5661] and [NFSv42]. This is elements, as defined by tables in [RFC5661] and [NFSv42]. This is
similar to, but not exactly the same as the way we use the word similar to, but not exactly the same as the way we use the word
"feature" is used in this document. "feature" is used in this document.
Often, as in previous minor versioning rules it is not always clear Often, as in previous minor versioning rules, it is not always clear
which sense of the word "feature" is meant. which sense of the word "feature" is meant.
6.2. Rules for Protocol Feature Construction 6.2. Rules for Protocol Feature Construction
A protocol feature consists of one or more valid NFSv4 changes, which A protocol feature consists of one or more valid NFSv4 changes, which
work together as a functional whole. The change elements may be of work together as a functional whole. The change elements may be of
any of the types described in Section 5 although the specific types any of the types described in Section 5 although the specific types
of changes will affect how the feature can be integrated in the NFSv4 of changes will affect how the feature can be integrated in the NFSv4
protocol. protocol.
A critical distinction in this regard is the one between features A critical distinction in this regard is the one between features
which can added to the protocol without a new minor version and those which can added to the protocol without a new minor version and those
which require a new minor version. In this document: which require a new minor version. In this document:
o Features which do not require a new minor version are discussed in o Features which do not require a new minor version are discussed in
Section 8, while the process of incorporation depends on the type Section 7, while the process of incorporation depends on the type
of features and is discussed in Sections 9, 11, 5.2.1, and 5.2.2, of features and is discussed in Sections 7.1, 9, 5.2.1, and 5.2.2,
o For handling of the remaining features which do require a new o For handling of the remaining features which do require a new
minor version, see Section 10. minor version, see Section 8.
6.3. Statuses of Features 6.3. Statuses of Features
Each feature has one of three statuses with regard to each minor Each feature has one of three statuses with regard to each minor
version of which it might be a part. version of which it might be a part.
o The feature is a REQUIRED part of the minor version. o The feature is a REQUIRED part of the minor version.
o The feature is not a REQUIRED part of the minor version, but may o The feature is not a REQUIRED part of the minor version, but may
be implemented as part of that version, i.e. it is OPTIONAL be implemented as part of that version, i.e. it is OPTIONAL
o The feature is not a valid part of the minor version. o The feature is not a valid part of the minor version.
For features which have been previously defined as valid, this is For features which have been previously defined as valid, this is
represented as being "mandatory to not implement" as opposed to represented as being "mandatory to not implement" as opposed to
simply being undefined. simply not being undefined.
These statuses define whether a client implementing the minor version These statuses define whether a client implementing the minor version
has to be prepared for the protocol feature's non-support by a server has to be prepared for the protocol feature's non-support by a server
implementation, even if the feature in question is known by the implementation, even if the feature in question is known by the
server. server.
The working group is still free to make recommendations regarding the The working group is still free to make recommendations regarding the
desirability of server and client support for particular features in desirability of server and client support for particular features in
particular minor versions in the minor version definition document, particular minor versions in the minor version definition document,
or in other, presumably informational, documents. or in other, presumably informational, documents.
skipping to change at page 26, line 30 skipping to change at page 27, line 22
based on support for the protocol element. This is referred to as based on support for the protocol element. This is referred to as
the protocol element's E-to-F status. the protocol element's E-to-F status.
o A status value that allows support for the feature element to be o A status value that allows support for the feature element to be
inferred based on support for the feature. This is referred to as inferred based on support for the feature. This is referred to as
the protocol element's F-to-E status with regard to the feature. the protocol element's F-to-E status with regard to the feature.
The purpose of defining these status values is to allow the support The purpose of defining these status values is to allow the support
or non-support for one protocol elements to be determined based on or non-support for one protocol elements to be determined based on
responses for others, avoiding the complexity that a client would responses for others, avoiding the complexity that a client would
have to deal with if each such support decision were independent. have to deal with if each such support decision were independent. A
The simpler model of simply assigning protocol elements to feature- simpler model would have been to simply assign protocol elements to
based equivalence was not adopted since it is not compatible with feature-based support equivalence classes and require all protocol
many current and expected feature patterns: elements in a feature to be supported or not supported together.
This approach was not adopted because it is not compatible with many
current and expected feature patterns:
o Many existing protocol features contain protocol elements that are o Many existing protocol features contain protocol elements that are
optional in the context of the feature. optional in the context of the feature.
o Some existing protocol elements are used by more than one feature. o Some existing protocol elements are used by more than one feature.
o Boolean attributes that indicate the presence of support for a o Boolean attributes that indicate the presence of support for a
given feature are tied to that feature, even though the attribute given feature are tied to that feature, even though the attribute
can be supported when he feature is not, in which case the can be supported when the feature is not, in which case the
attribute is supported and has the value FALSE. attribute is supported and has the value FALSE.
The following are possible E-to-F statuses. The following are possible E-to-F statuses.
o Support or non-support for the feature is always the same as that o Support or non-support for the feature is always the same as that
for the protocol element. This is represented as an "IFF" value. for the protocol element. This is represented as an "IFF" value.
o Support for the feature can be inferred from support for the o Support for the feature can be inferred from support for the
protocol element but not necessarily the reverse. This is protocol element but not necessarily the reverse. This is
represented as an "SINF" value. represented as an "SINF" value.
skipping to change at page 28, line 34 skipping to change at page 29, line 25
o If the protocol element is an operation, the operation can be o If the protocol element is an operation, the operation can be
attempted, with an error of NFS4ERR_NOTSUPP indicating the attempted, with an error of NFS4ERR_NOTSUPP indicating the
operation is known but not supported. operation is known but not supported.
o If the protocol element is a switch case, use of that case can be o If the protocol element is a switch case, use of that case can be
attempted, with an error of NFS4ERR_UNION_NOTSUPP indicating t the attempted, with an error of NFS4ERR_UNION_NOTSUPP indicating t the
operation is known but not supported. operation is known but not supported.
o If the protocol element is an operation flag bit and the operation o If the protocol element is an operation flag bit and the operation
is REQUIRED, use if that flag bit can be attempted with an error is REQUIRED, use of that flag bit can be attempted with an error
of NFS4ERR_UNION_NOTSUPP indicating the operation is known but not of NFS4ERR_NOTSUPP indicating the protocol element is known but
supported. not supported.
o If the protocol element is an operation flag bit and the operation o If the protocol element is an operation flag bit and the operation
defines an error to return in the case of unsupported flag bits, defines an error to return in the case of unsupported flag bits,
use if that flag bit can be attempted with the specified error use if that flag bit can be attempted with the specified error
indicating the operation is known but not supported. indicating the operation is known but not supported.
Once this is done, all of the protocol elements the client is aware Once this is done, all of the protocol elements the client is aware
of can be divided into three sets: of can be divided into three sets:
o Those that the server is unaware of and thus cannot support. o Those that the server is unaware of and thus cannot support.
skipping to change at page 31, line 5 skipping to change at page 31, line 42
at least one supported feature, it can be assumed that support is at least one supported feature, it can be assumed that support is
present. present.
o For other protocol elements which have an F-to-E status of o For other protocol elements which have an F-to-E status of
OPTIONAL for at least one supported feature, support needs to be OPTIONAL for at least one supported feature, support needs to be
tested for as described in Section 6.5. tested for as described in Section 6.5.
o For the remaining protocol elements, it can be assumed that o For the remaining protocol elements, it can be assumed that
support is not present. support is not present.
7. Documentation of Protocol Changes 6.7. Feature Incorporation
As mentioned previously, NFSv4 is evolving towards a finer-grained
documentation model. The use of extensions within minor versions
will continue this trend.
7.1. Documentation Approach
Documentation of future changes to the NFSv4 protocol will use
feature specification documents as described in Section 7.3. There
are a number of ways in which such documents may be used, as
discussed in Section 7.4
The documentation approach is intended to avoid the unnecessary
production of large documents in which many unrelated features are
tied together because either:
o The entire protocol is described in a single document, as happened
with NFSv4.0 (in [RFC7530]) and NFSv4.1 (in [RFC5661]).
o Many unrelated features are described in a single document as
occurred with NFSv4.2 (in [NFSv42]).
The production of a larger number of smaller documents will
streamline document production and review. A potential problem is
that a profusion of smaller documents might cause difficulty for
those learning about and implementing the protocol.
The production of indexing material described in Section 7.2 is
intended to limit such difficulties. The result will be that, for
operations and attributes, we will have essentially a single table of
contents, referencing material from multiple minor version definition
documents and feature specification documents.
7.2. Indexing material
The following items, referred to collectively as "Indexing material"
will be useful in many contexts. The reason for frequently
publishing such material is to prevent a situation in which large
numbers of documents must be scanned to find the most current
description of a particular protocol element.
o A table mapping operations and callbacks to the most recent
protocol definition document containing a description of that
operation.
o A table mapping attributes to the most recent protocol definition
document containing a description of that attribute.
o A table giving, for each operation in the protocol, the errors
that may validly be returned for that operation. If possible, it
would be desirable to give, as does [RFC5661], the operations
which may validly return each particular error.
o A table giving for each operation, callback, and attribute and for
each feature element in a published extension giving its status
(REQUIRED, OPTIONAL, or mandatory-to-not implement), the name of
the feature of which it is a part, its associated E-to-F and
F-to-E status values and information about other features for
which it has a non-empty F-to-E status value. This would be
similar to the material in Section 14 of [NFSv42], expanded to
include all feature elements.
7.3. Feature Specification Documents
Features will be documented in the form of a working-group standards-
track document which define one or more features. Generally, only
closely related features should be defined in the same document.
The definition of each of the new features may include one or more
"feature elements" which change the protocol in any of the ways
discussed in Section 5. Feature elements include new operations,
attributes, and enumeration values. Note that in this context,
"Operations" include both forward and callback operations. The
functionality of some existing operations may be extended by the
addition of new flags bits in existing flag words, by new cases in
existing switched unions, and by valid semantic changes to existing
operations.
Such feature definition documents would contain a number of items,
following the pattern of the NFSv4.2 specification. The only
difference would be that while the NFSv4.2 specification defines a
number of features to be incorporated into NFSv4.2, the feature
definition documents would each define a single feature, or a small
set of closely related features.
In addition to a general explanation of the feature(s) in question,
the items to be included in such feature definition documents would
be as listed below. In some cases these items, in addition to
descriptive text, would contain fragments of XDR code, to aid in
preparation of XDR files that include the additions defined by the
feature added to the base protocol that is being extended. For
information regarding preparation of such XDR files, see Section 7.5.
o Description of new operations (corresponding to Sections 15 and 16
of [NFSv42]). Such descriptions will contain XDR code defining
the structure the arguments and results of the new operation along
with preparatory XDR definitions used only by that operation.
o Description of any modified operations (corresponding to
Section 15 of [NFSv42]). Such description may contain XDR code
defining the new flag bits, enum values, and cases to be added to
existing switched unions. Note that addition of new attributes is
not considered an extension of GETATTR, SETATTR, VERIFY, or
NVERIFY.
o Description of new attributes (corresponding to Section 13 of
[NFSv42]). XDR code defining the types of the attributes would be
part of this description.
o Description of any added error codes (corresponding to
Section 12.1 of [NFSv42]).
o All operation descriptions, whether for new or modified
operations, should indicate when operations or the corresponding
results may be presented as RDMA chunks.
o A set of XDR code fragments giving the numeric values of added
operation codes, attribute numbers, and error codes.
o Descriptions of all other extensions made to existing flag words,
enums and switched unions used by existing operations. Such
descriptions will contain XDR code defining the new flag bits,
enum values, and cases to be added to existing switched unions.
o Descriptions of all added of new structures, enums, flag words,
and switched unions that are used by more than one new operation,
or which are available for future use by multiple operations.
Such descriptions will contain XDR code defining the new
structures/union and assigning the new numeric values for enum and
flag bits.
o A listing giving the valid errors for each new operation and
callback (corresponds to Sections 12.2 and 12.3 of [NFSv42]).
o For each feature, a table giving for each feature element that is
part of the feature, its overall status within the minor version
and its E-to-F and F-to-E status values. This would be similar to
the material in Section 14 of [NFSv42] but restricted to the
feature(s) defined in the document and expanded to include all
feature elements.
o A table presenting support requirement for each protocol element
which is either a part of a feature defined in the document or has
an F-to-E status with relation with a feature defined in the
document. This could present the F-to-E status value for each
relevant combination of feature element and feature. An
alternative presentation would give, for each protocol element, a
boolean expression in term of supported feature, that allow and
guarantee support for the specified element.
o All of the additional Sections required for RFC publication, such
as "Security Considerations", "IANA considerations", etc.
Note that the listing above is not intended to define, in detail, the
structure of the specification. Rather, the intention is to define
the things it needs to contain. If there would be no content for a
particular element, there is no need for an empty section
corresponding to that list element. If it makes more sense to
describe a new structure together with an extended one, then the need
for a readily understandable document is primary.
7.4. Feature Incorporation
All protocol changes will be organized, documented and effected as All protocol changes will be organized, documented and effected as
part of a given feature. This includes XDR extension and the various part of a given feature. This includes XDR extension and the various
sorts of non-XDR-based changes allowed. sorts of non-XDR-based changes allowed.
Such features may be made part of the protocol in a number of ways: Such features may be made part of the protocol in a number of ways:
o In new minor versions, as discussed in Section 10. o In new minor versions, as discussed in Section 8.
o In separately documented new features. When new features are o In separately documented new features. When new features are
OPTIONAL and do not include any non-XDR-based changes, they may be OPTIONAL and do not include any non-XDR-based changes, they may be
incorporated in an extensible minor version under construction. incorporated in an extensible minor version under construction.
See Section 9 for details. See Section 7.1 for details.
o When appropriate compatibility arrangement are in effect, they may o When appropriate compatibility arrangement are in effect, they may
be used to correct protocol problems in already approved minor be used to correct protocol problems in already approved minor
versions and features. See Section 11 for details. versions and features. See Section 9 for details.
7.5. XDR File Considerations
As mentioned previously, feature specification documents will
contain, in addition to description of XDR extensions, XDR code
fragments that embody those extensions. There will be various
occasions on which people will have occasion to produce XDR files
that combine one or more extensions together with the XDR for an
existing minor version.
o When a minor version is specified by a number of feature
specification documents, there will be a need to produce, in as
simple fashion as possible, the corresponding XDR specification
document for the new minor version.
o Within an extensible minor version, there will be a need for those
developing and testing the feature to have an XDR file that
incorporates XDR definitions from early drafts of the feature
specification document.
o Also, for an extensible minor version, there will be a need to
periodically produce Consolidated XDR documents that reflect all
features approved as Proposed Standards and thus incorporated in
the current minor version.
o Developers may need to be able to produce XDR files that reflect
particular combination of approved features, features under
development or experimental features not yet ready for working
group consideration.
We are assuming here that the primary task is producing XDR files and
that corresponding XDR documents can be produced relatively easily if
there is a well understood process to produce the underlying XDR
files.
The Feature specification document should contain all of the
necessary lines of XDR codes to be added to a base XDR file to effect
the extension. The only remaining issue is where to place each
addition to arrive at the correct consolidated file.
o One could rely on those preparing updated XDR file to place the
additional XDR code lines in the appropriate place, based on
inference from the document text.
o One could rely on the Feature Specification Document to indicate,
in the descriptive text, where each XDR extension is to be placed.
o One could formalize a set of conventions whereby the appropriate
placements are indicated by specific instructions embedded within
comments within the XDR code fragments to be placed.
8. Extensions within Minor Versions 7. Extensions within Minor Versions
The NFSv4 version management framework allows, with certain The NFSv4 version management framework allows, with certain
restrictions, features to be added to existing minor versions restrictions, features to be added to existing minor versions
o In the case of features which consist only of a pNFS mapping type, o In the case of features which consist only of a pNFS mapping type,
the protocol may be extended by publishing the new mapping type the protocol may be extended by publishing the new mapping type
definition as a Proposed Standard. This effects an extension to definition as a Proposed Standard. This effects an extension to
all minor versions in which pNFS is a valid feature. all minor versions in which pNFS is a valid feature.
Similar extension facilities could be made available if additional Similar extension facilities could be made available if additional
pNFS-like extension frameworks were created (See Section 5.2.2). pNFS-like extension frameworks were created (See Section 5.2.2).
o Minor versions designated as extensible (see Section 9) may be o Minor versions designated as extensible (see Section 7.1) may be
extended by the publication of a standards-track document defining extended by the publication of a standards-track document defining
the additional feature. Details are set out in Section 9. The the additional feature. Details are set out below. The features
features to be added are considered OPTIONAL in the extensible to be added are considered OPTIONAL in the extensible minor
minor version and must consist only of valid XDR-based extensions version and must consist only of valid XDR-based extensions
9. Adding Features to Extensible Minor Versions 7.1. Adding Features to Extensible Minor Versions
Addition of features to an extensible minor version will take Addition of features to an extensible minor version will take
advantage of the existing NFSv4 infrastructure that allows optional advantage of the existing NFSv4 infrastructure that allows optional
features to be added to new minor versions, but without in this case features to be added to new minor versions, but without in this case
requiring any change in the minor version number. Adding features in requiring any change in the minor version number. Adding features in
this way will enable compatibility with existing clients and servers, this way will enable compatibility with existing clients and servers,
who may be unaware of the new feature. who may be unaware of the new feature.
9.1. Use of Feature Specification Documents 7.2. Use of Feature Specification Documents
Each such extension will be in the form of a working-group standards- Each such extension will be in the form of a working-group standards-
track document which defines one or more new OPTIONAL features. The track document which defines one or more new OPTIONAL features. The
definition of each of the new feature may include one or more definition of each of the new feature may include one or more
"protocol elements" which extend the existing XDR as already "protocol elements" which extend the existing XDR as already
discussed (in Section 4.1). Other sorts of XDR modification are not discussed (in Section 4.1). Other sorts of XDR modification are not
allowed. Protocol elements include new operations, callbacks, allowed. Protocol elements include new operations, callbacks,
attributes, and enumeration values. The functionality of some attributes, and enumeration values. The functionality of some
existing operations may be extended by the addition of new flags bits existing operations may be extended by the addition of new flags bits
in existing flag words and new cases in existing switched unions. in existing flag words and new cases in existing switched unions.
skipping to change at page 36, line 34 skipping to change at page 33, line 4
Each such extension will be in the form of a working-group standards- Each such extension will be in the form of a working-group standards-
track document which defines one or more new OPTIONAL features. The track document which defines one or more new OPTIONAL features. The
definition of each of the new feature may include one or more definition of each of the new feature may include one or more
"protocol elements" which extend the existing XDR as already "protocol elements" which extend the existing XDR as already
discussed (in Section 4.1). Other sorts of XDR modification are not discussed (in Section 4.1). Other sorts of XDR modification are not
allowed. Protocol elements include new operations, callbacks, allowed. Protocol elements include new operations, callbacks,
attributes, and enumeration values. The functionality of some attributes, and enumeration values. The functionality of some
existing operations may be extended by the addition of new flags bits existing operations may be extended by the addition of new flags bits
in existing flag words and new cases in existing switched unions. in existing flag words and new cases in existing switched unions.
New error codes may be added but the set of valid error codes to be New error codes may be added but the set of valid error codes to be
returned by an operation is fixed, except that existing operations returned by an operation is fixed, except that existing operations
may return new errors to respond to situations that only arise when may return new errors to respond to situations that only arise when
previously unused flag bits are set or when extensions to a switched previously unused flag bits are set or when extensions to a switched
union are used. union are used.
Also, certain additional documents may be produced at this time to
simplify the process of using new versions that contain the
extension, and to help co-ordinate the process of making further
extensions. See Section 10.5 for details.
Each such additional feature will become, for all intents and Each such additional feature will become, for all intents and
purposes, part of the current NFSv4 minor version upon publication of purposes, part of the current NFSv4 minor version upon publication of
the description as a Proposed Standard, enabling such extensions to the description as a Proposed Standard, enabling such extensions to
be used by new client and server implementations without, as be used by new client and server implementations without, as
previously required, a change in the value of the minor version field previously required, a change in the value of the minor version field
within the COMPOUND operation. within the COMPOUND operation.
The working group has two occasions to make sure that such features The working group has two occasions to make sure that such features
are appropriate ones: are appropriate ones:
skipping to change at page 37, line 16 skipping to change at page 33, line 41
to existing operations) associated with the new feature are to existing operations) associated with the new feature are
complete and do not conflict with those in the existing protocol complete and do not conflict with those in the existing protocol
or those currently under development. or those currently under development.
o At the time the working group document is complete, the working o At the time the working group document is complete, the working
group, in addition to normal document review, can and should look group, in addition to normal document review, can and should look
at what prototype implementations of the feature have been done at what prototype implementations of the feature have been done
and use that information to determine the work-ability and and use that information to determine the work-ability and
maturity of the feature. maturity of the feature.
9.2. Compatibility Issues 7.3. Compatibility Issues
Because the receiver of a message may be unaware of the existence of Because the receiver of a message may be unaware of the existence of
a specific extension, certain compatibility rules need to be a specific extension, certain compatibility rules need to be
observed. In some cases (e.g., addition of new operations or observed. In some cases (e.g., addition of new operations or
callbacks or addition of new arms to an existing switched union) callbacks or addition of new arms to an existing switched union)
older clients or servers may be unable to do XDR parsing on an older clients or servers may be unable to do XDR parsing on an
extension of whose existence they are unaware. In other cases (e.g., extension of whose existence they are unaware. In other cases (e.g.,
error returns) there are no XDR parsing issues but existing clients error returns) there are no XDR parsing issues but existing clients
and servers may have expectations as to what may validly be returned. and servers may have expectations as to what may validly be returned.
Detailed discussion of these compatibility issues appears below: Detailed discussion of these compatibility issues appears below:
o Issues related to messages sent to the server are discussed in o Issues related to messages sent to the server are discussed in
Section 9.2.1. Section 7.3.1.
o Issues related to messages sent to the client are discussed in o Issues related to messages sent to the client are discussed in
Section 9.2.2. Section 7.3.2.
9.2.1. Compatibility Issues for Messages Sent to Servers 7.3.1. Compatibility Issues for Messages Sent to Servers
This section deals with compatibility issues that relate to messages This section deals with compatibility issues that relate to messages
sent to the server, i.e., requests and replies to callbacks. In the sent to the server, i.e., requests and replies to callbacks. In the
case of requests, it is the responsibility of the client to determine case of requests, it is the responsibility of the client to determine
whether the server supports the extension in question before sending whether the server supports the extension in question before sending
a request containing it for any purpose other than determining a request containing it for any purpose other than determining
whether the server is aware of the extension. In the case of whether the server is aware of the extension. In the case of
callback replies, the server demonstrates its awareness of proper callback replies, the server demonstrates its awareness of proper
parsing for callback replies by sending the associated callback. parsing for callback replies by sending the associated callback.
skipping to change at page 38, line 35 skipping to change at page 35, line 12
o Error values returned to the server for all callbacks that do not o Error values returned to the server for all callbacks that do not
use new features will only be those previously allowed. Only when use new features will only be those previously allowed. Only when
the server uses a new extension feature can a previously invalid the server uses a new extension feature can a previously invalid
error value be returned. error value be returned.
o Callback replies may only include a new arm of an existing o Callback replies may only include a new arm of an existing
switched union when the server, typically in the callback being switched union when the server, typically in the callback being
responded to, has used a feature element associated with the responded to, has used a feature element associated with the
feature that defined the new switched union arm. feature that defined the new switched union arm.
9.2.2. Compatibility Issues for Messages Sent to Clients 7.3.2. Compatibility Issues for Messages Sent to Clients
This sections deals with compatibility issues that relate to messages This sections deals with compatibility issues that relate to messages
sent to clients, i.e., request replies and callbacks. In both cases, sent to clients, i.e., request replies and callbacks. In both cases,
extensions are only sent to clients that have demonstrated awareness extensions are only sent to clients that have demonstrated awareness
of the extensions in question by using an extension associated with of the extensions in question by using an extension associated with
the same feature. the same feature.
Regarding the handling of request replies: Regarding the handling of request replies:
o Error values returned to the client for all requests that do not o Error values returned to the client for all requests that do not
skipping to change at page 39, line 31 skipping to change at page 36, line 8
callbacks that are part of the extension. For example, a flag bit callbacks that are part of the extension. For example, a flag bit
in the EXCHANGE_ID request may serve this purpose. in the EXCHANGE_ID request may serve this purpose.
o In both of the above cases, the ability to accept and parse the o In both of the above cases, the ability to accept and parse the
specified callback is considered separate from support for the specified callback is considered separate from support for the
callback. The feature specification will indicate whether support callback. The feature specification will indicate whether support
for the callback is required whenever the feature is used by the for the callback is required whenever the feature is used by the
client. In cases in which support is not required, the client is client. In cases in which support is not required, the client is
free to return NFS4ERR_NOTSUPP upon receiving the callback. free to return NFS4ERR_NOTSUPP upon receiving the callback.
9.3. Additional Documents to be Produced 7.4. Relationship Between Minor Versioning and Extensions within a
Additional documents will be required from time to time. These
documents will eventually become RFC's (informational or standards
track as described below), but the work of the working group and of
implementers developing features will be facilitated by a progression
of document drafts that incorporate information about new features
that are being developed or have been approved as Proposed Standards.
9.3.1. Minor Version Indexing Document
One document will organize existing material for a minor version
undergoing extension so that implementers will not have to scan a
large set of feature definition documents or minor version
specifications to find information being sought. Successive drafts
of this document will serve as an index to the current state of the
extensible minor version. Some desirable elements of this indexing
document would include:
o A list of all feature definition documents that have been approved
as working group documents but have not yet been approved as
Proposed Standards.
o All of the items of indexing material (see Section 7.2)
appropriately adjusted to reflect the contents of all extensions
accepted as Proposed Standards.
The frequency of updates for this document will be affected by
implementer needs and the ability to easily generate document drafts,
preferably by automated means. The most desirable situation is one
in which a new draft is available soon after each feature reaches the
status of a Proposed Standard.
9.3.2. Consolidated XDR Document
This document will consist of an updated XDR for the protocol as a
whole including feature elements from all features and minor versions
accepted as Proposed Standards.
A new draft should be prepared whenever a new feature within an
extensible minor version is accepted as a Proposed Standard. In most
cases, feature developers will be using a suitable XDR which can then
be reviewed and published. In cases in which multiple features reach
Proposed Standard status at approximately the same time, a merge of
the XDR changes made by each feature may be necessary.
9.3.3. XDR Assignment Document
This document will contain consolidated lists of XDR value
assignments that are relevant to the protocol extension process. It
should contain lists of assignments for:
o operation codes (separate lists for forward operations and for
callbacks)
o attribute numbers
o error codes
o bits within flag words that have been extended since they were
first introduced.
o enumeration values for enumerations which have been extended since
they were first introduced.
For each set of assignments, the individual assignments may be of
three types:
1. permanent assignments associated with a minor version or a
feature extension that has achieved Proposed Standard status.
These assignments are permanent in that the assigned value will
never be re-used. However, a subsequent minor version may define
some or all feature elements associated with a feature to be
mandatory to not implement.
2. provisional assignments associated with a feature under
development (i.e., one which has been approved as a working group
document but has not been approved as a Proposed Standard).
Provisional assignments are not are not permanent and the values
assigned can be re-used in certain circumstances. In particular,
when a feature with provisional assignments is not progressing
toward the goal of eventual Proposed Standard status, the working
group can judge the feature effort to have been abandoned,
allowing the codes formerly provisionally allocated to be
reclaimed and reassigned.
3. definition of individual assignments or ranges reserved for
experimental use.
A new draft of this document should be produced, whenever:
o A minor version or feature specification is accepted as a Proposed
Standard.
o A new feature is accepted for development and a draft of the
corresponding working-group standards-track document is produced
o A feature previously accepted for development is abandoned.
o The working group decides to make some change in assignments for
experimental use.
9.3.4. Transition of Documents to RFC's
Each of these documents should be published as an RFC soon after the
minor version in question ceases to be considered extensible.
Typically this will happen when the working group makes the
specification for the subsequent minor version into a working group
document. Some specifics about the individual documents are listed
below:
o The most current draft of the indexing document for the minor
version would be published as an informational RFC.
o The most current draft of the consolidated XDR document should be
published as a standards-track RFC. It would update the initial
specification of the minor version
o The most recent draft of the XDR assignment document should be
published as an informational RFC.
Handling of these documents in the event of a post-approval XDR
correction is discussed in Section 11.2
9.4. Relationship Between Minor Versioning and Extensions within a
Minor Version Minor Version
Extensibility of minor versions are governed by the following rules: Extensibility of minor versions are governed by the following rules:
o Minor versions zero and one are not extensible. Each has a fixed o Minor versions zero and one are not extensible. Each has a fixed
set of OPTIONAL features as described in [RFC7530] and [RFC5661]. set of OPTIONAL features as described in [RFC7530] and [RFC5661].
o Minor versions beyond one are presumed extensible as discussed o Minor versions beyond one are presumed extensible as discussed
herein. However, any statement within the minor version herein. However, any statement within the minor version
specification disallowing extension will cause that minor version specification disallowing extension will cause that minor version
to be considered non-extensible. to be considered non-extensible.
o No new feature may be added to a minor version once the o No new feature may be added to a minor version once the
specification document for a subsequent minor version becomes a specification document for a subsequent minor version becomes a
working group standards-track document. working group standards-track document.
Even when a minor version is non-extensible, or when a previous minor Even when a minor version is non-extensible, or when a previous minor
version is closed to further extension, the features that it contains version is closed to further extension, the features that it contains
are still subject to updates to effect protocol corrections. In many are still subject to updates to effect protocol corrections. In many
cases, making an XDR change, in the form of an extension will be the cases, making an XDR change, in the form of an extension will be the
best way of correcting an issue. See Section 11 for details. best way of correcting an issue. See Section 9 for details.
While making minor versions extensible will decrease the frequency of While making minor versions extensible will decrease the frequency of
new minor versions, it will not eliminate the need for them. new minor versions, it will not eliminate the need for them.
Protocol features that cannot be used as extensions (see Protocol features that cannot be used as extensions (see
Section 10.1.1 require a new minor version. Section 8.1.1 require a new minor version.
In addition, change which involve modifications to the set of In addition, change which involve modifications to the set of
protocol elements which are REQUIRED or mandatory to not implement protocol elements which are REQUIRED or mandatory to not implement
require a new minor version which starts a new minor version group. require a new minor version which starts a new minor version group.
Changes to the organization of protocol features are treated Changes to the organization of protocol features are treated
similarly, since they have a similar potential to cause interversion similarly, since they have a similar potential to cause interversion
incompatibility. See Section 10.1.2 for details. incompatibility. See Section 8.1.2 for details.
10. Minor Versions 8. Minor Versions
10.1. Reasons for New Minor Versions 8.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 or minor version groups to be that would require new minor versions or minor version groups to be
created, does not thereby imply that situations will exist in the created, does not thereby imply that situations will exist in the
future. Judgments regarding desirability of future changes will be future. Judgments regarding desirability of future changes will be
made by the working group or its successors and any guidance that can made by the working group or its successors and any guidance that can
be offered at this point is necessarily quite limited. be offered at this point is necessarily quite limited.
Creation of a new minor version or minor version group is an option Creation of a new minor version or minor version group is an option
that the working group retains. The listing of situations below that that the working group retains. The listing of situations below that
would prompt such actions is not meant to be exhaustive. would prompt such actions is not meant to be exhaustive.
10.1.1. New Minor Versions within an Existing Group New minor versions are to be documented as described in Section 10.6.
8.1.1. New Minor Versions within an Existing Group
The following sorts of features are not allowed as extensions and The following sorts of features are not allowed as extensions and
would require creation of a new minor version: would require creation of a new minor version:
o Features that incorporate any of the non-XDR-based changes o Features that incorporate any of the non-XDR-based changes
discussed in Sections 5.1.1 and 5.1.2. discussed in Sections 5.1.1 and 5.1.2.
o Any feature which includes a new mapping type (as described in o Any feature which includes a new mapping type (as described in
Section 5.2.1) and includes any other change. Section 5.2.1) and includes any other change.
To prevent new mapping types from evading this restriction by To prevent new mapping types from evading this restriction by
splitting the mapping type and other changes into two separate splitting the mapping type and other changes into two separate
changes, if new mapping type makes a reference to protocol changes changes, if new mapping type makes a reference to protocol changes
in an extension, it may not be incorporated in minor versions in in an extension, it may not be incorporated in minor versions in
which that extension is defined but only in later minor versions. which that extension is defined but only in later minor versions.
o Any feature that creates a new expansion mechanism as described in o Any feature that creates a new expansion mechanism as described in
in Section 5.2.2. in Section 5.2.2.
10.1.2. New Minor Version Groups 8.1.2. New Minor Version Groups
The following sorts of changes can only occur in the context of a new The following sorts of changes can only occur in the context of a new
minor version group: minor version group:
o Addition of REQUIRED new features. o Addition of REQUIRED new features.
o Changes to the status of existing features including converting o Changes to the status of existing features including converting
features to be mandatory to not implement. features to be mandatory to not implement.
o Changes to the status of existing feature elements within o Changes to the status of existing feature elements within
skipping to change at page 44, line 22 skipping to change at page 38, line 17
Changes to the status or organization of features will, in most case, Changes to the status or organization of features will, in most case,
result in changes to the status of individual protocol elements, result in changes to the status of individual protocol elements,
changing them between REQUIRED and OPTIONAL, or making them mandatory changing them between REQUIRED and OPTIONAL, or making them mandatory
to not implement. to not implement.
Conversion of protocol elements to be mandatory to not implement, Conversion of protocol elements to be mandatory to not implement,
will not, as had previously been the practice, result in their will not, as had previously been the practice, result in their
deletion from the protocol XDR. However, the server will be REQUIRED deletion from the protocol XDR. However, the server will be REQUIRED
to treat such protocol elements as not known when responding to to treat such protocol elements as not known when responding to
requests within minor versions in which they are not to be requests within minor versions in which they are not to be
implemented. See Sections 4.4.3 and 10.3.2 for details. implemented. See Sections 4.4.3 and 8.3.2 for details.
Such changes give rise to potential compatibility issues. In most Such changes give rise to potential compatibility issues. In most
cases in which such changes will actually be made, careful cases in which such changes will actually be made, careful
consideration of compatibility issues can limit the scope of consideration of compatibility issues can limit the scope of such
potential compatibility issues or ensure that actual compatibility issues or ensure that compatibility issues actually experienced are
issues are quite limited. quite limited.
This is opposed to the first new minor version group, that associated This is opposed to the first new minor version group, that associated
with minor version one, which resulted in a situation in which with minor version one, which resulted in a situation in which
clients for minor version zero could not interoperate with servers clients for minor version zero could not interoperate with servers
for minor version one and vice versa. Issues related to the question for minor version one and vice versa. Issues related to the question
of what to do about such situations are discussed in Section 10.1.3 of what to do about such situations are discussed in Section 8.1.3
The addition of REQUIRED features may serve to illustrate the issues. The addition of REQUIRED features may serve to illustrate the issues.
Such additions pose no compatibility issue for existing clients. On Such additions pose no compatibility issue for existing clients. On
the other hand, all servers will need to be updated to support the the other hand, all servers will need to be updated to support the
new features. The effort required and any potential for disruption new features. The effort required and any potential for disruption
depend on the scope of the feature being added. depend on the scope of the feature being added.
A number of features introduced as REQUIRED in NFSv4.1 can serve to A number of features introduced as REQUIRED in NFSv4.1 can serve to
illustrate the issues. illustrate the issues.
skipping to change at page 45, line 15 skipping to change at page 39, line 9
Some examples of potential feature status changes may be helpful in Some examples of potential feature status changes may be helpful in
illustrating compatibility issues illustrating compatibility issues
o Converting a REQUIRED feature to be mandatory to not implement o Converting a REQUIRED feature to be mandatory to not implement
poses the greatest level of difficulty from an interoperability poses the greatest level of difficulty from an interoperability
point of view. Clients need to change to use an alternative means point of view. Clients need to change to use an alternative means
of providing the functionality provided by the feature. Existing of providing the functionality provided by the feature. Existing
servers need to be updated, even if there is a replacement feature servers need to be updated, even if there is a replacement feature
available. available.
Such a transition is only possible if the feature in question has Such a transition is only possible without disruption if the
already fallen into disuse. feature in question has already fallen into disuse.
o Converting an OPTIONAL feature to be mandatory to not implement o Converting an OPTIONAL feature to be mandatory to not implement
poses similar difficulties. If clients have ceased to use the poses similar difficulties. If clients have ceased to use the
feature, after they have become aware, formally or informally, feature, after they have become aware, formally or informally,
that it is moribund, the difficulties can be quite limited. that it is moribund, the difficulties can be quite limited.
o Converting a REQUIRED feature to be OPTIONAL poses no difficulty o Converting a REQUIRED feature to be OPTIONAL poses no difficulty
for existing server implementations. It may pose difficulties for for existing server implementations. It may pose difficulties for
clients who have not made preparations for server non-support of clients who have not made preparations for server non-support of
the feature. the feature.
skipping to change at page 46, line 19 skipping to change at page 40, line 15
o If a feature scope is changed to be more fine-grained, the client o If a feature scope is changed to be more fine-grained, the client
has to deal with combinations of support and non-support it has to deal with combinations of support and non-support it
previously had not had to deal with, while the reverse forces the previously had not had to deal with, while the reverse forces the
server to maintain a unity of support it had previously not had server to maintain a unity of support it had previously not had
to. The unlikely case of conversion between session and file to. The unlikely case of conversion between session and file
system scope causes difficulties for both parties. system scope causes difficulties for both parties.
The tradeoff between interoperability issues and desirable changes to The tradeoff between interoperability issues and desirable changes to
the protocol is one for the working group to make. If the decision the protocol is one for the working group to make. If the decision
is made to create a new minor version group, the working group has is made to create a new minor version group, the working group has
decided that absolutely compatibility is not required. Nevertheless, decided that absolute compatibility is not required. Nevertheless,
it should strive to make necessary changes as non-disruptive as it should strive to make necessary changes as non-disruptive as
possible. possible.
10.1.3. Limits on Minor Version Groups 8.1.3. Limits on Minor Version Groups
The guidance that needs to be offered with regard to appropriate The guidance that needs to be offered with regard to appropriate
limits on changes that form new version groups does not appear limits on changes that form new version groups does not appear
reducible to specific rules. reducible to specific rules.
Instead it is appropriate to return to the basic goal of allowing the Instead it is appropriate to return to the basic goal of allowing the
NFSv4 protocol to adapt to future circumstances as they develop. NFSv4 protocol to adapt to future circumstances as they develop.
Although this was not explicitly stated, it seems to be intended that Although this was not explicitly stated, it seems to be intended that
this would not involve generation of essentially a new protocol, even this would not involve generation of an essentially a new protocol,
if that were, in some sense, a better one. even if that were, in some sense, a better one.
So the best way we can address the question of limits on new version So the best way we can address the question of limits on new version
groups is to state that the purpose of the rules in this document, groups is to state that the purpose of the rules in this document,
including the creation of new minor version groups is not the including the creation of new minor version groups is not the
creation of a successor protocol to NFSv4. creation of a successor protocol to NFSv4.
If this or a future working group does find itself defining a new If this or a future working group does find itself defining a new
file access protocol, it would be helpful if proper care were taken file access protocol, it would be helpful if proper care were taken
to retain what is valuable in the intellectual heritage of NFSv4. to retain what is valuable in the intellectual heritage of NFSv4.
Nevertheless, in doing so, it is important not to assume that Nevertheless, in doing so, it is important not to assume that
adherence to the rules in this document, is, in and of itself, a adherence to the rules in this document, is, in and of itself, a
guarantee that the new protocol is thereby a version of NFSv4. guarantee that the new protocol is thereby a version of NFSv4.
In dealing with such a future changed situation, the better option In dealing with such a future changed situation, the better option
would be to face the issue of necessary change forthrightly and would be to face the issue of necessary change forthrightly and
acknowledge that such a large change creates a fundamentally new acknowledge that such a large change creates a fundamentally new
situation. Appropriate responses might include replacing the XDR in situation. Appropriate responses might include replacing the XDR in
whole or in part, using a successor to XDR, or other means. whole or in part, using a successor to XDR, or other means.
10.2. Role of Minor Versions 8.2. Role of Minor Versions
Clearly, the ability to provide protocol extensions without creation Clearly, the ability to provide protocol extensions without creation
of a new minor version, has lessened the role of minor versions in of a new minor version, has lessened the role of minor versions in
extending the NFSv4 protocol to meet future needs. extending the NFSv4 protocol to meet future needs.
We have gone from a situation in which there was a single mechanism, We have gone from a situation in which there was a single mechanism,
creation of a new minor version, to extend the protocol, to a three- creation of a new minor version, to extend the protocol, to a three-
level approach: level approach:
o OPTIONAL features which extend but do not change protocol o OPTIONAL features which extend but do not change protocol
skipping to change at page 47, line 33 skipping to change at page 41, line 33
o Changes which do as the sets of protocol elements which are o Changes which do as the sets of protocol elements which are
REQUIRED and mandatory to not implement are only allowed in a new REQUIRED and mandatory to not implement are only allowed in a new
minor version group. minor version group.
This document does explore the situations that, if they arise, would This document does explore the situations that, if they arise, would
require the creation of new minor versions or version groups. This require the creation of new minor versions or version groups. This
does not imply that such situations will exist or that the working does not imply that such situations will exist or that the working
will choose to address things in that way. Such choices are left for will choose to address things in that way. Such choices are left for
future decision by the working group and the IESG. future decision by the working group and the IESG.
The discussion in Section 10.1.3 raises similar issues. It is The discussion in Section 8.1.3 raises similar issues. It is
possible that situations might arise that would cause NFSv4 possible that situations might arise that would cause NFSv4
development to be done outside the framework established here. development to be done outside the framework established here.
Nevertheless, this does not imply that such situations will arise. Nevertheless, this does not imply that such situations will arise.
10.3. Minor Version Interaction Rules 8.3. Minor Version Interaction Rules
This section addresses issues related to rules #11 and #13 in the This section addresses issues related to rules #11 and #13 in the
minor versioning rules in [RFC5661]. With regard to the supersession minor versioning rules in [RFC5661]. With regard to the supersession
of minor versioning rules, the treatment here overrides that in of minor versioning rules, the treatment here overrides that in
[RFC5661] when either of the potentially interacting minor versions [RFC5661] when either of the potentially interacting minor versions
has not yet been published as a Proposed Standard. has not yet been published as a Proposed Standard.
Note that these rules are the only ones directed to minor version Note that these rules are the only ones directed to minor version
implementers, rather than to those specifying new minor versions. implementers, rather than to those specifying new minor versions.
10.3.1. Minor Version Identifier Transfer Issues 8.3.1. Minor Version Identifier Transfer Issues
Each relationship between a client instance and a server instance, as Each relationship between a client instance and a server instance, as
represented by a clientid, is to be devoted to a single minor represented by a clientid, is to be devoted to a single minor
version. If a server detects that a COMPOUND with an inappropriate version. If a server detects that a COMPOUND with an inappropriate
minor version is being used, it MUST reject the request. In doing minor version is being used, it MUST reject the request. In doing
so, it may return either NFS4ERR_BAD_CLIENTID or so, it may return either NFS4ERR_BAD_CLIENTID or
NFS4RR_MINOR_VERS_MISMATCH. NFS4RR_MINOR_VERS_MISMATCH.
As a result of the above, the client has the assurance that the set As a result of the above, the client has the assurance that the set
of REQUIRED and OPTONAL features will not change within the context of REQUIRED and OPTONAL features will not change within the context
of a single clientid. Server implementations MUST ensure that the of a single clientid. Server implementations MUST ensure that the
set of supported features and protocol elements does not change set of supported features and protocol elements does not change
within such a context. within such a context.
10.3.2. Minor Version Intra-Group Compatibility 8.3.2. Minor Version Intra-Group Compatibility
Within a set of minor versions that belong to the same minor version Within a set of minor versions that belong to the same minor version
group, it is relatively easy for clients and servers to provides the group, it is relatively easy for clients and servers to provides the
needed compatibility by following the following rules. needed compatibility by following the following rules.
o Servers supporting a given minor version MUST support any earlier o Servers supporting a given minor version MUST support any earlier
minor version in the same minor version group and return minor version in the same minor version group and return
appropriate errors for use of protocol elements that were not a appropriate errors for use of protocol elements that were not a
valid part of that earlier minor version. For details see below. valid part of that earlier minor version. For details see below.
skipping to change at page 49, line 16 skipping to change at page 43, line 16
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 which 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 indicated non-support a flag bit) should be error defined as indicated non-support a flag bit) should be
returned. returned.
10.3.3. Minor Version Inter-Group Compatibility 8.3.3. Minor Version Inter-Group Compatibility
It is desirable for client and server implementations to support a It is desirable for client and server implementations to support a
wide range of minor versions. The difficulty of doing so can be wide range of minor versions. The difficulty of doing so can be
affected by choices made by the working group in defining those minor affected by choices made by the working group in defining those minor
versions, and the particulars of the changes made which establish new versions, and the particulars of the changes made which establish new
version groups. version groups.
Options for compatibility are affected by the scale and frequency of Options for compatibility are affected by the scale and frequency of
the changes which require a new minor version group and the working the changes which require a new minor version group and the working
group needs to take needs for inter-group compatibility into account group needs to take needs for inter-group compatibility into account
skipping to change at page 49, line 42 skipping to change at page 43, line 42
used. For details see below. used. For details see below.
o Clients SHOULD deal with an NFS4ERR_MINOR_VERS_MISMATCH error by a o Clients SHOULD deal with an NFS4ERR_MINOR_VERS_MISMATCH error by a
searching for a lower minor version number within the appropriate searching for a lower minor version number within the appropriate
minor version range until it finds one that the server will minor version range until it finds one that the server will
accept. accept.
In some cases, the server needs to behave as a more restricted one In some cases, the server needs to behave as a more restricted one
for an earlier minor version might, despite it having extensions for for an earlier minor version might, despite it having extensions for
protocol elements added in later minor versions. In these cases, the protocol elements added in later minor versions. In these cases, the
errors described in Section 10.3.2 should be returned in this case as errors described in Section 8.3.2 should be returned in this case as
well. well.
In the case in which the earlier version contains protocol elements In the case in which the earlier version contains protocol elements
subsequently made mandatory to not implement, the server needs to subsequently made mandatory to not implement, the server needs to
know of those protocol elements and not return the errors that would know of those protocol elements and not return the errors that would
appropriate if the most up-to-date minor version were used. In cases appropriate if the most up-to-date minor version were used. In cases
in which support for these protocol elements is REQUIRED, support in which support for these protocol elements is REQUIRED, support
will have to be provided by the server and if it cannot do that, it will have to be provided by the server and if it cannot do that, it
MUST return NFS4ERR_MINOR_VERS_MISMATCH for any requests using that MUST return NFS4ERR_MINOR_VERS_MISMATCH for any requests using that
minor version. minor version.
skipping to change at page 50, line 25 skipping to change at page 44, line 25
o Respect the inter-feature constraints specified by the earlier o Respect the inter-feature constraints specified by the earlier
minor version group. minor version group.
o Respect the feature scopes specified by the earlier minor version o Respect the feature scopes specified by the earlier minor version
group. group.
o Support (or not) protocol elements according to the F-to-E o Support (or not) protocol elements according to the F-to-E
statuses specified in the earlier minor version group. statuses specified in the earlier minor version group.
10.4. Minor Version Documentation 9. Correction of Existing Minor Versions and Features
Minor versions should be documented by specifying and explaining the
changes made relative to the previous minor version.
Features added to the minor version should be documented in their own
feature specification documents and normatively referenced.
Changes to the status or organization of existing features should be
documented by presenting a summary of the status of all existing
protocol elements, their relationship to OPTIONAL features, and any
relevant feature dependencies.
In addition, to avoid situation where a large number of minor
versions must be scanned to find the most recent valid treatment of a
specific protocol element, minor version definition documents will
contain the indexing material described in Section 7.2.
11. 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 or existing feature in some way, after the acceptance of that feature 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.
skipping to change at page 51, line 25 skipping to change at page 45, line 7
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 which simply updates the earlier
protocol definition document. Subsequently, the indexing material protocol definition document. Subsequently, the indexing material
would be updated to reflect the existence of the newer document. would be updated to reflect the existence of the newer 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 which 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.
11.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 an otherwise non- features. Such corrections may be done in an otherwise non-
skipping to change at page 52, line 12 skipping to change at page 45, line 42
only one is supported will depend on the needs of clients, which only one is supported will depend on the needs of clients, which
may be slow to adopt the updated version. may be slow to adopt the updated version.
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, decide that the working group might, in a later minor version, decide
that the older version is to become mandatory to not implement. that the older version is to become mandatory to not implement.
Issues related to the effect of XDR corrections on existing Issues related to the effect of XDR corrections on existing
documents, including co-ordination with other minor versions, are documents, including co-ordination with other minor versions, are
discussed in Section 11.2. discussed in Section 10.7.
By doing things this way, the protocol with the XDR modification can By doing things this way, 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.
o A client that supports only the earlier version of the feature o A client that supports only the earlier version of the feature
(i.e., an older unfixed client) can determine whether the server (i.e., an older unfixed client) can determine whether the server
it is connecting to supports the older version of feature. It is 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
skipping to change at page 53, line 4 skipping to change at page 46, line 34
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 which preserves the functioning of existing clients and servers and
allowing client and server implementers to adopt the new version of allows client and server implementers to adopt the new version of the
the feature at a reasonable pace. feature at a reasonable pace.
11.2. Documentation of XDR Changes 10. Documentation of Features, Extensions, Minor Versions, and Protocol
Corrections
As mentioned previously, NFSv4 is evolving towards a finer-grained
documentation model. This trend will be continued by:
o The use of extensions within minor versions.
o Features that are added by a minor version being documented in
feature definition documents rather than within the minor version
specification itself.
10.1. Documentation Approach
Documentation of future changes to the NFSv4 protocol will use
feature specification documents as described in Section 10.3. There
are a number of ways in which such documents may be used, which
reflect the different ways in which features are incorporated in the
NFSv4 protocol, as discussed in Section 6.7
This documentation approach is intended to avoid the unnecessary
production of large documents in which many unrelated features are
tied together because either:
o The entire protocol is described in a single document, as happened
with NFSv4.0 (in [RFC7530]) and NFSv4.1 (in [RFC5661]).
o Many unrelated features are described in a single document as
occurred with NFSv4.2 (in [NFSv42]).
The production of a larger number of smaller documents will
streamline document production and review. A potential problem is
that a profusion of smaller documents might cause difficulty for
those learning about and implementing the protocol.
The production of indexing material described in Section 10.2 is
intended to limit such difficulties. The result will be that, for
operations and attributes, we will have essentially a single table of
contents, referencing material from multiple minor version definition
documents and feature specification documents.
10.2. Indexing material
The items listed below, referred to collectively as "Indexing
material" will be useful in many contexts. The reason for frequently
publishing such material is to prevent a situation in which large
numbers of documents must be scanned to find the most current
description of a particular protocol element.
o A table mapping operations and callbacks to the most recent
protocol definition document containing a description of that
operation.
o A table mapping attributes to the most recent protocol definition
document containing a description of that attribute.
o A table giving, for each operation in the protocol, the errors
that may validly be returned for that operation. If possible, it
would be desirable to give, as does [RFC5661], the operations
which may validly return each particular error.
o A table giving for each operation, callback, and attribute and for
each feature element in a published extension giving its status
(REQUIRED, OPTIONAL, or mandatory-to-not implement), the name of
the feature of which it is a part, its associated E-to-F and
F-to-E status values and information about other features for
which it has a non-empty F-to-E status value. This would be
similar to the material in Section 14 of [NFSv42], expanded to
include all feature elements.
10.3. Feature Specification Documents
Features will be documented in the form of a working-group standards-
track document which define one or more features. Generally, only
closely related features should be defined in the same document.
The definition of each of the new features may include one or more
"feature elements" which change the protocol in any of the ways
discussed in Section 5. Feature elements include new operations,
attributes, and enumeration values. Note that in this context,
"Operations" include both forward and callback operations. The
functionality of some existing operations may be extended by the
addition of new flags bits in existing flag words, by new cases in
existing switched unions, and by valid semantic changes to existing
operations.
Such feature definition documents would contain a number of items,
following the pattern of the NFSv4.2 specification. The only
difference would be that while the NFSv4.2 specification defines a
number of features to be incorporated into NFSv4.2, the feature
definition documents would each define a single feature, or a small
set of closely related features.
In addition to a general explanation of the feature(s) in question,
the items to be included in such feature definition documents would
be as listed below. In some cases these items, in addition to
descriptive text, would contain fragments of XDR code, to aid in
preparation of XDR files that include the additions defined by the
feature added to the base protocol that is being extended. For
information regarding preparation of such XDR files, see
Section 10.4.
o Description of new operations (corresponding to Sections 15 and 16
of [NFSv42]). Such descriptions will contain XDR code defining
the structure the arguments and results of the new operation along
with preparatory XDR definitions used only by that operation.
o Description of any modified operations (corresponding to
Section 15 of [NFSv42]). Such description may contain XDR code
defining the new flag bits, enum values, and cases to be added to
existing switched unions. Note that addition of new attributes is
not considered an extension of GETATTR, SETATTR, VERIFY, or
NVERIFY.
o Description of new attributes (corresponding to Section 13 of
[NFSv42]). XDR code defining the types of the attributes would be
part of this description.
o Description of any added error codes (corresponding to
Section 12.1 of [NFSv42]).
o All operation descriptions, whether for new or modified
operations, should indicate when operations or the corresponding
results may be presented as RDMA chunks.
o A set of XDR code fragments giving the numeric values of added
operation codes, attribute numbers, and error codes.
o Descriptions of all other extensions made to existing flag words,
enums and switched unions used by existing operations. Such
descriptions will contain XDR code defining the new flag bits,
enum values, and cases to be added to existing switched unions.
o Descriptions of all new structures, enums, flag words, and
switched unions that are used by more than one new operation, or
which are available for future use by multiple operations. Such
descriptions will contain XDR code defining the new structures/
union and assigning the new numeric values for enum and flag bits.
o A listing giving the valid errors for each new operation and
callback (corresponds to Sections 12.2 and 12.3 of [NFSv42]).
o For each feature, a table giving for each feature element that is
part of the feature, its overall status within the minor version
and its E-to-F and F-to-E status values. This would be similar to
the material in Section 14 of [NFSv42] but restricted to the
feature(s) defined in the document and expanded to include all
feature elements.
o A table presenting support requirement for each protocol element
which is either a part of a feature defined in the document or has
an F-to-E status with relation with a feature defined in the
document. This could present the F-to-E status value for each
relevant combination of feature element and feature. An
alternative presentation would give, for each protocol element,
boolean expressions in term of supported features, that allows or
that guarantees support for the specified element.
o All of the additional Sections required for RFC publication, such
as "Security Considerations", "IANA considerations", etc.
Note that the listing above is not intended to define, in detail, the
structure of the specification. Rather, the intention is to define
the things it needs to contain. If there would be no content for a
particular element, there is no need for an empty section
corresponding to that list element. If it makes more sense to
describe a new structure together with an extended one, then the need
for a readily understandable document is primary.
10.4. XDR File Considerations
As mentioned previously, feature specification documents will
contain, in addition to description of XDR extensions, XDR code
fragments that embody those extensions. There will be various
occasions on which people will have occasion to produce XDR files
that combine one or more extensions together with the XDR for an
existing minor version.
o When a minor version is specified by a number of feature
specification documents, there will be a need to produce, in as
simple fashion as possible, the corresponding XDR specification
document for the new minor version.
o Within an extensible minor version, there will be a need for those
developing and testing the feature to have an XDR file that
incorporates XDR definitions from early drafts of the feature
specification document.
o Also, for an extensible minor version, there will be a need to
periodically produce Consolidated XDR documents that reflect all
features approved as Proposed Standards and thus incorporated in
the current minor version.
o Developers may need to be able to produce XDR files that reflect
particular combination of approved features, features under
development or experimental features not yet ready for working
group consideration.
We are assuming here that the primary task is producing XDR files and
that corresponding XDR documents can be produced relatively easily if
there is a well understood process to produce the underlying XDR
files.
The Feature specification document should contain all of the
necessary lines of XDR codes to be added to a base XDR file to effect
the extension. The only remaining issue is where to place each
addition to arrive at the correct consolidated file.
o One could rely on those preparing updated XDR file to place the
additional XDR code lines in the appropriate place, based on
inference from the document text.
o One could rely on the Feature Specification Document to indicate,
in the descriptive text, where each XDR extension is to be placed.
o One could formalize a set of conventions whereby the appropriate
placements are indicated by specific instructions embedded within
comments within the XDR code fragments to be placed.
10.5. Additional Documents to Support Protocol Extension
Additional documents will be required from time to time. These
documents will eventually become RFC's (informational or standards
track as described below), but the work of the working group and of
implementers developing features will be facilitated by a progression
of document drafts that incorporate information about new features
that are being developed or have been approved as Proposed Standards.
10.5.1. Minor Version Indexing Document
One document will organize existing material for a minor version
undergoing extension so that implementers will not have to scan a
large set of feature definition documents or minor version
specifications to find information being sought. Successive drafts
of this document will serve as an index to the current state of the
extensible minor version. Some desirable elements of this indexing
document would include:
o A list of all feature definition documents that have been approved
as working group documents but have not yet been approved as
Proposed Standards.
o All of the items of indexing material (see Section 10.2)
appropriately adjusted to reflect the contents of all extensions
accepted as Proposed Standards.
The frequency of updates for this document will be affected by
implementer needs and the ability to easily generate document drafts,
preferably by automated means. The most desirable situation is one
in which a new draft is available soon after each feature reaches the
status of a Proposed Standard.
10.5.2. Consolidated XDR Document
This document will consist of an updated XDR for the protocol as a
whole including feature elements from all features and minor versions
accepted as Proposed Standards.
A new draft should be prepared whenever a new feature within an
extensible minor version is accepted as a Proposed Standard. In most
cases, feature developers will be using a suitable XDR which can then
be reviewed and published. In cases in which multiple features reach
Proposed Standard status at approximately the same time, a merge of
the XDR changes made by each feature may be necessary.
10.5.3. XDR Assignment Document
This document will contain consolidated lists of XDR value
assignments that are relevant to the protocol extension process. It
should contain lists of assignments for:
o operation codes (separate lists for forward operations and for
callbacks)
o attribute numbers
o error codes
o bits within flag words that have been extended since they were
first introduced.
o enumeration values for enumerations which have been extended since
they were first introduced.
For each set of assignments, the individual assignments may be of
three types:
1. permanent assignments associated with a minor version or a
feature extension that has achieved Proposed Standard status.
These assignments are permanent in that the assigned value will
never be re-used. However, a subsequent minor version may define
some or all feature elements associated with a feature to be
mandatory to not implement.
2. provisional assignments associated with a feature under
development (i.e., one which has been approved as a working group
document but has not been approved as a Proposed Standard).
Provisional assignments are not are not permanent and the values
assigned can be re-used in certain circumstances. In particular,
when a feature with provisional assignments is not progressing
toward the goal of eventual Proposed Standard status, the working
group can judge the feature effort to have been abandoned,
allowing the codes formerly provisionally allocated to be
reclaimed and reassigned.
3. definition of individual assignments or ranges reserved for
experimental use.
A new draft of this document should be produced, whenever:
o A minor version or feature specification is accepted as a Proposed
Standard.
o A new feature is accepted for development and a draft of the
corresponding working-group standards-track document is produced
o A feature previously accepted for development is abandoned.
o The working group decides to make some change in assignments for
experimental use.
10.5.4. Transition of Documents to RFC's
Each of these documents should be published as an RFC soon after the
minor version in question ceases to be considered extensible.
Typically this will happen when the working group makes the
specification for the subsequent minor version into a working group
document. Some specifics about the individual documents are listed
below:
o The most current draft of the indexing document for the minor
version would be published as an informational RFC.
o The most current draft of the consolidated XDR document should be
published as a standards-track RFC. It would update the initial
specification of the minor version
o The most recent draft of the XDR assignment document should be
published as an informational RFC.
Handling of these documents in the event of a post-approval XDR
correction is discussed in Section 10.7
10.6. Documentation of New Minor Versions
Minor versions should be documented by specifying and explaining the
changes made relative to the previous minor version.
Features added to the minor version should be documented in their own
feature specification documents and normatively referenced.
Changes to the status or organization of existing features should be
documented by presenting a summary of the status of all existing
protocol elements, their relationship to OPTIONAL features, and any
relevant feature dependencies.
In addition, to avoid situation where a large number of minor
versions must be scanned to find the most recent valid treatment of a
specific protocol element, minor version definition documents will
contain the indexing material described in Section 10.2.
10.7. Documentation of XDR Changes for Corrections
In the event of an XDR correction, as discussed above, some document In the event of an XDR correction, as discussed above, some document
updates will be required. For the purposes of this discussion we updates will be required. For the purposes of this discussion we
call the minor version for which XDR correction is required minor call the minor version for which XDR correction is required minor
version X and the minor version on which development is occurring version X and the minor version on which development is occurring
minor version Y. minor version Y.
The following discusses the specific updated documents which could be The following discusses the specific updated documents which could be
required: required:
skipping to change at page 54, line 5 skipping to change at page 55, line 20
based on the most recent such document associated with minor based on the most recent such document associated with minor
version Y and will serve as the basis for later XDR assignment version Y and will serve as the basis for later XDR assignment
drafts for minor version Y. drafts for minor version Y.
The informational RFC's associated with minor version Y (version The informational RFC's associated with minor version Y (version
indexing document and XDR assignment document) will contain the indexing document and XDR assignment document) will contain the
effects of the correction when published. Similarly, the minor effects of the correction when published. Similarly, the minor
version specification RFC will contain the XDR changes associated version specification RFC will contain the XDR changes associated
with the correction. with the correction.
12. Security Considerations 11. 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.
As features and minor versions are designed and specified in As features and minor versions are designed and specified in
standards-track documents, their security issues will be addressed standards-track documents, their security issues will be addressed
and each RFC candidate will receive the appropriate security review and each RFC candidate will receive the appropriate security review
from the NFSv4 working group and IESG. from the NFSv4 working group and IESG.
13. IANA Considerations 12. IANA Considerations
The current document does not require any actions by IANA. The current document does not require any actions by IANA.
Depending on decisions that the working group makes about how to Depending on decisions that the working group makes about how to
address the issues raised in this document, future documents may address the issues raised in this document, future documents may
require actions by IANA. require actions by IANA.
14. References 13. References
14.1. Normative References 13.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>.
14.2. Informative References 13.2. Informative References
[NFSv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", [NFSv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", January
September 2015, <http://www.ietf.org/id/ 2016, <http://www.ietf.org/id/
draft-ietf-nfsv4-minorversion2-39.txt>. draft-ietf-nfsv4-minorversion2-40.txt>.
Work in progress. Work in progress.
[NFSv42-dot-x] [NFSv42-dot-x]
Haynes, T., Ed., "NFS Version 4 Minor Version 2 Protocol Haynes, T., Ed., "NFS Version 4 Minor Version 2 Protocol
External Data Representation Standard (XDR) Description", External Data Representation Standard (XDR) Description",
September 2015, <http://www.ietf.org/id/ January 2016, <http://www.ietf.org/id/
draft-ietf-nfsv4-minorversion2-dot-x-39.txt>. draft-ietf-nfsv4-minorversion2-dot-x-40.txt>.
Work in progress. Work in progress.
[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>.
[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
skipping to change at page 55, line 41 skipping to change at page 57, line 11
(NFS) Version 4 External Data Representation Standard (NFS) Version 4 External Data Representation Standard
(XDR) Description", RFC 7531, DOI 10.17487/RFC7531, March (XDR) Description", RFC 7531, DOI 10.17487/RFC7531, March
2015, <http://www.rfc-editor.org/info/rfc7531>. 2015, <http://www.rfc-editor.org/info/rfc7531>.
Appendix A. Acknowledgements Appendix A. 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 this effort started and his work in co-authoring the first getting this effort started and his work in co-authoring the first
version of this document. version of this document.
The author also wishes to thank Chuck Lever of Oracle for his The author also wishes to thank Chuck Lever and Mike Kepfer of Oracle
thorough document review and many helpful suggestions. for their thorough document reviews and many helpful suggestions.
Author's Address Author's Address
David Noveck David Noveck
Hewlett-Packard Hewlett Packard Enterprise
165 Dascomb Road 165 Dascomb Road
Andover, MA 01810 Andover, MA 01810
US US
Phone: +1 978 474 2011 Phone: +1 978 474 2011
Email: davenoveck@gmail.com Email: davenoveck@gmail.com
 End of changes. 137 change blocks. 
633 lines changed or deleted 694 lines changed or added

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