RFC 7862
Network File System (NFS) Version 4 Minor Version 2 Protocol
12. New File Attributes
12.1. New RECOMMENDED Attributes - List and Definition References
The list of new RECOMMENDED attributes appears in Table 4. The meanings of the columns of the table are: Name: The name of the attribute. Id: The number assigned to the attribute. In the event of conflicts between the assigned number and [RFC7863], the latter is authoritative, but in such an event, it should be resolved with errata to this document and/or [RFC7863]. See [IESG08] for the errata process. Data Type: The XDR data type of the attribute. Acc: Access allowed to the attribute. R means read-only (GETATTR may retrieve, SETATTR may not set). W means write-only (SETATTR may set, GETATTR may not retrieve). R W means read/write (GETATTR may retrieve, SETATTR may set). Defined in: The section of this specification that describes the attribute. +------------------+----+-------------------+-----+----------------+ | Name | Id | Data Type | Acc | Defined in | +------------------+----+-------------------+-----+----------------+ | clone_blksize | 77 | uint32_t | R | Section 12.2.1 | | space_freed | 78 | length4 | R | Section 12.2.2 | | change_attr_type | 79 | change_attr_type4 | R | Section 12.2.3 | | sec_label | 80 | sec_label4 | R W | Section 12.2.4 | +------------------+----+-------------------+-----+----------------+ Table 4: New RECOMMENDED Attributes12.2. Attribute Definitions
12.2.1. Attribute 77: clone_blksize
The clone_blksize attribute indicates the granularity of a CLONE operation.
12.2.2. Attribute 78: space_freed
space_freed gives the number of bytes freed if the file is deleted. This attribute is read-only and is of type length4. It is a per-file attribute.12.2.3. Attribute 79: change_attr_type
<CODE BEGINS> enum change_attr_type4 { NFS4_CHANGE_TYPE_IS_MONOTONIC_INCR = 0, NFS4_CHANGE_TYPE_IS_VERSION_COUNTER = 1, NFS4_CHANGE_TYPE_IS_VERSION_COUNTER_NOPNFS = 2, NFS4_CHANGE_TYPE_IS_TIME_METADATA = 3, NFS4_CHANGE_TYPE_IS_UNDEFINED = 4 }; <CODE ENDS> change_attr_type is a per-file system attribute that enables the NFSv4.2 server to provide additional information about how it expects the change attribute value to evolve after the file data or metadata has changed. While Section 5.4 of [RFC5661] discusses per-file system attributes, it is expected that the value of change_attr_type will not depend on the value of "homogeneous" and will only change in the event of a migration. NFS4_CHANGE_TYPE_IS_MONOTONIC_INCR: The change attribute value MUST monotonically increase for every atomic change to the file attributes, data, or directory contents. NFS4_CHANGE_TYPE_IS_VERSION_COUNTER: The change attribute value MUST be incremented by one unit for every atomic change to the file attributes, data, or directory contents. This property is preserved when writing to pNFS data servers. NFS4_CHANGE_TYPE_IS_VERSION_COUNTER_NOPNFS: The change attribute value MUST be incremented by one unit for every atomic change to the file attributes, data, or directory contents. In the case where the client is writing to pNFS data servers, the number of increments is not guaranteed to exactly match the number of WRITEs.
NFS4_CHANGE_TYPE_IS_TIME_METADATA: The change attribute is
implemented as suggested in [RFC7530] in terms of the
time_metadata attribute.
NFS4_CHANGE_TYPE_IS_UNDEFINED: The change attribute does not take
values that fit into any of these categories.
If either NFS4_CHANGE_TYPE_IS_MONOTONIC_INCR,
NFS4_CHANGE_TYPE_IS_VERSION_COUNTER, or
NFS4_CHANGE_TYPE_IS_TIME_METADATA is set, then the client knows at
the very least that the change attribute is monotonically increasing,
which is sufficient to resolve the question of which value is the
most recent.
If the client sees the value NFS4_CHANGE_TYPE_IS_TIME_METADATA, then
by inspecting the value of the "time_delta" attribute it additionally
has the option of detecting rogue server implementations that use
time_metadata in violation of the specification.
If the client sees NFS4_CHANGE_TYPE_IS_VERSION_COUNTER, it has the
ability to predict what the resulting change attribute value should
be after a COMPOUND containing a SETATTR, WRITE, or CREATE. This
again allows it to detect changes made in parallel by another client.
The value NFS4_CHANGE_TYPE_IS_VERSION_COUNTER_NOPNFS permits the
same, but only if the client is not doing pNFS WRITEs.
Finally, if the server does not support change_attr_type or if
NFS4_CHANGE_TYPE_IS_UNDEFINED is set, then the server SHOULD make an
effort to implement the change attribute in terms of the
time_metadata attribute.
12.2.4. Attribute 80: sec_label
<CODE BEGINS>
typedef uint32_t policy4;
struct labelformat_spec4 {
policy4 lfs_lfs;
policy4 lfs_pi;
};
struct sec_label4 {
labelformat_spec4 slai_lfs;
opaque slai_data<>;
};
<CODE ENDS>
The FATTR4_SEC_LABEL contains an array of two components, with the first component being an LFS. It serves to provide the receiving end with the information necessary to translate the security attribute into a form that is usable by the endpoint. Label Formats assigned an LFS may optionally choose to include a Policy Identifier field to allow for complex policy deployments. The LFS and the Security Label Format Selection Registry are described in detail in [RFC7569]. The translation used to interpret the security attribute is not specified as part of the protocol, as it may depend on various factors. The second component is an opaque section that contains the data of the attribute. This component is dependent on the MAC model to interpret and enforce. In particular, it is the responsibility of the LFS specification to define a maximum size for the opaque section, slai_data<>. When creating or modifying a label for an object, the client needs to be guaranteed that the server will accept a label that is sized correctly. By both client and server being part of a specific MAC model, the client will be aware of the size.13. Operations: REQUIRED, RECOMMENDED, or OPTIONAL
Tables 5 and 6 summarize the operations of the NFSv4.2 protocol and the corresponding designations of REQUIRED, RECOMMENDED, and OPTIONAL to implement or MUST NOT implement. The "MUST NOT implement" designation is reserved for those operations that were defined in either NFSv4.0 or NFSv4.1 and MUST NOT be implemented in NFSv4.2. For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation for operations sent by the client is for the server implementation. The client is generally required to implement the operations needed for the operating environment that it serves. For example, a read-only NFSv4.2 client would have no need to implement the WRITE operation and is not required to do so. The REQUIRED or OPTIONAL designation for callback operations sent by the server is for both the client and server. Generally, the client has the option of creating the backchannel and sending the operations on the forechannel that will be a catalyst for the server sending callback operations. A partial exception is CB_RECALL_SLOT; the only way the client can avoid supporting this operation is by not creating a backchannel.
Since this is a summary of the operations and their designation, there are subtleties that are not presented here. Therefore, if there is a question regarding implementation requirements, the operation descriptions themselves must be consulted, along with other relevant explanatory text within either this specification or the NFSv4.1 specification [RFC5661]. The abbreviations used in the second and third columns of Tables 5 and 6 are defined as follows: REQ: REQUIRED to implement REC: RECOMMENDED to implement OPT: OPTIONAL to implement MNI: MUST NOT implement For the NFSv4.2 features that are OPTIONAL, the operations that support those features are OPTIONAL, and the server MUST return NFS4ERR_NOTSUPP in response to the client's use of those operations when those operations are not implemented by the server. If an OPTIONAL feature is supported, it is possible that a set of operations related to the feature become REQUIRED to implement. The third column of the tables designates the feature(s) and if the operation is REQUIRED or OPTIONAL in the presence of support for the feature. The OPTIONAL features identified and their abbreviations are as follows: pNFS: Parallel NFS FDELG: File Delegations DDELG: Directory Delegations COPYra: Intra-server Server-Side Copy COPYer: Inter-server Server-Side Copy ADB: Application Data Blocks
+----------------------+--------------------+-----------------------+
| Operation | REQ, REC, OPT, or | Feature (REQ, REC, or |
| | MNI | OPT) |
+----------------------+--------------------+-----------------------+
| ACCESS | REQ | |
| ALLOCATE | OPT | |
| BACKCHANNEL_CTL | REQ | |
| BIND_CONN_TO_SESSION | REQ | |
| CLONE | OPT | |
| CLOSE | REQ | |
| COMMIT | REQ | |
| COPY | OPT | COPYer (REQ), COPYra |
| | | (REQ) |
| COPY_NOTIFY | OPT | COPYer (REQ) |
| CREATE | REQ | |
| CREATE_SESSION | REQ | |
| DEALLOCATE | OPT | |
| DELEGPURGE | OPT | FDELG (REQ) |
| DELEGRETURN | OPT | FDELG, DDELG, pNFS |
| | | (REQ) |
| DESTROY_CLIENTID | REQ | |
| DESTROY_SESSION | REQ | |
| EXCHANGE_ID | REQ | |
| FREE_STATEID | REQ | |
| GETATTR | REQ | |
| GETDEVICEINFO | OPT | pNFS (REQ) |
| GETDEVICELIST | MNI | pNFS (MNI) |
| GETFH | REQ | |
| GET_DIR_DELEGATION | OPT | DDELG (REQ) |
| ILLEGAL | REQ | |
| IO_ADVISE | OPT | |
| LAYOUTCOMMIT | OPT | pNFS (REQ) |
| LAYOUTERROR | OPT | pNFS (OPT) |
| LAYOUTGET | OPT | pNFS (REQ) |
| LAYOUTRETURN | OPT | pNFS (REQ) |
| LAYOUTSTATS | OPT | pNFS (OPT) |
| LINK | OPT | |
| LOCK | REQ | |
| LOCKT | REQ | |
| LOCKU | REQ | |
| LOOKUP | REQ | |
| LOOKUPP | REQ | |
| NVERIFY | REQ | |
| OFFLOAD_CANCEL | OPT | COPYer (OPT), COPYra |
| | | (OPT) |
| OFFLOAD_STATUS | OPT | COPYer (OPT), COPYra |
| | | (OPT) |
| OPEN | REQ | | | OPENATTR | OPT | | | OPEN_CONFIRM | MNI | | | OPEN_DOWNGRADE | REQ | | | PUTFH | REQ | | | PUTPUBFH | REQ | | | PUTROOTFH | REQ | | | READ | REQ | | | READDIR | REQ | | | READLINK | OPT | | | READ_PLUS | OPT | | | RECLAIM_COMPLETE | REQ | | | RELEASE_LOCKOWNER | MNI | | | REMOVE | REQ | | | RENAME | REQ | | | RENEW | MNI | | | RESTOREFH | REQ | | | SAVEFH | REQ | | | SECINFO | REQ | | | SECINFO_NO_NAME | REC | pNFS file layout | | | | (REQ) | | SEEK | OPT | | | SEQUENCE | REQ | | | SETATTR | REQ | | | SETCLIENTID | MNI | | | SETCLIENTID_CONFIRM | MNI | | | SET_SSV | REQ | | | TEST_STATEID | REQ | | | VERIFY | REQ | | | WANT_DELEGATION | OPT | FDELG (OPT) | | WRITE | REQ | | | WRITE_SAME | OPT | ADB (REQ) | +----------------------+--------------------+-----------------------+ Table 5: Operations
+-------------------------+------------------+----------------------+ | Operation | REQ, REC, OPT, | Feature (REQ, REC, | | | or MNI | or OPT) | +-------------------------+------------------+----------------------+ | CB_GETATTR | OPT | FDELG (REQ) | | CB_ILLEGAL | REQ | | | CB_LAYOUTRECALL | OPT | pNFS (REQ) | | CB_NOTIFY | OPT | DDELG (REQ) | | CB_NOTIFY_DEVICEID | OPT | pNFS (OPT) | | CB_NOTIFY_LOCK | OPT | | | CB_OFFLOAD | OPT | COPYer (REQ), COPYra | | | | (REQ) | | CB_PUSH_DELEG | OPT | FDELG (OPT) | | CB_RECALL | OPT | FDELG, DDELG, pNFS | | | | (REQ) | | CB_RECALL_ANY | OPT | FDELG, DDELG, pNFS | | | | (REQ) | | CB_RECALL_SLOT | REQ | | | CB_RECALLABLE_OBJ_AVAIL | OPT | DDELG, pNFS (REQ) | | CB_SEQUENCE | OPT | FDELG, DDELG, pNFS | | | | (REQ) | | CB_WANTS_CANCELLED | OPT | FDELG, DDELG, pNFS | | | | (REQ) | +-------------------------+------------------+----------------------+ Table 6: Callback Operations14. Modifications to NFSv4.1 Operations
14.1. Operation 42: EXCHANGE_ID - Instantiate the client ID
14.1.1. ARGUMENT
<CODE BEGINS> /* new */ const EXCHGID4_FLAG_SUPP_FENCE_OPS = 0x00000004; <CODE ENDS>14.1.2. RESULT
Unchanged
14.1.3. MOTIVATION
Enterprise applications require guarantees that an operation has either aborted or completed. NFSv4.1 provides this guarantee as long as the session is alive: simply send a SEQUENCE operation on the same slot with a new sequence number, and the successful return of SEQUENCE indicates that the previous operation has completed. However, if the session is lost, there is no way to know when any operations in progress have aborted or completed. In hindsight, the NFSv4.1 specification should have mandated that DESTROY_SESSION either abort or complete all outstanding operations.14.1.4. DESCRIPTION
A client SHOULD request the EXCHGID4_FLAG_SUPP_FENCE_OPS capability when it sends an EXCHANGE_ID operation. The server SHOULD set this capability in the EXCHANGE_ID reply whether the client requests it or not. It is the server's return that determines whether this capability is in effect. When it is in effect, the following will occur: o The server will not reply to any DESTROY_SESSION invoked with the client ID until all operations in progress are completed or aborted. o The server will not reply to subsequent EXCHANGE_ID operations invoked on the same client owner with a new verifier until all operations in progress on the client ID's session are completed or aborted. o In implementations where the NFS server is deployed as a cluster, it does support client ID trunking, and the EXCHGID4_FLAG_SUPP_FENCE_OPS capability is enabled, then a session ID created on one node of the storage cluster MUST be destroyable via DESTROY_SESSION. In addition, DESTROY_CLIENTID and an EXCHANGE_ID with a new verifier affect all sessions, regardless of what node the sessions were created on.
14.2. Operation 48: GETDEVICELIST - Get all device mappings for a file system
14.2.1. ARGUMENT
<CODE BEGINS> struct GETDEVICELIST4args { /* CURRENT_FH: object belonging to the file system */ layouttype4 gdla_layout_type; /* number of device IDs to return */ count4 gdla_maxdevices; nfs_cookie4 gdla_cookie; verifier4 gdla_cookieverf; }; <CODE ENDS>14.2.2. RESULT
<CODE BEGINS> struct GETDEVICELIST4resok { nfs_cookie4 gdlr_cookie; verifier4 gdlr_cookieverf; deviceid4 gdlr_deviceid_list<>; bool gdlr_eof; }; union GETDEVICELIST4res switch (nfsstat4 gdlr_status) { case NFS4_OK: GETDEVICELIST4resok gdlr_resok4; default: void; }; <CODE ENDS>14.2.3. MOTIVATION
The GETDEVICELIST operation was introduced in [RFC5661] specifically to request a list of devices at file system mount time from block layout type servers. However, the use of the GETDEVICELIST operation introduces a race condition versus notification about changes to pNFS device IDs as provided by CB_NOTIFY_DEVICEID. Implementation experience with block layout servers has shown that there is no need
for GETDEVICELIST. Clients have to be able to request new devices using GETDEVICEINFO at any time in response to either a new deviceid in LAYOUTGET results or the CB_NOTIFY_DEVICEID callback operation.14.2.4. DESCRIPTION
Clients and servers MUST NOT implement the GETDEVICELIST operation.
(page 64 continued on part 5)
