]> Hammerspace

loghyr@gmail.com

General Network File System Version 4 Internet-Draft Network File System version 4.2 (NFSv4.2) clients may cache directory-entry (dirent) metadata returned by READDIR to improve performance. Such caching typically assumes that directory-entry metadata and visibility are identical for all users of a client. In some deployments, however, directory-entry metadata or visibility observed by a client may vary over time or across clients due to server policy or other factors. Reuse of cached directory-entry metadata across users can therefore result in clients presenting directory contents or attributes that do not reflect the current state of the server. This document introduces an uncacheable dirent metadata attribute for NFSv4.2 that allows servers to advise clients that directory-entry metadata returned by READDIR and related operations should not be reused across users. Note to Readers Discussion of this draft takes place on the NFSv4 working group mailing list (nfsv4@ietf.org), which is archived at . Source code and issues list for this draft can be found at . Working Group information can be found at .

Introduction Clients of remote filesystems may cache directory-entries 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. This document does not define the conditions under which directory-entry metadata or visibility may vary. It specifies the client behavior necessary to maintain correctness when such variation is observed. 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 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. This document does not define server-side directory filtering or Access Based Enumeration (ABE) semantics. It only provides a mechanism by which a server may advise clients that directory-entry metadata returned by READDIR should not be reused across users. Access Based Enumeration (ABE), as implemented in the Server Message Block (SMB) and deployed in implementations such as Samba , is one example of an environment in which directory visibility may differ across requests. This document does not define such mechanisms, but addresses client-side caching behavior when such variation is observed. 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 can lead to applications observing inconsistent metadata and data views even when file data caching is disabled. This cooperation works because both the client and server typically interpret file permissions using POSIX-like () semantics based on mode bits, uid, and gid in NFSv3 . For NFSv4.2, these would respectively be the mode, owner, and owner_group attributes defined in . 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 directory entry cache to have checks done when a new user attempts to access the directory entry. 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, which can be used to control the visibility of directory entries. 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 metadata visibility is best performed on the server. Since cached directory entries 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 document introduces the uncacheable dirent metadata attribute to NFSv4.2 to allow servers to advise clients that caching of directory-entry metadata is unsuitable. Using the process detailed in , the revisions in this document become an extension of NFSv4.2 . They are built on top of the external data representation (XDR) generated from .

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

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 when, and only when, they appear in all capitals, as shown here.

Caching of Directory-Entry Metadata The fattr4_uncacheable_dirent_metadata attribute is a read-write boolean attribute that applies to directory objects and has a data type of boolean. The attribute is not set on individual file objects and applies only to directory-entry metadata returned from the directory on which it is set. The uncacheable dirent metadata attribute enables correct presentation of directory-entry visibility and attributes in environments where such information is not uniformly cacheable. As such, it is an OPTIONAL attribute to implement for NFSv4.2. If both the client and the server support this attribute, the client MUST NOT reuse directory-entry metadata returned by READDIR or related operations for different users when the attribute is set on the directory. This document specifies the required observable behavior rather than mandating a particular internal implementation strategy. Clients MAY employ more sophisticated mechanisms, such as per-user directory entry caching, provided that the externally visible behavior is equivalent to not caching directory-entry metadata across users. 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. The uncacheable dirent metadata attribute governs caching behavior of directory-entry metadata returned by READDIR and related operations, not the directory object itself. The uncacheable dirent metadata attribute addresses a different aspect of client-side caching than fattr4_uncacheable_file_data (). The file data attribute governs caching of file contents, while the dirent metadata attribute governs caching of directory-entry metadata returned by READDIR and related operations. The attributes are independent and may be used separately. 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. Directory delegations do not address per-user directory-entry metadata visibility and therefore cannot replace the semantics defined by the uncacheable dirent metadata attribute. Clients MUST NOT assume that directory-entry metadata is globally valid across different access contexts.

Uncacheable Directory-Entry Metadata The fattr4_uncacheable_file_data attribute is a read-write boolean attribute that applies on a per-file basis to regular files (NF4REG). Authorization to query or modify this attribute is governed by existing NFSv4.2 authorization mechanisms. If a directory object 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, ensuring that the returned metadata reflects the current state and visibility as determined by the server. Clients MUST NOT reuse directory-entry metadata retrieved on behalf of one user to satisfy requests made on behalf of another user. The uncacheable dirent metadata attribute does not modify the semantics of the NFSv4.2 change attribute. Clients MUST continue to use the change attribute to detect directory modifications and to determine when directory contents may have changed, even when directory-entry metadata caching is suppressed. Suppressing caching of directory-entry metadata does not remove the need for change-based validation. Servers SHOULD assume that clients which do not query or set this attribute may cache directory-entry metadata, and therefore SHOULD NOT rely on this attribute for correctness unless client support is confirmed. Authorization to set or modify this attribute is governed by existing NFSv4.2 authorization mechanisms. If a client holds a directory delegation for a directory that becomes marked with the uncacheable dirent metadata attribute, the server is expected to ensure that the client observes the updated attribute value. A server MAY recall an existing directory delegation in order to enforce the semantics of this attribute. Clients that observe the attribute set while holding a directory delegation MUST ensure that directory-entry metadata is not cached inconsistently with the attribute semantics. Because this attribute provides advisory guidance rather than mandatory access control, servers cannot rely on client compliance for security enforcement in adversarial environments.

Example: Directory Enumeration With and Without Dirent Metadata Caching This example illustrates the difference in client-visible behavior when directory-entry metadata caching is enabled versus when the uncacheable dirent metadata attribute is set on a directory.

Classic Directory Enumeration (Directory-Entry Metadata Cached) In this scenario, the client caches directory-entry metadata obtained from the server and reuses it for subsequent users.

Directory-Entry Metadata Cached ------------------------> | entries: {a,b,c} |<--------------------<------------------------ | (entries cached in client) User B Process ------------- readdir("/dir") | | (no network traffic) | entries returned from | client cache: {a,b,c} ]]>

In this case, shows directory-entry metadata retrieved on behalf of User A is reused to satisfy a directory read for User B. This behavior is typical of legacy NFSv4.2 clients and maximizes performance, but it can result in incorrect or unauthorized directory views in multi-user or multi-protocol environments.

Directory Enumeration With Uncacheable Dirent Metadata In this scenario, the directory has the uncacheable dirent metadata attribute set. The client does not retain directory-entry metadata across directory reads for different users.

Directory-Entry Metadata Not Cached ------------------------> | entries visible to A: | {a,b} |<--------------------<------------------------ | (no directory-entry metadata retained) User B Process ------------- readdir("/dir") | | READDIR |-------------------->------------------------> | entries visible to B: | {b,c} |<--------------------<------------------------ ]]>

In this case, shows each directory read results in a READDIR operation sent to the server for each enumeration request, ensuring that directory-entry metadata reflects the current visibility and attributes appropriate to the requesting user. The client may still cache other information, provided the externally observable behavior is equivalent to not caching directory-entry metadata.

Discussion This example demonstrates that the uncacheable dirent metadata attribute does not mandate a particular client implementation, but it does require that directory-entry metadata retrieved for one user MUST NOT be reused to satisfy directory reads for another user. The attribute ensures correctness and interoperability in environments where directory contents or visibility may differ across users, clients, or protocols.

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 not to reuse directory- entry metadata returned by READDIR across users. In the prototype, directories configured for ABE-like behavior are marked with the fattr4_uncacheable_dirent_metadata attribute. The client implementation suppresses reuse of directory-entry metadata across users and retrieves directory-entry metadata from the server as needed when servicing directory enumeration requests. Clients may employ more sophisticated mechanisms, such as per-user directory-entry caching, provided that the externally observable behavior matches the semantics described in this document. Experience with the prototype indicates that the attribute enables servers to present user-specific directory-entry visibility and attributes while remaining compatible with existing NFSv4.2 semantics.

XDR for Uncacheable Dirents Attribute

Extraction of XDR This document contains the external data representation (XDR) 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: For example, if the script is named 'extract.sh' and this document is named 'spec.txt', execute the following command: 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 ). 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 , the code snippets should be placed in their appropriate sections within the existing XDR.

Security Considerations This attribute is not intended to provide a security boundary or to replace server-enforced access control. Its primary purpose is to improve correctness and interoperability in environments where directory-entry metadata visibility varies across users or protocols. Servers MUST NOT rely on this mechanism alone to prevent unauthorized access to directory entries. Authorization to set or modify the fattr4_uncacheable_dirent_metadata attribute is governed by existing NFSv4.2 authorization mechanisms. Servers MAY restrict modification of this attribute based on local policy, file ownership, or access control rules. This document does not define a new authorization model. The discussion of users in this section is independent of the specific user identity representation employed by the client or server. This document does not distinguish between users identified via NFSv4.2 user@domain strings, RPC authentication identities, or local operating system user identifiers. The uncacheable dirent metadata attribute does not alter NFSv4.2 authentication or authorization semantics and does not depend on any particular user identity model. A client MUST NOT make access or visibility decisions for one user based on directory-entry metadata retrieved on behalf of another user. These decisions MUST be made by the server. If the client is Labeled NFS aware (), then the client MUST locally enforce the MAC security policies. The concerns described above primarily apply to multi-user clients that cache directory-entry metadata on behalf of multiple users. Single-user clients may not be subject to these risks, but the attribute semantics remain the same regardless of client usage model. The uncacheable dirent metadata attribute allows servers to indicate that directory-entry metadata should not be assumed to be uniformly cacheable across observations.

IANA Considerations This document has no IANA actions.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document describes the External Data Representation Standard (XDR) protocol as it is currently deployed and accepted. This document obsoletes RFC 1832. [STANDARDS-TRACK] This memo outlines high-level requirements for the integration of flexible Mandatory Access Control (MAC) functionality into the Network File System (NFS) version 4.2 (NFSv4.2). It describes the level of protections that should be provided over protocol components and the basic structure of the proposed system. The intent here is not to present the protocol changes but to describe the environment in which they reside. This document describes NFS version 4 minor version 2; it describes the protocol extensions made from NFS version 4 minor version 1. Major extensions introduced in NFS version 4 minor version 2 include the following: Server-Side Copy, Application Input/Output (I/O) Advise, Space Reservations, Sparse Files, Application Data Blocks, and Labeled NFS. This document provides the External Data Representation (XDR) description for NFS version 4 minor version 2. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document describes the rules relating to the extension of the NFSv4 family of protocols. It covers the creation of minor versions, the addition of optional features to existing minor versions, and the correction of flaws in features already published as Proposed Standards. The rules relating to the construction of minor versions and the interaction of minor version implementations that appear in this document supersede the minor versioning rules in RFC 5661 and other RFCs defining minor versions. This document describes the Network File System (NFS) version 4 minor version 1, including features retained from the base protocol (NFS version 4 minor version 0, which is specified in RFC 7530) and protocol extensions made subsequently. The later minor version has no dependencies on NFS version 4 minor version 0, and is considered a separate protocol. This document obsoletes RFC 5661. It substantially revises the treatment of features relating to multi-server namespace, superseding the description of those features appearing in RFC 5661. Hammerspace Network File System version 4.2 (NFSv4.2) clients commonly perform client-side caching of file data in order to improve performance. On some systems, applications may influence client data caching behavior, but there is no standardized mechanism for a server or administrator to indicate that particular file data should not be cached by clients for reasons of performance or correctness. This document introduces a new file data caching attribute for NFSv4.2. Files marked with this attribute are intended to be accessed with client-side caching of file data suppressed, in order to support workloads that require predictable data visibility. This document extends NFSv4.2 (see RFC7862). Informative References This Glossary provides definitions, abbreviations, and explanations of terminology for information system security. The 334 pages of entries offer recommendations to improve the comprehensibility of written material that is generated in the Internet Standards Process (RFC 2026). The recommendations follow the principles that such writing should (a) use the same term or definition whenever the same concept is mentioned; (b) use terms in their plainest, dictionary sense; (c) use terms that are already well-established in open publications; and (d) avoid terms that either favor a particular vendor or favor a particular technology or mechanism over other, competing techniques that already exist or could be developed. This memo provides information for the Internet community. The Network File System v4 (NFSv4) allows a client to both open a file and be granted a delegation of that file. This delegation provides the client the right to authoritatively cache metadata on the file locally. This document presents several extensions for both opening the file and delegating it to the client. This document extends NFSv4.2 (see RFC 7863). Microsoft Microsoft Corporation n.d. IEEE This paper describes the NFS version 3 protocol. This paper is provided so that people can write compatible implementations. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. Samba Team n.d.

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.