idnits 2.17.1 draft-ietf-netmod-revised-datastores-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 3, 2017) is 2489 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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: January 4, 2018 Jacobs University 6 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 July 3, 2017 13 Network Management Datastore Architecture 14 draft-ietf-netmod-revised-datastores-03 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 January 4, 2018. 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. Background . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.1. Original Model of Datastores . . . . . . . . . . . . . . 6 63 4. Architectural Model of Datastores . . . . . . . . . . . . . . 8 64 4.1. The Startup Configuration Datastore () . . . . . 9 65 4.2. The Candidate Configuration Datastore () . . . 10 66 4.3. The Running Configuration Datastore () . . . . . 10 67 4.4. The Intended Configuration Datastore () . . . . 10 68 4.5. Conventional Configuration Datastores . . . . . . . . . . 11 69 4.6. Dynamic Datastores . . . . . . . . . . . . . . . . . . . 11 70 4.7. The Operational State Datastore () . . . . . 11 71 4.7.1. Missing Resources . . . . . . . . . . . . . . . . . . 12 72 4.7.2. System-controlled Resources . . . . . . . . . . . . . 13 73 4.7.3. Origin Metadata Annotation . . . . . . . . . . . . . 13 74 5. Implications on YANG . . . . . . . . . . . . . . . . . . . . 14 75 5.1. XPath Context . . . . . . . . . . . . . . . . . . . . . . 14 76 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 15 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 78 7.1. Updates to the IETF XML Registry . . . . . . . . . . . . 21 79 7.2. Updates to the YANG Module Names Registry . . . . . . . . 22 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 81 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 82 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 83 10.1. Normative References . . . . . . . . . . . . . . . . . . 23 84 10.2. Informative References . . . . . . . . . . . . . . . . . 23 85 Appendix A. Guidelines for Defining Datastores . . . . . . . . . 24 86 A.1. Define which YANG modules can be used in the datastore . 24 87 A.2. Define which subset of YANG-modeled data applies . . . . 25 88 A.3. Define how data is actualized . . . . . . . . . . . . . . 25 89 A.4. Define which protocols can be used . . . . . . . . . . . 25 90 A.5. Define YANG identities for the datastore . . . . . . . . 25 91 Appendix B. Ephemeral Dynamic Datastore Example . . . . . . . . 25 92 Appendix C. Example Data . . . . . . . . . . . . . . . . . . . . 27 93 C.1. System Example . . . . . . . . . . . . . . . . . . . . . 27 94 C.2. BGP Example . . . . . . . . . . . . . . . . . . . . . . . 29 95 C.2.1. Datastores . . . . . . . . . . . . . . . . . . . . . 31 96 C.2.2. Adding a Peer . . . . . . . . . . . . . . . . . . . . 31 97 C.2.3. Removing a Peer . . . . . . . . . . . . . . . . . . . 32 98 C.3. Interface Example . . . . . . . . . . . . . . . . . . . . 33 99 C.3.1. Pre-provisioned Interfaces . . . . . . . . . . . . . 33 100 C.3.2. System-provided Interface . . . . . . . . . . . . . . 34 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 103 1. Introduction 105 This document provides an architectural framework for datastores as 106 they are used by network management protocols such as NETCONF 107 [RFC6241], RESTCONF [RFC8040] and the YANG [RFC7950] data modeling 108 language. Datastores are a fundamental concept binding network 109 management data models to network management protocols. Agreement on 110 a common architectural model of datastores ensures that data models 111 can be written in a network management protocol agnostic way. This 112 architectural framework identifies a set of conceptual datastores but 113 it does not mandate that all network management protocols expose all 114 these conceptual datastores. This architecture is agnostic with 115 regard to the encoding used by network management protocols. 117 2. Terminology 119 This document defines the following terms: 121 o datastore: A conceptual place to store and access information. A 122 datastore might be implemented, for example, using files, a 123 database, flash memory locations, or combinations thereof. A 124 datastore maps to an instantiated YANG data tree. 126 o configuration: Data that is required to get a device from its 127 initial default state into a desired operational state. This data 128 is modeled in YANG using "config true" nodes. Configuration can 129 originate from different sources. 131 o configuration datastore: A datastore holding configuration. 133 o running configuration datastore: A configuration datastore holding 134 the current configuration of the device. It may include inactive 135 configuration or template-mechanism-oriented configuration that 136 require further expansion. This datastore is commonly referred to 137 as "". 139 o candidate configuration datastore: A configuration datastore that 140 can be manipulated without impacting the device's running 141 configuration datastore and that can be committed to the running 142 configuration datastore. This datastore is commonly referred to 143 as "". 145 o startup configuration datastore: A configuration datastore holding 146 the configuration loaded by the device into the running 147 configuration datastore when it boots. This datastore is commonly 148 referred to as "". 150 o intended configuration: Configuration that is intended to be used 151 by the device. For example, intended configuration excludes any 152 inactive configuration and it would include configuration produced 153 through the expansion of templates. 155 o intended configuration datastore: A configuration datastore 156 holding the complete intended configuration of the device. This 157 datastore is commonly referred to as "". 159 o conventional configuration datastore: One of the following set of 160 configuration datastores: , , , and 161 . These datastores share a common schema and protocol 162 operations allow copying data between these datastores. The term 163 "conventional" is chosen as a generic umbrella term for these 164 datastores. 166 o conventional configuration: Configuration that is stored in any of 167 the conventional configuration datastores. 169 o dynamic datastore: A datastore holding data obtained dynamically 170 during the operation of a device through interaction with other 171 systems, rather than through one of the conventional configuration 172 datastores. 174 o dynamic configuration: Configuration obtained via a dynamic 175 datastore. 177 o learned configuration: Configuration that has been learned via 178 protocol interactions with other systems that is not conventional 179 or dynamic configuration. 181 o system configuration: Configuration that is supplied by the device 182 itself. 184 o default configuration: Configuration that is not explicitly 185 provided but for which a value defined in the data model is used. 187 o applied configuration: Configuration that is actively in use by a 188 device. Applied configuration originates from conventional, 189 dynamic, learned, system and default configuration. 191 o system state: The additional data on a system that is not 192 configuration, such as read-only status information and collected 193 statistics. System state is transient and modified by 194 interactions with internal components or other systems. System 195 state is modeled in YANG using "config false" nodes. 197 o operational state: The combination of applied configuration and 198 system state. 200 o operational state datastore: A datastore holding the complete 201 operational state of the device. This datastore is commonly 202 referred to as "". 204 o origin: A metadata annotation indicating the origin of a data 205 item. 207 o remnant configuration: Configuration that remains part of the 208 applied configuration for a period of time after it has been 209 removed from the intended configuration or dynamic configuration. 210 The time period may be minimal, or may last until all resources 211 used by the newly-deleted configuration (e.g., network 212 connections, memory allocations, file handles) have been 213 deallocated. 215 The following additional terms are not datastore specific but 216 commonly used and thus defined here as well: 218 o client: An entity that can access YANG-defined data on a server, 219 over some network management protocol. 221 o server: An entity that provides access to YANG-defined data to a 222 client, over some network management protocol. 224 o notification: A server-initiated message indicating that a certain 225 event has been recognized by the server. 227 o remote procedure call: An operation that can be invoked by a 228 client on a server. 230 3. Background 232 NETCONF [RFC6241] provides the following definitions: 234 o datastore: A conceptual place to store and access information. A 235 datastore might be implemented, for example, using files, a 236 database, flash memory locations, or combinations thereof. 238 o configuration datastore: The datastore holding the complete set of 239 configuration that is required to get a device from its initial 240 default state into a desired operational state. 242 YANG 1.1 [RFC7950] provides the following refinements when NETCONF is 243 used with YANG (which is the usual case but note that NETCONF was 244 defined before YANG existed): 246 o datastore: When modeled with YANG, a datastore is realized as an 247 instantiated data tree. 249 o configuration datastore: When modeled with YANG, a configuration 250 datastore is realized as an instantiated data tree with 251 configuration. 253 [RFC6244] defined operational state data as follows: 255 o Operational state data is a set of data that has been obtained by 256 the system at runtime and influences the system's behavior similar 257 to configuration data. In contrast to configuration data, 258 operational state is transient and modified by interactions with 259 internal components or other systems via specialized protocols. 261 Section 4.3.3 of [RFC6244] discusses operational state and among 262 other things mentions the option to consider operational state as 263 being stored in another datastore. Section 4.4 of this document then 264 concludes that at the time of the writing, modeling state as distinct 265 leafs and distinct branches is the recommended approach. 267 Implementation experience and requests from operators 268 [I-D.ietf-netmod-opstate-reqs], [I-D.openconfig-netmod-opstate] 269 indicate that the datastore model initially designed for NETCONF and 270 refined by YANG needs to be extended. In particular, the notion of 271 intended configuration and applied configuration has developed. 273 Furthermore, separating operational state from configuration in a 274 separate branch in the data model has been found operationally 275 complicated, and typically impacts the readability of module 276 definitions due to overuse of groupings. The relationship between 277 the branches is not machine readable and filter expressions operating 278 on configuration and on related operational state are different. 280 3.1. Original Model of Datastores 282 The following drawing shows the original model of datastores as it is 283 currently used by NETCONF [RFC6241]: 285 +-------------+ +-----------+ 286 | | | | 287 | (ct, rw) |<---+ +--->| (ct, rw) | 288 +-------------+ | | +-----------+ 289 | | | | 290 | +-----------+ | 291 +-------->| |<--------+ 292 | (ct, rw) | 293 +-----------+ 294 | 295 v 296 operational state <--- control plane 297 (cf, ro) 299 ct = config true; cf = config false 300 rw = read-write; ro = read-only 301 boxes denote datastores 303 Note that this diagram simplifies the model: read-only (ro) and read- 304 write (rw) is to be understood at a conceptual level. In NETCONF, 305 for example, support for and is optional and 306 does not have to be writable. Furthermore, can 307 only be modified by copying to in the 308 standardized NETCONF datastore editing model. The RESTCONF protocol 309 does not expose these differences and instead provides only a 310 writable unified datastore, which hides whether edits are done 311 through or by directly modifying or via some 312 other implementation specific mechanism. RESTCONF also hides how 313 configuration is made persistent. Note that implementations may also 314 have additional datastores that can propagate changes to . 315 NETCONF explicitly mentions so called named datastores. 317 Some observations: 319 o Operational state has not been defined as a datastore although 320 there were proposals in the past to introduce an operational state 321 datastore. 323 o The NETCONF operation returns the content of the 324 configuration datastore together with the operational state. It 325 is therefore necessary that "config false" data is in a different 326 branch than the "config true" data if the operational state can 327 have a different lifetime compared to configuration or if 328 configuration is not immediately or successfully applied. 330 o Several implementations have proprietary mechanisms that allow 331 clients to store inactive data in ; this inactive data is 332 only exposed to clients that indicate that they support the 333 concept of inactive data; clients not indicating support for 334 inactive data receive the content of with the inactive 335 data removed. Inactive data is conceptually removed before 336 validation. 338 o Some implementations have proprietary mechanisms that allow 339 clients to define configuration templates in . These 340 templates are expanded automatically by the system, and the 341 resulting configuration is applied internally. 343 o Some operators have reported that it is essential for them to be 344 able to retrieve the configuration that has actually been 345 successfully applied, which may be a subset or a superset of the 346 configuration. 348 4. Architectural Model of Datastores 350 Below is a new conceptual model of datastores extending the original 351 model in order to reflect the experience gained with the original 352 model. 354 +-------------+ +-----------+ 355 | | | | 356 | (ct, rw) |<---+ +--->| (ct, rw) | 357 +-------------+ | | +-----------+ 358 | | | | 359 | +-----------+ | 360 +-------->| |<--------+ 361 | (ct, rw) | 362 +-----------+ 363 | 364 | // configuration transformations, 365 | // e.g., removal of "inactive" 366 | // nodes, expansion of templates 367 v 368 +------------+ 369 | | // subject to validation 370 | (ct, ro) | 371 +------------+ 372 | // changes applied, subject to 373 | // local factors, e.g., missing 374 | // resources, delays 375 | 376 | +-------- learned configuration 377 dynamic | +-------- system configuration 378 datastores -----+ | +-------- default configuration 379 | | | 380 v v v 381 +---------------+ 382 | | <-- system state 383 | (ct + cf, ro) | 384 +---------------+ 386 ct = config true; cf = config false 387 rw = read-write; ro = read-only 388 boxes denote named datastores 390 4.1. The Startup Configuration Datastore () 392 The startup configuration datastore () is an optional 393 configuration datastore holding the configuration loaded by the 394 device when it boots. is only present on devices that 395 separate the startup configuration from the running configuration 396 datastore. 398 The startup configuration datastore may not be supported by all 399 protocols or implementations. 401 On devices that support non-volatile storage, the contents of 402 will typically persist across reboots via that storage. At 403 boot time, the device loads the saved startup configuration into 404 . To save a new startup configuration, data is copied to 405 , either via implicit or explicit protocol operations. 407 4.2. The Candidate Configuration Datastore () 409 The candidate configuration datastore () is an optional 410 configuration datastore that can be manipulated without impacting the 411 device's current configuration and that can be committed to 412 . 414 The candidate configuration datastore may not be supported by all 415 protocols or implementations. 417 does not typically persist across reboots, even in the 418 presence of non-volatile storage. If is stored using 419 non-volatile storage, it should be reset at boot time to the contents 420 of . 422 4.3. The Running Configuration Datastore () 424 The running configuration datastore () holds the complete 425 current configuration on the device. It may include inactive 426 configuration or template-mechanism-oriented configuration that 427 require further expansion. 429 If a device does not have a distinct and non-volatile is 430 available, the device will typically use that non-volatile storage to 431 allow to persist across reboots. 433 4.4. The Intended Configuration Datastore () 435 The intended configuration datastore () is a read-only 436 configuration datastore. It is tightly coupled to . When 437 data is written to , the data that is to be validated is 438 also conceptually written to . Validation is performed on 439 the contents of . 441 For simple implementations, and are identical. 443 does not persist across reboots; its relationship with 444 makes that unnecessary. 446 Currently there are no standard mechanisms defined that affect 447 so that it would have different contents than , 448 but this architecture allows for such mechanisms to be defined. 450 One example of such a mechanism is support for marking nodes as 451 inactive in . Inactive nodes are not copied to , 452 and are thus not taken into account when validating the 453 configuration. 455 Another example is support for templates. Templates are expanded 456 when copied into , and the expanded result is validated. 458 4.5. Conventional Configuration Datastores 460 The conventional configuration datastores are a set of configuration 461 datastores that share a common schema, allowing data to be copied 462 between them. The term is meant as a generic umbrella description of 463 these datastores. The set of datastores include: 465 o 467 o 469 o 471 o 473 Other conventional configuration datastores may be defined in future 474 documents. 476 The flow of data between these datastores is depicted in section 477 Section 4. 479 The specific protocols may define explicit operations to copy between 480 these datastores, e.g., NETCONF's operation. 482 4.6. Dynamic Datastores 484 The model recognizes the need for dynamic datastores that are, by 485 definition, not part of the persistent configuration of a device. In 486 some contexts, these have been termed ephemeral datastores since the 487 information is ephemeral, i.e., lost upon reboot. The dynamic 488 datastores interact with the rest of the system through 489 . 491 4.7. The Operational State Datastore () 493 The operational state datastore () is a read-only 494 datastore that consists of all "config true" and "config false" nodes 495 defined in the schema. In the original NETCONF model the operational 496 state only had "config false" nodes. The reason for incorporating 497 "config true" nodes here is to be able to expose all operational 498 settings without having to replicate definitions in the data models. 500 contains system state and all configuration actually 501 used by the system. This includes all applied configuration from 502 , system-provided configuration, and default values defined 503 by any supported data models. In addition, also 504 contains applied data from dynamic datastores. 506 Requests to retrieve nodes from always return the value 507 in use if the node exists, regardless of any default value specified 508 in the YANG module. If no value is returned for a given node, then 509 this implies that the node is not used by the device. 511 does not persist across reboots. 513 Changes to configuration may take time to percolate through to 514 . During this period, may contain nodes 515 for both the previous and current configuration, as closely as 516 possible tracking the current operation of the device. Such remnant 517 configuration from the previous configuration persists until the 518 system has released resources used by the newly-deleted configuration 519 (e.g., network connections, memory allocations, file handles). 521 As a result of remnant configuration, the semantic constraints 522 defined in the data model cannot be relied upon for , 523 since the system may have remnant configuration whose constraints 524 were valid with the previous configuration and that are not valid 525 with the current configuration. Since constraints on "config false" 526 nodes may refer to "config true" nodes, remnant configuration may 527 force the violation of those constraints. The constraints that may 528 not hold include "when", "must", "min-elements", and "max-elements". 529 Note that syntactic constraints cannot be violated, including 530 hierarchical organization, identifiers, and type-based constraints. 532 4.7.1. Missing Resources 534 Configuration in can refer to resources that are not 535 available or otherwise not physically present. In these situations, 536 these parts of the configuration are not applied. The 537 data appears in but does not appear in . 539 A typical example is an interface configuration that refers to an 540 interface that is not currently present. In such a situation, the 541 interface configuration remains in but the interface 542 configuration will not appear in . 544 Note that configuration validity cannot depend on the current state 545 of such resources, since that would imply the removing a resource 546 might render the configuration invalid. This is unacceptable, 547 especially given that rebooting such a device would fail to boot due 548 to an invalid configuration. Instead we allow configuration for 549 missing resources to exist in and , but it will 550 not appear in . 552 4.7.2. System-controlled Resources 554 Sometimes resources are controlled by the device and the 555 corresponding system controlled data appear in (and disappear from) 556 dynamically. If a system controlled resource has 557 matching configuration in when it appears, the system will 558 try to apply the configuration, which causes the configuration to 559 appear in eventually (if application of the 560 configuration was successful). 562 4.7.3. Origin Metadata Annotation 564 As data flows into , it is conceptually marked with a 565 metadata annotation ([RFC7952]) that indicates its origin. The 566 origin applies to all data nodes except non-presence containers. The 567 "origin" metadata annotation is defined in Section 6. The values are 568 YANG identities. The following identities are defined: 570 o origin: abstract base identity from which the other origin 571 identities are derived. 573 o intended: represents data provided by . 575 o dynamic: represents data provided by a dynamic datastore. 577 o system: represents data provided by the system itself, including 578 both system configuration and system state. Examples of system 579 configuration include applied configuration for an always existing 580 loopback interface, or interface configuration that is auto- 581 created due to the hardware currently present in the device. 583 o learned: represents configuration that has been learned via 584 protocol interactions with other systems, including protocols such 585 as link-layer negotiations, routing protocols, DHCP, etc. 587 o default: represents data using a default value specified in the 588 data model, using either values in the "default" statement or any 589 values described in the "description" statement. The default 590 origin is only used when the data has not been provided by any 591 other source. 593 o unknown: represents data for which the system cannot identify the 594 origin. 596 These identities can be further refined, e.g., there could be 597 separate identities for particular types or instances of dynamic 598 datastore derived from "dynamic". 600 In all cases, the device should report the origin that most 601 accurately reflects the source of the data that is actively being 602 used by the system. 604 In cases where it could be ambiguous as to which origin should be 605 used, i.e. where the same data node value has originated from 606 multiple sources, then the description statement in the YANG module 607 should be used as guidance for choosing the appropriate origin. For 608 example: 610 If for a particular configuration node, the associated YANG 611 description statement indicates that a protocol negotiated value 612 overrides any configured value, then the origin would be reported as 613 "learned", even when a learned value is the same as the configured 614 value. 616 Conversely, if for a particular configuration node, the associated 617 YANG description statement indicates that a protocol negotiated value 618 does not override an explicitly configured value, then the origin 619 would be reported as "intended" even when a learned value is the same 620 as the configured value. 622 In the case that a device cannot provide an accurate origin for a 623 particular data node then it should use the origin "unknown". 625 5. Implications on YANG 627 5.1. XPath Context 629 If a server implements the architecture defined in this document, the 630 accessible trees for some XPath contexts are refined as follows: 632 o If the XPath expression is defined in a substatement to a data 633 node that represents system state, the accessible tree is all 634 operational state in the server. The root node has all top-level 635 data nodes in all modules as children. 637 o If the XPath expression is defined in a substatement to a 638 "notification" statement, the accessible tree is the notification 639 instance and all operational state in the server. If the 640 notification is defined on the top level in a module, then the 641 root node has the node representing the notification being defined 642 and all top-level data nodes in all modules as children. 643 Otherwise, the root node has all top-level data nodes in all 644 modules as children. 646 o If the XPath expression is defined in a substatement to an "input" 647 statement in an "rpc" or "action" statement, the accessible tree 648 is the RPC or action operation instance and all operational state 649 in the server. The root node has top-level data nodes in all 650 modules as children. Additionally, for an RPC, the root node also 651 has the node representing the RPC operation being defined as a 652 child. The node representing the operation being defined has the 653 operation's input parameters as children. 655 o If the XPath expression is defined in a substatement to an 656 "output" statement in an "rpc" or "action" statement, the 657 accessible tree is the RPC or action operation instance and all 658 operational state in the server. The root node has top-level data 659 nodes in all modules as children. Additionally, for an RPC, the 660 root node also has the node representing the RPC operation being 661 defined as a child. The node representing the operation being 662 defined has the operation's output parameters as children. 664 6. YANG Modules 666 file "ietf-datastores@2017-04-26.yang" 668 module ietf-datastores { 669 yang-version 1.1; 670 namespace "urn:ietf:params:xml:ns:yang:ietf-datastores"; 671 prefix ds; 673 organization 674 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 676 contact 677 "WG Web: 679 WG List: 681 Author: Martin Bjorklund 682 684 Author: Juergen Schoenwaelder 685 687 Author: Phil Shafer 688 690 Author: Kent Watsen 691 693 Author: Rob Wilton 694 "; 696 description 697 "This YANG module defines two sets of identities for datastores. 698 The first identifies the datastores themselves, the second 699 identifies are for datastore protperties. 701 Copyright (c) 2017 IETF Trust and the persons identified as 702 authors of the code. All rights reserved. 704 Redistribution and use in source and binary forms, with or 705 without modification, is permitted pursuant to, and subject to 706 the license terms contained in, the Simplified BSD License set 707 forth in Section 4.c of the IETF Trust's Legal Provisions 708 Relating to IETF Documents 709 (http://trustee.ietf.org/license-info). 711 This version of this YANG module is part of RFC XXXX 712 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 713 for full legal notices."; 715 revision 2017-04-26 { 716 description 717 "Initial revision."; 718 reference 719 "RFC XXXX: Network Management Datastore Architecture"; 720 } 722 /* 723 * Identities 724 */ 726 identity datastore { 727 description 728 "Abstract base identity for datastore identities."; 729 } 731 identity conventional { 732 base datastore; 733 description 734 "Abstract base identity for conventional configuration 735 datastores."; 736 } 737 identity running { 738 base conventional; 739 description 740 "The running configuration datastore."; 741 } 743 identity candidate { 744 base conventional; 745 description 746 "The candidate configuration datastore."; 747 } 749 identity startup { 750 base conventional; 751 description 752 "The startup configuration datastore."; 753 } 755 identity intended { 756 base conventional; 757 description 758 "The intended configuration datastore."; 759 } 761 identity dynamic { 762 base datastore; 763 description 764 "Abstract base identity for dynamic datastores."; 765 } 767 identity operational { 768 base datastore; 769 description 770 "The operational state datastore."; 771 } 773 identity property { 774 description 775 "Abstract base identity for datastore identities."; 776 } 778 identity writable { 779 base property; 780 description 781 "Used on the 'running' datastore to indicate that it can be 782 written to."; 784 } 786 identity auto-persist { 787 base property; 788 description 789 "Used on the 'running' datastore to indicate that writes to 790 it will be automatically persisted. 792 If the 'startup' datastore is also supported, clients may 793 query its contents to ensure its synchronization. 795 If the 'startup' datastore is not supported, and this 796 property is not set, then clients must use a mechanism 797 provided by the protocol to explicitly persist the 798 'running' datastore's contents."; 799 } 801 identity rollback-on-error { 802 base property; 803 description 804 "Used on either the 'running' or 'candidate' datastores to 805 indicate that clients may request atomic update behavior."; 806 } 808 identity confirmed-commit { 809 base property; 810 description 811 "Used on the 'candidate' datastore to indicate that 812 clients may request confirmed-commit update behavior."; 813 } 815 identity validate { 816 base property; 817 description 818 "Used on the 'candidate' datastore to indicate that 819 clients may request datastore validation."; 820 } 822 } 824 826 file "ietf-origin@2017-04-26.yang" 828 module ietf-origin { 829 yang-version 1.1; 830 namespace "urn:ietf:params:xml:ns:yang:ietf-origin"; 831 prefix or; 833 import ietf-yang-metadata { 834 prefix md; 835 } 837 organization 838 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 840 contact 841 "WG Web: 843 WG List: 845 Author: Martin Bjorklund 846 848 Author: Juergen Schoenwaelder 849 851 Author: Phil Shafer 852 854 Author: Kent Watsen 855 857 Author: Rob Wilton 858 "; 860 description 861 "This YANG module defines an 'origin' metadata annotation, and a 862 set of identities for the origin value. 864 Copyright (c) 2017 IETF Trust and the persons identified as 865 authors of the code. All rights reserved. 867 Redistribution and use in source and binary forms, with or 868 without modification, is permitted pursuant to, and subject to 869 the license terms contained in, the Simplified BSD License set 870 forth in Section 4.c of the IETF Trust's Legal Provisions 871 Relating to IETF Documents 872 (http://trustee.ietf.org/license-info). 874 This version of this YANG module is part of RFC XXXX 875 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 876 for full legal notices."; 878 revision 2017-04-26 { 879 description 880 "Initial revision."; 881 reference 882 "RFC XXXX: Network Management Datastore Architecture"; 883 } 885 /* 886 * Identities 887 */ 889 identity origin { 890 description 891 "Abstract base identity for the origin annotation."; 892 } 894 identity intended { 895 base origin; 896 description 897 "Denotes data from the intended configuration datastore"; 898 } 900 identity dynamic { 901 base origin; 902 description 903 "Denotes data from a dynamic datastore."; 904 } 906 identity system { 907 base origin; 908 description 909 "Denotes data originated by the system itself, including 910 both system configuration and system state. 912 Examples of system configuration include applied configuration 913 for an always existing loopback interface, or interface 914 configuration that is auto-created due to the hardware 915 currently present in the device."; 916 } 918 identity learned { 919 base origin; 920 description 921 "Denotes configuration learned from protocol interactions with 922 other devices, instead of via the intended configuration 923 datastore or any dynamic datastore. 925 Examples of protocols that provide learned configuration 926 include link-layer negotiations, routing protocols, and 927 DHCP."; 928 } 930 identity default { 931 base origin; 932 description 933 "Denotes data that does not have an configured or learned 934 value, but has a default value in use. Covers both values 935 defined in a 'default' statement, and values defined via an 936 explanation in a 'description' statement."; 937 } 939 identity unknown { 940 base origin; 941 description 942 "Denotes data for which the system cannot identify the 943 origin."; 944 } 946 /* 947 * Metadata annotations 948 */ 950 md:annotation origin { 951 type identityref { 952 base origin; 953 } 954 description 955 "The 'origin' annotation can be present on any node in a 956 datastore. It specifies from where the node originated."; 957 } 959 } 961 963 7. IANA Considerations 965 7.1. Updates to the IETF XML Registry 967 This document registers two URIs in the IETF XML registry [RFC3688]. 968 Following the format in [RFC3688], the following registrations are 969 requested: 971 URI: urn:ietf:params:xml:ns:yang:ietf-datastores 972 Registrant Contact: The IESG. 973 XML: N/A, the requested URI is an XML namespace. 975 URI: urn:ietf:params:xml:ns:yang:ietf-origin 976 Registrant Contact: The IESG. 977 XML: N/A, the requested URI is an XML namespace. 979 7.2. Updates to the YANG Module Names Registry 981 This document registers two YANG modules in the YANG Module Names 982 registry [RFC6020]. Following the format in [RFC6020], the the 983 following registrations are requested: 985 name: ietf-datastores 986 namespace: urn:ietf:params:xml:ns:yang:ietf-datastores 987 prefix: ds 988 reference: RFC XXXX 990 name: ietf-origin 991 namespace: urn:ietf:params:xml:ns:yang:ietf-origin 992 prefix: or 993 reference: RFC XXXX 995 8. Security Considerations 997 This document discusses an architectural model of datastores for 998 network management using NETCONF/RESTCONF and YANG. It has no 999 security impact on the Internet. 1001 9. Acknowledgments 1003 This document grew out of many discussions that took place since 1004 2010. Several Internet-Drafts ([I-D.bjorklund-netmod-operational], 1005 [I-D.wilton-netmod-opstate-yang], [I-D.ietf-netmod-opstate-reqs], 1006 [I-D.kwatsen-netmod-opstate], [I-D.openconfig-netmod-opstate]) and 1007 [RFC6244] touched on some of the problems of the original datastore 1008 model. The following people were authors to these Internet-Drafts or 1009 otherwise actively involved in the discussions that led to this 1010 document: 1012 o Lou Berger, LabN Consulting, L.L.C., 1014 o Andy Bierman, YumaWorks, 1016 o Marcus Hines, Google, 1018 o Christian Hopps, Deutsche Telekom, 1019 o Acee Lindem, Cisco Systems, 1021 o Ladislav Lhotka, CZ.NIC, 1023 o Thomas Nadeau, Brocade Networks, 1025 o Anees Shaikh, Google, 1027 o Rob Shakir, Google, 1029 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 1030 Excellence project (ICT-318488) supported by the European Commission 1031 under its Seventh Framework Programme. 1033 10. References 1035 10.1. Normative References 1037 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1038 and A. Bierman, Ed., "Network Configuration Protocol 1039 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1040 . 1042 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1043 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1044 . 1046 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1047 RFC 7952, DOI 10.17487/RFC7952, August 2016, 1048 . 1050 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1051 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1052 . 1054 10.2. Informative References 1056 [I-D.bjorklund-netmod-operational] 1057 Bjorklund, M. and L. Lhotka, "Operational Data in NETCONF 1058 and YANG", draft-bjorklund-netmod-operational-00 (work in 1059 progress), October 2012. 1061 [I-D.ietf-netmod-opstate-reqs] 1062 Watsen, K. and T. Nadeau, "Terminology and Requirements 1063 for Enhanced Handling of Operational State", draft-ietf- 1064 netmod-opstate-reqs-04 (work in progress), January 2016. 1066 [I-D.kwatsen-netmod-opstate] 1067 Watsen, K., Bierman, A., Bjorklund, M., and J. 1068 Schoenwaelder, "Operational State Enhancements for YANG, 1069 NETCONF, and RESTCONF", draft-kwatsen-netmod-opstate-02 1070 (work in progress), February 2016. 1072 [I-D.openconfig-netmod-opstate] 1073 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 1074 of Operational State Data in YANG", draft-openconfig- 1075 netmod-opstate-01 (work in progress), July 2015. 1077 [I-D.wilton-netmod-opstate-yang] 1078 Wilton, R., ""With-config-state" Capability for NETCONF/ 1079 RESTCONF", draft-wilton-netmod-opstate-yang-02 (work in 1080 progress), December 2015. 1082 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1083 DOI 10.17487/RFC3688, January 2004, 1084 . 1086 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1087 the Network Configuration Protocol (NETCONF)", RFC 6020, 1088 DOI 10.17487/RFC6020, October 2010, 1089 . 1091 [RFC6244] Shafer, P., "An Architecture for Network Management Using 1092 NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244, June 1093 2011, . 1095 Appendix A. Guidelines for Defining Datastores 1097 The definition of a new datastore in this architecture should be 1098 provided in a document (e.g., an RFC) purposed to the definition of 1099 the datastore. When it makes sense, more than one datastore may be 1100 defined in the same document (e.g., when the datastores are logically 1101 connected). Each datastore's definition should address the points 1102 specified in the sections below. 1104 A.1. Define which YANG modules can be used in the datastore 1106 Not all YANG modules may be used in all datastores. Some datastores 1107 may constrain which data models can be used in them. If it is 1108 desirable that a subset of all modules can be targeted to the 1109 datastore, then the documentation defining the datastore must 1110 indicate this. 1112 A.2. Define which subset of YANG-modeled data applies 1114 By default, the data in a datastore is modeled by all YANG statements 1115 in the available YANG modules. However, it is possible to specify 1116 criteria that YANG statements must satisfy in order to be present in 1117 a datastore. For instance, maybe only "config true" nodes are 1118 present, or "config false nodes" that also have a specific YANG 1119 extension (e.g., "i2rs:ephemeral true") are present in the datastore. 1121 A.3. Define how data is actualized 1123 The new datastore must specify how it interacts with other 1124 datastores. For example, the diagram in Section 4 depicts dynamic 1125 datastores feeding into . How this interaction occurs 1126 must be defined by any dynamic datastore. In some cases, it may 1127 occur implicitly, as soon as the data is put into the dynamic 1128 datastore while, in other cases, an explicit action (e.g., an RPC) 1129 may be required to trigger the application of the datastore's data. 1131 A.4. Define which protocols can be used 1133 By default, it is assumed that both the NETCONF and RESTCONF 1134 protocols can be used to interact with a datastore. However, it may 1135 be that only a specific protocol can be used (e.g., ForCES) or that a 1136 subset of all protocol operations or capabilities are available 1137 (e.g., no locking or no XPath-based filtering). 1139 A.5. Define YANG identities for the datastore 1141 The datastore must be defined with a YANG identity that uses the 1142 "ds:datastore" identity or one of its derived identities as its base. 1143 This identity is necessary so that the datastore can be referenced in 1144 protocol operations (e.g., ). 1146 The datastore may also be defined with an identity that uses the 1147 "or:origin" identity or one its derived identities as its base. This 1148 identity is needed if the datastore interacts with so 1149 that data originating from the datastore can be identified as such 1150 via the "origin" metadata attribute defined in Section 6. 1152 An example of these guidelines in use is provided in Appendix B. 1154 Appendix B. Ephemeral Dynamic Datastore Example 1156 The section defines documentation for an example dynamic datastore 1157 using the guidelines provided in Appendix A. While this example is 1158 very terse, it is expected to be that a standalone RFC would be 1159 needed when fully expanded. 1161 This example defines a dynamic datastore called "ephemeral", which is 1162 loosely modeled after the work done in the I2RS working group. 1164 1. Name : ephemeral 1165 2. YANG modules : all (default) 1166 3. YANG statements : config false + ephemeral true 1167 4. How applied : automatic 1168 5. Protocols : NC/RC (default) 1169 6. YANG Module : (see below) 1171 module example-ds-ephemeral { 1172 yang-version 1.1; 1173 namespace "urn:example:ds-ephemeral"; 1174 prefix eph; 1176 import ietf-datastores { 1177 prefix ds; 1178 } 1179 import ietf-origin { 1180 prefix or; 1181 } 1183 // add datastore identity 1184 identity ds-ephemeral { 1185 base ds:datastore; 1186 description 1187 "The 'ephemeral' datastore."; 1188 } 1190 // add origin identity 1191 identity or-ephemeral { 1192 base or:dynamic; 1193 description 1194 "Denotes data from the ephemeral dynamic datastore."; 1195 } 1197 // define ephemeral extension 1198 extension ephemeral { 1199 argument "value"; 1200 description 1201 "This extension is mixed into config false YANG nodes to 1202 indicate that they are writable nodes in the 'ephemeral' 1203 datastore. This statement takes a single argument 1204 representing a boolean having the values 'true' and 1205 'false'. The default value is 'false'."; 1206 } 1207 } 1209 Appendix C. Example Data 1211 The use of datastores is complex, and many of the subtle effects are 1212 more easily presented using examples. This section presents a series 1213 of example data models with some sample contents of the various 1214 datastores. 1216 C.1. System Example 1218 In this example, the following fictional module is used: 1220 module example-system { 1221 yang-version 1.1; 1222 namespace urn:example:system; 1223 prefix sys; 1225 import ietf-inet-types { 1226 prefix inet; 1227 } 1229 container system { 1230 leaf hostname { 1231 type string; 1232 } 1234 list interface { 1235 key name; 1237 leaf name { 1238 type string; 1239 } 1241 container auto-negotiation { 1242 leaf enabled { 1243 type boolean; 1244 default true; 1245 } 1246 leaf speed { 1247 type uint32; 1248 units mbps; 1249 description 1250 "The advertised speed, in mbps."; 1251 } 1252 } 1254 leaf speed { 1255 type uint32; 1256 units mbps; 1257 config false; 1258 description 1259 "The speed of the interface, in mbps."; 1260 } 1262 list address { 1263 key ip; 1265 leaf ip { 1266 type inet:ip-address; 1267 } 1268 leaf prefix-length { 1269 type uint8; 1270 } 1271 } 1272 } 1273 } 1274 } 1276 The operator has configured the host name and two interfaces, so the 1277 contents of is: 1279 1281 foo 1283 1284 eth0 1285 1286 1000 1287 1288
1289 2001:db8::10 1290 32 1291
1292 1294 1295 eth1 1296
1297 2001:db8::20 1298 32 1299
1300 1302 1303 The system has detected that the hardware for one of the configured 1304 interfaces ("eth1") is not yet present, so the configuration for that 1305 interface is not applied. Further, the system has received a host 1306 name and an additional IP address for "eth0" over DHCP. In addition 1307 to a default value, a loopback interface is automatically added by 1308 the system, and the result of the "speed" auto-negotiation. All of 1309 this is reflected in : 1311 1315 bar 1317 1318 eth0 1319 1320 true 1321 1000 1322 1323 100 1324
1325 2001:db8::10 1326 64 1327
1328
1329 2001:db8::1:100 1330 64 1331
1332 1334 1335 lo0 1336
1337 ::1 1338 128 1339
1340 1342 1344 C.2. BGP Example 1346 Consider the following piece of a ersatz BGP module: 1348 container bgp { 1349 leaf local-as { 1350 type uint32; 1351 } 1352 leaf peer-as { 1353 type uint32; 1354 } 1355 list peer { 1356 key name; 1357 leaf name { 1358 type ipaddress; 1359 } 1360 leaf local-as { 1361 type uint32; 1362 description 1363 ".... Defaults to ../local-as"; 1364 } 1365 leaf peer-as { 1366 type uint32; 1367 description 1368 "... Defaults to ../peer-as"; 1369 } 1370 leaf local-port { 1371 type inet:port; 1372 } 1373 leaf remote-port { 1374 type inet:port; 1375 default 179; 1376 } 1377 leaf state { 1378 config false; 1379 type enumeration { 1380 enum init; 1381 enum established; 1382 enum closing; 1383 } 1384 } 1385 } 1386 } 1388 In this example model, both bgp/peer/local-as and bgp/peer/peer-as 1389 have complex hierarchical values, allowing the user to specify 1390 default values for all peers in a single location. 1392 The model also follows the pattern of fully integrating state 1393 ("config false") nodes with configuration ("config true") nodes. 1394 There is not separate "bgp-state" hierarchy, with the accompanying 1395 repetition of containment and naming nodes. This makes the model 1396 simpler and more readable. 1398 C.2.1. Datastores 1400 Each datastore represents differing views of these nodes. 1401 will hold the configuration provided by the user, for example a 1402 single BGP peer. will conceptually hold the data as 1403 validated, after the removal of data not intended for validation and 1404 after any local template mechanisms are performed. 1405 will show data from as well as any "config false" nodes. 1407 C.2.2. Adding a Peer 1409 If the user configures a single BGP peer, then that peer will be 1410 visible in both and . It may also appear in 1411 , if the server supports the "candidate" feature. 1412 Retrieving the peer will return only the user-specified values. 1414 No time delay should exist between the appearance of the peer in 1415 and . 1417 In this scenario, we've added the following to : 1419 1420 64642 1421 65000 1422 1423 10.1.2.3 1424 1425 1427 C.2.2.1. 1429 will contain the fully expanded peer data, including 1430 "config false" nodes. In our example, this means the "state" node 1431 will appear. 1433 In addition, will contain the "currently in use" values 1434 for all nodes. This means that local-as and peer-as will be 1435 populated even if they are not given values in . The value 1436 of bgp/local-as will be used if bgp/peer/local-as is not provided; 1437 bgp/peer-as and bgp/peer/peer-as will have the same relationship. In 1438 the operational view, this means that every peer will have values for 1439 their local-as and peer-as, even if those values are not explicitly 1440 configured but are provided by bgp/local-as and bgp/peer-as. 1442 Each BGP peer has a TCP connection associated with it, using the 1443 values of local-port and remote-port from . If those 1444 values are not supplied, the system will select values. When the 1445 connection is established, will contain the current 1446 values for the local-port and remote-port nodes regardless of the 1447 origin. If the system has chosen the values, the "origin" attribute 1448 will be set to "system". Before the connection is established, one 1449 or both of the nodes may not appear, since the system may not yet 1450 have their values. 1452 1453 64642 1454 65000 1455 1456 10.1.2.3 1457 64642 1458 65000 1459 60794 1460 179 1461 1462 1464 C.2.3. Removing a Peer 1466 Changes to configuration may take time to percolate through the 1467 various software components involved. During this period, it is 1468 imperative to continue to give an accurate view of the working of the 1469 device. will contain nodes for both the previous and 1470 current configuration, as closely as possible tracking the current 1471 operation of the device. 1473 Consider the scenario where a client removes a BGP peer. When a peer 1474 is removed, the operational state will continue to reflect the 1475 existence of that peer until the peer's resources are released, 1476 including closing the peer's connection. During this period, the 1477 current data values will continue to be visible in , 1478 with the "origin" attribute set to indicate the origin of the 1479 original data. 1481 1482 64642 1483 65000 1484 1485 10.1.2.3 1486 64642 1487 65000 1488 60794 1489 179 1490 1491 1493 Once resources are released and the connection is closed, the peer's 1494 data is removed from . 1496 C.3. Interface Example 1498 In this section, we'll use this simple interface data model: 1500 container interfaces { 1501 list interface { 1502 key name; 1503 leaf name { 1504 type string; 1505 } 1506 leaf description { 1507 type string; 1508 } 1509 leaf mtu { 1510 type uint; 1511 } 1512 leaf ipv4-address { 1513 type inet:ipv4-address; 1514 } 1515 } 1516 } 1518 C.3.1. Pre-provisioned Interfaces 1520 One common issue in networking devices is the support of Field 1521 Replaceable Units (FRUs) that can be inserted and removed from the 1522 device without requiring a reboot or interfering with normal 1523 operation. These FRUs are typically interface cards, and the devices 1524 support pre-provisioning of these interfaces. 1526 If a client creates an interface "et-0/0/0" but the interface does 1527 not physically exist at this point, then might contain the 1528 following: 1530 1531 1532 et-0/0/0 1533 Test interface 1534 1535 1537 Since the interface does not exist, this data does not appear in 1538 . 1540 When a FRU containing this interface is inserted, the system will 1541 detect it and process the associated configuration. The 1542 will contain the data from , as well as the 1543 "config false" nodes, such as the current value of the interface's 1544 MTU. 1546 1547 1548 et-0/0/0 1549 Test interface 1550 1500 1551 1552 1554 If the FRU is removed, the interface data is removed from 1555 . 1557 C.3.2. System-provided Interface 1559 Imagine if the system provides a loopback interface (named "lo0") 1560 with a default ipv4-address of "127.0.0.1". The system will only 1561 provide configuration for this interface if there is no data for it 1562 in . 1564 When no configuration for "lo0" appears in , then 1565 will show the system-provided data: 1567 1568 1569 lo0 1570 127.0.0.1 1571 1572 1574 When configuration for "lo0" does appear in , then 1575 will show that data with the origin set to "intended". 1576 If the "ipv4-address" is not provided, then the system-provided value 1577 will appear as follows: 1579 1580 1581 lo0 1582 loopback 1583 127.0.0.1 1584 1585 1587 Authors' Addresses 1589 Martin Bjorklund 1590 Tail-f Systems 1592 Email: mbj@tail-f.com 1594 Juergen Schoenwaelder 1595 Jacobs University 1597 Email: j.schoenwaelder@jacobs-university.de 1599 Phil Shafer 1600 Juniper Networks 1602 Email: phil@juniper.net 1604 Kent Watsen 1605 Juniper Networks 1607 Email: kwatsen@juniper.net 1609 Robert Wilton 1610 Cisco Systems 1612 Email: rwilton@cisco.com