Rules for NFSv4 Extensions and Minor Versions
draft-ietf-nfsv4-versioning-08

Internet-Draft               NFSv4 Extension               December 2016

   Within a set of minor versions that define the same set of features
   as REQUIRED and mandatory to not implement, it is relatively easy for
   clients and servers to provide the needed compatibility by adhering
   to the following practices.

   o  Servers supporting a given minor version should support earlier
      minor versions within that set and return appropriate errors for
      use of protocol elements that were not a valid part of that
      earlier minor version.  For details see below.

   o  Clients should deal with an NFS4ERR_MINOR_VERS_MISMATCH error by
      searching for a lower minor version number that the server will
      accept.

   Servers supporting a given minor version MUST, in returning errors
   for operations which were a valid part of the minor version, return
   the errors allowed for the current operation in the minor version
   actually being used.

   With regard to protocol elements not known in a given minor version,
   the appropriate error codes are given below.  Essentially, the
   server, although it has a more extensive XDR reflective of a newer
   minor version, must act as a server with a more limited XDR would.

   o  When an operation is used which is not known in the specified
      minor version, NFS4ERR_OP_ILLEGAL (as opposed to NFS4ERR_NOTSUPP)
      should be returned.

   o  When an attribute is used which is not known in the specified
      minor version, NFS4ERR_INVAL (as opposed to NFS4ERR_ATTRNOTSUPP)
      should be returned.

   o  When a switch case is used which is not known in the specified
      minor version, NFS4ERR_BADXDR (as opposed to
      NFS4ERR_UNION_NOTSUPP) should be returned.  Even though the
      message may be XDR-decodable by the server's current XDR, it is
      not so according to the minor version being used.

   o  When a flag bit is used which is not known in the specified minor
      version, NFS4ERR_INVAL (as opposed to NFS4ERR_NOTSUPP or any other
      error defined as indicating non-support of a flag bit) should be
      returned.

9.  Correction of Existing Minor Versions and Features

   The possibility always exists that there will be a need to correct an
   existing feature in some way, after the acceptance of that feature,
   or a minor version containing it, as a Proposed Standard.  While the

Noveck                    Expires June 6, 2017                 [Page 19]
Internet-Draft               NFSv4 Extension               December 2016

   working group can reduce the probability of such situations arising
   by waiting for running code before considering a feature as done, it
   cannot reduce the probability to zero.  As features are used more
   extensively and interact with other features, previously unseen flaws
   may be discovered and will need to be corrected.

   Such corrections are best done in a document obsoleting or updating
   the RFC defining the relevant feature or minor version.  In making
   such corrections, the working group will have to carefully consider
   how to assure interoperability with older clients and servers.

   Often, corrections can be done without changing the protocol XDR.  In
   many cases, a change in client and server behavior can be implemented
   without taking special provision with regard to interoperability with
   earlier implementations.  In those cases, and in cases in which a
   revision merely clarifies an earlier protocol definition document, a
   new document can be published which simply updates the earlier
   protocol definition document.

   In other cases, it is best if client or server behavior needs to
   change in a way which raises interoperability concerns.  In such
   cases, incompatible changes in server or client behavior should not
   be mandated in order to avoid XDR changes.

9.1.  XDR Changes to Implement Protocol Corrections

   When XDR changes are necessary as part of correcting a flaw, these
   should be done in a manner similar to that used when implementing new
   minor versions or features within them.  In particular,

   o  Existing XDR structures may not be modified or deleted.

   o  XDR extensions may be used to correct existing protocol facilities
      in a manner similar to those used to add additional optional
      features.  Such corrections may be done in a minor version for
      which optional features may no longer be added, if the working
      group decides that it is an appropriate way to compatibly effect a
      correction.

   o  When a correction is made to an OPTIONAL feature, the result is
      similar to a situation in which there are two independent OPTIONAL
      features.  A server may choose to implement either or both.  See
      Section 9.2 for a detailed discussion of interoperability issues.

   o  When a correction is made to a REQUIRED feature, the situation
      becomes one in which the old version of the feature remains
      REQUIRED while the corrected version, while OPTIONAL, in intended
      to be adopted to provide correct operation.  Although use of the

Noveck                    Expires June 6, 2017                 [Page 20]
Internet-Draft               NFSv4 Extension               December 2016

      corrected version is ultimately better, and may be recommended, it
      should not be described as "RECOMMENDED", since the choice of
      versions to support will depend on the needs of clients, which may
      be slow to adopt the updated version.  The nature of such
      corrections is such that it may result in situations in which
      different variants of the same minor version may not support both
      support the corrected version.  See Section 9.3 for details.

   o  In all of the cases above, it is appropriate that the old version
      of the feature be considered obsolescent, with the expectation
      that the working group might, in a later minor version, change the
      status of the uncorrected version.  See Section 9.4 for more
      detail.

9.2.  XDR Corrections to OPTIONAL features

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

   Based on the type of client:

   o  A client that uses only the earlier version of the feature (i.e.,
      an older unfixed client) can determine whether the server it is
      connecting to supports the older version of feature.  It is
      capable of interoperating with older servers that support only the
      unfixed protocol as well as ones that support both versions.

   o  A client that supports only the corrected version of the feature
      (i.e., a new or updated client) can determine whether the server
      it is connecting to supports the newer version of the feature.  It
      is capable of interoperating with newer servers that support only
      the updated feature as well as ones that support both versions.

   o  A client that supports both the older and newer version of the
      feature can determine which version of the particular feature is
      supported by the server it is working with.

   Based on the type of server:

   o  A server that supports only the earlier version of the feature
      (i.e., an older unfixed server) can only successfully interoperate
      with older clients.  However newer clients can easily determine
      that the feature cannot be used on that server.

Noveck                    Expires June 6, 2017                 [Page 21]
Internet-Draft               NFSv4 Extension               December 2016

   o  A server that supports only the newer version of the feature
      (i.e., a new or updated server) can only successfully interoperate
      with newer clients.  However, older clients can easily determine
      that the feature cannot be used on that server.  In the case of
      OPTIONAL features, clients can be expected to deal with non-
      support of that particular feature.

   o  A server that supports both the older and newer versions of the
      feature can interoperate with all client variants.

   By using extensions in this manner, the protocol creates a clear path
   which preserves the functioning of existing clients and servers and
   allows client and server implementers to adopt the new version of the
   feature at a reasonable pace.

9.3.  XDR Corrections to REQUIRED features

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

   The following types of servers can exist:

   o  Servers only aware of and supporting the uncorrected version, such
      as servers developed before the issue requiring correction was
      known.

   o  Servers aware of both versions while only supporting the
      uncorrected version.

   o  Servers aware of and supporting both versions.

   With the exception of clients which do not use the feature in
   question, the following sorts of clients may exist:

   o  Clients only aware of and prepared to use the uncorrected version,
      such as those developed before the issue requiring correction was
      known.

      Clients developed before the correction was defined would be of
      this type.  They would be capable of interoperating with all of
      the types of servers listed above, but could not use the corrected
      version.

Noveck                    Expires June 6, 2017                 [Page 22]
Internet-Draft               NFSv4 Extension               December 2016

   o  Clients aware of both versions while only prepared to use the
      uncorrected version.

      Some clients developed or modified after the correction was
      defined would be of this type, until they were modified to support
      the corrected version.  They would also be capable of
      interoperating with all of the types of servers listed above, but
      could not use the corrected version.

   o  Clients aware of and prepared to use either version.

      Such clients would be capable of interoperating with all of the
      types of servers listed above, and could use the corrected version
      with servers that supported it.

   o  Clients aware of both versions while only prepared to use the
      newer, corrected, version.

      Such clients would only be capable of interoperating with servers
      that supported the correct version.  With other types of server,
      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

   As described in Sections 9.2 and 9.3, a corrected XDR can be
   incorporated in an existing minor version and be used, while an
   existing uncorrected version is still supported.  Nevertheless, the
   uncorrected version will remain part of the protocol until its status
   is changed in a later minor version.

   One possible change that could be made in a later minor version is to
   define the uncorrected version as mandatory to not implement.
   Because of the difficulty of determining that no clients depend on
   support for the uncorrected version, it is unlikely that this step
   would be appropriate for a considerable time.

   In the case of a correction to a REQUIRED feature, there are a number
   of less disruptive changes that could be made earlier:

   o  Changing the uncorrected version from REQUIRED to OPTIONAL while
      REQUIRING that servers support at least one of the two versions.

      This would allow new server implementations to avoid support for
      the uncorrected version.

Noveck                    Expires June 6, 2017                 [Page 23]
Internet-Draft               NFSv4 Extension               December 2016

   o  Changing the corrected version from OPTIONAL to REQUIRED, making
      both versions REQUIRED.

      This would allow new clients to depend on support for the
      corrected version being present.

   o  Changing the uncorrected version from REQUIRED to OPTIONAL while
      changing the corrected version from OPTIONAL to REQUIRED.

      This would complete the shift to the corrected version once
      clients are prepared to use the corrected version.

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

10.  Security Considerations

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

11.  IANA Considerations

   The current document does not require any actions by IANA.

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>.

Noveck                    Expires June 6, 2017                 [Page 24]
Internet-Draft               NFSv4 Extension               December 2016

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>.

Appendix A.  Acknowledgements

   The author wishes to thank Tom Haynes of Primary Data for his role in
   getting the effort to revise NFSV4 version magement started and for
   his work in co-authoring the first version of this document.

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

Author's Address

   David Noveck
   Hewlett Packard Enterprise
   165 Dascomb Road
   Andover, MA  01810
   US

   Phone: +1 978 474 2011
   Email: davenoveck@gmail.com

Noveck                    Expires June 6, 2017                 [Page 25]