idnits 2.17.1 draft-ietf-netmod-revised-datastores-01.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 13, 2017) is 2600 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 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-20) exists of draft-ietf-netmod-rfc6087bis-12 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track J. Schoenwaelder 5 Expires: September 14, 2017 Jacobs University 6 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 March 13, 2017 13 Network Management Datastore Architecture 14 draft-ietf-netmod-revised-datastores-01 16 Abstract 18 Datastores are a fundamental concept binding the data models written 19 in the YANG data modeling language to network management protocols 20 such as NETCONF and RESTCONF. This document defines an architectural 21 framework for datastores based on the experience gained with the 22 initial simpler model, addressing requirements that were not well 23 supported in the initial model. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 14, 2017. 42 Copyright Notice 44 Copyright (c) 2017 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.1. Original Model of Datastores . . . . . . . . . . . . . . 7 63 4. Architectural Model of Datastores . . . . . . . . . . . . . . 8 64 4.1. The Datastore . . . . . . . . . . . . . . . . 9 65 4.2. Dynamic Datastores . . . . . . . . . . . . . . . . . . . 10 66 4.3. The Datastore . . . . . . . . . . . . . . . 10 67 4.3.1. Missing Resources . . . . . . . . . . . . . . . . . . 11 68 4.3.2. System-controlled Resources . . . . . . . . . . . . . 11 69 4.3.3. Origin Metadata Annotation . . . . . . . . . . . . . 11 70 5. Guidelines for Defining Dynamic Datastores . . . . . . . . . 12 71 5.1. Define a name for the dynamic datastore . . . . . . . . . 12 72 5.2. Define which YANG modules can be used in the datastore . 12 73 5.3. Define which subset of YANG-modeled data applies . . . . 13 74 5.4. Define how dynamic data is actualized . . . . . . . . . . 13 75 5.5. Define which protocols can be used . . . . . . . . . . . 13 76 5.6. Define a module for the dynamic datastore . . . . . . . . 13 77 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 14 78 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 79 7.1. Updates to the IETF XML Registry . . . . . . . . . . . . 18 80 7.2. Updates to the YANG Module Names Registry . . . . . . . . 19 81 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 82 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 83 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 84 10.1. Normative References . . . . . . . . . . . . . . . . . . 20 85 10.2. Informative References . . . . . . . . . . . . . . . . . 21 86 Appendix A. Example Data . . . . . . . . . . . . . . . . . . . . 22 87 A.1. System Example . . . . . . . . . . . . . . . . . . . . . 22 88 A.2. BGP Example . . . . . . . . . . . . . . . . . . . . . . . 25 89 A.2.1. Datastores . . . . . . . . . . . . . . . . . . . . . 27 90 A.2.2. Adding a Peer . . . . . . . . . . . . . . . . . . . . 27 91 A.2.3. Removing a Peer . . . . . . . . . . . . . . . . . . . 28 92 A.3. Interface Example . . . . . . . . . . . . . . . . . . . . 29 93 A.3.1. Pre-provisioned Interfaces . . . . . . . . . . . . . 29 94 A.3.2. System-provided Interface . . . . . . . . . . . . . . 30 95 Appendix B. Ephemeral Dynamic Datastore Example . . . . . . . . 31 96 Appendix C. Implications on Data Models . . . . . . . . . . . . 32 97 C.1. Proposed migration of existing YANG Data Models . . . . . 33 98 C.2. Standardization of new YANG Data Models . . . . . . . . . 34 99 Appendix D. Implications on other Documents . . . . . . . . . . 34 100 D.1. Implications on YANG . . . . . . . . . . . . . . . . . . 34 101 D.2. Implications on YANG Library . . . . . . . . . . . . . . 34 102 D.3. Implications to YANG Guidelines . . . . . . . . . . . . . 35 103 D.3.1. Nodes with different config/state value sets . . . . 35 104 D.3.2. Auto-configured or Auto-negotiated Values . . . . . . 35 105 D.4. Implications on NETCONF . . . . . . . . . . . . . . . . . 35 106 D.4.1. Introduction . . . . . . . . . . . . . . . . . . . . 36 107 D.4.2. Overview of additions to NETCONF . . . . . . . . . . 36 108 D.4.3. Overview of NETCONF version 2 . . . . . . . . . . . . 37 109 D.5. Implications on RESTCONF . . . . . . . . . . . . . . . . 40 110 D.5.1. Introduction . . . . . . . . . . . . . . . . . . . . 40 111 D.5.2. Overview of additions to RESTCONF . . . . . . . . . . 40 112 D.5.3. Overview of a possible new RESTCONF version . . . . . 42 113 Appendix E. Open Issues . . . . . . . . . . . . . . . . . . . . 43 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 116 1. Introduction 118 This document provides an architectural framework for datastores as 119 they are used by network management protocols such as NETCONF 120 [RFC6241], RESTCONF [RFC8040] and the YANG [RFC7950] data modeling 121 language. Datastores are a fundamental concept binding network 122 management data models to network management protocols. Agreement on 123 a common architectural model of datastores ensures that data models 124 can be written in a network management protocol agnostic way. This 125 architectural framework identifies a set of conceptual datastores but 126 it does not mandate that all network management protocols expose all 127 these conceptual datastores. This architecture is agnostic with 128 regard to the encoding used by network management protocols. 130 2. Terminology 132 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 134 "OPTIONAL" in this document are to be interpreted as described in BCP 135 14, [RFC2119]. 137 This document defines the following terms: 139 o configuration data: Data that determines how a device behaves. 140 This data is modeled in YANG using "config true" nodes. 141 Configuration data can originate from different sources. 143 o static configuration data: Configuration data that is eventually 144 persistent and used to get a device from its initial default state 145 into its desired operational state. 147 o dynamic configuration data: Configuration data that is obtained 148 dynamically during the operation of a device through interaction 149 with other systems and not persistent. 151 o system configuration data: Configuration data that is supplied by 152 the device itself. 154 o default configuration data: Configuration data that is not 155 explicitly provided but for which a value defined in the data 156 model is used. 158 o applied configuration data: Configuration data that is currently 159 used by a device. Applied configuration data consists of static 160 configuration data and dynamic configuration data. 162 o state data: The additional data on a system that is not 163 configuration data such as read-only status information and 164 collected statistics. State data is transient and modified by 165 interactions with internal components or other systems. State 166 data is modeled in YANG using "config false" nodes. 168 o datastore: A conceptual place to store and access information. A 169 datastore might be implemented, for example, using files, a 170 database, flash memory locations, or combinations thereof. A 171 datastore maps to an instantiated YANG data tree. 173 o configuration datastore: A datastore holding static configuration 174 data that is required to get a device from its initial default 175 state into a desired operational state. A configuration datastore 176 maps to an instantiated YANG data tree consisting of configuration 177 data nodes and interior data nodes. 179 o running configuration datastore: A configuration datastore holding 180 the complete static configuration currently active on the device. 181 The running configuration datastore always exists. It may include 182 inactive configuration or template-mechanism-oriented 183 configuration that require further expansion. 185 o intended configuration datastore: A configuration datastore 186 holding the complete configuration currently active on the device. 187 It does not include inactive configuration and it does include the 188 expansion of any template mechanisms. 190 o candidate configuration datastore: A configuration datastore that 191 can be manipulated without impacting the device's running 192 configuration datastore and that can be committed to the running 193 configuration datastore. A candidate datastore may not be 194 supported by all protocols or implementations. 196 o startup configuration datastore: The configuration datastore 197 holding the configuration loaded by the device into the running 198 configuration datastore when it boots. A startup datastore may 199 not be supported by all protocols or implementations. 201 o dynamic datastore: A datastore holding dynamic configuration data. 203 o operational state datastore: A datastore holding the currently 204 active applied configuration data as well as the device's state 205 data. 207 o origin: A metadata annotation indicating the origin of a data 208 item. 210 o remnant data: Configuration data that remains in the system for a 211 period of time after it has be removed from a configuration 212 datastore. The time period may be minimal, or may last until all 213 resources used by the newly-deleted configuration data (e.g., 214 network connections, memory allocations, file handles) have been 215 deallocated. 217 The following additional terms are not datastore specific but 218 commonly used and thus defined here as well: 220 o client: An entity that can access YANG-defined data on a server, 221 over some network management protocol. 223 o server: An entity that provides access to YANG-defined data to a 224 client, over some network management protocol. 226 o notification: A server-initiated message indicating that a certain 227 event has been recognized by the server. 229 o remote procedure call: An operation that can be invoked by a 230 client on a server. 232 3. Introduction 234 NETCONF [RFC6241] provides the following definitions: 236 o datastore: A conceptual place to store and access information. A 237 datastore might be implemented, for example, using files, a 238 database, flash memory locations, or combinations thereof. 240 o configuration datastore: The datastore holding the complete set of 241 configuration data that is required to get a device from its 242 initial default state into a desired operational state. 244 YANG 1.1 [RFC7950] provides the following refinements when NETCONF is 245 used with YANG (which is the usual case but note that NETCONF was 246 defined before YANG did exist): 248 o datastore: When modeled with YANG, a datastore is realized as an 249 instantiated data tree. 251 o configuration datastore: When modeled with YANG, a configuration 252 datastore is realized as an instantiated data tree with 253 configuration data. 255 [RFC6244] defined operational state data as follows: 257 o Operational state data is a set of data that has been obtained by 258 the system at runtime and influences the system's behavior similar 259 to configuration data. In contrast to configuration data, 260 operational state is transient and modified by interactions with 261 internal components or other systems via specialized protocols. 263 Section 4.3.3 of [RFC6244] discusses operational state and among 264 other things mentions the option to consider operational state as 265 being stored in another datastore. Section 4.4 of this document then 266 concludes that at the time of the writing, modeling state as a 267 separate data tree is the recommended approach. 269 Implementation experience and requests from operators 270 [I-D.ietf-netmod-opstate-reqs], [I-D.openconfig-netmod-opstate] 271 indicate that the datastore model initially designed for NETCONF and 272 refined by YANG needs to be extended. In particular, the notion of 273 intended configuration and applied configuration has developed. 275 Furthermore, separating operational state data from configuration 276 data in a separate branch in the data model has been found 277 operationally complicated, and typically impacts the readability of 278 module definitions due to overuse of groupings. The relationship 279 between the branches is not machine readable and filter expressions 280 operating on configuration data and on related operational state data 281 are different. 283 3.1. Original Model of Datastores 285 The following drawing shows the original model of datastores as it is 286 currently used by NETCONF [RFC6241]: 288 +-------------+ +-----------+ 289 | | | | 290 | (ct, rw) |<---+ +--->| (ct, rw) | 291 +-------------+ | | +-----------+ 292 | | | | 293 | +-----------+ | 294 +-------->| |<--------+ 295 | (ct, rw) | 296 +-----------+ 297 | 298 v 299 operational state <--- control plane 300 (cf, ro) 302 ct = config true; cf = config false 303 rw = read-write; ro = read-only 304 boxes denote datastores 306 Note that this diagram simplifies the model: read-only (ro) and read- 307 write (rw) is to be understood at a conceptual level. In NETCONF, 308 for example, support for the and datastores is 309 optional and the datastore does not have to be writable. 310 Furthermore, the datastore can only be modified by copying 311 to in the standardized NETCONF datastore editing 312 model. The RESTCONF protocol does not expose these differences and 313 instead provides only a writable unified datastore, which hides 314 whether edits are done through a datastore or by directly 315 modifying the datastore or via some other implementation 316 specific mechanism. RESTCONF also hides how configuration is made 317 persistent. Note that implementations may also have additional 318 datastores that can propagate changes to the datastore. 319 NETCONF explicitly mentions so called named datastores. 321 Some observations: 323 o Operational state has not been defined as a datastore although 324 there were proposals in the past to introduce an operational state 325 datastore. 327 o The NETCONF operation returns the content of the 328 configuration datastore together with the operational state. It 329 is therefore necessary that config false data is in a different 330 branch than the config true data if the operational state data can 331 have a different lifetime compared to configuration data or if 332 configuration data is not immediately or successfully applied. 334 o Several implementations have proprietary mechanisms that allow 335 clients to store inactive data in the datastore; this 336 inactive data is only exposed to clients that indicate that they 337 support the concept of inactive data; clients not indicating 338 support for inactive data receive the content of the 339 datastore with the inactive data removed. Inactive data is 340 conceptually removed before validation. 342 o Some implementations have proprietary mechanisms that allow 343 clients to define configuration templates in . These 344 templates are expanded automatically by the system, and the 345 resulting configuration is applied internally. 347 o Some operators have reported that it is essential for them to be 348 able to retrieve the configuration that has actually been 349 successfully applied, which may be a subset or a superset of the 350 configuration. 352 4. Architectural Model of Datastores 354 Below is a new conceptual model of datastores extending the original 355 model in order to reflect the experience gained with the original 356 model. 358 +-------------+ +-----------+ 359 | | | | 360 | (ct, rw) |<---+ +--->| (ct, rw) | 361 +-------------+ | | +-----------+ 362 | | | | 363 | +-----------+ | 364 +-------->| |<--------+ 365 | (ct, rw) | 366 +-----------+ 367 | 368 | // e.g., removal of "inactive" 369 | // nodes, expansion of templates 370 v 371 +------------+ 372 | | // subject to validation 373 | (ct, ro) | 374 +------------+ 375 | 376 | // e.g., missing resources, delays 377 | 378 | +------ auto-discovery 379 | +------ dynamic configuration protocols 380 | +------ control-plane protocols 381 | +------ dynamic datastores 382 | | 383 v v 384 +---------------+ 385 | | 386 | (ct + cf, ro) | 387 +---------------+ 389 ct = config true; cf = config false 390 rw = read-write; ro = read-only 391 boxes denote datastores 393 4.1. The Datastore 395 The datastore is a read-only datastore that consists of 396 config true nodes. It is tightly coupled to . When data is 397 written to , the data that is to be validated is also 398 conceptually written to . Validation is performed on the 399 contents of . 401 On a traditional NETCONF implementation, and are 402 always the same. 404 Currently there are no standard mechanisms defined that affect 405 so that it would have different contents than , 406 but this architecture allows for such mechanisms to be defined. 408 One example of such a mechanism is support for marking nodes as 409 inactive in . Inactive nodes are not copied to , 410 and are thus not taken into account when validating the 411 configuration. 413 Another example is support for templates. Templates are expanded 414 when copied into , and the expanded result is validated. 416 4.2. Dynamic Datastores 418 The model recognizes the need for dynamic datastores that are by 419 definition not part of the persistent configuration of a device. In 420 some contexts, these have been termed ephemeral datastores since the 421 information is ephemeral, i.e., lost upon reboot. The dynamic 422 datastores interact with the rest of the system through the 423 datastore. 425 Note that the ephemeral datastore discussed in I2RS documents maps to 426 a dynamic datastore in the datastore model described here. 428 4.3. The Datastore 430 The datastore is a read-only datastore that consists of 431 config true and config false nodes. In the original NETCONF model 432 the operational state only had config false nodes. The reason for 433 incorporating config true nodes here is to be able to expose all 434 operational settings without having to replicate definitions in the 435 data models. 437 The datastore contains all configuration data actually 438 used by the system, including all applied configuration, system- 439 provided configuration and values defined by any supported data 440 models. In addition, the datastore also contains state 441 data. 443 Changes to configuration data may take time to percolate through to 444 the datastore. During this period, the 445 datastore will return data nodes for both the previous and current 446 configuration, as closely as possible tracking the current operation 447 of the device. These "remnants" of the previous configuration 448 persist while the system has released resources used by the newly- 449 deleted configuration data (e.g., network connections, memory 450 allocations, file handles). 452 As a result of these remnants, the semantic constraints defined in 453 the data model cannot be relied upon for the datastore, 454 since the system may have remnants whose constraints were valid with 455 the previous configuration and that are not valid with the current 456 configuration. Since constraints on "config false" nodes may refer 457 to "config true" nodes, remnants may force the violation of those 458 constraints. The constraints that may not hold include "when", 459 "must", "min-elements", and "max-elements". Note that syntactic 460 constraints cannot be violated, including hierarchical organization, 461 identifiers, and type-based constraints. 463 4.3.1. Missing Resources 465 The configuration can refer to resources that are not 466 available or otherwise not physically present. In these situations, 467 these parts of the configuration are not applied. The 468 data appears in but does not appear in . 470 A typical example is an interface configuration that refers to an 471 interface that is not currently present. In such a situation, the 472 interface configuration remains in but the interface 473 configuration will not appear in . 475 Note that configuration validity cannot depend on the current state 476 of such resources, since that would imply the removing a resource 477 might render the configuration invalid. This is unacceptable, 478 especially given that rebooting such a device would fail to boot due 479 to an invalid configuration. Instead we allow configuration for 480 missing resources to exist in and , but it will 481 not appear in . 483 4.3.2. System-controlled Resources 485 Sometimes resources are controlled by the device and the 486 corresponding system controlled data appear in (and disappear from) 487 dynamically. If a system controlled resource has 488 matching configuration in when it appears, the system will 489 try to apply the configuration, which causes the configuration to 490 appear in eventually (if application of the 491 configuration was successful). 493 4.3.3. Origin Metadata Annotation 495 As data flows into the datastore, it is conceptually 496 marked with a metadata annotation ([RFC7952]) that indicates its 497 origin. The "origin" metadata annotation is defined in Section 6. 498 The values are YANG identities. The following identities are 499 defined: 501 +-- origin 502 +-- static 503 +-- dynamic 504 +-- default 505 +-- system 507 These identities can be further refined, e.g., there might be an 508 identity "dhcp" derived from "dynamic". 510 The "static" origin represents data provided by the 511 datastore. The "dynamic" origin represents data provided by a 512 dynamic datastore. The "default" origin represents data values 513 specified in the data model, using either simple values in the 514 "default" statement or any values described in the "description" 515 statement. Finally, the "system" origin represents data learned from 516 the normal operational of the system, including control-plane 517 protocols. 519 5. Guidelines for Defining Dynamic Datastores 521 The definition of a dynamic datastore SHOULD be provided in a 522 document (e.g., an RFC) purposed to the definition of the dynamic 523 datastore. When it makes sense, more than one dynamic datastore MAY 524 be defined in the same document (e.g., when the datastores are 525 logically connected). Each dynamic datastore's definition SHOULD 526 address the points specified in the sections below. 528 5.1. Define a name for the dynamic datastore 530 Each dynamic datastores MUST have a name using the character set 531 described by Section 6.2 of [RFC7950]. The name SHOULD be consistent 532 in style and length to other datastore names described in this 533 document. 535 The datastore's name does not need to be globally unique, as it will 536 be uniquely qualified by the namespace of the module in which it is 537 defined (Section 5.6). This means that names such as "running" and 538 "operational" are valid datastore names. However, it is usually 539 desirable to avoid using the same name for multiple different 540 datastores. 542 5.2. Define which YANG modules can be used in the datastore 544 Not all YANG modules may be used in all datastores. Some datastores 545 may constrain which data models can be used in them. If it is 546 desirable that a subset of all modules can be targeted to the dynamic 547 datastore, then the documentation defining the dynamic datastore MUST 548 use the mechanisms described in Appendix D.2 to provide the necessary 549 hooks for module-designers to indicate that their module is to be 550 accessible in the dynamic datastore. 552 5.3. Define which subset of YANG-modeled data applies 554 By default, the data in a dynamic datastore is modeled by all YANG 555 statements in the available YANG modules. However, it is possible to 556 specify criteria YANG statements must satisfy in order to be present 557 in a dynamic datastore. For instance, maybe only config true nodes 558 are present, or config false nodes that also have a specific YANG 559 extension (e.g., i2rs:ephemeral true) are present in the dynamic 560 datastore. 562 5.4. Define how dynamic data is actualized 564 The diagram in Section 4 depicts dynamic datastores feeding into the 565 datastore. How this interaction occurs must be defined 566 by the dynamic datastore. In some cases, it may occur implicitly, as 567 soon as the data is put into the dynamic datastore while, in other 568 cases, an explicit action (e.g., an RPC) may be required to trigger 569 the application of the dynamic datastore's data. 571 5.5. Define which protocols can be used 573 By default, it is assumed that both the NETCONF and RESTCONF 574 protocols can be used to interact with a dynamic datastore. However, 575 it may be that only a specific protocol can be used (e.g., Forces) or 576 that a subset of all protocol operations or capabilities are 577 available (e.g., no locking, no xpath-based filtering, etc.). 579 5.6. Define a module for the dynamic datastore 581 Each dynamic datastore MUST be defined by a YANG module. This module 582 is used by servers to indicate (e.g., via YANG Library) their support 583 for the dynamic datastore. 585 The YANG module MUST import the "ietf-datastores" and "ietf-origin" 586 modules, defined in this document. This is necessary in order to 587 access the base identities they define. 589 The YANG module MUST define an identity that uses the "ds:datastore" 590 identity as its base. This identity is necessary so that the 591 datastore can be referenced in protocol operations (e.g., 592 ). 594 The YANG module MUST define an identity that uses the "or:dynamic" 595 identity as its base. This identity is necessary so that data 596 originating from the datastore can be identified as such via the 597 "origin" metadata attribute defined in Section 6. 599 An example of these guidelines in use is provided in Appendix B. 601 6. YANG Modules 603 file "ietf-datastores@2017-03-13.yang" 605 module ietf-datastores { 606 yang-version 1.1; 607 namespace "urn:ietf:params:xml:ns:yang:ietf-datastores"; 608 prefix ds; 610 organization 611 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 613 contact 614 "WG Web: 616 WG List: 618 Author: Martin Bjorklund 619 621 Author: Juergen Schoenwaelder 622 624 Author: Phil Shafer 625 627 Author: Kent Watsen 628 630 Author: Rob Wilton 631 "; 633 description 634 "This YANG module defines a set of identities for datastores. 635 These identities can be used to identify datastores in protocol 636 operations. 638 Copyright (c) 2017 IETF Trust and the persons identified as 639 authors of the code. All rights reserved. 641 Redistribution and use in source and binary forms, with or 642 without modification, is permitted pursuant to, and subject to 643 the license terms contained in, the Simplified BSD License set 644 forth in Section 4.c of the IETF Trust's Legal Provisions 645 Relating to IETF Documents 646 (http://trustee.ietf.org/license-info). 648 This version of this YANG module is part of RFC XXXX 649 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 650 for full legal notices."; 652 revision 2017-03-13 { 653 description 654 "Initial revision."; 655 reference 656 "RFC XXXX: Network Management Datastore Architecture"; 657 } 659 /* 660 * Identities 661 */ 663 identity datastore { 664 description 665 "Abstract base identity for datastore identities."; 666 } 668 identity static { 669 description 670 "Abstract base identity for static configuration datastores."; 671 } 673 identity dynamic { 674 description 675 "Abstract base identity for dynamic configuration datastores."; 676 } 678 identity running { 679 base static; 680 description 681 "The 'running' datastore."; 682 } 684 identity candidate { 685 base static; 686 description 687 "The 'candidate' datastore."; 688 } 690 identity startup { 691 base static; 692 description 693 "The 'startup' datastore."; 694 } 696 identity intended { 697 base static; 698 description 699 "The 'intended' datastore."; 700 } 702 identity operational { 703 base datastore; 704 description 705 "The 'operational' state datastore."; 706 } 708 } 710 712 file "ietf-datastores@2017-03-13.yang" 714 module ietf-origin { 715 yang-version 1.1; 716 namespace "urn:ietf:params:xml:ns:yang:ietf-origin"; 717 prefix or; 719 import ietf-yang-metadata { 720 prefix md; 721 } 723 organization 724 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 726 contact 727 "WG Web: 729 WG List: 731 Author: Martin Bjorklund 732 734 Author: Juergen Schoenwaelder 735 737 Author: Phil Shafer 738 740 Author: Kent Watsen 741 743 Author: Rob Wilton 744 "; 746 description 747 "This YANG module defines an 'origin' metadata annotation, and a 748 set of identities for the origin value. The 'origin' metadata 749 annotation is used to mark data in the 'operational' 750 datastore with information on where the data originated. 752 Copyright (c) 2017 IETF Trust and the persons identified as 753 authors of the code. All rights reserved. 755 Redistribution and use in source and binary forms, with or 756 without modification, is permitted pursuant to, and subject to 757 the license terms contained in, the Simplified BSD License set 758 forth in Section 4.c of the IETF Trust's Legal Provisions 759 Relating to IETF Documents 760 (http://trustee.ietf.org/license-info). 762 This version of this YANG module is part of RFC XXXX 763 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 764 for full legal notices."; 766 revision 2017-03-13 { 767 description 768 "Initial revision."; 769 reference 770 "RFC XXXX: Network Management Datastore Architecture"; 771 } 773 /* 774 * Identities 775 */ 777 identity origin { 778 description 779 "Abstract base identity for the origin annotation."; 780 } 782 identity static { 783 base origin; 784 description 785 "Denotes data from static configuration (e.g., )."; 786 } 787 identity dynamic { 788 base origin; 789 description 790 "Denotes data from dynamic configuration protocols 791 or dynamic datastores (e.g., DHCP)."; 792 } 794 identity system { 795 base origin; 796 description 797 "Denotes data created by the system independently of what 798 has been configured."; 799 } 801 identity default { 802 base origin; 803 description 804 "Denotes data that does not have an explicitly configured 805 value, but has a default value in use. Covers both simple 806 defaults and defaults defined via an explanation in a 807 description statement."; 808 } 810 /* 811 * Metadata annotations 812 */ 814 md:annotation origin { 815 type identityref { 816 base origin; 817 } 818 } 820 } 822 824 7. IANA Considerations 826 7.1. Updates to the IETF XML Registry 828 This document registers two URIs in the IETF XML registry [RFC3688]. 829 Following the format in [RFC3688], the following registrations are 830 requested: 832 URI: urn:ietf:params:xml:ns:yang:ietf-datastores 833 Registrant Contact: The IESG. 834 XML: N/A, the requested URI is an XML namespace. 836 URI: urn:ietf:params:xml:ns:yang:ietf-origin 837 Registrant Contact: The IESG. 838 XML: N/A, the requested URI is an XML namespace. 840 7.2. Updates to the YANG Module Names Registry 842 This document registers two YANG modules in the YANG Module Names 843 registry [RFC6020]. Following the format in [RFC6020], the the 844 following registrations are requested: 846 name: ietf-datastores 847 namespace: urn:ietf:params:xml:ns:yang:ietf-datastores 848 prefix: ds 849 reference: RFC XXXX 851 name: ietf-origin 852 namespace: urn:ietf:params:xml:ns:yang:ietf-origin 853 prefix: or 854 reference: RFC XXXX 856 8. Security Considerations 858 This document discusses a conceptual model of datastores for network 859 management using NETCONF/RESTCONF and YANG. It has no security 860 impact on the Internet. 862 9. Acknowledgments 864 This document grew out of many discussions that took place since 865 2010. Several Internet-Drafts ([I-D.bjorklund-netmod-operational], 866 [I-D.wilton-netmod-opstate-yang], [I-D.ietf-netmod-opstate-reqs], 867 [I-D.kwatsen-netmod-opstate], [I-D.openconfig-netmod-opstate]) and 868 [RFC6244] touched on some of the problems of the original datastore 869 model. The following people were authors to these Internet-Drafts or 870 otherwise actively involved in the discussions that led to this 871 document: 873 o Lou Berger, LabN Consulting, L.L.C., 875 o Andy Bierman, YumaWorks, 877 o Marcus Hines, Google, 879 o Christian Hopps, Deutsche Telekom, 880 o Acee Lindem, Cisco Systems, 882 o Ladislav Lhotka, CZ.NIC, 884 o Thomas Nadeau, Brocade Networks, 886 o Anees Shaikh, Google, 888 o Rob Shakir, Google, 890 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 891 Excellence project (ICT-318488) supported by the European Commission 892 under its Seventh Framework Programme. 894 10. References 896 10.1. Normative References 898 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 899 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 900 RFC2119, March 1997, 901 . 903 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 904 and A. Bierman, Ed., "Network Configuration Protocol 905 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 906 . 908 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 909 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 910 . 912 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 913 RFC 7950, DOI 10.17487/RFC7950, August 2016, 914 . 916 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 917 7952, DOI 10.17487/RFC7952, August 2016, 918 . 920 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 921 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 922 . 924 10.2. Informative References 926 [I-D.bjorklund-netmod-operational] 927 Bjorklund, M. and L. Lhotka, "Operational Data in NETCONF 928 and YANG", draft-bjorklund-netmod-operational-00 (work in 929 progress), October 2012. 931 [I-D.ietf-netmod-opstate-reqs] 932 Watsen, K. and T. Nadeau, "Terminology and Requirements 933 for Enhanced Handling of Operational State", draft-ietf- 934 netmod-opstate-reqs-04 (work in progress), January 2016. 936 [I-D.ietf-netmod-rfc6087bis] 937 Bierman, A., "Guidelines for Authors and Reviewers of YANG 938 Data Model Documents", draft-ietf-netmod-rfc6087bis-12 939 (work in progress), March 2017. 941 [I-D.kwatsen-netmod-opstate] 942 Watsen, K., Bierman, A., Bjorklund, M., and J. 943 Schoenwaelder, "Operational State Enhancements for YANG, 944 NETCONF, and RESTCONF", draft-kwatsen-netmod-opstate-02 945 (work in progress), February 2016. 947 [I-D.openconfig-netmod-opstate] 948 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 949 of Operational State Data in YANG", draft-openconfig- 950 netmod-opstate-01 (work in progress), July 2015. 952 [I-D.wilton-netmod-opstate-yang] 953 Wilton, R., ""With-config-state" Capability for NETCONF/ 954 RESTCONF", draft-wilton-netmod-opstate-yang-02 (work in 955 progress), December 2015. 957 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 958 DOI 10.17487/RFC3688, January 2004, 959 . 961 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 962 the Network Configuration Protocol (NETCONF)", RFC 6020, 963 DOI 10.17487/RFC6020, October 2010, 964 . 966 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 967 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 968 . 970 [RFC6244] Shafer, P., "An Architecture for Network Management Using 971 NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244, June 972 2011, . 974 Appendix A. Example Data 976 The use of datastores is complex, and many of the subtle effects are 977 more easily presented using examples. This section presents a series 978 of example data models with some sample contents of the various 979 datastores. 981 A.1. System Example 983 In this example, the following fictional module is used: 985 module example-system { 986 yang-version 1.1; 987 namespace urn:example:system; 988 prefix sys; 990 import ietf-inet-types { 991 prefix inet; 992 } 994 container system { 995 leaf hostname { 996 type string; 997 } 999 list interface { 1000 key name; 1002 leaf name { 1003 type string; 1004 } 1006 container auto-negotiation { 1007 leaf enabled { 1008 type boolean; 1009 default true; 1010 } 1011 leaf speed { 1012 type uint32; 1013 units mbps; 1014 description 1015 "The advertised speed, in mbps."; 1016 } 1017 } 1018 leaf speed { 1019 type uint32; 1020 units mbps; 1021 config false; 1022 description 1023 "The speed of the interface, in mbps."; 1024 } 1026 list address { 1027 key ip; 1029 leaf ip { 1030 type inet:ip-address; 1031 } 1032 leaf prefix-length { 1033 type uint8; 1034 } 1035 } 1036 } 1037 } 1038 } 1040 The operator has configured the host name and two interfaces, so the 1041 contents of is: 1043 1045 foo 1047 1048 eth0 1049 1050 1000 1051 1052
1053 2001:db8::10 1054 32 1055
1056 1058 1059 eth1 1060
1061 2001:db8::20 1062 32 1063
1064 1066 1068 The system has detected that the hardware for one of the configured 1069 interfaces ("eth1") is not yet present, so the configuration for that 1070 interface is not applied. Further, the system has received a host 1071 name and an additional IP address for "eth0" over DHCP. In addition 1072 to a default value, a loopback interface is automatically added by 1073 the system, and the result of the "speed" auto-negotiation. All of 1074 this is reflected in : 1076 1080 bar 1082 1083 eth0 1084 1085 true 1086 1000 1087 1088 100 1089
1090 2001:db8::10 1091 32 1092
1093
1094 2001:db8::1:100 1095 32 1096
1097 1099 1100 lo0 1101
1102 ::1 1103 128 1104
1105 1107 1109 A.2. BGP Example 1111 Consider the following piece of a ersatz BGP module: 1113 container bgp { 1114 leaf local-as { 1115 type uint32; 1116 } 1117 leaf peer-as { 1118 type uint32; 1119 } 1120 list peer { 1121 key name; 1122 leaf name { 1123 type ipaddress; 1124 } 1125 leaf local-as { 1126 type uint32; 1127 description 1128 ".... Defaults to ../local-as"; 1129 } 1130 leaf peer-as { 1131 type uint32; 1132 description 1133 "... Defaults to ../peer-as"; 1134 } 1135 leaf local-port { 1136 type inet:port; 1137 } 1138 leaf remote-port { 1139 type inet:port; 1140 default 179; 1141 } 1142 leaf state { 1143 config false; 1144 type enumeration { 1145 enum init; 1146 enum established; 1147 enum closing; 1148 } 1149 } 1150 } 1151 } 1153 In this example model, both bgp/peer/local-as and bgp/peer/peer-as 1154 have complex hierarchical values, allowing the user to specify 1155 default values for all peers in a single location. 1157 The model also follows the pattern of fully integrating state 1158 ("config false") nodes with configuration ("config true") nodes. 1159 There is not separate "bgp-state" hierarchy, with the accompanying 1160 repetition of containment and naming nodes. This makes the model 1161 simpler and more readable. 1163 A.2.1. Datastores 1165 Each datastore represents differing views of these data nodes. The 1166 datastore will hold the configuration data provided by the 1167 user, for example a single BGP peer. The datastore will 1168 conceptually hold the data as validated, after the removal of data 1169 not intended for validation and after any local template mechanisms 1170 are performed. The datastore will show data from 1171 as well as any "config false" nodes. 1173 A.2.2. Adding a Peer 1175 If the user configures a single BGP peer, then that peer will be 1176 visible in both the and datastores. It may also 1177 appear in the datastore, if the server supports the 1178 "candidate" feature. Retrieving the peer will return only the user- 1179 specified values. 1181 No time delay should exist between the appearance of the peer in 1182 and . 1184 In this scenario, we've added the following to : 1186 1187 64642 1188 65000 1189 1190 10.1.2.3 1191 1192 1194 A.2.2.1. 1196 The datastore will contain the fully expanded peer 1197 data, including "config false" nodes. In our example, this means the 1198 "state" node will appear. 1200 In addition, the datastore will contain the "currently 1201 in use" values for all nodes. This means that local-as and peer-as 1202 will be populated even if they are not given values in . 1203 The value of bgp/local-as will be used if bgp/peer/local-as is not 1204 provided; bgp/peer-as and bgp/peer/peer-as will have the same 1205 relationship. In the operational view, this means that every peer 1206 will have values for their local-as and peer-as, even if those values 1207 are not explicitly configured but are provided by bgp/local-as and 1208 bgp/peer-as. 1210 Each BGP peer has a TCP connection associated with it, using the 1211 values of local-port and remote-port from the intended datastore. If 1212 those values are not supplied, the system will select values. When 1213 the connection is established, the datastore will 1214 contain the current values for the local-port and remote-port nodes 1215 regardless of the origin. If the system has chosen the values, the 1216 "origin" attribute will be set to "operational". Before the 1217 connection is established, one or both of the nodes may not appear, 1218 since the system may not yet have their values. 1220 1221 64642 1222 65000 1223 1224 10.1.2.3 1225 64642 1226 65000 1227 60794 1228 179 1229 1230 1232 A.2.3. Removing a Peer 1234 Changes to configuration data may take time to percolate through the 1235 various software components involved. During this period, it is 1236 imperative to continue to give an accurate view of the working of the 1237 device. The datastore will return data nodes for both 1238 the previous and current configuration, as closely as possible 1239 tracking the current operation of the device. 1241 Consider the scenario where a client removes a BGP peer. When a peer 1242 is removed, the operational state will continue to reflect the 1243 existence of that peer until the peer's resources are released, 1244 including closing the peer's connection. During this period, the 1245 current data values will continue to be visible in the 1246 datastore, with the "origin" attribute set to indicate the origin of 1247 the original data. 1249 1250 64642 1251 65000 1252 1253 10.1.2.3 1254 64642 1255 65000 1256 60794 1257 179 1258 1259 1261 Once resources are released and the connection is closed, the peer's 1262 data is removed from the datastore. 1264 A.3. Interface Example 1266 In this section, we'll use this simple interface data model: 1268 container interfaces { 1269 list interface { 1270 key name; 1271 leaf name { 1272 type string; 1273 } 1274 leaf description { 1275 type string; 1276 } 1277 leaf mtu { 1278 type uint; 1279 } 1280 leaf ipv4-address { 1281 type inet:ipv4-address; 1282 } 1283 } 1284 } 1286 A.3.1. Pre-provisioned Interfaces 1288 One common issue in networking devices is the support of Field 1289 Replaceable Units (FRUs) that can be inserted and removed from the 1290 device without requiring a reboot or interfering with normal 1291 operation. These FRUs are typically interface cards, and the devices 1292 support pre-provisioning of these interfaces. 1294 If a client creates an interface "et-0/0/0" but the interface does 1295 not physically exist at this point, then the datastore 1296 might contain the following: 1298 1299 1300 et-0/0/0 1301 Test interface 1302 1303 1305 Since the interface does not exist, this data does not appear in the 1306 datastore. 1308 When a FRU containing this interface is inserted, the system will 1309 detect it and process the associated configuration. The 1310 will contain the data from , as well as the 1311 "config false" nodes, such as the current value of the interface's 1312 MTU. 1314 1315 1316 et-0/0/0 1317 Test interface 1318 1500 1319 1320 1322 If the FRU is removed, the interface data is removed from the 1323 datastore. 1325 A.3.2. System-provided Interface 1327 Imagine if the system provides a loopback interface (named "lo0") 1328 with a default ipv4-address of "127.0.0.1". The system will only 1329 provide configuration for this interface if the is no data for it in 1330 . 1332 When no configuration for "lo0" appears in , then 1333 will show the system-provided data: 1335 1336 1337 lo0 1338 127.0.0.1 1339 1340 1342 When configuration for "lo0" does appear in , then 1343 will show that data with the origin set to "intended". 1344 If the "ipv4-address" is not provided, then the system-provided value 1345 will appear as follows: 1347 1348 1349 lo0 1350 loopback 1351 127.0.0.1 1352 1353 1355 Appendix B. Ephemeral Dynamic Datastore Example 1357 The section defines documentation for an example dynamic datastore 1358 using the guidelines provided in Section 5. While this example is 1359 very terse, it is expected to be that a standalone RFC would be 1360 needed when fully expanded. 1362 This example defines a dynamic datastore called "ephemeral", which is 1363 loosely modeled after the work done in the I2RS working group. 1365 1. Name : ephemeral 1366 2. YANG modules : all (default) 1367 3. YANG statements : config false + ephemeral true 1368 4. How applied : automatic 1369 5. Protocols : NC/RC (default) 1370 6. YANG Module : (see below) 1372 module example-ds-ephemeral { 1373 yang-version 1.1; 1374 namespace "urn:example:ds-ephemeral"; 1375 prefix eph; 1377 import ietf-datastores { 1378 prefix ds; 1379 } 1380 import ietf-origin { 1381 prefix or; 1382 } 1384 // add datastore identity 1385 identity ds-ephemeral { 1386 base ds:datastore; 1387 description 1388 "The 'ephemeral' datastore."; 1389 } 1391 // add origin identity 1392 identity or-ephemeral { 1393 base or:dynamic; 1394 description 1395 "Denotes data from the ephemeral dynamic datastore."; 1396 } 1398 // define ephemeral extension 1399 extension ephemeral { 1400 argument "value"; 1401 description 1402 "This extension is mixed into config false YANG nodes to 1403 indicate that they are writable nodes in the 'ephemeral' 1404 datastore. This statement takes a single argument 1405 representing a boolean having the values 'true' and 'false'. 1406 The default value is 'false'."; 1407 } 1408 } 1410 Appendix C. Implications on Data Models 1412 Since the NETCONF operation returns the content of the 1413 configuration datastore and the operational state together 1414 in one tree, data models were often forced to branch at the top-level 1415 into a config true branch and a structurally similar config false 1416 branch that replicated some of the config true nodes and added state 1417 nodes. With the datastore model described here this is not needed 1418 anymore since the different datastores handle the different lifetimes 1419 of data objects. Introducing this model together with the 1420 deprecation of the operation makes it possible to write 1421 simpler models. 1423 C.1. Proposed migration of existing YANG Data Models 1425 For standards based YANG modules that have already been published, 1426 that are using split config and state trees, it is planned that these 1427 modules are updated with new revisions containing the following 1428 changes: 1430 o The top level module description is updated to indicate that the 1431 module conforms to the revised datastore architecture with a 1432 combined config and state tree, and that the existing state tree 1433 nodes are deprecated, to be obsoleted over time. 1435 o All status "current" data nodes under the existing "state" trees 1436 are copied to the equivalent place under the "config" tree: 1438 * If a node with the same name and type already exists under the 1439 equivalent path in the config tree then the nodes are merged 1440 and the description updated. 1442 * If a node with the same name but different type exists under 1443 the equivalent path in the config tree, then the module authors 1444 must choose the appropriate mechanism to combine the config and 1445 state nodes in a backwards compatible way based on the data 1446 model design guidelines below. This may require the state node 1447 to be added to the config tree with a modified name. This 1448 scenario is expected to be relatively uncommon. 1450 * If no node with the same name and path already exists under the 1451 config tree then the state node schema is copied verbatim into 1452 the config tree. 1454 * As the state nodes are copied into the config trees, any 1455 leafrefs that reference other nodes in the state tree are 1456 adjusted to reference the equivalent path in the config tree. 1458 * All status "current" nodes under the existing "state" trees are 1459 marked as "status" deprecated. 1461 o Augmentations are similarly handled to data nodes as described 1462 above. 1464 C.2. Standardization of new YANG Data Models 1466 New standards based YANG modules, or those in active development, 1467 should be designed to conform to the revised datastore architecture, 1468 following the design guidelines described below, and only need to 1469 provide combined config/state trees. 1471 Appendix D. Implications on other Documents 1473 The sections below describe the authors' thoughts on how various 1474 other documents may be updated to support the datastore architecture 1475 described in this document. They have been incorporated as an 1476 appendix of this document to facilitate easier review, but the 1477 expectation is that this work will be moved into another document as 1478 soon as the appropriate working group decides to take on the work. 1480 D.1. Implications on YANG 1482 Note: This section describes the authors' thoughts on how YANG 1483 [RFC7950] could be updated to support the datastore architecture 1484 described in this document. It has been incorporated here as a 1485 temporary measure to facilitate easier review, but the expectation is 1486 that this work will be owned and standardized via the NETCONF working 1487 group. 1489 o Some clarifications may be needed if this datastore model is 1490 adopted. YANG currently describes validation in terms of the 1491 configuration datastore while it really happens on the 1492 configuration datastore. 1494 D.2. Implications on YANG Library 1496 Note: This section describes the authors' thoughts on how YANG 1497 Library [RFC7895] could be updated to support the datastore 1498 architecture described in this document. It has been incorporated 1499 here as a temporary measure to facilitate easier review, but the 1500 expectation is that this work will be owned and standardized via the 1501 NETCONF working group. 1503 With the introduction of multiple datastores, it is important that a 1504 server can advertise to clients which modules are supported in the 1505 different datastores implemented by the server. In order to do this, 1506 we propose that the "ietf-yang-module" ([RFC7895]) is revised, with 1507 the following addition to the "module" list in the "module-list" 1508 grouping: 1510 leaf-list datastore { 1511 type identityref { 1512 base ds:datastore; 1513 } 1514 description 1515 "The datastores in which this module is supported."; 1517 } 1519 D.3. Implications to YANG Guidelines 1521 Note: This section describes the authors' thoughts on how Guidelines 1522 for Authors and Reviewers of YANG Data Model Documents 1523 [I-D.ietf-netmod-rfc6087bis] could be updated to support the 1524 datastore architecture described in this document. It has been 1525 incorporated here as a temporary measure to facilitate easier review, 1526 but the expectation is that this work will be owned and standardized 1527 via the NETCONF working group. 1529 It is important to design data models with clear semantics that work 1530 equally well for instantiation in a configuration datastore and 1531 instantiation in the datastore. 1533 D.3.1. Nodes with different config/state value sets 1535 There may be some differences in the value set of some nodes that are 1536 used for both configuration and state. At this point of time, these 1537 are considered to be rare cases that can be dealt with using 1538 different nodes for the configured and state values. 1540 D.3.2. Auto-configured or Auto-negotiated Values 1542 Sometimes configuration leafs support special values that instruct 1543 the system to automatically configure a value. An example is an MTU 1544 that is configured to "auto" to let the system determine a suitable 1545 MTU value. Another example is Ethernet auto-negotiation of link 1546 speed. In such a situation, it is recommended to model this as two 1547 separate leafs, one config true leaf for the input to the auto- 1548 negotiation process, and one config false leaf for the output from 1549 the process. 1551 D.4. Implications on NETCONF 1553 Note: This section describes the authors' thoughts on how NETCONF 1554 [RFC6241] could be updated to support the datastore architecture 1555 described in this document. It has been incorporated here as a 1556 temporary measure to facilitate easier review, but the expectation is 1557 that this work will be owned and standardized via the NETCONF working 1558 group. 1560 D.4.1. Introduction 1562 The NETCONF protocol [RFC6241] defines a simple mechanism through 1563 which a network device can be managed, configuration data information 1564 can be retrieved, and new configuration data can be uploaded and 1565 manipulated. 1567 NETCONF already has support for configuration datastores, but it does 1568 not define an operational datastore. Instead, it provides the 1569 operation that returns the contents of the datastore along 1570 with all config false leaves. However, this operation is 1571 incompatible with the new datastore architecture defined in this 1572 document, and hence should be deprecated. 1574 There are two possible ways that NETCONF could be extended to support 1575 the new architecture: Either as new optional capabilities extending 1576 the current version of NETCONF (v1.1, [RFC6241]), or by defining a 1577 new version of NETCONF. 1579 Many of the required additions are common to both approaches, and are 1580 described below. A following section then describes the benefits of 1581 defining a new NETCONF version, and the additional changes that would 1582 entail. 1584 D.4.2. Overview of additions to NETCONF 1586 o A new "supported datastores" capability allows a device to list 1587 all datastores it supports. Implementations can choose which 1588 datastores they expose, but MUST at least expose both the 1589 and datastores. They MAY expose 1590 additional datastores, such as , , etc. 1592 o A new operation is introduced that allows the client to 1593 return the contents of a datastore. For configuration datastores, 1594 this operation returns the same data that would be returned by the 1595 existing operation. 1597 o Some form of new filtering mechanism is required to allow the 1598 device to filter the data based on the YANG metadata in addition 1599 to other filters (such as the subtree filter). See also 1600 Appendix E. 1602 o A new "with-metadata" capability allows a device to indicate that 1603 it supports the capability of including YANG metadata annotations 1604 in the responses to and requests. This is 1605 achieved in a similar way to with-defaults [RFC6243], by 1606 introducing a XML element to and 1607 requests. 1609 * The capability would allow a device to indicate which types of 1610 metadata are supported. 1612 * The XML element would specify which types of metadata are 1613 included in the response. 1615 o The handling of defaults for the new configuration datastores is 1616 as described in with-defaults [RFC6243], but that does not apply 1617 for the operational state datastore that defines new semantics. 1619 D.4.2.1. Operational State Datastore Defaults Handling 1621 The normal semantics for the datastore are that all 1622 values that match the default specified in the schema are included in 1623 response to requests on the operational state datastore. This is 1624 equivalent to the "report-all" mode of the with-defaults handling. 1626 The "metadata-filter" query parameter can be used to exclude nodes 1627 with origin metadata matching "default", that would exclude nodes 1628 that match the default value specified in the schema. 1630 If the server cannot return a value for any reason (e.g., the server 1631 cannot determine the value, or the value that would be returned is 1632 outside the allowed leaf value range) then the server can choose to 1633 not return any value for a particular leaf, which MUST be interpreted 1634 by the client as the value of that leaf not being known, rather than 1635 implicitly having the default value. 1637 D.4.3. Overview of NETCONF version 2 1639 This section describes NETCONF version 2, by explaining the 1640 differences to NETCONF version 1.1. Where not explicitly specified, 1641 the behavior of NETCONF version 2 is the same as for NETCONF version 1642 1.1 [RFC6241]. 1644 D.4.3.1. Benefits of defining a new NETCONF version 1646 Defining a new version of NETCONF (as opposed to extending NETCONF 1647 version 1.1) has several benefits: 1649 o It allows for removal of the existing RPC operation, that 1650 returns content from both the running configuration datastore 1651 combined with all config false leaves. 1653 o It could allow the existing operation to also be 1654 removed, replaced by the more generic that is named 1655 appropriately to also apply to the operational datastore. 1657 o It makes it easier for clients and servers to know what reasonable 1658 common baseline functionality to expect, rather than a collection 1659 of capabilities that may not be implemented in a consistent 1660 fashion. In particular, clients will able to assume support for 1661 the datastore. 1663 o It can gracefully coexist with NETCONF v1.1. A server could 1664 implement both versions. Existing YANG models exposing split 1665 config/state trees could be exposed via NETCONF v1.1, whereas 1666 combined config/state YANG models could be exposed via NETCONF v2, 1667 providing a viable server upgrade path. 1669 D.4.3.2. Proposed changes for NETCONF v2 1671 The differences between NETCONF v2 and NETCONF v1.1 can be summarized 1672 as: 1674 o NETCONF v2 advertises a new base NETCONF capability 1675 "urn:ietf:params:netconf:base:2.0". A server may advertise older 1676 NETCONF versions as well, to allow a client to choose which 1677 version to use. 1679 o NETCONF v2 removes support for the existing operation, that 1680 is replaced by the on the operational datastore. 1682 o NETCONF v2 can publish a separate version of YANG library from a 1683 NETCONF v1.1 implementation running on the same device, allowing 1684 different versions of NETCONF to support a different set of YANG 1685 modules. 1687 D.4.3.3. Possible Migration Paths 1689 A common approach in current data models is to have two separate 1690 trees "/foo" and "/foo-state", where the former contains config true 1691 nodes, and the latter config false nodes. A data model that is 1692 designed for the revised architectural framework presented in this 1693 document will have a single tree "/foo" with a combination of config 1694 true and config false nodes. 1696 Two different migration strategies are considered: 1698 D.4.3.3.1. Migration Path using two instances of NETCONF 1700 If, for backwards compatability reasons, a server intends to support 1701 both split config/state trees and the combined config/state trees 1702 proposed in this architecture, then this can be achieved by having 1703 the device support both NETCONF v1 and NETCONF v2 at the same time: 1705 o The NETCONF v1 implementation could support existing YANG module 1706 revisions defined with split config/state trees. 1708 o The NETCONF v2 implementation could support different YANG 1709 modules, or YANG module revisions, with combined config/state 1710 trees. 1712 Clients can then decide on which type of models to use by expressing 1713 the appropriate version of the base NETCONF capability during 1714 capability exchange. 1716 D.4.3.3.2. Migration Path using a single instance of NETCONF 1718 The proposed strategy for updating existing published data models is 1719 to publish new revisions with the state trees' nodes copied under the 1720 config tree, and for the existing state trees to have all of their 1721 nodes marked as deprecated. The expectation is that NETCONF servers 1722 would use a combination of these updated models alongside new models 1723 that only follow the new datastore architecture. 1725 o NETCONF servers can support clients that are not aware of the 1726 revised datastore architecture, particularly if they continue to 1727 support the deprecated operation: 1729 * For updated YANG modules they would see additional information 1730 returned via the operation. 1732 * For new YANG modules, some of the state nodes may not be 1733 available, i.e. for any state nodes that exist under a config 1734 node that has not been configured (e.g., statistics under a 1735 system created interface). 1737 o NETCONF servers can also support clients that are aware of the 1738 revised datastores architecture: 1740 * For updated YANG modules they would see additional information 1741 returned under the legacy state trees. This information can be 1742 excluded using appropriate subtree filters. 1744 * New YANG modules, conforming to the datastores architecture, 1745 would work exactly as expected. 1747 D.5. Implications on RESTCONF 1749 This section describes the authors' thoughts on how RESTCONF 1750 [RFC8040] could be updated to support the datastore architecture 1751 described in this document. It has been incorporated here as a 1752 temporary measure to facilitate easier review, but the expectation is 1753 that this work will be owned and standardized via the NETCONF working 1754 group. 1756 D.5.1. Introduction 1758 RESTCONF [RFC8040] defines a protocol based on HTTP for configuring 1759 data defined in YANG version 1 or 1.1, using a conceptual datastore 1760 that is compatible with a server that implements NETCONF 1.1 1761 compliant datastores. 1763 The combined conceptual datastore defined in RESTCONF is incompatible 1764 with the new datastore architecture defined in this document. There 1765 are two possible ways that RESTCONF could be extended to support the 1766 new architecture: Either as new optional capabilities extending the 1767 existing RESTCONF RFC, or possibly as an new version of RESTCONF. 1769 Many of the required additions are common to both approaches, and are 1770 described below. A following section then describes the potential 1771 benefits of defining a new RESTCONF version, and the additional 1772 changes that might entail. 1774 D.5.2. Overview of additions to RESTCONF 1776 o A new path {+restconf}/datastore//data/ to provide 1777 a YANG data tree for each datastore that is exposed via RESTCONF. 1779 o Implementations can choose which datastores they expose, but MUST 1780 at least expose both the and datastores. 1781 They MAY expose the datastores as needed. 1783 o The same HTTP Methods supported on {+restconf}/data/ are also 1784 supported on {+restconf}/datastore//data/ but 1785 suitably constrained depending on whether the datastore can be 1786 written to by the client, or is read-only. 1788 o The same query parameters supported on {+restconf}/data/ are also 1789 support on {+restconf}/datastore//data/ except for 1790 the following query parameters: 1792 o "metadata" - is a new optional query parameter that filters the 1793 returned data based on the metadata annotation. 1795 o "with-metadata" - is a new optional query parameter that 1796 indicating that the metadata annotations should be included in the 1797 reply. 1799 o "with-defaults" is supported on all configuration datastores, but 1800 is not supported on the operational state datastore path, because 1801 it has different default handling semantics. 1803 o The handling of defaults (include the with-defaults query 1804 parameter) for the new configuration datastores is the same as the 1805 existing conceptual datastore, but does not apply for the 1806 operational state datastore that defines new semantics. 1808 D.5.2.1. HTTP Methods 1810 All configuration datastores support all HTTP Methods. 1812 The datastore only supports the following HTTP methods: 1813 OPTIONS, HEAD, GET, and POST to invoke an RFC operation. 1815 D.5.2.2. Query parameters 1817 [RFC7952] specifies how a YANG data tree can be annotated with 1818 generic metadata information, that is used by this document to 1819 annotate data nodes with origin information indicating the mechanism 1820 by which the operational value came into effect. 1822 RESTCONF could be extended with an optional generic mechanism to 1823 allow the filtering of nodes returned in a query based on metadata 1824 annotations associated with the data node. 1826 RESTCONF could also be extended with an optional generic mechanism to 1827 choose whether metadata annotations should be included in the 1828 response, potentially filtering to a subset of annotations. E.g., 1829 only include @origin metadata annotations, and not any others that 1830 may be in use. 1832 Both of the generic mechanisms could be controlled by a new 1833 capability. A new capability is defined to indicate whether a device 1834 supports filtering on, or annotating responses with, the origin meta 1835 data. 1837 D.5.2.3. Operational State Datastore Defaults Handling 1839 The normal semantics for the datastore are that all 1840 values that match the default specified in the schema are included in 1841 response to requests on the operational state datastore. This is 1842 equivalent to the "report-all" mode of the with-defaults handling. 1844 The "metadata" query parameter can be used to exclude nodes with a 1845 origin metadata matching "default", that would exclude (only config 1846 true?) nodes that match the default value specified in the schema. 1848 If the server cannot return a value for any reason (e.g., the server 1849 cannot determine the value, or the value that would be returned is 1850 outside the allowed leaf value range) then the server can choose to 1851 not return any value for a particular leaf, which MUST be interpreted 1852 by the client as the value of that leaf not being known, rather than 1853 implicitly having the default value. 1855 D.5.3. Overview of a possible new RESTCONF version 1857 This section describes a notional new RESTCONF version, by explaining 1858 the differences to RESTCONF version 1. Where not explicitly 1859 specified, the behavior of a new RESTCONF version is the same as for 1860 RESTCONF version 1 [RFC8040]. 1862 D.5.3.1. Potential benefits of defining a new RESTCONF version 1864 Defining a new version of RESTCONF (as opposed to extending RESTCONF 1865 version 1) has several potential benefits: 1867 o It could expose datastores, and models designed for the revised 1868 datastore architecture, in a clean and consistent way. 1870 o It would allow the parts of RESTCONF that do not work well with 1871 the revised datastore architecture to be omitted from the new 1872 RESTCONF version. 1874 o It would make it easier for clients and servers to know what 1875 reasonable common baseline functionality to expect, rather than a 1876 collection of capabilities that may not be implemented in a 1877 consistent fashion. 1879 o It could gracefully coexist with RESTCONF v1. A server could 1880 implement both versions. Existing YANG models exposing split 1881 config/state trees could be exposed via RESTCONF v1, whereas 1882 combined config/state YANG models could be exposed via a new 1883 RESTCONF version, providing a viable server upgrade path. 1885 D.5.3.2. Possible changes for a new RESTCONF version 1887 The differences between a notional new RESTCONF version and RESTCONF 1888 version 1 (RESTCONF v1) [RFC8040] can be summarized as: 1890 o A new RESTCONF version would define a new root resource, and a 1891 separate link relation in the /.well-known/host-meta resource. 1893 o A new RESTCONF version could remove support for the 1894 {+restconf}/data path supported in RESTCONF v1. 1896 o A new RESTCONF version could publish a separate version of YANG 1897 library from a RESTCONF v1 implementation running on the same 1898 device, allowing different versions of RESTCONF to support a 1899 different set of YANG modules. 1901 D.5.3.3. Possible Migration Path using a new RESTCONF version 1903 A common approach in current data models is to have two separate 1904 trees "/foo" and "/foo-state", where the former contains config true 1905 nodes, and the latter config false nodes. A data model that is 1906 designed for the revised architectural framework presented in this 1907 document will have a single tree "/foo" with a combination of config 1908 true and config false nodes. 1910 If for backwards compatability reasons, a server intends to support 1911 both split config/state trees, and the combined config/state trees 1912 proposed in this architecture, then this could be achieved by having 1913 the device support both RESTCONF v1 and the new RESTCONF version at 1914 the same time: 1916 o The RESTCONF v1 implementation could support existing YANG module 1917 revisions defined with split config/state trees. 1919 o The implementation of the new RESTCONF version could support 1920 different YANG modules, or YANG module revisions, with combined 1921 config/state trees. 1923 Clients can then decide on which type of models to use by choosing 1924 whether to use the RESTCONF v1 root resource or the root resource 1925 associated with the new RESTCONF version. 1927 Appendix E. Open Issues 1929 1. NETCONF needs to be able to filter data based on the origin 1930 metadata. Possibly this could be done as part of the 1931 operation. 1933 2. We need a means of inheriting @origin values, so whole 1934 hierarchies can avoid the noise of repeating parent values. 1935 Should "origin='system'" (or whatever we call it) be the default? 1937 3. We need to discuss somewhere how remote procedure calls and 1938 notifications/actions tie into datastores. RFC 7950 shows as an 1939 example a ping action tied to an interface. Does this refer to 1940 an interface defined in a configuration datastore? Or an 1941 interface defined in the operational state datastore? Or the 1942 applied configuration datastore? Similarly, RFC 7950 shows an 1943 example of a link-failure notification; this likely applies 1944 implicitly to the operational state datastore. The netconf- 1945 config-change notification does explicitly identify a datastore. 1946 I think we generally need to have remote procedure calls and 1947 notifications be explicit about which datastores they apply to 1948 and perhaps change the default xpath context from running plus 1949 state to the operational state datastore. 1951 Authors' Addresses 1953 Martin Bjorklund 1954 Tail-f Systems 1956 Email: mbj@tail-f.com 1958 Juergen Schoenwaelder 1959 Jacobs University 1961 Email: j.schoenwaelder@jacobs-university.de 1963 Phil Shafer 1964 Juniper Networks 1966 Email: phil@juniper.net 1968 Kent Watsen 1969 Juniper Networks 1971 Email: kwatsen@juniper.net 1973 Rob Wilton 1974 Cisco Systems 1976 Email: rwilton@cisco.com