idnits 2.17.1 draft-ietf-netmod-revised-datastores-02.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 (May 11, 2017) is 2541 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: November 12, 2017 Jacobs University 6 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 May 11, 2017 13 Network Management Datastore Architecture 14 draft-ietf-netmod-revised-datastores-02 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 November 12, 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. 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 . . . . . . . . . . 10 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 . . . . . . . . . . . . . 12 73 4.7.3. Origin Metadata Annotation . . . . . . . . . . . . . 12 74 5. Implications on YANG . . . . . . . . . . . . . . . . . . . . 14 75 5.1. XPath Context . . . . . . . . . . . . . . . . . . . . . . 14 76 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 15 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 78 7.1. Updates to the IETF XML Registry . . . . . . . . . . . . 20 79 7.2. Updates to the YANG Module Names Registry . . . . . . . . 20 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 81 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 82 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 83 10.1. Normative References . . . . . . . . . . . . . . . . . . 21 84 10.2. Informative References . . . . . . . . . . . . . . . . . 22 85 Appendix A. Guidelines for Defining Datastores . . . . . . . . . 23 86 A.1. Define which YANG modules can be used in the datastore . 23 87 A.2. Define which subset of YANG-modeled data applies . . . . 23 88 A.3. Define how data is actualized . . . . . . . . . . . . . . 23 89 A.4. Define which protocols can be used . . . . . . . . . . . 23 90 A.5. Define YANG identities for the datastore . . . . . . . . 24 91 Appendix B. Ephemeral Dynamic Datastore Example . . . . . . . . 24 92 Appendix C. Example Data . . . . . . . . . . . . . . . . . . . . 25 93 C.1. System Example . . . . . . . . . . . . . . . . . . . . . 26 94 C.2. BGP Example . . . . . . . . . . . . . . . . . . . . . . . 28 95 C.2.1. Datastores . . . . . . . . . . . . . . . . . . . . . 30 96 C.2.2. Adding a Peer . . . . . . . . . . . . . . . . . . . . 30 97 C.2.3. Removing a Peer . . . . . . . . . . . . . . . . . . . 31 98 C.3. Interface Example . . . . . . . . . . . . . . . . . . . . 32 99 C.3.1. Pre-provisioned Interfaces . . . . . . . . . . . . . 32 100 C.3.2. System-provided Interface . . . . . . . . . . . . . . 33 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 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 determines how a device behaves. This 127 data is modeled in YANG using "config true" nodes. Configuration 128 can originate from different sources. 130 o configuration datastore: A datastore holding configuration. 132 o running configuration datastore: A configuration datastore holding 133 the current configuration of the device. It may include inactive 134 configuration or template-mechanism-oriented configuration that 135 require further expansion. This datastore is commonly referred to 136 as "". 138 o candidate configuration datastore: A configuration datastore that 139 can be manipulated without impacting the device's running 140 configuration datastore and that can be committed to the running 141 configuration datastore. This datastore is commonly referred to 142 as "". 144 o startup configuration datastore: A configuration datastore holding 145 the configuration loaded by the device into the running 146 configuration datastore when it boots. This datastore is commonly 147 referred to as "". 149 o intended configuration: Configuration that is intended to be used 150 by the device. For example, intended configuration excludes any 151 inactive configuration and it would include configuration produced 152 through the expansion of templates. 154 o intended configuration datastore: A configuration datastore 155 holding the complete intended configuration of the device. This 156 datastore is commonly referred to as "". 158 o conventional configuration datastore: One of the following set of 159 configuration datastores: , , , and 160 . These datastores share a common schema and protocol 161 operations allow copying data between these datastores. The term 162 "conventional" is chosen as a generic umbrella term for these 163 datastores. 165 o conventional configuration: Configuration that is stored in any of 166 the conventional configuration datastores. 168 o dynamic datastore: A datastore holding data obtained dynamically 169 during the operation of a device through interaction with other 170 systems, rather than through one of the conventional configuration 171 datastores. 173 o dynamic configuration: Configuration obtained via a dynamic 174 datastore. 176 o learned configuration: Configuration that has been learned via 177 protocol interactions with other systems that is not conventional 178 or dynamic configuration. 180 o system configuration: Configuration that is supplied by the device 181 itself. 183 o default configuration: Configuration that is not explicitly 184 provided but for which a value defined in the data model is used. 186 o applied configuration: Configuration that is actively in use by a 187 device. Applied configuration originates from conventional, 188 dynamic, learned, system and default configuration. 190 o system state: The additional data on a system that is not 191 configuration, such as read-only status information and collected 192 statistics. System state is transient and modified by 193 interactions with internal components or other systems. System 194 state is modeled in YANG using "config false" nodes. 196 o operational state: The combination of applied configuration and 197 system state. 199 o operational state datastore: A datastore holding the complete 200 operational state of the device. This datastore is commonly 201 referred to as "". 203 o origin: A metadata annotation indicating the origin of a data 204 item. 206 o remnant configuration: Configuration that remains part of the 207 applied configuration for a period of time after it has been 208 removed from the intended configuration or dynamic configuration. 209 The time period may be minimal, or may last until all resources 210 used by the newly-deleted configuration (e.g., network 211 connections, memory allocations, file handles) have been 212 deallocated. 214 The following additional terms are not datastore specific but 215 commonly used and thus defined here as well: 217 o client: An entity that can access YANG-defined data on a server, 218 over some network management protocol. 220 o server: An entity that provides access to YANG-defined data to a 221 client, over some network management protocol. 223 o notification: A server-initiated message indicating that a certain 224 event has been recognized by the server. 226 o remote procedure call: An operation that can be invoked by a 227 client on a server. 229 3. Background 231 NETCONF [RFC6241] provides the following definitions: 233 o datastore: A conceptual place to store and access information. A 234 datastore might be implemented, for example, using files, a 235 database, flash memory locations, or combinations thereof. 237 o configuration datastore: The datastore holding the complete set of 238 configuration that is required to get a device from its initial 239 default state into a desired operational state. 241 YANG 1.1 [RFC7950] provides the following refinements when NETCONF is 242 used with YANG (which is the usual case but note that NETCONF was 243 defined before YANG existed): 245 o datastore: When modeled with YANG, a datastore is realized as an 246 instantiated data tree. 248 o configuration datastore: When modeled with YANG, a configuration 249 datastore is realized as an instantiated data tree with 250 configuration. 252 [RFC6244] defined operational state data as follows: 254 o Operational state data is a set of data that has been obtained by 255 the system at runtime and influences the system's behavior similar 256 to configuration data. In contrast to configuration data, 257 operational state is transient and modified by interactions with 258 internal components or other systems via specialized protocols. 260 Section 4.3.3 of [RFC6244] discusses operational state and among 261 other things mentions the option to consider operational state as 262 being stored in another datastore. Section 4.4 of this document then 263 concludes that at the time of the writing, modeling state as distinct 264 leafs and distinct branches is the recommended approach. 266 Implementation experience and requests from operators 267 [I-D.ietf-netmod-opstate-reqs], [I-D.openconfig-netmod-opstate] 268 indicate that the datastore model initially designed for NETCONF and 269 refined by YANG needs to be extended. In particular, the notion of 270 intended configuration and applied configuration has developed. 272 Furthermore, separating operational state from configuration in a 273 separate branch in the data model has been found operationally 274 complicated, and typically impacts the readability of module 275 definitions due to overuse of groupings. The relationship between 276 the branches is not machine readable and filter expressions operating 277 on configuration and on related operational state are different. 279 3.1. Original Model of Datastores 281 The following drawing shows the original model of datastores as it is 282 currently used by NETCONF [RFC6241]: 284 +-------------+ +-----------+ 285 | | | | 286 | (ct, rw) |<---+ +--->| (ct, rw) | 287 +-------------+ | | +-----------+ 288 | | | | 289 | +-----------+ | 290 +-------->| |<--------+ 291 | (ct, rw) | 292 +-----------+ 293 | 294 v 295 operational state <--- control plane 296 (cf, ro) 298 ct = config true; cf = config false 299 rw = read-write; ro = read-only 300 boxes denote datastores 302 Note that this diagram simplifies the model: read-only (ro) and read- 303 write (rw) is to be understood at a conceptual level. In NETCONF, 304 for example, support for and is optional and 305 does not have to be writable. Furthermore, can 306 only be modified by copying to in the 307 standardized NETCONF datastore editing model. The RESTCONF protocol 308 does not expose these differences and instead provides only a 309 writable unified datastore, which hides whether edits are done 310 through or by directly modifying or via some 311 other implementation specific mechanism. RESTCONF also hides how 312 configuration is made persistent. Note that implementations may also 313 have additional datastores that can propagate changes to . 314 NETCONF explicitly mentions so called named datastores. 316 Some observations: 318 o Operational state has not been defined as a datastore although 319 there were proposals in the past to introduce an operational state 320 datastore. 322 o The NETCONF operation returns the content of the 323 configuration datastore together with the operational state. It 324 is therefore necessary that "config false" data is in a different 325 branch than the "config true" data if the operational state can 326 have a different lifetime compared to configuration or if 327 configuration is not immediately or successfully applied. 329 o Several implementations have proprietary mechanisms that allow 330 clients to store inactive data in ; this inactive data is 331 only exposed to clients that indicate that they support the 332 concept of inactive data; clients not indicating support for 333 inactive data receive the content of with the inactive 334 data removed. Inactive data is conceptually removed before 335 validation. 337 o Some implementations have proprietary mechanisms that allow 338 clients to define configuration templates in . These 339 templates are expanded automatically by the system, and the 340 resulting configuration is applied internally. 342 o Some operators have reported that it is essential for them to be 343 able to retrieve the configuration that has actually been 344 successfully applied, which may be a subset or a superset of the 345 configuration. 347 4. Architectural Model of Datastores 349 Below is a new conceptual model of datastores extending the original 350 model in order to reflect the experience gained with the original 351 model. 353 +-------------+ +-----------+ 354 | | | | 355 | (ct, rw) |<---+ +--->| (ct, rw) | 356 +-------------+ | | +-----------+ 357 | | | | 358 | +-----------+ | 359 +-------->| |<--------+ 360 | (ct, rw) | 361 +-----------+ 362 | 363 | // configuration transformations, 364 | // e.g., removal of "inactive" 365 | // nodes, expansion of templates 366 v 367 +------------+ 368 | | // subject to validation 369 | (ct, ro) | 370 +------------+ 371 | // changes applied, subject to 372 | // local factors, e.g., missing 373 | // resources, delays 374 | 375 | +-------- learned configuration 376 dynamic | +-------- system configuration 377 datastores -----+ | +-------- default configuration 378 | | | 379 v v v 380 +---------------+ 381 | | <-- system state 382 | (ct + cf, ro) | 383 +---------------+ 385 ct = config true; cf = config false 386 rw = read-write; ro = read-only 387 boxes denote named datastores 389 4.1. The Startup Configuration Datastore () 391 The startup configuration datastore () is an optional 392 configuration datastore holding the configuration loaded by the 393 device when it boots. is only present on devices that 394 separate the startup configuration from the running configuration 395 datastore. 397 The startup configuration datastore may not be supported by all 398 protocols or implementations. 400 4.2. The Candidate Configuration Datastore () 402 The candidate configuration datastore () is an optional 403 configuration datastore that can be manipulated without impacting the 404 device's current configuration and that can be committed to 405 . 407 The candidate configuration datastore may not be supported by all 408 protocols or implementations. 410 4.3. The Running Configuration Datastore () 412 The running configuration datastore () holds the complete 413 current configuration on the device. It may include inactive 414 configuration or template-mechanism-oriented configuration that 415 require further expansion. 417 4.4. The Intended Configuration Datastore () 419 The intended configuration datastore () is a read-only 420 configuration datastore. It is tightly coupled to . When 421 data is written to , the data that is to be validated is 422 also conceptually written to . Validation is performed on 423 the contents of . 425 For simple implementations, and are identical. 427 Currently there are no standard mechanisms defined that affect 428 so that it would have different contents than , 429 but this architecture allows for such mechanisms to be defined. 431 One example of such a mechanism is support for marking nodes as 432 inactive in . Inactive nodes are not copied to , 433 and are thus not taken into account when validating the 434 configuration. 436 Another example is support for templates. Templates are expanded 437 when copied into , and the expanded result is validated. 439 4.5. Conventional Configuration Datastores 441 The conventional configuration datastores are a set of configuration 442 datastores that share a common schema, allowing data to be copied 443 between them. The term is meant as a generic umbrella description of 444 these datastores. The set of datastores include: 446 o 447 o 449 o 451 o 453 Other conventional configuration datastores may be defined in future 454 documents. 456 The flow of data between these datastores is depicted in section 457 Section 4. 459 The specific protocols may define explicit operations to copy between 460 these datastores, e.g., NETCONF's operation. 462 4.6. Dynamic Datastores 464 The model recognizes the need for dynamic datastores that are, by 465 definition, not part of the persistent configuration of a device. In 466 some contexts, these have been termed ephemeral datastores since the 467 information is ephemeral, i.e., lost upon reboot. The dynamic 468 datastores interact with the rest of the system through 469 . 471 4.7. The Operational State Datastore () 473 The operational state datastore () is a read-only 474 datastore that consists of all "config true" and "config false" nodes 475 defined in the schema. In the original NETCONF model the operational 476 state only had "config false" nodes. The reason for incorporating 477 "config true" nodes here is to be able to expose all operational 478 settings without having to replicate definitions in the data models. 480 contains system state and all configuration actually 481 used by the system. This includes all applied configuration from 482 , system-provided configuration, and default values defined 483 by any supported data models. In addition, also 484 contains applied data from dynamic datastores. 486 Changes to configuration may take time to percolate through to 487 . During this period, may contain nodes 488 for both the previous and current configuration, as closely as 489 possible tracking the current operation of the device. Such remnant 490 configuration from the previous configuration persists until the 491 system has released resources used by the newly-deleted configuration 492 (e.g., network connections, memory allocations, file handles). 494 As a result of remnant configuration, the semantic constraints 495 defined in the data model cannot be relied upon for , 496 since the system may have remnant configuration whose constraints 497 were valid with the previous configuration and that are not valid 498 with the current configuration. Since constraints on "config false" 499 nodes may refer to "config true" nodes, remnant configuration may 500 force the violation of those constraints. The constraints that may 501 not hold include "when", "must", "min-elements", and "max-elements". 502 Note that syntactic constraints cannot be violated, including 503 hierarchical organization, identifiers, and type-based constraints. 505 4.7.1. Missing Resources 507 Configuration in can refer to resources that are not 508 available or otherwise not physically present. In these situations, 509 these parts of the configuration are not applied. The 510 data appears in but does not appear in . 512 A typical example is an interface configuration that refers to an 513 interface that is not currently present. In such a situation, the 514 interface configuration remains in but the interface 515 configuration will not appear in . 517 Note that configuration validity cannot depend on the current state 518 of such resources, since that would imply the removing a resource 519 might render the configuration invalid. This is unacceptable, 520 especially given that rebooting such a device would fail to boot due 521 to an invalid configuration. Instead we allow configuration for 522 missing resources to exist in and , but it will 523 not appear in . 525 4.7.2. System-controlled Resources 527 Sometimes resources are controlled by the device and the 528 corresponding system controlled data appear in (and disappear from) 529 dynamically. If a system controlled resource has 530 matching configuration in when it appears, the system will 531 try to apply the configuration, which causes the configuration to 532 appear in eventually (if application of the 533 configuration was successful). 535 4.7.3. Origin Metadata Annotation 537 As data flows into , it is conceptually marked with a 538 metadata annotation ([RFC7952]) that indicates its origin. The 539 origin applies to all data nodes except non-presence containers. The 540 "origin" metadata annotation is defined in Section 6. The values are 541 YANG identities. The following identities are defined: 543 o origin: abstract base identity from which the other origin 544 identities are derived. 546 o intended: represents data provided by . 548 o dynamic: represents data provided by a dynamic datastore. 550 o system: represents data provided by the system itself, including 551 both system configuration and system state. Examples of system 552 configuration include applied configuration for an always existing 553 loopback interface, or interface configuration that is auto- 554 created due to the hardware currently present in the device. 556 o learned: represents configuration that has been learned via 557 protocol interactions with other systems, including protocols such 558 as link-layer negotiations, routing protocols, DHCP, etc. 560 o default: represents data using a default value specified in the 561 data model, using either values in the "default" statement or any 562 values described in the "description" statement. The default 563 origin is only used when the data has not been provided by any 564 other source. 566 o unknown: represents data for which the system cannot identify the 567 origin. 569 These identities can be further refined, e.g., there could be 570 separate identities for particular types or instances of dynamic 571 datastore derived from "dynamic". 573 In all cases, the device should report the origin that most 574 accurately reflects the source of the data that is actively being 575 used by the system. 577 In cases where it could be ambiguous as to which origin should be 578 used, i.e. where the same data node value has originated from 579 multiple sources, then the description statement in the YANG module 580 should be used as guidance for choosing the appropriate origin. For 581 example: 583 If for a particular configuration node, the associated YANG 584 description statement indicates that a protocol negotiated value 585 overrides any configured value, then the origin would be reported as 586 "learned", even when a learned value is the same as the configured 587 value. 589 Conversely, if for a particular configuration node, the associated 590 YANG description statement indicates that a protocol negotiated value 591 does not override an explicitly configured value, then the origin 592 would be reported as "intended" even when a learned value is the same 593 as the configured value. 595 In the case that a device cannot provide an accurate origin for a 596 particular data node then it should use the origin "unknown". 598 5. Implications on YANG 600 5.1. XPath Context 602 If a server implements the architecture defined in this document, the 603 accessible trees for some XPath contexts are refined as follows: 605 o If the XPath expression is defined in a substatement to a data 606 node that represents system state, the accessible tree is all 607 operational state in the server. The root node has all top-level 608 data nodes in all modules as children. 610 o If the XPath expression is defined in a substatement to a 611 "notification" statement, the accessible tree is the notification 612 instance and all operational state in the server. If the 613 notification is defined on the top level in a module, then the 614 root node has the node representing the notification being defined 615 and all top-level data nodes in all modules as children. 616 Otherwise, the root node has all top-level data nodes in all 617 modules as children. 619 o If the XPath expression is defined in a substatement to an "input" 620 statement in an "rpc" or "action" statement, the accessible tree 621 is the RPC or action operation instance and all operational state 622 in the server. The root node has top-level data nodes in all 623 modules as children. Additionally, for an RPC, the root node also 624 has the node representing the RPC operation being defined as a 625 child. The node representing the operation being defined has the 626 operation's input parameters as children. 628 o If the XPath expression is defined in a substatement to an 629 "output" statement in an "rpc" or "action" statement, the 630 accessible tree is the RPC or action operation instance and all 631 operational state in the server. The root node has top-level data 632 nodes in all modules as children. Additionally, for an RPC, the 633 root node also has the node representing the RPC operation being 634 defined as a child. The node representing the operation being 635 defined has the operation's output parameters as children. 637 6. YANG Modules 639 file "ietf-datastores@2017-04-26.yang" 641 module ietf-datastores { 642 yang-version 1.1; 643 namespace "urn:ietf:params:xml:ns:yang:ietf-datastores"; 644 prefix ds; 646 organization 647 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 649 contact 650 "WG Web: 652 WG List: 654 Author: Martin Bjorklund 655 657 Author: Juergen Schoenwaelder 658 660 Author: Phil Shafer 661 663 Author: Kent Watsen 664 666 Author: Rob Wilton 667 "; 669 description 670 "This YANG module defines a set of identities for datastores. 671 These identities can be used to identify datastores in protocol 672 operations. 674 Copyright (c) 2017 IETF Trust and the persons identified as 675 authors of the code. All rights reserved. 677 Redistribution and use in source and binary forms, with or 678 without modification, is permitted pursuant to, and subject to 679 the license terms contained in, the Simplified BSD License set 680 forth in Section 4.c of the IETF Trust's Legal Provisions 681 Relating to IETF Documents 682 (http://trustee.ietf.org/license-info). 684 This version of this YANG module is part of RFC XXXX 685 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 686 for full legal notices."; 688 revision 2017-04-26 { 689 description 690 "Initial revision."; 691 reference 692 "RFC XXXX: Network Management Datastore Architecture"; 693 } 695 /* 696 * Identities 697 */ 699 identity datastore { 700 description 701 "Abstract base identity for datastore identities."; 702 } 704 identity conventional { 705 base datastore; 706 description 707 "Abstract base identity for conventional configuration 708 datastores."; 709 } 711 identity dynamic { 712 base datastore; 713 description 714 "Abstract base identity for dynamic datastores."; 715 } 717 identity running { 718 base conventional; 719 description 720 "The running configuration datastore."; 721 } 723 identity candidate { 724 base conventional; 725 description 726 "The candidate configuration datastore."; 727 } 729 identity startup { 730 base conventional; 731 description 732 "The startup configuration datastore."; 734 } 736 identity intended { 737 base conventional; 738 description 739 "The intended configuration datastore."; 740 } 742 identity operational { 743 base datastore; 744 description 745 "The operational state datastore."; 746 } 748 } 750 752 file "ietf-origin@2017-04-26.yang" 754 module ietf-origin { 755 yang-version 1.1; 756 namespace "urn:ietf:params:xml:ns:yang:ietf-origin"; 757 prefix or; 759 import ietf-yang-metadata { 760 prefix md; 761 } 763 organization 764 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 766 contact 767 "WG Web: 769 WG List: 771 Author: Martin Bjorklund 772 774 Author: Juergen Schoenwaelder 775 777 Author: Phil Shafer 778 780 Author: Kent Watsen 781 783 Author: Rob Wilton 784 "; 786 description 787 "This YANG module defines an 'origin' metadata annotation, and a 788 set of identities for the origin value. 790 Copyright (c) 2017 IETF Trust and the persons identified as 791 authors of the code. All rights reserved. 793 Redistribution and use in source and binary forms, with or 794 without modification, is permitted pursuant to, and subject to 795 the license terms contained in, the Simplified BSD License set 796 forth in Section 4.c of the IETF Trust's Legal Provisions 797 Relating to IETF Documents 798 (http://trustee.ietf.org/license-info). 800 This version of this YANG module is part of RFC XXXX 801 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 802 for full legal notices."; 804 revision 2017-04-26 { 805 description 806 "Initial revision."; 807 reference 808 "RFC XXXX: Network Management Datastore Architecture"; 809 } 811 /* 812 * Identities 813 */ 815 identity origin { 816 description 817 "Abstract base identity for the origin annotation."; 818 } 820 identity intended { 821 base origin; 822 description 823 "Denotes data from the intended configuration datastore"; 824 } 826 identity dynamic { 827 base origin; 828 description 829 "Denotes data from a dynamic datastore."; 830 } 831 identity system { 832 base origin; 833 description 834 "Denotes data originated by the system itself, including 835 both system configuration and system state. 837 Examples of system configuration include applied configuration 838 for an always existing loopback interface, or interface 839 configuration that is auto-created due to the hardware 840 currently present in the device."; 841 } 843 identity learned { 844 base origin; 845 description 846 "Denotes configuration learned from protocol interactions with 847 other devices, instead of via the intended configuration 848 datastore or any dynamic datastore. 850 Examples of protocols that provide learned configuration 851 include link-layer negotiations, routing protocols, and 852 DHCP."; 853 } 855 identity default { 856 base origin; 857 description 858 "Denotes data that does not have an configured or learned 859 value, but has a default value in use. Covers both values 860 defined in a 'default' statement, and values defined via an 861 explanation in a 'description' statement."; 862 } 864 identity unknown { 865 base origin; 866 description 867 "Denotes data for which the system cannot identify the 868 origin."; 869 } 871 /* 872 * Metadata annotations 873 */ 875 md:annotation origin { 876 type identityref { 877 base origin; 878 } 879 description 880 "The 'origin' annotation can be present on any node in a 881 datastore. It specifies from where the node originated."; 882 } 884 } 886 888 7. IANA Considerations 890 7.1. Updates to the IETF XML Registry 892 This document registers two URIs in the IETF XML registry [RFC3688]. 893 Following the format in [RFC3688], the following registrations are 894 requested: 896 URI: urn:ietf:params:xml:ns:yang:ietf-datastores 897 Registrant Contact: The IESG. 898 XML: N/A, the requested URI is an XML namespace. 900 URI: urn:ietf:params:xml:ns:yang:ietf-origin 901 Registrant Contact: The IESG. 902 XML: N/A, the requested URI is an XML namespace. 904 7.2. Updates to the YANG Module Names Registry 906 This document registers two YANG modules in the YANG Module Names 907 registry [RFC6020]. Following the format in [RFC6020], the the 908 following registrations are requested: 910 name: ietf-datastores 911 namespace: urn:ietf:params:xml:ns:yang:ietf-datastores 912 prefix: ds 913 reference: RFC XXXX 915 name: ietf-origin 916 namespace: urn:ietf:params:xml:ns:yang:ietf-origin 917 prefix: or 918 reference: RFC XXXX 920 8. Security Considerations 922 This document discusses an architectural model of datastores for 923 network management using NETCONF/RESTCONF and YANG. It has no 924 security impact on the Internet. 926 9. Acknowledgments 928 This document grew out of many discussions that took place since 929 2010. Several Internet-Drafts ([I-D.bjorklund-netmod-operational], 930 [I-D.wilton-netmod-opstate-yang], [I-D.ietf-netmod-opstate-reqs], 931 [I-D.kwatsen-netmod-opstate], [I-D.openconfig-netmod-opstate]) and 932 [RFC6244] touched on some of the problems of the original datastore 933 model. The following people were authors to these Internet-Drafts or 934 otherwise actively involved in the discussions that led to this 935 document: 937 o Lou Berger, LabN Consulting, L.L.C., 939 o Andy Bierman, YumaWorks, 941 o Marcus Hines, Google, 943 o Christian Hopps, Deutsche Telekom, 945 o Acee Lindem, Cisco Systems, 947 o Ladislav Lhotka, CZ.NIC, 949 o Thomas Nadeau, Brocade Networks, 951 o Anees Shaikh, Google, 953 o Rob Shakir, Google, 955 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 956 Excellence project (ICT-318488) supported by the European Commission 957 under its Seventh Framework Programme. 959 10. References 961 10.1. Normative References 963 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 964 and A. Bierman, Ed., "Network Configuration Protocol 965 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 966 . 968 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 969 RFC 7950, DOI 10.17487/RFC7950, August 2016, 970 . 972 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 973 7952, DOI 10.17487/RFC7952, August 2016, 974 . 976 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 977 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 978 . 980 10.2. Informative References 982 [I-D.bjorklund-netmod-operational] 983 Bjorklund, M. and L. Lhotka, "Operational Data in NETCONF 984 and YANG", draft-bjorklund-netmod-operational-00 (work in 985 progress), October 2012. 987 [I-D.ietf-netmod-opstate-reqs] 988 Watsen, K. and T. Nadeau, "Terminology and Requirements 989 for Enhanced Handling of Operational State", draft-ietf- 990 netmod-opstate-reqs-04 (work in progress), January 2016. 992 [I-D.kwatsen-netmod-opstate] 993 Watsen, K., Bierman, A., Bjorklund, M., and J. 994 Schoenwaelder, "Operational State Enhancements for YANG, 995 NETCONF, and RESTCONF", draft-kwatsen-netmod-opstate-02 996 (work in progress), February 2016. 998 [I-D.openconfig-netmod-opstate] 999 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 1000 of Operational State Data in YANG", draft-openconfig- 1001 netmod-opstate-01 (work in progress), July 2015. 1003 [I-D.wilton-netmod-opstate-yang] 1004 Wilton, R., ""With-config-state" Capability for NETCONF/ 1005 RESTCONF", draft-wilton-netmod-opstate-yang-02 (work in 1006 progress), December 2015. 1008 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1009 DOI 10.17487/RFC3688, January 2004, 1010 . 1012 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1013 the Network Configuration Protocol (NETCONF)", RFC 6020, 1014 DOI 10.17487/RFC6020, October 2010, 1015 . 1017 [RFC6244] Shafer, P., "An Architecture for Network Management Using 1018 NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244, June 1019 2011, . 1021 Appendix A. Guidelines for Defining Datastores 1023 The definition of a new datastore in this architecture should be 1024 provided in a document (e.g., an RFC) purposed to the definition of 1025 the datastore. When it makes sense, more than one datastore may be 1026 defined in the same document (e.g., when the datastores are logically 1027 connected). Each datastore's definition should address the points 1028 specified in the sections below. 1030 A.1. Define which YANG modules can be used in the datastore 1032 Not all YANG modules may be used in all datastores. Some datastores 1033 may constrain which data models can be used in them. If it is 1034 desirable that a subset of all modules can be targeted to the 1035 datastore, then the documentation defining the datastore must 1036 indicate this. 1038 A.2. Define which subset of YANG-modeled data applies 1040 By default, the data in a datastore is modeled by all YANG statements 1041 in the available YANG modules. However, it is possible to specify 1042 criteria that YANG statements must satisfy in order to be present in 1043 a datastore. For instance, maybe only "config true" nodes are 1044 present, or "config false nodes" that also have a specific YANG 1045 extension (e.g., "i2rs:ephemeral true") are present in the datastore. 1047 A.3. Define how data is actualized 1049 The new datastore must specify how it interacts with other 1050 datastores. For example, the diagram in Section 4 depicts dynamic 1051 datastores feeding into . How this interaction occurs 1052 must be defined by any dynamic datastore. In some cases, it may 1053 occur implicitly, as soon as the data is put into the dynamic 1054 datastore while, in other cases, an explicit action (e.g., an RPC) 1055 may be required to trigger the application of the datastore's data. 1057 A.4. Define which protocols can be used 1059 By default, it is assumed that both the NETCONF and RESTCONF 1060 protocols can be used to interact with a datastore. However, it may 1061 be that only a specific protocol can be used (e.g., ForCES) or that a 1062 subset of all protocol operations or capabilities are available 1063 (e.g., no locking or no XPath-based filtering). 1065 A.5. Define YANG identities for the datastore 1067 The datastore must be defined with a YANG identity that uses the 1068 "ds:datastore" identity or one of its derived identities as its base. 1069 This identity is necessary so that the datastore can be referenced in 1070 protocol operations (e.g., ). 1072 The datastore may also be defined with an identity that uses the 1073 "or:origin" identity or one its derived identities as its base. This 1074 identity is needed if the datastore interacts with so 1075 that data originating from the datastore can be identified as such 1076 via the "origin" metadata attribute defined in Section 6. 1078 An example of these guidelines in use is provided in Appendix B. 1080 Appendix B. Ephemeral Dynamic Datastore Example 1082 The section defines documentation for an example dynamic datastore 1083 using the guidelines provided in Appendix A. While this example is 1084 very terse, it is expected to be that a standalone RFC would be 1085 needed when fully expanded. 1087 This example defines a dynamic datastore called "ephemeral", which is 1088 loosely modeled after the work done in the I2RS working group. 1090 1. Name : ephemeral 1091 2. YANG modules : all (default) 1092 3. YANG statements : config false + ephemeral true 1093 4. How applied : automatic 1094 5. Protocols : NC/RC (default) 1095 6. YANG Module : (see below) 1097 module example-ds-ephemeral { 1098 yang-version 1.1; 1099 namespace "urn:example:ds-ephemeral"; 1100 prefix eph; 1102 import ietf-datastores { 1103 prefix ds; 1104 } 1105 import ietf-origin { 1106 prefix or; 1107 } 1109 // add datastore identity 1110 identity ds-ephemeral { 1111 base ds:datastore; 1112 description 1113 "The 'ephemeral' datastore."; 1114 } 1116 // add origin identity 1117 identity or-ephemeral { 1118 base or:dynamic; 1119 description 1120 "Denotes data from the ephemeral dynamic datastore."; 1121 } 1123 // define ephemeral extension 1124 extension ephemeral { 1125 argument "value"; 1126 description 1127 "This extension is mixed into config false YANG nodes to 1128 indicate that they are writable nodes in the 'ephemeral' 1129 datastore. This statement takes a single argument 1130 representing a boolean having the values 'true' and 1131 'false'. The default value is 'false'."; 1132 } 1133 } 1135 Appendix C. Example Data 1137 The use of datastores is complex, and many of the subtle effects are 1138 more easily presented using examples. This section presents a series 1139 of example data models with some sample contents of the various 1140 datastores. 1142 C.1. System Example 1144 In this example, the following fictional module is used: 1146 module example-system { 1147 yang-version 1.1; 1148 namespace urn:example:system; 1149 prefix sys; 1151 import ietf-inet-types { 1152 prefix inet; 1153 } 1155 container system { 1156 leaf hostname { 1157 type string; 1158 } 1160 list interface { 1161 key name; 1163 leaf name { 1164 type string; 1165 } 1167 container auto-negotiation { 1168 leaf enabled { 1169 type boolean; 1170 default true; 1171 } 1172 leaf speed { 1173 type uint32; 1174 units mbps; 1175 description 1176 "The advertised speed, in mbps."; 1177 } 1178 } 1180 leaf speed { 1181 type uint32; 1182 units mbps; 1183 config false; 1184 description 1185 "The speed of the interface, in mbps."; 1186 } 1188 list address { 1189 key ip; 1190 leaf ip { 1191 type inet:ip-address; 1192 } 1193 leaf prefix-length { 1194 type uint8; 1195 } 1196 } 1197 } 1198 } 1199 } 1201 The operator has configured the host name and two interfaces, so the 1202 contents of is: 1204 1206 foo 1208 1209 eth0 1210 1211 1000 1212 1213
1214 2001:db8::10 1215 32 1216
1217 1219 1220 eth1 1221
1222 2001:db8::20 1223 32 1224
1225 1227 1229 The system has detected that the hardware for one of the configured 1230 interfaces ("eth1") is not yet present, so the configuration for that 1231 interface is not applied. Further, the system has received a host 1232 name and an additional IP address for "eth0" over DHCP. In addition 1233 to a default value, a loopback interface is automatically added by 1234 the system, and the result of the "speed" auto-negotiation. All of 1235 this is reflected in : 1237 1241 bar 1243 1244 eth0 1245 1246 true 1247 1000 1248 1249 100 1250
1251 2001:db8::10 1252 32 1253
1254
1255 2001:db8::1:100 1256 32 1257
1258 1260 1261 lo0 1262
1263 ::1 1264 128 1265
1266 1268 1270 C.2. BGP Example 1272 Consider the following piece of a ersatz BGP module: 1274 container bgp { 1275 leaf local-as { 1276 type uint32; 1277 } 1278 leaf peer-as { 1279 type uint32; 1280 } 1281 list peer { 1282 key name; 1283 leaf name { 1284 type ipaddress; 1285 } 1286 leaf local-as { 1287 type uint32; 1288 description 1289 ".... Defaults to ../local-as"; 1290 } 1291 leaf peer-as { 1292 type uint32; 1293 description 1294 "... Defaults to ../peer-as"; 1295 } 1296 leaf local-port { 1297 type inet:port; 1298 } 1299 leaf remote-port { 1300 type inet:port; 1301 default 179; 1302 } 1303 leaf state { 1304 config false; 1305 type enumeration { 1306 enum init; 1307 enum established; 1308 enum closing; 1309 } 1310 } 1311 } 1312 } 1314 In this example model, both bgp/peer/local-as and bgp/peer/peer-as 1315 have complex hierarchical values, allowing the user to specify 1316 default values for all peers in a single location. 1318 The model also follows the pattern of fully integrating state 1319 ("config false") nodes with configuration ("config true") nodes. 1320 There is not separate "bgp-state" hierarchy, with the accompanying 1321 repetition of containment and naming nodes. This makes the model 1322 simpler and more readable. 1324 C.2.1. Datastores 1326 Each datastore represents differing views of these nodes. 1327 will hold the configuration provided by the user, for example a 1328 single BGP peer. will conceptually hold the data as 1329 validated, after the removal of data not intended for validation and 1330 after any local template mechanisms are performed. 1331 will show data from as well as any "config false" nodes. 1333 C.2.2. Adding a Peer 1335 If the user configures a single BGP peer, then that peer will be 1336 visible in both and . It may also appear in 1337 , if the server supports the "candidate" feature. 1338 Retrieving the peer will return only the user-specified values. 1340 No time delay should exist between the appearance of the peer in 1341 and . 1343 In this scenario, we've added the following to : 1345 1346 64642 1347 65000 1348 1349 10.1.2.3 1350 1351 1353 C.2.2.1. 1355 will contain the fully expanded peer data, including 1356 "config false" nodes. In our example, this means the "state" node 1357 will appear. 1359 In addition, will contain the "currently in use" values 1360 for all nodes. This means that local-as and peer-as will be 1361 populated even if they are not given values in . The value 1362 of bgp/local-as will be used if bgp/peer/local-as is not provided; 1363 bgp/peer-as and bgp/peer/peer-as will have the same relationship. In 1364 the operational view, this means that every peer will have values for 1365 their local-as and peer-as, even if those values are not explicitly 1366 configured but are provided by bgp/local-as and bgp/peer-as. 1368 Each BGP peer has a TCP connection associated with it, using the 1369 values of local-port and remote-port from . If those 1370 values are not supplied, the system will select values. When the 1371 connection is established, will contain the current 1372 values for the local-port and remote-port nodes regardless of the 1373 origin. If the system has chosen the values, the "origin" attribute 1374 will be set to "operational". Before the connection is established, 1375 one or both of the nodes may not appear, since the system may not yet 1376 have their values. 1378 1379 64642 1380 65000 1381 1382 10.1.2.3 1383 64642 1384 65000 1385 60794 1386 179 1387 1388 1390 C.2.3. Removing a Peer 1392 Changes to configuration may take time to percolate through the 1393 various software components involved. During this period, it is 1394 imperative to continue to give an accurate view of the working of the 1395 device. will contain nodes for both the previous and 1396 current configuration, as closely as possible tracking the current 1397 operation of the device. 1399 Consider the scenario where a client removes a BGP peer. When a peer 1400 is removed, the operational state will continue to reflect the 1401 existence of that peer until the peer's resources are released, 1402 including closing the peer's connection. During this period, the 1403 current data values will continue to be visible in , 1404 with the "origin" attribute set to indicate the origin of the 1405 original data. 1407 1408 64642 1409 65000 1410 1411 10.1.2.3 1412 64642 1413 65000 1414 60794 1415 179 1416 1417 1419 Once resources are released and the connection is closed, the peer's 1420 data is removed from . 1422 C.3. Interface Example 1424 In this section, we'll use this simple interface data model: 1426 container interfaces { 1427 list interface { 1428 key name; 1429 leaf name { 1430 type string; 1431 } 1432 leaf description { 1433 type string; 1434 } 1435 leaf mtu { 1436 type uint; 1437 } 1438 leaf ipv4-address { 1439 type inet:ipv4-address; 1440 } 1441 } 1442 } 1444 C.3.1. Pre-provisioned Interfaces 1446 One common issue in networking devices is the support of Field 1447 Replaceable Units (FRUs) that can be inserted and removed from the 1448 device without requiring a reboot or interfering with normal 1449 operation. These FRUs are typically interface cards, and the devices 1450 support pre-provisioning of these interfaces. 1452 If a client creates an interface "et-0/0/0" but the interface does 1453 not physically exist at this point, then might contain the 1454 following: 1456 1457 1458 et-0/0/0 1459 Test interface 1460 1461 1463 Since the interface does not exist, this data does not appear in 1464 . 1466 When a FRU containing this interface is inserted, the system will 1467 detect it and process the associated configuration. The 1468 will contain the data from , as well as the 1469 "config false" nodes, such as the current value of the interface's 1470 MTU. 1472 1473 1474 et-0/0/0 1475 Test interface 1476 1500 1477 1478 1480 If the FRU is removed, the interface data is removed from 1481 . 1483 C.3.2. System-provided Interface 1485 Imagine if the system provides a loopback interface (named "lo0") 1486 with a default ipv4-address of "127.0.0.1". The system will only 1487 provide configuration for this interface if there is no data for it 1488 in . 1490 When no configuration for "lo0" appears in , then 1491 will show the system-provided data: 1493 1494 1495 lo0 1496 127.0.0.1 1497 1498 1500 When configuration for "lo0" does appear in , then 1501 will show that data with the origin set to "intended". 1502 If the "ipv4-address" is not provided, then the system-provided value 1503 will appear as follows: 1505 1506 1507 lo0 1508 loopback 1509 127.0.0.1 1510 1511 1513 Authors' Addresses 1515 Martin Bjorklund 1516 Tail-f Systems 1518 Email: mbj@tail-f.com 1520 Juergen Schoenwaelder 1521 Jacobs University 1523 Email: j.schoenwaelder@jacobs-university.de 1525 Phil Shafer 1526 Juniper Networks 1528 Email: phil@juniper.net 1530 Kent Watsen 1531 Juniper Networks 1533 Email: kwatsen@juniper.net 1535 Rob Wilton 1536 Cisco Systems 1538 Email: rwilton@cisco.com