Network File System Version 4 R. Macklem Internet-Draft FreeBSD Intended status: Standards Track 29 December 2021 Expires: 2 July 2022 New Attributes for Network File System Version 4, Minor Version 2 draft-rmacklem-nfsv4-new-attributes-00 Abstract This document proposes several new recommended attributes that extend the Network File System Version 4, Minor Version 2 protocol (NFSv4.2). All of these new attributes are read-only, per file system attributes. Note This note is to be removed before publishing as an RFC. Discussion of this draft occurs on the NFSv4 working group mailing list (nfsv4@ietf.org), archived at https://mailarchive.ietf.org/arch/browse/nfsv4/. Working Group information is available at https://datatracker.ietf.org/wg/nfsv4/ about/. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 2 July 2022. Copyright Notice Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. Macklem Expires 2 July 2022 [Page 1] Internet-Draft New Attributes for NFSv4.2 December 2021 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Protocol Extension Considerations . . . . . . . . . . . . . . 2 3. List of new per-file system Attributes . . . . . . . . . . . 2 4. New Attributes . . . . . . . . . . . . . . . . . . . . . . . 3 5. RECOMMENDED New Attributes - List and Definition References . . . . . . . . . . . . . . . . . . . . . . . 3 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 6 6.1. FreeBSD NFS server and client . . . . . . . . . . . . . . 6 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 7.2. Informational References . . . . . . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction Implementation experience with NFSv4.2 has identified that some additional attributes providing per file system information to clients are useful. This document specifies these additional recommended attributes. 2. Protocol Extension Considerations This document presents an extension to minor version 2 of the NFSv4 protocol as described in [RFC8178]. It describes new OPTIONAL features. NFSv4.2 servers and clients implemented without knowledge of this extension will continue to interoperate with clients and servers that are aware of the extension (whether or not they support it). Note that [RFC7862] does not define NFSv4.2 as non-extensible, so [RFC8178] treats it as an extensible minor version. This Standards Track RFC extends NFSv4.2 but does not update [RFC7862] or [RFC8178]. 3. List of new per-file system Attributes * The per-file system attributes are: Macklem Expires 2 July 2022 [Page 2] Internet-Draft New Attributes for NFSv4.2 December 2021 supported_operations, directory_cookie_monotonically_increasing, seek_granularity, mandatory_locking, maximum_extended_attribute_length 4. New Attributes All of these attributes are read-only. 5. RECOMMENDED New Attributes - List and Definition References The list of New RECOMMENDED attributes appears in Table 1. The meaning of the columns of the table are: Name: The name of the attribute. Id: The number assigned to the attribute. Data Type: The XDR data type of the attribute. Acc: Access allowed to the attribute. R means read-only. Defined in: The section of this specification that describes the attribute. +===========================================+==+========+===+=======+ | Name |Id|Data |Acc|Defined| | | |Type | |in: | +===========================================+==+========+===+=======+ | supported_operations |83|bitmap4 |R |Section| | | | | |5.1.1 | +-------------------------------------------+--+--------+---+-------+ | directory_cookie_monotonically_increasing |84|bool |R |Section| | | | | |5.1.2 | +-------------------------------------------+--+--------+---+-------+ | seek_granularity |85|uint64_t|R |Section| | | | | |5.1.3 | +-------------------------------------------+--+--------+---+-------+ | mandatory_locking |86|bool |R |Section| | | | | |5.1.4 | +-------------------------------------------+--+--------+---+-------+ | maximum_extended_attribute_length |87|uint64_t|R |Section| | | | | |5.1.5 | +-------------------------------------------+--+--------+---+-------+ Table 1 Macklem Expires 2 July 2022 [Page 3] Internet-Draft New Attributes for NFSv4.2 December 2021 5.1. Definitions of New RECOMMENDED Attributes The definitions of the new RECOMMENDED attributes follow. 5.1.1. Attribute 83: supported_operations The bit vector that indicates all operations that are supported for this object. The scope of this attribute applies to all objects with a matching fsid. The bit vector is a counted array of 32-bit integers used to contain bit values. The position of the integer in the array that contains bit n can be computed from the expression (n / 32), and its bit within that integer is (n mod 32), where n is the operation number. 5.1.2. Attribute 84: directory_cookie_monotonically_increasing TRUE, if the READDIR operation always returns monotonically increasing directory offset cookies for the file system system object. The scope of this attribute applies to all objects with a matching fsid. 5.1.3. Attribute 85: seek_granularity This attribute indicates the minimum granuarity of an unallocated region. The scope of this attribute applies to all objects with a matching fsid. 0, if the SEEK operation will not return unallocated regions (holes). 1, if the SEEK operation will return unallocated regions (holes), but of no fixed granularity > 1, if the SEEK operation will return unallocated regions (holes), which are an exact multiple of this attribute in length. If the file system does not support the SEEK operation, a value of 0 should be returned for this attribute. 5.1.4. Attribute 86: mandatory_locking TRUE, if mandatory byte range locking is applied to this file object. The scope of this attribute applies to all objects with a matching fsid. Macklem Expires 2 July 2022 [Page 4] Internet-Draft New Attributes for NFSv4.2 December 2021 5.1.5. Attribute 87: maximum_extended_attribute_length The maximum length, in bytes, of the extended attribute that can be set by the SETXATTR operation for this file object. The SETXATTR operation is one of the operations described in the [RFC8276] extension to NFSv4.2. The scope of this attribute applies to all objects with a matching fsid. 5.2. Rational for New RECOMMENDED Attributes The rationale for the new RECOMMENDED attributes follow. 5.2.1. Attribute 83: supported_operations Without this attribute, an NFSv4.2 client must attempt an optional operation to determine if the server supports it. This attribute allows the NFSv4.2 client to avoid attempting an optional operation when it is not supported for the file object's file system on the server. 5.2.2. Attribute 84: directory_cookie_monotonically_increasing If the NFSv4.2 client knows that directory offset cookies in READDIR replies are monotonically increasing, it might make it feasible to implement client side support for directory delegation. As an example, implementing client side directory delegation support is much easier when the directory offset cookies are monotonically increasing, so they can be used to order directory entries. Further, the client needs to know that the directory offset cookies are monotonically increasing before reading a directory, so that acquisition and use of a directory delegation may be done. Client side directory caching may also benefit from monotonically increasing directory offset cookies. For example, the Linux NFSv4.2 client uses a different caching algorithm when directory offset cookies are monotonically increasing. 5.2.3. Attribute 85: seek_granularity A NFSv4.2 client can avoid performing RPCs doing the SEEK operation when this attribute is equal 0 or whenever the client can determine that holes greater or equal to the value of this attribute do not exist in the file. Macklem Expires 2 July 2022 [Page 5] Internet-Draft New Attributes for NFSv4.2 December 2021 5.2.4. Attribute 86: mandatory_locking A NFSv4.2 client cannot cache data for a file object unless it holds an appropriate byte range lock if the server is implementing mandatory byte range locking. Since client side data caching is required for good performance, the client needs to know that the server is implementing mandatory byte range locking, so that it can aquire byte range locks for the byte ranges being cached. 5.2.5. Attribute 87: maximum_extended_attribute_length This attribute allows a NFSv4.2 client to avoid attempting a SETXATTR operation when the length of the extended attribute is greater than the maximum specified by this attribute. 6. Implementation Status This section is to be removed before publishing as an RFC. This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. 6.1. FreeBSD NFS server and client Organization: FreeBSD Project URL: https://www.freebsd.org Maturity: Prototype software based on the current document. Coverage: The bulk of this specification is implemented. Licensing: BSD Implementation experience: The implementation of these attributes Macklem Expires 2 July 2022 [Page 6] Internet-Draft New Attributes for NFSv4.2 December 2021 have allowed the NFSv4.2 client to avoid unnecessary RPCs against the server. The current client implementation does not include support for directory delegations nor makes use of the directory_cookie_monotonically_increasing attribute. The current client implementation does not support mandatory byte range locking. 7. References 7.1. Normative References [RFC7862] Haynes, T., "Network File System (NFS) Version 4 Minor Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862, November 2016, . [RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor Versions", RFC 8178, DOI 10.17487/RFC8178, July 2017, . [RFC8276] Naik, M. and M. Eshel, "File System Extended Attributes in NFSv4", RFC 8276, DOI 10.17487/RFC8276, December 2017, . 7.2. Informational References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [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, . Author's Address Rick Macklem FreeBSD Project Canada Email: rmacklem@uoguelph.ca Macklem Expires 2 July 2022 [Page 7]