Summary

  • Revision 11 of the NFSv4 uncacheable-dirent-metadata draft replaces a vague instruction about cache retrieval with a testable rule: a new directory enumeration cannot reuse another enumeration’s READDIR result, and an entry cannot be reported with metadata older than the latest READDIR that returned it.
  • The guarantee is narrow. It is scoped to one directory path, one returned entry and one observation at the server; it does not erase caches, make every value permanently current or override a write-delegation holder whose value is newer than the server’s.
  • Operators gain a correctness control for busy HPC and ingest directories, but they must pay and measure the recurring READDIR cost, restrict who can toggle the attribute and treat client honoring as an observed behavior rather than an asserted capability.

Revision 11 writes a rule a test can observe

draft-ietf-nfsv4-uncacheable-directories-11 was uploaded on 5 September 2026. It is an active NFSv4 Working Group document on the standards track, with reported Hammerspace server and Linux client prototypes. It remains an Internet-Draft, not an RFC, an IETF approval or evidence that deployed clients already behave this way.

The important change from revision 10 is not a new attribute number. It is a more honest statement of what the attribute can control. Revision 10 said an honoring client had to retrieve directory-entry metadata from the server “on each READDIR”. Every protocol READDIR already reaches a server, so the sentence did not say what an application was allowed to observe. A client could issue a new READDIR, retain the returned names and still serve an older size from its ordinary inode-attribute cache.

Revision 11 moves the requirement to the visible boundary. If fattr4_uncacheable_dirent_metadata is set on a directory, an honoring client must not satisfy a new application-level pass from READDIR results obtained during a different pass. For an entry returned in the new pass, it must not report an attribute value received before the READDIR that most recently returned that entry, whatever operation originally populated the value.

That wording can be tested without demanding an x-ray of the client. Create a marked directory, enumerate it, change a child from another client, enumerate again and then inspect the child. The prohibited result is the value that predates the READDIR of the second pass. Whether the implementation discarded, overwrote, versioned or retained its old cache entries is irrelevant if it does not expose the forbidden answer.

The directory clock does not time the child

NFS has two neighboring forms of state that are easy to merge in an operator’s head. A directory entry is the name and fileid pairing that locates a child. Its validity follows the directory’s change attribute: create, remove or rename an entry and the directory changes. The size and timestamps returned alongside that entry belong to the child file. Another client can extend the file without changing its name, fileid or parent directory.

That separation explains the failure. The client may hold a perfectly valid snapshot of the names while the accompanying size and time_modify describe an earlier file state. RFC 8881 permits attribute caching with a bounded lifetime, but a busy high-performance-computing output directory or ingest landing zone can receive writes faster than any useful positive lifetime. Revalidating every child separately would cost one GETATTR per entry—the traffic that requesting attributes inside READDIR was intended to avoid.

This is not cosmetic staleness. An incremental backup or directory-tree synchronization pass can decide that a file has not changed and silently omit new data. The new attribute lets the server identify the particular directories where that risk justifies a fresh server observation on each enumeration. It does not claim that all caching elsewhere became safe.

One pass is the unit of freshness

Revision 11 defines its units because capitalization was hiding an interoperability problem. Lower-case readdir means an application’s directory-read request. Upper-case READDIR is an NFSv4.2 wire operation. An enumeration is one pass over the directory, often composed of many application readdirs and several continuation READDIRs. One READDIR response ordinarily feeds many application calls.

The draft therefore does not require one network request for every entry. It requires a new pass to be grounded in READDIRs from that pass. The client should ask for the attributes it expects to report in each READDIR’s attr_request. It may fetch them later, but doing so one child at a time recreates the GETATTR storm the mechanism is meant to avoid.

Metadata returned during a pass may remain cached when the pass ends. Between passes, the ordinary attribute-cache rules still govern it. The next enumeration is the boundary that makes a pre-existing value ineligible for an entry newly returned by READDIR. “Uncacheable” is therefore an unfortunate shorthand for a reporting invariant, not a command to keep no state.

The activation time is equally bounded. If a server changes the attribute from false to true, a client that has cached the directory attributes need not know instantly. It can continue its prior behavior until that cache expires or ordinary revalidation sees the directory change attribute move. A server-side timestamp saying “enabled” and a client-side timestamp saying “observed” are different facts.

The server may not hold the newest value

The phrase “go to the server” still cannot mean “replace all knowledge with the server’s copy”. A client holding an OPEN_DELEGATE_WRITE delegation may have a file’s newest size or change while the server’s local copy lags. RFC 8881 permits the server to obtain those authoritative attributes from the delegated client with CB_GETATTR.

Revision 11 now makes the exception explicit. The rule is directed at a value older than the server would return; it does not require a write-delegation holder to replace its newer value with an older server value. Freshness is an authority relation, not merely a trip across the network.

The distinction also prevents a larger false promise. A value returned by READDIR reflects what the server could report at that observation. Another writer may change the file immediately afterward. The attribute gives the application a newer, attributable boundary than cross-pass cache reuse; it does not freeze the world or create a distributed snapshot of file contents and metadata.

The signal belongs to a path, not an inode

The attribute is attached to a directory and governs answers for entries enumerated through that directory. It makes no claim about the underlying object. If one file is hard-linked into a marked directory and an unmarked directory, traversal through the unmarked path is unaffected. Protocol text that described the object itself as uncacheable would overstate the authority of one parent directory.

This path scope also matters for inheritance. The draft defines no automatic propagation to new subdirectories. A server may implement local inheritance policy, but that is a deployment statement, not an NFSv4.2 invariant. Operators need to inventory effective markings rather than infer a whole tree from its root.

Type behavior was repaired as well. Attribute support is advertised per filesystem, so a supporting server owes a GETATTR value even for a non-directory; revision 11 requires FALSE there. A SETATTR on the wrong object type returns NFS4ERR_WRONG_TYPE. Those responses distinguish “the filesystem knows this attribute” from “this object is a directory to which it can meaningfully apply”.

Awareness is not compliance

The attribute is advisory. A client can request it with GETATTR or try to modify it with SETATTR and still decline to enforce the reporting rule. The server has no protocol receipt proving that the client honored the answer. Querying a field proves awareness of its name, not obedience to its meaning.

That is why the draft says a server should not rely on the attribute for correctness. Mixed fleets may include honoring, unaware and aware-but-non-honoring clients. A directory-wide policy can be uniform at the server and non-uniform at the application surface.

Directory delegations add a concrete conflict. A delegation lets a client serve directory state without returning to the server, while the new attribute requires a fresh server path for each pass. When the attribute is set, the server must recall any outstanding directory delegation and must not grant a new one until the attribute is cleared. Child-attribute notification is not assumed to rescue the design: it is optional, may be unsupported and can scale with clients multiplied by changes.

The cost of a better answer

The control deliberately spends cache efficiency. Every new enumeration of a marked directory generates server work, and a names-only READDIR followed by individual GETATTRs spends even more. On a directory touched by thousands of writers and readers, the correctness benefit and the load externality can both be large.

Authorization to set the attribute is therefore part of the mechanism. If an unprivileged user can toggle it on a hot tree, one metadata write can force every honoring client onto the expensive path. The draft leaves restrictions to local administration, export policy, ownership and existing access controls. It neither supplies a new security model nor changes Labeled NFS obligations.

Heng Lu’s reality-layer discipline is useful here because the nouns tempt overclaiming. The server’s attribute is a policy statement. The client’s cache is private operational state. The READDIR response is a server observation. The later stat result is the application-visible claim. A sound deployment preserves those layers and tests the transitions between them instead of treating “uncacheable=true” as proof that stale answers disappeared.

Scope limits

The public record establishes the draft text, its revision history, the referenced NFS rules, public commit rationale and contributor-reported prototype status. It establishes no released Linux version, Hammerspace production behavior, adoption rate, benchmark, incident, exploit or measured correctness gain. The separate uncacheable-file-data draft governs file contents and write durability; it does not enlarge this metadata rule.

The durable finding is narrower: the specification became more credible when it stopped claiming authority over an invisible cache and named the answer an implementation must not give.

Sources