Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7862

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

Pages: 104
Proposed Standard
Errata
Updated by:  8178
Part 3 of 6 – Pages 32 to 53
First   Prev   Next

Top   ToC   RFC7862 - Page 32   prevText

7. Space Reservation

Applications want to be able to reserve space for a file, report the amount of actual disk space a file occupies, and free up the backing space of a file when it is not required. One example is the posix_fallocate() operation [posix_fallocate], which allows applications to ask for space reservations from the operating system, usually to provide a better file layout and reduce overhead for random or slow-growing file-appending workloads.
Top   ToC   RFC7862 - Page 33
   Another example is space reservation for virtual disks in a
   hypervisor.  In virtualized environments, virtual disk files are
   often stored on NFS-mounted volumes.  When a hypervisor creates a
   virtual disk file, it often tries to preallocate the space for the
   file so that there are no future allocation-related errors during the
   operation of the VM.  Such errors prevent a VM from continuing
   execution and result in downtime.

   Currently, in order to achieve such a guarantee, applications zero
   the entire file.  The initial zeroing allocates the backing blocks,
   and all subsequent writes are overwrites of already-allocated blocks.
   This approach is not only inefficient in terms of the amount of I/O
   done; it is also not guaranteed to work on file systems that are
   log-structured or deduplicated.  An efficient way of guaranteeing
   space reservation would be beneficial to such applications.

   The new ALLOCATE operation (see Section 15.1) allows a client to
   request a guarantee that space will be available.  The ALLOCATE
   operation guarantees that any future writes to the region it was
   successfully called for will not fail with NFS4ERR_NOSPC.

   Another useful feature is the ability to report the number of blocks
   that would be freed when a file is deleted.  Currently, NFS reports
   two size attributes:

   size  The logical file size of the file.

   space_used  The size in bytes that the file occupies on disk.

   While these attributes are sufficient for space accounting in
   traditional file systems, they prove to be inadequate in modern file
   systems that support block-sharing.  In such file systems, multiple
   inodes (the metadata portion of the file system object) can point to
   a single block with a block reference count to guard against
   premature freeing.  Having a way to tell the number of blocks that
   would be freed if the file was deleted would be useful to
   applications that wish to migrate files when a volume is low on
   space.

   Since virtual disks represent a hard drive in a VM, a virtual disk
   can be viewed as a file system within a file.  Since not all blocks
   within a file system are in use, there is an opportunity to reclaim
   blocks that are no longer in use.  A call to deallocate blocks could
   result in better space efficiency; less space might be consumed for
   backups after block deallocation.
Top   ToC   RFC7862 - Page 34
   The following attribute and operation can be used to resolve these
   issues:

   space_freed  This attribute reports the space that would be freed
      when a file is deleted, taking block-sharing into consideration.

   DEALLOCATE  This operation deallocates the blocks backing a region of
      the file.

   If space_used of a file is interpreted to mean the size in bytes of
   all disk blocks pointed to by the inode of the file, then shared
   blocks get double-counted, over-reporting the space utilization.
   This also has the adverse effect that the deletion of a file with
   shared blocks frees up less than space_used bytes.

   On the other hand, if space_used is interpreted to mean the size in
   bytes of those disk blocks unique to the inode of the file, then
   shared blocks are not counted in any file, resulting in
   under-reporting of the space utilization.

   For example, two files, A and B, have 10 blocks each.  Let six of
   these blocks be shared between them.  Thus, the combined space
   utilized by the two files is 14 * BLOCK_SIZE bytes.  In the former
   case, the combined space utilization of the two files would be
   reported as 20 * BLOCK_SIZE.  However, deleting either would only
   result in 4 * BLOCK_SIZE being freed.  Conversely, the latter
   interpretation would report that the space utilization is only
   8 * BLOCK_SIZE.

   Using the space_freed attribute (see Section 12.2.2) is helpful in
   solving this problem.  space_freed is the number of blocks that are
   allocated to the given file that would be freed on its deletion.  In
   the example, both A and B would report space_freed as 4 * BLOCK_SIZE
   and space_used as 10 * BLOCK_SIZE.  If A is deleted, B will report
   space_freed as 10 * BLOCK_SIZE, as the deletion of B would result in
   the deallocation of all 10 blocks.

   Using the space_freed attribute does not solve the problem of space
   being over-reported.  However, over-reporting is better than
   under-reporting.

8. Application Data Block Support

At the OS level, files are contained on disk blocks. Applications are also free to impose structure on the data contained in a file and thus can define an Application Data Block (ADB) to be such a structure. From the application's viewpoint, it only wants to handle ADBs and not raw bytes (see [Strohm11]). An ADB is typically
Top   ToC   RFC7862 - Page 35
   comprised of two sections: header and data.  The header describes the
   characteristics of the block and can provide a means to detect
   corruption in the data payload.  The data section is typically
   initialized to all zeros.

   The format of the header is application specific, but there are two
   main components typically encountered:

   1.  An Application Data Block Number (ADBN), which allows the
       application to determine which data block is being referenced.
       This is useful when the client is not storing the blocks in
       contiguous memory, i.e., a logical block number.

   2.  Fields to describe the state of the ADB and a means to detect
       block corruption.  For both pieces of data, a useful property
       would be that the allowed values are specially selected so that,
       if passed across the network, corruption due to translation
       between big-endian and little-endian architectures is detectable.
       For example, 0xf0dedef0 has the same (32 wide) bit pattern in
       both architectures, making it inappropriate.

   Applications already impose structures on files [Strohm11] and detect
   corruption in data blocks [Ashdown08].  What they are not able to do
   is efficiently transfer and store ADBs.  To initialize a file with
   ADBs, the client must send each full ADB to the server, and that must
   be stored on the server.

   This section defines a framework for transferring the ADB from client
   to server and presents one approach to detecting corruption in a
   given ADB implementation.

8.1. Generic Framework

The representation of the ADB needs to be flexible enough to support many different applications. The most basic approach is no imposition of a block at all, which entails working with the raw bytes. Such an approach would be useful for storing holes, punching holes, etc. In more complex deployments, a server might be supporting multiple applications, each with their own definition of the ADB. One might store the ADBN at the start of the block and then have a guard pattern to detect corruption [McDougall07]. The next might store the ADBN at an offset of 100 bytes within the block and have no guard pattern at all, i.e., existing applications might already have well-defined formats for their data blocks. The guard pattern can be used to represent the state of the block, to protect against corruption, or both. Again, it needs to be able to be placed anywhere within the ADB.
Top   ToC   RFC7862 - Page 36
   Both the starting offset of the block and the size of the block need
   to be represented.  Note that nothing prevents the application from
   defining different-sized blocks in a file.

8.1.1. Data Block Representation

<CODE BEGINS> struct app_data_block4 { offset4 adb_offset; length4 adb_block_size; length4 adb_block_count; length4 adb_reloff_blocknum; count4 adb_block_num; length4 adb_reloff_pattern; opaque adb_pattern<>; }; <CODE ENDS> The app_data_block4 structure captures the abstraction presented for the ADB. The additional fields present are to allow the transmission of adb_block_count ADBs at one time. The adb_block_num is used to convey the ADBN of the first block in the sequence. Each ADB will contain the same adb_pattern string. As both adb_block_num and adb_pattern are optional, if either adb_reloff_pattern or adb_reloff_blocknum is set to NFS4_UINT64_MAX, then the corresponding field is not set in any of the ADBs.

8.2. An Example of Detecting Corruption

In this section, an example ADB format is defined in which corruption can be detected. Note that this is just one possible format and means to detect corruption. Consider a very basic implementation of an operating system's disk blocks. A block is either data or an indirect block that allows for files that are larger than one block. It is desired to be able to initialize a block. Lastly, to quickly unlink a file, a block can be marked invalid. The contents remain intact; this would enable the OS application in question to undelete a file.
Top   ToC   RFC7862 - Page 37
   The application defines 4K-sized data blocks, with an 8-byte block
   counter occurring at offset 0 in the block, and with the guard
   pattern occurring at offset 8 inside the block.  Furthermore, the
   guard pattern can take one of four states:

   0xfeedface -  This is the FREE state and indicates that the ADB
      format has been applied.

   0xcafedead -  This is the DATA state and indicates that real data has
      been written to this block.

   0xe4e5c001 -  This is the INDIRECT state and indicates that the block
      contains block counter numbers that are chained off of this block.

   0xba1ed4a3 -  This is the INVALID state and indicates that the block
      contains data whose contents are garbage.

   Finally, it also defines an 8-byte checksum starting at byte 16 that
   applies to the remaining contents of the block (see [Baira08] for an
   example of using checksums to detect data corruption).  If the state
   is FREE, then that checksum is trivially zero.  As such, the
   application has no need to transfer the checksum implicitly inside
   the ADB -- it need not make the transfer layer aware of the fact that
   there is a checksum (see [Ashdown08] for an example of checksums used
   to detect corruption in application data blocks).

   Corruption in each ADB can thus be detected:

   o  If the guard pattern is anything other than one of the allowed
      values, including all zeros.

   o  If the guard pattern is FREE and any other byte in the remainder
      of the ADB is anything other than zero.

   o  If the guard pattern is anything other than FREE, then if the
      stored checksum does not match the computed checksum.

   o  If the guard pattern is INDIRECT and one of the stored indirect
      block numbers has a value greater than the number of ADBs in
      the file.

   o  If the guard pattern is INDIRECT and one of the stored indirect
      block numbers is a duplicate of another stored indirect block
      number.

   As can be seen, the application can detect errors based on the
   combination of the guard pattern state and the checksum but also can
   detect corruption based on the state and the contents of the ADB.
Top   ToC   RFC7862 - Page 38
   This last point is important in validating the minimum amount of data
   incorporated into the generic framework.  That is, the guard pattern
   is sufficient in allowing applications to design their own corruption
   detection.

   Finally, it is important to note that none of these corruption checks
   occur in the transport layer.  The server and client components are
   totally unaware of the file format and might report everything as
   being transferred correctly, even in cases where the application
   detects corruption.

8.3. An Example of READ_PLUS

The hypothetical application presented in Section 8.2 can be used to illustrate how READ_PLUS would return an array of results. A file is created and initialized with 100 4K ADBs in the FREE state with the WRITE_SAME operation (see Section 15.12): WRITE_SAME {0, 4K, 100, 0, 0, 8, 0xfeedface} Further, assume that the application writes a single ADB at 16K, changing the guard pattern to 0xcafedead; then there would be in memory: 0K -> (4K - 1) : 00 00 00 00 ... fe ed fa ce 00 00 ... 00 4K -> (8K - 1) : 00 00 00 01 ... fe ed fa ce 00 00 ... 00 8K -> (12K - 1) : 00 00 00 02 ... fe ed fa ce 00 00 ... 00 12K -> (16K - 1) : 00 00 00 03 ... fe ed fa ce 00 00 ... 00 16K -> (20K - 1) : 00 00 00 04 ... ca fe de ad 00 00 ... 00 20K -> (24K - 1) : 00 00 00 05 ... fe ed fa ce 00 00 ... 00 24K -> (28K - 1) : 00 00 00 06 ... fe ed fa ce 00 00 ... 00 ... 396K -> (400K - 1) : 00 00 00 63 ... fe ed fa ce 00 00 ... 00 And when the client did a READ_PLUS of 64K at the start of the file, it could get back a result of data: 0K -> (4K - 1) : 00 00 00 00 ... fe ed fa ce 00 00 ... 00 4K -> (8K - 1) : 00 00 00 01 ... fe ed fa ce 00 00 ... 00 8K -> (12K - 1) : 00 00 00 02 ... fe ed fa ce 00 00 ... 00 12K -> (16K - 1) : 00 00 00 03 ... fe ed fa ce 00 00 ... 00 16K -> (20K - 1) : 00 00 00 04 ... ca fe de ad 00 00 ... 00 20K -> (24K - 1) : 00 00 00 05 ... fe ed fa ce 00 00 ... 00 24K -> (28K - 1) : 00 00 00 06 ... fe ed fa ce 00 00 ... 00 ... 62K -> (64K - 1) : 00 00 00 15 ... fe ed fa ce 00 00 ... 00
Top   ToC   RFC7862 - Page 39

8.4. An Example of Zeroing Space

A simpler use case for WRITE_SAME is applications that want to efficiently zero out a file, but do not want to modify space reservations. This can easily be achieved by a call to WRITE_SAME without an ADB block numbers and pattern, e.g.: WRITE_SAME {0, 1K, 10000, 0, 0, 0, 0}

9. Labeled NFS

Access control models such as UNIX permissions or Access Control Lists (ACLs) are commonly referred to as Discretionary Access Control (DAC) models. These systems base their access decisions on user identity and resource ownership. In contrast, Mandatory Access Control (MAC) models base their access control decisions on the label on the subject (usually a process) and the object it wishes to access [RFC4949]. These labels may contain user identity information but usually contain additional information. In DAC systems, users are free to specify the access rules for resources that they own. MAC models base their security decisions on a system-wide policy -- established by an administrator or organization -- that the users do not have the ability to override. In this section, a MAC model is added to NFSv4.2. First, a method is provided for transporting and storing security label data on NFSv4 file objects. Security labels have several semantics that are met by NFSv4 recommended attributes such as the ability to set the label value upon object creation. Access control on these attributes is done through a combination of two mechanisms. As with other recommended attributes on file objects, the usual DAC checks, based on the ACLs and permission bits, will be performed to ensure that proper file ownership is enforced. In addition, a MAC system MAY be employed on the client, server, or both to enforce additional policy on what subjects may modify security label information. Second, a method is described for the client to determine if an NFSv4 file object security label has changed. A client that needs to know if a label on a file or set of files is going to change SHOULD request a delegation on each labeled file. In order to change such a security label, the server will have to recall delegations on any file affected by the label change, so informing clients of the label change.
Top   ToC   RFC7862 - Page 40
   An additional useful feature would be modification to the RPC layer
   used by NFSv4 to allow RPCs to assert client process subject security
   labels and enable the enforcement of Full Mode as described in
   Section 9.5.1.  Such modifications are outside the scope of this
   document (see [RFC7861]).

9.1. Definitions

Label Format Specifier (LFS): an identifier used by the client to establish the syntactic format of the security label and the semantic meaning of its components. LFSs exist in a registry associated with documents describing the format and semantics of the label. Security Label Format Selection Registry: the IANA registry (see [RFC7569]) containing all registered LFSs, along with references to the documents that describe the syntactic format and semantics of the security label. Policy Identifier (PI): an optional part of the definition of an LFS. The PI allows clients and servers to identify specific security policies. Object: a passive resource within the system that is to be protected. Objects can be entities such as files, directories, pipes, sockets, and many other system resources relevant to the protection of the system state. Subject: an active entity, usually a process that is requesting access to an object. MAC-Aware: a server that can transmit and store object labels. MAC-Functional: a client or server that is Labeled NFS enabled. Such a system can interpret labels and apply policies based on the security system. Multi-Level Security (MLS): a traditional model where objects are given a sensitivity level (Unclassified, Secret, Top Secret, etc.) and a category set (see [LB96], [RFC1108], [RFC2401], and [RFC4949]). (Note: RFC 2401 has been obsoleted by RFC 4301, but we list RFC 2401 here because RFC 4301 does not discuss MLS.)
Top   ToC   RFC7862 - Page 41

9.2. MAC Security Attribute

MAC models base access decisions on security attributes bound to subjects (usually processes) and objects (for NFS, file objects). This information can range from a user identity for an identity-based MAC model, sensitivity levels for MLS, or a type for type enforcement. These models base their decisions on different criteria, but the semantics of the security attribute remain the same. The semantics required by the security attribute are listed below: o MUST provide flexibility with respect to the MAC model. o MUST provide the ability to atomically set security information upon object creation. o MUST provide the ability to enforce access control decisions on both the client and the server. o MUST NOT expose an object to either the client or server namespace before its security information has been bound to it. NFSv4 implements the MAC security attribute as a recommended attribute. This attribute has a fixed format and semantics, which conflicts with the flexible nature of security attributes in general. To resolve this, the MAC security attribute consists of two components. The first component is an LFS, as defined in [RFC7569], to allow for interoperability between MAC mechanisms. The second component is an opaque field, which is the actual security attribute data. To allow for various MAC models, NFSv4 should be used solely as a transport mechanism for the security attribute. It is the responsibility of the endpoints to consume the security attribute and make access decisions based on their respective models. In addition, creation of objects through OPEN and CREATE allows the security attribute to be specified upon creation. By providing an atomic create and set operation for the security attribute, it is possible to enforce the second and fourth requirements listed above. The recommended attribute FATTR4_SEC_LABEL (see Section 12.2.4) will be used to satisfy this requirement.

9.2.1. Delegations

In the event that a security attribute is changed on the server while a client holds a delegation on the file, both the server and the client MUST follow the NFSv4.1 protocol (see Section 10 of [RFC5661]) with respect to attribute changes. It SHOULD flush all changes back to the server and relinquish the delegation.
Top   ToC   RFC7862 - Page 42

9.2.2. Permission Checking

It is not feasible to enumerate all possible MAC models and even levels of protection within a subset of these models. This means that the NFSv4 client and servers cannot be expected to directly make access control decisions based on the security attribute. Instead, NFSv4 should defer permission checking on this attribute to the host system. These checks are performed in addition to existing DAC and ACL checks outlined in the NFSv4 protocol. Section 9.5 gives a specific example of how the security attribute is handled under a particular MAC model.

9.2.3. Object Creation

When creating files in NFSv4, the OPEN and CREATE operations are used. One of the parameters for these operations is an fattr4 structure containing the attributes the file is to be created with. This allows NFSv4 to atomically set the security attribute of files upon creation. When a client is MAC-Functional, it must always provide the initial security attribute upon file creation. In the event that the server is MAC-Functional as well, it should determine by policy whether it will accept the attribute from the client or instead make the determination itself. If the client is not MAC-Functional, then the MAC-Functional server must decide on a default label. A more in-depth explanation can be found in Section 9.5.

9.2.4. Existing Objects

Note that under the MAC model, all objects must have labels. Therefore, if an existing server is upgraded to include Labeled NFS support, then it is the responsibility of the security system to define the behavior for existing objects.

9.2.5. Label Changes

Consider a Guest Mode system (Section 9.5.3) in which the clients enforce MAC checks and the server has only a DAC security system that stores the labels along with the file data. In this type of system, a user with the appropriate DAC credentials on a client with poorly configured or disabled MAC labeling enforcement is allowed access to the file label (and data) on the server and can change the label.
Top   ToC   RFC7862 - Page 43
   Clients that need to know if a label on a file or set of files has
   changed SHOULD request a delegation on each labeled file so that a
   label change by another client will be known via the process
   described in Section 9.2.1, which must be followed: the delegation
   will be recalled, which effectively notifies the client of the
   change.

   Note that the MAC security policies on a client can be such that the
   client does not have access to the file unless it has a delegation.

9.3. pNFS Considerations

The new FATTR4_SEC_LABEL attribute is metadata information, and as such the storage device is not aware of the value contained on the metadata server. Fortunately, the NFSv4.1 protocol [RFC5661] already has provisions for doing access-level checks from the storage device to the metadata server. In order for the storage device to validate the subject label presented by the client, it SHOULD utilize this mechanism.

9.4. Discovery of Server Labeled NFS Support

The server can easily determine that a client supports Labeled NFS when it queries for the FATTR4_SEC_LABEL label for an object. Further, it can then determine which LFS the client understands. The client might want to discover whether the server supports Labeled NFS and which LFS the server supports. The following COMPOUND MUST NOT be denied by any MAC label check: PUTROOTFH, GETATTR {FATTR4_SEC_LABEL} Note that the server might have imposed a security flavor on the root that precludes such access. That is, if the server requires Kerberized access and the client presents a COMPOUND with AUTH_SYS, then the server is allowed to return NFS4ERR_WRONGSEC in this case. But if the client presents a correct security flavor, then the server MUST return the FATTR4_SEC_LABEL attribute with the supported LFS filled in.

9.5. MAC Security NFS Modes of Operation

A system using Labeled NFS may operate in three modes (see Section 4 of [RFC7204]). The first mode provides the most protection and is called "Full Mode". In this mode, both the client and server implement a MAC model allowing each end to make an access control decision. The second mode is a subset of the Full Mode and is called "Limited Server Mode". In this mode, the server cannot enforce the
Top   ToC   RFC7862 - Page 44
   labels, but it can store and transmit them.  The remaining mode is
   called the "Guest Mode"; in this mode, one end of the connection is
   not implementing a MAC model and thus offers less protection than
   Full Mode.

9.5.1. Full Mode

Full Mode environments consist of MAC-Functional NFSv4 servers and clients and may be composed of mixed MAC models and policies. The system requires that both the client and server have an opportunity to perform an access control check based on all relevant information within the network. The file object security attribute is provided using the mechanism described in Section 9.2. Fully MAC-Functional NFSv4 servers are not possible in the absence of RPCSEC_GSSv3 [RFC7861] support for client process subject label assertion. However, servers may make decisions based on the RPC credential information available.
9.5.1.1. Initial Labeling and Translation
The ability to create a file is an action that a MAC model may wish to mediate. The client is given the responsibility to determine the initial security attribute to be placed on a file. This allows the client to make a decision as to the acceptable security attribute to create a file with before sending the request to the server. Once the server receives the creation request from the client, it may choose to evaluate if the security attribute is acceptable. Security attributes on the client and server may vary based on MAC model and policy. To handle this, the security attribute field has an LFS component. This component is a mechanism for the host to identify the format and meaning of the opaque portion of the security attribute. A Full Mode environment may contain hosts operating in several different LFSs. In this case, a mechanism for translating the opaque portion of the security attribute is needed. The actual translation function will vary based on MAC model and policy and is outside the scope of this document. If a translation is unavailable for a given LFS, then the request MUST be denied. Another recourse is to allow the host to provide a fallback mapping for unknown security attributes.
9.5.1.2. Policy Enforcement
In Full Mode, access control decisions are made by both the clients and servers. When a client makes a request, it takes the security attribute from the requesting process and makes an access control decision based on that attribute and the security attribute of the
Top   ToC   RFC7862 - Page 45
   object it is trying to access.  If the client denies that access, an
   RPC to the server is never made.  If, however, the access is allowed,
   the client will make a call to the NFS server.

   When the server receives the request from the client, it uses any
   credential information conveyed in the RPC request and the attributes
   of the object the client is trying to access to make an access
   control decision.  If the server's policy allows this access, it will
   fulfill the client's request; otherwise, it will return
   NFS4ERR_ACCESS.

   Future protocol extensions may also allow the server to factor into
   the decision a security label extracted from the RPC request.

   Implementations MAY validate security attributes supplied over the
   network to ensure that they are within a set of attributes permitted
   from a specific peer and, if not, reject them.  Note that a system
   may permit a different set of attributes to be accepted from
   each peer.

9.5.2. Limited Server Mode

A Limited Server mode (see Section 4.2 of [RFC7204]) consists of a server that is label aware but does not enforce policies. Such a server will store and retrieve all object labels presented by clients and will utilize the methods described in Section 9.2.5 to allow the clients to detect changing labels, but may not factor the label into access decisions. Instead, it will expect the clients to enforce all such access locally.

9.5.3. Guest Mode

Guest Mode implies that either the client or the server does not handle labels. If the client is not Labeled NFS aware, then it will not offer subject labels to the server. The server is the only entity enforcing policy and may selectively provide standard NFS services to clients based on their authentication credentials and/or associated network attributes (e.g., IP address, network interface). The level of trust and access extended to a client in this mode is configuration specific. If the server is not Labeled NFS aware, then it will not return object labels to the client. Clients in this environment may consist of groups implementing different MAC model policies. The system requires that all clients in the environment be responsible for access control checks.
Top   ToC   RFC7862 - Page 46

9.6. Security Considerations for Labeled NFS

Depending on the level of protection the MAC system offers, there may be a requirement to tightly bind the security attribute to the data. When only one of the client or server enforces labels, it is important to realize that the other side is not enforcing MAC protections. Alternate methods might be in use to handle the lack of MAC support, and care should be taken to identify and mitigate threats from possible tampering outside of these methods. An example of this is that a server that modifies READDIR or LOOKUP results based on the client's subject label might want to always construct the same subject label for a client that does not present one. This will prevent a non-Labeled NFS client from mixing entries in the directory cache.

10. Sharing Change Attribute Implementation Characteristics with NFSv4 Clients

Although both the NFSv4 [RFC7530] and NFSv4.1 [RFC5661] protocols define the change attribute as being mandatory to implement, there is little in the way of guidance as to its construction. The only mandated constraint is that the value must change whenever the file data or metadata changes. While this allows for a wide range of implementations, it also leaves the client with no way to determine which is the most recent value for the change attribute in a case where several RPCs have been issued in parallel. In other words, if two COMPOUNDs, both containing WRITE and GETATTR requests for the same file, have been issued in parallel, how does the client determine which of the two change attribute values returned in the replies to the GETATTR requests corresponds to the most recent state of the file? In some cases, the only recourse may be to send another COMPOUND containing a third GETATTR that is fully serialized with the first two. NFSv4.2 avoids this kind of inefficiency by allowing the server to share details about how the change attribute is expected to evolve, so that the client may immediately determine which, out of the several change attribute values returned by the server, is the most recent. change_attr_type is defined as a new recommended attribute (see Section 12.2.3) and is a per-file system attribute.
Top   ToC   RFC7862 - Page 47

11. Error Values

NFS error numbers are assigned to failed operations within a COMPOUND (COMPOUND or CB_COMPOUND) request. A COMPOUND request contains a number of NFS operations that have their results encoded in sequence in a COMPOUND reply. The results of successful operations will consist of an NFS4_OK status followed by the encoded results of the operation. If an NFS operation fails, an error status will be entered in the reply and the COMPOUND request will be terminated.

11.1. Error Definitions

+-------------------------+--------+------------------+ | Error | Number | Description | +-------------------------+--------+------------------+ | NFS4ERR_BADLABEL | 10093 | Section 11.1.3.1 | | NFS4ERR_OFFLOAD_DENIED | 10091 | Section 11.1.2.1 | | NFS4ERR_OFFLOAD_NO_REQS | 10094 | Section 11.1.2.2 | | NFS4ERR_PARTNER_NO_AUTH | 10089 | Section 11.1.2.3 | | NFS4ERR_PARTNER_NOTSUPP | 10088 | Section 11.1.2.4 | | NFS4ERR_UNION_NOTSUPP | 10090 | Section 11.1.1.1 | | NFS4ERR_WRONG_LFS | 10092 | Section 11.1.3.2 | +-------------------------+--------+------------------+ Table 1: Protocol Error Definitions

11.1.1. General Errors

This section deals with errors that are applicable to a broad set of different purposes.
11.1.1.1. NFS4ERR_UNION_NOTSUPP (Error Code 10090)
One of the arguments to the operation is a discriminated union, and while the server supports the given operation, it does not support the selected arm of the discriminated union.

11.1.2. Server-to-Server Copy Errors

These errors deal with the interaction between server-to-server copies.
11.1.2.1. NFS4ERR_OFFLOAD_DENIED (Error Code 10091)
The COPY offload operation is supported by both the source and the destination, but the destination is not allowing it for this file. If the client sees this error, it should fall back to the normal copy semantics.
Top   ToC   RFC7862 - Page 48
11.1.2.2. NFS4ERR_OFFLOAD_NO_REQS (Error Code 10094)
The COPY offload operation is supported by both the source and the destination, but the destination cannot meet the client requirements for either consecutive byte copy or synchronous copy. If the client sees this error, it should either relax the requirements (if any) or fall back to the normal copy semantics.
11.1.2.3. NFS4ERR_PARTNER_NO_AUTH (Error Code 10089)
The source server does not authorize a server-to-server COPY offload operation. This may be due to the client's failure to send the COPY_NOTIFY operation to the source server, the source server receiving a server-to-server copy offload request after the copy lease time expired, or some other permission problem. The destination server does not authorize a server-to-server COPY offload operation. This may be due to an inter-server COPY request where the destination server requires RPCSEC_GSSv3 and it is not used, or some other permissions problem.
11.1.2.4. NFS4ERR_PARTNER_NOTSUPP (Error Code 10088)
The remote server does not support the server-to-server COPY offload protocol.

11.1.3. Labeled NFS Errors

These errors are used in Labeled NFS.
11.1.3.1. NFS4ERR_BADLABEL (Error Code 10093)
The label specified is invalid in some manner.
11.1.3.2. NFS4ERR_WRONG_LFS (Error Code 10092)
The LFS specified in the subject label is not compatible with the LFS in the object label.
Top   ToC   RFC7862 - Page 49

11.2. New Operations and Their Valid Errors

This section contains a table that gives the valid error returns for each new NFSv4.2 protocol operation. The error code NFS4_OK (indicating no error) is not listed but should be understood to be returnable by all new operations. The error values for all other operations are defined in Section 15.2 of [RFC5661]. +----------------+--------------------------------------------------+ | Operation | Errors | +----------------+--------------------------------------------------+ | ALLOCATE | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | | | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | | | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | | | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT, | | | NFS4ERR_EXPIRED, NFS4ERR_FBIG, | | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, | | | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_MOVED, | | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | | | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID, | | | NFS4ERR_OPENMODE, NFS4ERR_OP_NOT_IN_SESSION, | | | NFS4ERR_REP_TOO_BIG, | | | NFS4ERR_REP_TOO_BIG_TO_CACHE, | | | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, | | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | | | NFS4ERR_STALE, NFS4ERR_SYMLINK, | | | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | +----------------+--------------------------------------------------+ | CLONE | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | | | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | | | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | | | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT, | | | NFS4ERR_EXPIRED, NFS4ERR_FBIG, | | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, | | | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_MOVED, | | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | | | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID, | | | NFS4ERR_OPENMODE, NFS4ERR_OP_NOT_IN_SESSION, | | | NFS4ERR_REP_TOO_BIG, | | | NFS4ERR_REP_TOO_BIG_TO_CACHE, | | | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, | | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | | | NFS4ERR_STALE, NFS4ERR_SYMLINK, | | | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE, | | | NFS4ERR_XDEV |
Top   ToC   RFC7862 - Page 50
   +----------------+--------------------------------------------------+
   | COPY           | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT,            |
   |                | NFS4ERR_EXPIRED, NFS4ERR_FBIG,                   |
   |                | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, |
   |                | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_LOCKED,       |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOSPC, NFS4ERR_OFFLOAD_DENIED,           |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE,           |
   |                | NFS4ERR_OP_NOT_IN_SESSION,                       |
   |                | NFS4ERR_PARTNER_NO_AUTH,                         |
   |                | NFS4ERR_PARTNER_NOTSUPP, NFS4ERR_PNFS_IO_HOLE,   |
   |                | NFS4ERR_PNFS_NO_LAYOUT, NFS4ERR_REP_TOO_BIG,     |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT,               |
   |                | NFS4ERR_STALE, NFS4ERR_SYMLINK,                  |
   |                | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE         |
   +----------------+--------------------------------------------------+
   | COPY_NOTIFY    | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED,          |
   |                | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, |
   |                | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_LOCKED,       |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE,           |
   |                | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_PNFS_IO_HOLE, |
   |                | NFS4ERR_PNFS_NO_LAYOUT, NFS4ERR_REP_TOO_BIG,     |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_STALE,              |
   |                | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS,           |
   |                | NFS4ERR_WRONG_TYPE                               |
   +----------------+--------------------------------------------------+
   | DEALLOCATE     | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED,          |
   |                | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, NFS4ERR_GRACE,  |
   |                | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR,        |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID,            |
   |                | NFS4ERR_OPENMODE, NFS4ERR_OP_NOT_IN_SESSION,     |
   |                | NFS4ERR_REP_TOO_BIG,                             |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
Top   ToC   RFC7862 - Page 51
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT,               |
   |                | NFS4ERR_STALE, NFS4ERR_SYMLINK,                  |
   |                | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE         |
   +----------------+--------------------------------------------------+
   | GETDEVICELIST  | NFS4ERR_NOTSUPP                                  |
   +----------------+--------------------------------------------------+
   | IO_ADVISE      | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED,          |
   |                | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, NFS4ERR_GRACE,  |
   |                | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR,        |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID,            |
   |                | NFS4ERR_OP_NOT_IN_SESSION,                       |
   |                | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_SERVERFAULT, |
   |                | NFS4ERR_STALE, NFS4ERR_SYMLINK,                  |
   |                | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE         |
   +----------------+--------------------------------------------------+
   | LAYOUTERROR    | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR,           |
   |                | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION,        |
   |                | NFS4ERR_DELAY, NFS4ERR_DELEG_REVOKED,            |
   |                | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED,              |
   |                | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_ISDIR,     |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOTSUPP, NFS4ERR_NO_GRACE,               |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OP_NOT_IN_SESSION,  |
   |                | NFS4ERR_REP_TOO_BIG,                             |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_STALE,              |
   |                | NFS4ERR_TOO_MANY_OPS,                            |
   |                | NFS4ERR_UNKNOWN_LAYOUTTYPE, NFS4ERR_WRONG_CRED,  |
   |                | NFS4ERR_WRONG_TYPE                               |
   +----------------+--------------------------------------------------+
   | LAYOUTSTATS    | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR,           |
   |                | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION,        |
   |                | NFS4ERR_DELAY, NFS4ERR_DELEG_REVOKED,            |
   |                | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED,              |
   |                | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_ISDIR,     |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOTSUPP, NFS4ERR_NO_GRACE,               |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OP_NOT_IN_SESSION,  |
   |                | NFS4ERR_REP_TOO_BIG,                             |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_STALE,              |
Top   ToC   RFC7862 - Page 52
   |                | NFS4ERR_TOO_MANY_OPS,                            |
   |                | NFS4ERR_UNKNOWN_LAYOUTTYPE, NFS4ERR_WRONG_CRED,  |
   |                | NFS4ERR_WRONG_TYPE                               |
   +----------------+--------------------------------------------------+
   | OFFLOAD_CANCEL | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR,           |
   |                | NFS4ERR_BAD_STATEID, NFS4ERR_COMPLETE_ALREADY,   |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_EXPIRED, NFS4ERR_GRACE, NFS4ERR_NOTSUPP, |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OP_NOT_IN_SESSION,  |
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS        |
   +----------------+--------------------------------------------------+
   | OFFLOAD_STATUS | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR,           |
   |                | NFS4ERR_BAD_STATEID, NFS4ERR_COMPLETE_ALREADY,   |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_EXPIRED, NFS4ERR_GRACE, NFS4ERR_NOTSUPP, |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OP_NOT_IN_SESSION,  |
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS        |
   +----------------+--------------------------------------------------+
   | READ_PLUS      | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED,          |
   |                | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, |
   |                | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_LOCKED,       |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID,            |
   |                | NFS4ERR_OPENMODE, NFS4ERR_OP_NOT_IN_SESSION,     |
   |                | NFS4ERR_PARTNER_NO_AUTH, NFS4ERR_PNFS_IO_HOLE,   |
   |                | NFS4ERR_PNFS_NO_LAYOUT, NFS4ERR_REP_TOO_BIG,     |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_STALE,              |
   |                | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS,           |
   |                | NFS4ERR_WRONG_TYPE                               |
   +----------------+--------------------------------------------------+
   | SEEK           | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED,          |
   |                | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, |
   |                | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_LOCKED,       |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID,            |
   |                | NFS4ERR_OPENMODE, NFS4ERR_OP_NOT_IN_SESSION,     |
   |                | NFS4ERR_PNFS_IO_HOLE, NFS4ERR_PNFS_NO_LAYOUT,    |
   |                | NFS4ERR_REP_TOO_BIG,                             |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
Top   ToC   RFC7862 - Page 53
   |                | NFS4ERR_SERVERFAULT, NFS4ERR_STALE,              |
   |                | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS,           |
   |                | NFS4ERR_UNION_NOTSUPP, NFS4ERR_WRONG_TYPE        |
   +----------------+--------------------------------------------------+
   | WRITE_SAME     | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED,           |
   |                | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID,             |
   |                | NFS4ERR_DEADSESSION, NFS4ERR_DELAY,              |
   |                | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT,            |
   |                | NFS4ERR_EXPIRED, NFS4ERR_FBIG,                   |
   |                | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, |
   |                | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_LOCKED,       |
   |                | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE,             |
   |                | NFS4ERR_NOSPC, NFS4ERR_NOTSUPP,                  |
   |                | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE,           |
   |                | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_PNFS_IO_HOLE, |
   |                | NFS4ERR_PNFS_NO_LAYOUT, NFS4ERR_REP_TOO_BIG,     |
   |                | NFS4ERR_REP_TOO_BIG_TO_CACHE,                    |
   |                | NFS4ERR_REQ_TOO_BIG, NFS4ERR_RETRY_UNCACHED_REP, |
   |                | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT,               |
   |                | NFS4ERR_STALE, NFS4ERR_SYMLINK,                  |
   |                | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE         |
   +----------------+--------------------------------------------------+

       Table 2: Valid Error Returns for Each New Protocol Operation

11.3. New Callback Operations and Their Valid Errors

This section contains a table that gives the valid error returns for each new NFSv4.2 callback operation. The error code NFS4_OK (indicating no error) is not listed but should be understood to be returnable by all new callback operations. The error values for all other callback operations are defined in Section 15.3 of [RFC5661]. +------------+------------------------------------------------------+ | Callback | Errors | | Operation | | +------------+------------------------------------------------------+ | CB_OFFLOAD | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | | | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, | | | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_REP_TOO_BIG, | | | NFS4ERR_REP_TOO_BIG_TO_CACHE, NFS4ERR_REQ_TOO_BIG, | | | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_SERVERFAULT, | | | NFS4ERR_TOO_MANY_OPS | +------------+------------------------------------------------------+ Table 3: Valid Error Returns for Each New Protocol Callback Operation


(next page on part 4)

Next Section