Skip to main content

NFSv4 Version Management
draft-ietf-nfsv4-versioning-00

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 8178.
Expired & archived
Authors Thomas Haynes , David Noveck
Last updated 2015-05-15 (Latest revision 2014-11-11)
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state Became RFC 8178 (Proposed Standard)
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-nfsv4-versioning-00
NFSv4                                                          T. Haynes
Internet-Draft                                              Primary Data
Intended status: Standards Track                               D. Noveck
Expires: May 15, 2015                                               Dell
                                                       November 11, 2014

                        NFSv4 Version Management
                     draft-ietf-nfsv4-versioning-00

Abstract

   This document describes the management of versioning within the NFSv4
   family of protocols.  It covers the creation of minor versions, the
   addition of OPTIONAL features to existing minor versions, and the
   correction of flaws in features already published as Proposed
   Standards.  The rules for minor versioning set out in this document
   supersede the multiple sets of minor versioning rules in RFC3530 and
   RFC5661.

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 May 15, 2015.

Copyright Notice

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

Haynes & Noveck           Expires May 15, 2015                  [Page 1]
Internet-Draft          NFSv4 Version Management           November 2014

   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
   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 . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Consolidation of the Minor Version Rules  . . . . . . . . . .   3
   4.  The Minor Versioning Rules  . . . . . . . . . . . . . . . . .   4
   5.  Extensions within Minor Versions  . . . . . . . . . . . . . .   7
     5.1.  Feature Specification Documents . . . . . . . . . . . . .   7
       5.1.1.  Compatibility Issues for Messages Sent to Servers . .   9
       5.1.2.  Compatibility Issues for Messages Sent to Clients . .  11
     5.2.  Additional Documents to be Produced . . . . . . . . . . .  12
       5.2.1.  Minor Version Indexing Document . . . . . . . . . . .  12
       5.2.2.  Consolidated XDR Document . . . . . . . . . . . . . .  13
       5.2.3.  XDR Assignment Document . . . . . . . . . . . . . . .  13
       5.2.4.  Transition of Documents to RFC's  . . . . . . . . . .  14
     5.3.  Relationship Between Minor Versioning and Extensions
           within a Minor Version  . . . . . . . . . . . . . . . . .  15
   6.  Correction of Existing Minor Versions and Features  . . . . .  16
     6.1.  Documentation of XDR changes  . . . . . . . . . . . . . .  18
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  19
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  19
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  19
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  19
   Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . .  19
   Appendix B.  RFC Editor Notes . . . . . . . . . . . . . . . . . .  20
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  20

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.  These versioning rules SHOULD maintain compatibility
   with existing clients and servers.

   A large portion of such changes will be part of new minor versions.
   The COMPOUND procedure (see Section 14.2 of [RFC3530]) specifies the

Haynes & Noveck           Expires May 15, 2015                  [Page 2]
Internet-Draft          NFSv4 Version Management           November 2014

   minor version being used by the client.  The CB_COMPOUND (see
   Section 15.2 of [RFC3530]) procedure specifies the minor version
   being used by the server on callbacks.

   Each minor version is specified by one or more standards track RFC:

   Minor version 0  is specified by [RFC3530]

   Minor version 1  is specified principally by [RFC5661]

   Minor version 2  is specified principally by [NFSv42].

   In addition to the creation of new minor versions, two other sorts of
   versioning are discussed in this document:

   o  Addition of OPTIONAL features to existing minor versions.

   o  XDR-based extensions used to correct protocol bugs in existing
      minor versions or associated features.

2.  Terminology

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

3.  Consolidation of the Minor Version Rules

   Previously, versioning rules had been being maintained and specified
   in the Standards Track RFCs, defining the individual minor versions.
   As a result, versioning rules were modified on an ad hoc basis for
   each new minor version.

   This document defines a set of versioning rules, including rules for
   minor version construction, that applies to the NFSv4 protocol as a
   whole.  The rules are subject to change but any such change should be
   part of a standards track RFC obsoleting or updating this document.

   This document supersedes the minor versioning rules appearing in the
   minor version specification RFC's.  As a result potential conflicts
   among these documents should be addressed as follows:

   o  The specification of the actual protocols for minor versions
      previously published as Proposed Standards take precedence over
      minor versioning rules in either this document or in the minor
      version specification RFC's.  In other words, if the transition
      from version A to version B violates a minor versioning rules, the
      protocol stays as it is.

Haynes & Noveck           Expires May 15, 2015                  [Page 3]
Internet-Draft          NFSv4 Version Management           November 2014

   o  Otherwise, any conflict between the minor versioning rules in this
      document and those in minor version specification RFC's are to be
      resolved based on the treatment in this document.

   Future minor version specification documents should avoid specifying
   minor versioning rules and reference this document in connection with
   rules for minor versions.

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.

        Again, the complexity of handling multiple structure definitions
        for a single operation is too burdensome.  New operations should

Haynes & Noveck           Expires May 15, 2015                  [Page 4]
Internet-Draft          NFSv4 Version Management           November 2014

        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"
        the request as an XDR decode error.  This approach allows for

Haynes & Noveck           Expires May 15, 2015                  [Page 5]
Internet-Draft          NFSv4 Version Management           November 2014

        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 May 15, 2015                  [Page 6]
Internet-Draft          NFSv4 Version Management           November 2014

   15.  Other than where explicitly documented in a minor version's
        specification document, 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 set of 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 discussed in connection with
   the creation of 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 minor version field within the
   COMPOUND operation.

Haynes & Noveck           Expires May 15, 2015                  [Page 7]
Internet-Draft          NFSv4 Version Management           November 2014

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

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

   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 of 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 operations 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]).

Haynes & Noveck           Expires May 15, 2015                  [Page 8]
Internet-Draft          NFSv4 Version Management           November 2014

   o  A table giving for each new feature element its status (always
      OPTIONAL), and its relationship to the feature being described
      (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.

   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 in the minor version number.  Adding features in this way
   will enable compatibility with existing clients and servers, who may
   be unaware of the new feature.

   Because the receiver of a message may be unaware of the existence of
   a specific extension, certain compatibility rules need to be
   observed.  In some cases (e.g., addition of new operations or
   callbacks or addition of new arms to an existing switched union)
   older clients or servers may be unable to do XDR parsing on an
   extension of whose existence they are unaware.  In other cases (e.g.,
   error returns) there are no XDR parsing issues but existing clients
   and servers may have expectations as to what may validly be returned.
   Detailed discussion of these compatibility issues appears below:

   o  Issues related to messages sent to the server are discussed in
      Section 5.1.1.

   o  Issues related to messages sent to the client are discussed in
      Section 5.1.2.

5.1.1.  Compatibility Issues for Messages Sent to Servers

   This section deals with compatibility issues that relate to messages
   sent to the server, i.e., requests and replies to callbacks.  In the
   case of requests, it is the responsibility of the client to determine
   whether the server in question supports the extension in question
   before sending a request containing it for any purpose other than
   determining whether the server is aware of the extension.  In the
   case of callback replies, the server demonstrates its awareness of
   proper parsing for callback replies by sending the associated
   callback.

   Regarding the handling of requests:

Haynes & Noveck           Expires May 15, 2015                  [Page 9]
Internet-Draft          NFSv4 Version Management           November 2014

   o  Existing server implementations will return NFS4ERR_NOTSUPP or
      NFS4ERR_OP_ILLEGAL in response to any use of a new operation,
      allowing the client to determine that the requested operation (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 when
      the supported_attr attribute is interrogated.  Clients need to do
      this before attempting to use attributes defined in an extension
      since they cannot depend on the server returning
      NFS4ERRATTRNOTSUPP for requests which include a mask bit
      corresponding to a previously unspecified attribute number (as
      opposed to one which is defined but unsupported).

   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 in a request 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.

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

   Regarding the handling of responses to callbacks:

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

   o  Callback replies may only include a new arm of an existing
      switched union when the server, typically in the callback being
      responded to, has used a feature element associated with the
      feature that defined he new switched union arm.

Haynes & Noveck           Expires May 15, 2015                 [Page 10]
Internet-Draft          NFSv4 Version Management           November 2014

5.1.2.  Compatibility Issues for Messages Sent to Clients

   This sections deals with compatibility issues that relate to messages
   sent to clients, i.e., request replies and callbacks.  In both cases,
   extensions are only sent to clients that have demonstrated awareness
   of the extensions in question by using an extension associated with
   the same feature.

   Regarding the handling of request replies:

   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 server uses a new callback extension feature can a previously
      invalid error value be returned.

   o  Replies may only include a new arm of an existing switched union
      when the server, typically in the request being responded to, has
      used a feature element associated with the feature that defined
      the new switched union arm.

   Regarding the handling of callbacks, the server needs to be sure that
   it only sends callbacks to those clients prepared to receive and
   parse them.

   o  In most cases, the new callback will be part of a feature that
      contains new (forward) operations as well.  When this is the case,
      the feature specification will specify the operations whose
      receipt by a server is sufficient to indicate that the client
      issuing them is prepared to accept and parse the associated
      callbacks.

   o  For callbacks associated with features that have no new operations
      defined, the feature specification should define some way for a
      client to indicate that it is prepared to accept and parse
      callbacks that are part of the extension.  For example, a flag bit
      in the EXCHANGE_ID request may serve this purpose.

   o  In both of the above cases, the ability to accept and parse the
      specified callback is considered separate from support for the
      callback.  The feature specification will indicate whether support
      for the callback is required whenever the feature is used by the
      client.  In cases in which support is not required, the client is
      free to return NFS4ERR_NOTSUPP upon receiving the callback.

Haynes & Noveck           Expires May 15, 2015                 [Page 11]
Internet-Draft          NFSv4 Version Management           November 2014

5.2.  Additional Documents to be Produced

   Additional documents will be required from time to time.  These
   documents will eventually become RFC's (informational or standards
   track as described below), but the work of the working group and of
   implementers developing features will be facilitated by a progression
   of document drafts that incorporate information about new features
   that are being developed or have been approved as Proposed Standards.

5.2.1.  Minor Version Indexing Document

   One document will organize existing material for a minor version
   undergoing extension so that implementers will not have to scan a
   large set of feature definition documents or minor version
   specifications to find information being sought.  Successive drafts
   of this document will serve as an index to the current state of the
   extensible minor version.  Some desirable elements of this indexing
   document would include:

   o  A list of all feature definition documents that have been approved
      as working group documents but have not yet been approved as
      Proposed Standards.

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

   The frequency of updates for this document will be affected by
   implementer needs and the ability to easily generate document drafts,
   preferably by automated means.  The most desirable situation is one

Haynes & Noveck           Expires May 15, 2015                 [Page 12]
Internet-Draft          NFSv4 Version Management           November 2014

   in which a new draft is available soon after each feature reaches the
   status of a Proposed Standard.

5.2.2.  Consolidated XDR Document

   This document will consist of an updated XDR for the protocol as a
   whole including feature elements from all features and minor versions
   accepted as Proposed Standards.

   A new draft should be prepared whenever a new feature within an
   extensible minor version is accepted as a Proposed Standard.  In most
   cases, feature developers will be using a suitable XDR which can then
   be reviewed and published.  In cases in which multiple features reach
   Proposed Standard status at approximately the same time, a merge of
   the XDR changes made by each feature may be necessary.

5.2.3.  XDR Assignment Document

   This document will contain consolidated lists of XDR value
   assignments that are relevant to the protocol extension process.  It
   should contain lists of assignments for:

   o  operation codes (separate lists for forward operations and for
      callbacks)

   o  attribute numbers

   o  error codes

   o  bits within flag words that have been extended since they were
      first introduced.

   o  enumeration values for enumerations which have been extended since
      they were first introduced.

   For each set of assignments, the individual assignments may be of
   three types:

   1.  permanent assignments associated with a minor version or a
       feature extension that has achieved Proposed Standard status.

       These assignments are permanent in that the assigned value will
       never be re-used.  However, a subsequent minor version may define
       some or all feature elements associated with a feature to be
       Mandatory to NOT support.

Haynes & Noveck           Expires May 15, 2015                 [Page 13]
Internet-Draft          NFSv4 Version Management           November 2014

   2.  provisional assignments associated with a feature under
       development (i.e., one which has been approved as a working group
       document but has not been approved as a Proposed Standard).

       Provisional assignments are not are not permanent and the values
       assigned can be re-used in certain circumstances.  In particular,
       when a feature with provisional assignments is not progressing
       toward the goal of eventual Proposed Standard status, the working
       group can judge the feature effort to have been abandoned,
       allowing the codes formerly provisionally allocated to be
       reclaimed and reassigned.

   3.  definition of individual assignments or ranges reserved for
       experimental use.

   A new draft of this document should be produced, whenever:

   o  A minor version or feature specification is accepted as a Proposed
      Standard.

   o  A new feature is accepted for development and a draft of the
      corresponding working-group standards-track document is produced

   o  A feature previously accepted for development is abandoned.

   o  The working group decides to make some change in assignments for
      experimental use.

5.2.4.  Transition of Documents to RFC's

   Each of these documents should be published as an RFC soon after the
   minor version in question ceases to be considered extensible.
   Typically this will happen when the working group makes the
   specification for the subsequent minor version into a working group
   document.  Some specifics about the individual documents are listed
   below:

   o  The most current draft of the indexing document for the minor
      version would be published as an informational RFC.

   o  The most current draft of the consolidated XDR document should be
      published as a standards-track RFC.  It would update the initial
      specification of the minor version.

   o  The most recent draft of the XDR assignment document should be
      published as an informational RFC.

Haynes & Noveck           Expires May 15, 2015                 [Page 14]
Internet-Draft          NFSv4 Version Management           November 2014

   Handling of these documents in the event of a post-approval XDR
   correction is discussed in Section 6.1.

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

   Extensibility of minor version 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 new feature may be added to a minor version may be made once
      the specification document document for a subsequent minor version
      becomes a working group standards-track document.

   Even when a minor version is non-extensible, or when a previous minor
   version is closed to further extension, the features that it contains
   are still subject to updates to effect protocol corrections.  In many
   cases, making an XDR change, in the form of an extension will be the
   best way of correcting the issue.  See Section 6 for details.

   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
      feature elements 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 errors returned 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.

Haynes & Noveck           Expires May 15, 2015                 [Page 15]
Internet-Draft          NFSv4 Version Management           November 2014

   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
      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.  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
   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 bis document updating the RFC
   defining the relevant feature definition document or minor version
   specification.  In making such correction, the working will have to
   carefully consider how to assure interoperability with older clients
   and servers.

   Often, corrections can be done without changing the protocol XDR.
   However, incompatible changes in server or client behavior should not
   be mandated in order to avoid XDR changes.  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 structure 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 an otherwise non-
      extensible minor version, if the working group judges it
      appropriate.

   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.

   o  When a correction is made to a MANDATORY feature, the situation
      becomes one in which neither the old nor the new new version of
      the feature is MANDATORY.  Instead, it is MANDATORY that a server
      support at least one of the two, while each is individually
      OPTIONAL.  Although use of the corrected version is ultimately

Haynes & Noveck           Expires May 15, 2015                 [Page 16]
Internet-Draft          NFSv4 Version Management           November 2014

      better, it is not RECOMMENDED, since the choice of which version
      to support if only one is supported will depend on the needs of
      clients, which may be slow to adopt the updated version.

   o  When a correction is made to a RECOMMENDED feature, the situation
      is similar to the case of a MANDATORY feature.  Neither version is
      RECOMMENDED, Neither the old nor the new version of the feature is
      RECOMMENDED.  Instead, it is RECOMMENDED that a server support at
      least one of the two, while each is individually OPTIONAL.

   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, decide
      that the older version is to become MANDATORY to NOT implement.

   Issues related to the effect of XDR corrections on existing
   documents, including co-ordination with other minor versions, are
   discussed in Section 6.1.

   By doing things this way, 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.

   o  A client that supports 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.

   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.

   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

Haynes & Noveck           Expires May 15, 2015                 [Page 17]
Internet-Draft          NFSv4 Version Management           November 2014

      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 interopt with all client variants.

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

6.1.  Documentation of XDR changes

   In the event of an XDR correction, as discussed above, some document
   updates will be required.  For the purposes of this discussion we
   call the minor version for which XDR correction is required minor
   version X and the minor version on which development is occurring
   minor version Y.

   The following discusses the specific updated documents which could be
   required:

   o  The specification of the feature in question will have to be
      updated to explain the issue, how it was fixed, and the
      compatibility and upgrade strategy.  Normally this will require an
      RFC updating the associated feature specification document.
      However, in the case of a correction to a feature documented in in
      a minor version definition document, the RFC will update that
      document instead.

   o  An updated XDR for minor version X will be produced and will be
      published as a updated to the minor version specification RFC for
      minor version X.

      When the correction is to feature documented in a minor version
      definition, a single RFC will contain both updates to the minor
      version specification RFC.

   o  An updated minor version indexing document for minor version X is
      desirable but not absolutely necessary.

      The question of updated minor version indexing documents for minor
      versions between X and Y should be addressed by the working group
      on a case-by-case basis.

   o  An updated XDR assignment document will be required.  It should be
      based on the most recent such document associated wit minor

Haynes & Noveck           Expires May 15, 2015                 [Page 18]
Internet-Draft          NFSv4 Version Management           November 2014

      version Y and will serve as the basis for later XDR assignment
      drafts for minor version Y.

   The informational RFC's associated with minor version Y (version
   indexing document and XDR assignment document) will contain the
   effects of the correction when published.  Similarly, the minor
   version specification RFC will contain the XDR changes associated
   with the correction.

7.  Security Considerations

   There are no security considerations in this document.

8.  IANA Considerations

   There are no IANA considerations in this document.

9.  References

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

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

Haynes & Noveck           Expires May 15, 2015                 [Page 19]
Internet-Draft          NFSv4 Version Management           November 2014

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]

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
   Dell
   300 Innovative Way
   Nashua, NH  03062
   US

   Phone: +1 781 572 8038
   Email: dave_noveck@dell.com

Haynes & Noveck           Expires May 15, 2015                 [Page 20]