[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                   Spencer Shepler
Internet Draft                                          Editor
Document: draft-shepler-nfsv4-dirnotify-00.txt          Sun Microsystems
                                                        May 2003



                 NFS version 4 Directory Notifications



Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 10 of RFC2026.

   This document is an Internet-Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.

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

   To view the entire list of current Internet-Drafts, please check the
   "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
   Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern
   Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific
   Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast).

Abstract

   NFSv4 [RFC3530] contains within it a mechanism for the delegation of
   file data to a client.  The intent of this feature is to reduce the
   necessary interaction between a client and server such that overall
   performance is improved.  The same type of mechanism does not exist
   for directory contents and to determine validity of cached directory
   contents an NFSv4 client is left with polling the server to determine
   if updates have occurred.

   The proposal described here is for an NFSv4 minor version that would
   allow a client to register interest in a directory and to receive a
   callback RPC upon update of that directory.  This type of interaction
   would reduce or eliminate the polling that occurs between client and
   server and improve scalability of the server's resources along with
   improved performance for the client's directory content caching.



Expires: November 2003                                          [Page 1]


Title                 NFSv4 Directory Notifications             May 2003


Key Words

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].














































Expires: November 2003                                          [Page 2]


Title                 NFSv4 Directory Notifications             May 2003


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
   2.  Design . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
   3.  Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
   4.  GETDIR_NOTIFICATION - Request notification on a Directory  . 6
   5.  CLIENTID - Notify server of clientid associated with request 8
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . 9
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . 9
   8.  Normative References . . . . . . . . . . . . . . . . . . .  10
   9.  Informative References . . . . . . . . . . . . . . . . . .  10
   10.  Authors Address . . . . . . . . . . . . . . . . . . . . .  11
   10.1.  Editor's Address  . . . . . . . . . . . . . . . . . . .  11
   10.2.  Author's Addresses  . . . . . . . . . . . . . . . . . .  11
   11.  Copyright . . . . . . . . . . . . . . . . . . . . . . . .  12




































Expires: November 2003                                          [Page 3]


Title                 NFSv4 Directory Notifications             May 2003


1.  Introduction


   Directory caching for the NFS (Network File System) version 4
   [RFC3530] protocol is similar to previous versions of NFS.  Directory
   information is cached on the client for a duration determined by the
   client. At the end of a predefined timeout, the client will query the
   server to see if the directory has been updated.  In order to reduce
   network traffic, NFS version 4 defines delegations on file data.
   Traffic reduction is also the motivation behind directory
   notifications.

   A client registers interest in a directory by use of a specific
   operation and will be notified if that directory is modified in the
   future.  While this directory nofication mechanism uses the
   delegation structure of the NFSv4 protocol, it differs from file
   delegations in that the server is not required to notify registered
   clients before a directory modification can proceed.  While a
   directory notification doesn't provide strict notification behaviors,
   this allows the client to locally service certain directory
   operations (LOOKUP, LOOKUPP, READDIR) from its directory cache
   without querying the server at periodic predefined intervals.


2.  Design

   Directory notification design is based on file delegation.

   o    Use the existing file data delegation callback mechanism

   o    Use stateid's as in file data delegation

   o    DELEGRETURN will be used to return a directory delegation.

   o    Server decides when to accept directory notification
        registrations.

   o    Unlike file delegations which piggy-back on the file OPEN call,
        the client will request a directory notification with a new
        operation GETDIR_NOTIFICATION.

   o    directory notifications delegates what set of attributes? e.g.
        ACL, change, space_avail, time_access.  What attributes should
        not be delegated.

   o    directory notification covers contents: filehandles, fileid,
        fsid, cookies cached as part of directory, read the rest later
        even with a delegation



Expires: November 2003                                          [Page 4]


Title                 NFSv4 Directory Notifications             May 2003


   o    when a server receives a change in a directory with a registered
        notification, it doesn't have to wait for all DELEGRETURNs to
        occur before allowing the modification.


3.  Issues


   o    should we include the change attributes of the directory
        contents?
         problem: it's hard for the server to bookkeep.
           - singlely linked: keep track of parent
           - multiply linked: hard to keep track of

   o    renaming
          - grandparent renamed - directory read delegation still ok.
          - parent renamed?
          - content reneame? recall delegation.

   o    callback vrs change notify
          - should we allow a change notify operation over the callback
            communication link so that a small number of contents in a
            big directory can be updated without recalling the
        delegation?



























Expires: November 2003                                          [Page 5]


Title                 NFSv4 Directory Notifications             May 2003


4.  GETDIR_NOTIFICATION - Request notification on a Directory


   SYNOPSIS

     (cfh), dir_delegation_type4 -> stateid

   ARGUMENT

     enum dir_delegation_type4 {
             DIRECTORY_NOTIFY     = 0
     };

     struct GETDIR_NOTIFICATION4args {
       clientid4clientid;
             dir_delegation_type4    type;
     }


   RESULT

     union GETDIR_NOTIFICATION4res (bool_t available){
      case TRUE:
             stateid4    dir_stateid;
      case FALSE:
      default:
       void;
     }



   DESCRIPTION

     The client issues a GETDIR_NOTIFICATION operation to request a
     notification on the direcory represented by the current filehandle.
     If the server is unable or unwilling to provide the directory
     notification, the result will indicate this by setting the
     "available" value to FALSE.  In the case "available" is TRUE, the
     server provides a directory notification stateid.  This stateid is
     used by the client to match CB_RECALL calls from server to client.
     It is also used by the client for DELEGRETURN to indicate to the
     server that the directory notification is no longer needed.


   IMPLEMENTATION

     Since a server is not required to return directory notifications,
     the client must be prepared to never receive a directory



Expires: November 2003                                          [Page 6]


Title                 NFSv4 Directory Notifications             May 2003


     notification stateid.  This also allows the server to avoid
     returning an error for GETDIR_NOTIFICATION when it otherwise may be
     required.  This would potentially allow for a COMPOUND request to
     succeed in the case that subsequent operations would not encounter
     an error.

             PUTFH (directory filehandle)
             GETDIR_NOTIFICATION
             READDIR or LOOKUP










































Expires: November 2003                                          [Page 7]


Title                 NFSv4 Directory Notifications             May 2003


5.  CLIENTID - Notify server of clientid associated with request


   SYNOPSIS

     clientid -> ()

   ARGUMENT

     struct CLIENTID4args {
             clientid4       clientid;
     };


   RESULT

     struct CLIENTID4res {
             nfsstat4        status;
     };


   DESCRIPTION

     The CLIENTID operation is uesd to identify the client by the server
     supplied clientid.  This operation (used within a COMPOUND prior to
     operations that either deal with file delegations or directory
     notifications) can be used as an optimization for interaction
     between client and server.  The use of the operation is not
     required but the client should expect that the server may generate
     callbacks because it can not differentiate the client holding the
     delegation or directory notification from a client that does not
     hold the delegation or directory notification.

     An example of use would be something like:

             PUTFH
             CLIENTID
             CREATE


     In this scenario, the server is able to identify the client and
     associate a directory notification for the target directory of
     CREATE and avoid a notification callback as a result of the object
     creation.

     The client is implicitly agreeing to managing its knowledge of the
     directory notification in this case by the use of the CLIENTID
     operation.  Therefore, the client must not rely on the server's



Expires: November 2003                                          [Page 8]


Title                 NFSv4 Directory Notifications             May 2003


     callback and update its directory information as appropriate.


   IMPLEMENTATION



   ERRORS

     NFS4ERR_ADMIN_REVOKED
     NFS4ERR_BADXDR
     NFS4ERR_CB_PATH_DOWN
     NFS4ERR_EXPIRED
     NFS4ERR_LEASE_MOVED
     NFS4ERR_RESOURCE
     NFS4ERR_SERVERFAULT
     NFS4ERR_STALE_CLIENTID


6.  Security Considerations


   Note: security issues have yet to be considered and documented


7.  IANA Considerations


   Note: IANA issues have yet to be documented.






















Expires: November 2003                                          [Page 9]


Title                 NFSv4 Directory Notifications             May 2003


8.  Normative References


   [RFC3530] S. Shepler, B. Callaghan, D. Robinson, R. Thurlow, C.
             Beame, M.  Eisler, D. Noveck, RFC3530, "Network File System
             (NFS) version 4 Protocol", April 2003.


9.  Informative References










































Expires: November 2003                                         [Page 10]


Title                 NFSv4 Directory Notifications             May 2003


10.  Authors Address

   Address comments related to this memorandum to:

        nfsv4@ietf.org

10.1.  Editor's Address


   Spencer Shepler
   7808 Moonflower Drive
   Austin, Texas 78750

   Phone: 512-349-9376
   E-mail: spencer.shepler@sun.com


10.2.  Author's Addresses

   Andy Adamson
   Center for Information Technology Integration
   The University of Michigan
   519 W.William
   Ann Arbor, MI 48103-4943

   Phone: 734.764.9465
   E-mail: andros@citi.umich.edu


   David Noveck
   Network Appliance
   375 Totten Pond Road
   Waltham, MA  02451

   Phone: +1 781-768-5347
   E-mail: dnoveck@netapp.com















Expires: November 2003                                         [Page 11]


Title                 NFSv4 Directory Notifications             May 2003


11.  Copyright

   "Copyright (C) The Internet Society (date). All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implmentation may be prepared, copied, published and
   distributed, in whole or in part, without restriction of any kind,
   provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
























Expires: November 2003                                         [Page 12]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/