/// struct LAYOUT_WCC4args { /// stateid4 lowa_stateid; /// layouttype4 lowa_type; /// opaque lowa_body<>; /// }; stateid4 is defined in Section 3.3.12 of [RFC8881]. layouttype4 is defined in Section 3.3.13 of [RFC8881]. 3.2. RESULT /// struct LAYOUT_WCC4res { /// nfsstat4 lowr_status; /// }; nfsstat4 is defined in Section 3.2 of [RFC8881]. 3.3. DESCRIPTION The current filehandle and the lowa_stateid identify the specific layout for the LAYOUT_WCC operation. The lowa_type indicates how to interpret the layout-type-specific payload contained in the lowa_body field. The lowa_type is the corresponding value from the "pNFS Layout Types" IANA registry for the layout type being used. The lowa_body contains the data file attributes. The client is responsible for mapping NFSv3 post-operation attributes to the fattr4 representation. Similar to the behavior of post-operation attributes, the client may ignore these attributes, and the server may also choose to ignore any attributes included in LAYOUT_WCC. However, the server can use these attributes to avoid querying the data server for data file attributes. Because these attributes are optional and the client has no recourse if the server opts to disregard them, there is no requirement to return a bitmap4 indicating which attributes have been accepted in the LAYOUT_WCC result. 3.4. Implementation 3.4.1. Examples of When to Use LAYOUT_WCC The only way for the metadata server to detect modifications to the data file is to probe the data servers via a GETATTR. It can compare the mtime results across multiple calls to detect an NFSv3 WRITE operation by the client. Likewise, the atime results indicate the client having issued an NFSv3 READ operation. As such, the client can leverage the LAYOUT_WCC operation whenever it has the belief that the metadata server would need to refresh the attributes of the data files. While the client can send a LAYOUT_WCC at any time, there are times it will want to do this operation in order to avoid having the metadata server issue NFSv3 GETATTR requests to the data servers: * Whenever it sends a GETATTR for any of the following attributes: - size (see Section 5.8.1.5 of [RFC8881]) - space_used (see Section 5.8.2.35 of [RFC8881]) - change (see Section 5.8.1.4 of [RFC8881]) - time_access (see Section 5.8.2.37 of [RFC8881]) - time_metadata (see Section 5.8.2.42 of [RFC8881]) - time_modify (see Section 5.8.2.43 of [RFC8881]) * Whenever it sends an NFS4ERR_ACCESS error via LAYOUTRETURN or LAYOUTERROR. It could have already gotten the NFSv3 uid and gid values back in the WCC of the WRITE, READ, or COMMIT operation that got the error. Thus, it could report that information back to the metadata server, saving it from querying that information via an NFSv3 GETATTR. * Whenever it sends a SETATTR to refresh the proxied times (see Section 5 of [RFC9754]). The metadata server will correlate these times in order to detect later modification to the data file. 3.4.2. Examples of What to Send in LAYOUT_WCC The NFSv3 attributes returned in the WCC of WRITE, READ, and COMMIT operations are a smaller subset of what can be transmitted as an NFSv4 attribute. The mapping of NFSv3 to NFSv4 attributes is shown in Table 1. The LAYOUT_WCC MUST provide all of these attributes to the metadata server. Both the uid and gid are stringified into their respective attributes of owner and owner_group. In the case of NFS4ERR_ACCESS, the reason to provide these two attributes is that the metadata server can compare what it expects the values of the uid and gid of the data file to be versus the actual values. It can then repair the permissions as needed or modify the expected values it has cached. +=================+===================+ | NFSv3 Attribute | NFSv4.2 Attribute | +=================+===================+ | size | size | +-----------------+-------------------+ | used | space_used | +-----------------+-------------------+ | mode | mode | +-----------------+-------------------+ | uid | owner | +-----------------+-------------------+ | gid | owner_group | +-----------------+-------------------+ | atime | time_access | +-----------------+-------------------+ | mtime | time_modify | +-----------------+-------------------+ | ctime | time_metadata | +-----------------+-------------------+ Table 1: NFSv3 to NFSv4.2 Attribute Mappings 3.5. Allowed Errors The LAYOUT_WCC operation can raise the errors listed in Table 2. When an error is encountered, the metadata server can decide to ignore the entire operation, or depending on the layout-type-specific payload, it could decide to apply a portion of the payload. Note that there are no new errors introduced for the LAYOUT_WCC operation and the errors in Table 2 are each defined in Section 15.1 of [RFC8881]. Table 2 can be considered as an extension of Section 15.2 of [RFC8881]. +============+====================================================+ | Operation | Errors | +============+====================================================+ | LAYOUT_WCC | 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 | +------------+----------------------------------------------------+ Table 2: Operations and Their Valid Errors 3.6. Extension of Existing Implementations The new LAYOUT_WCC operation is OPTIONAL for both NFSv4.2 [RFC7863] and the flexible file layout type [RFC8435]. 3.7. Flexible File Layout Type /// struct ff_data_server_wcc4 { /// deviceid4 ffdsw_deviceid; /// stateid4 ffdsw_stateid; /// nfs_fh4 ffdsw_fh_vers<>; /// fattr4 ffdsw_attributes; /// }; /// /// struct ff_mirror_wcc4 { /// ff_data_server_wcc4 ffmw_data_servers<>; /// }; /// /// struct ff_layout_wcc4 { /// ff_mirror_wcc4 fflw_mirrors<>; /// }; The results specific to the flexible file layout type MUST correspond to the ff_layout4 data structure as defined in Section 5.1 of [RFC8435]. There MUST be a one-to-one correspondence between the following: * ff_data_server4 -> ff_data_server_wcc4 * ff_mirror4 -> ff_mirror_wcc4 * ff_layout4 -> ff_layout_wcc4 Each ff_layout4 has an array of ff_mirror4, which has an array of ff_data_server4. Based on the current filehandle and the lowa_stateid, the server can match the reported attributes. But the positional correspondence between the elements is not sufficient to determine the attributes to update. Consider the case where a layout has three mirrors and two of them have updated attributes but the third does not. A client could decide to present all three mirrors, with one mirror having an attribute mask with no attributes present. Or it could decide to present only the two mirrors that had been changed. In either case, the combination of ffdsw_deviceid, ffdsw_stateid, and ffdsw_fh_vers will uniquely identify the attributes to be updated. All three arguments are required. A layout might have multiple data files on the same storage device, in which case the ffdsw_deviceid and ffdsw_stateid would match, but the ffdsw_fh_vers would not. The ffdsw_attributes are processed similar to the obj_attributes in the SETATTR arguments (see Section 18.30 of [RFC8881]). 4. Extraction of XDR This document contains the XDR [RFC4506] description of the new NFSv4.2 operation LAYOUT_WCC. The XDR description is embedded in this document in a way that makes it simple for the reader to extract into a ready-to-compile form. The reader can feed this document into the following shell script to produce the machine-readable XDR description of the new NFSv4.2 operation LAYOUT_WCC. #!/bin/sh grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??' That is, if the above script is stored in a file called 'extract.sh', and this document is in a file called 'spec.txt', then the reader can do: sh extract.sh < spec.txt > layout_wcc.x The effect of the script is to remove leading blank space from each line, plus a sentinel sequence of '///'. XDR descriptions with the sentinel sequence are embedded throughout the document. Note that the XDR code contained in this document depends on types from the NFSv4.2 nfs4_prot.x file (generated from [RFC7863]). This includes both nfs types that end with a 4 (such as offset4 and length4) as well as more generic types (such as uint32_t and uint64_t). While the XDR can be appended to that from [RFC7863], the various code snippets belong in their respective areas of that XDR. 5. Security Considerations There are no new security considerations beyond those in [RFC8435]. 6. IANA Considerations This document has no IANA actions. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC4506] Eisler, M., Ed., "XDR: External Data Representation Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May 2006, . [RFC7862] Haynes, T., "Network File System (NFS) Version 4 Minor Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862, November 2016, . [RFC7863] Haynes, T., "Network File System (NFS) Version 4 Minor Version 2 External Data Representation Standard (XDR) Description", RFC 7863, DOI 10.17487/RFC7863, November 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor Versions", RFC 8178, DOI 10.17487/RFC8178, July 2017, . [RFC8434] Haynes, T., "Requirements for Parallel NFS (pNFS) Layout Types", RFC 8434, DOI 10.17487/RFC8434, August 2018, . [RFC8435] Halevy, B. and T. Haynes, "Parallel NFS (pNFS) Flexible File Layout", RFC 8435, DOI 10.17487/RFC8435, August 2018, . [RFC8881] Noveck, D., Ed. and C. Lever, "Network File System (NFS) Version 4 Minor Version 1 Protocol", RFC 8881, DOI 10.17487/RFC8881, August 2020, . [RFC9754] Haynes, T. and T. Myklebust, "Extensions for Opening and Delegating Files in NFSv4.2", RFC 9754, DOI 10.17487/RFC9754, March 2025, . 7.2. Informative References [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS Version 3 Protocol Specification", RFC 1813, DOI 10.17487/RFC1813, June 1995, . Acknowledgments Dave Noveck, Tigran Mkrtchyan, and Rick Macklem provided reviews of the document. Authors' Addresses Thomas Haynes Hammerspace Email: loghyr@gmail.com Trond Myklebust Hammerspace Email: trondmy@hammerspace.com
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4