idnits 2.17.1 draft-ietf-netmod-revised-datastores-10.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 (January 13, 2018) is 2295 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 7277 (Obsoleted by RFC 8344) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). 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 Updates: 7950 (if approved) J. Schoenwaelder 5 Intended status: Standards Track Jacobs University 6 Expires: July 17, 2018 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 January 13, 2018 13 Network Management Datastore Architecture 14 draft-ietf-netmod-revised-datastores-10 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. This document updates RFC 7950. 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 July 17, 2018. 42 Copyright Notice 44 Copyright (c) 2018 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. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 4.1. Original Model of Datastores . . . . . . . . . . . . . . 8 64 5. Architectural Model of Datastores . . . . . . . . . . . . . . 9 65 5.1. Conventional Configuration Datastores . . . . . . . . . . 10 66 5.1.1. The Startup Configuration Datastore () . . . 11 67 5.1.2. The Candidate Configuration Datastore () . 11 68 5.1.3. The Running Configuration Datastore () . . . 12 69 5.1.4. The Intended Configuration Datastore () . . 12 70 5.2. Dynamic Configuration Datastores . . . . . . . . . . . . 13 71 5.3. The Operational State Datastore () . . . . . 13 72 5.3.1. Remnant Configuration . . . . . . . . . . . . . . . . 14 73 5.3.2. Missing Resources . . . . . . . . . . . . . . . . . . 15 74 5.3.3. System-controlled Resources . . . . . . . . . . . . . 15 75 5.3.4. Origin Metadata Annotation . . . . . . . . . . . . . 15 76 6. Implications on YANG . . . . . . . . . . . . . . . . . . . . 17 77 6.1. XPath Context . . . . . . . . . . . . . . . . . . . . . . 17 78 6.2. Invocation of Actions and RPCs . . . . . . . . . . . . . 18 79 7. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 18 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 81 8.1. Updates to the IETF XML Registry . . . . . . . . . . . . 24 82 8.2. Updates to the YANG Module Names Registry . . . . . . . . 24 83 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 84 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 86 11.1. Normative References . . . . . . . . . . . . . . . . . . 26 87 11.2. Informative References . . . . . . . . . . . . . . . . . 26 88 Appendix A. Guidelines for Defining Datastores . . . . . . . . . 27 89 A.1. Define which YANG modules can be used in the datastore . 27 90 A.2. Define which subset of YANG-modeled data applies . . . . 28 91 A.3. Define how data is actualized . . . . . . . . . . . . . . 28 92 A.4. Define which protocols can be used . . . . . . . . . . . 28 93 A.5. Define YANG identities for the datastore . . . . . . . . 28 94 Appendix B. Ephemeral Dynamic Configuration Datastore Example . 29 95 Appendix C. Example Data . . . . . . . . . . . . . . . . . . . . 30 96 C.1. System Example . . . . . . . . . . . . . . . . . . . . . 30 97 C.2. BGP Example . . . . . . . . . . . . . . . . . . . . . . . 33 98 C.2.1. Datastores . . . . . . . . . . . . . . . . . . . . . 35 99 C.2.2. Adding a Peer . . . . . . . . . . . . . . . . . . . . 35 100 C.2.3. Removing a Peer . . . . . . . . . . . . . . . . . . . 36 101 C.3. Interface Example . . . . . . . . . . . . . . . . . . . . 37 102 C.3.1. Pre-provisioned Interfaces . . . . . . . . . . . . . 37 103 C.3.2. System-provided Interface . . . . . . . . . . . . . . 38 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 106 1. Introduction 108 This document provides an architectural framework for datastores as 109 they are used by network management protocols such as NETCONF 110 [RFC6241], RESTCONF [RFC8040] and the YANG [RFC7950] data modeling 111 language. Datastores are a fundamental concept binding network 112 management data models to network management protocols. Agreement on 113 a common architectural model of datastores ensures that data models 114 can be written in a network management protocol agnostic way. This 115 architectural framework identifies a set of conceptual datastores but 116 it does not mandate that all network management protocols expose all 117 these conceptual datastores. This architecture is agnostic with 118 regard to the encoding used by network management protocols. 120 This document updates RFC 7950 by refining the definition of the 121 accessible tree for some XPath context (see Section 6.1) and the 122 invocation context of operations (see Section 6.2). 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in BCP 127 14 [RFC2119] [RFC8174] when, and only when, they appear in all 128 capitals, as shown here. 130 2. Objectives 132 Network management data objects can often take two different values, 133 the value configured by the user or an application (configuration) 134 and the value that the device is actually using (operational state). 135 These two values may be different for a number of reasons, e.g., 136 system internal interactions with hardware, interaction with 137 protocols or other devices, or simply the time it takes to propagate 138 a configuration change to the software and hardware components of a 139 system. Furthermore, configuration and operational state data 140 objects may have different lifetimes. 142 The original model of datastores required these data objects to be 143 modeled twice in the YANG schema, as "config true" objects and as 144 "config false" objects. The convention adopted by the interfaces 145 data model ([RFC7223]) and the IP data model ([RFC7277]) was using 146 two separate branches rooted at the root of the data tree, one branch 147 for configuration data objects and one branch for operational state 148 data objects. 150 The duplication of definitions and the ad-hoc separation of 151 operational state data from configuration data leads to a number of 152 problems. Having configuration and operational state data in 153 separate branches in the data model is operationally complicated and 154 impacts the readability of module definitions. Furthermore, the 155 relationship between the branches is not machine readable and filter 156 expressions operating on configuration and on related operational 157 state are different. 159 With the revised architectural model of datastores defined in this 160 document, the data objects are defined only once in the YANG schema 161 but independent instantiations can appear in different datastores, 162 e.g., one for a configured value and another for an operationally 163 used value. This provides a more elegant and simpler solution to the 164 problem. 166 The revised architectural model of datastores supports additional 167 datastores for systems that support more advanced processing chains 168 converting configuration to operational state. For example, some 169 systems support configuration that is not currently used (so called 170 inactive configuration) or they support configuration templates that 171 are used to expand configuration data via a common template. 173 3. Terminology 175 This document defines the following terminology. Some of the terms 176 are revised definitions of terms originally defined in [RFC6241] and 177 [RFC7950] (see also section Section 4). The revised definitions are 178 semantically equivalent with the definitions found in [RFC6241] and 179 [RFC7950]. It is expected that the revised definitions provided in 180 this section will replace the definitions in [RFC6241] and [RFC7950] 181 when these documents are revised. 183 o datastore: A conceptual place to store and access information. A 184 datastore might be implemented, for example, using files, a 185 database, flash memory locations, or combinations thereof. A 186 datastore maps to an instantiated YANG data tree. 188 o schema node: A node in the schema tree. The formal definition is 189 in RFC 7950. 191 o datastore schema: The combined set of schema nodes for all modules 192 supported by a particular datastore, taking into consideration any 193 deviations and enabled features for that datastore. 195 o configuration: Data that is required to get a device from its 196 initial default state into a desired operational state. This data 197 is modeled in YANG using "config true" nodes. Configuration can 198 originate from different sources. 200 o configuration datastore: A datastore holding configuration. 202 o running configuration datastore: A configuration datastore holding 203 the current configuration of the device. It may include 204 configuration that requires further transformations before it can 205 be applied. This datastore is referred to as "". 207 o candidate configuration datastore: A configuration datastore that 208 can be manipulated without impacting the device's running 209 configuration datastore and that can be committed to the running 210 configuration datastore. This datastore is referred to as 211 "". 213 o startup configuration datastore: A configuration datastore holding 214 the configuration loaded by the device into the running 215 configuration datastore when it boots. This datastore is referred 216 to as "". 218 o intended configuration: Configuration that is intended to be used 219 by the device. It represents the configuration after all 220 configuration transformations to have been performed and 221 is the configuration that the system attempts to apply. 223 o intended configuration datastore: A configuration datastore 224 holding the complete intended configuration of the device. This 225 datastore is referred to as "". 227 o configuration transformation: The addition, modification or 228 removal of configuration between the and 229 datastores. Examples of configuration transformations include the 230 removal of inactive configuration and the configuration produced 231 through the expansion of templates. 233 o conventional configuration datastore: One of the following set of 234 configuration datastores: , , , and 235 . These datastores share a common datastore schema, and 236 protocol operations allow copying data between these datastores. 237 The term "conventional" is chosen as a generic umbrella term for 238 these datastores. 240 o conventional configuration: Configuration that is stored in any of 241 the conventional configuration datastores. 243 o dynamic configuration datastore: A configuration datastore holding 244 configuration obtained dynamically during the operation of a 245 device through interaction with other systems, rather than through 246 one of the conventional configuration datastores. 248 o dynamic configuration: Configuration obtained via a dynamic 249 configuration datastore. 251 o learned configuration: Configuration that has been learned via 252 protocol interactions with other systems and that is neither 253 conventional nor dynamic configuration. 255 o system configuration: Configuration that is supplied by the device 256 itself. 258 o default configuration: Configuration that is not explicitly 259 provided but for which a value defined in the data model is used. 261 o applied configuration: Configuration that is actively in use by a 262 device. Applied configuration originates from conventional, 263 dynamic, learned, system and default configuration. 265 o system state: The additional data on a system that is not 266 configuration, such as read-only status information and collected 267 statistics. System state is transient and modified by 268 interactions with internal components or other systems. System 269 state is modeled in YANG using "config false" nodes. 271 o operational state: The combination of applied configuration and 272 system state. 274 o operational state datastore: A datastore holding the complete 275 operational state of the device. This datastore is referred to as 276 "". 278 o origin: A metadata annotation indicating the origin of a data 279 item. 281 o remnant configuration: Configuration that remains part of the 282 applied configuration for a period of time after it has been 283 removed from the intended configuration or dynamic configuration. 284 The time period may be minimal, or may last until all resources 285 used by the newly-deleted configuration (e.g., network 286 connections, memory allocations, file handles) have been 287 deallocated. 289 The following additional terms are not datastore specific but 290 commonly used and thus defined here as well: 292 o client: An entity that can access YANG-defined data on a server, 293 over some network management protocol. 295 o server: An entity that provides access to YANG-defined data to a 296 client, over some network management protocol. 298 o notification: A server-initiated message indicating that a certain 299 event has been recognized by the server. 301 o remote procedure call: An operation that can be invoked by a 302 client on a server. 304 4. Background 306 NETCONF [RFC6241] provides the following definitions: 308 o datastore: A conceptual place to store and access information. A 309 datastore might be implemented, for example, using files, a 310 database, flash memory locations, or combinations thereof. 312 o configuration datastore: The datastore holding the complete set of 313 configuration that is required to get a device from its initial 314 default state into a desired operational state. 316 YANG 1.1 [RFC7950] provides the following refinements when NETCONF is 317 used with YANG (which is the usual case but note that NETCONF was 318 defined before YANG existed): 320 o datastore: When modeled with YANG, a datastore is realized as an 321 instantiated data tree. 323 o configuration datastore: When modeled with YANG, a configuration 324 datastore is realized as an instantiated data tree with 325 configuration. 327 [RFC6244] defined operational state data as follows: 329 o Operational state data is a set of data that has been obtained by 330 the system at runtime and influences the system's behavior similar 331 to configuration data. In contrast to configuration data, 332 operational state is transient and modified by interactions with 333 internal components or other systems via specialized protocols. 335 Section 4.3.3 of [RFC6244] discusses operational state and among 336 other things mentions the option to consider operational state as 337 being stored in another datastore. Section 4.4 of [RFC6244] then 338 concludes that at the time of the writing, modeling state as distinct 339 leafs and distinct branches is the recommended approach. 341 Implementation experience and requests from operators 342 [I-D.ietf-netmod-opstate-reqs], [I-D.openconfig-netmod-opstate] 343 indicate that the datastore model initially designed for NETCONF and 344 refined by YANG needs to be extended. In particular, the notion of 345 intended configuration and applied configuration has developed. 347 4.1. Original Model of Datastores 349 The following drawing shows the original model of datastores as it is 350 currently used by NETCONF [RFC6241]: 352 +-------------+ +-----------+ 353 | | | | 354 | (ct, rw) |<---+ +--->| (ct, rw) | 355 +-------------+ | | +-----------+ 356 | | | | 357 | +-----------+ | 358 +-------->| |<--------+ 359 | (ct, rw) | 360 +-----------+ 361 | 362 v 363 operational state <--- control plane 364 (cf, ro) 366 ct = config true; cf = config false 367 rw = read-write; ro = read-only 368 boxes denote datastores 370 Figure 1 372 Note that this diagram simplifies the model: read-only (ro) and read- 373 write (rw) is to be understood at a conceptual level. In NETCONF, 374 for example, support for and is optional and 375 does not have to be writable. Furthermore, can 376 only be modified by copying to in the 377 standardized NETCONF datastore editing model. The RESTCONF protocol 378 does not expose these differences and instead provides only a 379 writable unified datastore, which hides whether edits are done 380 through or by directly modifying or via some 381 other implementation specific mechanism. RESTCONF also hides how 382 configuration is made persistent. Note that implementations may also 383 have additional datastores that can propagate changes to . 384 NETCONF explicitly mentions so called named datastores. 386 Some observations: 388 o Operational state has not been defined as a datastore although 389 there were proposals in the past to introduce an operational state 390 datastore. 392 o The NETCONF operation returns the contents of 393 together with the operational state. It is therefore necessary 394 that "config false" data is in a different branch than the "config 395 true" data if the operational state can have a different lifetime 396 compared to configuration or if configuration is not immediately 397 or successfully applied. 399 o Several implementations have proprietary mechanisms that allow 400 clients to store inactive data in . Inactive data is 401 conceptually removed before validation. 403 o Some implementations have proprietary mechanisms that allow 404 clients to define configuration templates in . These 405 templates are expanded automatically by the system, and the 406 resulting configuration is applied internally. 408 o Some operators have reported that it is essential for them to be 409 able to retrieve the configuration that has actually been 410 successfully applied, which may be a subset or a superset of the 411 configuration. 413 5. Architectural Model of Datastores 415 Below is a new conceptual model of datastores extending the original 416 model in order to reflect the experience gained with the original 417 model. 419 +-------------+ +-----------+ 420 | | | | 421 | (ct, rw) |<---+ +--->| (ct, rw) | 422 +-------------+ | | +-----------+ 423 | | | | 424 | +-----------+ | 425 +-------->| |<--------+ 426 | (ct, rw) | 427 +-----------+ 428 | 429 | // configuration transformations, 430 | // e.g., removal of nodes marked as 431 | // "inactive", expansion of 432 | // templates 433 v 434 +------------+ 435 | | // subject to validation 436 | (ct, ro) | 437 +------------+ 438 | // changes applied, subject to 439 | // local factors, e.g., missing 440 | // resources, delays 441 | 442 dynamic | +-------- learned configuration 443 configuration | +-------- system configuration 444 datastores -----+ | +-------- default configuration 445 | | | 446 v v v 447 +---------------+ 448 | | <-- system state 449 | (ct + cf, ro) | 450 +---------------+ 452 ct = config true; cf = config false 453 rw = read-write; ro = read-only 454 boxes denote named datastores 456 Figure 2 458 5.1. Conventional Configuration Datastores 460 The conventional configuration datastores are a set of configuration 461 datastores that share exactly the same datastore schema, allowing 462 data to be copied between them. The term is meant as a generic 463 umbrella description of these datastores. If a module does not 464 contain any configuration data nodes and it is not needed to satisfy 465 any imports, then it MAY be omitted from the datastore schema for the 466 conventional configuration datastores. The set of datastores 467 include: 469 o 471 o 473 o 475 o 477 Other conventional configuration datastores may be defined in future 478 documents. 480 The flow of data between these datastores is depicted in Section 5. 482 The specific protocols may define explicit operations to copy between 483 these datastores, e.g., NETCONF defines the operation. 485 5.1.1. The Startup Configuration Datastore () 487 The startup configuration datastore () is a configuration 488 datastore holding the configuration loaded by the device when it 489 boots. is only present on devices that separate the 490 startup configuration from the running configuration datastore. 492 The startup configuration datastore may not be supported by all 493 protocols or implementations. 495 On devices that support non-volatile storage, the contents of 496 will typically persist across reboots via that storage. At 497 boot time, the device loads the saved startup configuration into 498 . To save a new startup configuration, data is copied to 499 , either via implicit or explicit protocol operations. 501 5.1.2. The Candidate Configuration Datastore () 503 The candidate configuration datastore () is a 504 configuration datastore that can be manipulated without impacting the 505 device's current configuration and that can be committed to 506 . 508 The candidate configuration datastore may not be supported by all 509 protocols or implementations. 511 does not typically persist across reboots, even in the 512 presence of non-volatile storage. If is stored using 513 non-volatile storage, it is reset at boot time to the contents of 514 . 516 5.1.3. The Running Configuration Datastore () 518 The running configuration datastore () is a configuration 519 datastore that holds the current configuration of the device. It MAY 520 include configuration that requires further transformation before it 521 can be applied, e.g., inactive configuration, or template-mechanism- 522 oriented configuration that needs further expansion. However, 523 MUST always be a valid configuration data tree, as defined 524 in Section 8.1 of [RFC7950]. 526 MUST be supported if the device can be configured via 527 conventional configuration datastores. 529 If a device does not have a distinct and non-volatile 530 storage is available, the device will typically use that non-volatile 531 storage to allow to persist across reboots. 533 5.1.4. The Intended Configuration Datastore () 535 The intended configuration datastore () is a read-only 536 configuration datastore. It represents the configuration after all 537 configuration transformations to are performed (e.g., 538 template expansion, removal of inactive configuration), and is the 539 configuration that the system attempts to apply. 541 is tightly coupled to . Whenever data is written 542 to , then MUST also be immediately updated by 543 performing all necessary configuration transformations to the 544 contents of and then is validated. 546 MAY also be updated independently of if the 547 effect of a configuration transformation changes, but MUST 548 always be a valid configuration data tree, as defined in Section 8.1 549 of [RFC7950]. 551 For simple implementations, and are identical. 553 The contents of are also related to the "config true" 554 subset of , and hence a client can determine to what 555 extent the intended configuration is currently in use by checking 556 whether the contents of also appear in . 558 does not persist across reboots; its relationship with 559 makes that unnecessary. 561 Currently there are no standard mechanisms defined that affect 562 so that it would have different content than , 563 but this architecture allows for such mechanisms to be defined. 565 One example of such a mechanism is support for marking nodes as 566 inactive in . Inactive nodes are not copied to . 567 A second example is support for templates, which can perform 568 transformations on the configuration from to the 569 configuration written to . 571 5.2. Dynamic Configuration Datastores 573 The model recognizes the need for dynamic configuration datastores 574 that are, by definition, not part of the persistent configuration of 575 a device. In some contexts, these have been termed ephemeral 576 datastores since the information is ephemeral, i.e., lost upon 577 reboot. The dynamic configuration datastores interact with the rest 578 of the system through . 580 The datastore schema for a dynamic configuration datastore MAY differ 581 from the datastore schema used for conventional configuration 582 datastores. If a module does not contain any configuration data 583 nodes and it is not needed to satisfy any imports, then it MAY be 584 omitted from the datastore schema for the dynamic configuration 585 datastore. 587 5.3. The Operational State Datastore () 589 The operational state datastore () is a read-only 590 datastore that consists of all "config true" and "config false" nodes 591 defined in the datastore's schema. In the original NETCONF model the 592 operational state only had "config false" nodes. The reason for 593 incorporating "config true" nodes here is to be able to expose all 594 operational settings without having to replicate definitions in the 595 data models. 597 contains system state and all configuration actually 598 used by the system. This includes all applied configuration from 599 , learned configuration, system-provided configuration, and 600 default values defined by any supported data models. In addition, 601 also contains applied configuration from dynamic 602 configuration datastores. 604 The datastore schema for MUST be a superset of the 605 combined datastore schema used in all configuration datastores except 606 that configuration data nodes supported in a configuration datastore 607 MAY be omitted from if a server is not able to 608 accurately report them. 610 Requests to retrieve nodes from always return the value 611 in use if the node exists, regardless of any default value specified 612 in the YANG module. If no value is returned for a given node, then 613 this implies that the node is not used by the device. 615 The interpretation of what constitutes as being "in use" by the 616 system is dependent on both the schema definition and the device 617 implementation. Generally, functionality that is enabled and 618 operational on the system would be considered as being "in use". 619 Conversely, functionality that is neither enabled nor operational on 620 the system is considered as not being "in use", and hence SHOULD be 621 omitted from . 623 SHOULD conform to any constraints specified in the data 624 model, but given the principal aim of returning "in use" values, it 625 is possible that constraints MAY be violated under some 626 circumstances, e.g., an abnormal value is "in use", the structure of 627 a list is being modified, or due to remnant configuration (see 628 Section 5.3.1). Note, that deviations SHOULD be used when it is 629 known in advance that a device does not fully conform to the 630 schema. 632 Only semantic constraints MAY be violated, these are the YANG "when", 633 "must", "mandatory", "unique", "min-elements", and "max-elements" 634 statements; and the uniqueness of key values. 636 Syntactic constraints MUST NOT be violated, including hierarchical 637 organization, identifiers, and type-based constraints. If a node in 638 does not meet the syntactic constraints then it MUST 639 NOT be returned, and some other mechanism should be used to flag the 640 error. 642 does not persist across reboots. 644 5.3.1. Remnant Configuration 646 Changes to configuration may take time to percolate through to 647 . During this period, may contain nodes 648 for both the previous and current configuration, as closely as 649 possible tracking the current operation of the device. Such remnant 650 configuration from the previous configuration persists until the 651 system has released resources used by the newly-deleted configuration 652 (e.g., network connections, memory allocations, file handles). 654 Remnant configuration is a common example of where the semantic 655 constraints defined in the data model cannot be relied upon for 656 , since the system may have remnant configuration whose 657 constraints were valid with the previous configuration and that are 658 not valid with the current configuration. Since constraints on 659 "config false" nodes may refer to "config true" nodes, remnant 660 configuration may force the violation of those constraints. 662 5.3.2. Missing Resources 664 Configuration in can refer to resources that are not 665 available or otherwise not physically present. In these situations, 666 these parts of are not applied. The data appears in 667 but does not appear in . 669 A typical example is an interface configuration that refers to an 670 interface that is not currently present. In such a situation, the 671 interface configuration remains in but the interface 672 configuration will not appear in . 674 Note that configuration validity cannot depend on the current state 675 of such resources, since that would imply that removing a resource 676 might render the configuration invalid. This is unacceptable, 677 especially given that rebooting such a device would cause it to 678 restart with an invalid configuration. Instead we allow 679 configuration for missing resources to exist in and 680 , but it will not appear in . 682 5.3.3. System-controlled Resources 684 Sometimes resources are controlled by the device and the 685 corresponding system controlled data appears in (and disappears from) 686 dynamically. If a system controlled resource has 687 matching configuration in when it appears, the system will 688 try to apply the configuration, which causes the configuration to 689 appear in eventually (if application of the 690 configuration was successful). 692 5.3.4. Origin Metadata Annotation 694 As configuration flows into , it is conceptually marked 695 with a metadata annotation ([RFC7952]) that indicates its origin. 696 The origin applies to all configuration nodes except non-presence 697 containers. The "origin" metadata annotation is defined in 698 Section 7. The values are YANG identities. The following identities 699 are defined: 701 o origin: abstract base identity from which the other origin 702 identities are derived. 704 o intended: represents configuration provided by . 706 o dynamic: represents configuration provided by a dynamic 707 configuration datastore. 709 o system: represents configuration provided by the system itself. 710 Examples of system configuration include applied configuration for 711 an always existing loopback interface, or interface configuration 712 that is auto-created due to the hardware currently present in the 713 device. 715 o learned: represents configuration that has been learned via 716 protocol interactions with other systems, including protocols such 717 as link-layer negotiations, routing protocols, DHCP, etc. 719 o default: represents configuration using a default value specified 720 in the data model, using either values in the "default" statement 721 or any values described in the "description" statement. The 722 default origin is only used when the configuration has not been 723 provided by any other source. 725 o unknown: represents configuration for which the system cannot 726 identify the origin. 728 These identities can be further refined, e.g., there could be 729 separate identities for particular types or instances of dynamic 730 configuration datastores derived from "dynamic". 732 For all configuration data nodes in , the device SHOULD 733 report the origin that most accurately reflects the source of the 734 configuration that is in use by the system. 736 In cases where it could be ambiguous as to which origin should be 737 used, i.e. where the same data node value has originated from 738 multiple sources, then the description statement in the YANG module 739 SHOULD be used as guidance for choosing the appropriate origin. For 740 example: 742 If for a particular configuration node, the associated YANG 743 description statement indicates that a protocol negotiated value 744 overrides any configured value, then the origin would be reported as 745 "learned", even when a learned value is the same as the configured 746 value. 748 Conversely, if for a particular configuration node, the associated 749 YANG description statement indicates that a protocol negotiated value 750 does not override an explicitly configured value, then the origin 751 would be reported as "intended" even when a learned value is the same 752 as the configured value. 754 In the case that a device cannot provide an accurate origin for a 755 particular configuration data node then it SHOULD use the origin 756 "unknown". 758 6. Implications on YANG 760 6.1. XPath Context 762 This section updates section 6.4.1 of RFC 7950. 764 If a server implements the architecture defined in this document, the 765 accessible trees for some XPath contexts are refined as follows: 767 o If the XPath expression is defined in a substatement to a data 768 node that represents system state, the accessible tree is all 769 operational state in the server. The root node has all top-level 770 data nodes in all modules as children. 772 o If the XPath expression is defined in a substatement to a 773 "notification" statement, the accessible tree is the notification 774 instance and all operational state in the server. If the 775 notification is defined on the top level in a module, then the 776 root node has the node representing the notification being defined 777 and all top-level data nodes in all modules as children. 778 Otherwise, the root node has all top-level data nodes in all 779 modules as children. 781 o If the XPath expression is defined in a substatement to an "input" 782 statement in an "rpc" or "action" statement, the accessible tree 783 is the RPC or action operation instance and all operational state 784 in the server. The root node has top-level data nodes in all 785 modules as children. Additionally, for an RPC, the root node also 786 has the node representing the RPC operation being defined as a 787 child. The node representing the operation being defined has the 788 operation's input parameters as children. 790 o If the XPath expression is defined in a substatement to an 791 "output" statement in an "rpc" or "action" statement, the 792 accessible tree is the RPC or action operation instance and all 793 operational state in the server. The root node has top-level data 794 nodes in all modules as children. Additionally, for an RPC, the 795 root node also has the node representing the RPC operation being 796 defined as a child. The node representing the operation being 797 defined has the operation's output parameters as children. 799 6.2. Invocation of Actions and RPCs 801 This section updates section 7.15 of RFC 7950. 803 Actions are always invoked in the context of the operational state 804 datastore. The node for which the action is invoked MUST exist in 805 the operational state datastore. 807 Note that this document does not constrain the result of invoking an 808 RPC or action in any way. For example, an RPC might be defined to 809 modify the contents of some datastore. 811 7. YANG Modules 813 file "ietf-datastores@2018-01-11.yang" 815 module ietf-datastores { 816 yang-version 1.1; 817 namespace "urn:ietf:params:xml:ns:yang:ietf-datastores"; 818 prefix ds; 820 organization 821 "IETF Network Modeling (NETMOD) Working Group"; 823 contact 824 "WG Web: 826 WG List: 828 Author: Martin Bjorklund 829 831 Author: Juergen Schoenwaelder 832 834 Author: Phil Shafer 835 837 Author: Kent Watsen 838 840 Author: Rob Wilton 841 "; 843 description 844 "This YANG module defines two sets of identities for datastores. 845 The first identifies the datastores themselves, the second 846 identifies datastore properties. 848 Copyright (c) 2018 IETF Trust and the persons identified as 849 authors of the code. All rights reserved. 851 Redistribution and use in source and binary forms, with or 852 without modification, is permitted pursuant to, and subject to 853 the license terms contained in, the Simplified BSD License set 854 forth in Section 4.c of the IETF Trust's Legal Provisions 855 Relating to IETF Documents 856 (http://trustee.ietf.org/license-info). 858 This version of this YANG module is part of RFC XXXX 859 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 860 for full legal notices."; 862 revision 2018-01-11 { 863 description 864 "Initial revision."; 865 reference 866 "RFC XXXX: Network Management Datastore Architecture"; 867 } 869 /* 870 * Identities 871 */ 873 identity datastore { 874 description 875 "Abstract base identity for datastore identities."; 876 } 878 identity conventional { 879 base datastore; 880 description 881 "Abstract base identity for conventional configuration 882 datastores."; 883 } 885 identity running { 886 base conventional; 887 description 888 "The running configuration datastore."; 889 } 891 identity candidate { 892 base conventional; 893 description 894 "The candidate configuration datastore."; 895 } 896 identity startup { 897 base conventional; 898 description 899 "The startup configuration datastore."; 900 } 902 identity intended { 903 base conventional; 904 description 905 "The intended configuration datastore."; 906 } 908 identity dynamic { 909 base datastore; 910 description 911 "Abstract base identity for dynamic configuration datastores."; 912 } 914 identity operational { 915 base datastore; 916 description 917 "The operational state datastore."; 918 } 920 /* 921 * Type definitions 922 */ 924 typedef datastore-ref { 925 type identityref { 926 base datastore; 927 } 928 description 929 "A datastore identity reference."; 930 } 932 } 934 936 file "ietf-origin@2018-01-11.yang" 938 module ietf-origin { 939 yang-version 1.1; 940 namespace "urn:ietf:params:xml:ns:yang:ietf-origin"; 941 prefix or; 943 import ietf-yang-metadata { 944 prefix md; 945 } 947 organization 948 "IETF Network Modeling (NETMOD) Working Group"; 950 contact 951 "WG Web: 953 WG List: 955 Author: Martin Bjorklund 956 958 Author: Juergen Schoenwaelder 959 961 Author: Phil Shafer 962 964 Author: Kent Watsen 965 967 Author: Rob Wilton 968 "; 970 description 971 "This YANG module defines an 'origin' metadata annotation, and a 972 set of identities for the origin value. 974 Copyright (c) 2018 IETF Trust and the persons identified as 975 authors of the code. All rights reserved. 977 Redistribution and use in source and binary forms, with or 978 without modification, is permitted pursuant to, and subject to 979 the license terms contained in, the Simplified BSD License set 980 forth in Section 4.c of the IETF Trust's Legal Provisions 981 Relating to IETF Documents 982 (http://trustee.ietf.org/license-info). 984 This version of this YANG module is part of RFC XXXX 985 (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself 986 for full legal notices."; 988 revision 2018-01-11 { 989 description 990 "Initial revision."; 991 reference 992 "RFC XXXX: Network Management Datastore Architecture"; 993 } 995 /* 996 * Identities 997 */ 999 identity origin { 1000 description 1001 "Abstract base identity for the origin annotation."; 1002 } 1004 identity intended { 1005 base origin; 1006 description 1007 "Denotes configuration from the intended configuration 1008 datastore"; 1009 } 1011 identity dynamic { 1012 base origin; 1013 description 1014 "Denotes configuration from a dynamic configuration 1015 datastore."; 1016 } 1018 identity system { 1019 base origin; 1020 description 1021 "Denotes configuration originated by the system itself. 1023 Examples of system configuration include applied configuration 1024 for an always existing loopback interface, or interface 1025 configuration that is auto-created due to the hardware 1026 currently present in the device."; 1027 } 1029 identity learned { 1030 base origin; 1031 description 1032 "Denotes configuration learned from protocol interactions with 1033 other devices, instead of via either the intended 1034 configuration datastore or any dynamic configuration 1035 datastore. 1037 Examples of protocols that provide learned configuration 1038 include link-layer negotiations, routing protocols, and 1039 DHCP."; 1041 } 1043 identity default { 1044 base origin; 1045 description 1046 "Denotes configuration that does not have an configured or 1047 learned value, but has a default value in use. Covers both 1048 values defined in a 'default' statement, and values defined 1049 via an explanation in a 'description' statement."; 1050 } 1052 identity unknown { 1053 base origin; 1054 description 1055 "Denotes configuration for which the system cannot identify the 1056 origin."; 1057 } 1059 /* 1060 * Type definitions 1061 */ 1063 typedef origin-ref { 1064 type identityref { 1065 base origin; 1066 } 1067 description 1068 "An origin identity reference."; 1069 } 1071 /* 1072 * Metadata annotations 1073 */ 1075 md:annotation origin { 1076 type origin-ref; 1077 description 1078 "The 'origin' annotation can be present on any configuration 1079 data node in the operational state datastore. It specifies 1080 from where the node originated. If not specified for a given 1081 configuration data node then the origin is the same as the 1082 origin of its parent node in the data tree. The origin for 1083 any top level configuration data nodes must be specified."; 1084 } 1085 } 1087 1089 8. IANA Considerations 1091 8.1. Updates to the IETF XML Registry 1093 This document registers two URIs in the IETF XML registry [RFC3688]. 1094 Following the format in [RFC3688], the following registrations are 1095 requested: 1097 URI: urn:ietf:params:xml:ns:yang:ietf-datastores 1098 Registrant Contact: The IESG. 1099 XML: N/A, the requested URI is an XML namespace. 1101 URI: urn:ietf:params:xml:ns:yang:ietf-origin 1102 Registrant Contact: The IESG. 1103 XML: N/A, the requested URI is an XML namespace. 1105 8.2. Updates to the YANG Module Names Registry 1107 This document registers two YANG modules in the YANG Module Names 1108 registry [RFC6020]. Following the format in [RFC6020], the following 1109 registrations are requested: 1111 name: ietf-datastores 1112 namespace: urn:ietf:params:xml:ns:yang:ietf-datastores 1113 prefix: ds 1114 reference: RFC XXXX 1116 name: ietf-origin 1117 namespace: urn:ietf:params:xml:ns:yang:ietf-origin 1118 prefix: or 1119 reference: RFC XXXX 1121 9. Security Considerations 1123 This document discusses an architectural model of datastores for 1124 network management using NETCONF/RESTCONF and YANG. It has no 1125 security impact on the Internet. 1127 Although this document specifies several YANG modules, these modules 1128 only define identities and a metadata annotation, hence the "YANG 1129 module security guidelines" do not apply. 1131 The origin metadata annotation exposes the origin of values in the 1132 applied configuration. Origin information may provide hints that 1133 certain control plane protocols are active on a device. Since origin 1134 information is tied to applied configuration values, it is only 1135 accessible to clients that have the permissions to read the applied 1136 configuration values. Security administrators should consider the 1137 sensitivity of origin information while defining access control 1138 rules. 1140 10. Acknowledgments 1142 This document grew out of many discussions that took place since 1143 2010. Several Internet-Drafts ([I-D.bjorklund-netmod-operational], 1144 [I-D.wilton-netmod-opstate-yang], [I-D.ietf-netmod-opstate-reqs], 1145 [I-D.kwatsen-netmod-opstate], [I-D.openconfig-netmod-opstate]) and 1146 [RFC6244] touched on some of the problems of the original datastore 1147 model. The following people were authors to these Internet-Drafts or 1148 otherwise actively involved in the discussions that led to this 1149 document: 1151 o Lou Berger, LabN Consulting, L.L.C., 1153 o Andy Bierman, YumaWorks, 1155 o Marcus Hines, Google, 1157 o Christian Hopps, Deutsche Telekom, 1159 o Balazs Lengyel, Ericsson, 1161 o Acee Lindem, Cisco Systems, 1163 o Ladislav Lhotka, CZ.NIC, 1165 o Thomas Nadeau, Brocade Networks, 1167 o Tom Petch, Engineering Networks Ltd, 1169 o Anees Shaikh, Google, 1171 o Rob Shakir, Google, 1173 o Jason Sterne, Nokia, 1175 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 1176 Excellence project (ICT-318488) supported by the European Commission 1177 under its Seventh Framework Programme. 1179 11. References 1180 11.1. Normative References 1182 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1183 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1184 RFC2119, March 1997, . 1187 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1188 and A. Bierman, Ed., "Network Configuration Protocol 1189 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1190 . 1192 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1193 RFC 7950, DOI 10.17487/RFC7950, August 2016, . 1196 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 1197 7952, DOI 10.17487/RFC7952, August 2016, . 1200 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1201 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1202 . 1204 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1205 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1206 May 2017, . 1208 11.2. Informative References 1210 [I-D.bjorklund-netmod-operational] 1211 Bjorklund, M. and L. Lhotka, "Operational Data in NETCONF 1212 and YANG", draft-bjorklund-netmod-operational-00 (work in 1213 progress), October 2012. 1215 [I-D.ietf-netmod-opstate-reqs] 1216 Watsen, K. and T. Nadeau, "Terminology and Requirements 1217 for Enhanced Handling of Operational State", draft-ietf- 1218 netmod-opstate-reqs-04 (work in progress), January 2016. 1220 [I-D.kwatsen-netmod-opstate] 1221 Watsen, K., Bierman, A., Bjorklund, M., and J. 1222 Schoenwaelder, "Operational State Enhancements for YANG, 1223 NETCONF, and RESTCONF", draft-kwatsen-netmod-opstate-02 1224 (work in progress), February 2016. 1226 [I-D.openconfig-netmod-opstate] 1227 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 1228 of Operational State Data in YANG", draft-openconfig- 1229 netmod-opstate-01 (work in progress), July 2015. 1231 [I-D.wilton-netmod-opstate-yang] 1232 Wilton, R., ""With-config-state" Capability for NETCONF/ 1233 RESTCONF", draft-wilton-netmod-opstate-yang-02 (work in 1234 progress), December 2015. 1236 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1237 DOI 10.17487/RFC3688, January 2004, . 1240 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1241 the Network Configuration Protocol (NETCONF)", RFC 6020, 1242 DOI 10.17487/RFC6020, October 2010, . 1245 [RFC6244] Shafer, P., "An Architecture for Network Management Using 1246 NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244, June 1247 2011, . 1249 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1250 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1251 . 1253 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", RFC 1254 7277, DOI 10.17487/RFC7277, June 2014, . 1257 Appendix A. Guidelines for Defining Datastores 1259 The definition of a new datastore in this architecture should be 1260 provided in a document (e.g., an RFC) purposed to the definition of 1261 the datastore. When it makes sense, more than one datastore may be 1262 defined in the same document (e.g., when the datastores are logically 1263 connected). Each datastore's definition should address the points 1264 specified in the sections below. 1266 A.1. Define which YANG modules can be used in the datastore 1268 Not all YANG modules may be used in all datastores. Some datastores 1269 may constrain which data models can be used in them. If it is 1270 desirable that a subset of all modules can be targeted to the 1271 datastore, then the documentation defining the datastore must 1272 indicate this. 1274 A.2. Define which subset of YANG-modeled data applies 1276 By default, the data in a datastore is modeled by all YANG statements 1277 in the available YANG modules. However, it is possible to specify 1278 criteria that YANG statements must satisfy in order to be present in 1279 a datastore. For instance, maybe only "config true" nodes, or 1280 "config false" nodes that also have a specific YANG extension, are 1281 present in the datastore. 1283 A.3. Define how data is actualized 1285 The new datastore must specify how it interacts with other 1286 datastores. 1288 For example, the diagram in Section 5 depicts dynamic configuration 1289 datastores feeding into . How this interaction occurs 1290 has to be defined by the particular dynamic configuration datastores. 1291 In some cases, it may occur implicitly, as soon as the data is put 1292 into the dynamic configuration datastore while, in other cases, an 1293 explicit action (e.g., an RPC) may be required to trigger the 1294 application of the datastore's data. 1296 A.4. Define which protocols can be used 1298 By default, it is assumed that both the NETCONF and RESTCONF 1299 protocols can be used to interact with a datastore. However, it may 1300 be that only a specific protocol can be used (e.g., ForCES) or that a 1301 subset of all protocol operations or capabilities are available 1302 (e.g., no locking or no XPath-based filtering). 1304 A.5. Define YANG identities for the datastore 1306 The datastore must be defined with a YANG identity that uses the 1307 "ds:datastore" identity, or one of its derived identities, as its 1308 base. This identity is necessary so that the datastore can be 1309 referenced in protocol operations (e.g., ). 1311 The datastore may also be defined with an identity that uses the 1312 "or:origin" identity or one its derived identities as its base. This 1313 identity is needed if the datastore interacts with so 1314 that data originating from the datastore can be identified as such 1315 via the "origin" metadata attribute defined in Section 7. 1317 An example of these guidelines in use is provided in Appendix B. 1319 Appendix B. Ephemeral Dynamic Configuration Datastore Example 1321 The section defines documentation for an example dynamic 1322 configuration datastore using the guidelines provided in Appendix A. 1323 While this example is very terse, it is expected to be that a 1324 standalone RFC would be needed when fully expanded. 1326 This example defines a dynamic configuration datastore called 1327 "ephemeral", which is loosely modeled after the work done in the I2RS 1328 working group. 1330 +--------------+---------------------------------------------------+ 1331 | Name | Value | 1332 +--------------+---------------------------------------------------+ 1333 | Name | ephemeral | 1334 | YANG modules | all (default) | 1335 | YANG nodes | all "config true" data nodes | 1336 | How applied | changes automatically propagated to | 1337 | Protocols | NC/RC (default) | 1338 | YANG Module | (see below) | 1339 +--------------+---------------------------------------------------+ 1341 The example "ephemeral" datastore properties 1343 module example-ds-ephemeral { 1344 yang-version 1.1; 1345 namespace "urn:example:ds-ephemeral"; 1346 prefix eph; 1348 import ietf-datastores { 1349 prefix ds; 1350 } 1351 import ietf-origin { 1352 prefix or; 1353 } 1355 // datastore identity 1356 identity ds-ephemeral { 1357 base ds:dynamic; 1358 description 1359 "The ephemeral dynamic configuration datastore."; 1360 } 1362 // origin identity 1363 identity or-ephemeral { 1364 base or:dynamic; 1365 description 1366 "Denotes data from the ephemeral dynamic configuration 1367 datastore."; 1368 } 1369 } 1371 Appendix C. Example Data 1373 The use of datastores is complex, and many of the subtle effects are 1374 more easily presented using examples. This section presents a series 1375 of example data models with some sample contents of the various 1376 datastores. 1378 C.1. System Example 1380 In this example, the following fictional module is used: 1382 module example-system { 1383 yang-version 1.1; 1384 namespace urn:example:system; 1385 prefix sys; 1387 import ietf-inet-types { 1388 prefix inet; 1389 } 1390 container system { 1391 leaf hostname { 1392 type string; 1393 } 1395 list interface { 1396 key name; 1398 leaf name { 1399 type string; 1400 } 1402 container auto-negotiation { 1403 leaf enabled { 1404 type boolean; 1405 default true; 1406 } 1407 leaf speed { 1408 type uint32; 1409 units mbps; 1410 description 1411 "The advertised speed, in mbps."; 1412 } 1413 } 1415 leaf speed { 1416 type uint32; 1417 units mbps; 1418 config false; 1419 description 1420 "The speed of the interface, in mbps."; 1421 } 1423 list address { 1424 key ip; 1426 leaf ip { 1427 type inet:ip-address; 1428 } 1429 leaf prefix-length { 1430 type uint8; 1431 } 1432 } 1433 } 1434 } 1435 } 1436 The operator has configured the host name and two interfaces, so the 1437 contents of are: 1439 1441 foo.example.com 1443 1444 eth0 1445 1446 1000 1447 1448
1449 2001:db8::10 1450 64 1451
1452 1454 1455 eth1 1456
1457 2001:db8::20 1458 64 1459
1460 1462 1464 The system has detected that the hardware for one of the configured 1465 interfaces ("eth1") is not yet present, so the configuration for that 1466 interface is not applied. Further, the system has received a host 1467 name and an additional IP address for "eth0" over DHCP. In addition 1468 to a default value, a loopback interface is automatically added by 1469 the system, and the result of the "speed" auto-negotiation. All of 1470 this is reflected in . Note how the origin metadata 1471 attribute for several "config true" data nodes is inherited from 1472 their parent data nodes. 1474 1478 bar.example.com 1480 1481 eth0 1482 1483 true 1484 1000 1485 1486 100 1487
1488 2001:db8::10 1489 64 1490
1491
1492 2001:db8::1:100 1493 64 1494
1495 1497 1498 lo0 1499
1500 ::1 1501 128 1502
1503 1505 1507 C.2. BGP Example 1509 Consider the following fragment of a fictional BGP module: 1511 container bgp { 1512 leaf local-as { 1513 type uint32; 1514 } 1515 leaf peer-as { 1516 type uint32; 1517 } 1518 list peer { 1519 key name; 1520 leaf name { 1521 type inet:ip-address; 1522 } 1523 leaf local-as { 1524 type uint32; 1525 description 1526 ".... Defaults to ../local-as"; 1527 } 1528 leaf peer-as { 1529 type uint32; 1530 description 1531 "... Defaults to ../peer-as"; 1532 } 1533 leaf local-port { 1534 type inet:port; 1535 } 1536 leaf remote-port { 1537 type inet:port; 1538 default 179; 1539 } 1540 leaf state { 1541 config false; 1542 type enumeration { 1543 enum init; 1544 enum established; 1545 enum closing; 1546 } 1547 } 1548 } 1549 } 1551 In this example model, both bgp/peer/local-as and bgp/peer/peer-as 1552 have complex hierarchical values, allowing the user to specify 1553 default values for all peers in a single location. 1555 The model also follows the pattern of fully integrating state 1556 ("config false") nodes with configuration ("config true") nodes. 1557 There is no separate "bgp-state" hierarchy, with the accompanying 1558 repetition of containment and naming nodes. This makes the model 1559 simpler and more readable. 1561 C.2.1. Datastores 1563 Each datastore represents differing views of these nodes. 1564 will hold the configuration provided by the operator, for example a 1565 single BGP peer. will conceptually hold the data as 1566 validated, after the removal of data not intended for validation and 1567 after any local template mechanisms are performed. 1568 will show data from as well as any "config false" nodes. 1570 C.2.2. Adding a Peer 1572 If the user configures a single BGP peer, then that peer will be 1573 visible in both and . It may also appear in 1574 , if the server supports the candidate configuration 1575 datastore. Retrieving the peer will return only the user-specified 1576 values. 1578 No time delay should exist between the appearance of the peer in 1579 and . 1581 In this scenario, we've added the following to : 1583 1584 64501 1585 64502 1586 1587 2001:db8::2:3 1588 1589 1591 C.2.2.1. 1593 The operational datastore will contain the fully expanded peer data, 1594 including "config false" nodes. In our example, this means the 1595 "state" node will appear. 1597 In addition, will contain the "currently in use" values 1598 for all nodes. This means that local-as and peer-as will be 1599 populated even if they are not given values in . The value 1600 of bgp/local-as will be used if bgp/peer/local-as is not provided; 1601 bgp/peer-as and bgp/peer/peer-as will have the same relationship. In 1602 the operational view, this means that every peer will have values for 1603 their local-as and peer-as, even if those values are not explicitly 1604 configured but are provided by bgp/local-as and bgp/peer-as. 1606 Each BGP peer has a TCP connection associated with it, using the 1607 values of local-port and remote-port from . If those 1608 values are not supplied, the system will select values. When the 1609 connection is established, will contain the current 1610 values for the local-port and remote-port nodes regardless of the 1611 origin. If the system has chosen the values, the "origin" attribute 1612 will be set to "system". Before the connection is established, one 1613 or both of the nodes may not appear, since the system may not yet 1614 have their values. 1616 1617 64501 1618 64502 1619 1620 2001:db8::2:3 1621 64501 1622 64502 1623 60794 1624 179 1625 established 1626 1627 1629 C.2.3. Removing a Peer 1631 Changes to configuration may take time to percolate through the 1632 various software components involved. During this period, it is 1633 imperative to continue to give an accurate view of the working of the 1634 device. will contain nodes for both the previous and 1635 current configuration, as closely as possible tracking the current 1636 operation of the device. 1638 Consider the scenario where a client removes a BGP peer. When a peer 1639 is removed, the operational state will continue to reflect the 1640 existence of that peer until the peer's resources are released, 1641 including closing the peer's connection. During this period, the 1642 current data values will continue to be visible in , 1643 with the "origin" attribute set to indicate the origin of the 1644 original data. 1646 1647 64501 1648 64502 1649 1650 2001:db8::2:3 1651 64501 1652 64502 1653 60794 1654 179 1655 closing 1656 1657 1659 Once resources are released and the connection is closed, the peer's 1660 data is removed from . 1662 C.3. Interface Example 1664 In this section, we will use this simple interface data model: 1666 container interfaces { 1667 list interface { 1668 key name; 1669 leaf name { 1670 type string; 1671 } 1672 leaf description { 1673 type string; 1674 } 1675 leaf mtu { 1676 type uint16; 1677 } 1678 leaf-list ip-address { 1679 type inet:ip-address; 1680 } 1681 } 1682 } 1684 C.3.1. Pre-provisioned Interfaces 1686 One common issue in networking devices is the support of Field 1687 Replaceable Units (FRUs) that can be inserted and removed from the 1688 device without requiring a reboot or interfering with normal 1689 operation. These FRUs are typically interface cards, and the devices 1690 support pre-provisioning of these interfaces. 1692 If a client creates an interface "et-0/0/0" but the interface does 1693 not physically exist at this point, then might contain the 1694 following: 1696 1697 1698 et-0/0/0 1699 Test interface 1700 1701 1703 Since the interface does not exist, this data does not appear in 1704 . 1706 When a FRU containing this interface is inserted, the system will 1707 detect it and process the associated configuration. 1708 will contain the data from , as well as nodes added by the 1709 system, such as the current value of the interface's MTU. 1711 1712 1713 et-0/0/0 1714 Test interface 1715 1500 1716 1717 1719 If the FRU is removed, the interface data is removed from 1720 . 1722 C.3.2. System-provided Interface 1724 Imagine if the system provides a loopback interface (named "lo0") 1725 with a default ip-address of "127.0.0.1" and a default ip-address of 1726 "::1". The system will only provide configuration for this interface 1727 if there is no data for it in . 1729 When no configuration for "lo0" appears in , then 1730 will show the system-provided data: 1732 1733 1734 lo0 1735 127.0.0.1 1736 ::1 1737 1738 1740 When configuration for "lo0" does appear in , then 1741 will show that data with the origin set to "intended". 1742 If the "ip-address" is not provided, then the system-provided value 1743 will appear as follows: 1745 1746 1747 lo0 1748 loopback 1749 127.0.0.1 1750 ::1 1751 1752 1754 Authors' Addresses 1756 Martin Bjorklund 1757 Tail-f Systems 1759 Email: mbj@tail-f.com 1761 Juergen Schoenwaelder 1762 Jacobs University 1764 Email: j.schoenwaelder@jacobs-university.de 1766 Phil Shafer 1767 Juniper Networks 1769 Email: phil@juniper.net 1771 Kent Watsen 1772 Juniper Networks 1774 Email: kwatsen@juniper.net 1776 Robert Wilton 1777 Cisco Systems 1779 Email: rwilton@cisco.com