idnits 2.17.1 draft-ietf-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 == 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 'not RECOMMENDED' in this paragraph: o When a correction is made to a MANDATORY feature, the situation becomes one in which neither the old nor the new new version of the feature is MANDATORY. Instead, it is MANDATORY that a server support at least one of the two, while each is individually OPTIONAL. Although use of the corrected version is ultimately better, it is not RECOMMENDED, since the choice of which version to support if only one is supported will depend on the needs of clients, which may be slow to adopt the updated version. -- The document date (November 11, 2014) is 3452 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 (~~), 4 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 5 Expires: May 15, 2015 Dell 6 November 11, 2014 8 NFSv4 Version Management 9 draft-ietf-nfsv4-versioning-00 11 Abstract 13 This document describes the management of versioning within the NFSv4 14 family of protocols. It covers the creation of minor versions, the 15 addition of OPTIONAL features to existing minor versions, and the 16 correction of flaws in features already published as Proposed 17 Standards. The rules for minor versioning set out in this document 18 supersede the multiple sets of minor versioning rules in RFC3530 and 19 RFC5661. 21 Requirements Language 23 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 24 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 25 document are to be interpreted as described in RFC 2119 [RFC2119]. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on May 15, 2015. 44 Copyright Notice 46 Copyright (c) 2014 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. Consolidation of the Minor Version Rules . . . . . . . . . . 3 64 4. The Minor Versioning Rules . . . . . . . . . . . . . . . . . 4 65 5. Extensions within Minor Versions . . . . . . . . . . . . . . 7 66 5.1. Feature Specification Documents . . . . . . . . . . . . . 7 67 5.1.1. Compatibility Issues for Messages Sent to Servers . . 9 68 5.1.2. Compatibility Issues for Messages Sent to Clients . . 11 69 5.2. Additional Documents to be Produced . . . . . . . . . . . 12 70 5.2.1. Minor Version Indexing Document . . . . . . . . . . . 12 71 5.2.2. Consolidated XDR Document . . . . . . . . . . . . . . 13 72 5.2.3. XDR Assignment Document . . . . . . . . . . . . . . . 13 73 5.2.4. Transition of Documents to RFC's . . . . . . . . . . 14 74 5.3. Relationship Between Minor Versioning and Extensions 75 within a Minor Version . . . . . . . . . . . . . . . . . 15 76 6. Correction of Existing Minor Versions and Features . . . . . 16 77 6.1. Documentation of XDR changes . . . . . . . . . . . . . . 18 78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 80 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 81 9.1. Normative References . . . . . . . . . . . . . . . . . . 19 82 9.2. Informative References . . . . . . . . . . . . . . . . . 19 83 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 19 84 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 20 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 87 1. Introduction 89 To address the requirement of an NFS protocol that can evolve as the 90 need arises, the Network File System (NFS) version 4 (NFSv4) protocol 91 contains the rules and framework to allow for future minor changes or 92 versioning. These versioning rules SHOULD maintain compatibility 93 with existing clients and servers. 95 A large portion of such changes will be part of new minor versions. 96 The COMPOUND procedure (see Section 14.2 of [RFC3530]) specifies the 97 minor version being used by the client. The CB_COMPOUND (see 98 Section 15.2 of [RFC3530]) procedure specifies the minor version 99 being used by the server on callbacks. 101 Each minor version is specified by one or more standards track RFC: 103 Minor version 0 is specified by [RFC3530] 105 Minor version 1 is specified principally by [RFC5661] 107 Minor version 2 is specified principally by [NFSv42]. 109 In addition to the creation of new minor versions, two other sorts of 110 versioning are discussed in this document: 112 o Addition of OPTIONAL features to existing minor versions. 114 o XDR-based extensions used to correct protocol bugs in existing 115 minor versions or associated features. 117 2. Terminology 119 A basic familiarity with the NFSv4 terminology is assumed in this 120 document, the reader is pointed to [RFC3530]. 122 3. Consolidation of the Minor Version Rules 124 Previously, versioning rules had been being maintained and specified 125 in the Standards Track RFCs, defining the individual minor versions. 126 As a result, versioning rules were modified on an ad hoc basis for 127 each new minor version. 129 This document defines a set of versioning rules, including rules for 130 minor version construction, that applies to the NFSv4 protocol as a 131 whole. The rules are subject to change but any such change should be 132 part of a standards track RFC obsoleting or updating this document. 134 This document supersedes the minor versioning rules appearing in the 135 minor version specification RFC's. As a result potential conflicts 136 among these documents should be addressed as follows: 138 o The specification of the actual protocols for minor versions 139 previously published as Proposed Standards take precedence over 140 minor versioning rules in either this document or in the minor 141 version specification RFC's. In other words, if the transition 142 from version A to version B violates a minor versioning rules, the 143 protocol stays as it is. 145 o Otherwise, any conflict between the minor versioning rules in this 146 document and those in minor version specification RFC's are to be 147 resolved based on the treatment in this document. 149 Future minor version specification documents should avoid specifying 150 minor versioning rules and reference this document in connection with 151 rules for minor versions. 153 4. The Minor Versioning Rules 155 The following items represent the basic rules for the development of 156 minor versions. 158 1. Procedures are not added or deleted. 160 To maintain the general Remote Procedure Call (RPC) model, NFSv4 161 minor versions will not add to or delete procedures from the NFS 162 program. 164 2. Minor versions may add operations to the COMPOUND and 165 CB_COMPOUND procedures. 167 The addition of operations to the COMPOUND and CB_COMPOUND 168 procedures does not affect the RPC model. 170 * Minor versions may append attributes to the bitmap4 that 171 represents sets of attributes and to the fattr4 that 172 represents sets of attribute values. 174 This allows for the expansion of the attribute model to allow 175 for future growth or adaptation. 177 * Minor version X must append any new attributes after the last 178 documented attribute. 180 Since attribute results are specified as an opaque array of 181 per-attribute, XDR-encoded results, the complexity of adding 182 new attributes in the midst of the current definitions would 183 be too burdensome. 185 3. Minor versions must not modify the structure of an existing 186 operation's arguments or results. 188 Again, the complexity of handling multiple structure definitions 189 for a single operation is too burdensome. New operations should 190 be added instead of modifying existing structures for a minor 191 version. 193 This rule does not preclude the following adaptations in a minor 194 version: 196 * adding bits to flag fields, such as new attributes to 197 GETATTR's bitmap4 data type, and providing corresponding 198 variants of opaque arrays, such as a notify4 used together 199 with such bitmaps 201 * adding bits to existing attributes like Access Control Lists 202 (ACL) that have flag words 204 * extending enumerated types (including NFS4ERR_*) with new 205 values 207 * adding cases to a switched union 209 4. Note that when adding new cases to a switched union, a minor 210 version must not make new cases be REQUIRED. While the 211 encapsulating operation may be REQUIRED, the new cases (the 212 specific arm of the discriminated union) is not. The error code 213 NFS4ERR_UNION_NOTSUPP is used to notify the client when the 214 server does not support such a case. 216 5. Minor versions must not modify the structure of existing 217 attributes. 219 6. Minor versions must not delete operations. 221 This prevents the potential reuse of a particular operation 222 "slot" in a future minor version. 224 7. Minor versions must not delete attributes. 226 8. Minor versions must not delete flag bits or enumeration values. 228 9. Minor versions may declare an operation MUST NOT be implemented. 230 Specifying that an operation MUST NOT be implemented is 231 equivalent to obsoleting an operation. For the client, it means 232 that the operation MUST NOT be sent to the server. For the 233 server, an NFS error can be returned as opposed to "dropping" 234 the request as an XDR decode error. This approach allows for 235 the obsolescence of an operation while maintaining its structure 236 so that a future minor version can reintroduce the operation. 238 1. Minor versions may declare that an attribute MUST NOT be 239 implemented. 241 2. Minor versions may declare that a flag bit or enumeration 242 value MUST NOT be implemented. 244 10. Minor versions may declare an operation to be OBSOLESCENT, which 245 indicates an intention to remove the operation (i.e., make it 246 MANDATORY TO NOT implement) in a subsequent minor version. Such 247 labeling is separate from the question of whether the operation 248 is REQUIRED or RECOMMENDED or OPTIONAL in the current minor 249 version. An operation may be both REQUIRED for the given minor 250 version and marked OBSOLESCENT, with the expectation that it 251 will be MANDATORY TO NOT implement in the next (or other 252 subsequent) minor version. 254 11. Note that the early notification of operation obsolescence is 255 put in place to mitigate the effects of design and 256 implementation mistakes, and to allow protocol development to 257 adapt to unexpected changes in the pace of implementation. Even 258 if an operation is marked OBSOLESCENT in a given minor version, 259 it may end up not being marked MANDATORY TO NOT implement in the 260 next minor version. In unusual circumstances, it might not be 261 marked OBSOLESCENT in a subsequent minor version, and never 262 become MANDATORY TO NOT implement. 264 12. Minor versions may downgrade features from REQUIRED to 265 RECOMMENDED, from RECOMMENDED to OPTIONAL, or from OPTIONAL to 266 MANDATORY TO NOT implement. Also, if a feature was marked as 267 OBSOLESCENT in the prior minor version, it may be downgraded 268 from REQUIRED to OPTIONAL from RECOMMENDED to MANDATORY TO NOT 269 implement, or from REQUIRED to MANDATORY TO NOT implement. 271 13. Minor versions may upgrade features from OPTIONAL to 272 RECOMMENDED, or RECOMMENDED to REQUIRED. Also, if a feature was 273 marked as OBSOLESCENT in the prior minor version, it may be 274 upgraded to not be OBSOLESCENT. 276 14. A client and server that support minor version X SHOULD support 277 minor versions 0 through X-1 as well. 279 15. Other than where explicitly documented in a minor version's 280 specification document, except for infrastructural changes, a 281 minor version must not introduce REQUIRED new features. 283 This rule allows for the introduction of new functionality and 284 forces the use of implementation experience before designating a 285 feature as REQUIRED. On the other hand, some classes of 286 features are infrastructural and have broad effects. Allowing 287 infrastructural features to be RECOMMENDED or OPTIONAL 288 complicates implementation of the minor version. 290 16. A client MUST NOT attempt to use a stateid, filehandle, or 291 similar returned object from the COMPOUND procedure with minor 292 version X for another COMPOUND procedure with minor version Y, 293 where X != Y. 295 5. Extensions within Minor Versions 297 An important goal of this document is to enable extensions to be made 298 to the set of features included in an existing minor version, without 299 the overhead attendant upon the creation of an entirely new minor 300 version. 302 5.1. Feature Specification Documents 304 Each such extension will be in the form of a working-group standards- 305 track document which defines a new optional feature. The definition 306 of the new feature may include one or more "feature elements" which 307 add to the existing XDR in ways already discussed in connection with 308 the creation of new minor versions. Other sorts of XDR modification 309 are not allowed. Feature elements include new operations, callbacks, 310 attributes, and enumeration values. The functionality of some 311 existing operations may be extended by the addition of new flags bits 312 in existing flag words and new cases in existing switched unions. 313 New error codes may be added but the set of valid error codes to be 314 returned by an operation is fixed, except that existing operations 315 may return new errors to respond to situations that only arise when 316 previously unused flag bits are set or when extensions to a switched 317 union are used. 319 Such an additional feature will become, for all intents and purposes, 320 part of the current NFSv4 minor version upon publication of the 321 description as a Proposed Standard, enabling such extensions to be 322 used by new client and server implementations without, as previously 323 required, a change in the value of the minor version field within the 324 COMPOUND operation. 326 The working group has two occasions to make sure that such features 327 are appropriate ones: 329 o At the time the feature definition document becomes a working 330 group document, the working group needs to determine, in addition 331 to the feature's general compatibility with NFSv4, that the XDR 332 assignments (i.e., additional values for operation callback and 333 attribute numbers, and for new flags and switch values to be added 334 to existing operations) associated with the new feature are 335 complete and do not conflict with those in the existing protocol 336 or those currently under development. 338 o At the time the working group document is complete, the working 339 group, in addition to normal document review, can and should look 340 at what prototype implementations of the feature have been done 341 and use that information to determine the work-ability and 342 maturity of the feature. 344 Such feature definition documents would contain a number of items, 345 following the pattern of the NFSv4.2 specification. The only 346 difference would be that while the NFSv4.2 specification defines a 347 number of features to be incorporated in NFSv4.2, the feature 348 definition documents would each define a single feature. 350 In addition to a general explanation of the feature in question, the 351 items to be included in such feature definition documents would be: 353 o Description of new operations (corresponding to Sections 16 and 17 354 of [NFSv42]). 356 o Description of any modified operations (corresponding to 357 Section 15 of [NFSv42]). 359 o Description of new attributes (corresponding to Section 13 of 360 [NFSv42]). 362 o Description of any added error codes (corresponding to 363 Section 12.1 of [NFSv42]). 365 o A summary description of all changes made by this feature to the 366 XDR definition of the protocol, including operation codes, 367 attribute numbers, added flag bits and enumeration values, and 368 request and response structures for new operations together with 369 the other XDR extensions needed to support them. 371 o A listing giving the valid errors for each new operation and 372 callback (corresponds to Sections 12.2 and 12.3 of [NFSv42]). 374 o A table giving for each new feature element its status (always 375 OPTIONAL), and its relationship to the feature being described 376 (i.e., REQUIRED for every implementation of the feature, or 377 OPTIONAL in the presence of the feature). This would be similar 378 to the material in Section 14 of [NFSv42] but it is restricted to 379 a single feature and expanded in scope to include all feature 380 elements. 382 o All of the Sections required for RFC publication, such as 383 "Security Considerations", "IANA considerations", etc. 385 Addition of features to an existing minor version will take advantage 386 of the existing NFSv4 infrastructure that allows optional features to 387 be added to new minor versions, but without in this case requiring 388 any change in the minor version number. Adding features in this way 389 will enable compatibility with existing clients and servers, who may 390 be unaware of the new feature. 392 Because the receiver of a message may be unaware of the existence of 393 a specific extension, certain compatibility rules need to be 394 observed. In some cases (e.g., addition of new operations or 395 callbacks or addition of new arms to an existing switched union) 396 older clients or servers may be unable to do XDR parsing on an 397 extension of whose existence they are unaware. In other cases (e.g., 398 error returns) there are no XDR parsing issues but existing clients 399 and servers may have expectations as to what may validly be returned. 400 Detailed discussion of these compatibility issues appears below: 402 o Issues related to messages sent to the server are discussed in 403 Section 5.1.1. 405 o Issues related to messages sent to the client are discussed in 406 Section 5.1.2. 408 5.1.1. Compatibility Issues for Messages Sent to Servers 410 This section deals with compatibility issues that relate to messages 411 sent to the server, i.e., requests and replies to callbacks. In the 412 case of requests, it is the responsibility of the client to determine 413 whether the server in question supports the extension in question 414 before sending a request containing it for any purpose other than 415 determining whether the server is aware of the extension. In the 416 case of callback replies, the server demonstrates its awareness of 417 proper parsing for callback replies by sending the associated 418 callback. 420 Regarding the handling of requests: 422 o Existing server implementations will return NFS4ERR_NOTSUPP or 423 NFS4ERR_OP_ILLEGAL in response to any use of a new operation, 424 allowing the client to determine that the requested operation (and 425 potentially the feature in question) is not supported by the 426 server. 428 o Clients can determine whether particular new attributes are 429 supported by a given server by examining the value returned when 430 the supported_attr attribute is interrogated. Clients need to do 431 this before attempting to use attributes defined in an extension 432 since they cannot depend on the server returning 433 NFS4ERRATTRNOTSUPP for requests which include a mask bit 434 corresponding to a previously unspecified attribute number (as 435 opposed to one which is defined but unsupported). 437 o Existing server implementations that do not recognize new flag 438 bits will return NFS4ERR_INVAL, enabling the client to determine 439 that the new flag value is not supported by the server. 441 o Existing server implementations that do not recognize the new arm 442 of a switched union in a request will return NFS4ERR_INVAL or 443 NFS4ERR_UNION_NOTSUPP, enabling the client to determine that the 444 the new union arm is not supported by the server. 446 Given that some existing servers may have XDR parsing implementations 447 that cannot easily accommodate previously unknown operations or 448 switched union arms, clients should carefully determine whether 449 particular features are supported by the server before proceeding to 450 use them and need to be prepared to treat NFS4ERR_BADXDR as 451 indicating non-support of a new operation or switched union arm where 452 server support for a particular feature is being tested. 454 Regarding the handling of responses to callbacks: 456 o Error values returned to the server for all callbacks that do not 457 use new features will only be those previously allowed. Only when 458 the server uses a new callback extension feature can a previously 459 invalid error value be returned. 461 o Callback replies may only include a new arm of an existing 462 switched union when the server, typically in the callback being 463 responded to, has used a feature element associated with the 464 feature that defined he new switched union arm. 466 5.1.2. Compatibility Issues for Messages Sent to Clients 468 This sections deals with compatibility issues that relate to messages 469 sent to clients, i.e., request replies and callbacks. In both cases, 470 extensions are only sent to clients that have demonstrated awareness 471 of the extensions in question by using an extension associated with 472 the same feature. 474 Regarding the handling of request replies: 476 o Error values returned to the client for all requests that do not 477 use new features will only be those previously allowed. Only when 478 the server uses a new callback extension feature can a previously 479 invalid error value be returned. 481 o Replies may only include a new arm of an existing switched union 482 when the server, typically in the request being responded to, has 483 used a feature element associated with the feature that defined 484 the new switched union arm. 486 Regarding the handling of callbacks, the server needs to be sure that 487 it only sends callbacks to those clients prepared to receive and 488 parse them. 490 o In most cases, the new callback will be part of a feature that 491 contains new (forward) operations as well. When this is the case, 492 the feature specification will specify the operations whose 493 receipt by a server is sufficient to indicate that the client 494 issuing them is prepared to accept and parse the associated 495 callbacks. 497 o For callbacks associated with features that have no new operations 498 defined, the feature specification should define some way for a 499 client to indicate that it is prepared to accept and parse 500 callbacks that are part of the extension. For example, a flag bit 501 in the EXCHANGE_ID request may serve this purpose. 503 o In both of the above cases, the ability to accept and parse the 504 specified callback is considered separate from support for the 505 callback. The feature specification will indicate whether support 506 for the callback is required whenever the feature is used by the 507 client. In cases in which support is not required, the client is 508 free to return NFS4ERR_NOTSUPP upon receiving the callback. 510 5.2. Additional Documents to be Produced 512 Additional documents will be required from time to time. These 513 documents will eventually become RFC's (informational or standards 514 track as described below), but the work of the working group and of 515 implementers developing features will be facilitated by a progression 516 of document drafts that incorporate information about new features 517 that are being developed or have been approved as Proposed Standards. 519 5.2.1. Minor Version Indexing Document 521 One document will organize existing material for a minor version 522 undergoing extension so that implementers will not have to scan a 523 large set of feature definition documents or minor version 524 specifications to find information being sought. Successive drafts 525 of this document will serve as an index to the current state of the 526 extensible minor version. Some desirable elements of this indexing 527 document would include: 529 o A list of all feature definition documents that have been approved 530 as working group documents but have not yet been approved as 531 Proposed Standards. 533 o A table mapping operations and callbacks to the most recent 534 document containing a description of that operation. 536 o A table mapping attributes to the most recent document containing 537 a description of that attribute. 539 o A table giving, for each operation in the protocol, the errors 540 that may validly be returned for that operation. If possible, it 541 would be desirable to give, as does [RFC5661], the operations 542 which may validly return each particular error. 544 o A table giving for each operation, callback, and attribute and for 545 each feature element in a published extension giving its status 546 OPTIONAL, REQUIRED, RECOMMENDED, MANDATORY to NOT implement), and 547 its relationship to the feature which allows its inclusion (i.e., 548 REQUIRED for every implementation of the feature, or OPTIONAL in 549 the presence of the feature). This would be similar to the 550 material in Section 14 of [NFSv42], expanded in scope to include 551 all feature elements, and updated to include all published 552 features that are part of the current NFSv4 minor version, at the 553 date of publication. 555 The frequency of updates for this document will be affected by 556 implementer needs and the ability to easily generate document drafts, 557 preferably by automated means. The most desirable situation is one 558 in which a new draft is available soon after each feature reaches the 559 status of a Proposed Standard. 561 5.2.2. Consolidated XDR Document 563 This document will consist of an updated XDR for the protocol as a 564 whole including feature elements from all features and minor versions 565 accepted as Proposed Standards. 567 A new draft should be prepared whenever a new feature within an 568 extensible minor version is accepted as a Proposed Standard. In most 569 cases, feature developers will be using a suitable XDR which can then 570 be reviewed and published. In cases in which multiple features reach 571 Proposed Standard status at approximately the same time, a merge of 572 the XDR changes made by each feature may be necessary. 574 5.2.3. XDR Assignment Document 576 This document will contain consolidated lists of XDR value 577 assignments that are relevant to the protocol extension process. It 578 should contain lists of assignments for: 580 o operation codes (separate lists for forward operations and for 581 callbacks) 583 o attribute numbers 585 o error codes 587 o bits within flag words that have been extended since they were 588 first introduced. 590 o enumeration values for enumerations which have been extended since 591 they were first introduced. 593 For each set of assignments, the individual assignments may be of 594 three types: 596 1. permanent assignments associated with a minor version or a 597 feature extension that has achieved Proposed Standard status. 599 These assignments are permanent in that the assigned value will 600 never be re-used. However, a subsequent minor version may define 601 some or all feature elements associated with a feature to be 602 Mandatory to NOT support. 604 2. provisional assignments associated with a feature under 605 development (i.e., one which has been approved as a working group 606 document but has not been approved as a Proposed Standard). 608 Provisional assignments are not are not permanent and the values 609 assigned can be re-used in certain circumstances. In particular, 610 when a feature with provisional assignments is not progressing 611 toward the goal of eventual Proposed Standard status, the working 612 group can judge the feature effort to have been abandoned, 613 allowing the codes formerly provisionally allocated to be 614 reclaimed and reassigned. 616 3. definition of individual assignments or ranges reserved for 617 experimental use. 619 A new draft of this document should be produced, whenever: 621 o A minor version or feature specification is accepted as a Proposed 622 Standard. 624 o A new feature is accepted for development and a draft of the 625 corresponding working-group standards-track document is produced 627 o A feature previously accepted for development is abandoned. 629 o The working group decides to make some change in assignments for 630 experimental use. 632 5.2.4. Transition of Documents to RFC's 634 Each of these documents should be published as an RFC soon after the 635 minor version in question ceases to be considered extensible. 636 Typically this will happen when the working group makes the 637 specification for the subsequent minor version into a working group 638 document. Some specifics about the individual documents are listed 639 below: 641 o The most current draft of the indexing document for the minor 642 version would be published as an informational RFC. 644 o The most current draft of the consolidated XDR document should be 645 published as a standards-track RFC. It would update the initial 646 specification of the minor version. 648 o The most recent draft of the XDR assignment document should be 649 published as an informational RFC. 651 Handling of these documents in the event of a post-approval XDR 652 correction is discussed in Section 6.1. 654 5.3. Relationship Between Minor Versioning and Extensions within a 655 Minor Version 657 Extensibility of minor version are governed by the following rules: 659 o Minor versions zero and one are not extensible. Each has a fixed 660 set of optional features as described in [RFC3530bis] and 661 [RFC5661]. 663 o Minor versions beyond one are presumed extensible as discussed 664 herein. However, any statement within the minor version 665 specification disallowing extension will cause that minor version 666 to be considered non-extensible. 668 o No new feature may be added to a minor version may be made once 669 the specification document document for a subsequent minor version 670 becomes a working group standards-track document. 672 Even when a minor version is non-extensible, or when a previous minor 673 version is closed to further extension, the features that it contains 674 are still subject to updates to effect protocol corrections. In many 675 cases, making an XDR change, in the form of an extension will be the 676 best way of correcting the issue. See Section 6 for details. 678 While making minor versions extensible will decrease the frequency of 679 new minor versions, it will not eliminate the need for them. In 680 particular: 682 o A new minor version will be required for any change in the status 683 of a feature element (i.e., an operation, callback, attribute, 684 added flag or switch case). For example, changes which make 685 feature elements Recommended, Required or Mandatory to Not 686 Implement will require a minor version. 688 o Any incompatible semantic change in the required or allowed 689 processing of an existing operation or attribute will require a 690 minor version. 692 o Any change that extends the set of errors returned that an 693 existing operation, with the exception noted above. New errors 694 may be added when the conditions that give rise to these new 695 errors cannot arise as long as new flag bits or switched union 696 arms are not used. I.e., when it is clear that existing client 697 cannot receive these errors. 699 o Any change in the mapping of feature elements to features will 700 require a minor version. For example, if a feature is to be split 701 into two separate features clients would no longer be able to 702 infer support for one operation from support for the other, in the 703 same way that had been done previously, invalidating logic in 704 existing clients. 706 6. Correction of Existing Minor Versions and Features 708 The possibility always exists that there will be a need to correct an 709 existing feature in some way, after the acceptance of that feature, 710 or a minor version containing it, as a Proposed Standard. While the 711 working group can reduce the probability of such situations arising 712 by waiting for running code before considering a feature as done, it 713 cannot reduce the probability to zero. As features are used more 714 extensively and interact with other features, previously unseen flaws 715 may be discovered and will need to be corrected. 717 Such corrections are best done in a bis document updating the RFC 718 defining the relevant feature definition document or minor version 719 specification. In making such correction, the working will have to 720 carefully consider how to assure interoperability with older clients 721 and servers. 723 Often, corrections can be done without changing the protocol XDR. 724 However, incompatible changes in server or client behavior should not 725 be mandated in order to avoid XDR changes. When XDR changes are 726 necessary as part of correcting a flaw, these should be done in a 727 manner similar to that used when implementing new minor versions or 728 features within them. In particular, 730 o Existing XDR structure may not be modified or deleted. 732 o XDR extensions may be used to correct existing protocol facilities 733 in a manner similar to those used to add additional OPTIONAL 734 features. Such corrections may be done in an otherwise non- 735 extensible minor version, if the working group judges it 736 appropriate. 738 o When a correction is made to an OPTIONAL feature, the result is 739 similar to a situation in which there are two independent OPTIONAL 740 features. A server may choose to implement either or both. 742 o When a correction is made to a MANDATORY feature, the situation 743 becomes one in which neither the old nor the new new version of 744 the feature is MANDATORY. Instead, it is MANDATORY that a server 745 support at least one of the two, while each is individually 746 OPTIONAL. Although use of the corrected version is ultimately 747 better, it is not RECOMMENDED, since the choice of which version 748 to support if only one is supported will depend on the needs of 749 clients, which may be slow to adopt the updated version. 751 o When a correction is made to a RECOMMENDED feature, the situation 752 is similar to the case of a MANDATORY feature. Neither version is 753 RECOMMENDED, Neither the old nor the new version of the feature is 754 RECOMMENDED. Instead, it is RECOMMENDED that a server support at 755 least one of the two, while each is individually OPTIONAL. 757 o In all of the cases above, it is appropriate that the old version 758 of the feature, be considered OBSOLESCENT, with the expectation 759 that the working group might, in a later minor version, decide 760 that the older version is to become MANDATORY to NOT implement. 762 Issues related to the effect of XDR corrections on existing 763 documents, including co-ordination with other minor versions, are 764 discussed in Section 6.1. 766 By doing things this way, the protocol with the XDR modification can 767 accommodate clients and servers that support either the corrected or 768 the uncorrected version of the protocol and also clients and servers 769 aware of and capable of supporting both alternatives. 771 o A client that supports only the earlier version of the feature 772 (i.e., an older unfixed client) can determine whether the server 773 it is connecting to supports the older version of feature. It is 774 capable of interoperating with older servers that support only the 775 unfixed protocol as well as ones that support both versions. 777 o A client that supports only the corrected version of the feature 778 (i.e., a new or updated client) can determine whether the server 779 it is connecting to supports the newer version of the feature. It 780 is capable of interoperating with newer servers that support only 781 the updated feature as well as ones that support both versions. 783 o A client that supports both the older and newer version of the 784 feature can determine which version of the particular feature is 785 supported by the server it is working with. 787 o A server that supports only the earlier version of the feature 788 (i.e., an older unfixed server) can only successfully interoperate 789 with older clients. However newer clients can easily determine 790 that the feature cannot be used on that server. 792 o A server that supports only the newer version of the feature 793 (i.e., a new or updated server) can only successfully interoperate 794 with newer clients. However, older clients can easily determine 795 that the feature cannot be used on that server. In the case of 796 OPTIONAL features, clients can be expected to deal with non- 797 support of that particular feature. 799 o A server that supports both the older and newer versions of the 800 feature can interopt with all client variants. 802 By using extensions in this manner, the protocol creates clear path 803 which preserves the functioning of existing clients and servers and 804 allowing client and server implementers to adopt the new version of 805 the feature at a reasonable pace. 807 6.1. Documentation of XDR changes 809 In the event of an XDR correction, as discussed above, some document 810 updates will be required. For the purposes of this discussion we 811 call the minor version for which XDR correction is required minor 812 version X and the minor version on which development is occurring 813 minor version Y. 815 The following discusses the specific updated documents which could be 816 required: 818 o The specification of the feature in question will have to be 819 updated to explain the issue, how it was fixed, and the 820 compatibility and upgrade strategy. Normally this will require an 821 RFC updating the associated feature specification document. 822 However, in the case of a correction to a feature documented in in 823 a minor version definition document, the RFC will update that 824 document instead. 826 o An updated XDR for minor version X will be produced and will be 827 published as a updated to the minor version specification RFC for 828 minor version X. 830 When the correction is to feature documented in a minor version 831 definition, a single RFC will contain both updates to the minor 832 version specification RFC. 834 o An updated minor version indexing document for minor version X is 835 desirable but not absolutely necessary. 837 The question of updated minor version indexing documents for minor 838 versions between X and Y should be addressed by the working group 839 on a case-by-case basis. 841 o An updated XDR assignment document will be required. It should be 842 based on the most recent such document associated wit minor 843 version Y and will serve as the basis for later XDR assignment 844 drafts for minor version Y. 846 The informational RFC's associated with minor version Y (version 847 indexing document and XDR assignment document) will contain the 848 effects of the correction when published. Similarly, the minor 849 version specification RFC will contain the XDR changes associated 850 with the correction. 852 7. Security Considerations 854 There are no security considerations in this document. 856 8. IANA Considerations 858 There are no IANA considerations in this document. 860 9. References 862 9.1. Normative References 864 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 865 Requirement Levels", March 1997. 867 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 868 Beame, C., Eisler, M., and D. Noveck, "Network File System 869 (NFS) version 4 Protocol", RFC 3530, April 2003. 871 [RFC3530bis] 872 Haynes, T. and D. Noveck, "Network File System (NFS) 873 version 4 Protocol", draft-ietf-nfsv4-rfc3530bis-33 (Work 874 In Progress), April 2014. 876 [RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File 877 System (NFS) Version 4 Minor Version 1 Protocol", RFC 878 5661, January 2010. 880 9.2. Informative References 882 [NFSv42] Haynes, T., "NFS Version 4 Minor Version 2", draft-ietf- 883 nfsv4-minorversion2-27 (Work In Progress), September 2014. 885 Appendix A. Acknowledgments 886 Appendix B. RFC Editor Notes 888 [RFC Editor: please remove this section prior to publishing this 889 document as an RFC] 891 [RFC Editor: prior to publishing this document as an RFC, please 892 replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the 893 RFC number of this document] 895 Authors' Addresses 897 Thomas Haynes 898 Primary Data, Inc. 899 4300 El Camino Real Ste 100 900 Los Altos, CA 94022 901 USA 903 Phone: +1 408 215 1519 904 Email: thomas.haynes@primarydata.com 906 David Noveck 907 Dell 908 300 Innovative Way 909 Nashua, NH 03062 910 US 912 Phone: +1 781 572 8038 913 Email: dave_noveck@dell.com