RFC 7862
Network File System (NFS) Version 4 Minor Version 2 Protocol
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 ProtocolAbstract
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.
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
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
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].
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.
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.
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
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).
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 page on part 2)
