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]