RFC 8178

Rules for NFSv4 Extensions and Minor Versions

📅 published July 2017, from ietf

RFC 8178: Rules for NFSv4 Extensions and Minor Versions 🎀

okay bestie, this one is RFC 8178, and it's giving "how do we add new stuff to NFSv4 without breaking everybody" 💅 It was written by D. Noveck at NetApp, dated July 2017, and it's a Standards Track document from the Internet Engineering Task Force (IETF). Its ISSN is 2070-1721. It updates RFC 5661 and RFC 7862, and the title block doesn't list anything it obsoletes. 🧚

Abstract 🌸

so the abstract says this doc covers the rules for extending the NFSv4 family of protocols ✨ That includes making new minor versions, adding optional features to minor versions that already exist, and fixing mistakes in features that were already published as Proposed Standards 🔧 The rules for building minor versions and for how different minor version implementations talk to each other now replace the minor versioning rules in RFC 5661 and in any other RFCs that define minor versions. Bye-bye, old rules 👋

Status of This Memo 📮

this is an Internet Standards Track document 🏆

it's a product of the IETF, so it represents the consensus of the IETF community. It got public review and the IESG (Internet Engineering Steering Group) approved it for publication 🫶 If you want more info on Internet Standards, check out Section 2 of RFC 7841.

for the current status, any errata, and how to send feedback, head to http://www.rfc-editor.org/info/rfc8178 💜

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. 🌈

this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at http://trustee.ietf.org/license-info as they were in effect on the date this document was published. Please read these carefully, because they explain what you can and can't do with this document 📜 Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes 💅

Table of Contents 📚

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Use of Keywords Defined in RFCs 2119 and 8174 . . . . . .   4
     2.2.  Use of Feature Statuses . . . . . . . . . . . . . . . . .   4
     2.3.  NFSv4 Versions  . . . . . . . . . . . . . . . . . . . . .   5
   3.  Consolidation of Extension Rules  . . . . . . . . . . . . . .   6
   4.  XDR Considerations  . . . . . . . . . . . . . . . . . . . . .   7
     4.1.  XDR Extension . . . . . . . . . . . . . . . . . . . . . .   8
     4.2.  Rules for XDR Extension within NFSv4  . . . . . . . . . .   8
     4.3.  Handling of Protocol Elements by Responders . . . . . . .   9
     4.4.  Inter-version Interoperability  . . . . . . . . . . . . .  11
       4.4.1.  Requirements for Knowledge of Protocol Elements . . .  11
       4.4.2.  Establishing Interoperability . . . . . . . . . . . .  12
       4.4.3.  Determining Knowledge of Protocol Elements  . . . . .  14
     4.5.  XDR Overlay . . . . . . . . . . . . . . . . . . . . . . .  15
   5.  Other NFSv4 Protocol Changes  . . . . . . . . . . . . . . . .  15
     5.1.  Field Interpretation and Use  . . . . . . . . . . . . . .  15
     5.2.  Behavioral Changes  . . . . . . . . . . . . . . . . . . .  16
   6.  Extending Existing Minor Versions . . . . . . . . . . . . . .  17
   7.  Minor Versions  . . . . . . . . . . . . . . . . . . . . . . .  18
     7.1.  Creation of New Minor Versions  . . . . . . . . . . . . .  18
   8.  Minor Version Interaction Rules . . . . . . . . . . . . . . .  18
     8.1.  Minor Version Identifier Transfer Issues  . . . . . . . .  19
     8.2.  Minor Version Compatibility . . . . . . . . . . . . . . .  19
   9.  Correction of Existing Minor Versions and Features  . . . . .  20
     9.1.  XDR Changes to Implement Protocol Corrections . . . . . .  21
     9.2.  XDR Corrections to OPTIONAL Features  . . . . . . . . . .  21
     9.3.  XDR Corrections to REQUIRED Features  . . . . . . . . . .  22
     9.4.  Addressing XDR Corrections in Later Minor Versions  . . .  24
   10. Security Considerations . . . . . . . . . . . . . . . . . . .  24
   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  25
   12. References  . . . . . . . . . . . . . . . . . . . . . . . . .  25
     12.1.  Normative References . . . . . . . . . . . . . . . . . .  25
     12.2.  Informative References . . . . . . . . . . . . . . . . .  25
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  25
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  26

1. Introduction 🦋

okay so NFSv4 needs to be able to grow as needs change 🌱 That's why the protocol has a framework for future changes through new protocol versions. That includes new minor versions and some ways of changing existing minor versions. The extension rules in this doc let you add extensions and other changes without breaking compatibility with the clients and servers that already exist 💖

back in the day, every protocol change was part of a new minor version 📖 The COMPOUND procedure (see Section 14.2 of [RFC7530]) says which minor version the client is using when it makes requests. The CB_COMPOUND procedure (see Section 15.2 of [RFC7530]) says which minor version the server is using for callback requests.

now a new minor version isn't the only way to make changes anymore 🙌 You can add optional features as extensions, and you can propose, specify, and implement protocol corrections inside a single minor version. Making new minor versions is still an option when you actually need one 🫶

the point of allowing extensions inside a minor version is more flexibility for implementers, while keeping interoperability when the protocol gets upgraded 🌈 As Section 4.4 explains, a client and a server can each pick a subset of the available extensions. Each side can successfully use the protocol elements that both the client and the server know about and support. That shared subset keeps working even if the server supports extensions outside it, or the client might use them 💅

2. Terminology 📝

you need a basic familiarity with NFSv4 terminology for this doc, so if you're new, go read [RFC7530] first 📚

in this document, "version" isn't only about minor versions 👀 When the doc means minor versions, it says "minor version" out loud. For more on this and related terms, see Section 2.3.

a "feature package" is a set of features that are defined together, either as part of a minor version or as part of the same protocol extension 🎁

2.1. Use of Keywords Defined in RFCs 2119 and 8174 🔑

the keywords defined by [RFC2119] [RFC8174] have special meanings, and this document intends to follow them 💖 But because of what this doc is and some special circumstances, there are a few complexities to watch out for:

  • Where this document doesn't directly specify implementation requirements, using these capitalized terms usually isn't appropriate, because the guidance here doesn't directly affect interoperability.
  • In this document, what authors of RFCs defining features and minor versions need to do is stated without these specialized terms. Following this guidance is still necessary for a successful NFSv4 protocol extension, but that kind of necessity isn't the kind defined for the keywords in [RFC2119] [RFC8174].

The fact that these capitalized terms aren't used should not be read as meaning this guidance doesn't need to be followed, or that it isn't important 🙈

  • In speaking of the possible statuses of features and feature elements, the terms "OPTIONAL" and "REQUIRED" are used. For further discussion, see Section 2.2.
  • When one of these upper-case keywords defined in [RFC2119] [RFC8174] is used in this document, it's in the context of a rule aimed at an implementer of NFSv4 minor versions, the status of a feature or protocol element, or a quotation, sometimes indirect, from another document 💅

2.2. Use of Feature Statuses ✨

there's been some confusion in NFSv4 history about how to use these terms 😭 Sometimes the keywords defined in [RFC2119] [RFC8174] were used in ways that look different from what that document defines.

  • In [RFC3530], the lower-case terms "optional", "recommended", and "required" were used as feature statuses. Later, [RFC5661] and [RFC7530] used the matching upper-case keywords. Nobody's totally sure why that change happened 🤷‍♀️
  • Using "RECOMMENDED" as a feature status doesn't match what [RFC2119] [RFC8174] says, so this document won't use it for that purpose 🙅‍♀️
  • Using "RECOMMENDED" for the status of attributes in [RFC7530] and [RFC5661] raises similar issues. [RFC7530] noticed this for NFSv4.0, but the situation for NFSv4.1 is still unresolved 🌸

in this document, the keywords "OPTIONAL" and "REQUIRED", plus the phrase "mandatory to not implement", are used to say what the status of a feature is within a given minor version. When RFCs specify the status of a feature, they tell:

  • client implementations whether they need to deal with a feature being absent 🧚
  • server implementations whether they need to provide support for the feature 💜

2.3. NFSv4 Versions ✨

okay so "version" is the umbrella term 💜 It means any valid protocol variant built by the rules in this doc, and that includes minor versions. BUT, and this is the lowkey tricky part, a single minor version can have a bunch of variants chilling inside it 🫶

  • When there are feature specification documents published as Proposed Standards extending a given minor version, then the protocol defined by the minor version specification document, when combined with any subset (not necessarily a proper subset) of the feature specification documents, is a valid NFSv4 version variant that is part of the minor version in question.
  • When there are protocol corrections published that update a given minor version, each set of published updates, up to the date of publication of the update, is a valid NFSv4 version variant that is part of the minor version in question.

So yeah, multiple variants can belong to one minor version 🌈 Two of them get their own special names:

  • The term "base minor version" denotes the version variant that corresponds to the minor version as originally defined, including all protocol elements specified in the minor version definition document but not incorporating any extensions or protocol corrections published after that original definition. 🍓
  • At any given time, the term "current minor version" denotes the minor version variant including all extensions of and corrections to the minor version made by Standards Track documents published up to that time. 👑

Every client and server that implements a specific minor version will implement some particular variant of it 💅 Each variant is a subset of the current minor version and a superset of the base minor version. Like, it's giving nested dolls 🪆 When the term "minor version" shows up without either of those qualifiers, it should refer to something that is true of all variants within that minor version. For example, if a minor version has never had a protocol correction, you can talk about the set of REQUIRED features for that minor version, since it's the same for every variant in it 🎀 Check Section 9 for how correcting an existing minor version works.

3. Consolidation of Extension Rules

Back in the day, the only extension rules were the minor versioning rules maintained in the Standards Track RFCs that defined each individual minor version. And those rules got tweaked on an ad hoc basis for every new minor version 😭

Then [RFC5661] came along and specified minor versioning rules, and modifications to those rules were allowed in subsequent minor versions.

This document defines a set of extension rules, including rules for minor version construction. These rules apply to all future changes to the NFSv4 protocol 🦋 They're subject to change, but any such change should be part of a Standards Track RFC obsoleting or updating this document.

Instead of one big list of extension rules like the minor versioning rules in [RFC5661], this document defines multiple sets of rules for the different forms of protocol change that the NFSv4 extension framework provides for 🧚

  • The kinds of changes in External Data Representation (XDR) definitions that may be made to extend NFSv4 are addressed in the rules in Section 4.2.
  • Minor version construction, including rules applicable to changes that cannot be made in extensions to existing minor versions, is addressed in Section 7.1.
  • Minor version interaction rules are discussed in Sections 8.1 and 8.2.

This document supersedes minor versioning rules appearing in the minor version specification RFCs, including those in [RFC5661], and also the modification to those rules mentioned in [RFC7862]. So if there are potential conflicts between documents, here's how they get sorted out 👀

  • The specification of the actual protocols for minor versions previously published as Proposed Standards takes precedence over minor versioning rules in either this document or in the minor version specification RFCs. In other words, if the transition from version A to version B violates a minor versioning rule, the version B protocol stays as it is. 🔥
  • Since minor versioning rules #11 and #13 from [RFC5661] deal with the interactions between multiple minor versions, the situation is more complicated. See Section 8 for a discussion of these issues, including how potential conflicts between rules are to be resolved. 🫠
  • Otherwise, any conflict between the extension rules in this document and those in minor version specification RFCs is to be resolved based on the treatment in this document. In particular, corrections may be made as specified in Section 9 for all previously specified minor versions, and the extensibility of previously specified minor versions is to be handled in accord with Section 6. ✨

Future minor version specification documents should avoid specifying rules relating to minor versioning and should reference this document in connection with rules for NFSv4 extension 💖

4. XDR Considerations ✨

NFSv4 is an extensible XDR-based protocol, so it has to make sure things stay inter-version compatible when the client and server are using different XDR descriptions 🌸 For example, the client and server might implement different variants of the same minor version, since each one might add a different set of extensions to the base minor version.

The XDR extension paradigm, discussed in Section 4.1, is what makes sure these descriptions stay compatible. Clients and servers can figure out and use the parts of the protocol they both share, using the method described in Section 4.4.2. Iconic teamwork, honestly 🫶

4.1. XDR Extension

When an NFSv4 version change needs a modification to the protocol XDR, it's handled within a framework built on the idea of XDR extension. This is different from transitions between major NFS versions (including the one between NFSv3 and NFSv4.0), where the XDR for one version got replaced by a totally different XDR for the newer version 💀

The XDR extension approach lets an XDR description be extended in a way that keeps the structure of all previously valid messages intact 🧚 If a base XDR description gets extended to create a second XDR description, the following will be true for the second description to be a valid extension of the first:

  • The set of valid messages described by the extended definition is a superset of that described by the first.
  • Each message within the set of valid messages described by the base definition is recognized as having exactly the same structure/interpretation using the extended definition.
  • Each message within the set of messages described as valid by the extended definition but not the base definition must be recognized, using the base definition, as part of an unknown extension.

XDR extension can make it way easier for different versions of the NFSv4 protocol to get along 🌈 When it's used to implement OPTIONAL features, you get the greatest degree of inter-version compatibility. In this case, as long as the rules in Section 6 are followed, no change in minor version number is needed and the extension can happen within a single minor version 🎀

4.2. Rules for XDR Extension within NFSv4

In NFSv4, COMPOUND and CB_COMPOUND play a central role, so adding new RPC procedures is not allowed, and the enumeration of operations and callback operations get a special status 👑

The following XDR extensions, by their nature, affect both messages sent by requesters (i.e., requests and callbacks) and responders (i.e., replies and callback replies) 🦋

  • Addition of previously unspecified operation codes, within the framework established by COMPOUND and CB_COMPOUND. These extend the appropriate enumeration and the corresponding switches devoted to requests and responses for the associated direction of operation.
  • Addition of previously unspecified attributes. These add additional numeric constants that define each attribute's bit position within the attribute bitmap, together with XDR typedefs that specify the attributes' format within the nominally opaque arrays specifying sets of attributes.

Other sorts of changes will generally affect one of requests, replies, callback, or callback replies. Although all of them are valid XDR extensions, the messages affected may determine whether the extension requires a new minor version (see Section 7) or can be made as an extension within an existing minor version (see Section 6) 🍓

  • Addition of new, previously unused, values to existing enums.
  • Addition of previously unassigned bit values to a flag word.
  • Addition of new cases to existing switches, provided that the existing switch did not contain a default case.

None of the following is allowed to happen 🙈

  • Any change to the structure of existing requests or replies other than those listed above.
  • Addition of previously unspecified RPC procedures for either the NFSv4 program or the callback program.
  • Deletion of existing RPC procedures, operation codes, enum values, flag bit values, and switch cases. Note that changes may be made to define use of any of these as causing an error, as long as the XDR is unaffected. Similarly, none of these items may be reused for a new purpose. 💀

4.3. Handling of Protocol Elements by Responders 🎀

Okay so, implementations handle protocol elements that show up in requests and callbacks in one of three ways 🦋 Which of these are valid depends on the status of the element in the variant being implemented:

  • The protocol element is not a part of definition of the variant in question and so is "unknown". The responder, when it does not report an RPC XDR decode error, reports an error that signals the element isn't defined in the XDR, like NFS4ERR_OP_ILLEGAL, NFS4ERR_BADXDR, or NFS4ERR_INVAL. See Section 4.4.3 for details. 🙈
  • The protocol element is a known part of the variant but is not supported by the particular implementation. The responder reports an error that says the element is recognized as one that isn't supported, such as NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, or NFS4ERR_ATTRNOTSUPP. 💀
  • The protocol element is a known part of the variant that is supported by the particular implementation. The responder reports success or an error other than the special ones discussed above. ✨

Which of these are validly returned by the responder depends on the status of the protocol element in the minor version specified in the COMPOUND or CB_COMPOUND. The possibilities that can exist when dealing with minor versions that have not been subject to corrections are listed below. See Sections 9.1 and 9.3 for a discussion of the effects of protocol correction. 💅

  • The protocol element is not known in the minor version. In this case, all implementations of the minor version MUST indicate that the protocol element is not known.
  • The protocol element is part of a feature specified as mandatory to not implement in the minor version. In this case as well, all implementations of the minor version MUST indicate that the protocol element is not known. 🚫
  • The protocol element is defined as part of the current variant of the minor version but is not part of the corresponding base variant. In this case, the requester can run into situations where the protocol element is either not known to the responder, is known to but not supported by the responder, or is both known to and supported by the responder. 🌸
  • The protocol element is defined as an OPTIONAL part of the base minor version. In this case, the requester can expect the protocol element to be known but must deal with cases in which it is supported or is not supported. 🤷‍♀️
  • The protocol element is defined as a REQUIRED part of the base minor version. In this case, the requester can expect the protocol element to be both known and supported by the responder. 👑

The list above doesn't mean a requester always has to be ready for every one of those possibilities 🧚 Often, depending on the scope of the feature the protocol element belongs to, handling of a previous request that uses the same or related protocol elements lets the requester be sure that some of these possibilities can't happen.

Requesters, typically clients, may test for knowledge of, or support for, protocol elements as part of connection establishment. This can help the requester spot a responder's lack of knowledge of or support for problematic requests before those requests are used to affect user requests. 🫶

4.4. Inter-version Interoperability 🌈

Because NFSv4 uses XDR extension, any communicating client and server versions have XDR definitions where each one is a valid extension of a third version. Once that version is determined, both client and server may use it to communicate. Each party can successfully use a subset of protocol elements that are known to and supported by both parties. 💖

4.4.1. Requirements for Knowledge of Protocol Elements 🔥

Here are the rules for what has to be known about protocol elements. They come from the XDR extension paradigm combined with the way extensions get added to existing minor versions (for the full details, see Section 6). ✨

  • Any protocol element defined as part of the base variant of a particular minor version is required to be known by that minor version. This holds whether the specification lives in the body of the minor definition document or in a feature definition document that becomes part of the minor version by being normatively referenced by the minor version definition document. 📚
  • Any protocol element required to be known in a given minor version is required to be known in subsequent minor versions, unless and until a minor version has made that protocol element mandatory to not implement. 🙌
  • When a protocol element is defined as part of an extension to an extensible minor version, it is not required to be known in that minor version but is required to be known by the next minor version. In the earlier minor version, it might not be defined in the XDR definition document, while in the later version it needs to be defined there. Either way, if it is defined, it might or might not be supported. 🦋
  • When knowledge of protocol elements is optional in a given minor version, the responder's knowledge of such optional elements must obey the rule that if one such element is known, then all the protocol elements defined in the same minor version definition document must be known as well. 🍓

For many minor versions, all existing protocol elements are required to be known by both the client and the server, so requesters don't have to test for whether knowledge exists. This is the case when there has been no extension for the minor version in question. Extensions can be added to extensible minor versions as described in Section 6, and they can be used to correct protocol flaws as described in Section 9. 🎀

Requesters can figure out what the responder knows in two ways:

  • By issuing a request that uses the protocol element and looking at the response. Note that even if the protocol element used is not supported by the responder, the requester can still determine whether the element is known by the responder. 🔍
  • By receiving a request from the responder, acting in the role of requester. For example, a client may issue a request that lets the server infer that the client is aware of a corresponding callback. 📞

When making this determination, the requester can rely on two basic facts:

  • If the responder is aware of a single protocol element within a feature package, it must be aware of all protocol elements within that feature package. 🧩
  • If a protocol element is one defined by the minor version specified by a request (and not in an extension), or in a previous minor version, the responder must be aware of it. 💜

4.4.2. Establishing Interoperability 🧚‍♀️

When a client and a server interact, they need to be able to take advantage of the compatibility that NFSv4's use of XDR extension provides. ✨

In this context, the client and server arrive at a common variant. The client uses that variant to send requests that the server will then accept, and the server uses it to send callbacks that the client will then accept. This can happen in a few different ways:

  • Client and server have been built using XDR variants that belong to the same minor version. 🫧
  • The client's minor version is lower than that of the server. In this case the server, in accord with Section 8.2, accepts the client's minor version and acts as if it has no knowledge of extensions made in subsequent minor versions. It has knowledge of protocol elements within the current (i.e., effectively final) variant of the lower minor version. 🌙
  • The client's minor version is higher than that of the server. In this case the client, in accord with Section 8.2, uses a lower minor version that the server will accept. Here, the server has no knowledge of extensions made in subsequent minor versions. 🍑

There are a few cases to think about depending on which minor version gets chosen:

  • When the minor version consists of only a single variant (no extension or XDR corrections), the client and the server are using the same XDR description and have knowledge of the same protocol elements. 💖
  • When the minor version consists of multiple variants (i.e., there are one or more XDR extensions or XDR corrections), the client and the server are using compatible XDR descriptions. The client is aware of some set of extensions while the server may be aware of a different set. The client can use the approach described in Section 4.4.3 to determine which of the extensions it knows about are also known by the server. Once that's done, the client and server both use a common variant. The variants the client and the server were built with will each either be identical to this variant or a valid extension of it. Similarly, the variants the client and the server actually use will be a subset of this variant, in that certain OPTIONAL features will not be used. 🌈

In either case, the client must determine which of the OPTIONAL protocol elements within the common version are supported by the server, just as it does for OPTIONAL features introduced as part of a minor version. 🔎

It is best if client implementations determine the support provided by the server before acting on user requests. This includes working out the common protocol variant and the level of support for OPTIONAL protocol elements. 🫶

4.4.3. Determining Knowledge of Protocol Elements 🔍

okay bestie, so a requester is allowed to check whether the responder knows about a particular protocol element 🕵️‍♀️ and how you check depends on what kind of element it is. heads up though: if you test two or more attribute or flag bits whose status is still undetermined ("known" versus "unknown"), the results can be kinda useless 🙃 in that case, a NFS4ERR_INVAL response only tells you that at least one of those bits is unknown. 💀

  • When a GETATTR request is made specifying an attribute bit to be tested and that attribute is not a set-only attribute, if the GETATTR returns with the error NFS4ERR_INVAL, then it can be concluded that the responder has no knowledge of the attribute in question. Other responses, including NFS4ERR_ATTRNOTSUPP, indicate that the responder is aware of the attribute in question. ✨
  • When a SETATTR request is made specifying the attribute bit to be tested and that attribute is not a get-only attribute, if the SETATTR returns with the error NFS4ERR_INVAL, then it can be concluded that the responder has no knowledge of the attribute in question. Other responses, including NFS4ERR_ATTRNOTSUPP, indicate that the responder is aware of the attribute in question. 🎀
  • When a request is made including an operation with a new flag bit, if the operation returns with the error NFS4ERR_INVAL, then it can generally be concluded that the responder has no knowledge of the flag bit in question, as long as the requester is careful to avoid other error situations in which the operation in question is defined as returning NFS4ERR_INVAL. Other responses indicate that the responder is aware of the flag bit in question. 🚩
  • When a request is made including the operation to be tested, if the responder returns an RPC XDR decode error, or a response indicating that the operation in question resulted in NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR, then it can be concluded that the responder has no knowledge of the operation in question. Other responses, including NFS4ERR_NOTSUPP, indicate that the responder is aware of the operation in question. 🧠
  • When a request is made including the switch arm to be tested, if the responder returns an RPC XDR decode error, or a response indicating that the operation in question resulted in NFS4ERR_BADXDR, then it can be concluded that the responder has no knowledge of the operation in question. Other responses, including NFS4ERR_UNION_NOTSUPP, indicate that the responder is aware of the protocol element in question. 💅

A determination of the knowledge or lack of knowledge of a particular protocol element is expected to remain valid as long as the clientid associated with the request remains valid. Basically the answer sticks around for as long as that clientid is still good 🦋

The above assumes, as should be the case, that the server will accept the minor version used by the client. For more detail regarding this issue, see Section 8.2. 🌸

4.5. XDR Overlay ✨

okay so XDR additions can also show up by defining XDR structures that overlay nominally opaque fields, which are set up on purpose to allow these little incremental extensions 🧁

For example, each parallel NFS (pNFS) mapping type provides its own XDR definition for various pNFS-related fields defined in [RFC5661] as opaque arrays. 🌈

Because such additions provide new interpretations of existing fields, they may be made outside of the extension framework as long as they obey the rules previously established when the nominally opaque protocol elements were added to the protocol. this is giving "follow the original rules or else" energy 💖

5. Other NFSv4 Protocol Changes 🦋

there are a bunch of protocol changes that live outside the XDR extension framework we talked about in Section 4. 🫧 these changes are still managed within the NFSv4 versioning framework too, and they come in a few different types, which we'll go through in the sections below.

Even though we've been obsessing over XDR changes, NFSv4 changes haven't been limited to ones that involve changes (in the form of extensions) to the protocol XDR. 👀 Examples of other sorts of changes have been taken from NFSv4.1.

All such changes that have been made in the past have been made as part of new minor version. Future change of these sorts may not be done in an extension but can only be made in a new minor version. no extension shortcuts for these, periodt 💅

5.1. Field Interpretation and Use 🧶

The XDR description of a protocol does not constitute a complete description of the protocol. Therefore, versioning needs to consider the role of changes in the use of fields, even when there is no change to the underlying XDR. 🤓

Although any XDR element is potentially subject to a change in its interpretation and use, the likelihood of such change will vary with the XDR-specified type of the element, as discussed below:

  • When XDR elements are defined as strings, rules regarding the appropriate string values are specified in protocol specification text with changes in such rules documented in minor version definition documents. Some types of strings within NFS4 are used in server names (in location-related attributes), user and group names, and in the names of file objects within directories. Rules regarding what strings are acceptable appear in [RFC7530] and [RFC5661] with the role of the XDR limited to hints regarding UTF-8 and capitalization issues via XDR typedefs. 🔤
  • Fields that are XDR-defined as opaque elements and that are truly opaque, do not raise versioning issues, except as regards inter-version use, which is effectively foreclosed by the rules in Section 8.1. 🔒

Note that sometimes a field will seem to be opaque but not actually be fully opaque when considered carefully. For example, the "other" field of stateids is defined as an opaque array, while the specification text specially defines appropriate treatment when the "other" field within it is either all zeros or all ones. Given this context, creation or deletion of reserved values for "special" stateids will be a protocol change that versioning rules need to deal with. 👻

  • Some nominally opaque elements have external XDR definitions that overlay the nominally opaque arrays. Such cases are discussed in Section 4.5. 🧩

5.2. Behavioral Changes 🎀

Changes in the behavior of NFSv4 operations are possible, even if there is no change in the underlying XDR or change to field interpretation and use. 🎭

One class of behavioral change involves changes in the set of errors to be returned when various failure conditions occur. When the set of valid requests remain the same, and the behavior for each of them remains the same, such changes can be implemented with only limited disruption to existing clients. 🌷

Many more substantial behavioral changes have occurred in connection with the addition of the session concept in NFSv4.1. Even though there was no change to the XDR for existing operations, many existing operations and COMPOUNDs consisting only of them became invalid. ngl this one was a whole plot twist 😭

Also, changes were made regarding the required server behavior as to the interaction of the MODE and Access Control List (ACL) attributes. 📋

6. Extending Existing Minor Versions 🌈

Extensions to the most recently published NFSv4 minor version may be made by publishing the extension as a Proposed Standard, unless the minor version in question has been defined as non-extensible. 🪄 A document need not use the Updates header specifying the RFC that defines the minor version, which remains a valid description of the base variant of the minor version in question. no need to update the header, the original still holds up 💅

In addition to following the rules for XDR extensions in Section 4.2, such extensions must also obey the rules listed below in order to allow interoperability to be established, as described in Section 4.4:

  • Additions to the set of callback requests and extensions to the XDR for existing callback operations can only be made if the server can determine, based on the client's actions, that the client is aware of the changes. This determination, for any particular client (as defined by its clientid), is made before sending those new or extended callbacks. 📞
  • XDR extensions that affect the structures of responses to existing operations can only be made if the server can determine, based on the client's actions, that it is aware of the existence of XDR changes, before sending responses containing those extensions. This determination can be based on the request being responded to, but that is not required. Use of any protocol element defined in the extension can be the basis of the determination, provided that the requirements for determining client awareness are clearly stated. 🔎

Corrections to protocol errors (see Section 9) may be accomplished by publishing an extension, including a compatible XDR change that follows the rules above. Such documents will update the defining documents for the minor version to be corrected. 🛠️

In some cases, extensions will contain elements such as new operations or previously invalid switch cases. Although it is possible to determine whether these OPTIONAL elements are supported using the rules described above, those defining an extension that contains such elements have the choice of defining a new attribute that indicates whether the feature is present and supported. Since it is easy to determine whether a new attribute is supported using the supported_attrs attribute, this can make it simple and convenient for clients to determine whether support is present, particularly when a feature involves support for multiple such elements. 🧃

7. Minor Versions 💜

7.1. Creation of New Minor Versions 🌸

It is important to note that this section, in describing situations that would require new minor versions to be created, does not thereby imply that situations will exist in the future. Judgments regarding desirability of future changes will be made by the working group or its successors and any guidance that can be offered at this point is necessarily quite limited. 🔮

Creation of a new minor version is an option that the working group retains. The listing of situations below that would prompt such actions is not meant to be exhaustive. 🧭

The following sorts of features are not allowed as extensions and would require creation of a new minor version:

  • Features that incorporate any of the non-XDR-based changes discussed in Sections 5.1 and 5.2. 🧱
  • Features whose XDR changes do not follow the rules in Section 6. 🚫
  • Addition of REQUIRED new features. this one is a big deal 🌈👑
  • Changes to the status of existing features including converting features to be mandatory to not implement. 🗝️

8. Minor Version Interaction Rules 🫶

This section addresses issues related to rules #11 and #13 in the minor versioning rules in [RFC5661]. With regard to the supersession of minor versioning rules, the treatment here overrides that in [RFC5661] when either of the potentially interacting minor versions has not yet been published as a Proposed Standard. 💫

Note that these rules are the only ones directed to minor version implementers, rather than to those specifying new minor versions. this part is for the implementers, babes 🧚

8.1. Minor Version Identifier Transfer Issues 🦋

Okay so every client-server relationship (aka the clientid 🆔) is basically devoted to ONE minor version 💍 no cheating allowed. If a server spots a COMPOUND using the wrong minor version, it MUST reject the request 🚫. When it does that, it can send back either NFS4ERR_BAD_CLIENTID or NFS4RR_MINOR_VERS_MISMATCH (yes, that's how it's spelled in the spec 🙈).

ngl this matters a lot 🫶 because it gives the client the assurance that the set of REQUIRED and OPTIONAL features won't shift within a single clientid. Server implementations MUST ensure that the set of supported features and protocol elements does not change inside that context. Stable vibes only, bestie 🔒

8.2. Minor Version Compatibility 🌈

The whole goal of the NFSv4 extension model is to enable compatibility 💖, including compatibility between clients and servers running different minor versions.

Within a set of minor versions that define the same set of features as REQUIRED and as mandatory to not implement, it's pretty easy for clients and servers to stay compatible by following these practices:

  • Servers supporting a given minor version should support earlier minor versions within that set, and return appropriate errors when someone uses protocol elements that weren't a valid part of that earlier version. More on this below 👀
  • Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by searching for a lower minor version number that the server will accept 🔍

Servers supporting a given minor version MUST, when returning errors for operations that were a valid part of that minor version, return the errors allowed for the current operation in the minor version actually being used. Consistency is everything 💅

For protocol elements that aren't known in a given minor version, the right error codes are listed below. Basically, the server might have a fancier XDR from a newer minor version 🧚, but it still has to act like a server with the more limited XDR would.

  • When an operation that isn't known in the specified minor version is used, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP) should be returned.
  • When an attribute that isn't known in the specified minor version is used, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP) should be returned.
  • When a switch case that isn't known in the specified minor version is used, NFS4ERR_BADXDR (as opposed to NFS4ERR_UNION_NOTSUPP) should be returned. Even if the message is XDR-decodable by the server's current XDR, it isn't according to the minor version being used 🙅‍♀️
  • When a flag bit that isn't known in the specified minor version is used, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP or any other error defined as indicating non-support of a flag bit) should be returned.

9. Correction of Existing Minor Versions and Features 🛠️✨

There's always a chance that a feature will need a fix after it's been accepted as a Proposed Standard, or after a minor version containing it has been. The working group can lower the odds by waiting for running code before calling a feature done, but it can't get them to zero 😭 As features get used more and interact with other features, sneaky flaws show up and need to be corrected 🐛

Corrections are best made in a document that obsoletes or updates the RFC defining the relevant feature or minor version 📜 While making them, the working group has to carefully think about how to keep things interoperable with older clients and servers 🫶

Often, corrections can happen without changing the protocol XDR 🎉 In lots of cases, a change in client and server behavior can be rolled out without any special provision for interoperability with earlier implementations. In those cases, and in cases where a revision just clarifies an earlier protocol definition document, a new document can simply update the earlier one 💜

Other times, it's best if client or server behavior changes in a way that raises interoperability concerns. In those cases, incompatible changes in server or client behavior should not be mandated just to avoid XDR changes (no sacrificing the vibe for convenience 🙅‍♀️)

9.1. XDR Changes to Implement Protocol Corrections 💅

When XDR changes are needed to fix a flaw, they should be done in a way similar to how new minor versions or features within them get implemented. Specifically:

  • Existing XDR structures may not be modified or deleted 🚫
  • XDR extensions may be used to correct existing protocol facilities, in a manner similar to how additional optional features are added. Such corrections may be done in a minor version for which optional features may no longer be added, if the working group decides that's an appropriate way to compatibly effect a correction 🧩
  • When a correction is made to an OPTIONAL feature, the result is similar to having two independent OPTIONAL features. A server may choose to implement either or both. See Section 9.2 for a detailed discussion of interoperability issues 👯
  • When a correction is made to a REQUIRED feature, the old version stays REQUIRED while the corrected version, though OPTIONAL, is meant to be adopted to provide correct operation. Using the corrected version is ultimately better and may be recommended, but it should not be described as "RECOMMENDED" 🙃 since which versions to support depends on the needs of clients, and clients may be slow to adopt the updated version. This kind of correction can mean that different variants of the same minor version don't both support the corrected version. See Section 9.3 for details 🌸
  • In all of the cases above, it's appropriate for the old version to be considered obsolescent, with the expectation that the working group might change the status of the uncorrected version in a later minor version. See Section 9.4 for more detail ⏳

9.2. XDR Corrections to OPTIONAL Features 🎀

By defining the corrected and uncorrected versions as independent OPTIONAL features, the protocol with the XDR modification can accommodate clients and servers that support either version, plus clients and servers that are aware of and capable of supporting both alternatives 🦋

Based on the type of client:

  • An older client that only uses the earlier version of the feature (i.e., an older unfixed client) can determine whether the server it's connecting to supports the older version of the feature. It can interoperate with older servers that only support the unfixed protocol, as well as ones that support both versions 🫠
  • A client that only supports the corrected version of the feature (i.e., a new or updated client) can determine whether the server it's connecting to supports the newer version. It can interoperate with newer servers that only support the updated feature, as well as ones that support both versions 💫
  • A client that supports both the older and newer version of the feature can determine which version of the particular feature is supported by the server it's working with 🧠

Based on the type of server:

  • A server that only supports the earlier version of the feature (i.e., an older unfixed server) can only successfully interoperate with clients implementing the older version. However, clients that don't implement the older version can easily determine that the feature can't be used on that server 🙈
  • A server that only supports the newer version of the feature (i.e., a new or updated server) can only successfully interoperate with newer clients. However, older clients can easily determine that the feature can't be used on that server. In the case of OPTIONAL features, clients can be expected to deal with non-support of that particular feature 🤷‍♀️
  • A server that supports both the older and newer versions of the feature can interoperate with all client variants 👑

By using extensions in this way, the protocol creates a clear path that keeps existing clients and servers working, and lets client and server implementers adopt the new version of the feature at a reasonable pace 🌈✨

9.3. XDR Corrections to REQUIRED Features ⭐

Interoperability issues in this case are similar to those for the OPTIONAL case described above (in Section 9.2). However, because use of the uncorrected version is REQUIRED, servers have to support it until there's a minor version change 😤 Still, there's the chance for clients and servers to implement the corrected version while keeping the necessary interoperability with earlier implementations 🫶

The following types of servers can exist:

  • Servers that are only aware of and support the uncorrected version, such as servers developed before the issue requiring correction was known 🕰️
  • Servers that are aware of both versions while only supporting the uncorrected version
  • Servers that are aware of and support both versions 💖

With the exception of clients that don't use the feature in question, the following sorts of clients may exist:

  • Clients that are only aware of and prepared to use the uncorrected version, such as those developed before the issue requiring correction was known. Clients developed before the correction was defined would be of this type. They would be capable of interoperating with all of the types of servers listed above, but couldn't use the corrected version 🥹
  • Clients that are aware of both versions while only prepared to use the uncorrected version. Some clients developed or modified after the correction was defined would be of this type, until they were modified to support the corrected version. They would also be capable of interoperating with all of the types of servers listed above, but couldn't use the corrected version 🧃
  • Clients that are aware of and prepared to use either version. These clients would be capable of interoperating with all of the types of servers listed above, and could use the corrected version with servers that support it 🎁
  • Clients that are aware of both versions while only prepared to use the newer, corrected version. These clients would only be capable of interoperating with servers that support the corrected version. With other types of servers, they could determine the absence of appropriate support at an early stage and treat the minor version in question as unsupported by the server. Such clients are only likely to be deployed when the majority of servers support the corrected version 🚀

9.4. Addressing XDR Corrections in Later Minor Versions ✨

Okay so bestie, remember how Sections 9.2 and 9.3 talked about corrected XDR? 🎀 A corrected XDR can get tucked into an existing minor version and be used, while the uncorrected version is still supported 💅. Ngl that's a whole glow-up, but the uncorrected version stays part of the protocol until a later minor version changes its status 🫶.

One move a later minor version could make is defining the uncorrected version as mandatory to not implement. 💀 It's unlikely that would be appropriate for a considerable time, because it's super hard to figure out whether no clients depend on the uncorrected version 😭.

If we're correcting a REQUIRED feature, there are a few less disruptive changes we could make earlier 🦋:

  • Changing the uncorrected version from REQUIRED to OPTIONAL while REQUIRING that servers support at least one of the two versions. This would let new server implementations skip support for the uncorrected version 🌸.
  • Changing the corrected version from OPTIONAL to REQUIRED, making both versions REQUIRED. This would let new clients depend on the corrected version being present 👑.
  • Changing the uncorrected version from REQUIRED to OPTIONAL while changing the corrected version from OPTIONAL to REQUIRED. This would complete the shift to the corrected version once clients are ready to use it 🔥.

In making such changes, interoperability issues would need to be carefully considered. 🧚

10. Security Considerations 🔐

Since no substantive protocol changes are proposed here, no security considerations apply.

11. IANA Considerations 🌈

The current document does not require any IANA actions.

12. References 📚

12.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC5661]  Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed.,
           "Network File System (NFS) Version 4 Minor Version 1
           Protocol", RFC 5661, DOI 10.17487/RFC5661, January 2010,
           <http://www.rfc-editor.org/info/rfc5661>.

[RFC7530]  Haynes, T., Ed. and D. Noveck, Ed., "Network File System
           (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530,
           March 2015, <http://www.rfc-editor.org/info/rfc7530>.

[RFC7862]  Haynes, T., "Network File System (NFS) Version 4 Minor
           Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862,
           November 2016, <http://www.rfc-editor.org/info/rfc7862>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <http://www.rfc-editor.org/info/rfc8174>.

12.2. Informative References

[RFC3530]  Shepler, S., Callaghan, B., Robinson, D., Thurlow, R.,
           Beame, C., Eisler, M., and D. Noveck, "Network File System
           (NFS) version 4 Protocol", RFC 3530, DOI 10.17487/RFC3530,
           April 2003, <http://www.rfc-editor.org/info/rfc3530>.

Acknowledgements 🫶

The author wishes to thank Tom Haynes of Primary Data for his role in getting the effort to revise NFSV4 version management started and for his work in coauthoring the first draft version of this document.

The author also wishes to thank Chuck Lever and Mike Kupfer of Oracle, and Bruce Fields of Red Hat for their helpful reviews of this and other versioning-related documents.

Author's Address 💌

David Noveck
NetApp
1601 Trapelo Road
Waltham, MA  02451
United States of America

Phone: +1 781 572 8038
Email: davenoveck@gmail.com

And that's the whole thing, bestie! 💜 Every version, every correction, every bullet point, all accounted for. Periodt. ✨

📦 where this page comes from