Network File System Version 4 T. Haynes Internet-Draft Hammerspace Intended status: Standards Track 20 January 2026 Expires: 24 July 2026 Adding an Uncacheable Directory-Entry Metadata Attribute to NFSv4.2 draft-ietf-nfsv4-uncacheable-directories-02 Abstract Network File System version 4.2 (NFSv4.2) clients commonly cache directory entries (dirents) to improve performance. While effective in many cases, such caching can prevent servers from enforcing per- user access controls on directory entries and up-to-date directory entry attributes such as size and timestamps. This document introduces a new uncacheable dirent metadata attribute for NFSv4.2 that allows servers to advise clients that caching of directory entry metadata is unsuitable. This enables servers to present directory contents based on user-specific access permissions while remaining compatible with existing NFSv4.2 clients. Note to Readers Discussion of this draft takes place on the NFSv4 working group mailing list (nfsv4@ietf.org), which is archived at https://mailarchive.ietf.org/arch/search/?email_list=nfsv4. Source code and issues list for this draft can be found at https://github.com/ietf-wg-nfsv4/uncacheable-directories. Working Group information can be found at https://github.com/ietf-wg- nfsv4. 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." Haynes Expires 24 July 2026 [Page 1] Internet-Draft Uncacheable Dirents January 2026 This Internet-Draft will expire on 24 July 2026. Copyright Notice Copyright (c) 2026 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 (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 1.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 4 2. Caching of Directory-Entry Metadata . . . . . . . . . . . . . 5 2.1. Uncacheable Directory-Entry Metadata . . . . . . . . . . 6 3. XDR for Uncacheable Dirents Attribute . . . . . . . . . . . . 6 4. Extraction of XDR . . . . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 7.2. Informative References . . . . . . . . . . . . . . . . . 8 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction Clients of remote filesystems commonly cache directory entries (dirents) to improve performance. This caching is typically shared across users on the client and assumes that directory contents and access permissions are uniform across users. In this document, the term directory is used to describe the context in which directory entries are retrieved. The uncacheable dirent metadata attribute applies to the caching of directory entry (dirent) metadata, including names and associated file object metadata such as size and timestamps. It does not prohibit caching of the directory object itself, nor does it affect caching of file data. Haynes Expires 24 July 2026 [Page 2] Internet-Draft Uncacheable Dirents January 2026 Access Based Enumeration (ABE) [MS-ABE], as implemented in the Server Message Block (SMB) [MS-SMB2] and deployed in implementations such as Samba [Samba], restricts directory visibility based on the access permissions of the requesting user. Implementing similar behavior in NFSv4.2 requires server involvement, as clients may not have sufficient information to evaluate permissions based on identity mappings, ACLs, or server-local policy. While effective in environments with centralized identity and server- driven enumeration, the SMB ABE model tightly couples directory enumeration with authorization and requires per-user directory views that are not safely cacheable across users. This approach does not generalize well to NFS, where directory contents and metadata are traditionally shared and cached. The uncacheable dirent metadata attribute allows servers to ensure correctness of directory-entry metadata visibility and attributes without mandating a specific enumeration or authorization model. Even in the absence of ABE, caching of directory entry metadata can result in incorrect size and timestamp information when files are modified concurrently, reducing the effectiveness of uncacheable file data semantics when directory entry metadata is stale. This document introduces the uncacheable dirent metadata attribute to NFSv4.2 to allow servers to advise clients that caching of directory- entry metadata is unsuitable. This enables correct presentation of directory entry visibility and attributes, including but not limited to Access Based Enumeration (ABE). As such, it is an OPTIONAL attribute to implement for NFSv4.2. If both the client and the server support this attribute, the client is advised to bypass caching of directory-entry metadata for directories marked as uncacheable. The uncacheable dirent metadata attribute is read-write and applies to directory objects. The data type is bool. Allowing clients to set this attribute provides a portable mechanism to request that directory-entry metadata not be cached, without requiring changes to application behavior or out-of-band administrative configuration. A client can determine whether the uncacheable dirent metadata attribute is supported for a given directory by issuing a GETATTR request and examining the returned attribute list. The only way that the server can determine that the client supports the attribute is if the client sends either a GETATTR or a SETATTR with the uncacheable dirent metadata attribute. Haynes Expires 24 July 2026 [Page 3] Internet-Draft Uncacheable Dirents January 2026 The uncacheable dirent metadata attribute governs caching behavior of directory-entry metadata returned by READDIR and related operations, not the directory object itself. Suppressing caching of file data alone is insufficient to guarantee correct behavior if directory-entry metadata such as size and timestamps remains cached. The uncacheable dirent metadata attribute complements the fattr4_uncacheable_file_data attribute by ensuring directory-entry metadata correctness. Using the process detailed in [RFC8178], the revisions in this document become an extension of NFSv4.2 [RFC7862]. They are built on top of the external data representation (XDR) [RFC4506] generated from [RFC7863]. 1.1. Definitions Access Based Enumeration (ABE) When servicing a READDIR or GETATTR operation, the server provides results based on the access permissions of the user making the request. dirent A directory entry representing a file or subdirectory and its associated attributes. dirent caching A client-side cache of directory entry names and associated file object metadata, used to avoid repeated directory lookup and attribute retrieval. uncacheable dirent metadata attribute An NFSv4.2 file attribute that advises clients not to cache directory-entry metadata associated with file objects, including names, size, timestamps, and visibility. This document assumes familiarity with NFSv4.2 operations, attributes, and error handling as defined in [RFC8881] and [RFC7862]. 1.2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Haynes Expires 24 July 2026 [Page 4] Internet-Draft Uncacheable Dirents January 2026 2. Caching of Directory-Entry Metadata With a remote filesystem, the client typically caches directory entries (dirents) locally to improve performance. This cooperation succeeds because both the server and client operate under POSIX semantics ([POSIX.1]) and agree to interpretation of mode bits with respect to the uid and gid in NFSv3 [RFC1813]. For NFSv4.2, these would respectively be the mode, owner, and owner_group attributes defined in Section 5 of [RFC8881]. Note that this cooperation does not apply to Access Control List (ACLs) entries as NFSv4.2 does not implement a strict POSIX style ACL. NFSv4.2 does implement NFSv4.1 ACLs, which are enforced on the server and not the client. As such, ACL enforcement requires the client to bypass the dirent cache to have checks done when a new user attempts to access the dirent. Another consideration is that not all server implementations natively support SMB. Instead, they layer Samba on top of the NFSv4.2 service. The attributes of hidden, system, and offline have already been introduced in the NFSv4.2 protocol to support Samba. The Samba implementation can utilize these attributes to provide SMB semantics. While private protocols can supply these features, it is better to drive them into open standards. Another concept that can be adapted from SMB is that of ABE If a a directory has ABE enabled, then the user can only see the files and sub-directories for which they have permissions. Under the POSIX model, this can be done on the client and not the server. However, that only works with uid, gid, and mode bits. If we consider identity mappings, ACLs, and server local policies, then the determination of ABE and directory entry visibility is best performed on the server. Since cached dirents are shared by all users on a client, and the client cannot determine access permissions for individual dirents, all users are presented with the same set of attributes. To address this, this document introduces the uncacheable dirent metadata attribute. This attribute advises the client not to cache directory entry metadata for a file or directory object. Consequently, each time a client queries for these attributes, the server's response can be tailored to the specific user making the request. This attribute does not define behavior for positive or negative name caching or for caching of LOOKUP results outside the scope of directory-entry metadata returned by READDIR and related operations. Haynes Expires 24 July 2026 [Page 5] Internet-Draft Uncacheable Dirents January 2026 Directory delegations do not address per-user directory-entry metadata visibility and therefore cannot replace the semantics defined by the uncacheable dirent metadata attribute. 2.1. Uncacheable Directory-Entry Metadata If a file object or directory has the uncacheable dirent metadata attribute set, the client is advised not to cache directory entry metadata. In such cases, the client retrieves directory entry attributes from the server for each request, allowing the server to evaluate access permissions based on the requesting user. Clients are advised not to share cached dirent attributes between different users. Servers MUST assume that clients which do not query or set this attribute may cache directory-entry metadata, and therefore MUST NOT rely on this attribute for correctness unless client support is confirmed. 3. XDR for Uncacheable Dirents Attribute /// /// typedef bool fattr4_uncacheable_dirent_metadata; /// /// const FATTR4_UNCACHEABLE_DIRENT_METADATA = 88; /// 4. Extraction of XDR This document contains the external data representation (XDR) [RFC4506] description of the uncacheable dirent metadata attribute. The XDR description is presented in a manner that facilitates easy extraction into a ready-to-compile format. To extract the machine- readable XDR description, use the following shell script: #!/bin/sh grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??' For example, if the script is named 'extract.sh' and this document is named 'spec.txt', execute the following command: sh extract.sh < spec.txt > uncacheable_prot.x This script removes leading blank spaces and the sentinel sequence '///' from each line. XDR descriptions with the sentinel sequence are embedded throughout the document. Haynes Expires 24 July 2026 [Page 6] Internet-Draft Uncacheable Dirents January 2026 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, length4, etc., as well as more generic types such as uint32_t and uint64_t. While the XDR can be appended to that from [RFC7863], the code snippets should be placed in their appropriate sections within the existing XDR. 5. Security Considerations For a given user A, a client MUST NOT make access decisions for uncacheable dirents retrieved for another user B. These decisions MUST be made by the server. If the client is Labeled NFS aware ([RFC7204]), then the client MUST locally enforce the MAC security policies. The uncacheable dirent metadata attribute allows dirents to be annotated such that attributes are presented to the user based on the server's access control decisions. 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, . [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, . [RFC7204] Haynes, T., "Requirements for Labeled NFS", RFC 7204, DOI 10.17487/RFC7204, April 2014, . Haynes Expires 24 July 2026 [Page 7] Internet-Draft Uncacheable Dirents January 2026 [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, . [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 [MS-ABE] Microsoft, "Access-Based Enumeration (ABE) Concepts", May 2009, . [MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Protocol Versions 2 and 3", Microsoft MS-SMB2, n.d., . [POSIX.1] IEEE, "The Open Group Base Specifications Issue 7", IEEE Std 1003.1, 2013 Edition , 2013. [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS Version 3 Protocol Specification", RFC 1813, DOI 10.17487/RFC1813, June 1995, . [Samba] Samba Team, "Samba Project", n.d., . Haynes Expires 24 July 2026 [Page 8] Internet-Draft Uncacheable Dirents January 2026 Acknowledgments Trond Myklebust, Mike Snitzer, Jon Flynn, Keith Mannthey, and Thomas Haynes all worked on the prototype at Hammerspace. Rick Macklem, Chuck Lever, and Dave Noveck reviewed the document. Chris Inacio, Brian Pawlowski, and Gorry Fairhurst helped guide this process. Author's Address Thomas Haynes Hammerspace Email: loghyr@gmail.com Haynes Expires 24 July 2026 [Page 9]