Minor versioning Rules for NFSv4
draft-haynes-nfsv4-versioning-00

NFSv4                                                          T. Haynes
Internet-Draft                                              Primary Data
Intended status: Standards Track                          D. Noveck, Ed.
Expires: April 9, 2015
                                                        October 06, 2014

                    Minor versioning Rules for NFSv4
                    draft-haynes-nfsv4-versioning-00

Abstract

   This document specifies the minor versioning rules for NFSv4.  It
   also specifies how those minor versioning rules may be modified.

Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on April 9, 2015.

Copyright Notice

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

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect

Haynes & Noveck           Expires April 9, 2015                 [Page 1]
Internet-Draft                    NFSv4                     October 2014

   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Modifying the minor version rules . . . . . . . . . . . . . .   3
   4.  The minor versioning rules  . . . . . . . . . . . . . . . . .   3
   5.  Extensions within Minor Versions  . . . . . . . . . . . . . .   6
     5.1.  Feature Specification Documents . . . . . . . . . . . . .   6
     5.2.  Additional Informational Documents  . . . . . . . . . . .   9
     5.3.  Relationship Between Minor versioning and Extensions
           within a Minor Version  . . . . . . . . . . . . . . . . .  10
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  11
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  11
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  11
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  11
   Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . .  11
   Appendix B.  RFC Editor Notes . . . . . . . . . . . . . . . . . .  11
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  12

1.  Introduction

   To address the requirement of an NFS protocol that can evolve as the
   need arises, the Network File System (NFS) version 4 (NFSv4) protocol
   contains the rules and framework to allow for future minor changes or
   versioning.

   The base assumption with respect to minor versioning is that any
   future accepted minor version will be documented in one or more
   Standards Track RFCs.  Minor version 0 of the NFSv4 protocol is
   represented by [RFC3530], minor version 1 by [RFC5661], and minor
   version 2 by [NFSv42].  The COMPOUND (see Section 14.2 of [RFC3530])
   and CB_COMPOUND (see Section 15.2 of [RFC3530]) procedures support
   the encoding of the minor version being requested by the client.

2.  Terminology

   A basic familiarity with the NFSv4 terminology is assumed in this
   document, the reader is pointed to [RFC3530].

Haynes & Noveck           Expires April 9, 2015                 [Page 2]
Internet-Draft                    NFSv4                     October 2014

3.  Modifying the minor version rules

   The minor versioning rules had been being maintained inside the
   various Standards Track RFCs, which had the impact of the minor
   versioning rules being modified as needed per release of the minor
   versions.  The rules for minor versions SHOULD stand outside the
   minor versions and be tracked by their own Standard Track RFCs.  As
   such, all modifications to the minor versioning rules MUST be
   documented not in the minor version documents, but in Standard Track
   RFCs which are focused entirely on the minor versioning rules
   themselves.

4.  The minor versioning rules

   The following items represent the basic rules for the development of
   minor versions.

   1.   Procedures are not added or deleted.

        To maintain the general Remote Procedure Call (RPC) model, NFSv4
        minor versions will not add to or delete procedures from the NFS
        program.

   2.   Minor versions may add operations to the COMPOUND and
        CB_COMPOUND procedures.

        The addition of operations to the COMPOUND and CB_COMPOUND
        procedures does not affect the RPC model.

        *  Minor versions may append attributes to the bitmap4 that
           represents sets of attributes and to the fattr4 that
           represents sets of attribute values.

           This allows for the expansion of the attribute model to allow
           for future growth or adaptation.

        *  Minor version X must append any new attributes after the last
           documented attribute.

           Since attribute results are specified as an opaque array of
           per-attribute, XDR-encoded results, the complexity of adding
           new attributes in the midst of the current definitions would
           be too burdensome.

   3.   Minor versions must not modify the structure of an existing
        operation's arguments or results.

Haynes & Noveck           Expires April 9, 2015                 [Page 3]
Internet-Draft                    NFSv4                     October 2014

        Again, the complexity of handling multiple structure definitions
        for a single operation is too burdensome.  New operations should
        be added instead of modifying existing structures for a minor
        version.

        This rule does not preclude the following adaptations in a minor
        version:

        *  adding bits to flag fields, such as new attributes to
           GETATTR's bitmap4 data type, and providing corresponding
           variants of opaque arrays, such as a notify4 used together
           with such bitmaps

        *  adding bits to existing attributes like Access Control Lists
           (ACL) that have flag words

        *  extending enumerated types (including NFS4ERR_*) with new
           values

        *  adding cases to a switched union

   4.   Note that when adding new cases to a switched union, a minor
        version must not make new cases be REQUIRED.  While the
        encapsulating operation may be REQUIRED, the new cases (the
        specific arm of the discriminated union) is not.  The error code
        NFS4ERR_UNION_NOTSUPP is used to notify the client when the
        server does not support such a case.

   5.   Minor versions must not modify the structure of existing
        attributes.

   6.   Minor versions must not delete operations.

        This prevents the potential reuse of a particular operation
        "slot" in a future minor version.

   7.   Minor versions must not delete attributes.

   8.   Minor versions must not delete flag bits or enumeration values.

   9.   Minor versions may declare an operation MUST NOT be implemented.

        Specifying that an operation MUST NOT be implemented is
        equivalent to obsoleting an operation.  For the client, it means
        that the operation MUST NOT be sent to the server.  For the
        server, an NFS error can be returned as opposed to "dropping"

Haynes & Noveck           Expires April 9, 2015                 [Page 4]
Internet-Draft                    NFSv4                     October 2014

        the request as an XDR decode error.  This approach allows for
        the obsolescence of an operation while maintaining its structure
        so that a future minor version can reintroduce the operation.

        1.  Minor versions may declare that an attribute MUST NOT be
            implemented.

        2.  Minor versions may declare that a flag bit or enumeration
            value MUST NOT be implemented.

   10.  Minor versions may declare an operation to be OBSOLESCENT, which
        indicates an intention to remove the operation (i.e., make it
        MANDATORY TO NOT implement) in a subsequent minor version.  Such
        labeling is separate from the question of whether the operation
        is REQUIRED or RECOMMENDED or OPTIONAL in the current minor
        version.  An operation may be both REQUIRED for the given minor
        version and marked OBSOLESCENT, with the expectation that it
        will be MANDATORY TO NOT implement in the next (or other
        subsequent) minor version.

   11.  Note that the early notification of operation obsolescence is
        put in place to mitigate the effects of design and
        implementation mistakes, and to allow protocol development to
        adapt to unexpected changes in the pace of implementation.  Even
        if an operation is marked OBSOLESCENT in a given minor version,
        it may end up not being marked MANDATORY TO NOT implement in the
        next minor version.  In unusual circumstances, it might not be
        marked OBSOLESCENT in a subsequent minor version, and never
        become MANDATORY TO NOT implement.

   12.  Minor versions may downgrade features from REQUIRED to
        RECOMMENDED, from RECOMMENDED to OPTIONAL, or from OPTIONAL to
        MANDATORY TO NOT implement.  Also, if a feature was marked as
        OBSOLESCENT in the prior minor version, it may be downgraded
        from REQUIRED to OPTIONAL from RECOMMENDED to MANDATORY TO NOT
        implement, or from REQUIRED to MANDATORY TO NOT implement.

   13.  Minor versions may upgrade features from OPTIONAL to
        RECOMMENDED, or RECOMMENDED to REQUIRED.  Also, if a feature was
        marked as OBSOLESCENT in the prior minor version, it may be
        upgraded to not be OBSOLESCENT.

   14.  A client and server that support minor version X SHOULD support
        minor versions 0 through X-1 as well.

Haynes & Noveck           Expires April 9, 2015                 [Page 5]
Internet-Draft                    NFSv4                     October 2014

   15.  Except for infrastructural changes, a minor version must not
        introduce REQUIRED new features.

        This rule allows for the introduction of new functionality and
        forces the use of implementation experience before designating a
        feature as REQUIRED.  On the other hand, some classes of
        features are infrastructural and have broad effects.  Allowing
        infrastructural features to be RECOMMENDED or OPTIONAL
        complicates implementation of the minor version.

   16.  A client MUST NOT attempt to use a stateid, filehandle, or
        similar returned object from the COMPOUND procedure with minor
        version X for another COMPOUND procedure with minor version Y,
        where X != Y.

5.  Extensions within Minor Versions

   An important goal of this document is to enable extensions to be made
   to the features included in an existing minor version, without the
   overhead attendant upon the creation of an entirely new minor
   version.

5.1.  Feature Specification Documents

   Each such extension will be in the form of a working-group standards-
   track document which defines a new optional feature.  The definition
   of the new feature may include one or more "feature elements" which
   add to the existing XDR in ways already used in creating new minor
   versions.  Other sorts of XDR modification are not allowed.  Feature
   elements include new operations, callbacks, attributes, and
   enumeration values.  The functionality of some existing operations
   may be extended by the addition of new flags bits 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 returned by an
   operation is fixed, except that existing operations may return new
   errors to respond to situations that only arise when previously
   unused flag bits are set or when extensions to a switched union are
   used.

   Such an additional feature will become, for all intents and purposes,
   part of the current NFSv4 minor version upon publication of the
   description as a Proposed Standard, enabling such extensions to be
   used by new client and server implementations without, as previously
   required, a change in the value of the minorversion field within the
   COMPOUND operation.

   The working group has two occasions to make sure that such features
   are appropriate ones:

Haynes & Noveck           Expires April 9, 2015                 [Page 6]
Internet-Draft                    NFSv4                     October 2014

   o  At the time the feature definition document becomes a working
      group document, the working group needs to determine, in addition
      to the feature's general compatibility with NFSv4, that the XDR
      assignments (i.e., additional values for operation callback and
      attribute numbers, and for new flags and switch values to be added
      to existing operations) associated with the new feature are
      complete and do not conflict with those in the existing protocol
      or those currently under development.

   o  At the time the working group document is complete, the working
      group, in addition to, normal document review, can and should look
      at what prototype implementations of the feature have been done
      and use that information to determine the work-ability of the
      feature.

   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 in NFSv4.2, the feature
   definition documents would each define a single feature.

   Such feature definition documents would contain a number of In
   addition to a general explanation of the feature in question, the
   items to be included in such feature definition documents would be:

   o  Description of new operations (corresponding to sections 16 and 17
      of [NFSv42]).

   o  Description of any modified operations (corresponding to section
      15 of [NFSv42]).

   o  Description of new attributes (corresponding to section 13 of
      [NFSv42]).

   o  Description of any added error codes (corresponding to section
      12.1 of [NFSv42]).

   o  A summary description all changes made by this feature to the xdr
      definition of the protocol, including operation codes, attribute
      numbers, added flag bits and enumeration values, and request and
      response structures for new operation together with the other xdr
      extensions needed to support them.

   o  A listing giving the valid errors for each new operation and
      callback (corresponds to sections 12.2 and 12.3 of [NFSv42]).

   o  A table giving for each new feature element its status (always
      OPTIONAL), and its relationship to the feature being described

Haynes & Noveck           Expires April 9, 2015                 [Page 7]
Internet-Draft                    NFSv4                     October 2014

      (i.e., REQUIRED for every implementation of the feature, or
      OPTIONAL in the presence of the feature).  This would be similar
      to the material in section 14 of [NFSv42] but it is restricted to
      a single feature and expanded in scope to include all feature
      elements.

   o  All of the sections required for RFC publication, such as
      "Security Considerations", "IANA considerations", etc.

   Such feature definition documents would contain a number of Addition
   of features to an existing minor version will take advantage of the
   existing NFSv4 infrastructure that allows optional features to be
   added to new minor versions, but without in this case requiring any
   change the version number.  This will enable compatibility with
   existing clients and servers.  In particular:

   o  Existing server implementations will return NFS4ERR_NOTSUPP or
      NFS4ERR_OP_ILLEGAL in response to any use of the new operation,
      allowing the client to determine that the requested (and
      potentially the feature in question) is not supported by the
      server.

   o  Clients can determine whether particular new attributes are
      supported by a given server by examining the value returned as the
      value of the supported_attr attribute.

   o  New callbacks will only be sent to clients that have used the new
      features associated with them, allowing existing clients to be
      unaware of their existence.

   o  Existing server implementations that do not recognize new flag
      bits will return NFS4ERR_INVAL, enabling the client to determine
      that the new flag value is not supported by the server.

   o  Existing server implementations that do not recognize the new arm
      of a switched union will return will return NFS4ERR_INVAL or
      NFS4ERR_UNION_NOTSUPP, enabling the client to determine that the
      the new union arm is not supported by the server.

   o  Error values returned to the client for all requests that do not
      use new features will only be those previously allowed.  Only when
      the client uses a new feature will a previously invalid error
      value be returned.

   Given that some existing servers may have XDR parsing implementations
   that cannot easily accommodate previously unknown operations or
   switched union arms, clients should carefully determine whether
   particular features are supported by the server before proceeding to

Haynes & Noveck           Expires April 9, 2015                 [Page 8]
Internet-Draft                    NFSv4                     October 2014

   use them and need to be prepared to treat NFS4ERR_BADXDR as
   indicating non-support of a new operation or switched union arm where
   server support for a particular feature is being tested.

5.2.  Additional Informational Documents

   Additional documents will be required from time to time.  The purpose
   of these documents will be to organize existing material so that an
   implementer will not have to scan a large set of feature definition
   document or minor version specification to find information being
   sought.

   The frequency of updates for such documents will be affected by
   implementer needs and the ability to easily generate such documents,
   preferably by automated means.  These documents will be informational
   documents whose purpose is to simplify use of the standards-track
   documents.  Some desirable elements would include:

   o  An updated XDR for the protocol as a whole including feature
      elements from all features accepted as Proposed Standards.

   o  A consolidated list of XDR assignments of values (e.g., operation
      codes, attribute numbers, error codes, new flag bits, enumeration
      extensions) for all features under development (i.e., accepted as
      working-group standards-track documents but not yet published or
      abandoned).

   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  A table mapping operations and callbacks to the most recent
      document containing a description of that operation.

   o  A table mapping attributes to the most recent 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
      OPTIONAL, REQUIRED, RECOMMENDED, MANDATORY to NOT implement), and
      its relationship to the feature which allows its inclusion (i.e.,
      REQUIRED for every implementation of the feature, or OPTIONAL in
      the presence of the feature).  This would be similar to the

Haynes & Noveck           Expires April 9, 2015                 [Page 9]
Internet-Draft                    NFSv4                     October 2014

      material in section 14 of [NFSv42], expanded in scope to include
      all feature elements, and updated to include all published
      features that are part of the current NFSv4 minor version, at the
      date of publication.

5.3.  Relationship Between Minor versioning and Extensions within a
      Minor Version

   The extensibility of minor versions are governed by the following
   rules:

   o  Minor versions zero and one are not extensible.  Each has a fixed
      set of optional features as described in [RFC3530bis] and
      [RFC5661].

   o  Minor versions beyond one are presumed extensible as discussed
      herein.  However, any statement within the minor version
      specification disallowing extension will cause that minor version
      to be considered non-extensible.

   o  No extension to a minor version may be made once the specification
      document for a subsequent minor version becomes a working group
      standards-track document.

   While making minor versions extensible will decrease the frequency of
   new minor versions, it will not eliminate the need for them.  In
   particular,

   o  A new minor version will be required for any change in the status
      of a feature element (i.e., an operation, callback, attribute,
      added flag or switch case).  For example, changes which make
      operations Recommended, Required or Mandatory to Not Implement
      will require a minor version.

   o  Any incompatible semantic change in the required or allowed
      processing of an existing operation or attribute will require a
      minor version.

   o  Any change that extends the set of operations that an existing
      operation, with the exception noted above.  New errors may be
      added when the conditions that give rise to these new errors
      cannot arise as long as new flag bits or switched union arms are
      not used.  I.e., when it is clear that existing client cannot
      receive these errors.

   o  Any change in the mapping of feature elements to features will
      require a minor version.  For example, if a feature is to be split
      into two separate features clients would no longer be able to

Haynes & Noveck           Expires April 9, 2015                [Page 10]
Internet-Draft                    NFSv4                     October 2014

      infer support for one operation from support for the other, in the
      same way that had been done previously, invalidating logic in
      existing clients.

6.  Security Considerations

   There are no security considerations in this document.

7.  IANA Considerations

   There are no IANA considerations in this document.

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", March 1997.

   [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, April 2003.

   [RFC3530bis]
              Haynes, T. and D. Noveck, "Network File System (NFS)
              version 4 Protocol", draft-ietf-nfsv4-rfc3530bis-33 (Work
              In Progress), April 2014.

   [RFC5661]  Shepler, S., Eisler, M., and D. Noveck, "Network File
              System (NFS) Version 4 Minor Version 1 Protocol", RFC
              5661, January 2010.

8.2.  Informative References

   [NFSv42]   Haynes, T., "NFS Version 4 Minor Version 2", draft-ietf-
              nfsv4-minorversion2-27 (Work In Progress), September 2014.

Appendix A.  Acknowledgments

Appendix B.  RFC Editor Notes

   [RFC Editor: please remove this section prior to publishing this
   document as an RFC]

   [RFC Editor: prior to publishing this document as an RFC, please
   replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the
   RFC number of this document]

Haynes & Noveck           Expires April 9, 2015                [Page 11]
Internet-Draft                    NFSv4                     October 2014

Authors' Addresses

   Thomas Haynes
   Primary Data, Inc.
   4300 El Camino Real Ste 100
   Los Altos, CA  94022
   USA

   Phone: +1 408 215 1519
   Email: thomas.haynes@primarydata.com

   David Noveck (editor)
   26 Locust Ave
   Lexington, MA  02421
   US

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

Haynes & Noveck           Expires April 9, 2015                [Page 12]