idnits 2.17.1 draft-benjamin-extendedcallbackinfo-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 3) being 154 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Unrecognized Status in 'Intended status: Informational ', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document date (December 10, 2011) is 4513 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) -- Looks like a reference, but probably isn't: 'StoreData' on line 1642 == Unused Reference: '1' is defined on line 1730, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 1742, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 3530 (ref. '4') (Obsoleted by RFC 7530) -- Possible downref: Non-RFC (?) normative reference: ref. '5' -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' -- Possible downref: Non-RFC (?) normative reference: ref. '8' -- Possible downref: Non-RFC (?) normative reference: ref. '9' Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Matt Benjamin 2 Internet-Draft Linux Box Corporation 3 Intended status: Informational December 10, 2011 4 Expires: June 10, 2012 6 AFS Callback Extensions (Draft 14) 8 draft-benjamin-extendedcallbackinfo-02 10 Abstract 12 AFS cache-control strategy is callback (invalidate) based. The 13 AFS callback design allows a client to know when an object it 14 has cached is no longer consistent, but the callback 15 notification message itself provides no specific information 16 about the triggering event. This is a protocol inefficiency, as 17 in several scenarios it results in unnecessary round-trips to 18 file servers to verify file status information, file access 19 information, or to fetch file data which has not changed. We 20 propose an extension of the callback mechanism to provide 21 information about the event(s) triggering a callback, in the 22 payload of the callback notification message itself. The 23 proposed mechanism eliminates most or all unnecessary 24 round-trips imposed by the current callback mechanism, and 25 simultaneously allows AFS implementations to (efficiently) 26 provide correct semantics in several scenarios involving 27 multiple writers (ie, where AFS currently provides incorrect 28 semantics). 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet 36 Engineering Task Force (IETF), its areas, and its working 37 groups. Note that other groups may also distribute working 38 documents as Internet-Drafts. 40 Internet-Drafts are draft documents valid for a maximum of six 41 months and may be updated, replaced, or obsoleted by other 42 documents at any time. It is inappropriate to use 43 Internet-Drafts as reference material or to cite them other 44 than as "work in progress." 45 The list of current Internet-Drafts can be accessed at 46 http://www.ietf.org/1id-abstracts.html 48 The list of Internet-Draft Shadow Directories can be accessed 49 at http://www.ietf.org/shadow.html 51 Copyright Notice 53 Copyright (c) 2011 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with 61 respect to this document. 63 Table of Contents 65 Abstract 66 Status of this Memo 67 Copyright Notice 68 1 Introduction 69 2 Conventions Used in this Document 70 3 The AFS Callback Mechanism 71 3.1 Description 72 3.2 Analysis 73 4 Extended Callback Interface 74 4.1 Backward Compatibility 75 4.2 Interface Changes 76 4.2.1 Procedures 77 4.2.2 Constants 78 All Sequences 79 AFSXCBInvocation 80 AFSExtendedCallBack 81 AFSXCBRInvocation 82 AFSExtendedCallBackResult 83 Sequence Types 84 4.2.3 Data Types 85 HostIdentifier 86 AFSXCBInvocation 87 Fid 88 Flags 89 lowDV 90 highDV 91 ExpirationTime 92 CallBacks_Array 93 AFSExtendedCallBack 94 Flags and ExtraFlags 95 Origin 96 NCoalesced 97 DataVersion 98 Data 99 AFSXCBRInvocation 100 AFSExtendedCallBackResult 101 AFSCBFileStatus 102 AFSCBDirStatus 103 AFSCB_NotificationData 104 4.3 Semantic Changes 105 4.3.1 DataVersion Rule 106 4.3.2 Callback Synchrony and Callback Bracketing 107 4.3.3 Callback Workload Considerations 108 4.4 Callback Invocations 109 4.4.1 AFSXCBInvocation 110 Origin 111 ExpirationTime 112 4.4.2 AFSExtendedCallBack 113 Flags 114 ExtraFlags 115 DataVersion 116 Data 117 4.4.3 AFSXCBRInvocation 118 Xcb_Result_Array 119 4.4.4 AFSExtendedCallBackResult 120 Flags 121 ExtraFlags 122 Data 123 4.4.5 ExtendedCallBack Procedure 124 4.4.6 Callback Coalescing 125 Call Consolidation (Sequences of Notifications) 126 Coalescing of Equivalent Notifications 127 Implementation Note 128 4.4.7 AFSCB_Event_Cancel 129 Reasons for Cancellation 130 AFSCB_Cancel_Shutdown 131 AFSCB_Cancel_CallbackGC 132 AFSCB_Cancel_VolumeOffline 133 AFSCB_Cancel_VolumeMoved 134 AFSCB_Cancel_LostMyMind 135 AFSCB_Cancel_IHateYou 136 4.4.8 AFSCB_Event_StoreData 137 4.4.9 AFSCB_Event_StoreACL 138 4.4.10 AFSCB_Event_StoreStatus 139 4.4.11 AFSCB_Event_CreateFile 140 4.4.12 AFSCB_Event_MakeDir 141 4.4.13 AFSCB_Data_Symlink 142 4.4.14 AFSCB_Event_Link 143 4.4.15 AFSCB_Event_RemoveFile 144 4.4.16 AFSCB_Event_RemoveDir 145 4.4.17 AFSCB_Event_Rename 146 4.4.18 AFSCB_Event_Deleted 147 4.4.19 AFSCB_Event_ReleaseLock 148 4.5 Callbacks And Read-Only Volume Replicas 149 4.5.1 Constants 150 AFSCB_Flag_Release 151 AFSCB_IFlag_Release 152 AFSCB_Release_WholeVolumeCancel 153 4.5.2 Semantic Changes 154 5 Security Considerations 155 Edinburgh Consensus 156 6 IANA Considerations 157 7 Acknowledgements 158 8 Appendix A: XDR Grammar 159 9 Informative References 160 Author's Address 162 1 Introduction 164 The AFS protocol provides a comprehensive framework for 165 scalable, secure, wide-area file sharing over IP networks. The 166 AFS system has historically distinguished itself through its 167 emphasis on client-side caching[3, 7]. File data, file and 168 directory metadata, and access control information may all be 169 cached. Cache consistency is maintained through client 170 registration and an associated asynchronous notification 171 mechanism known as the callback. 173 The current AFS consistency model (which is of larger scope 174 than the callback mechanism, eg, it includes AFS sync-on-close 175 semantics) has allowed AFS to scale to large numbers of clients 176 (tens of thousands today), and to perform well under the 177 workloads for which AFS was originally designed. 179 However, AFS does not perform efficiently under other 180 conditions, such as when more than one client is interested in 181 a file which is changing--even if the file has only one writer, 182 and many readers[footnote: 183 NFSv4.1 in particular efficiently supports this scenario with 184 byte-range delegation, see[9]. 185 ]. In general, the AFS protocol arguably (still, considering 186 improvements made between AFS-2 and AFS-3) places too little 187 emphasis on efficient caching of mutable data. The current AFS 188 consistency model is insufficient to correctly support 189 single-file, multiple-writer scenarios, including those 190 required for POSIX semantics, and therefore is insufficient to 191 support many applications which may be run correctly on 192 competing distributed file systems (e.g., CIFS, Novell Netware, 193 or NFSv4). 195 The efficiency of the current AFS cache management algorithm 196 can be substantially improved if specific triggering event 197 information and current status are included in the payload of 198 the callback notifications sent to clients. In particular, 199 inclusion of the current DataVersion number and affected byte 200 ranges in response to StoreData operations significantly 201 reduces the need for cache revalidation and reconstruction 202 traffic in response to callbacks--in many cases, altogether. 203 These changes allow efficient support for single-writer updates 204 on a file with multiple readers. More importantly, they permit 205 AFS to correctly and efficiently support multiple writers 206 updating disjoint ranges on a single file, a prerequisite for 207 supporting granular file locking (and applications which 208 require it) in future. 210 2 Conventions Used in this Document 212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 213 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 214 "OPTIONAL" in this document are to be interpreted as described 215 in RFC 2119. 217 3 The AFS Callback Mechanism 219 3.1 Description 221 When an AFS-3 client contacts a file server to perform any of 222 several operations on a file, or explicitly to fetch its 223 status, the file server includes in its RPC response an 224 AFSCallBack structure, representing the server's promise to 225 call back the client "if any modifications are made to the data 226 in the file." (A key paper on AFS-2 has "before allowing a 227 modification by any other workstation".) The AFSCallBack 228 structure contains the callback expiration time, and two integer 229 values treated as invariants. 231 When any client executes an operation which would change a file 232 (e.g., StoreData), and in a variety of other situations, the 233 file server invalidates the client's cached copy by executing a 234 call to the CallBack procedure in the client's RPC interface. (The 235 call includes in its arguments an AFSCallBack structure for each file 236 being invalidated. However, the value of the passed AFSCallBack is 237 unused [e.g., afs/afs_callback.c:643 ff., openafs-1.5.54]). 238 Between the time of issue and either expiry or receipt of a 239 callback, the client may consider any information it has cached 240 on a file to be consistent with the file server's on-disk copy. 241 Conversely, on receipt of a callback, the client must consider 242 that it knows nothing about the file. Thus the client must 243 re-establish a relationship with the file at the file server 244 before executing any further operations on it. 246 The AFS callback mechanism obviates the need for clients to 247 send frequent cache validation requests before performing 248 operations on their locally cached copies of objects, reducing 249 network traffic as well as file server workload[3, 7]. The 250 callback innovation has been since taken up, with variations, 251 by other distributed file system protocols[4, 6]. 253 3.2 Analysis 255 The AFS callback mechanism reliably notifies clients when 256 information they may have cached becomes invalidated, but omits 257 to send information it trivially knows, ie, the triggering 258 event, that could certainly be used by the client to more 259 efficiently manage cache state. 261 For example, consider the case where 2 clients A and B are 262 interested in a file F, each having read chunks 1-15 into 263 cache. Now another client C initiates a change in the file, 264 writing a new state to chunk 45. This event increments the 265 dataversion of the file, and triggers a callback to A and B. 266 (C, because it initiated the change, is not called back.) On 267 receipt of the callback, A and B must issue FetchStatus 268 requests on F to acquire its current status information, 269 including its current data version. Since the data version of F 270 has increased, any chunks of F which A or B has cached are 271 invalidated, including 30 chunks correctly cached. Should A or 272 B remain interested, it must refetch these chunks (up to 2 273 megabytes of data, in this case). This scenario will occur 274 reasonably often in environments where mutable data is common, 275 and a related scenario involving directory entries (omitted for 276 brevity) is much more common. In these cases, an AFS callback 277 mechanism capable of sending triggering event information with 278 the callback would have facilitated a more efficient result, at 279 small marginal cost. In another set of scenarios where a client 280 A has changed data in a file invalidated by non-overlapping 281 stores by B, a revised mechanism would be capable of delivering 282 a correct result, whereas a correct result would be impossible 283 with the mechanism in AFS today. (In the AFS-3 callback model, 284 either As or Bs changes must be rejected. In the extended 285 callback model, the range-based invalidate mechanism means that 286 As and Bs changes will be merged, as they are disjoint.) 288 The justification for sending minimal information with the 289 callback is presumably to minimize the execution cost of the 290 callback procedure. The increased cost of sending a limited but 291 informative callback notification to clients, relative to 292 sending an uninformative one, is small. Analysis of the OpenAFS 293 file server code reveals that the file server always has the 294 information that would logically be sent as extended callback 295 information in response to file operations (e.g., file ranges 296 affected by StoreData operations, or changed entries for 297 various directory modification operations). 299 For these reasons, enhancement of the AFS callback interface to 300 supply triggering event information seems likely to improve 301 both correctness and performance of AFS implementations, and 302 experimental implementation and profiling appear justified. 304 4 Extended Callback Interface 306 4.1 Backward Compatibility 308 AFS clients will indicate their preference to receive extended 309 callback notifications through a new client capability flag: 311 const CLIENT_CAPABILITY_EXT_CALLBACK = 0x0002; 313 4.2 Interface Changes 315 4.2.1 Procedures 317 We propose a new procedure ExtendedCallBack in the client's RPC 318 interface. The ExtendedCallBack procedure arguments consist of 319 a HostIdentifier containing the UUIDs of the sending fileserver 320 and of its cell, and a (variable-length) sequence of 321 AFSXCBInvocation structures. And AFSXCBInvocation represents a 322 (variable-length) sequence of AFSExtendedCallBack events on one 323 AFSFid at Server. One invocation of the ExtendedCallBack 324 procedure can thus deliver up to AFSXCBMAX event notifications 325 on each of up to AFSXCBMAX fids. An OUT-direction sequence of 326 variant AFSExtendedCallBackResult structures is added for 327 future callback notification styles (e.g., locks, delegations) 328 which may return structured data on receipt of notifications: 330 proc ExtendedCallBack( 332 IN HostIdentifier *Server, 334 AFSXCBInvocationSeq *Invocations_Array, 336 OUT AFSXCBRInvocationSeq *Result_Array 338 ) multi = 65540; 340 4.2.2 Constants 342 All Sequences 344 The AFSXCBMAX constant is the maximum allowed length for 345 AFSXCBInvocation and AFSExtendedCallBack sequences: 347 const AFSXCBMAX = 512; 349 AFSXCBInvocation 351 As detailed in section [sub:Data-Types], an AFSXCBInvocation is 352 a structure representing a sequence of XCB events on one Fid. 353 The following constants are flag values are used as flag values 354 on AFSXCBInvocation instances: 356 const AFSCB_IFlag_SOrigin = 1; /* callbacks on this invocation 357 have a single origin host */ 359 const AFSCB_IFlag_Release = 2; /* this invocation was triggered 360 by a volume release */ 362 AFSExtendedCallBack 364 As detailed in section [sub:Data-Types], an AFSExtendedCallBack 365 is a structure representing an XCB event, and is principally 366 constituted by an instance of an XDR union, discriminated on 367 the callback event type. The following callback event types are 368 defined: 370 const AFSCB_Event_Cancel = 1; /* extended break callback */ 372 const AFSCB_Event_StoreData = 2; /* data in file changed */ 374 const AFSCB_Event_StoreACL = 3; /* ACL changed on vnode */ 376 const AFSCB_Event_StoreStatus = 4; /* status stored on vnode */ 378 const AFSCB_Event_CreateFile = 5; /* file created in directory 379 vnode */ 381 const AFSCB_Event_MakeDir = 6; /* dir created in directory 382 vnode */ 384 const AFSCB_Event_Symlink = 7; /* symlink created in directory 385 vnode */ 387 const AFSCB_Event_Link = 8; /* hard link created in directory 388 vnode */ 390 const AFSCB_Event_RemoveFile = 9; /* file removd from directory 391 vnode */ 393 const AFSCB_Event_RemoveDir = 10; /* dir removed from directory 394 vnode */ 395 const AFSCB_Event_Rename = 11; /* object renamed (moved) */ 397 const AFSCB_Event_Deleted = 12; /* object no longer exists, ex 398 object */ 400 const AFSCB_Event_ReleaseLock = 13; /* traditional AFS lock 401 released */ 403 A flag constant is provided to indicate callback cancellation 404 along with an extended notification message of any of the above 405 types: 407 const AFSCB_Flag_Cancel = 1; /* Callback promise is cancelled 408 */ 410 The following constants indicate reasons for cancellation, when 411 (Flags & AFSCB_Flag_Cancel): 413 const AFSCB_Cancel_Shutdown = 1; 415 const AFSCB_Cancel_CallbackGC = 2; 417 const AFSCB_Cancel_VolumeOffline = 3; 419 const AFSCB_Cancel_VolumeMoved = 4; 421 const AFSCB_Cancel_LostMyMind = 5; 423 const AFSCB_Cancel_IHateYou = 6; 425 The following flag constants (Flags) indicate the beginning or 426 end of a callback bracketing sequence (each is orthogonal to 427 each other and to AFSCB_Flag_Cancel): 429 const AFSCB_Flag_OpenBracket = 2; /* Callback syncrhony is 430 interrupted */ 432 const AFSCB_Flag_CloseBracket = 4; /* Callback syncrhony is 433 restored */ 435 The following constants indicate direction (from or to called 436 back FID) in the atomic AFSCB_Event_Rename notification: 438 const AFSCB_Rename_From = 1; 440 const AFSCB_Rename_To = 2; 442 AFSXCBRInvocation 443 As detailed in section [sub:Data-Types], an AFSRXCBInvocation 444 is a structure representing the sequence of results of XCB 445 events delivered in one AFSXCBInvocation. 447 AFSExtendedCallBackResult 449 As detailed in section [sub:Data-Types], an 450 AFSExtendedCallBackResult is a structure describing the result 451 of an XCB event. The following constants a provided as 452 descriminator for the AFSCB_ResultData union: 454 const AFSCB_Result_NoResult = 1; 456 const AFSCB_Result_Diag = 2; 458 const AFSCB_Result_Generic = 3; /* all currently defined 459 messages */ 461 Sequence Types 463 The following sequences are defined, and are used to construct 464 the input and output arguments for the ExtendedCallBack 465 procedure: 467 typedef AFSXCBInvocation AFSXCBInvocationSeq; 469 typedef AFSExtendedCallBack AFSExtendedCallBackSeq; 471 typedef AFSXCBRInvocation AFSXCBRInvocationSeq; 473 typedef AFSExtendedCallBackResult 474 AFSExtendedCallBackRSeq; 476 4.2.3 Data Types 478 HostIdentifier 480 A HostIdentifier structure contains the unique server and cell 481 UUIDs of a specific host in some AFS cell. 483 struct HostIdentifier { 485 afsUUID ServerUuid; 487 afsUUID CellUuid; 489 }; 491 AFSXCBInvocation 492 The AFSXCBInvocation data type represents a sequence of 0 or 493 more callback events on one fid. The enclosed 494 AFSExtendedCallBack objects MUST be in DataVersion order. 496 Fid 498 Fid is the fid object of the callback sequence. 500 Flags 502 Flags provide specializing information about the invocation. 504 lowDV 506 The lowest data version of Fid at all events in the sequence. 508 highDV 510 The highest data version of Fid at all events in the sequence. 512 ExpirationTime 514 ExpirationTime indicates a new expiration time for the 515 receiving client's callback on fid. And ExpirationTime of 0 516 indicates no change in ExpirationTime. 518 CallBacks_Array 520 A sequence of 0 or more AFSExtendedCallBack notifications on 521 FID. 523 struct AFSXCBInvocation { 525 AFSFid Fid; 527 afs_uint32 Flags; 529 afs_uint64 lowDV; /* lowest DV at invocation */ 531 AFSTimestamp highDV; /* highest */ 533 AFSTimestamp ExpirationTime; /* new expiration, or 0 if 534 unchanged */ 536 AFSExtendedCallBackSeq CallBacks_Array; 538 }; 540 AFSExtendedCallBack 541 The AFSExtendedCallBack data type represents a single callback 542 event on some fid, that of its containing AFSXCBInvocation when 543 sent with an ExtendedCallBack RPC. 545 Flags and ExtraFlags 547 Flags and ExtraFlags (added for future expansion) provide 548 possibly event-specific information. 550 Origin 552 Origin is the AFS UUID of the host or server which originated 553 the event, ie, the client whose operation on fid triggered some 554 event, in the typical case. If the origin is unknown to the 555 server or would not be meaningful, it MAY send the null UUID. 557 NCoalesced 559 As specified later in this document, certain operations (ie, 560 StoreData, StoreStatus) MAY be regarded by the file server as 561 idempotent and sent as one callback. NCoalesced indicates the 562 number of equivalent or combined operations coalesced on the 563 event, or 0 if the event is singular. 565 DataVersion 567 DataVersion is the (possibly updated) data version of fid at 568 the completion of the operation which triggered the event. 569 Considering coalescing, DataVersion is the data version at the 570 completion of the first event in the coalesced sequence. 572 Data 574 Data is an object of the discriminated union type 575 AFSCB_NotificationData: 577 struct AFSExtendedCallBack { 579 afs_uint32 Flags; 581 afs_uint32 ExtraFlags; 583 afsUUID Origin; /* originator of changes */ 585 afs_uint32 NCoalesced; /* calls combined on this */ 587 afs_uint64 DataVersion; 589 AFSCB_NotificationData Data; 590 }; 592 A non-zero value in Flags for the AFSCB_Flag_Cancel bit 593 indicates cancellation of the callback upon receipt of the 594 message. In that event, a non-zero value of ExtraFlags 595 indicates the reason for the cancellation. 597 AFSXCBRInvocation 599 An AFSXCBRInvocation is a structure describing the result of an 600 XCB invocation (a sequence of extended callback events at one 601 Fid). 603 struct AFSXCBRInvocation { 605 AFSExtendedCallBackRSeq Xcb_Result_Array; 607 }; 609 AFSExtendedCallBackResult 611 An AFSExtendedCallBackResult is a structure describing the 612 result of a single XCB event. 614 struct AFSExtendedCallBackResult { 616 afs_uint32 Flags; 618 afs_uint32 ExtraFlags; 620 AFSCB_ResultData Data; 622 }; 624 AFSCBFileStatus 626 The AFSCBFileStatus structure is a reduced-footprint 627 AFSFetchStatus replacement intended to communicate changed 628 vnode information in response to StoreData operations: 630 struct AFSCBFileStatus { 632 afs_uint32 LinkCount; 634 afs_uint64 ClientModTime; 636 }; 638 AFSCBDirStatus 639 The AFSCBDirStatus structure is a reduced-footprint 640 AFSFetchStatus replacement intended to communicate changed 641 vnode information in response to directory change operations: 643 struct AFSCBDirStatus { 645 afs_uint32 LinkCount; 647 afs_uint64 ClientModTime; 649 }; 651 AFSCB_NotificationData 653 AFSCB_NotificationData is a union discriminated by callback 654 event type, ie, its value may be any of the constants defined 655 in section [sub:Constants]. 657 ext-union AFSCB_NotificationData switch (afs_uint32 Event_Type) 658 { 660 case AFSCB_Event_StoreData: 662 AFSCB_Data_StoreData u_store_data; 664 case AFSCB_Event_StoreACL: 666 void; 668 case AFSCB_Event_StoreStatus: 670 AFSCB_Data_StoreStatus u_store_status; 672 case AFSCB_Event_CreateFile: 674 AFSCB_Data_CreateFile u_create_file; 676 case AFSCB_Event_MakeDir: 678 AFSCB_Data_MakeDir u_make_dir; 680 case AFSCB_Event_Symlink: 682 AFSCB_Data_Symlink u_symlink; 684 case AFSCB_Event_Link: 686 AFSCB_Data_Link u_link; 687 case AFSCB_Event_RemoveFile: 689 AFSCB_Data_RemoveFile u_remove_file; 691 case AFSCB_Event_RemoveDir: 693 AFSCB_Data_RemoveDir u_remove_dir; 695 case AFSCB_Event_Rename: 697 AFSCB_Data_Rename u_rename; 699 case AFSCB_Event_Deleted: 701 void; 703 case AFSCB_Event_ReleaseLock: 705 AFSCB_Data_Lock u_lock; 707 case AFSCB_Event_Cancel: 709 void; 711 }; 713 The types for the variant member u_data are enumerated and 714 discussed in detail in section [sub:Callback-Invocations]. 716 4.3 Semantic Changes 718 A file server MAY send traditional callback messages, with 719 traditional semantics, to any AFS client in response to any 720 event. A file server MAY send extended callback notifications 721 to any client which has announced the capability to use the 722 extended interface, with the following semantics: 724 * extended callback notification messages, in general, preserve 725 the file server's callback promise to send further 726 notifications for the called-back FID 728 * the file server MAY cancel a client's registration (callback 729 promise) with any extended callback notification message, by 730 setting AFSCB_Flag_Cancel in the Flags member of the 731 AFSExtendedCallBack structure 733 * the AFSCB_Event_Cancel message is similar to a traditional 734 AFS callback, breaking the callback promise, and requesting 735 the client not request further status on the FID 736 * the file server MAY suspend its obligation to deliver 737 callback notifications synchronously without revoking an 738 object's registration, by setting AFSCB_Flag_OpenBracket in 739 the Flags member of the AFSExtendedCallBack structure 741 * a file server which as previously suspended synchronous 742 notification on an object (with AFSCB_Flag_OpenBracket) MAY 743 restore it by sending AFSCB_Flag_CloseBracket in Flags in a 744 subsequent message 746 * callback bracketing, if enabled, terminates automatically 747 on ordinary cancellation or expiration of the corresponding 748 callback registration 750 4.3.1 DataVersion Rule 752 The various extended callback notification messages include 753 information a client may use to selectively invalidate or 754 reconstruct its cache. In interpreting each message, the client 755 MUST observe the dataversion rule, which states: 757 If the client's cached DataVersion is DataVersion or 758 (DataVersion-1), the client MAY invalidate or update its cache 759 using the type-dependent information contained in the message. 760 In all other cases, the client MUST regard the message as 761 equivalent to a traditional AFS callback. 763 The semantics of specific callback events are enumerated in 764 section [sub:Callback-Invocations]. 766 4.3.2 Callback Synchrony and Callback Bracketing 768 The AFS prototol regards client data and metadata operations as 769 atomic and synchronous. A legacy AFS callback registration 770 establishes a domain of synchrony between the registering file 771 server(s) and each registered client. A client operating on any 772 object in the file server interface is assured that each 773 eligible client has been notified of its operation when the 774 operation completes. 776 The extended callback mechanism carries forward these semantics 777 in full, with the following modification, referred to as 778 callback bracketing: A synchronous notification may suspend the 779 sending server's obligation to deliver synchronous 780 notifications without otherwise removing the receiving client's 781 registration on a Fid. The motivation for callback bracketing 782 is to permit more efficient processing of sequential operations 783 at one or several clients, through callback coalescing, without 784 violating any client's expectation of synchrony. Since an 785 AFSCB_Flag_OpenBracket indication is delivered synchronously to 786 any client which would be assured to receive an ordinary legacy 787 or extended callback notification with synchrony, in any 788 circumstance in which a server would be obligated to send 789 callback breaks or notifications, the callback bracketing 790 mechanism does not violate any client's expectation of 791 synchrony. 793 4.3.3 Callback Workload Considerations 795 The preference to preserve the fileserver's callback promises 796 to clients across file operations is a significant behavioral 797 change. In particular, file servers configured with traditional 798 small callback databases may be vulnerable to callback 799 exhaustion, which in turn may lead to thrashing or other 800 undesirable behavior. Sites are recommended to explicitly 801 increase provisioned callbacks, likely to at least 1 million. 802 The OpenAFS viced implementation will increase the number of 803 callbacks in the "large" configuration (-L) to a new, large 804 value. In general, a file server is expected take appropriate 805 action to shed workload (e.g., break callbacks) whenever 806 appropriate. 808 4.4 Callback Invocations 810 The various extended callback notification types generally 811 respond to specific events at the file server, but present a 812 view of it relevant to a specific callback promise at one 813 client. In one case (ie, AFSCB_Event_Rename), the file server 814 is sending notification of an event which effects two FIDs, 815 either or both of which may be cached by the receiving client. 816 A structure of type AFSExtendedCallBack is sent with each 817 extended callback notification message, as noted above. Unless 818 otherwise noted, FID is the FID of the object that is the 819 subject of the callback. 821 4.4.1 AFSXCBInvocation 823 Origin 825 A file server MAY omit to send extended callback notifications 826 triggered by a file operation to the client host which 827 originated the change. (Omission to send such callbacks has 828 been the general behavior of AFS file servers.) A client MUST 829 be prepared to appropriately process (or ignore) callbacks for 830 which its own UUID is the Origin. 832 ExpirationTime 834 The new expiration time asserted for the server's callback 835 promise, not necessarily different from the existing expiration 836 cached by the client. 838 4.4.2 AFSExtendedCallBack 840 The members of the AFSExtendedCallBack structures are to be 841 interpreted as follows: 843 Flags 845 If AFSCB_Flag_Cancel is set, the notification effects a 846 callback break. The client may make use of the information sent 847 with the message. If AFSCB_Flag_OpenBracket is set, the 848 notification (if actionable with respect to DataVersion) 849 suspends the server's obligation to send synchronous 850 notifications on FID. The client may make use of the 851 information sent with the message. The new state persists until 852 restored by a subsequent AFSCB_Flag_OpenBracket notification or 853 client-initiated callback-granting operation. 855 ExtraFlags 857 If (Flags & AFSCB_Flag_Cancel), a non-zero value for ExtraFlags 858 indicates the reason for cancellation. 860 DataVersion 862 The value of DataVersion at completion of the event of which 863 the client is being notified. Considering coalescing, the new 864 data version after completion of all events summarized at this 865 callback is (DataVersion+NCoalesced). 867 Data 869 The message-specific data for this notification. 871 4.4.3 AFSXCBRInvocation 873 The AFSXCBRInvocation structure contains only an array of 874 AFSExtendedCallBackResult. 876 Xcb_Result_Array 878 A sequence of AFSExtendedCallBackResult objects dimensioned by 879 the matching Callbacks_Array argument of an ExtendedCallBack 880 invocation. 882 4.4.4 AFSExtendedCallBackResult 884 An AFSExtendedCallBackResult is a structure describing the 885 result of a single XCB event. 887 Flags 889 Provided for future extension. 891 ExtraFlags 892 Provided for future extension. 894 Data 896 The result, expressed as a union of nil, diagnostic/string, and 897 generic result types. The generic result type (or future 898 extension) should be used in general, as it allows for 899 per-message acknowledgement. 901 4.4.5 ExtendedCallBack Procedure 903 Extended callbacks are delivered through a new ExtendedCallBack 904 procedure. 906 proc ExtendedCallBack( 908 IN HostIdentifier *Server, 910 AFSXCBInvocationSeq *Invocations_Array, 912 OUT AFSXCBRInvocationSeq *Result_Array 914 ) multi = 65540; 916 ExtendedCallBack provides for flexible event notification, 917 including bulk notification support by Fid and per Fid, 918 supports per-message acknowledgement, and uniquely identifies 919 the issuing server host. 921 4.4.6 Callback Coalescing 923 A server implementation MAY coalesce sequences of 924 effectively-simultaneous notifications to a single client, in 925 accordance with rules of composition of specific notifications, 926 and provided doing so would not violate any client's 927 expectation of synchrony. 929 Call Consolidation (Sequences of Notifications) 931 A server implementation MAY coalesce any sequence of 932 effectively simultaneous notifications into sequences of 933 AFSExtendedCallBack objects enclosed in one AFSXCBInvocation 934 object, provided doing so would not violate any client's 935 expectation of synchrony. Any number of such callbacks may be 936 combined, up to the limit of AFSXCBMAX. 938 Coalescing of Equivalent Notifications 940 A server implementation MAY coalesce a sequence of effectively 941 simultaneous and equivalent notifications to the same client 942 into a single callback in a notification message, provided 943 doing so would not violate any client's expectation of 944 synchrony. The following combinations of operations are 945 explicitly permitted: 947 * sequences of AFSCB_EventStoreAcl notifications on FID from a 948 single Origin MAY be delivered as a single notification 950 * sequences of AFSCB_EventStoreStatus notifications on FID from 951 a single Origin MAY be delivered as the single notification 952 of the most recently stored status 954 * sequences of AFSCB_Event_StoreData notifications on FID from 955 a single Origin at adjacent or overlapping byte ranges MAY 956 deliver a single notification at the consolidated range 958 Implementation Note 960 "Effectively simultaneous" is left intentionally unspecified. 961 An adaptive window expanding from 100ms to a small number of 962 seconds appears to work well with commonly available switched 963 networks and multi-core fileservers, in 2008. The current 964 OpenAFS implementation uses an adaptive per-Fid window, which 965 extends on repeated events, and closes when client contention 966 is detected. Peer RTT or other considerations may be added to 967 the windowing algorithm in future. 969 4.4.7 AFSCB_Event_Cancel 971 The AFSCB_Event_Cancel notification indicates that the client's 972 callback promise on the corresponding Fid is cancelled. It is 973 therefore equivalent to a legacy AFS break call back 974 indication, but uses the extended interface. A cancel 975 indication may include an optional reason for cancellation in 976 the Flags member of the corresponding AFSExtendedCallBack 977 message. 979 Reasons for Cancellation 981 The following reasons for cancellation are defined: 983 AFSCB_Cancel_Shutdown 985 The server or service is shutting down. 987 AFSCB_Cancel_CallbackGC 989 Callback has been disposed during periodic garbage collection. 991 AFSCB_Cancel_VolumeOffline 993 The volume associated with FID is now offline. 995 AFSCB_Cancel_VolumeMoved 996 The volume associated with FID has moved. 998 AFSCB_Cancel_LostMyMind 1000 The server may be having problems related to provisioning an 1001 insufficient number of callback structures. 1003 AFSCB_Cancel_IHateYou 1005 Callback has been administratively revoked. 1007 4.4.8 AFSCB_Event_StoreData 1009 The notification is sent in response to a successful StoreData 1010 RPC on FID. A structure of type AFSCB_Data_StoreData is sent 1011 with the message. 1013 struct AFSCB_Data_StoreData { 1015 afs_uint64 StoreOffset; 1017 afs_uint64 StoreLength; 1019 afs_uint64 Length; 1021 AFSCBFileStatus FileStatus; 1023 }; 1025 StoreLength bytes were stored starting at position StoreOffset 1026 in FID. Length is the current file length and FileStatus 1027 contains the modification time of FID following the operation. 1028 The client must regard cached file data in the range 1029 [StoreOffset, StoreOffset+StoreLength) as invalidated, and may 1030 regard data outside that range as up-to-date. The client MUST 1031 discard undirtied cached data in the invalidated range. The 1032 client MAY send dirtied data in the invalidated range to the 1033 file server prior to discarding (as allowed in current AFS 1034 semantics). 1036 4.4.9 AFSCB_Event_StoreACL 1038 ACL and/or access information cached by the client for FID, if 1039 any, is invalidated. 1041 4.4.10 AFSCB_Event_StoreStatus 1043 A StoreStatus RPC was successfully executed on FID. A structure 1044 of type AFSFetchStatus is sent with the message. 1046 struct AFSCB_Data_StoreStatus { 1048 struct AFSFetchStatus Status; 1050 }; 1052 Status is the new AFSFetchStatus of FID, ie, the message 1053 communicates the current status information of FID.[footnote: 1054 This is changed from earlier drafts. 1055 ] 1057 4.4.11 AFSCB_Event_CreateFile 1059 A file has been created in the vnode corresponding to FID. A 1060 structure of type AFSCB_Data_CreateFile is sent with the 1061 message. 1063 struct AFSCB_Data_CreateFile { 1065 string Name; 1067 AFSFid Fid; 1069 AFSFetchStatus FidStatus; 1071 AFSCBDirStatus DirStatus; 1073 }; 1075 Name and Fid are, respectively, the name and FID of the created 1076 file. FidStatus is the AFSFetchStatus of the created file, and 1077 DirStatus the current modification time and link count of FID, 1078 at the completion of the call. 1080 4.4.12 AFSCB_Event_MakeDir 1082 A directory has been created in the vnode corresponding to FID. 1083 A structure of type AFSCB_Data_MakeDir is sent with the 1084 message. 1086 struct AFSCB_Data_MakeDir { 1088 string Name; 1090 AFSFid Fid; 1092 AFSFetchStatus FidStatus; 1094 AFSCBDirStatus DirStatus; 1096 };; 1097 Name and Fid are, respectively, the name and FID of the created 1098 directory. FidStatus is the AFSFetchStatus of the created 1099 directory, and DirStatus the current modification time and link 1100 count of FID, at the completion of the call. 1102 4.4.13 AFSCB_Data_Symlink 1104 A symbolic link has been created in the vnode corresponding to 1105 FID. A structure of type AFSCB_Data_Symlink is sent with the 1106 message. 1108 struct AFSCB_Data_Symlink { 1110 string Name; 1112 AFSFid Fid; 1114 string LinkContents; 1116 AFSFetchStatus FidStatus; 1118 AFSCBDirStatus DirStatus; 1120 }; 1122 Name is the name of the symbolic link. Fid is its AFSFid. The 1123 link points to LinkContents. FidStatus is the AFSFetchStatus of 1124 the created symbolic link, and DirStatus the current 1125 modification time and link count of FID, at the completion of 1126 the call. 1128 4.4.14 AFSCB_Event_Link 1130 A hard link has been created in the vnode corresponding to FID. 1131 A structure of type AFSCB_Data_Link is sent with the message. 1133 struct AFSCB_Data_Link { 1135 string Name; 1137 AFSFid LinkTarget; 1139 AFSFetchStatus FidStatus; 1141 AFSCBDirStatus DirStatus; 1143 }; 1145 Name is the name of the link. The link is a synonym for 1146 LinkTarget. FidStatus is the AFSFetchStatus of the created 1147 link, and DirStatus the current modification time and link 1148 count of FID, at the completion of the call. 1150 4.4.15 AFSCB_Event_RemoveFile 1152 A file has been removed from the vnode corresponding to FID. A 1153 structure of type AFSCB_Data_RemoveFile is sent with the 1154 message. 1156 struct AFSCB_Data_RemoveFile { 1158 string Name; 1160 AFSCBDirStatus DirStatus; 1162 }; 1164 Name indicates the removed entry. DirStatus the current 1165 modification time and link count of FID, at the completion of 1166 the call. 1168 4.4.16 AFSCB_Event_RemoveDir 1170 A directory has been removed from the vnode corresponding to 1171 FID. A structure of type AFSCB_Data_RemoveDir is sent with the 1172 message. 1174 struct AFSCB_Data_RemoveDir { 1176 string Name; 1178 AFSCBDirStatus DirStatus; 1180 }; 1182 Name indicates the removed entry. DirStatus the current 1183 modification time and link count of FID, at the completion of 1184 the call. 1186 4.4.17 AFSCB_Event_Rename 1188 A file or directory has been renamed, ie moved, from or to the 1189 vnode corresponding to FID. A structure of type 1190 AFSCB_Data_RemoveDir is sent with the message. 1192 const AFSCB_Rename_From = 1; 1194 const AFSCB_Rename_To = 2; 1196 struct AFSCB_Data_Rename { 1197 afs_uint32 Direction; 1199 string OldName; 1201 string NewName; 1203 AFSCBDirStatus FromStatus; 1205 AFSCBDirStatus ToStatus; 1207 }; 1209 Direction indicates whether FID is the source or the 1210 destination directory of the move. OldName is the name of the 1211 object in its old location, NewName the name of the object in 1212 its new location. FromStatus is the current modification time 1213 and link count of the source directory vnode, and ToStatus is 1214 the current modification time and link count of the destination 1215 directory vnode, and FidStatus the at the completion of the 1216 call. 1218 To preserve atomicity, the AFSCB_Data_Rename message is 1219 constructed so that changes to cached copies of both the source 1220 and directory vnodes may be recovered from a single 1221 notification. If a client owns callbacks for both the source 1222 and destination FIDs, a file server MAY elect to send only one 1223 notification, for either the source or the destination FID. 1225 4.4.18 AFSCB_Event_Deleted 1227 The object corresponding to FID not longer exists, and so may 1228 no longer be cached. It is an ex-object. (I.e., the client MUST 1229 discard any information it has cached about FID.) 1231 4.4.19 AFSCB_Event_ReleaseLock 1233 A traditional AFS whole-file lock has been released on FID. A 1234 structure of type AFSCB_Data_Lock is sent with the message. 1235 LockType is the type of the lock released. 1237 struct AFSCB_Data_Lock { 1239 afs_uint32 LockType; 1241 }; 1243 Receipt of an AFSCB_Event_ReleaseLock notification does not 1244 imply that a lock on FID will be immediately available to the 1245 receiving client (i.e., it is not a reservation). Non-receipt 1246 of a notification of this type does not imply non-release of 1247 locks that may be (may have been) held on FID. A file server 1248 SHOULD send notifications of this type only to clients which 1249 have indicated probable interest in the event, e.g., by having 1250 recently requested a lock on FID. 1252 4.5 Callbacks And Read-Only Volume Replicas 1254 Callbacks associated with read-only volume replicas have 1255 traditionally been handled specially in AFS. When any file in 1256 an RO volume is accessed the AFS file server establishes a 1257 single callback promise considered to be on the entire volume. 1258 Any event which updates the replica (e.g., vos release) 1259 triggers a whole-volume callback break. The whole-volume 1260 callback optimization significantly reduced file server memory 1261 utilization, which was at a premium in 1988. However, the 1262 whole-volume callback is less of an optimization in OpenAFS in 1263 2008: 1265 * modern AFS file servers have sufficient memory to track 1266 millions of callbacks (and do track up to 1 million callbacks 1267 at one site we know of, with up to 3 million callback 1268 structures available)[8] 1270 * whole-volume callback semantics require clients (and the file 1271 server) to potentially expend considerable effort 1272 re-establishing cache consistency, and so whole-volume 1273 callbacks are necessarily a considerable protocol 1274 inefficiency for sites relying heavily on AFS replication (in 1275 particular, incremental replication now possible in OpenAFS) 1277 For these reasons, we propose that the scope of extended 1278 callback information include notifications concerning changes 1279 that originate in the release of a volume. We provide the 1280 option for the file server to provide whole-volume or per file 1281 notifications, at its discretion. We provide the option for the 1282 file server to track client interest in specific files (ie, 1283 issue per-file callbacks on files in RO volumes), and speculate 1284 that this implementation would be preferred, but do not mandate 1285 it. 1287 4.5.1 Constants 1289 The following flag constants are added: 1291 const AFSCB_Flag_Release = 2; 1293 const AFSCB_IFlag_Release = 2; 1295 const AFSCB_Release_WholeVolumeCancel = 1; 1297 AFSCB_Flag_Release 1299 In an AFSExtendedCallBack instance, (Flags & 1300 AFSCB_Flag_Release) indicates a notification in response to the 1301 (possibly incremental) release of a read-only replica. 1303 AFSCB_IFlag_Release 1305 In an AFSXCBInvocation instance, (Flags & AFSCB_IFlag_Release) 1306 indicates a notification in response to the (possibly 1307 incremental) release of a read-only replica. 1309 AFSCB_Release_WholeVolumeCancel 1311 If additionally (ExtraFlags & AFSCB_Release_WholeVolumeCancel), 1312 then the callback invalidates the entire volume, otherwise it 1313 is a selective invalidation of just the FIDs in Fids_Array. 1315 4.5.2 Semantic Changes 1317 An AFS file server MAY send selective or whole-volume extended 1318 callback notifications. The file server MAY choose to regard 1319 files in RO volumes equivalently to files in RW volumes, ie, 1320 effectively maintain callback state on them. Alternatively it 1321 MAY send selective notifications on any FIDs changed, removed, 1322 or added in the volume without regard to client cache state. 1323 The AFS client must handle such notifications gracefully. 1325 5 Security Considerations 1327 Extended callback information messages that only invalidate 1328 information that may be cached at clients have equivalent 1329 security implications to AFS-3 callback messages. This class of 1330 messages includes AFSCB_Event_Cancel and probably 1331 AFSCB_Event_StoreData. The remaining extended callback 1332 information messages (most of them) contain explicit metadata 1333 information which could potentially be used by an attacker 1334 impersonating a file server to introduce malicious information 1335 into a client cache. Rx security extensions in development (eg, 1336 rxgk) include provisions for secure transmission of callback 1337 messages. 1339 Edinburgh Consensus 1341 Implementations should ensure that extended callbacks which 1342 send explicit metadata use a secure communication channel. 1343 Cancellation and StoreData messages may be sent over any 1344 channel. 1346 6 IANA Considerations 1348 This document makes no request of the IANA. 1350 7 Acknowledgements 1351 Thanks to Jeffrey Altman, Tom Keiser, Jeffrey Hutzelman, 1352 Derrick Brashear, and Steven Jenkins for their feedback and 1353 suggested improvements from previous drafts. Thanks to 1354 participants at the 2009 Hackathon in Edinburgh and 2011 1355 Hackathon in Pittsburgh for their feedback and assistance. 1357 8 Appendix A: XDR Grammar 1359 /* Cache Manager Capability Flags */ 1361 const CLIENT_CAPABILITY_EXT_CALLBACK = 0x0002; 1363 /* Host Tracking/Extended Information */ 1365 struct HostIdentifier { 1367 afsUUID ServerUuid; 1369 afsUUID CellUuid; 1371 }; 1373 /* Extended Callback Information */ 1375 /* callback event types, predominantly events on the vnode for 1377 * which the callback is being made, but also (e.g., Deleted) 1378 side 1380 * effects of operations on related vnodes */ 1382 const AFSCB_Event_Cancel = 1; 1384 const AFSCB_Event_StoreData = 2; 1386 const AFSCB_Event_StoreACL = 3; 1388 const AFSCB_Event_StoreStatus = 4; 1390 const AFSCB_Event_CreateFile = 5; 1392 const AFSCB_Event_MakeDir = 6; 1394 const AFSCB_Event_Symlink = 7; 1395 const AFSCB_Event_Link = 8; 1397 const AFSCB_Event_RemoveFile = 9; 1399 const AFSCB_Event_RemoveDir = 10; 1401 const AFSCB_Event_Rename = 11; 1403 const AFSCB_Event_Deleted = 12; 1405 const AFSCB_Event_ReleaseLock = 13; 1407 /* for use in AFSExtendedCallBack Flags */ 1409 const AFSCB_Flag_Cancel = 1; 1411 const AFSCB_Flag_Release = 2; 1413 /* intended for use in AFSExtendedCallBack ExtraFlags, 1415 * when (flags & AFSCB_Flag_Cancel), to indicate reason for 1417 * cancellation */ 1419 const AFSCB_Cancel_Shutdown = 1; 1421 const AFSCB_Cancel_CallbackGC = 2; 1423 const AFSCB_Cancel_VolumeOffline = 3; 1425 const AFSCB_Cancel_VolumeMoved = 4; 1427 const AFSCB_Cancel_LostMyMind = 5; /* ran out of callbacks? */ 1429 const AFSCB_Cancel_IHateYou = 6; /* callback administratively 1430 revoked */ 1432 /* for use in AFSXCBInvocation Flags */ 1434 const AFSCB_IFlag_SOrigin = 1; 1436 const AFSCB_IFlag_Release = 2; 1437 /* flags intended for use in AFSExtendedCallBack ExtraFlags 1439 * to indicate RO volume callback events */ 1441 const AFSCB_Release_WholeVolumeCancel = 1; 1443 /* callback result types */ 1445 const AFSCB_Result_NoResult = 1; 1447 const AFSCB_Result_Diag = 2; 1449 const AFSCB_Result_Generic = 3; /* all currently defined 1450 messages */ 1452 /* differential status to be sent with StoreData msgs */ 1454 struct AFSCBFileStatus { 1456 afs_uint32 LinkCount; 1458 afs_uint64 ClientModTime; 1460 }; 1462 /* differential status to be sent with directory change msgs */ 1464 struct AFSCBDirStatus { 1466 afs_uint32 LinkCount; 1468 afs_uint64 ClientModTime; 1470 }; 1472 /* variant data types for AFSCB_Notification_Data */ 1474 struct AFSCB_Data_StoreData { 1475 afs_uint64 StoreOffset; 1477 afs_uint64 StoreLength; 1479 afs_uint64 Length; 1481 AFSCBFileStatus FileStatus; 1483 }; 1485 struct AFSCB_Data_StoreStatus { 1487 struct AFSFetchStatus Status; 1489 }; 1491 struct AFSCB_Data_CreateFile { 1493 string Name; 1495 AFSFid Fid; 1497 AFSFetchStatus FidStatus; 1499 AFSCBDirStatus DirStatus; 1501 }; 1503 struct AFSCB_Data_MakeDir { 1505 string Name; 1507 AFSFid Fid; 1509 AFSFetchStatus FidStatus; 1511 AFSCBDirStatus DirStatus; 1513 }; 1515 struct AFSCB_Data_Symlink { 1516 string Name; 1518 AFSFid Fid; 1520 string LinkContents; 1522 AFSFetchStatus FidStatus; 1524 AFSCBDirStatus DirStatus; 1526 }; 1528 struct AFSCB_Data_Link { 1530 string Name; 1532 AFSFid LinkTarget; 1534 AFSFetchStatus FidStatus; 1536 AFSCBDirStatus DirStatus; 1538 }; 1540 struct AFSCB_Data_RemoveFile { 1542 string Name; 1544 AFSCBDirStatus DirStatus; 1546 }; 1548 struct AFSCB_Data_RemoveDir { 1550 string Name; 1552 AFSCBDirStatus DirStatus; 1554 }; 1556 const AFSCB_Rename_From = 1; 1557 const AFSCB_Rename_To = 2; 1559 struct AFSCB_Data_Rename { 1561 afs_uint32 Direction; 1563 string OldName; 1565 string NewName; 1567 AFSCBDirStatus FromStatus; 1569 AFSCBDirStatus ToStatus; 1571 }; 1573 struct AFSCB_Data_Lock { 1575 afs_uint32 LockType; 1577 }; 1579 union AFSCB_NotificationData switch (afs_uint32 Event_Type) { 1581 case AFSCB_Event_StoreData: 1583 AFSCB_Data_StoreData u_store_data; 1585 case AFSCB_Event_StoreACL: 1587 void; 1589 case AFSCB_Event_StoreStatus: 1591 AFSCB_Data_StoreStatus u_store_status; 1593 case AFSCB_Event_CreateFile: 1595 AFSCB_Data_CreateFile u_create_file; 1597 case AFSCB_Event_MakeDir: 1599 AFSCB_Data_MakeDir u_make_dir; 1600 case AFSCB_Event_Symlink: 1602 AFSCB_Data_Symlink u_symlink; 1604 case AFSCB_Event_Link: 1606 AFSCB_Data_Link u_link; 1608 case AFSCB_Event_RemoveFile: 1610 AFSCB_Data_RemoveFile u_remove_file; 1612 case AFSCB_Event_RemoveDir: 1614 AFSCB_Data_RemoveDir u_remove_dir; 1616 case AFSCB_Event_Rename: 1618 AFSCB_Data_Rename u_rename; 1620 case AFSCB_Event_Deleted: 1622 void; 1624 case AFSCB_Event_ReleaseLock: 1626 AFSCB_Data_Lock u_lock; 1628 case AFSCB_Event_Cancel: 1630 void; 1632 }; 1634 struct AFSExtendedCallBack { 1636 afs_uint32 Flags; 1638 afs_uint32 ExtraFlags; 1640 afsUUID Origin; /* originator of changes */ 1642 afs_uint32 NCoalesced; /* calls [StoreData] combined on 1643 this */ 1645 afs_uint64 DataVersion; 1646 AFSCB_NotificationData Data; 1648 }; 1650 const AFSXCBMAX = 512; 1652 struct AFSXCBInvocation { 1654 AFSFid Fid; 1656 afs_uint32 Flags; 1658 afs_uint64 lowDV; /* lowest DV at invocation */ 1660 AFSTimestamp highDV; /* highest */ 1662 AFSTimestamp ExpirationTime; /* new expiration, or 0 if 1663 unchanged */ 1665 AFSExtendedCallBackSeq CallBacks_Array; 1667 }; 1669 typedef AFSExtendedCallBack AFSExtendedCallBackSeq; 1671 /* Forward-looking union for callback results */ 1673 struct AFSCB_Result_Data_Generic { 1675 afs_int32 code; 1677 }; 1679 union AFSCB_ResultData switch (afs_uint32 Result_Type) { 1681 case AFSCB_Result_NoResult: 1683 void; 1684 case AFSCB_Result_Diag: 1686 string msg<30>; 1688 case AFSCB_Result_Generic: 1690 AFSCB_Result_Data_Generic u_generic; 1692 }; 1694 /* extended callback result structure */ 1696 struct AFSExtendedCallBackResult { 1698 afs_uint32 Flags; 1700 afs_uint32 ExtraFlags; 1702 AFSCB_ResultData Data; 1704 }; 1706 typedef AFSExtendedCallBackResult 1707 AFSExtendedCallBackRSeq; 1709 struct AFSXCBRInvocation { 1711 AFSExtendedCallBackRSeq Xcb_Result_Array; 1713 }; 1715 typedef AFSXCBRInvocation AFSXCBRInvocationSeq; 1717 proc ExtendedCallBack( 1718 IN HostIdentifier *Server, 1720 AFSXCBInvocationSeq *Invocations_Array, 1722 OUT AFSXCBRInvocationSeq *Result_Array 1724 ) multi = 65540; 1726 9 Informative References 1728 References 1730 [1] Bradner, S., "Key words for use in RFCs to Indicate 1731 Requirement Levels", BCP 14, RFC 2119, March 1997. 1733 [3] Howard, J.H., Kazar, M.L., Menees, S.G., Nichols, D.A., 1734 Satyanarayanan, M., Sidebotham, R.N. and West, M. "Scale and 1735 Performance in a Distributed File System" ACM Transactions on 1736 Computer Systems, February 1988 1738 [4] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 1739 Beame, C., Eisler, M., and D. Noveck, "Network File System 1740 (NFS) version 4 Protocol", RFC 3530, April 2003. 1742 [5] Edward R Zayas, "AFS-3 Programmer's Reference: File 1743 Server/Cache Manager Interface", Transarc Corporation, 1744 FS-00-D162, 20th August 1991 1746 [6] Paul J. Leach, Dilip C. Naik. A Common Internet File System 1747 (CIFS/1.0) Protocol 1748 [http://www.tools.ietf.org/html/draft-leach-cifs-v1-spec-01], 1749 1997. 1751 [7] Kazar, Michael Leon, "Synchronization and Caching Issues in 1752 the Andrew File System," USENIX Conference Proceedings, USENIX 1753 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. 1755 [8] Alistair Ferguson. OpenAFS and the Dawn of a New Era. AFS 1756 and Kerberos Best Practices Workshop, 2008. 1758 [9] Trond Myklebust. Byte Range Delegations. 1759 [https://www3.ietf.org/proceedings/05nov/slides/nfsv4-3.pdf ], 1760 November 2006. 1762 Author's Address 1764 Matt Benjamin 1765 Linux Box Corporation 1766 206 S. Fifth Ave, Ste 150 1767 Ann Arbor, MI 48104 1768 USA 1769 Phone: +1 734 761 4689 1771 Email: matt@linuxbox.com