Tech-invite   World Map
3GPPspecs     Glossaries     T+       IETF     RFCs     Groups     SIP     ABNFs

RFC 7862

Proposed STD
Pages: 104
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: NFSV4

Network File System (NFS) Version 4 Minor Version 2 Protocol

Part 1 of 6, p. 1 to 9
None       Next Section

Updated by:    8178


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                         T. Haynes
Request for Comments: 7862                                  Primary Data
Category: Standards Track                                  November 2016
ISSN: 2070-1721


      Network File System (NFS) Version 4 Minor Version 2 Protocol

Abstract

   This document describes NFS version 4 minor version 2; it describes
   the protocol extensions made from NFS version 4 minor version 1.
   Major extensions introduced in NFS version 4 minor version 2 include
   the following: Server-Side Copy, Application Input/Output (I/O)
   Advise, Space Reservations, Sparse Files, Application Data Blocks,
   and Labeled NFS.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc7862.

Copyright Notice

   Copyright (c) 2016 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
   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.

Top       Page 2 
Table of Contents

   1. Introduction ....................................................4
      1.1. Requirements Language ......................................4
      1.2. Scope of This Document .....................................5
      1.3. NFSv4.2 Goals ..............................................5
      1.4. Overview of NFSv4.2 Features ...............................6
           1.4.1. Server-Side Clone and Copy ..........................6
           1.4.2. Application Input/Output (I/O) Advise ...............6
           1.4.3. Sparse Files ........................................6
           1.4.4. Space Reservation ...................................7
           1.4.5. Application Data Block (ADB) Support ................7
           1.4.6. Labeled NFS .........................................7
           1.4.7. Layout Enhancements .................................7
      1.5. Enhancements to Minor Versioning Model .....................7
   2. Minor Versioning ................................................8
   3. pNFS Considerations for New Operations ..........................9
      3.1. Atomicity for ALLOCATE and DEALLOCATE ......................9
      3.2. Sharing of Stateids with NFSv4.1 ...........................9
      3.3. NFSv4.2 as a Storage Protocol in pNFS: The File
           Layout Type ................................................9
           3.3.1. Operations Sent to NFSv4.2 Data Servers .............9
   4. Server-Side Copy ...............................................10
      4.1. Protocol Overview .........................................10
           4.1.1. COPY Operations ....................................11
           4.1.2. Requirements for Operations ........................11
      4.2. Requirements for Inter-Server Copy ........................13
      4.3. Implementation Considerations .............................13
           4.3.1. Locking the Files ..................................13
           4.3.2. Client Caches ......................................14
      4.4. Intra-Server Copy .........................................14
      4.5. Inter-Server Copy .........................................16
      4.6. Server-to-Server Copy Protocol ............................19
           4.6.1. Considerations on Selecting a Copy Protocol ........19
           4.6.2. Using NFSv4.x as the Copy Protocol .................19
           4.6.3. Using an Alternative Copy Protocol .................20
      4.7. netloc4 - Network Locations ...............................21
      4.8. Copy Offload Stateids .....................................21
      4.9. Security Considerations for Server-Side Copy ..............22
           4.9.1. Inter-Server Copy Security .........................22
   5. Support for Application I/O Hints ..............................30
   6. Sparse Files ...................................................30
      6.1. Terminology ...............................................31
      6.2. New Operations ............................................32
           6.2.1. READ_PLUS ..........................................32
           6.2.2. DEALLOCATE .........................................32
   7. Space Reservation ..............................................32

Top      ToC       Page 3 
   8. Application Data Block Support .................................34
      8.1. Generic Framework .........................................35
           8.1.1. Data Block Representation ..........................36
      8.2. An Example of Detecting Corruption ........................36
      8.3. An Example of READ_PLUS ...................................38
      8.4. An Example of Zeroing Space ...............................39
   9. Labeled NFS ....................................................39
      9.1. Definitions ...............................................40
      9.2. MAC Security Attribute ....................................41
           9.2.1. Delegations ........................................41
           9.2.2. Permission Checking ................................42
           9.2.3. Object Creation ....................................42
           9.2.4. Existing Objects ...................................42
           9.2.5. Label Changes ......................................42
      9.3. pNFS Considerations .......................................43
      9.4. Discovery of Server Labeled NFS Support ...................43
      9.5. MAC Security NFS Modes of Operation .......................43
           9.5.1. Full Mode ..........................................44
           9.5.2. Limited Server Mode ................................45
           9.5.3. Guest Mode .........................................45
      9.6. Security Considerations for Labeled NFS ...................46
   10. Sharing Change Attribute Implementation Characteristics
       with NFSv4 Clients ............................................46
   11. Error Values ..................................................47
      11.1. Error Definitions ........................................47
           11.1.1. General Errors ....................................47
           11.1.2. Server-to-Server Copy Errors ......................47
           11.1.3. Labeled NFS Errors ................................48
      11.2. New Operations and Their Valid Errors ....................49
      11.3. New Callback Operations and Their Valid Errors ...........53
   12. New File Attributes ...........................................54
      12.1. New RECOMMENDED Attributes - List and Definition
            References ...............................................54
      12.2. Attribute Definitions ....................................54
   13. Operations: REQUIRED, RECOMMENDED, or OPTIONAL ................57
   14. Modifications to NFSv4.1 Operations ...........................61
      14.1. Operation 42: EXCHANGE_ID - Instantiate the client ID ....61
      14.2. Operation 48: GETDEVICELIST - Get all device
            mappings for a file system ...............................63
   15. NFSv4.2 Operations ............................................64
      15.1. Operation 59: ALLOCATE - Reserve space in a
            region of a file .........................................64
      15.2. Operation 60: COPY - Initiate a server-side copy .........65
      15.3. Operation 61: COPY_NOTIFY - Notify a source
            server of a future copy ..................................70
      15.4. Operation 62: DEALLOCATE - Unreserve space in a
            region of a file .........................................72

Top      ToC       Page 4 
      15.5. Operation 63: IO_ADVISE - Send client I/O access
            pattern hints to the server ..............................73
      15.6. Operation 64: LAYOUTERROR - Provide errors for
            the layout ...............................................79
      15.7. Operation 65: LAYOUTSTATS - Provide statistics
            for the layout ...........................................82
      15.8. Operation 66: OFFLOAD_CANCEL - Stop an offloaded
            operation ................................................84
      15.9. Operation 67: OFFLOAD_STATUS - Poll for the
            status of an asynchronous operation ......................85
      15.10. Operation 68: READ_PLUS - READ data or holes
             from a file .............................................86
      15.11. Operation 69: SEEK - Find the next data or hole .........91
      15.12. Operation 70: WRITE_SAME - WRITE an ADB multiple
             times to a file .........................................92
      15.13. Operation 71: CLONE - Clone a range of a file
             into another file .......................................96
   16. NFSv4.2 Callback Operations ...................................98
      16.1. Operation 15: CB_OFFLOAD - Report the results of
            an asynchronous operation ................................98
   17. Security Considerations .......................................99
   18. IANA Considerations ...........................................99
   19. References ...................................................100
      19.1. Normative References ....................................100
      19.2. Informative References ..................................101
   Acknowledgments ..................................................103
   Author's Address .................................................104

1.  Introduction

   The NFS version 4 minor version 2 (NFSv4.2) protocol is the third
   minor version of the NFS version 4 (NFSv4) protocol.  The first minor
   version, NFSv4.0, is described in [RFC7530], and the second minor
   version, NFSv4.1, is described in [RFC5661].

   As a minor version, NFSv4.2 is consistent with the overall goals for
   NFSv4, but NFSv4.2 extends the protocol so as to better meet those
   goals, based on experiences with NFSv4.1.  In addition, NFSv4.2 has
   adopted some additional goals, which motivate some of the major
   extensions in NFSv4.2.

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

Top      ToC       Page 5 
1.2.  Scope of This Document

   This document describes the NFSv4.2 protocol as a set of extensions
   to the specification for NFSv4.1.  That specification remains current
   and forms the basis for the additions defined herein.  The
   specification for NFSv4.0 remains current as well.

   It is necessary to implement all the REQUIRED features of NFSv4.1
   before adding NFSv4.2 features to the implementation.  With respect
   to NFSv4.0 and NFSv4.1, this document does not:

   o  describe the NFSv4.0 or NFSv4.1 protocols, except where needed to
      contrast with NFSv4.2

   o  modify the specification of the NFSv4.0 or NFSv4.1 protocols

   o  clarify the NFSv4.0 or NFSv4.1 protocols -- that is, any
      clarifications made here apply only to NFSv4.2 and not to NFSv4.0
      or NFSv4.1

   NFSv4.2 is a superset of NFSv4.1, with all of the new features being
   optional.  As such, NFSv4.2 maintains the same compatibility that
   NFSv4.1 had with NFSv4.0.  Any interactions of a new feature with
   NFSv4.1 semantics is described in the relevant text.

   The full External Data Representation (XDR) [RFC4506] for NFSv4.2 is
   presented in [RFC7863].

1.3.  NFSv4.2 Goals

   A major goal of the enhancements provided in NFSv4.2 is to take
   common local file system features that have not been available
   through earlier versions of NFS and to offer them remotely.  These
   features might

   o  already be available on the servers, e.g., sparse files

   o  be under development as a new standard, e.g., SEEK pulls in both
      SEEK_HOLE and SEEK_DATA

   o  be used by clients with the servers via some proprietary means,
      e.g., Labeled NFS

   NFSv4.2 provides means for clients to leverage these features on the
   server in cases in which such leveraging had previously not been
   possible within the confines of the NFS protocol.

Top      ToC       Page 6 
1.4.  Overview of NFSv4.2 Features

1.4.1.  Server-Side Clone and Copy

   A traditional file copy of a remotely accessed file, whether from one
   server to another or between locations in the same server, results in
   the data being put on the network twice -- source to client and then
   client to destination.  New operations are introduced to allow
   unnecessary traffic to be eliminated:

   o  The intra-server CLONE feature allows the client to request a
      synchronous cloning, perhaps by copy-on-write semantics.

   o  The intra-server COPY feature allows the client to request the
      server to perform the copy internally, avoiding unnecessary
      network traffic.

   o  The inter-server COPY feature allows the client to authorize the
      source and destination servers to interact directly.

   As such copies can be lengthy, asynchronous support is also provided.

1.4.2.  Application Input/Output (I/O) Advise

   Applications and clients want to advise the server as to expected I/O
   behavior.  Using IO_ADVISE (see Section 15.5) to communicate future
   I/O behavior such as whether a file will be accessed sequentially or
   randomly, and whether a file will or will not be accessed in the near
   future, allows servers to optimize future I/O requests for a file by,
   for example, prefetching or evicting data.  This operation can be
   used to support the posix_fadvise() [posix_fadvise] function.  In
   addition, it may be helpful to applications such as databases and
   video editors.

1.4.3.  Sparse Files

   Sparse files are files that have unallocated or uninitialized data
   blocks as holes in the file.  Such holes are typically transferred as
   zeros when read from the file.  READ_PLUS (see Section 15.10) allows
   a server to send back to the client metadata describing the hole, and
   DEALLOCATE (see Section 15.4) allows the client to punch holes into a
   file.  In addition, SEEK (see Section 15.11) is provided to scan for
   the next hole or data from a given location.

Top      ToC       Page 7 
1.4.4.  Space Reservation

   When a file is sparse, one concern that applications have is ensuring
   that there will always be enough data blocks available for the file
   during future writes.  ALLOCATE (see Section 15.1) allows a client to
   request a guarantee that space will be available.  Also, DEALLOCATE
   (see Section 15.4) allows the client to punch a hole into a file,
   thus releasing a space reservation.

1.4.5.  Application Data Block (ADB) Support

   Some applications treat a file as if it were a disk and as such want
   to initialize (or format) the file image.  The WRITE_SAME operation
   (see Section 15.12) is introduced to send this metadata to the server
   to allow it to write the block contents.

1.4.6.  Labeled NFS

   While both clients and servers can employ Mandatory Access Control
   (MAC) security models to enforce data access, there has been no
   protocol support for interoperability.  A new file object attribute,
   sec_label (see Section 12.2.4), allows the server to store MAC labels
   on files, which the client retrieves and uses to enforce data access
   (see Section 9.5.3).  The format of the sec_label accommodates any
   MAC security system.

1.4.7.  Layout Enhancements

   In the parallel NFS implementations of NFSv4.1 (see Section 12 of
   [RFC5661]), the client cannot communicate back to the metadata server
   any errors or performance characteristics with the storage devices.
   NFSv4.2 provides two new operations to do so: LAYOUTERROR (see
   Section 15.6) and LAYOUTSTATS (see Section 15.7), respectively.

1.5.  Enhancements to Minor Versioning Model

   In NFSv4.1, the only way to introduce new variants of an operation
   was to introduce a new operation.  For instance, READ would have to
   be replaced or supplemented by, say, either READ2 or READ_PLUS.  With
   the use of discriminated unions as parameters for such functions in
   NFSv4.2, it is possible to add a new "arm" (i.e., a new entry in the
   union and a corresponding new field in the structure) in a subsequent
   minor version.  It is also possible to move such an operation from
   OPTIONAL/RECOMMENDED to REQUIRED.  Forcing an implementation to adopt
   each arm of a discriminated union at such a time does not meet the
   spirit of the minor versioning rules.  As such, new arms of a
   discriminated union MUST follow the same guidelines for minor

Top      ToC       Page 8 
   versioning as operations in NFSv4.1 -- i.e., they may not be made
   REQUIRED.  To support this, a new error code, NFS4ERR_UNION_NOTSUPP,
   allows the server to communicate to the client that the operation is
   supported but the specific arm of the discriminated union is not.

2.  Minor Versioning

   NFSv4.2 is a minor version of NFSv4 and is built upon NFSv4.1 as
   documented in [RFC5661] and [RFC5662].

   NFSv4.2 does not modify the rules applicable to the NFSv4 versioning
   process and follows the rules set out in [RFC5661] or in
   Standards Track documents updating that document (e.g., in an RFC
   based on [NFSv4-Versioning]).

   NFSv4.2 only defines extensions to NFSv4.1, each of which may be
   supported (or not) independently.  It does not

   o  introduce infrastructural features

   o  make existing features MANDATORY to NOT implement

   o  change the status of existing features (i.e., by changing their
      status among OPTIONAL, RECOMMENDED, REQUIRED)

   The following versioning-related considerations should be noted.

   o  When a new case is added to an existing switch, servers need to
      report non-support of that new case by returning
      NFS4ERR_UNION_NOTSUPP.

   o  As regards the potential cross-minor-version transfer of stateids,
      Parallel NFS (pNFS) (see Section 12 of [RFC5661]) implementations
      of the file-mapping type may support the use of an NFSv4.2
      metadata server (see Sections 1.7.2.2 and 12.2.2 of [RFC5661])
      with NFSv4.1 data servers.  In this context, a stateid returned by
      an NFSv4.2 COMPOUND will be used in an NFSv4.1 COMPOUND directed
      to the data server (see Sections 3.2 and 3.3).

Top      ToC       Page 9 
3.  pNFS Considerations for New Operations

   The interactions of the new operations with non-pNFS functionality
   are straightforward and are covered in the relevant sections.
   However, the interactions of the new operations with pNFS are more
   complicated.  This section provides an overview.

3.1.  Atomicity for ALLOCATE and DEALLOCATE

   Both ALLOCATE (see Section 15.1) and DEALLOCATE (see Section 15.4)
   are sent to the metadata server, which is responsible for
   coordinating the changes onto the storage devices.  In particular,
   both operations must either fully succeed or fail; it cannot be the
   case that one storage device succeeds whilst another fails.

3.2.  Sharing of Stateids with NFSv4.1

   An NFSv4.2 metadata server can hand out a layout to an NFSv4.1
   storage device.  Section 13.9.1 of [RFC5661] discusses how the client
   gets a stateid from the metadata server to present to a storage
   device.

3.3.  NFSv4.2 as a Storage Protocol in pNFS: The File Layout Type

   A file layout provided by an NFSv4.2 server may refer to either (1) a
   storage device that only implements NFSv4.1 as specified in [RFC5661]
   or (2) a storage device that implements additions from NFSv4.2, in
   which case the rules in Section 3.3.1 apply.  As the file layout type
   does not provide a means for informing the client as to which minor
   version a particular storage device is providing, the client will
   have to negotiate this with the storage device via the normal Remote
   Procedure Call (RPC) semantics of major and minor version discovery.
   For example, as per Section 16.2.3 of [RFC5661], the client could try
   a COMPOUND with a minorversion field value of 2; if it gets
   NFS4ERR_MINOR_VERS_MISMATCH, it would drop back to 1.

3.3.1.  Operations Sent to NFSv4.2 Data Servers

   In addition to the commands listed in [RFC5661], NFSv4.2 data servers
   MAY accept a COMPOUND containing the following additional operations:
   IO_ADVISE (see Section 15.5), READ_PLUS (see Section 15.10),
   WRITE_SAME (see Section 15.12), and SEEK (see Section 15.11), which
   will be treated like the subset specified as "Operations Sent to
   NFSv4.1 Data Servers" in Section 13.6 of [RFC5661].

   Additional details on the implementation of these operations in a
   pNFS context are documented in the operation-specific sections.


Next Section