Directory Delegation clarification for Network File System Version 4, Minor Version 2

Introduction 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. 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 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. A server should reply with as large a subset of the bit flags set in gdda_notification_types in gddr_notification as is possible. The server may also set bit flags in gddr_notification that were not set in the client's gdda_notication_types field of the GET_DIR_DELEGATION request, to inform the client of what behavior is to be expected. 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.

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.

Protocol Extension Considerations This document presents an extension to minor version 2 of the NFSv4 protocol as described in . 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 does not define NFSv4.2 as non-extensible, so treats it as an extensible minor version. This Standards Track RFC extends NFSv4.2 but does not update or .

New Notification Bit Flags

New Bit Flags for Notification Bitmaps /* New bits for gdda_notification_types and gddr_notification */ const CB_NOTIFY_TYPE_BIT_MASK = 0x003F; const CB_NOTIFY_WANT_BIT_MASK = 0xFF00; const CB_NOTIFY_WANT_VALID = 0x0100; const CB_NOTIFY_WANT_OLD_DIR_OFF_COOKIE = 0x0200; const CB_NOTIFY_WANT_NEW_DIR_OFF_COOKIE = 0x0400; const CB_NOTIFY_WANT_ADD_PREV_ENTRY = 0x0800; const CB_NOTIFY_WANT_LAST_ENTRY_BOOL = 0x1000; const CB_NOTIFY_WANT_MONOTONIC_DIR_OFF_COOKIE = 0x2000; const CB_NOTIFY_WANT_NOTIFY_SAME_CLIENT = 0x4000; const CB_NOTIFY_WANT_SYNCHRONOUS_RECALL = 0x8000;

Definitions of new bit flags for notification bitmaps

CB_NOTIFY_WANT_VALID This bit flag is set to indicate this extension is being used.

Rationale 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 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 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 compliant behavior.

CB_NOTIFY_WANT_OLD_DIR_OFF_COOKIE This bit flag is set to indicate a valid nrm_old_entry_cookie in the NOTIFY4_REMOVE_ENTRY, NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFY requests.

Rationale This bit indicates that the nrm_old_entry_cookie field will be filled in correctly. When this bit flag is not set, all nrm_old_entry_cookie field(s) in CB_NOTIFY requests MUST be ignored. A server implementation may be simplified if it does not need to fill this field in correctly.

CB_NOTIFY_WANT_NEW_DIR_OFF_COOKIE This bit flag is set to indicate a valid nad_new_entry_cookie in the NOTIFY4_ADD_ENTRY and NOTIFY4_RENAME_ENTRY CB_NOTIFY requests. When this bit flag is not set, the nad_new_entry_cookie array MUST be of 0 length.

Rationale This bit indicates that the nad_new_entry_cookie array will always be of length 1 with a valid cookie value in it. When this bit flag is not set, the array nad_new_entry_cookie should be of 0 length and any array entry MUST be ignored. A server implementation may be simplified if it does not need to fill this field in correctly.

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

Rationale A server implementation may be simplified if it does not need to fill in a previous entry correctly.

CB_NOTIFY_WANT_MONOTONIC_DIR_OFF_COOKIE This bit flag is set to indicate that the directory offset cookies in the server's READDIR operation replies are always monotonically increasing values for this directory. If this bit is not set, a client can only assume directory offset cookie values in READDIR operation replies are unique for this directory.

Rationale If the directory offset cookies in the server's READDIR replies are monotonically increasing, the client can use these cookies to maintain the order of the directory entries in the READDIR reply. It can also use a valid value in nad_new_entry_cookie to determine the ordinal position of the new entry. The client can make good use of this ordinal position information, particularily when it is using CB_NOTIFYs to maintain cached READDIR reply blocks in the client.

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

Rationale A server implementation may be simplified if it does not need to indicate if a new entry is the last entry in a directory.

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

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

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

Rationale 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 in 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 and should only be required by a client if needed for correct behavior.

Implementation Status 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.

FreeBSD NFS server and client

Organization:: FreeBSD Project
URL:
Maturity:: Experimental software based on the current document.
Coverage:: The bulk of this specification is implemented, but using only certain bit flags.
Licensing:: BSD
Implementation experience:: The FreeBSD NFSv4.2 server implements the generation of monotonically increasing directory offset cookies and provides these cookies in NOTIFY4_REMOVE_ENTRY and NOTIFY4_ADD_ENTRY CB_NOTIFY's. It does not generate a previous entry for NOTIFY4_ADD_ENTRY and always replies with a 0 length nad_prev_entry array. It does not set nad_last_entry correctly and always returns false. When the FreeBSD NFSv4.2 server is required to recall a directory delegation, it performs the CB_RECALL asynchronously. The above is sufficient for the requirements of the FreeBSD NFSv4.2 client implementation at this time. The current client sets CB_NOTIFY_WANT_VALID, CB_NOTIFY_WANT_OLD_DIR_OFF_COOKIE, CB_NOTIFY_WANT_NEW_DIR_OFF_COOKIE, CB_NOTIFY_WANT_MONOTONIC_DIR_OFF_COOKIE and CB_NOTIFY_WANT_NOTIFY_SAME_CLIENT so that it can use the CB_NOTIFYs to maintain up to date cached READDIR blocks. However, the client implementation will soon accept a gddr_notification reply with only CB_NOTIFY_WANT_VALID set and will use the CB_NOTIFYs to maintain the client's name lookup cache.