Skip to main content

Directory Delegation clarification for Network File System Version 4, Minor Version 2
draft-rmacklem-nfsv4-directory-delegations-01

Document Type Active Internet-Draft (individual)
Author Rick Macklem
Last updated 2024-05-13
RFC stream (None)
Intended RFC status (None)
Formats
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-rmacklem-nfsv4-directory-delegations-01
Network File System Version 4                                 R. Macklem
Internet-Draft                                                   FreeBSD
Intended status: Standards Track                             13 May 2024
Expires: 14 November 2024

 Directory Delegation clarification for Network File System Version 4,
                            Minor Version 2
             draft-rmacklem-nfsv4-directory-delegations-01

Abstract

   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.

Note

   This note is to be removed before publishing as an RFC.

   Discussion of this draft occurs on the NFSv4 working group mailing
   list (nfsv4@ietf.org), archived at
   https://mailarchive.ietf.org/arch/browse/nfsv4/. Working Group
   information is available at https://datatracker.ietf.org/wg/nfsv4/
   about/.

Status of This Memo

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

Macklem                 Expires 14 November 2024                [Page 1]
Internet-Draft  Directory Delegation clarification for N        May 2024

   This Internet-Draft will expire on 14 November 2024.

Copyright Notice

   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   3
   3.  Protocol Extension Considerations . . . . . . . . . . . . . .   3
   4.  New Notification Bit Flags  . . . . . . . . . . . . . . . . .   3
     4.2.  Definitions of new bit flags for notification bitmaps . .   4
       4.2.1.  CB_NOTIFY_WANT_VALID  . . . . . . . . . . . . . . . .   4
       4.2.2.  CB_NOTIFY_WANT_OLD_DIR_OFF_COOKIE . . . . . . . . . .   4
       4.2.3.  CB_NOTIFY_WANT_NEW_DIR_OFF_COOKIE . . . . . . . . . .   5
       4.2.4.  CB_NOTIFY_WANT_ADD_PREV_ENTRY . . . . . . . . . . . .   5
       4.2.5.  CB_NOTIFY_WANT_MONOTONIC_DIR_OFF_COOKIE . . . . . . .   5
       4.2.6.  CB_NOTIFY_WANT_LAST_ENTRY_BOOL  . . . . . . . . . . .   6
       4.2.7.  CB_NOTIFY_WANT_NOTIFY_SAME_CLIENT . . . . . . . . . .   6
       4.2.8.  CB_NOTIFY_WANT_SYNCHRONOUS_RECALL . . . . . . . . . .   7
   5.  Implementation Status . . . . . . . . . . . . . . . . . . . .   7
     5.1.  FreeBSD NFS server and client . . . . . . . . . . . . . .   7
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

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

Macklem                 Expires 14 November 2024                [Page 2]
Internet-Draft  Directory Delegation clarification for N        May 2024

   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.

   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.

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

3.  Protocol Extension Considerations

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

4.  New Notification Bit Flags

4.1.  New Bit Flags for Notification Bitmaps

Macklem                 Expires 14 November 2024                [Page 3]
Internet-Draft  Directory Delegation clarification for N        May 2024

   /* 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;

4.2.  Definitions of new bit flags for notification bitmaps

4.2.1.  CB_NOTIFY_WANT_VALID

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

4.2.1.1.  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 [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.

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

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

Macklem                 Expires 14 November 2024                [Page 4]
Internet-Draft  Directory Delegation clarification for N        May 2024

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

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

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

4.2.4.1.  Rationale

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

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

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

Macklem                 Expires 14 November 2024                [Page 5]
Internet-Draft  Directory Delegation clarification for N        May 2024

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

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

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

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

Macklem                 Expires 14 November 2024                [Page 6]
Internet-Draft  Directory Delegation clarification for N        May 2024

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

4.2.8.1.  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 Section 10.9.2 of [RFC8881] and should only be required
   by a client if needed for correct behavior.

5.  Implementation Status

   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.

5.1.  FreeBSD NFS server and client

   Organization:  FreeBSD Project

   URL:       https://www.freebsd.org

   Maturity:  Experimental software based on the current document.

Macklem                 Expires 14 November 2024                [Page 7]
Internet-Draft  Directory Delegation clarification for N        May 2024

   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.

6.  References

6.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC7862]  Haynes, T., "Network File System (NFS) Version 4 Minor
              Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862,
              November 2016, <https://www.rfc-editor.org/info/rfc7862>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8178]  Noveck, D., "Rules for NFSv4 Extensions and Minor
              Versions", RFC 8178, DOI 10.17487/RFC8178, July 2017,
              <https://www.rfc-editor.org/info/rfc8178>.

Macklem                 Expires 14 November 2024                [Page 8]
Internet-Draft  Directory Delegation clarification for N        May 2024

   [RFC8881]  Noveck, D., Ed. and C. Lever, "Network File System (NFS)
              Version 4 Minor Version 1 Protocol", RFC 8881,
              DOI 10.17487/RFC8881, August 2020,
              <https://www.rfc-editor.org/info/rfc8881>.

Acknowledgments

   XXX

Author's Address

   Rick Macklem
   FreeBSD Project
   Canada
   Email: rmacklem@uoguelph.ca

Macklem                 Expires 14 November 2024                [Page 9]