idnits 2.17.1 draft-haynes-nfsv4-versioning-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 -- The document date (October 06, 2014) is 3488 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) ** Obsolete normative reference: RFC 3530 (Obsoleted by RFC 7530) == Outdated reference: A later version (-35) exists of draft-ietf-nfsv4-rfc3530bis-33 ** Obsolete normative reference: RFC 5661 (Obsoleted by RFC 8881) == Outdated reference: A later version (-41) exists of draft-ietf-nfsv4-minorversion2-27 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 T. Haynes 3 Internet-Draft Primary Data 4 Intended status: Standards Track D. Noveck, Ed. 5 Expires: April 9, 2015 6 October 06, 2014 8 Minor versioning Rules for NFSv4 9 draft-haynes-nfsv4-versioning-00 11 Abstract 13 This document specifies the minor versioning rules for NFSv4. It 14 also specifies how those minor versioning rules may be modified. 16 Requirements Language 18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 19 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 20 document are to be interpreted as described in RFC 2119 [RFC2119]. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 9, 2015. 39 Copyright Notice 41 Copyright (c) 2014 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 58 3. Modifying the minor version rules . . . . . . . . . . . . . . 3 59 4. The minor versioning rules . . . . . . . . . . . . . . . . . 3 60 5. Extensions within Minor Versions . . . . . . . . . . . . . . 6 61 5.1. Feature Specification Documents . . . . . . . . . . . . . 6 62 5.2. Additional Informational Documents . . . . . . . . . . . 9 63 5.3. Relationship Between Minor versioning and Extensions 64 within a Minor Version . . . . . . . . . . . . . . . . . 10 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 69 8.2. Informative References . . . . . . . . . . . . . . . . . 11 70 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11 71 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 11 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 74 1. Introduction 76 To address the requirement of an NFS protocol that can evolve as the 77 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 78 contains the rules and framework to allow for future minor changes or 79 versioning. 81 The base assumption with respect to minor versioning is that any 82 future accepted minor version will be documented in one or more 83 Standards Track RFCs. Minor version 0 of the NFSv4 protocol is 84 represented by [RFC3530], minor version 1 by [RFC5661], and minor 85 version 2 by [NFSv42]. The COMPOUND (see Section 14.2 of [RFC3530]) 86 and CB_COMPOUND (see Section 15.2 of [RFC3530]) procedures support 87 the encoding of the minor version being requested by the client. 89 2. Terminology 91 A basic familiarity with the NFSv4 terminology is assumed in this 92 document, the reader is pointed to [RFC3530]. 94 3. Modifying the minor version rules 96 The minor versioning rules had been being maintained inside the 97 various Standards Track RFCs, which had the impact of the minor 98 versioning rules being modified as needed per release of the minor 99 versions. The rules for minor versions SHOULD stand outside the 100 minor versions and be tracked by their own Standard Track RFCs. As 101 such, all modifications to the minor versioning rules MUST be 102 documented not in the minor version documents, but in Standard Track 103 RFCs which are focused entirely on the minor versioning rules 104 themselves. 106 4. The minor versioning rules 108 The following items represent the basic rules for the development of 109 minor versions. 111 1. Procedures are not added or deleted. 113 To maintain the general Remote Procedure Call (RPC) model, NFSv4 114 minor versions will not add to or delete procedures from the NFS 115 program. 117 2. Minor versions may add operations to the COMPOUND and 118 CB_COMPOUND procedures. 120 The addition of operations to the COMPOUND and CB_COMPOUND 121 procedures does not affect the RPC model. 123 * Minor versions may append attributes to the bitmap4 that 124 represents sets of attributes and to the fattr4 that 125 represents sets of attribute values. 127 This allows for the expansion of the attribute model to allow 128 for future growth or adaptation. 130 * Minor version X must append any new attributes after the last 131 documented attribute. 133 Since attribute results are specified as an opaque array of 134 per-attribute, XDR-encoded results, the complexity of adding 135 new attributes in the midst of the current definitions would 136 be too burdensome. 138 3. Minor versions must not modify the structure of an existing 139 operation's arguments or results. 141 Again, the complexity of handling multiple structure definitions 142 for a single operation is too burdensome. New operations should 143 be added instead of modifying existing structures for a minor 144 version. 146 This rule does not preclude the following adaptations in a minor 147 version: 149 * adding bits to flag fields, such as new attributes to 150 GETATTR's bitmap4 data type, and providing corresponding 151 variants of opaque arrays, such as a notify4 used together 152 with such bitmaps 154 * adding bits to existing attributes like Access Control Lists 155 (ACL) that have flag words 157 * extending enumerated types (including NFS4ERR_*) with new 158 values 160 * adding cases to a switched union 162 4. Note that when adding new cases to a switched union, a minor 163 version must not make new cases be REQUIRED. While the 164 encapsulating operation may be REQUIRED, the new cases (the 165 specific arm of the discriminated union) is not. The error code 166 NFS4ERR_UNION_NOTSUPP is used to notify the client when the 167 server does not support such a case. 169 5. Minor versions must not modify the structure of existing 170 attributes. 172 6. Minor versions must not delete operations. 174 This prevents the potential reuse of a particular operation 175 "slot" in a future minor version. 177 7. Minor versions must not delete attributes. 179 8. Minor versions must not delete flag bits or enumeration values. 181 9. Minor versions may declare an operation MUST NOT be implemented. 183 Specifying that an operation MUST NOT be implemented is 184 equivalent to obsoleting an operation. For the client, it means 185 that the operation MUST NOT be sent to the server. For the 186 server, an NFS error can be returned as opposed to "dropping" 187 the request as an XDR decode error. This approach allows for 188 the obsolescence of an operation while maintaining its structure 189 so that a future minor version can reintroduce the operation. 191 1. Minor versions may declare that an attribute MUST NOT be 192 implemented. 194 2. Minor versions may declare that a flag bit or enumeration 195 value MUST NOT be implemented. 197 10. Minor versions may declare an operation to be OBSOLESCENT, which 198 indicates an intention to remove the operation (i.e., make it 199 MANDATORY TO NOT implement) in a subsequent minor version. Such 200 labeling is separate from the question of whether the operation 201 is REQUIRED or RECOMMENDED or OPTIONAL in the current minor 202 version. An operation may be both REQUIRED for the given minor 203 version and marked OBSOLESCENT, with the expectation that it 204 will be MANDATORY TO NOT implement in the next (or other 205 subsequent) minor version. 207 11. Note that the early notification of operation obsolescence is 208 put in place to mitigate the effects of design and 209 implementation mistakes, and to allow protocol development to 210 adapt to unexpected changes in the pace of implementation. Even 211 if an operation is marked OBSOLESCENT in a given minor version, 212 it may end up not being marked MANDATORY TO NOT implement in the 213 next minor version. In unusual circumstances, it might not be 214 marked OBSOLESCENT in a subsequent minor version, and never 215 become MANDATORY TO NOT implement. 217 12. Minor versions may downgrade features from REQUIRED to 218 RECOMMENDED, from RECOMMENDED to OPTIONAL, or from OPTIONAL to 219 MANDATORY TO NOT implement. Also, if a feature was marked as 220 OBSOLESCENT in the prior minor version, it may be downgraded 221 from REQUIRED to OPTIONAL from RECOMMENDED to MANDATORY TO NOT 222 implement, or from REQUIRED to MANDATORY TO NOT implement. 224 13. Minor versions may upgrade features from OPTIONAL to 225 RECOMMENDED, or RECOMMENDED to REQUIRED. Also, if a feature was 226 marked as OBSOLESCENT in the prior minor version, it may be 227 upgraded to not be OBSOLESCENT. 229 14. A client and server that support minor version X SHOULD support 230 minor versions 0 through X-1 as well. 232 15. Except for infrastructural changes, a minor version must not 233 introduce REQUIRED new features. 235 This rule allows for the introduction of new functionality and 236 forces the use of implementation experience before designating a 237 feature as REQUIRED. On the other hand, some classes of 238 features are infrastructural and have broad effects. Allowing 239 infrastructural features to be RECOMMENDED or OPTIONAL 240 complicates implementation of the minor version. 242 16. A client MUST NOT attempt to use a stateid, filehandle, or 243 similar returned object from the COMPOUND procedure with minor 244 version X for another COMPOUND procedure with minor version Y, 245 where X != Y. 247 5. Extensions within Minor Versions 249 An important goal of this document is to enable extensions to be made 250 to the features included in an existing minor version, without the 251 overhead attendant upon the creation of an entirely new minor 252 version. 254 5.1. Feature Specification Documents 256 Each such extension will be in the form of a working-group standards- 257 track document which defines a new optional feature. The definition 258 of the new feature may include one or more "feature elements" which 259 add to the existing XDR in ways already used in creating new minor 260 versions. Other sorts of XDR modification are not allowed. Feature 261 elements include new operations, callbacks, attributes, and 262 enumeration values. The functionality of some existing operations 263 may be extended by the addition of new flags bits in existing flag 264 words and new cases in existing switched unions. New error codes may 265 be added but the set of valid error codes to be returned by an 266 operation is fixed, except that existing operations may return new 267 errors to respond to situations that only arise when previously 268 unused flag bits are set or when extensions to a switched union are 269 used. 271 Such an additional feature will become, for all intents and purposes, 272 part of the current NFSv4 minor version upon publication of the 273 description as a Proposed Standard, enabling such extensions to be 274 used by new client and server implementations without, as previously 275 required, a change in the value of the minorversion field within the 276 COMPOUND operation. 278 The working group has two occasions to make sure that such features 279 are appropriate ones: 281 o At the time the feature definition document becomes a working 282 group document, the working group needs to determine, in addition 283 to the feature's general compatibility with NFSv4, that the XDR 284 assignments (i.e., additional values for operation callback and 285 attribute numbers, and for new flags and switch values to be added 286 to existing operations) associated with the new feature are 287 complete and do not conflict with those in the existing protocol 288 or those currently under development. 290 o At the time the working group document is complete, the working 291 group, in addition to, normal document review, can and should look 292 at what prototype implementations of the feature have been done 293 and use that information to determine the work-ability of the 294 feature. 296 Such feature definition documents would contain a number of items, 297 following the pattern of the NFSv4.2 specification. The only 298 difference would be that while the NFSv4.2 specification defines a 299 number of features to be incorporated in NFSv4.2, the feature 300 definition documents would each define a single feature. 302 Such feature definition documents would contain a number of In 303 addition to a general explanation of the feature in question, the 304 items to be included in such feature definition documents would be: 306 o Description of new operations (corresponding to sections 16 and 17 307 of [NFSv42]). 309 o Description of any modified operations (corresponding to section 310 15 of [NFSv42]). 312 o Description of new attributes (corresponding to section 13 of 313 [NFSv42]). 315 o Description of any added error codes (corresponding to section 316 12.1 of [NFSv42]). 318 o A summary description all changes made by this feature to the xdr 319 definition of the protocol, including operation codes, attribute 320 numbers, added flag bits and enumeration values, and request and 321 response structures for new operation together with the other xdr 322 extensions needed to support them. 324 o A listing giving the valid errors for each new operation and 325 callback (corresponds to sections 12.2 and 12.3 of [NFSv42]). 327 o A table giving for each new feature element its status (always 328 OPTIONAL), and its relationship to the feature being described 329 (i.e., REQUIRED for every implementation of the feature, or 330 OPTIONAL in the presence of the feature). This would be similar 331 to the material in section 14 of [NFSv42] but it is restricted to 332 a single feature and expanded in scope to include all feature 333 elements. 335 o All of the sections required for RFC publication, such as 336 "Security Considerations", "IANA considerations", etc. 338 Such feature definition documents would contain a number of Addition 339 of features to an existing minor version will take advantage of the 340 existing NFSv4 infrastructure that allows optional features to be 341 added to new minor versions, but without in this case requiring any 342 change the version number. This will enable compatibility with 343 existing clients and servers. In particular: 345 o Existing server implementations will return NFS4ERR_NOTSUPP or 346 NFS4ERR_OP_ILLEGAL in response to any use of the new operation, 347 allowing the client to determine that the requested (and 348 potentially the feature in question) is not supported by the 349 server. 351 o Clients can determine whether particular new attributes are 352 supported by a given server by examining the value returned as the 353 value of the supported_attr attribute. 355 o New callbacks will only be sent to clients that have used the new 356 features associated with them, allowing existing clients to be 357 unaware of their existence. 359 o Existing server implementations that do not recognize new flag 360 bits will return NFS4ERR_INVAL, enabling the client to determine 361 that the new flag value is not supported by the server. 363 o Existing server implementations that do not recognize the new arm 364 of a switched union will return will return NFS4ERR_INVAL or 365 NFS4ERR_UNION_NOTSUPP, enabling the client to determine that the 366 the new union arm is not supported by the server. 368 o Error values returned to the client for all requests that do not 369 use new features will only be those previously allowed. Only when 370 the client uses a new feature will a previously invalid error 371 value be returned. 373 Given that some existing servers may have XDR parsing implementations 374 that cannot easily accommodate previously unknown operations or 375 switched union arms, clients should carefully determine whether 376 particular features are supported by the server before proceeding to 377 use them and need to be prepared to treat NFS4ERR_BADXDR as 378 indicating non-support of a new operation or switched union arm where 379 server support for a particular feature is being tested. 381 5.2. Additional Informational Documents 383 Additional documents will be required from time to time. The purpose 384 of these documents will be to organize existing material so that an 385 implementer will not have to scan a large set of feature definition 386 document or minor version specification to find information being 387 sought. 389 The frequency of updates for such documents will be affected by 390 implementer needs and the ability to easily generate such documents, 391 preferably by automated means. These documents will be informational 392 documents whose purpose is to simplify use of the standards-track 393 documents. Some desirable elements would include: 395 o An updated XDR for the protocol as a whole including feature 396 elements from all features accepted as Proposed Standards. 398 o A consolidated list of XDR assignments of values (e.g., operation 399 codes, attribute numbers, error codes, new flag bits, enumeration 400 extensions) for all features under development (i.e., accepted as 401 working-group standards-track documents but not yet published or 402 abandoned). 404 o A list of all feature definition documents that have been approved 405 as working group documents but have not yet been approved as 406 proposed standards. 408 o A table mapping operations and callbacks to the most recent 409 document containing a description of that operation. 411 o A table mapping attributes to the most recent document containing 412 a description of that attribute. 414 o A table giving, for each operation in the protocol, the errors 415 that may validly be returned for that operation. If possible, it 416 would be desirable to give, as does RFC5661, the operations which 417 may validly return each particular error. 419 o A table giving for each operation, callback, and attribute and for 420 each feature element in a published extension giving its status 421 OPTIONAL, REQUIRED, RECOMMENDED, MANDATORY to NOT implement), and 422 its relationship to the feature which allows its inclusion (i.e., 423 REQUIRED for every implementation of the feature, or OPTIONAL in 424 the presence of the feature). This would be similar to the 425 material in section 14 of [NFSv42], expanded in scope to include 426 all feature elements, and updated to include all published 427 features that are part of the current NFSv4 minor version, at the 428 date of publication. 430 5.3. Relationship Between Minor versioning and Extensions within a 431 Minor Version 433 The extensibility of minor versions are governed by the following 434 rules: 436 o Minor versions zero and one are not extensible. Each has a fixed 437 set of optional features as described in [RFC3530bis] and 438 [RFC5661]. 440 o Minor versions beyond one are presumed extensible as discussed 441 herein. However, any statement within the minor version 442 specification disallowing extension will cause that minor version 443 to be considered non-extensible. 445 o No extension to a minor version may be made once the specification 446 document for a subsequent minor version becomes a working group 447 standards-track document. 449 While making minor versions extensible will decrease the frequency of 450 new minor versions, it will not eliminate the need for them. In 451 particular, 453 o A new minor version will be required for any change in the status 454 of a feature element (i.e., an operation, callback, attribute, 455 added flag or switch case). For example, changes which make 456 operations Recommended, Required or Mandatory to Not Implement 457 will require a minor version. 459 o Any incompatible semantic change in the required or allowed 460 processing of an existing operation or attribute will require a 461 minor version. 463 o Any change that extends the set of operations that an existing 464 operation, with the exception noted above. New errors may be 465 added when the conditions that give rise to these new errors 466 cannot arise as long as new flag bits or switched union arms are 467 not used. I.e., when it is clear that existing client cannot 468 receive these errors. 470 o Any change in the mapping of feature elements to features will 471 require a minor version. For example, if a feature is to be split 472 into two separate features clients would no longer be able to 473 infer support for one operation from support for the other, in the 474 same way that had been done previously, invalidating logic in 475 existing clients. 477 6. Security Considerations 479 There are no security considerations in this document. 481 7. IANA Considerations 483 There are no IANA considerations in this document. 485 8. References 487 8.1. Normative References 489 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 490 Requirement Levels", March 1997. 492 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 493 Beame, C., Eisler, M., and D. Noveck, "Network File System 494 (NFS) version 4 Protocol", RFC 3530, April 2003. 496 [RFC3530bis] 497 Haynes, T. and D. Noveck, "Network File System (NFS) 498 version 4 Protocol", draft-ietf-nfsv4-rfc3530bis-33 (Work 499 In Progress), April 2014. 501 [RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File 502 System (NFS) Version 4 Minor Version 1 Protocol", RFC 503 5661, January 2010. 505 8.2. Informative References 507 [NFSv42] Haynes, T., "NFS Version 4 Minor Version 2", draft-ietf- 508 nfsv4-minorversion2-27 (Work In Progress), September 2014. 510 Appendix A. Acknowledgments 512 Appendix B. RFC Editor Notes 514 [RFC Editor: please remove this section prior to publishing this 515 document as an RFC] 517 [RFC Editor: prior to publishing this document as an RFC, please 518 replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the 519 RFC number of this document] 521 Authors' Addresses 523 Thomas Haynes 524 Primary Data, Inc. 525 4300 El Camino Real Ste 100 526 Los Altos, CA 94022 527 USA 529 Phone: +1 408 215 1519 530 Email: thomas.haynes@primarydata.com 532 David Noveck (editor) 533 26 Locust Ave 534 Lexington, MA 02421 535 US 537 Phone: +1 781 572 8038 538 Email: davenoveck@gmail.com