idnits 2.17.1 draft-haynes-nfsv4-delstid-00.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 (April 01, 2018) is 2216 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' ** Obsolete normative reference: RFC 5661 (Obsoleted by RFC 8881) Summary: 1 error (**), 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 Hammerspace 4 Intended status: Standards Track April 01, 2018 5 Expires: October 3, 2018 7 Extending the Opening of Files in NFSv4.2 8 draft-haynes-nfsv4-delstid-00.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 grants the 14 client the right to cache metadata on the file locally. This 15 document presents serveral refinements to both the opeing 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 https://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 October 3, 2018. 35 Copyright Notice 37 Copyright (c) 2018 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 2. Determining the Arguments to OPEN . . . . . . . . . . . . . . 3 56 3. Offline Files . . . . . . . . . . . . . . . . . . . . . . . . 6 57 4. Proxying of Times . . . . . . . . . . . . . . . . . . . . . . 6 58 4.1. Use case . . . . . . . . . . . . . . . . . . . . . . . . 8 59 5. XDR Description of the Flexible File Layout Type . . . . . . 8 60 5.1. Code Components Licensing Notice . . . . . . . . . . . . 9 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 63 8. Normative References . . . . . . . . . . . . . . . . . . . . 10 64 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 10 65 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 10 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 68 1. Introduction 70 In the Network File System version4 (NFSv4) a client may be granted a 71 delegation for a file. This allows the client to act as the 72 authority of the file's metadata and data. In this document, we 73 introduce some new semnatics to both the open and the delegation 74 process which allows the client to: 76 o determine the extension of OPEN (see Section 18.16 of [RFC5661]) 77 flags. 79 o during the OPEN procedure, get either the open or delegation 80 stateids, but not both. 82 o detect an offline file, which may be located off premise. 84 o cache both the access and modify times, reducing the number of 85 times the client needs to go to the server to get that 86 information. 88 Using the process detailed in [RFC8178], the revisions in this 89 document become an extension of NFSv4.2 [RFC7862]. They are built on 90 top of the external data representation (XDR) [RFC4506] generated 91 from [RFC7863]. 93 1.1. Definitions 95 delegation: A file delegation, which is a recallable lock that 96 assures the holder that inconsistent opens and file changes cannot 97 occur so long as the delegation is held. 99 stateid: A stateid is a 128-bit quantity returned by a server that 100 uniquely defines state held by the server for the client. (See 101 Section 8 of [RFC5661]) 103 1.2. Requirements Language 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in [RFC2119]. 109 2. Determining the Arguments to OPEN 111 113 /// 114 /// struct open_arguments4 { 115 /// bitmap4 oa_share_access; 116 /// bitmap4 oa_share_deny; 117 /// bitmap4 oa_share_access_want; 118 /// bitmap4 oa_open_claim; 119 /// bitmap4 oa_create_mode; 120 /// }; 121 /// 123 /// 124 /// enum open_args_share_access4 = { 125 /// OPEN_ARGS_SHARE_ACCESS_READ = 0; 126 /// OPEN_ARGS_SHARE_ACCESS_WRITE = 1; 127 /// OPEN_ARGS_SHARE_ACCESS_BOTH = 2; 128 /// }; 129 /// 131 /// 132 /// enum open_args_share_deny4 = { 133 /// OPEN_ARGS_SHARE_DENY_NONE = 0; 134 /// OPEN_ARGS_SHARE_DENY_READ = 1; 135 /// OPEN_ARGS_SHARE_DENY_WRITE = 2; 136 /// }; 137 /// 138 /// 139 /// enum open_args_share_access4 = { 140 /// OPEN_ARGS_SHARE_ACCESS_WANT_ANY_DELEG = 0; 141 /// OPEN_ARGS_SHARE_ACCESS_WANT_NO_DELEG = 1; 142 /// OPEN_ARGS_SHARE_ACCESS_WANT_CANCEL = 2; 143 /// OPEN_ARGS_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL 144 /// = 3; 145 /// OPEN_ARGS_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED 146 /// = 4; 147 /// OPEN_ARGS_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS = 5; 148 /// OPEN_ARGS_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION = 6; 149 /// }; 150 /// 152 /// 153 /// enum open_args_share_access4 = { 154 /// OPEN_ARGS_CLAIM_NULL = 0; 155 /// OPEN_ARGS_CLAIM_PREVIOUS = 1; 156 /// OPEN_ARGS_CLAIM_DELEGATE_CUR = 2; 157 /// OPEN_ARGS_CLAIM_DELEGATE_PREV = 3; 158 /// OPEN_ARGS_CLAIM_FH = 4; 159 /// OPEN_ARGS_CLAIM_DELEG_CUR_FH = 5; 160 /// OPEN_ARGS_CLAIM_DELEG_PREV_FH = 6; 161 /// }; 162 /// 164 /// 165 /// enum open_args_share_access4 = { 166 /// OPEN_ARGS_CREATE_MODE_GUARDED = 0; 167 /// OPEN_ARGS_CREATE_MODE_EXCLUSIVE = 1; 168 /// }; 169 /// 171 /// 172 /// typedef open_arguments4 fattr4_open_arguments; 173 /// 175 /// 176 /// %/* 177 /// % * Determine what OPEN4 supports. 178 /// % */ 179 /// const FATTR4_OPEN_ARGUMENTS = 86; 180 /// 182 /// 183 /// const OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION = 0x200000; 184 /// 185 /// 186 /// const OPEN4_RESULT_NO_OPEN_STATEID = 0x00000010; 187 /// 189 191 [RFC8178] (see Section 4.4.2) allows for extending the microversion 192 of the NFSv4.x protocol without increasing the microversion. The 193 client can probe the capabilities of the server and based on that 194 result, determine if both it and the server support features not 195 specified in the main microversion documuent. 197 The XDR extensions presented in this section allow for the OPEN 198 procedure to be extended in such a fashion. It models all of the 199 parameters via bitmap4 data structures, which allows for the addition 200 of a new flag to any of the OPEN arguments (see Section 18.16.1 of 201 [RFC5661]. Two new flags are provided: 203 o OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION (see 204 Section Section 4) 206 o OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS 208 Subsequent documents can use this framework to introduce new 209 functionality to OPEN. 211 This section extends the OPEN procedure to allow it to return either 212 an open or delegation stateid. The file is said to be "open" to the 213 client as long as the count of open and delegated stateids is greater 214 than 0. Either type of stateid is suffucient to keep the file open, 215 which allows READ, WRITE, LOCK, and LAYOUTGET operations to proceed. 216 If the client gets both a open and a delegation stateid as part of 217 the OPEN, then it has to return them both. And during each 218 operation, the client can send a costly GETATTR. 220 If the client knows that the server supports the 221 OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag (as determined by an 222 earlier GETATTR operation which queried for the FATTR4_OPEN_ARGUMENTS 223 attribute), then the client can supply that flag during the OPEN and 224 only get either an open or delegation stateid. 226 The client is already prepared to not get a delegation stateid even 227 if requested. In order to not send an open stateid, the server can 228 indicate that fact with the result flag of 229 OPEN4_RESULT_NO_OPEN_STATEID. The open stateid field, 230 OPEN4resok.stateid (see Section 18.16.2 of [RFC5661]), should also be 231 set to the special all zero stateid. 233 3. Offline Files 235 237 /// 238 /// typedef bool fattr4_offline; 239 /// 241 /// 242 /// const FATTR4_OFFLINE = 83; 243 /// 245 247 If a file is archived or offline, then the metadata portion is 248 available to the file server, but the data content is not available. 249 Thus a compound with a GETATTR or READDIR can report the file's 250 attributes without bringing the file online. However, either an OPEN 251 or a LAYOUTGET might cause the file server to retrieve the archived 252 data contents, bringing the file online. If an operating system is 253 not aware that the file is offline, it might inadvertantly open the 254 file to determine what type of file it is accessing. [[AI2: Document 255 these OSes! --TH]] 257 By adding the new attribute FATTR4_OFFLINE, a client can predetermine 258 the avaiablity of the file, avoiding the need to open it at all. 259 Note that being offline might also mean that the file is archived in 260 the cloud, i.e., there can be an expense in both retrieving the file 261 to bring online and in sending the file back to offline status. 263 4. Proxying of Times 265 267 /// 268 /// /* 269 /// * attributes for the delegation times being 270 /// * cached and served by the "client" 271 /// */ 272 /// typedef nfstime4 fattr4_time_deleg_access; 273 /// typedef nfstime4 fattr4_time_deleg_modify; 274 /// 275 /// 276 /// %/* 277 /// % * New RECOMMENDED Attribute for 278 /// % * delegation caching of times 279 /// % */ 280 /// const FATTR4_TIME_DELEG_ACCESS = 84; 281 /// const FATTR4_TIME_DELEG_MODIFY = 85; 282 /// 284 /// 285 /// const OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS = 0x100000; 286 /// 288 290 When a client is granted a write delegation on a file, it is the 291 authority for the file. If the server queries the client as to the 292 state of the file via a CB_GETATTR (see Section 20.1 of [RFC5661]), 293 then it can only determine the size of the file. Likewise, if the 294 client holding the delegation wants to know either of the access, 295 modify, or change times, it has to send a GETATTR to the server. 296 While it is the authority for these values, it has no way to 297 guarantee these values after the delegation has been returned. And 298 as such, it can not pass these times up to an application expecting 299 posix compliance. [[AI3: Cite --TH]] 301 With the addition of the new flag: 302 OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS, the client and server can 303 negiotiate that the client will be the authority for these values and 304 upon return of the delegation stateid via a DELEGRETURN (see section 305 18.6 of [RFC5661]), the times will be passed back to the server. If 306 the server is queried by another client for either the size or the 307 times, it will need to use a CB_GETATTR to query the client which 308 holds the delegation (see Section 20.1 of [RFC5661]). 310 If a server informs the client via the FATTR4_OPEN_ARGUMENTS 311 attribute that it supports 312 OPEN_ARGS_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS and it returns a valid 313 delegation stateid for an OPEN operation which sets the 314 OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag, then it MUST be able 315 to query the client via a CB_GETATTR for the FATTR4_TIME_DELEG_ACCESS 316 attribute and FATTR4_TIME_DELEG_MODIFY attribute. (The change time 317 can be derived from the modify time.) Further, when it gets a 318 SETATTR (see Section 18.30 of [RFC5661]) in the same compound as the 319 DELEGRETURN, then it MUST accept those FATTR4_TIME_DELEG_ACCESS 320 attribute and FATTR4_TIME_DELEG_MODIFY attribute changes and derive 321 the change time or reject the changes with NFS4ERR_DELAY. 323 A key prequisite of this approach is that the server and client are 324 in time synchronization with each other. Note that while the base 325 NFSv4.2 does not require such synchronization, the use of RPCSEC_GSS 326 typically makes such a requirement. When the client presents either 327 FATTR4_TIME_DELEG_ACCESS or FATTR4_TIME_DELEG_MODIFY attributes to 328 the server, the server MUST decide whether the times presented are 329 before the old times or past the current time. If the time presented 330 is before the original time, then the update is ignored. If the time 331 presented is in the future, the server can either clamp the new time 332 to the current time, or it may return NFS4ERR_DELAY to the client, 333 allowing it to retry. Note that if the clock skew is large, this 334 policy will result in access to the file being denied until such time 335 that the clock skew is exceeded. 337 A change in the access time MUST not advance the change time, also 338 known as the time_metadata attribute (see Section 5.8.2.42 of 339 [RFC5661]), but a change in the modify time might advance the change 340 time (and in turn the change attribute (See Section 5.8.1.4 of 341 [RFC5661]). If the modify time is greater than the change time and 342 before the current time, then the change time is adjusted to the 343 modify time and not the current time (as is most likely done on most 344 SETATTR calls that change the metadata). If the modify time is in 345 the future, it will be clamped to the current time. 347 Note that each of the possible times, access, modify, and change, are 348 compared to the current time. They should all be compared against 349 the same time value for the current time. I.e., do not retrieve a 350 different value of the current time for each calculation. 352 If the client sets the OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag 353 in an OPEN operation, then it MUST support the 354 FATTR4_TIME_DELEG_ACCESS and FATTR4_TIME_DELEG_MODIFY attributes both 355 in the CB_GETATTR and SETATTR operations. 357 4.1. Use case 359 With a server is a proxy for a NFSv4 server, it is a client to the 360 NFSv4 server and during file I/O, it may get a delegation on a file. 361 The client of the proxy would be querying the proxy for attributes 362 and not the NFSv4 server. Each GETATTR from that client would result 363 in at least one additional GETATTR being sent across the wire. 365 5. XDR Description of the Flexible File Layout Type 367 This document contains the external data representation (XDR) 368 [RFC4506] description of the new open flags for delegating the file 369 to the client. The XDR description is embedded in this document in a 370 way that makes it simple for the reader to extract into a ready-to- 371 compile form. The reader can feed this document into the following 372 shell script to produce the machine readable XDR description of the 373 new flags: 375 377 #!/bin/sh 378 grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??' 380 382 That is, if the above script is stored in a file called "extract.sh", 383 and this document is in a file called "spec.txt", then the reader can 384 do: 386 sh extract.sh < spec.txt > delstid_prot.x 388 The effect of the script is to remove leading white space from each 389 line, plus a sentinel sequence of "///". XDR descriptions with the 390 sentinel sequence are embedded throughout the document. 392 Note that the XDR code contained in this document depends on types 393 from the NFSv4.2 nfs4_prot.x file (generated from [RFC7863]). This 394 includes both nfs types that end with a 4, such as offset4, length4, 395 etc., as well as more generic types such as uint32_t and uint64_t. 397 While the XDR can be appeneded to that from [RFC7863], the various 398 code snippets belong in their respective areas of the that XDR. 400 5.1. Code Components Licensing Notice 402 Both the XDR description and the scripts used for extracting the XDR 403 description are Code Components as described in Section 4 of "Legal 404 Provisions Relating to IETF Documents" [LEGAL]. These Code 405 Components are licensed according to the terms of that document. 407 6. Security Considerations 409 There are no new security considerations beyond those in [RFC7862]. 411 7. IANA Considerations 413 There are no IANA considerations. 415 8. Normative References 417 [LEGAL] IETF Trust, "Legal Provisions Relating to IETF Documents", 418 November 2008, . 421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 422 Requirement Levels", BCP 14, RFC 2119, March 1997. 424 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 425 STD 67, RFC 4506, May 2006. 427 [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., 428 "Network File System (NFS) Version 4 Minor Version 1 429 Protocol", RFC 5661, January 2010. 431 [RFC7862] Haynes, T., "NFS Version 4 Minor Version 2", RFC 7862, 432 November 2016. 434 [RFC7863] Haynes, T., "Network File System (NFS) Version 4 Minor 435 Version 2 External Data Representation Standard (XDR) 436 Description", RFC 7863, November 2016. 438 [RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor 439 Versions", RFC 8178, July 2017. 441 Appendix A. Acknowledgments 443 Trond Myklebust and David Flynn all worked on the prototype at 444 Hammerspace. 446 Appendix B. RFC Editor Notes 448 [RFC Editor: please remove this section prior to publishing this 449 document as an RFC] 451 [RFC Editor: prior to publishing this document as an RFC, please 452 replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the 453 RFC number of this document] 455 Author's Address 456 Thomas Haynes 457 Hammerspace 458 4300 El Camino Real Ste 105 459 Los Altos, CA 94022 460 USA 462 Email: loghyr@hammer.space