idnits 2.17.1 draft-haynes-nfsv4-delstid-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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: A change in the access time MUST not advance the change time, also known as the time_metadata attribute (see Section 5.8.2.42 of [RFC5661]), but a change in the modify time might advance the change time (and in turn the change attribute (See Section 5.8.1.4 of [RFC5661]). If the modify time is greater than the change time and before the current time, then the change time is adjusted to the modify time and not the current time (as is most likely done on most SETATTR calls that change the metadata). If the modify time is in the future, it will be clamped to the current time. -- The document date (July 25, 2019) is 1730 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'LEGAL' ** Downref: Normative reference to an Informational RFC: RFC 1813 ** Obsolete normative reference: RFC 5661 (Obsoleted by RFC 8881) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 T. Haynes 3 Internet-Draft T. Myklebust 4 Intended status: Standards Track Hammerspace 5 Expires: January 26, 2020 July 25, 2019 7 Extending the Opening of Files in NFSv4.2 8 draft-haynes-nfsv4-delstid-02.txt 10 Abstract 12 The Network File System v4 (NFSv4) allows a client to both open a 13 file and be granted a delegation of that file. This provides the 14 client the right to cache metadata on the file locally. This 15 document presents several refinements to both the opening and 16 delegating of the file to the client. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 26, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 2. Offline Files . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Determining the Arguments to OPEN . . . . . . . . . . . . . . 4 57 3.1. XDR Modifications to OPEN . . . . . . . . . . . . . . . . 5 58 4. Proxying of Times . . . . . . . . . . . . . . . . . . . . . . 7 59 4.1. Use case . . . . . . . . . . . . . . . . . . . . . . . . 8 60 4.2. XDR for Proxying of Times . . . . . . . . . . . . . . . . 9 61 5. Operation 77: LAYOUT_WCC - Layout Weak Cache Consistency . . 9 62 5.4. Allowed Errors . . . . . . . . . . . . . . . . . . . . . 11 63 5.5. Flex Files Layout Type . . . . . . . . . . . . . . . . . 11 64 6. Extraction of XDR . . . . . . . . . . . . . . . . . . . . . . 13 65 6.1. Code Components Licensing Notice . . . . . . . . . . . . 13 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 68 9. Normative References . . . . . . . . . . . . . . . . . . . . 14 69 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 14 70 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 14 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 73 1. Introduction 75 In the Network File System version4 (NFSv4) a client may be granted a 76 delegation for a file. This allows the client to act as the 77 authority of the file's metadata and data. In this document, we 78 introduce some new semantics to both the open and the delegation 79 process which allows the client to: 81 o detect an offline file, which may be located off premise. 83 o determine the extension of OPEN (see Section 18.16 of [RFC5661]) 84 flags. 86 o during the OPEN procedure, get either the open or delegation 87 stateids, but not both. 89 o cache both the access and modify times, reducing the number of 90 times the client needs to go to the server to get that 91 information. 93 o for clients using Parallel NFS (pNFS) (see Section 12 of 94 [RFC5661]), periodically report the attributes of the data files 95 to the metadata server. 97 Using the process detailed in [RFC8178], the revisions in this 98 document become an extension of NFSv4.2 [RFC7862]. They are built on 99 top of the external data representation (XDR) [RFC4506] generated 100 from [RFC7863]. 102 1.1. Definitions 104 delegation: A file delegation, which is a recall-able lock that 105 assures the holder that inconsistent opens and file changes cannot 106 occur so long as the delegation is held. 108 stateid: A stateid is a 128-bit quantity returned by a server that 109 uniquely defines state held by the server for the client. (See 110 Section 8 of [RFC5661]) 112 weak cache consistency (WCC): In NFSv3, operations are not sent in a 113 compound, hence the client would have to perform two round trips 114 to the server in order to determine the result of modification to 115 the state of a file or directory. With WCC, the server can return 116 post-operation attributes on such operations. As these do not 117 provide a strict consistency between the server and client, the 118 client is free to ignore the data. (See Section 2.6 of [RFC1813]) 120 1.2. Requirements Language 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 2. Offline Files 128 If a file is offline, then the server locally has the file's 129 attributes, but not the file's content. It has to be able to present 130 to the client enough information to describe the file, but the 131 content is not readily available. The cost of retrieving the data 132 content is expensive, to the extent that the content should only be 133 retrieved if it is going to be used. A graphical file manager (such 134 as OSX's Finder) may want to access the beginning of the file to 135 preview it for an user who is hovering his pointer over the file 136 name. If the file is retrieved, it will most likely either be 137 immediately thrown away or returned. 139 A compound with a GETATTR or READDIR can report the file's attributes 140 without bringing the file online. However, either an OPEN or a 141 LAYOUTGET might cause the file server to retrieve the archived data 142 contents, bringing the file online. For non-pNFS systems, the OPEN 143 operation requires a filehandle to the data content. For pNFS 144 systems, the filehandle retrieved from an OPEN need not cause the 145 data content to be retrieved. But when the LAYOUTGET operation is 146 processed, a layout type specific mapping will cause the data content 147 to be retrieved from offline storage. 149 If an operating system is not aware that the file is offline, it 150 might inadvertently open the file to determine what type of file it 151 is accessing. By adding the new attribute FATTR4_OFFLINE, a client 152 can predetermine the availability of the file, avoiding the need to 153 open it at all. Being offline might also mean that the file is 154 archived in the cloud, i.e., there can be an expense in both 155 retrieving the file to bring online and in sending the file back to 156 offline status. 158 160 /// 161 /// typedef bool fattr4_offline; 162 /// 164 /// 165 /// const FATTR4_OFFLINE = 83; 166 /// 168 170 3. Determining the Arguments to OPEN 172 The OPEN (See Section 18.16 of [RFC5661]) procedure returns an open 173 stateid to the client to reference the state of the file. The client 174 could also request a delegation stateid in the OPEN arguements. The 175 file is said to be "open" to the client as long as the count of open 176 and delegated stateids is greater than 0. Either type of stateid is 177 suffucient to keep the file open, which allows READ (See 178 Section 18.22 of [RFC5661]), WRITE (See Section 18.2 of [RFC5661]), 179 LOCK (See Section 18.10 of [RFC5661]), and LAYOUTGET (see 180 Section 18.43 of [RFC5661]) operations to proceed. If the client 181 gets both a open and a delegation stateid as part of the OPEN, then 182 it has to return them both. And during each operation, the client 183 can send a costly GETATTR (See Section 18.7 of [RFC5661]). 185 If the client knows that the server supports the 186 OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag (as determined by an 187 earlier GETATTR operation which queried for the FATTR4_OPEN_ARGUMENTS 188 attribute), then the client can supply that flag during the OPEN and 189 only get either an open or delegation stateid. 191 The client is already prepared to not get a delegation stateid even 192 if requested. In order to not send an open stateid, the server can 193 indicate that fact with the result flag of 194 OPEN4_RESULT_NO_OPEN_STATEID. The open stateid field, 195 OPEN4resok.stateid (see Section 18.16.2 of [RFC5661]), should also be 196 set to the special all zero stateid. 198 3.1. XDR Modifications to OPEN 200 [RFC8178] (see Section 4.4.2) allows for extending the microversion 201 of the NFSv4.x protocol without increasing the microversion. The 202 client can probe the capabilities of the server and based on that 203 result, determine if both it and the server support features not 204 specified in the main microversion docuument. 206 The XDR extensions presented in this section allow for the OPEN 207 procedure to be extended in such a fashion. It models all of the 208 parameters via bitmap4 data structures, which allows for the addition 209 of a new flag to any of the OPEN arguments (see Section 18.16.1 of 210 [RFC5661]). Two new flags are provided: 212 o OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION (see Section 4) 214 o OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS 216 Subsequent documents can use this framework to introduce new 217 functionality to OPEN. 219 221 /// 222 /// struct open_arguments4 { 223 /// bitmap4 oa_share_access; 224 /// bitmap4 oa_share_deny; 225 /// bitmap4 oa_share_access_want; 226 /// bitmap4 oa_open_claim; 227 /// bitmap4 oa_create_mode; 228 /// }; 229 /// 231 /// 232 /// enum open_args_share_access4 = { 233 /// OPEN_ARGS_SHARE_ACCESS_READ = 0; 234 /// OPEN_ARGS_SHARE_ACCESS_WRITE = 1; 235 /// OPEN_ARGS_SHARE_ACCESS_BOTH = 2; 236 /// }; 237 /// 238 /// 239 /// enum open_args_share_deny4 = { 240 /// OPEN_ARGS_SHARE_DENY_NONE = 0; 241 /// OPEN_ARGS_SHARE_DENY_READ = 1; 242 /// OPEN_ARGS_SHARE_DENY_WRITE = 2; 243 /// }; 244 /// 246 /// 247 /// enum open_args_share_access4 = { 248 /// OPEN_ARGS_SHARE_ACCESS_WANT_ANY_DELEG = 0; 249 /// OPEN_ARGS_SHARE_ACCESS_WANT_NO_DELEG = 1; 250 /// OPEN_ARGS_SHARE_ACCESS_WANT_CANCEL = 2; 251 /// OPEN_ARGS_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL 252 /// = 3; 253 /// OPEN_ARGS_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED 254 /// = 4; 255 /// OPEN_ARGS_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS = 5; 256 /// OPEN_ARGS_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION = 6; 257 /// }; 258 /// 260 /// 261 /// enum open_args_share_access4 = { 262 /// OPEN_ARGS_CLAIM_NULL = 0; 263 /// OPEN_ARGS_CLAIM_PREVIOUS = 1; 264 /// OPEN_ARGS_CLAIM_DELEGATE_CUR = 2; 265 /// OPEN_ARGS_CLAIM_DELEGATE_PREV = 3; 266 /// OPEN_ARGS_CLAIM_FH = 4; 267 /// OPEN_ARGS_CLAIM_DELEG_CUR_FH = 5; 268 /// OPEN_ARGS_CLAIM_DELEG_PREV_FH = 6; 269 /// }; 270 /// 272 /// 273 /// enum open_args_share_access4 = { 274 /// OPEN_ARGS_CREATE_MODE_GUARDED = 0; 275 /// OPEN_ARGS_CREATE_MODE_EXCLUSIVE = 1; 276 /// }; 277 /// 279 /// 280 /// typedef open_arguments4 fattr4_open_arguments; 281 /// 282 /// 283 /// %/* 284 /// % * Determine what OPEN4 supports. 285 /// % */ 286 /// const FATTR4_OPEN_ARGUMENTS = 86; 287 /// 289 /// 290 /// const OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION = 0x200000; 291 /// 293 /// 294 /// const OPEN4_RESULT_NO_OPEN_STATEID = 0x00000010; 295 /// 297 299 4. Proxying of Times 301 When a client is granted a write delegation on a file, it is the 302 authority for the file. If the server queries the client as to the 303 state of the file via a CB_GETATTR (see Section 20.1 of [RFC5661]), 304 then it can only determine the size of the file. Likewise, if the 305 client holding the delegation wants to know either of the access, 306 modify, or change times, it has to send a GETATTR to the server. 307 While it is the authority for these values, it has no way to 308 guarantee these values after the delegation has been returned. And 309 as such, it can not pass these times up to an application expecting 310 posix compliance. 312 With the addition of the new flag: 313 OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS, the client and server can 314 negiotiate that the client will be the authority for these values and 315 upon return of the delegation stateid via a DELEGRETURN (see section 316 18.6 of [RFC5661]), the times will be passed back to the server. If 317 the server is queried by another client for either the size or the 318 times, it will need to use a CB_GETATTR to query the client which 319 holds the delegation (see Section 20.1 of [RFC5661]). 321 If a server informs the client via the FATTR4_OPEN_ARGUMENTS 322 attribute that it supports 323 OPEN_ARGS_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS and it returns a valid 324 delegation stateid for an OPEN operation which sets the 325 OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag, then it MUST be able 326 to query the client via a CB_GETATTR for the FATTR4_TIME_DELEG_ACCESS 327 attribute and FATTR4_TIME_DELEG_MODIFY attribute. (The change time 328 can be derived from the modify time.) Further, when it gets a 329 SETATTR (see Section 18.30 of [RFC5661]) in the same compound as the 330 DELEGRETURN, then it MUST accept those FATTR4_TIME_DELEG_ACCESS 331 attribute and FATTR4_TIME_DELEG_MODIFY attribute changes and derive 332 the change time or reject the changes with NFS4ERR_DELAY. 334 A key prerequisite of this approach is that the server and client are 335 in time synchronization with each other. Note that while the base 336 NFSv4.2 does not require such synchronization, the use of RPCSEC_GSS 337 typically makes such a requirement. When the client presents either 338 FATTR4_TIME_DELEG_ACCESS or FATTR4_TIME_DELEG_MODIFY attributes to 339 the server, the server MUST decide whether the times presented are 340 before the old times or past the current time. If the time presented 341 is before the original time, then the update is ignored. If the time 342 presented is in the future, the server can either clamp the new time 343 to the current time, or it may return NFS4ERR_DELAY to the client, 344 allowing it to retry. Note that if the clock skew is large, this 345 policy will result in access to the file being denied until such time 346 that the clock skew is exceeded. 348 A change in the access time MUST not advance the change time, also 349 known as the time_metadata attribute (see Section 5.8.2.42 of 350 [RFC5661]), but a change in the modify time might advance the change 351 time (and in turn the change attribute (See Section 5.8.1.4 of 352 [RFC5661]). If the modify time is greater than the change time and 353 before the current time, then the change time is adjusted to the 354 modify time and not the current time (as is most likely done on most 355 SETATTR calls that change the metadata). If the modify time is in 356 the future, it will be clamped to the current time. 358 Note that each of the possible times, access, modify, and change, are 359 compared to the current time. They should all be compared against 360 the same time value for the current time. I.e., do not retrieve a 361 different value of the current time for each calculation. 363 If the client sets the OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag 364 in an OPEN operation, then it MUST support the 365 FATTR4_TIME_DELEG_ACCESS and FATTR4_TIME_DELEG_MODIFY attributes both 366 in the CB_GETATTR and SETATTR operations. 368 4.1. Use case 370 When a server is a proxy for a NFSv4 server, it is a client to the 371 NFSv4 server and during file I/O, it may get a delegation on a file. 372 The client of the proxy would be querying the proxy for attributes 373 and not the NFSv4 server. Each GETATTR from that client would result 374 in at least one additional GETATTR being sent across the wire. 376 4.2. XDR for Proxying of Times 378 380 /// 381 /// /* 382 /// * attributes for the delegation times being 383 /// * cached and served by the "client" 384 /// */ 385 /// typedef nfstime4 fattr4_time_deleg_access; 386 /// typedef nfstime4 fattr4_time_deleg_modify; 387 /// 389 /// 390 /// %/* 391 /// % * New RECOMMENDED Attribute for 392 /// % * delegation caching of times 393 /// % */ 394 /// const FATTR4_TIME_DELEG_ACCESS = 84; 395 /// const FATTR4_TIME_DELEG_MODIFY = 85; 396 /// 398 /// 399 /// const OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS = 0x100000; 400 /// 402 404 5. Operation 77: LAYOUT_WCC - Layout Weak Cache Consistency 406 5.1. ARGUMENT 408 409 /// struct LAYOUT_WCC4args { 410 /// stateid4 lowa_stateid; 411 /// layouttype4 lowa_type; 412 /// opaque lowa_body<>; 413 /// }; 414 416 5.2. RESULT 418 419 /// struct LAYOUT_WCC4res { 420 /// nfsstat4 lowr_status; 421 /// }; 422 424 5.3. DESCRIPTION 426 When using pNFS (See Section 12 of [RFC5661]), the client is most 427 likely to be performing file operations to the storage device and not 428 the metadata server. With some layout types (most notably the 429 flexible files layout type in [RFC8435]) there is no control protocol 430 between the metadata server and the storage device. In order to 431 update the metadata state of the file, the metadata server will need 432 to track the metadata state of the data file - once the layout is 433 issued, it is not able to see the NFSv3 file operations from the 434 client to the storage device. Thus the metadata server will be 435 required to query the storage device for the data file attributes. 437 For example, with a flexible files layout type, the metadata server 438 would issue a NFSv3 GETATTR to the storage device. These queries are 439 most likely triggered in response to a NFSv4 GETATTR to the metadata 440 server. Not only are these GETATTRs to the storage device 441 individually expensive, the storage device can become inundated by a 442 storm of such requests. NFSv3 solved a similar issue by having the 443 READ and WRITE operations employ a post-operation attribute to report 444 the weak cache consistency (WCC) data (See Section 2.6 of [RFC1813]). 446 Each NFSv3 operation corresponds to one round trip between the client 447 and server. So a WRITE followed by a GETATTR would require two round 448 trips. In that scenario, the attribute information retrieved is 449 considered to be strict server-client consistency for a cache 450 consistency protocol. For NFSv4, the WRITE and GETATTR can be issued 451 together inside a compound, which only requires one round trip 452 between the client and server. And this is also considered to be a 453 strict server-client consistency. In essence, the NFSv4 READ and 454 WRITE operations drop the post-operation attributes, allowing the 455 client to decide if it needs that information. 457 With the flexible files layout type, the client can leverage the 458 NFSv3 WCC to service the proxying of times (See Section 4). But the 459 granularity of this data is limited. With client side mirroring (See 460 Section 8 of [RFC8435]), the client has to aggregate the N mirrored 461 files in order to send one piece of information instead of N pieces 462 of information. Also, the client is limited to sending that 463 information only when it returns the delegation. 465 The current filehandle and the lowa_stateid identifies the particular 466 layout for the LAYOUT_WCC operation. The lowa_type indicates how to 467 unpack the layout type specific payload inside the lowa_body field. 468 The lowa_type is defined to be a value from the IANA registry for 469 "pNFS Layout Types Registry". 471 The lowa_body will contain the data file attributes. The client will 472 be responsible for mapping the NFSv3 post-operation attributes to 473 those in a fattr4. Just as the post-operation attributes may be 474 ignored by the client, the server may ignore the attributes inside 475 the LAYOUT_WCC. But the server can also use those attributes to 476 avoid querying the storage device for the data file attributes. Note 477 that as these attributes are optional and there is nothing the client 478 can do if the server ignores one, there is no need to return a 479 bitmap4 of which attributes were accepted in the result of the 480 LAYOUT_WCC. 482 5.4. Allowed Errors 484 The LAYOUT_WCC operation can raise the errors in Table 1. When an 485 error is encountered, the metadata server can decide to ignore the 486 entire operation or depending on the layout type specific payload, it 487 could decide to apply a portion of the payload. 489 Valid Error Returns for LAYOUT_WCC 491 +-------------------------------------------------------------------+ 492 | Errors | 493 +-------------------------------------------------------------------+ 494 | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | 495 | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, NFS4ERR_DELEG_REVOKED, | 496 | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, NFS4ERR_INVAL, | 497 | NFS4ERR_ISDIR, NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | 498 | NFS4ERR_NOTSUPP, NFS4ERR_NO_GRACE, NFS4ERR_OLD_STATEID, | 499 | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_REP_TOO_BIG, | 500 | NFS4ERR_REP_TOO_BIG_TO_CACHE, NFS4ERR_REQ_TOO_BIG, | 501 | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | 502 | NFS4ERR_TOO_MANY_OPS, NFS4ERR_UNKNOWN_LAYOUTTYPE, | 503 | NFS4ERR_WRONG_CRED, NFS4ERR_WRONG_TYPE | 504 +-------------------------------------------------------------------+ 506 Table 1 508 5.5. Flex Files Layout Type 509 510 /// struct ff_data_server_wcc4 { 511 /// deviceid4 ffdsw_deviceid; 512 /// stateid4 ffdsw_stateid; 513 /// nfs_fh4 ffdsw_fh_vers<>; 514 /// fattr4 ffdsw_attributes; 515 /// }; 516 /// 517 /// struct ff_mirror_wcc4 { 518 /// ff_data_server_wcc4 ffmw_data_servers<>; 519 /// }; 520 /// 521 /// struct ff_layout_wcc4 { 522 /// ff_mirror_wcc4 fflw_mirrors<>; 523 /// }; 524 526 The flex file layout type specific results SHOULD correspond to the 527 ff_layout4 data structure as defined in Section 5.1 of [RFC8435]. 528 There SHOULD be a one-to-one correspondence between: 530 o ff_data_server4 -> ff_data_server_wcc4 532 o ff_mirror4 -> ff_mirror_wcc4 534 o ff_layout4 -> ff_layout_wcc4 536 Each ff_layout4 has an array of ff_mirror4, which have an array of 537 ff_data_server4. Based on the current filehandle and the 538 lowa_stateid, the server can match the reported attributes. 540 But the positional correspondence between the elements is not 541 sufficient to determine the attributes to update. Consider the case 542 where a layout had three mirrors and two of them had updated 543 attributes, but the third did not. A client could decide to present 544 all three mirrors, with one mirror having an attribute mask with no 545 attributes present. Or it could decide to present only the two 546 mirrors which had been changed. 548 In either case, the combination of ffdsw_deviceid, ffdsw_stateid, and 549 ffdsw_fh_vers will uniquely identify the attributes to be updated. 550 All three arguments are required. A layout might have multiple data 551 files on the same storage device, in which case the ffdsw_deviceid 552 and ffdsw_stateid would match, but the ffdsw_fh_vers would not. 554 The ffdsw_attributes are processed similar to the obj_attributes in 555 the SETATTR arguments (See Section 18.30 of [RFC5661]). 557 6. Extraction of XDR 559 This document contains the external data representation (XDR) 560 [RFC4506] description of the new open flags for delegating the file 561 to the client. The XDR description is embedded in this document in a 562 way that makes it simple for the reader to extract into a ready-to- 563 compile form. The reader can feed this document into the following 564 shell script to produce the machine readable XDR description of the 565 new flags: 567 569 #!/bin/sh 570 grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??' 572 574 That is, if the above script is stored in a file called "extract.sh", 575 and this document is in a file called "spec.txt", then the reader can 576 do: 578 sh extract.sh < spec.txt > delstid_prot.x 580 The effect of the script is to remove leading white space from each 581 line, plus a sentinel sequence of "///". XDR descriptions with the 582 sentinel sequence are embedded throughout the document. 584 Note that the XDR code contained in this document depends on types 585 from the NFSv4.2 nfs4_prot.x file (generated from [RFC7863]). This 586 includes both nfs types that end with a 4, such as offset4, length4, 587 etc., as well as more generic types such as uint32_t and uint64_t. 589 While the XDR can be appeneded to that from [RFC7863], the various 590 code snippets belong in their respective areas of the that XDR. 592 6.1. Code Components Licensing Notice 594 Both the XDR description and the scripts used for extracting the XDR 595 description are Code Components as described in Section 4 of "Legal 596 Provisions Relating to IETF Documents" [LEGAL]. These Code 597 Components are licensed according to the terms of that document. 599 7. Security Considerations 601 There are no new security considerations beyond those in [RFC7862]. 603 8. IANA Considerations 605 There are no IANA considerations. 607 9. Normative References 609 [LEGAL] IETF Trust, "Legal Provisions Relating to IETF Documents", 610 November 2008, . 613 [RFC1813] IETF, "NFS Version 3 Protocol Specification", RFC 1813, 614 June 1995. 616 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 617 Requirement Levels", BCP 14, RFC 2119, March 1997. 619 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 620 STD 67, RFC 4506, May 2006. 622 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 623 "Network File System (NFS) Version 4 Minor Version 1 624 Protocol", RFC 5661, January 2010. 626 [RFC7862] Haynes, T., "NFS Version 4 Minor Version 2", RFC 7862, 627 November 2016. 629 [RFC7863] Haynes, T., "Network File System (NFS) Version 4 Minor 630 Version 2 External Data Representation Standard (XDR) 631 Description", RFC 7863, November 2016. 633 [RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor 634 Versions", RFC 8178, July 2017. 636 [RFC8435] Halevy, B. and T. Haynes, "Parallel NFS (pNFS) Flexible 637 File Layout", RFC 8435, August 2018. 639 Appendix A. Acknowledgments 641 Trond Myklebust and David Flynn all worked on the prototype at 642 Hammerspace. 644 Appendix B. RFC Editor Notes 646 [RFC Editor: please remove this section prior to publishing this 647 document as an RFC] 649 [RFC Editor: prior to publishing this document as an RFC, please 650 replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the 651 RFC number of this document] 653 Authors' Addresses 655 Thomas Haynes 656 Hammerspace 657 4300 El Camino Real Ste 105 658 Los Altos, CA 94022 659 USA 661 Email: loghyr@hammerspace.com 663 Trond Myklebust 664 Hammerspace 665 4300 El Camino Real Ste 105 666 Los Altos, CA 94022 667 USA 669 Email: trondmy@hammerspace.com