Adding an Uncacheable Attribute to NFSv4.2
Internet-Draft draft-haynes-nfsv4-uncacheable-01
Thomas Haynes
Hammerspace
loghyr@gmail.com
13 October 2024
Transport
Network File System Version 4
NFSv4
The Network File System v4.2 (NFSv4.2) allows a client to cache both the metadata and the data for a file object. It can also cache the metadata for a directory object. Caching the dirents (i.e., the metadata) allows the client to avoid querying the server to refresh information. But this defeats the server checking to see if the user has permission to view the dirent's attributes. Caching the data can cause performance impacts if the page cache hit rate is low.. This document introduces a new file attribute called uncacheable which indicates that the client MUST NOT cache the metadata or data for that dirent. This document extends NFSv4.2 (see RFC7863).
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/browse/nfsv4/. Working Group information can be found at https://datatracker.ietf.org/wg/nfsv4/about/.
Introduction
In the Network File System version 4.2 (NFSv4.2) (see [RFC7863]) , a client queries for either a file's or directory's attributes via either GETATTR (see Section 18.7 of [RFC8881]) or READDIR (see Section 18.23 of [RFC8881]) to the server. These directory entries (dirents) can be cached locally by the client.
As these cached dirents are shared by all users on the clients and the client can not determine access to these dirents, all users are presented with the same set of attributes. We introduce the new uncacheable attribute, which informs the client not to cache a dirent for that file or directory object. As such each time the client queries for those attributes, the response can be tailored to that user. That decision can be based on either Access Control List (ACL) on a file or directory object (see Section 6 of [RFC8881]) or proprietary policies.
Besides the caching of metadata for both files and directories, the client can also cache data for files. The uncacheable attribute also informs the client to avoid its page cache. It is very similar to passing the O_DIRECT to the open call. This can be useful for files that are not shared and also for ones which do not meet the expectations of the caching patterns of the page cache.
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].
Definitions
Access Based Enumeration:
When servicing either a READDIR or a GETATTR, base the result on the access permitted to the user making the request.
dirent:
A directory entry, describing either a directory or a file.
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.
Uncacheable Dirents
If a file object or directory has the uncacheable attribute set, then the client MUST NOT cache their dirent attributes. I.e., just because it presented the attributes to user A on the first request, then on a subsequent request, it MUST query for those attributes again. Also, the client MUST NOT share attributes between different users.
Uncacheable Files
If a file object is marked as uncacheable, that also means all modifications to the file MUST immediately be sent from the client to the server. I.e., the data is also not cacheable.
XDR for Offline Attribute

///
/// typedef bool            fattr4_uncacheable;
///
/// const FATTR4_UNCACHEABLE            = 87;
///

Extraction of XDR
This document contains the external data representation (XDR) [RFC4506] description of the uncacheable attribute. 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 flags:

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

The effect of the script is to remove leading white 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, 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 various code snippets belong in their respective areas of that XDR.
Security Considerations
Clients MUST NOT make access decisions to uncacheable dirents, these decisions MUST be made by the server. With the uncacheable attribute, dirents can be annotated such that attributes can be presented to the user based on the server's decision.
IANA Considerations
There are no IANA considerations.
References
Normative References
[RFC7863]
[RFC8881]
[RFC8178]
[RFC7862]
[RFC4506]
[RFC2119]
[RFC8174]
Acknowledgments
Trond Myklebust and Thomas Haynes all worked on the prototype at Hammerspace.