| Internet-Draft | Directory Delegation clarification for N | June 2024 |
| Macklem & Layton | Expires 10 December 2024 | [Page] |
This document describes the addition of bit flags to be used in the request by a client for the GET_DIR_DELEGATION operation to allow the client to specify detailed behavior of CB_NOTIFYs the server will perform on the client. Early implementation experience with directory delegations has demonstrated that clients may not need the full information specified in [RFC8881] for CB_NOTIFYs and may not require the recall of the directory delegation to be done synchronously. Limiting the CB_NOTIFY's requirements can simplify server implementation of directory delegations. These additional bit flags allow the client to request desired behavior. The server's reply will then specify what behavior the client can expect.¶
This note is to be removed before publishing as an RFC.¶
Discussion of this draft occurs on the NFSv4 working group mailing list, archived at https://mailarchive.ietf.org/arch/browse/nfsv4/. Working Group information is available at https://datatracker.ietf.org/wg/nfsv4/about/.¶
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 10 December 2024.¶
Copyright (c) 2024 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.¶
Implementation experience with directory delegations in NFSv4.2 has identified a need for a client to request specific information be provided in the CB_NOTIFYs performed by the server when a directory delegation has been issued to a client. It has also been discovered that certain aspects of CB_NOTIFYs are underspecified. This document specifies the addition of bit flags to be used in the gdda_notification_types request argument and gddr_notification reply argument of the GET_DIR_DELEGATION operation to allow negotiation of specific information to be provided in the CB_NOTIFYs. Note that these bit flags are used in addition to the bits defined in Section 20.4.1 of [RFC8881] for the notification types and not in place of them. A client will also set bit(s) in gdda_notification_types for the types of notifications requested, if the client is requesting notifications.¶
The CB_NOTIFY_WANT_VALID bit is used to indicate to the server that this extended behavior is being requested and the server acknowledges that it supports this extended behavior by setting CB_NOTIFY_WANT_VALID in the gddr_notification field in the GET_DIR_DELEGATION reply. It also implies that the specification of behavior for CB_NOTIFYs in this document are expected by the client.¶
A server should reply with as large a subset of the bits set in gdda_notification_types in gddr_notification as is possible. The client will decide if the set of bit flags set in the gddr_notification field of the GET_DIR_DELEGATION reply provides behavior that is useful for the client. If the directory delegation is deemed not useful, the client SHOULD DELEGRETURN the directory delegation.¶
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.¶
This document presents an extension to minor version 2 of the NFSv4 protocol as described in [RFC8178]. It describes new OPTIONAL features. NFSv4.2 servers and clients implemented without knowledge of this extension will continue to interoperate with clients and servers that are aware of the extension (whether or not they support it).¶
Note that [RFC7862] does not define NFSv4.2 as non-extensible, so [RFC8178] treats it as an extensible minor version. This Standards Track RFC extends NFSv4.2 but does not update [RFC7862] or [RFC8178].¶
/* New bits for gdda_notification_types and gddr_notification */ const CB_NOTIFY_TYPE_BIT_MASK = 0x0000FFFF; const CB_NOTIFY_WANT_BIT_MASK = 0xFFFF0000; const CB_NOTIFY_WANT_VALID = 0x00010000; const CB_NOTIFY_WANT_OLD_DIR_OFF_COOKIE = 0x00020000; const CB_NOTIFY_WANT_NEW_DIR_OFF_COOKIE = 0x00040000; const CB_NOTIFY_WANT_ADD_PREV_ENTRY = 0x00080000; const CB_NOTIFY_WANT_LAST_ENTRY_BOOL = 0x00100000; const CB_NOTIFY_WANT_MONOTONIC_DIR_OFF_COOKIE = 0x00200000; const CB_NOTIFY_WANT_NOTIFY_SAME_CLIENT = 0x00400000; const CB_NOTIFY_WANT_SYNCHRONOUS_RECALL = 0x00800000; const CB_NOTIFY_WANT_DIR_ATTRS_RECALL = 0x01000000;¶
This bit flag is set to indicate this extension is being used.¶
This bit is used to by the client to indicate that this extension is being requested and by the server to indicate that it supports this extension. If not set in the server's reply, all bits not in the CB_NOTIFY4_TYPE_BIT_MASK MUST be ignored by the client and the client MUST assume [RFC8881] compliant directory delegation behavior for the server. If a server receives a GET_DIR_DELEGATION request without this bit set in it, the client is requesting a [RFC8881] compliant directory delegation. If the client receives any of NFS4ERR_BADXDR, NFS4ERR_INVAL or NFS4ERR_SERVERFAULT for a GET_DIR_DELEGATION reply, the client MUST assume that the server does not support this extension and can only support [RFC8881] compliant behavior.¶
This bit flag is set to indicate a valid nad_prev_entry in the NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFY requests. When this bit flag is set, the nad_prev_entry array will be of length 1 with a valid previous entry in it unless the new entry has been added at the beginning of the directory. When this bit flag is not set, the nad_prev_entry array MUST be of 0 length.¶
A server implementation may be simplified if it does not need to fill in a previous entry correctly.¶
This bit flag is set to indicate a valid nad_last_entry in the NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFY requests. When this bit flag is set, nad_last_entry will be set true or false to indicate if the new entry is the last entry in the directory. When this bit flag is not set, nad_last_entry should be false and MUST be ignored by the client.¶
A server implementation may be simplified if it does not need to indicate if a new entry is the last entry in a directory.¶
This bit flag is set to indicate that NOTIFY4_REMOVE_ENTRY, NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFY requests will be sent to the client that performed the operation(s) that changed the directory contents. If this bit is not set, the server will only send NOTIFY4_REMOVE_ENTRY, NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFY requests to other client(s) that hold a directory delegation for the directory whose contents changed. Normally, a server is required to perform a CB_RECALL of the directory delegation if it cannot perform the CB_NOTIFY(s) that a directory change requires. However, if this bit is not set, the CB_RECALL is only required to be done to other client(s) that hold a directory delegation for a directory that has changed and not for the client that performed the operation(s) that caused the directory change.¶
For some client implementations, a client will not require any CB_NOTIFYs for directory content changes that the same client caused via operation(s) performed on the directory. For other clients, the NOTIFY4_REMOVE_ENTRY, NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFYs are required for directory contents changes caused by the client performing operation(s) on the directory. This is likely because the client requires position information for the removal/addition of new entries from the server.¶
This bit flag is set to indicate that any required CB_RECALL of the directory delegation will be done synchronously. This behavior is described in Section 10.9.2 of [RFC8881] and requires that the recall be completed before the completion of the directory operation being performed on the server that caused the recall. If this bit is not set, any recall will be performed asynchronously, but with as short a delay as possible after the operation on the directory that caused the recall.¶
A synchronous recall will normally result in a reply of NFS4ERR_DELAY to the directory operation that is causing the directory change that is, in turn, causing the required CB_RECALL. This results in significant delays for clients performing such operations. Since CB_NOTIFYs are done asynchronously, it is likely that required CB_RECALLs can be asynchronous, as well. It seems likely that synchronous behavior may only be required for the pure recall model described in Section 10.9.2 of [RFC8881] and should only be required by a client if needed for correct behavior.¶
This bit flag is set to indicate that any change to the directory's attributes caused by operation(s) performed by other clients will result in a CB_RECALL of the directory delegation. Whether or not the CB_RECALL is done synchronously is determined by the CB_NOTIFY_WANT_SYNCHRONOUS_RECALL bit flag.¶
Some clients could use a CB_RECALL of the directory delegation to indicate that the directory's attributes have changed and that a ACCESS operation is needed to determine if the directory is still readable. Other clients may use NOTIFY4_CHANGE_DIR_ATTRS for handling directory attributes and directory access, while still others may choose to use ACCESS operations to determine if the directory is still readable. This flag avoids a CB_RECALL of the directory delegation for clients that do not require that behavior.¶
[RFC8881] does not specify what attributes are to be sent in the nad_new_entry.ne_attrs field of the CB_NOTIFYs. For this extension, the gdda_child_attributes argument to GET_DIR_DELEGATIONS indicates what attributes the client wants to be sent in the nad_new_entry.ne_attrs field of NOTIFY4_ADD_ENTRY or NOTIFY4_RENAME_ENTRY if either of these CB_NOTIFYs are requested in the gdda_notification_types argument.¶
The XDR specification for CB_NOTIFY found in [RFC8881] allows multiple bits to be set in cna_changes.notify_mask. If NOTIFY4_CHANGE_DIR_ATTRS is set along with any of NOTIFY4_REMOVE_ENTRY, NOTIFY4_ADD_ENTRY or NOTIFY4_RENAME_ENTRY, the directory attributes MUST be post operation attributes, for the operation that caused the NOTIFY4_REMOVE_ENTRY, NOTIFY4_ADD_ENTRY or NOTIFY4_RENAME_ENTRY.¶
This section is to be removed before publishing as an RFC.¶
This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs.¶
Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.¶
This section is to be removed before publishing as an RFC.¶
This section is to be removed before publishing as an RFC.¶
XXX¶