Adding an Uncacheable Dirent Metadata Attribute to NFSv4.2

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 30 March 2027.¶

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

Clients of remote filesystems may cache the file attributes returned by READDIR alongside each directory entry, to reduce the volume of follow-on GETATTR traffic for entries the client has already seen. This caching is inherently best-effort -- writes to the underlying files can change those attributes at any time, and the directory's change attribute does not track such writes. In some deployments the cost of that staleness is high enough to be a problem; the conditions are described in Section 2.¶

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 dirent metadata -- the file object attributes, such as size and timestamps, returned alongside each entry -- and to what an honoring client reports of it. It does not prohibit caching of the directory object itself, nor does it affect caching of file data.¶

When this best-effort caching returns stale size and timestamp information for concurrently modified files, it also undermines the effectiveness of uncacheable file data semantics ([I-D.ietf-nfsv4-uncacheable-files]) in the same deployment: applications can observe inconsistent metadata and data views even when file data caching is disabled.¶

This document introduces the uncacheable dirent metadata attribute to NFSv4.2 to allow servers to identify the directories for which an honoring client reports each entry's attributes as the READDIR that returned the entry supplied them, rather than from a value it held earlier. Using the process described in [RFC8178] Section 6, this document extends NFSv4.2 [RFC7862]; as that section provides, it does not update [RFC7862], which remains a valid description of the base variant of the minor version. The revisions are built on top of the external data representation (XDR) [RFC4506] generated from [RFC7863].¶

2. Deployment Motivation

A class of deployment uses NFSv4.2 to serve a shared directory to many concurrent NFSv4.2 client writers, each writing files within the directory. Workloads of this kind are typical of High-Performance Computing (HPC) environments, where a single output directory may receive results from hundreds or thousands of compute nodes simultaneously, and of large-scale data-ingest pipelines where many producers append to a common landing directory. The files within such a directory have their attributes -- size and timestamps in particular, though the attribute of this document covers the whole class defined in Section 3 -- modified at a high rate by clients other than the one performing READDIR.¶

[RFC8881] Section 10.6 permits a client that requested the full set of attributes to be cached in a READDIR to cache what it returned on the same basis as attributes obtained by GETATTR: cached per file, bounded by an upper time boundary, and revalidated against that file's change attribute. In a directory receiving writes from thousands of compute nodes, any nonzero cache lifetime yields stale size and time_modify for most entries most of the time, and revalidating each entry individually costs one GETATTR per entry -- the very traffic that requesting attributes in READDIR exists to avoid. NFSv4.2 gives a server no in-band way to tell a client that the file attributes it holds for the children of a particular directory should be refreshed each time the directory is enumerated; mount options shorten attribute cache lifetimes out of band and per client, not per directory.¶

Nor can a client work out for itself which directories those are. The directory's change attribute is the only per-directory signal it has, and that attribute does not move when a file the directory names is written, so it reads the same for a directory receiving writes from a thousand nodes and for one nobody is touching. Lacking any basis for a per-directory choice, a client is left applying one attribute-cache policy across the whole mount.¶

The staleness has correctness consequences, not merely cosmetic ones. An incremental backup or a directory-tree synchronization pass that decides what to copy from the size and time_modify reported for each entry will silently skip a file whose cached metadata predates a concurrent write, leaving data uncopied. This attribute lets a server mark the directories where that outcome is likely, so that an honoring client fetches current metadata on each enumeration.¶

The fattr4_uncacheable_dirent_metadata attribute is the server's mechanism to identify a directory for which this risk is high enough that client-side caching is not safe. When the server sets the attribute on a directory, an honoring client goes to the server for each enumeration and does not report an entry's attributes from a value it held before that READDIR.¶

3. Definitions

readdir

A directory-read request made by an application, however the client's interface batches entries. Written in lower case throughout this document to distinguish it from READDIR, the NFSv4.2 operation ([RFC8881] Section 18.23).¶

enumeration

One pass over a directory: the readdirs of that pass and the READDIRs the client issues to satisfy them. A READDIR ordinarily supplies enough entries for many readdirs, so a requirement scoped to an enumeration does not imply a READDIR per readdir.¶

dirent

A directory entry -- the (name, fileid) pair that names a file or subdirectory within a directory. This is what a client maintains for an entry, whatever a given READDIR response carries on the wire; it is the pair POSIX exposes as d_name and d_ino. A dirent itself does not include the file attributes returned alongside it.¶

dirent metadata

The file attributes that a READDIR response can return alongside each dirent, whether or not a particular response carried them -- including size, time_modify, time_metadata, time_access, mode, owner, and the file's own change attribute. These attributes belong to the underlying file object, not to the directory; they change when the underlying file is written, which is independent of the directory's change attribute. The term "dirent metadata" in this document is a naming convenience for "the file attributes a READDIR response carries alongside an entry"; it names that class of attributes, not the subset a given response happened to return, and it does not assert that those attributes inherit the directory's cache-coherence semantics.¶

dirent caching

A client-side cache of the dirents themselves -- the (name, fileid) pairs -- used to avoid repeated READDIR traffic. Whether such a cache remains valid is governed by the directory's change attribute: the directory changes when an entry is created, removed, or renamed, and a fileid is stable for as long as its entry names the same object. A fileid is therefore cached with the name rather than with the file attributes: writes to a file change its size and timestamps without touching either the name or the fileid. This document does not change what a client may hold in this cache or how it validates it; for a directory on which the attribute is set, however, each enumeration is satisfied by a READDIR, so for that directory the cache no longer avoids that traffic.¶

dirent metadata caching

A client-side cache of the dirent metadata returned alongside those entries, used to avoid repeated GETATTR traffic. Because those file attributes are not invalidated by the directory's change attribute (only by writes to the underlying files), this caching is inherently best-effort and subject to staleness whenever the underlying files are modified. This is the caching whose results the attribute defined in this document constrains: for a directory on which the attribute is set, Section 5.1 limits what an honoring client may report for an entry, however the client structures the cache the value comes from.¶

uncacheable dirent metadata attribute

An NFSv4.2 file attribute that advises clients not to report dirent metadata, such as size and timestamps, from a value held before the READDIR that most recently returned the entry it describes.¶

revalidation

The procedure of [RFC8881] Section 10.3.1 by which a client determines whether something it holds in a cache is still current: the client fetches the change attribute of the object from the server, compares it with the value it cached, and, if they differ, treats what it cached as invalid. A client validates when it fetches from the server; it revalidates before reusing what it cached. For a cached directory the attribute compared is the directory's own ([RFC8881] Section 10.8.2).¶

honoring client

A client that implements this attribute and enforces the always-refetch behavior it defines for a directory on which the attribute is set. The attribute is advisory: a client that does not implement it, or that declines to enforce it, is non-honoring and may continue to report dirent metadata it held beforehand.¶

This document assumes familiarity with NFSv4.2 operations, attributes, and error handling as defined in [RFC8881] and [RFC7862].¶

4. 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.¶

5. Caching of Dirent Metadata

The uncacheable dirent metadata attribute constrains what an honoring client may report for the entries of a particular directory. If both the client and the server support this attribute, and the attribute is set on a directory, an honoring client goes to the server for each enumeration and does not report an entry's attributes from a value it held before that READDIR. Section 5.1 states the requirement normatively.¶

That requirement has two halves. Each enumeration of such a directory is satisfied by a READDIR rather than from the results of an earlier one, and what the client reports for an entry that READDIR returned is what that READDIR supplied, rather than a value held beforehand. The first half is the one that changes what a client may do today: [RFC8881] Section 10.8.2 lets a client answer an application readdir from a cached snapshot validated by the directory's change attribute, with no READDIR on the wire at all, and that change attribute does not move when a file the directory names is written. The second half alone would not close the gap, since a client could satisfy it by sending a READDIR with a minimal attr_request and reporting the entries' attributes from what it already held.¶

It adds no constraint on the objects the entries name: an honoring client may continue to hold the dirents themselves, validated by the directory's change attribute as it would be for any other directory. Clients typically hold a single cache of a file object's attributes, populated by whichever operation last returned them; the requirement is on what the client reports, not on how it structures that cache.¶

A server sets it on the directories where it knows the staleness of cached READDIR attributes is particularly likely and particularly damaging. It is a RECOMMENDED attribute for NFSv4.2, in the attribute-category sense of [RFC8881] Section 5.2 and [RFC7862] Section 12 rather than the BCP 14 sense; a server is not required to support it.¶

Because the attribute governs what an honoring client reports for the entries of one directory, rather than the objects those entries name, it makes no claim about those objects. A file reached through a directory on which the attribute is not set is unaffected, including where the same file is linked into both a directory on which it is set and one on which it is not.¶

This document specifies the required observable behavior rather than mandating a particular internal implementation strategy. Clients MAY employ more sophisticated mechanisms, such as time-limited caches that revalidate against the server on each READDIR, provided that the externally visible behavior satisfies Section 5.1.¶

A client can determine whether the uncacheable dirent metadata attribute is supported for a given directory by examining the supported_attrs attribute for that directory's filesystem or by probing support using the procedures described in [RFC8178].¶

A change to the attribute while a directory is in use may not be reflected in client behavior immediately. A client that has cached the directory's attributes MAY continue to behave as it did before the change and is not required to act on a value it has not yet observed. Two ordinary mechanisms bound that delay: the client's cached attributes for the directory expire under the upper time boundary described in [RFC8881] Section 10.6, and a client revalidating a cached directory inspects the directory's change attribute ([RFC8881] Section 10.8.2), and that attribute changes whenever the object it describes is modified ([RFC8881] Section 5.8.1.4), including by a SETATTR of this one. Clients are expected to observe the change through those mechanisms and to apply the rule in Section 5.1 to subsequent enumerations.¶

The uncacheable dirent metadata attribute governs what an honoring client may report for a directory's entries. It does NOT govern:¶

• How long a value remains reportable between enumerations. Attributes a client obtains for an individual entry at other times, by a direct GETATTR following a LOOKUP for example, remain governed between enumerations by the attribute-cache mechanisms already defined by NFSv4.2 and are subject to the same staleness from concurrent writes. The rule in Section 5.1 applies at each enumeration and is indifferent to which operation last supplied a value.¶

• The directory's own attribute cache. The directory object's own attributes (mode, owner, etc.) can be cached normally and revalidated via the directory's change attribute as usual.¶

• Operations that do not return file attributes in their response (for example, LOOKUP without a following GETATTR, ACCESS). These are unaffected.¶

The uncacheable dirent metadata attribute addresses a different aspect of client-side caching than fattr4_uncacheable_file_data ([I-D.ietf-nfsv4-uncacheable-files]). The file data attribute governs caching of file contents, while the dirent metadata attribute governs what a client reports for the entries of a directory it enumerates. The attributes are independent and may be used separately.¶

This attribute follows the same pattern as fattr4_uncacheable_file_data ([I-D.ietf-nfsv4-uncacheable-files]) applied at the file-data layer. In both cases:¶

• The underlying NFSv4.2 protocol permits client-side caching that can become stale.¶

• Client caching of the relevant data is widely implemented in practice and reduces network traffic for stable objects.¶

• For specific objects where the deployment knows the caching will produce incorrect results, the server requires a mechanism to instruct an honoring client not to rely on it for those specific objects.¶

• The attribute does not redefine the legality of caching in the general case. It is a per-object server-side signal that the caching is known to be unsuitable for that object.¶

The attribute does NOT make dirent metadata caching reliable for directories where it is not set. Clients MUST NOT interpret the absence of fattr4_uncacheable_dirent_metadata, or its value being false, as a guarantee that cached READDIR attributes are authoritative. As stated in [RFC8881] Section 10.6, all client-cached attributes are subject to staleness; the attribute defined in this document only identifies directories for which staleness is particularly likely and particularly damaging. The base specification separates the two concerns this attribute is often accused of conflating: [RFC8881] Section 10.8.2 governs caching of the directory entries themselves, while Section 10.6 governs caching of the file attributes that arrive alongside them. This attribute leaves what a client may hold under either unchanged; it requires a READDIR for each enumeration and constrains what may be reported for an entry, as Section 5.1 states.¶

This attribute does not define behavior for positive or negative name caching, nor for LOOKUP results other than the file attributes it constrains an honoring client from reporting for an entry.¶

A directory delegation ([RFC8881] Section 10.9) lets a client cache a directory's entries and the directory's own attributes until the server recalls the delegation. It is not recalled when the attributes of an entry within the directory change ([RFC8881] Sections 10.9.2 and 10.9.4), so a directory delegation does not, by itself, keep the file attributes returned by READDIR fresh. NOTIFY4_CHANGE_CHILD_ATTRS, requested through GET_DIR_DELEGATION, can deliver changed child attributes to a delegated client, but it is not a substitute for this attribute in the deployments of Section 2: GET_DIR_DELEGATION is OPTIONAL and is not implemented by the clients and servers those deployments use; notification cost scales with the number of delegated clients times the number of changes, which a directory written by thousands of clients makes prohibitive (and [RFC8881] Section 10.9.4 permits a server that finds a directory is causing too many notifications to decline to delegate it); and the dirent_notif_delay attribute lets a server bound or refuse child-attribute notification, so a client cannot rely on notification for freshness.¶

6. Example: Directory Enumeration With and Without Dirent Metadata Caching

This example illustrates the difference in client-visible behavior when dirent metadata caching is enabled versus when the uncacheable dirent metadata attribute is set on a directory. In both scenarios each readdir("/dir") is a separate enumeration -- the application opens the directory, reads it to end-of-file and closes it, and opens it again for the second. The set of entries does not change between the two; an attribute value of one entry is updated at the server between them. The difference is whether the stat after the second readdir observes the updated value.¶

Application             NFSv4.2 Client        NFSv4.2 Server
-----------             --------------        --------------
readdir("/dir")
   |
   |                     READDIR, size and
   |                     time_modify requested
   |-------------------->------------------------>
   |                     entries:
   |                       a (size=100)
   |                       b (size=200)
   |<--------------------<------------------------
   |<-- names a, b
                        (attributes retained per
                         entry, bounded by the
                         attribute cache lifetime)

                                        (concurrent writer extends
                                         a from size=100 to
                                         size=500)

readdir("/dir")
   |                     (served from the cached
   |                      READDIR result; no
   |                      network traffic)
   |<-- names a, b

stat("/dir/a")
   |                     (served from the retained
   |                      READDIR attributes)
   |<-- size=100

Application             NFSv4.2 Client        NFSv4.2 Server
-----------             --------------        --------------
readdir("/dir")
   |
   |                     READDIR, size and
   |                     time_modify requested
   |-------------------->------------------------>
   |                     entries:
   |                       a (size=100)
   |                       b (size=200)
   |<--------------------<------------------------
   |<-- names a, b

                                        (concurrent writer extends
                                         a from size=100 to
                                         size=500)

readdir("/dir")
   |
   |                     READDIR, size and
   |                     time_modify requested
   |                     (cached result not used)
   |-------------------->------------------------>
   |                     entries:
   |                       a (size=500)
   |                       b (size=200)
   |<--------------------<------------------------
   |<-- names a, b

stat("/dir/a")
   |<-- size=500

7. Implementation Status

Note to RFC Editor: please remove this section prior to publication.¶

There is a prototype Hammerspace server which implements the uncacheable dirent metadata attribute and a prototype Linux client which treats the attribute as an indication to satisfy each enumeration of such a directory with a READDIR that requests the entries' attributes, rather than from its readdir cache.¶

In the prototype, directories whose contents change at the server at a rate exceeding typical client cache lifetimes are marked with the fattr4_uncacheable_dirent_metadata attribute.¶

The Linux client decodes the attribute in fs/nfs/nfs4xdr.c into a per-inode flag (nfsi->uncacheable_dirent_metadata, declared in include/linux/nfs_fs.h). The readdir path in fs/nfs/dir.c consults this flag to skip the readdir cache and refetch from the server on each readdir call that is not already at end of directory. It also forces the client onto its attribute-returning READDIR path for such a directory, where the server has been found capable of it: a READDIR that returns only names would refresh the entries but leave their attributes to the client's attribute caches, and the cache-bypassing path above never accrues the cache usage that would otherwise select that path for the continuation READDIRs of a large directory. Clients may employ more sophisticated mechanisms, such as time-limited caches that revalidate against the server on each READDIR, provided that the externally observable behavior satisfies Section 5.1.¶

The Linux client implementation encodes this attribute as a flag distinct from the companion file-data attribute defined in [I-D.ietf-nfsv4-uncacheable-files]; the two attributes are separated as the two documents specify. That implementation is posted to linux-nfs (patches 4-6 of https://lore.kernel.org/linux-nfs/cover.1785140181.git.snitzer@kernel.org/).¶

Experience with the prototype indicates that the attribute enables servers to identify directories whose contents change faster than typical NFSv4.2 client cache lifetimes can track, while remaining compatible with existing NFSv4.2 semantics.¶

8. XDR for the Uncacheable Dirent Metadata Attribute

///
/// typedef bool            fattr4_uncacheable_dirent_metadata;
///
/// const FATTR4_UNCACHEABLE_DIRENT_METADATA   = 88;
///

9. 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, which relies on the sh, grep, and sed utilities as specified by [POSIX]:¶

#!/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.¶

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.¶

10. Security Considerations

This attribute is not a security mechanism. It addresses correctness of client-side caching when client-cached dirent metadata can become stale relative to the current state of the directory at the server. It does not change NFSv4.2 authentication or authorization semantics, and it does not impose access controls on the entries it describes.¶

Authorization to set or modify the fattr4_uncacheable_dirent_metadata attribute is governed by existing NFSv4.2 authorization mechanisms. Section 5.1 states what a server returns for a request its policy refuses. This document does not define a new authorization model.¶

Because the attribute is visible to and affects the caching behavior of all honoring clients, servers should consider the implications of allowing unprivileged users to set or clear it. Setting the attribute on a directory forces honoring clients to abandon READDIR caching and refetch dirent metadata on every enumeration, which can increase load on the server and on other clients.¶

This attribute does not change the semantics of sec_label or the enforcement of MAC security policies. A client's obligations under Labeled NFS (see [RFC7204] for background, and [RFC7862] Section 9 for the NFSv4.2 mechanism) are the same whether dirent metadata is refetched or served from a cache.¶

11. IANA Considerations

This document has no IANA actions.¶

NFSv4.2 attribute numbers are assigned by working group coordination rather than through an IANA registry. This document uses attribute number 88, chosen alongside attribute number 87 in [I-D.ietf-nfsv4-uncacheable-files].¶

12. References

Acknowledgments

Trond Myklebust, Mike Snitzer, Jon Flynn, Keith Mannthey, and Thomas Haynes all worked on the prototype at Hammerspace.¶

Rick Macklem, Chuck Lever, Dave Noveck, Sorin Faibish, Christoph Hellwig, Jeff Layton, and Jamie Koehl reviewed the document.¶

Chris Inacio, Brian Pawlowski, Chuck Lever, Zahed Sarker, and Gorry Fairhurst helped guide this process.¶

Author's Address