idnits 2.17.1 draft-khan-nfsv4-directory-delegation-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([RFC3530]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 379 has weird spacing: '...r_entry cha...' == Line 576 has weird spacing: '...ication would...' == Line 924 has weird spacing: '...r_entry chan...' == Line 929 has weird spacing: '...r_entry old_...' == Line 1113 has weird spacing: '...for the purpo...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 2004) is 7376 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3530 (Obsoleted by RFC 7530) Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group S. Khan 2 Internet-Draft Author 3 Document: Network Appliance, Inc. 4 draft-khan-nfsv4-directory-delegation-00.txt February 2004 6 NFSv4.1: Directory Delegations and Notifications 8 Status of this Memo 10 This document is an Internet-Draft and is subject to all provisions 11 of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that 15 other groups may also distribute working documents as 16 Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other 20 documents at any time. It is inappropriate to use Internet- 21 Drafts as reference material or to cite them other than as 22 "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/1id-abstracts.html 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html 30 ABSTRACT 32 This document proposes adding directory delegations and notifications 33 to NFS Version 4 [RFC3530]. It is hoped that these changes will be 34 part of a new minor version of NFS, such as NFSv4.1. 36 TABLE OF CONTENTS 38 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 39 2. Proposed protocol extensions. . . . . . . . . . . . . . . . . 3 40 3. Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 41 4. New Operation 40: GET_DIR_DELEGATION - Get a directory 42 delegation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 43 5. New Recommended Attributes . . . . . . . . . . . . . . . . . . 7 44 6. New Callback Operation: CB_NOTIFY - Notify directory changes . 8 45 7. Delegation Recall . . . . . . . . . . . . . . . . . . . . . 11 46 8. New Callback Operation: CB_RECALL_ANY - Keep any N 47 delegations . . . . . . . . . . . . . . . . . . . . . . . . 11 49 9. Delegation Recovery . . . . . . . . . . . . . . . . . . . . 12 50 10. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 12 51 10.1. Synchronous vs. Asynchronous notifications . . . . . . . 12 52 11. RPC Definition File Changes . . . . . . . . . . . . . . . . 13 53 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . 22 54 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 22 55 14. Normative References . . . . . . . . . . . . . . . . . . . 22 56 15. Informative References . . . . . . . . . . . . . . . . . . 23 57 16. Author's Address . . . . . . . . . . . . . . . . . . . . . 23 58 17. IPR Notices . . . . . . . . . . . . . . . . . . . . . . . . 23 59 18. Copyright Notice . . . . . . . . . . . . . . . . . . . . . 23 61 1. Introduction 63 This document assumes understanding of the NFSv4.0 specification. It 64 also assumes that the changes proposed by [talpey] will be present in 65 the same minor version and that the protocol would need some 66 adjustment in the event that the session changes are not present. 68 The major addition to NFS version 4 in the area of caching is the 69 ability of the server to delegate certain responsibilities to the 70 client. When the server grants a delegation for a file to a client, 71 the client receives certain semantic guarentees with respect to the 72 sharing of that file with other clients. At OPEN, the server may 73 provide the client either a read or write delegation for the file. If 74 the client is granted a read delegation, it is assured that no other 75 client has the ability to write to the file for the duration of the 76 delegation. If the client is granted a write delegation, the client 77 is assured that no other client has read or write access to the file. 78 This reduces network traffic by allowing the client to perform 79 various operations locally on file data. 81 Directory caching for the NFS version 4 protocol is similar to 82 previous versions. Clients typically cache directory information for 83 a duration determined by the client. At the end of a predefined 84 timeout, the client will query the server to see if the directory has 85 been updated. By caching attributes, clients reduce the number of 86 GETATTR calls made to the server to validate attributes. Furthermore, 87 frequently accessed files and directories, such as the current 88 working directory, have their attributes cached on the client so that 89 some NFS operations can be performed without having to make an RPC 90 call. By caching name and inode information about most recently 91 looked up entries in DNLC (Directory Name Lookup Cache), clients do 92 not need to send LOOKUP calls to the server every time these files 93 are accessed. 95 Delegation of directory contents is proposed as an extension for 96 NFSv4. Such an extension would provide similar traffic reduction 97 benefits as with file delegations. By allowing clients to cache 98 directory contents (in a read-only fashion) while being notified of 99 changes, the client can avoid making frequent requests to interrogate 100 the contents of slowly-changing directories, reducing network traffic 101 and improving client performance. 103 2. Proposed protocol extensions. 105 This document includes the definition of protocol extensions to 106 implement directory delegations. It is believed that these extension 107 fit within the minor-versioning framework presented in RFC3530, 108 although careful review on this point needs to be undertaken. As 109 stated above, these extensions are designed supposing that the 110 session extensions [talpey] will be present in the same minor 111 version, as currently seems likely. Some modifications will be 112 necessary, if that turns out not to be the case. 114 Mainly in the interests of clarity of presentation, elements within 115 these extensions are assigned numeric identifiers such as operation 116 numbers and attribute identitifies. It should be understood that 117 when these extensions are included in a minor version of NFSv4, the 118 actual numeric identifiers assigned may be different from the ones 119 chosen here. 121 3. Design 123 A client gets a directory delegation by use of a new operation 124 (GET_DIR_DELEGATION) and also informs the server if it wants to be 125 notified of any changes that are made to the directory. If the server 126 is unable to notify the client of some set of changes, it should 127 inform the client of its inability to do so. The server will send 128 notifications for all change events it has agreed to. Because true 129 synchronous notification poses significant server implementation 130 difficulties, the document describes just an asynchronous approach. 131 The clients are notified of changes to the directory only after the 132 change has been processed by the server. See the section "Synchronous 133 vs. Asynchronous notifications" for a discussion on different types 134 of notifications and the reason for choosing asynchronous 135 notifications. The delegation is read only and the client may not 136 make changes to the directory other than by performing NFSv4 137 operations that modify the directory or the associated file 138 attributes so that the server has knowledge of these changes. If a 139 client holding the delegation makes any changes to the directory, it 140 will not be notified and the delegation will not be recalled. The 141 client making changes is presumed not to need notifications of 142 changes that it itself is making. 144 Delegations can be recalled by the server. The server is free to 145 recall the delegation at any time. Normally, the server will recall 146 the delegation when the directory changes in a way that is not 147 covered by the notification, or when there is a directory change and 148 notifications have not been requested. 150 Also if the server notices that handing out a delegation for a 151 directory is causing too many notifications to be sent out, it may 152 decide not to hand out a delegation for that directory or recall 153 existing delegations. If another client removes the directory for 154 which a delegation has been granted, the server will recall the 155 delegation. 157 Both the notification and recall operations need a callback path to 158 exist between the client and server. If the callback path does not 159 exist, then delegations should not be granted. Note that with the 160 session extensions [talpey] that should not be an issue. 162 4. New Operation 40: GET_DIR_DELEGATION - Get a directory delegation 164 SYNOPSIS 165 (cfh), notification, claim -> (cfh), cookieverf, stateid, 166 notification 168 ARGUMENT 169 struct GET_DIR_DELEGATION4args { 170 dir_notification_type4 notification_type; 171 fattr4 file_attributes; 172 attr_notice file_attr_notice; 173 fattr4 dir_attributes; 174 attr_notice dir_attr_notice; 175 }; 177 /* 178 * Notification types. 179 */ 180 const DIR_NOTIFICATION_NONE = 0x00000000; 181 const DIR_NOTIFICATION_CHANGE_FILE_ATTRIBUTES = 0x00000001; 182 const DIR_NOTIFICATION_CHANGE_DIR_ATTRIBUTES = 0x00000002; 183 const DIR_NOTIFICATION_REMOVE_ENTRY = 0x00000004; 184 const DIR_NOTIFICATION_ADD_ENTRY = 0x00000008; 185 const DIR_NOTIFICATION_RENAME_ENTRY = 0x00000010; 186 const DIR_NOTIFICATION_CHANGE_COOKIE_VERIFIER = 0x00000020; 188 typedef uint32_t dir_notification_type4; 190 RESULT 191 struct GET_DIR_DELEGATION4resok { 192 verifier4 cookieverf; 193 /* Stateid for get_dir_delegation */ 194 stateid4 stateid; 196 /* Which notifications can the server support */ 197 dir_notification_type4 supp_notification; 198 fattr4 file_attributes; 199 fattr4 dir_attributes; 200 }; 202 struct attr_notice { 203 bitmap4 attr_notice_req; 204 uint32_t attr_notice_delays<>; 205 }; 207 union GET_DIR_DELEGATION4res switch (nfsstat4 status) { 208 case NFS4_OK: 209 /* CURRENT_FH: delegated dir */ 210 GET_DIR_DELEGATION4resok resok4; 211 default: 212 void; 213 }; 215 DESCRIPTION: 216 The GET_DIR_DELEGATION operation is used by the client to 217 request a directory delegation. The directory is represented by 218 the current filehandle. The client also specifies whether it 219 wants the server to notify it when the directory changes in 220 certain ways by setting bits in a bitmap. The server may choose 221 not to grant the delegation. In that case the server will return 222 NFS4ERR_DIRDELEG_UNAVAIL. If the server decides to hand out the 223 delegation, it will return a cookie verifier for that directory. 224 If the cookie verifier changes when the client is holding the 225 delegation, it will be notified about the change, provided the 226 client has asked for the notification. Otherwise, the delegation 227 will be recalled. 229 The server will also return a directory delegation stateid in 230 addition to the cookie verifier as a result of the 231 GET_DIR_DELEGATION operation. This stateid will appear in 232 callback messages related to the delegation, such as 233 notifications and delegation recalls. The client will use this 234 stateid to return the delegation voluntarily or upon recall. 235 Delegation is returned by calling the DELEGRETURN operation. 237 The server may not be able to support notifications of certain 238 events. If the client asks for such notifications, the server 239 must inform the client of its inability to do so as part of the 240 GET_DIR_DELEGATION reply. 242 The GET_DIR_DELEGATION operation can be used for both normal and 243 named attribute directories. 245 IMPLEMENTATION: 246 Notifications are specified in terms of potential changes to the 247 directory. A client can ask to be notified whenever an entry is 248 added to a directory by setting notification_type to 249 DIR_NOTIFICATION_ADD_ENTRY. It can also ask for notifications on 250 entry removal, renames, attribute and cookie verifier changes by 251 setting notification_type flag appropriately . A client can also 252 ask to be notified of all events that would invalidate its 253 attribute cache. In that case it will set the notification_type 254 to D IR_NOTIFICATION_CHANGE_FILE_ATTRIBUTES and 255 DIR_NOTIFICATION_CHANGE_DIR_ATTRIBUTES. The server will then 256 noti fy it of any file or directory attribute changes. If a 257 client is interested in directory entry caching, or negative 258 name caching, it can set the notification_type appropriately and 259 the server will notify it of all changes that would otherwise 260 invalidate its name cache. 262 The client will set one or more bits in a bitmap to let the 263 server know what kind of notification(s) it is interested in 264 getting. For attribute caching the client registers interest in 265 getting notifications for certain attributes by setting file and 266 directory attributes in two separate attribute bitmaps. One of 267 the bitmaps covers directory attributes changes and the other 268 covers changes to any files in the directory. The server can 269 choose to support notifications on only a subset of attributes. 270 The client will also specify the frequency of notifications for 271 each attribute change by setting the file_attr_notice and 272 dir_attr_notice arguments. The server will deny the request if 273 it does not support notifications on that attribute or the 274 requested frequency. If the client wants notifications for all 275 changes, it will set the time delay to zero indicating it wants 276 to be notified as soon as the change occurs. For other types of 277 notifications, the client does not need to provide the server 278 with this additional information. So in these cases the 279 attribute masks for file and directory will not be set. 281 The server will set a bitmap to inform the client of which 282 notifications it will receive. If it agrees to send attribute 283 notifications, it will also set two attribute masks indicating 284 which attribute change notifications it supports. One of the 285 masks covers changes in directory attributes and the other 286 covers changes to any files in the directory. 288 ERRORS 289 NFS4ERR_ACCESS 290 NFS4ERR_BADHANDLE 291 NFS4ERR_BADCHAR 292 NFS4ERR_BADNAME 293 NFS4ERR_BADXDR 294 NFS4ERR_FHEXPIRED 295 NFS4ERR_INVAL 296 NFS4ERR_MOVED 297 NFS4ERR_NAMETOOLONG 298 NFS4ERR_NOENT 299 NFS4ERR_NOFILEHANDLE 300 NFS4ERR_NOTDIR 301 NFS4ERR_RESOURCE 302 NFS4ERR_SERVERFAULT 303 NFS4ERR_STALE 304 NFS4ERR_DIRDELEG_UNAVAIL 305 NFS4ERR_DIRDELEG_DENIED 307 5. New Recommended Attributes 309 #56 - supp_dir_attr_notice - Range of notification delays on 310 directory attributes 311 #57 - supp_file_attr_notice - Range of notification delays on file 312 attributes 314 DESCRIPTION: 315 These attributes allow the client and server to negotiate the 316 frequency of notifications sent due to changes in attributes. 317 The server returns these attributes for every attribute that it 318 supports. Each has a range of supported notification delay for 319 every attribute. If the server does not support notifications on 320 a certain attribute, it must indicate that by not setting these 321 attributes. 323 These attributes are per filesystem attributes. The client need 324 only get the values when it encounters a new fsid during 325 navigation of the server's namespace. 327 The client gets this information when it does a GETATTR on a 328 directory. The server will return supp_dir_attr_notice on every 329 directory attribute giving a range of notification frequencies. 330 It is possible that the server does not support or supports 331 different ranges for file attributes. The server will set 332 supp_file_attr_notice to indicate the range of notification 333 frequencies for file attribute changes. This attribute covers 334 all files in the directory. e.g. A server can choose to support 335 notifications for mtime updates between 0 to 5 seconds. If the 336 client specifies a time delay of 3 seconds, the server will 337 guarentee that mtime updates are not out of sync by more than 3 338 seconds. For file changes, the server will provide the same 339 guarentee for any mtime change on any file in the directory. 341 When the client calls the GET_DIR_DELEGATION operation and asks 342 for attribute change notifications, it will request a 343 notification time that is within the supported server range. If 344 the client violates what supp_attr_file_notice or 345 supp_attr_dir_notice values are, GET_DIR_DELEGATION fails with 346 NFS4ERR_DIRDELEG_DENIED. 348 6. New Callback Operation: CB_NOTIFY - Notify directory changes 350 SYNOPSIS 351 stateid, notification -> {} 353 ARGUMENT 354 struct CB_NOTIFY4args { 355 stateid4 stateid; 356 dir_notification4 changes<>; 357 }; 359 /* 360 * Notification information sent to the client. 361 */ 362 union dir_notification4 363 switch (dir_notification_type4 notification_type) { 364 case DIR_NOTIFICATION_CHANGE_FILE_ATTRIBUTE: 365 dir_notification_attribute4 change_file_attributes; 366 case DIR_NOTIFICATION_CHANGE_DIR_ATTRIBUTE: 367 fattr4 change_dir_attributes; 368 case DIR_NOTIFICATION_REMOVE_ENTRY: 369 dir_notification_remove4 remove_notification; 370 case DIR_NOTIFICATION_ADD_ENTRY: 371 dir_notification_add4 add_notification; 372 case DIR_NOTIFICATION_RENAME_ENTRY: 373 dir_notification_rename4 rename_notification; 374 case DIR_NOTIFICATION_CHANGE_COOKIE_VERIFIER: 375 dir_notification_verifier4 verf_notification; 376 }; 378 struct dir_notification_attribute4 { 379 dir_entry changed_entry; 380 fattr4 change_dir_attributes; 381 }; 383 struct dir_notification_remove4 { 384 dir_entry old_entry; 385 nfs_cookie4 old_entry_cookie; 386 }; 388 struct dir_notification_rename4 { 389 dir_entry old_entry; 390 dir_notification_add4 new_entry; 391 }; 393 struct dir_notification_verifier4 { 394 verifier4 old_cookieverf; 395 verifier4 new_cookieverf; 396 }; 398 struct dir_notification_add4 { 399 dir_entry new_entry; 400 /* what READDIR would have returned for this entry */ 401 nfs_cookie4 new_entry_cookie; 402 bool last_entry; 403 prev_entry4 prev_entry_info; 404 }; 406 union prev_entry4 switch (bool isprev) { 407 case TRUE: /* A previous entry exists */ 408 prev_entry4 prev_entry_info; 409 case FALSE: /* we are adding to an empty 410 directory */ 411 void; 412 }; 414 /* 415 * Previous entry information 416 */ 417 struct prev_entry4 { 418 dir_entry prev_entry; 419 /* what READDIR returned for this entry */ 420 nfs_cookie4 prev_entry_cookie; 421 } 422 /* 423 * Changed entry information. 424 */ 425 struct dir_entry { 426 component4 file; 427 fattr4 attrs; 428 }; 430 RESULT 431 struct CB_NOTIFY4res { 432 nfsstat4 status; 433 }; 435 DESCRIPTION: 436 The CB_NOTIFY operation is used by the server to send 437 notifications to clients about changes in a delegated directory. 439 These notifications are sent over the callback path. The 440 notification is sent once the original request has been 441 processed on the server. The server will send an array of 442 notifications for all changes that might have occured in the 443 directory. It will send the following information for each 444 operation: 446 o ADDING A FILE: The server sends information about the new 447 entry being created along with the cookie for that entry. The 448 entry information contains the nfs name of the entry and 449 attributes. If this entry is added to the end of the 450 directory, the server will set a last_entry flag to true. If 451 the file is added such that there is atleast one entry before 452 it, the server will also return the previous entry 453 information along with its cookie. This is to help clients 454 find the right location in their DNLC or directory caches 455 where this entry should be cached. 457 o REMOVING A FILE: The server sends information about the 458 directory entry being deleted. The server also sends the 459 cookie value for the deleted entry so that clients can get to 460 the cached information for this entry. 462 o RENAMING A FILE: The server sends information about both the 463 old entry and the new entry. This includes name and 464 attributes for each entry. This notification is only sent if 465 both entries are in the same directory. If the rename is 466 across directories, the server will send a remove 467 notification to one directory and an add notification to the 468 other directory, assuming both have a directory delegation. 470 o FILE/DIR ATTRIBUTE CHANGE: The client uses the attribute 471 mask to inform the server of attributes for which it wants to 472 receive notifications. This change notification can be 473 requested for both changes to the attributes of the directory 474 as well as changes to any files in the directory by using two 475 separate attribute masks. The client can not ask for change 476 attribute notification per file. One attribute mask covers 477 all the files in the directory. Upon any attribute change, 478 the server will send back the values of changed attributes. 479 If the client asks for change attributes on files, the server 480 will send back the change notification for both files and 481 directory. Notifications might not make sense for some 482 filesystem wide attributes and it is up to the server to 483 decide which subset it wants to support. The client can 484 negotiate the frequency of attribute notifications by letting 485 the server know how often it wants to be notified of an 486 attribute change. The server will return a range of supported 487 notification frequencies or an indication that no 488 notification is permitted for every attribute by setting the 489 supp_attr_file_notice and supp_attr_dir_notice attributes. 491 o COOKIE VERIFIER CHANGE: If the cookie verifier changes while 492 a client is holding a delegation, the server will notify the 493 client so that it can invalidate its cookies and reissue a 494 READDIR to get the new set of cookies. 496 ERRORS 497 NFS4ERR_BAD_STATEID 498 NFS4ERR_INVAL 499 NFS4ERR_BADXDR 501 7. Delegation Recall 503 The server will recall the directory delegation by sending a callback 504 to the client. It will use the same callback procedure as used for 505 recalling file delegations. The server will recall the delegation 506 when the directory changes in a way that is not covered by the 507 notification. Also if the server notices that handing out a 508 delegation for a directory is causing too many notifications to be 509 sent out, it may decide not to hand out a delegation for that 510 directory. If another client tries to remove the directory for which 511 a delegation has been granted, the server may recall the delegation. 513 The server will recall the delegation by sending a CB_RECALL callback 514 to the client and if the delegation is being recalled due to a change 515 being made to the directory that is not covered by the notification, 516 the request making that change may need to wait while the client 517 returns the delegation. 519 8. New Callback Operation: CB_RECALL_ANY - Keep any N delegations 521 SYNOPSIS 522 N -> {} 524 ARGUMENT 525 struct CB_RECALLANYY4args { 526 uint4 dlgs_to_keep; 527 } 529 RESULT 530 struct CB_RECALLANY4res { 531 nfsstat4 status; 533 }; 535 DESCRIPTION: 536 The server may decide that it can not hold all the delegation 537 state without running out of resources. Since the server has no 538 knowledge of which delegations are being used more than others, 539 it can not implement an effective reclaim scheme that avoids 540 reclaiming frequently used delegations. In that case the server 541 may issue a CB_RECALL_ANY callback to the client asking it to 542 keep N delegations and return the rest. The reason why 543 CB_RECALL_ANY specifies a count of delegations the client may 544 keep as opposed to a count of delegations the client must yield 545 is as follows. Were it otherwise, there is a potential for a 546 race between a CB_RECALL_ANY that had a count of delegations to 547 free with a set of client originated operations to return 548 delegations. As a result of the race the client and server would 549 have differing ideas as to how many delegations to return. Hence 550 the client could mistakenly free too many delegations. 552 The client can choose to return any type of delegation as a 553 result of this callback i.e. read, write or directory 554 delegation. The client can also choose to keep more delegations 555 than what the server asked for and it is up to the server to 556 handle this situation. The server must give the client enough 557 time to return the delegations. This time should not be less 558 than the lease period. 560 ERRORS 561 NFS4ERR_RESOURCE 563 9. Delegation Recovery 565 Since the mode of notifications proposed in this draft is 566 asynchronous in nature, and since the primary use of directory 567 delegations is anticipated to be in the conjection with 568 notifications, adding reclaim functionality will add unnecessary 569 implementation complexity. Thus, the client is required to establish 570 a new delegation on a server or client reboot. 572 10. Issues 574 10.1. Synchronous vs. Asynchronous notifications 576 An async notification would be sent to a client holding the 577 delegation after a directory changing event has taken place. It is 578 possible that the client holding the delegation tries to act on the 579 change before it has been notified by the server and fails. It would 580 certainly be better if the notification was synchronous so that when 581 the client tried to access, e.g. a newly created file, it was 582 guaranteed to be there. 584 For one form of synchronous notification, the server would suspend 585 the request and send a notification to the client notifying it of the 586 change about to occur. However this is not a true synchronous 587 notification, since after the server has sent out the notification, 588 it might discover that due to some error the request cannot be 589 completed. If this is for a regular file create, the client might add 590 this information to its directory cache and return bogus positive 591 information as a result of a readdir call. This puts the client in a 592 worse situation than with async notifications where the change is 593 guaranteed to be available but a delay may be involved. 595 For another form of synchronous notification, the server would notify 596 a client holding the delegation about a change about to occur in a 597 directory, only after the server has determined that this request is 598 definitely going to succeed. At that time, the server would send a 599 notification to the client holding the delegation while suspending 600 the original request. However note that the server has not yet 601 committed the change so at this point in time, only the client 602 holding the delegation knows about this change. Once the client 603 acknowledges the notification, the server will commit the change 604 making it visible to all other clients. It is doubtful many operating 605 environments would allow a server to provide this form of 606 notification. 608 Since synchronous notifications do not guarentee true request 609 ordering any better than asynchronous notifications except by adding 610 substantial implementation complexity, asynchronous notifications are 611 proposed as the default method for notifying the client. These 612 notifications l be sent after the directory changing operation has 613 completed. 615 11. RPC Definition File Changes 617 /* 618 * Copyright (C) The Internet Society (2003) 619 * All Rights Reserved. 620 */ 622 /* 623 * nfs41_prot.x 624 */ 626 %/* $Id: nfs41_prot.x,v 1.1 2004/02/01 05:10:53 saadia Exp $ */ 628 /* new operation, GET_DIR_DELEGATION */ 629 /* 630 * Notification mask for letting the server know which notifications 631 * the client is interested in. 632 */ 633 typedef uint32_t dir_notification_type4; 635 /* 636 * The bitmask constants used for notification_type field 637 */ 638 const DIR_NOTIFICATION_NONE = 0x00000000; 639 const DIR_NOTIFICATION_CHANGE_FILE_ATTRIBUTES = 0x00000001; 640 const DIR_NOTIFICATION_CHANGE_DIR_ATTRIBUTES = 0x00000002; 641 const DIR_NOTIFICATION_REMOVE_ENTRY = 0x00000004; 642 const DIR_NOTIFICATION_ADD_ENTRY = 0x00000008; 643 const DIR_NOTIFICATION_RENAME_ENTRY = 0x00000010; 644 const DIR_NOTIFICATION_CHANGE_COOKIE_VERIFIER = 0x00000020; 646 /* 647 * Input arguments passed to the GET_DIR_DELEGATION operation. 648 */ 649 struct GET_DIR_DELEGATION4args { 650 /* CURRENT_FH: directory */ 651 dir_notification_type4 notification_type; 652 fattr4 file_attributes; 653 attr_notice file_attr_notice; 654 fattr4 dir_attributes; 655 attr_notice dir_attr_notice; 656 }; 658 /* 659 * Result flags 660 */ 662 struct GET_DIR_DELEGATION4resok { 663 verifier4 cookieverf; 664 /* Stateid for get_dir_delegation */ 665 stateid4 stateid; 666 /* Which notifications can the server support */ 667 dir_notification_type4 supp_notification; 668 /* Which attribute notifications can the server support */ 669 fattr4 file_attributes; 670 fattr4 dir_attributes; 671 }; 673 struct attr_notice { 674 bitmap4 attr_notice_req; 675 uint32_t attr_notice_delays<>; 676 }; 678 union GET_DIR_DELEGATION4res switch (nfsstat4 status) { 679 case NFS4_OK: 680 /* CURRENT_FH: delegated dir */ 681 GET_DIR_DELEGATION4resok resok4; 682 default: 683 void; 684 }; 686 /* 687 * Operation arrays 688 */ 690 enum nfs_opnum4 { 691 OP_ACCESS = 3, 692 OP_CLOSE = 4, 693 OP_COMMIT = 5, 694 OP_CREATE = 6, 695 OP_DELEGPURGE = 7, 696 OP_DELEGRETURN = 8, 697 OP_GETATTR = 9, 698 OP_GETFH = 10, 699 OP_LINK = 11, 700 OP_LOCK = 12, 701 OP_LOCKT = 13, 702 OP_LOCKU = 14, 703 OP_LOOKUP = 15, 704 OP_LOOKUPP = 16, 705 OP_NVERIFY = 17, 706 OP_OPEN = 18, 707 OP_OPENATTR = 19, 708 OP_OPEN_CONFIRM = 20, 709 OP_OPEN_DOWNGRADE = 21, 710 OP_PUTFH = 22, 711 OP_PUTPUBFH = 23, 712 OP_PUTROOTFH = 24, 713 OP_READ = 25, 714 OP_READDIR = 26, 715 OP_READLINK = 27, 716 OP_REMOVE = 28, 717 OP_RENAME = 29, 718 OP_RENEW = 30, 719 OP_RESTOREFH = 31, 720 OP_SAVEFH = 32, 721 OP_SECINFO = 33, 722 OP_SETATTR = 34, 723 OP_SETCLIENTID = 35, 724 OP_SETCLIENTID_CONFIRM = 36, 725 OP_VERIFY = 37, 726 OP_WRITE = 38, 727 OP_RELEASE_LOCKOWNER = 39, 728 OP_OPENDIR = 40, 729 OP_ILLEGAL = 10044 730 }; 732 union nfs_argop4 switch (nfs_opnum4 argop) { 733 case OP_ACCESS: ACCESS4args opaccess; 734 case OP_CLOSE: CLOSE4args opclose; 735 case OP_COMMIT: COMMIT4args opcommit; 736 case OP_CREATE: CREATE4args opcreate; 737 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 738 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 739 case OP_GETATTR: GETATTR4args opgetattr; 740 case OP_GETFH: void; 741 case OP_LINK: LINK4args oplink; 742 case OP_LOCK: LOCK4args oplock; 743 case OP_LOCKT: LOCKT4args oplockt; 744 case OP_LOCKU: LOCKU4args oplocku; 745 case OP_LOOKUP: LOOKUP4args oplookup; 746 case OP_LOOKUPP: void; 747 case OP_NVERIFY: NVERIFY4args opnverify; 748 case OP_OPEN: OPEN4args opopen; 749 case OP_OPENATTR: OPENATTR4args opopenattr; 750 case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; 751 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4args opopen_downgrade; 752 case OP_PUTFH: PUTFH4args opputfh; 753 case OP_PUTPUBFH: void; 754 case OP_PUTROOTFH: void; 755 case OP_READ: READ4args opread; 756 case OP_READDIR: READDIR4args opreaddir; 757 case OP_READLINK: void; 758 case OP_REMOVE: REMOVE4args opremove; 759 case OP_RENAME: RENAME4args oprename; 760 case OP_RENEW: RENEW4args oprenew; 761 case OP_RESTOREFH: void; 762 case OP_SAVEFH: void; 763 case OP_SECINFO: SECINFO4args opsecinfo; 764 case OP_SETATTR: SETATTR4args opsetattr; 765 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 766 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args 767 opsetclientid_confirm; 768 case OP_VERIFY: VERIFY4args opverify; 769 case OP_WRITE: WRITE4args opwrite; 770 case OP_RELEASE_LOCKOWNER: RELEASE_LOCKOWNER4args 771 oprelease_lockowner; 772 case OP_OPENDIR: OPENDIR4args opopendir; 773 case OP_ILLEGAL: void; 774 }; 775 union nfs_resop4 switch (nfs_opnum4 resop){ 776 case OP_ACCESS: ACCESS4res opaccess; 777 case OP_CLOSE: CLOSE4res opclose; 778 case OP_COMMIT: COMMIT4res opcommit; 779 case OP_CREATE: CREATE4res opcreate; 780 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 781 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 782 case OP_GETATTR: GETATTR4res opgetattr; 783 case OP_GETFH: GETFH4res opgetfh; 784 case OP_LINK: LINK4res oplink; 785 case OP_LOCK: LOCK4res oplock; 786 case OP_LOCKT: LOCKT4res oplockt; 787 case OP_LOCKU: LOCKU4res oplocku; 788 case OP_LOOKUP: LOOKUP4res oplookup; 789 case OP_LOOKUPP: LOOKUPP4res oplookupp; 790 case OP_NVERIFY: NVERIFY4res opnverify; 791 case OP_OPEN: OPEN4res opopen; 792 case OP_OPENATTR: OPENATTR4res opopenattr; 793 case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; 794 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4res opopen_downgrade; 795 case OP_PUTFH: PUTFH4res opputfh; 796 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 797 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 798 case OP_READ: READ4res opread; 799 case OP_READDIR: READDIR4res opreaddir; 800 case OP_READLINK: READLINK4res opreadlink; 801 case OP_REMOVE: REMOVE4res opremove; 802 case OP_RENAME: RENAME4res oprename; 803 case OP_RENEW: RENEW4res oprenew; 804 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 805 case OP_SAVEFH: SAVEFH4res opsavefh; 806 case OP_SECINFO: SECINFO4res opsecinfo; 807 case OP_SETATTR: SETATTR4res opsetattr; 808 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 809 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4res 810 opsetclientid_confirm; 811 case OP_VERIFY: VERIFY4res opverify; 812 case OP_WRITE: WRITE4res opwrite; 813 case OP_RELEASE_LOCKOWNER: RELEASE_LOCKOWNER4res 814 oprelease_lockowner; 815 case OP_OPENDIR: OPENDIR4res opopendir; 816 case OP_ILLEGAL: ILLEGAL4res opillegal; 817 }; 819 struct COMPOUND4args { 820 utf8str_cs tag; 821 uint32_t minorversion; /* == 1 !!! */ 822 nfs_argop4 argarray<>; 823 }; 824 struct COMPOUND4res { 825 nfsstat4 status; 826 utf8str_cs tag; 827 nfs_resop4 resarray<>; 828 }; 830 /* 831 * New error codes 832 */ 834 enum nfsstat4 { 835 NFS4_OK = 0, /* everything is okay */ 836 NFS4ERR_PERM = 1, /* caller not privileged */ 837 NFS4ERR_NOENT = 2, /* no such file/directory */ 838 NFS4ERR_IO = 5, /* hard I/O error */ 839 NFS4ERR_NXIO = 6, /* no such device */ 840 NFS4ERR_ACCESS = 13, /* access denied */ 841 NFS4ERR_EXIST = 17, /* file already exists */ 842 NFS4ERR_XDEV = 18, /* different filesystems */ 843 /* Unused/reserved 19 */ 844 NFS4ERR_NOTDIR = 20, /* should be a directory */ 845 NFS4ERR_ISDIR = 21, /* should not be directory */ 846 NFS4ERR_INVAL = 22, /* invalid argument */ 847 NFS4ERR_FBIG = 27, /* file exceeds server max */ 848 NFS4ERR_NOSPC = 28, /* no space on filesystem */ 849 NFS4ERR_ROFS = 30, /* read-only filesystem */ 850 NFS4ERR_MLINK = 31, /* too many hard links */ 851 NFS4ERR_NAMETOOLONG = 63, /* name exceeds server max */ 852 NFS4ERR_NOTEMPTY = 66, /* directory not empty */ 853 NFS4ERR_DQUOT = 69, /* hard quota limit reached*/ 854 NFS4ERR_STALE = 70, /* file no longer exists */ 855 NFS4ERR_BADHANDLE = 10001,/* Illegal filehandle */ 856 NFS4ERR_BAD_COOKIE = 10003,/* READDIR cookie is stale */ 857 NFS4ERR_NOTSUPP = 10004,/* operation not supported */ 858 NFS4ERR_TOOSMALL = 10005,/* response limit exceeded */ 859 NFS4ERR_SERVERFAULT = 10006,/* undefined server error */ 860 NFS4ERR_BADTYPE = 10007,/* type invalid for CREATE */ 861 NFS4ERR_DELAY = 10008,/* file "busy" - retry */ 862 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 863 NFS4ERR_DENIED = 10010,/* lock unavailable */ 864 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 865 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 866 NFS4ERR_GRACE = 10013,/* in grace period */ 867 NFS4ERR_FHEXPIRED = 10014,/* filehandle expired */ 868 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 869 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 870 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 871 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 872 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 873 NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ 874 NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ 875 NFS4ERR_STALE_CLIENTID = 10022,/* server has rebooted */ 876 NFS4ERR_STALE_STATEID = 10023,/* server has rebooted */ 877 NFS4ERR_OLD_STATEID = 10024,/* state is out of sync */ 878 NFS4ERR_BAD_STATEID = 10025,/* incorrect stateid */ 879 NFS4ERR_BAD_SEQID = 10026,/* request is out of seq. */ 880 NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */ 881 NFS4ERR_LOCK_RANGE = 10028,/* lock range not supported*/ 882 NFS4ERR_SYMLINK = 10029,/* should be file/directory*/ 883 NFS4ERR_RESTOREFH = 10030,/* no saved filehandle */ 884 NFS4ERR_LEASE_MOVED = 10031,/* some filesystem moved */ 885 NFS4ERR_ATTRNOTSUPP = 10032,/* recommended attr not sup*/ 886 NFS4ERR_NO_GRACE = 10033,/* reclaim outside of grace*/ 887 NFS4ERR_RECLAIM_BAD = 10034,/* reclaim error at server */ 888 NFS4ERR_RECLAIM_CONFLICT = 10035,/* conflict on reclaim */ 889 NFS4ERR_BADXDR = 10036,/* XDR decode failed */ 890 NFS4ERR_LOCKS_HELD = 10037,/* file locks held at CLOSE*/ 891 NFS4ERR_OPENMODE = 10038,/* conflict in OPEN and I/O*/ 892 NFS4ERR_BADOWNER = 10039,/* owner translation bad */ 893 NFS4ERR_BADCHAR = 10040,/* utf-8 char not supported*/ 894 NFS4ERR_BADNAME = 10041,/* name not supported */ 895 NFS4ERR_BAD_RANGE = 10042,/* lock range not supported*/ 896 NFS4ERR_LOCK_NOTSUPP = 10043,/* no atomic up/downgrade */ 897 NFS4ERR_OP_ILLEGAL = 10044,/* undefined operation */ 898 NFS4ERR_DEADLOCK = 10045,/* file locking deadlock */ 899 NFS4ERR_FILE_OPEN = 10046,/* open file blocks op. */ 900 NFS4ERR_ADMIN_REVOKED = 10047,/* lockowner state revoked */ 901 NFS4ERR_CB_PATH_DOWN = 10048,/* callback path down */ 902 NFS4ERR_DIRDELEG_UNAVAIL= 10049,/* dir dlg. not returned */ 903 NFS4ERR_DIRDELEG_DENIED = 10050 /* dir delegation denied */ 904 }; 906 /* 907 * New Callback operation CB_NOTIFY 908 */ 910 struct CB_NOTIFY4args { 911 stateid4 stateid; 912 dir_notification4 changes<>; 913 }; 915 /* 916 * Changed entry information. 917 */ 918 struct dir_entry { 919 component4 file; 920 fattr4 attrs; 921 }; 923 struct dir_notification_attribute4 { 924 dir_entry changed_entry; 925 fattr change_dir_attributes; 926 }; 928 struct dir_notification_remove4 { 929 dir_entry old_entry; 930 nfs_cookie4 old_entry_cookie; 931 }; 933 struct dir_notification_rename4 { 934 dir_entry old_entry; 935 dir_notification_add4 new_entry; 936 }; 938 struct dir_notification_verifier4 { 939 verifier4 old_cookieverf; 940 verifier4 new_cookieverf; 941 }; 943 struct dir_notification_add4 { 944 dir_entry new_entry; 945 nfs_cookie4 new_entry_cookie; /* what READDIR would 946 have returned 947 for this entry */ 948 bool last_entry; 949 prev_entry4 prev_entry_info; 950 }; 952 union prev_entry4 switch (bool isprev) { 953 case TRUE: 954 prev_entry4 prev_entry_info; 955 case FALSE: /* we are adding to an empty directory */ 956 void; 957 }; 959 /* 960 * Previous entry information 961 */ 962 struct prev_entry4 { 963 dir_entry prev_entry; 964 /* what READDIR returned for this entry */ 965 nfs_cookie4 prev_entry_cookie; 966 }; 968 /* 969 * Notification information sent to the client. 970 */ 971 union dir_notification4 972 switch (dir_notification_type4 notification_type) { 973 case DIR_NOTIFICATION_CHANGE_FILE_ATTRIBUTE: 974 dir_notification_attribute4 change_file_attributes; 975 case DIR_NOTIFICATION_CHANGE_DIR_ATTRIBUTE: 976 fattr4 change_dir_attributes; 977 case DIR_NOTIFICATION_REMOVE_ENTRY: 978 dir_notification_remove4 remove_notification; 979 case DIR_NOTIFICATION_ADD_ENTRY: 980 dir_notification_add4 add_notification; 981 case DIR_NOTIFICATION_RENAME_ENTRY: 982 dir_notification_rename4 rename_notification; 983 case DIR_NOTIFICATION_CHANGE_COOKIE_VERIFIER: 984 dir_notification_verifier4 verf_notification; 985 }; 987 struct CB_NOTIFY4res { 988 nfsstat4 status; 989 }; 991 /* 992 * New Callback operation CB_RECALL_ANY 993 * 995 struct CB_RECALLANYY4args { 996 uint4 dlgs_to_keep; 997 } 999 struct CB_RECALLANY4res { 1000 nfsstat4 status; 1001 }; 1003 /* 1004 * Various definitions for CB_COMPOUND 1005 */ 1006 enum nfs_cb_opnum4 { 1007 OP_CB_GETATTR = 3, 1008 OP_CB_RECALL = 4, 1009 OP_CB_NOTIFY = 5, 1010 OP_CB_RECALL_ANY = 6, 1011 OP_CB_ILLEGAL = 10044 1012 }; 1014 union nfs_cb_argop4 switch (unsigned argop) { 1015 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 1016 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 1017 case OP_CB_NOTIFY: CB_NOTIFY4args opcbnotify; 1018 case OP_CB_RECALLANY: CB_RECALLANY4args opcbrecallany; 1019 case OP_CB_ILLEGAL: CB_ILLEGAL4args opcbillegal; 1020 }; 1022 union nfs_cb_resop4 switch (unsigned resop) { 1023 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 1024 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 1025 case OP_CB_NOTIFY: CB_NOTIFY4res opcbnotify; 1026 case OP_CB_RECALLANY: CB_RECALLANY4res opcbrecallany; 1027 case OP_CB_ILLEGAL: CB_ILLEGAL4res opcbillegal; 1028 }; 1030 struct CB_COMPOUND4args { 1031 utf8str_cs tag; 1032 uint32_t minorversion; 1033 uint32_t callback_ident; 1034 nfs_cb_argop4 argarray<>; 1035 }; 1037 struct CB_COMPOUND4res { 1038 nfsstat4 status; 1039 utf8str_cs tag; 1040 nfs_cb_resop4 resarray<>; 1041 }; 1043 12. IANA Considerations 1045 The IANA considerations of NFSv4.0 apply to NFSv4.1. 1047 13. Acknowledgements 1049 David Noveck and Michael Eisler for their constructive feedback and 1050 critical comments. 1052 14. Normative References 1054 [RFC3530] 1055 S. Shepler, B. Callaghan, D. Robinson, R. Thurlow, C. Beame, M. 1056 Eisler, D. Noveck, "NFS version 4 Protocol", RFC 3530, April, 1057 2003. 1059 [talpey] 1060 T. Talpey, S. Shepler, "NFSv4 RDMA and Session Extensions", 1061 Internet-Draft, May, 2003. A URL for this Internet-Draft is 1062 available at http://www.ietf.org/internet-drafts/draft-talpey- 1063 nfsv4-rdma-sess-00.txt 1065 15. Informative References 1067 None. 1069 16. Author's Address 1071 Saadia Khan 1072 2324 Dubois Street 1073 Milpitas, CA 95035 1074 USA 1076 Phone: 408-957-9626 1077 EMail: saadiak@yahoo.com 1079 17. IPR Notices 1081 The IETF takes no position regarding the validity or scope of any 1082 intellectual property or other rights that might be claimed to 1083 pertain to the implementation or use of the technology described in 1084 this document or the extent to which any license under such rights 1085 might or might not be available; neither does it represent that it 1086 has made any effort to identify any such rights. Information on the 1087 IETF's procedures with respect to rights in standards-track and 1088 standards-related documentation can be found in BCP-11. Copies of 1089 claims of rights made available for publication and any assurances of 1090 licenses to be made available, or the result of an attempt made to 1091 obtain a general license or permission for the use of such 1092 proprietary rights by implementors or users of this specification can 1093 be obtained from the IETF Secretariat. 1095 The IETF invites any interested party to bring to its attention any 1096 copyrights, patents or patent applications, or other proprietary 1097 rights which may cover technology that may be required to practice 1098 this standard. Please address the information to the IETF Executive 1099 Director. 1101 18. Copyright Notice 1103 Copyright (C) The Internet Society (2003). All Rights Reserved. 1105 This document and translations of it may be copied and furnished to 1106 others, and derivative works that comment on or otherwise explain it 1107 or assist in its implementation may be prepared, copied, published 1108 and distributed, in whole or in part, without restriction of any 1109 kind, provided that the above copyright notice and this paragraph are 1110 included on all such copies and derivative works. However, this 1111 document itself may not be modified in any way, such as by removing 1112 the copyright notice or references to the Internet Society or other 1113 Internet organizations, except as needed for the purpose of 1114 developing Internet standards in which case the procedures for 1115 copyrights defined in the Internet Standards process must be 1116 followed, or as required to translate it into languages other than 1117 English. 1119 The limited permissions granted above are perpetual and will not be 1120 revoked by the Internet Society or its successors or assigns. 1122 This document and the information contained herein is provided on an 1123 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1124 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1125 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1126 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1127 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.