idnits 2.17.1 draft-openconfig-netmod-opstate-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([RFC6020]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 434 has weird spacing: '...ty-time yan...' == Line 460 has weird spacing: '...terface oci...' -- The document date (July 6, 2015) is 3210 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'YANG-IF' is mentioned on line 394, but not defined ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) == Outdated reference: A later version (-25) exists of draft-ietf-netmod-routing-cfg-16 == Outdated reference: A later version (-02) exists of draft-shaikh-idr-bgp-model-01 Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Shakir 3 Internet-Draft BT 4 Intended status: Informational A. Shaikh 5 Expires: January 7, 2016 M. Hines 6 Google 7 July 6, 2015 9 Consistent Modeling of Operational State Data in YANG 10 draft-openconfig-netmod-opstate-01 12 Abstract 14 This document proposes an approach for modeling configuration and 15 operational state data in YANG [RFC6020] that is geared toward 16 network management systems that require capabilities beyond those 17 typically envisioned in a NETCONF-based management system. The 18 document presents the requirements of such systems and proposes a 19 modeling approach to meet these requirements, along with implications 20 and design patterns for modeling operational state in YANG. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 7, 2016. 39 Copyright Notice 41 Copyright (c) 2015 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Requirement to interact with both intended and applied 59 configuration . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4. Operational requirements . . . . . . . . . . . . . . . . . . 6 61 4.1. Applied configuration as part of operational state . . . 6 62 4.2. Support for both transactional, synchronous management 63 systems as well as distributed, asynchronous management 64 systems . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.3. Separation of configuration and operational state data; 66 ability to retrieve them independently . . . . . . . . . 7 67 4.4. Ability to retrieve operational state corresponding 68 only to derived values, statistics, etc. . . . . . . . . 8 69 4.5. Consistent schema locations for configuration and 70 corresponding operational state data . . . . . . . . . . 8 71 5. Implications on modeling operational state . . . . . . . . . 8 72 5.1. Inclusion of applied configuration as part of operational 73 state . . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 5.2. Corresponding leaves for configuration and state . . . . 9 75 5.3. Retrieval of only the derived, or NE-generated part of 76 the operational state . . . . . . . . . . . . . . . . . . 9 77 5.4. Consistency and predictability in the paths where 78 corresponding state and configuration data may be 79 retrieved . . . . . . . . . . . . . . . . . . . . . . . . 9 80 5.5. Reuse of existing NETCONF conventions where applicable . 9 81 6. Proposed operational state structure . . . . . . . . . . . . 10 82 6.1. Example model structure . . . . . . . . . . . . . . . . . 10 83 7. Discussion and observations . . . . . . . . . . . . . . . . . 13 84 8. Impact on model authoring . . . . . . . . . . . . . . . . . . 14 85 8.1. Modeling design patterns . . . . . . . . . . . . . . . . 15 86 8.1.1. Basic structure . . . . . . . . . . . . . . . . . . . 15 87 8.1.2. Handling lists . . . . . . . . . . . . . . . . . . . 15 88 8.1.3. Selective use of state data from common groupings . . 16 89 8.1.4. Non-corresponding configuration and state data . . . 16 90 9. YANG language considerations . . . . . . . . . . . . . . . . 16 91 9.1. Distinguishing derived operational state data and 92 applied configuration . . . . . . . . . . . . . . . . . . 17 93 9.2. YANG lists as maps . . . . . . . . . . . . . . . . . . . 17 94 9.3. Configuration and state data hierarchy . . . . . . . . . 17 95 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 96 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 97 11.1. Normative references . . . . . . . . . . . . . . . . . . 18 98 11.2. Informative references . . . . . . . . . . . . . . . . . 18 99 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 18 100 Appendix B. Example YANG base structure . . . . . . . . . . . . 19 101 Appendix C. Example YANG list structure . . . . . . . . . . . . 20 102 Appendix D. Changes between revisions -00 and -01 . . . . . . . 23 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 105 1. Introduction 107 Retrieving the operational state of a network element (NE) is a 108 critical process for a network operator, both because it determines 109 how the network is currently running (for example, how many errors 110 are occurring on a certain link, what is the load of that link); but 111 also because it determines whether the intended configuration applied 112 by a network management system is currently operational. While 113 configuration changes may be relatively infrequent, accessing the 114 state of the network happens significantly more often. Knowing the 115 real-time state of the network is required for a variety of use cases 116 including traffic management, rapid diagnosis and recovery, and 117 enabling tight control loops (implying reading this data on 118 millisecond timescales). 120 Based on this operational requirement, this document seeks to 121 enumerate the requirements of representing both configuration and 122 operational state data in YANG; propose a common set of terminology; 123 and propose a common layout for configuration and state data such 124 that they can be retrieved from a NE. These proposals are based on 125 the assertion that YANG models should be usable via a number of 126 protocols (not solely IETF- defined protocols such as NETCONF and 127 RESTCONF), and may also be used to carry data that is pushed from 128 devices via streaming rather than polled. 130 2. Terminology 132 In order to understand the way in which a network operator or network 133 management system may need to interact with a device, it is key to 134 understand the different types of data that network elements may 135 store or master: 137 o intended configuration - this data represents the state that the 138 network operator intends the system to be in. This data is 139 colloquially referred to as the 'configuration' of the system. 141 o applied configuration - this data represents the state that the 142 network element is actually in, i.e., that which is currently 143 being run by particular software modules (e.g., the BGP daemon), 144 or other systems within the device (e.g., a secondary control- 145 plane, or line card). 147 o derived state - this data represents information which is 148 generated as part of the system's own interactions. For example, 149 derived state may consist of the results of protocol interactions 150 (the negotiated duplex state of an Ethernet link), statistics 151 (such as message queue depth), or counters (such as packet input 152 or output bytes). 154 The applied configuration and derived state can be considered as the 155 overall 'operational' state of the NE. 157 When an external system desires to change the state of the network 158 element, the changes are written to the intended configuration. This 159 may be done directly or via a set of staged changes. The process of 160 transitioning the intended to applied configuration may be implicit, 161 or explicitly controlled by the network management system (NMS). 162 Derived state is never directly influenced by the external NMS or 163 user, since it is generated based on the systems own interactions. 164 To this end, operational state information can be considered to be 165 'unknown' to the network manager. 167 It is notable that the intended configuration and the applied 168 configuration represent exactly the same set of variables (leaves). 169 These may have different values based on the current point in time 170 (e.g., if the change has not been communicated to an external 171 software entity), or due to missing dependencies (e.g., a particular 172 linecard not being installed). 174 +---------+ 175 | | transition intended 176 |intended | to applied 177 | config +---------+ 178 | | | 179 +---------+ | 180 ^ | config: true 181 +----------|------------------------------------+ 182 | | config: false 183 | | 184 | | 185 | +-----------------------------+ 186 | | | operational state | 187 | | +----v----+ +-----------+ | 188 | | | | | | | 189 + | | applied | | derived | | operational:true 190 same +------>| config | | state |<-------+ 191 leaves | | | | | | 192 | | | | | | 193 | +---------+ +-----------+ | 194 +-----------------------------+ 196 The relationship between intended and applied configuration, and 197 derived state. The combination of the applied and derived state is 198 referred to as the operational state. 200 Figure 1 202 Figure 1 shows the relationship between the different types of state 203 referred to above. The intended configuration (which is read/write) 204 is the only 'config: true' data. The remaining operational state 205 (consisting of applied configuration and derived state) is read-only. 206 Only derived state is marked as operational data. 208 Where the terms 'intended', 'applied', 'derived' and 'operational' 209 are used throughout this document to refer to configuration or state, 210 this should be read as explained above. 212 3. Requirement to interact with both intended and applied configuration 214 An operator or network management system has key requirements to be 215 able to interact with both the intended and applied configuration. 216 The type of interaction with each type of data does differ, however. 217 The intended configuration is writable by the managing entity. That 218 is, intended configuration is the means through which the NMS informs 219 the network element of its desire to change the state of the system. 220 An NMS may read back this intended configuration in order to 221 determine the state that the network element is currently trying to 222 apply. 224 Once such changes have been made to the intended configuration, the 225 NMS interacts with the read-only applied configuration to determine 226 whether the change that was requested has been applied. The NMS can 227 only influence changes to the applied configuration based on writing 228 changes to the intended configuration. The applied configuration 229 cannot be directly changed itself. It is therefore a common 230 operation for an NMS to write to the intended configuration, and 231 subsequently read the applied configuration to determine whether the 232 change has been instantiated. It is therefore of great importance to 233 have a means by which the intended and applied configuration can be 234 easily related to one another programmatically within a single schema 235 to avoid complex mapping between a particular intended configuration 236 leaf and the corresponding applied configuration. 238 Similarly, it is also important to have operational state data for a 239 particular entity easily related to the applied and intended 240 configuration without requiring complex mapping. It should be noted 241 that this does not imply that the NMS layer that is retrieving the 242 operational state data understands the semantics of each data 243 element, but rather that it can retrieve the required set of 244 elements. A number of existing NMS architectures have a logical 245 division between the elements of the system responsible for 246 interacting with the network elements themselves, and those that are 247 responsible for data processing, such that general data retrieval and 248 parsing should be considered separate activities. 250 4. Operational requirements 252 The proposed modeling approach described in this document is 253 motivated by a number of operational requirements. 255 4.1. Applied configuration as part of operational state 257 The definition of operational state in [RFC6244] includes read-only 258 transient data that is the result of system operation or protocol 259 interactions, and data that is typically thought of as counters or 260 statistics. In many operational use cases it is also important to 261 distinguish between the intended value of a configuration variable 262 and its actual configured state, as described above. In non- 263 transactional or asynchronous environments, for example, these may be 264 different and it is important to know when they are different or when 265 they have converged (see requirement #2). For this reason, we 266 consider the applied configuration as an additional important element 267 of the operational state. This is not considered in [RFC6244]. 269 4.2. Support for both transactional, synchronous management systems as 270 well as distributed, asynchronous management systems 272 In a synchronous system, configuration changes are transactional and 273 committed as an atomic unit. This implies that the management system 274 knows the success or failure of the configuration change based on the 275 return value, and hence knows that the intended configuration matches 276 what is on the system (i..e, what has been applied). In particular, 277 the value of any configuration variable should always reflect the 278 (intended) configured value. Synchronous operation is generally 279 associated with a NETCONF-based system that provides transactional 280 semantics for all changes. 282 In an asynchronous system, configuration changes to the system may 283 not be reflected immediately, even though the change operation 284 returns success. Rather, the change is verified by observing the 285 state of the system, for example based on notifications, or 286 continuously streamed values of the state. In this case, the value 287 of a configuration variable may not reflect the intended configured 288 value at a given point in time. 290 The asynchronous use case is important because synchronous operation 291 may not always be possible. For example, in a large scale 292 environment, the management system may not need to wait for all 293 changes to complete if it is acceptable to proceed while some 294 configuration values are being updated. In addition, not all devices 295 may support transactional changes, making asynchronous operation a 296 requirement. Moreover, using observed state to infer the configured 297 value allows the management system to learn the time taken to 298 complete various configuration changes. 300 4.3. Separation of configuration and operational state data; ability to 301 retrieve them independently 303 These requirements are also mentioned in [RFC3535]: 305 o It is necessary to make a clear distinction between configuration 306 data, data that describes operational state, and statistics. 308 o It is required to be able to fetch separately configuration data, 309 operational state data, and statistics from devices, and to be 310 able to compare these between devices. 312 4.4. Ability to retrieve operational state corresponding only to 313 derived values, statistics, etc. 315 When the management system operates in synchronous mode, it should be 316 able to retrieve only the operational state corresponding to the 317 system determined values, such as negotiated values, protocol 318 determined values, or statistics and counters. Since in synchronous 319 mode the intended and applied configuration values are identical, 320 sending the applied configuration state is redundant. 322 4.5. Consistent schema locations for configuration and corresponding 323 operational state data 325 This requirement implies that a common convention is used throughout 326 the schema to locate configuration and state data so that the 327 management system can infer how to access one or the other without 328 needing significant external context. When considering applied 329 configuration as part of operational state (as discussed in 330 Section 4.1), it is similarly required that the intended value vs. 331 actual value for a particular configuration variable should be 332 possible to locate with minimal, if any, mapping information. 334 This requirement becomes more evident when considering the 335 composition of individual data models into a higher-level model for a 336 complete device (e.g., /device[name=devXY]/protocols/routing/...) or 337 even higher layer models maintained by network operators (e.g., /ope 338 ratorX/global/continent[name=eur]/pop[name=paris]/device[name=devXY] 339 /...). If each model has it's own way to separate configuration and 340 state data, then this information must be known at potentially every 341 subtree of the composed model. 343 From an operator perspective it is highly desirable that data nodes 344 are accessible via a single data model - rather than requiring 345 different 'views' of the same data model. This greatly simplifies 346 NMS operation, and eliminates ambiguity for a single path. That is, 347 it avoids the need for an NMS to provide a tuple to 348 uniquely identify a data node. A path should be sufficient to 349 uniquely reference to a piece of data. Utilizing a single data model 350 and set of paths wherever possible, ensures that this existing 351 convention can be continued, and ambiguity of a particular path's 352 value and meaning can be avoided. 354 5. Implications on modeling operational state 356 The requirements in Section 4 give rise to a number of new 357 considerations for modeling operational state. Some of the key 358 implications are summarized below. 360 5.1. Inclusion of applied configuration as part of operational state 362 This implies that a copy of the configurable (i.e., writable) values 363 should be included as read-only variables in containers for 364 operational state, in addition to the derived variables that are 365 traditionally thought of as state data (counters, negotiated values, 366 etc.). 368 5.2. Corresponding leaves for configuration and state 370 Any configuration leaf should have a corresponding state leaf. The 371 opposite is clearly not true -- some parts of the model may only have 372 derived state variables, for example the contents of a routing table 373 that are populated by a dynamic routing protocols like BGP or IS-IS. 375 5.3. Retrieval of only the derived, or NE-generated part of the 376 operational state 378 YANG and NETCONF do not currently differentiate between state that is 379 derived by the NE, state representing statistics, and state 380 representing applied configuration -- all state is simply marked as 381 'config false' or read-only. To retrieve only the state that is not 382 part of intended configuration, we require a new way to tag such 383 data. This is proposed in this document as a YANG extension. 384 Alternatively, as described in [RFC6244], a new NETCONF datastore for 385 operational state that is just for derived state could also be used 386 to allow (or similar) operations to specify just that part of 387 the state. 389 5.4. Consistency and predictability in the paths where corresponding 390 state and configuration data may be retrieved 392 To avoid arbitrary placement of state and configuration data 393 containers, the most consistent options would be at the root of the 394 model (as done in [YANG-IF]) or at the leaves, i.e., at the start or 395 end of the paths. When operators compose models into a higher level 396 model, the root of the model is no longer well-defined, and hence 397 neither is the start of the path. For these reasons, we propose 398 placing configuration and state separation at leaves of the model. 400 5.5. Reuse of existing NETCONF conventions where applicable 402 Though not a specific requirement, models for operational state 403 should take advantage of existing protocol mechanisms where possible, 404 e.g., to retrieve configuration and state data. As mentioned above, 405 this does not mean that the solution for modeling operational state 406 and configuration data should be limited to NETCONF architecture or 407 protocols. 409 6. Proposed operational state structure 411 Below we show an example model structure that meets the requirements 412 described above for all three types of data we are considering: 414 o intended configuration 416 o applied configuration 418 o derived state 420 6.1. Example model structure 422 The example below shows a partial model (in ascii tree format) for 423 managing Ethernet aggregate interfaces (leveraging data definitions 424 from [RFC7223]): 426 +--rw interfaces 427 +--rw interface* [name] 428 +--rw name -> ../config/name 429 +--rw config 430 | ... 431 +--ro state 432 | | ... 433 | +--ro counters 434 | +--ro discontinuity-time yang:date-and-time 435 | +--ro in-octets? yang:counter64 436 | +--ro in-unicast-pkts? yang:counter64 437 | +--ro in-broadcast-pkts? yang:counter64 438 | +--ro in-multicast-pkts? yang:counter64 439 | +--ro in-discards? yang:counter64 440 | +--ro in-errors? yang:counter64 441 | +--ro in-unknown-protos? yang:counter64 442 | +--ro out-octets? yang:counter64 443 | +--ro out-unicast-pkts? yang:counter64 444 | +--ro out-broadcast-pkts? yang:counter64 445 | +--ro out-multicast-pkts? yang:counter64 446 | +--ro out-discards? yang:counter64 447 | +--ro out-errors? yang:counter64 448 +--rw aggregation! 449 +--rw config 450 | +--rw lag-type? aggregation-type 451 | +--rw min-links? uint16 452 +--ro state 453 | +--ro lag-type? aggregation-type 454 | +--ro min-links? uint16 455 | +--ro members* ocif:interface-ref 456 +--rw lacp! 457 +--rw config 458 | +--rw interval? lacp-period-type 459 +--rw members* [interface] 460 | +--rw interface ocif:interface-ref 461 | +--ro state 462 | +--ro activity? lacp-activity-type 463 | +--ro timeout? lacp-timeout-type 464 | +--ro synchronization? lacp-synch-type 465 | +--ro aggregatable? boolean 466 | +--ro collecting? boolean 467 | +--ro distributing? boolean 468 +--ro state 469 +--ro interval? lacp-period-type 471 In this model, the path to the intended configuration (rw) items at 472 the aggregate interface level is: 474 /interfaces/interface[name=ifName]/aggregation/config/... 476 The corresponding applied configuration and derived state is located 477 at: 479 /interfaces/interface[name=ifName]/aggregation/state/... 481 This container holds a read-only copy of the intended configuration 482 variables (lag-type and min-links) - the applied configuration - as 483 well as a generated list of member interfaces (the members leaf-list) 484 for the aggregate that is active when the lag-type indicates a 485 statically configured aggregate (which is derived state). Note that 486 although the paths to config and state containers are symmetric, the 487 state container contains additional derived variables. 489 The model has an additional hierarchy level for aggregate interfaces 490 that are maintained using LACP. For these, the configuration path 491 is: 493 /interfaces/interface[name=ifName]/aggregation/lacp/config/... 495 with the corresponding state container (in this case with only the 496 state corresponding to the applied configuration) at: 498 /interfaces/interface[name=ifName]/aggregation/lacp/state/... 500 There is an additional list of members for LACP-managed aggregates 501 with only a state container: 503 /interfaces/interface[name=ifName]/aggregation/lacp/ 504 members[name=ifName]/state/... 506 Note that it is not required that both a state and a config container 507 be present at every leaf. It may be convenient to include an empty 508 config container to make it more explicit to the management system 509 that there are no configuration variables at this location in the 510 data tree. 512 Finally, we can see that the generic interface object also has config 513 and state containers (these are abbreviated for clarity). The state 514 container has a subcontainer for operational state corresponding to 515 counters and statistics that are valid for any interface type: 517 /interfaces/interface[name=ifName]/state/counters/... 519 7. Discussion and observations 521 A number of issues have been raised with the proposed solution, which 522 are documented below, along with the authors observations relating to 523 these issues. 525 1. The proposed solution decreases the readability of a YANG data 526 model for some, or the ease of writing a model for others. It is 527 difficult to make this judgment without being subjective - the 528 complexity in model writing (as is noted in the above section) is 529 only at the expense of meeting the operational requirement 530 described in this document. The authors consider that this is a 531 fair trade-off between one-time modeling complexity. It could 532 also be observed that a common convention for representing 533 operational state data alongside configuration improved 534 readability. 536 2. Data is duplicated on the wire by this proposal. The intention 537 of defining a set of annotations for data (operational: true, or 538 the data-type flag proposed below) is in order to allow RPCs to 539 be defined which return only specific types of data. For 540 example, a >get-operational< call may return only values with 541 operational: true so that an NMS can return a specific set of 542 data to the requesting entity. 544 3. The proposal does not allow items that are not configured, 545 configured but not present, or system configured. A common 546 example which is quoted is where there are elements that are not 547 configured, or are system-generated based on some other 548 configuration. For example, consider a model whereby an 'all' 549 interface is configured, which corresponds to all interfaces on 550 the system. In this case, the intended configuration should 551 include only the 'all' interface which is configured. This 552 intended configuration should be reflected to the applied 553 configuration. The operational state should contain per- 554 interface (e.g., eth0, Fa0/1) values relating to the interface 555 entities that exist in the network. The intended configuration 556 corresponds solely to a particular interface (e.g., eth0) -- 557 there should be no corresponding 'intended' configuration. In 558 these cases, there is no 'intended' configuration for an entity, 559 but there is an 'applied' configuration present. One challenge 560 here relates to the fact that YANG's list semantics currently 561 imply that that the "config true" interface-name leaf has been 562 set - in practice, it is unlikely that this list key is actually 563 configurable in any real system (it must correspond to a real 564 interface, which has an explicit name according to the system 565 implementation). Additionally, this could be resolved with the 566 alternative map type described later in this document. 568 4. It is not clear what to do when the intended and applied 569 configuration differ. The proposal made in this document makes 570 no presumption as to the actions that are taken when intended and 571 applied leaves for a certain value differ. In fact, it is the 572 expectation of the authors that there is separation between 573 elements of the NMS that are responsible for retrieving data from 574 network elements, as opposed to those that need to understand 575 process this data. The fact that this layer interacting with the 576 network can retrieve both intended and applied configuration, and 577 find the corresponding operational state data in a consistent 578 manner is independently useful regardless of whether the 579 semantics of the contained data are understood. 581 5. An operational-path statement could be used to point between 582 intended and applied configuration. Essentially, this proposal 583 moves the mapping dictionary on a per-leaf basis within the data 584 model itself. It appears to be a more complex solution that the 585 proposed approach within this document which does not require any 586 need to build a per-leaf mapping. 588 6. Models that do not follow the proposed pattern would not be 589 usable. Models that do not follow the structural convention for 590 modeling operational state data would require some refactoring to 591 meet the requirements described in this document. However, by 592 following the design pattern for YANG grouping described in 593 Section Section 8.1.1 it becomes possible to leverage existing 594 modules by importing them and reusing the groupings. More 595 specifically, if models are designed with only configuration or 596 state related data leaf nodes in groupings, another model could 597 create the required structure and reuse these groupings. 599 8. Impact on model authoring 601 One drawback of structuring operational and configuration data in 602 this way is the added complexity in authoring the models, relative to 603 the way some models are currently built with state and config split 604 at the root of the individual model (e.g., in [RFC7223], [RFC7317], 605 and [IETF-RTG]). Moving the config and state containers to each leaf 606 adds a one-time modeling effort, which is somewhat dependent on the 607 model structure itself (how many layers of container hierarchy, 608 number of lists, etc.) However, we feel this effort is justified by 609 the resulting simplicity with which management systems can access and 610 correlate state and configuration data. 612 8.1. Modeling design patterns 614 We propose some specific YANG modeling design patterns that are be 615 useful for building models following these conventions. 617 8.1.1. Basic structure 619 Since leaves that are created under the 'config' container also 620 appear under the 'state' container, it is recommended that the 621 following conventions are used to ensure that the schema remain as 622 simple as possible: 624 o A grouping for the intended configuration data items is created - 625 with a specific naming convention to indicate that such variables 626 are configurable, such as a suffix like '-config' or '_config'. 627 For example, the OpenConfig BGP model [OC-BGP] adopts the 628 convention of appending "_config" to the name of the grouping. 630 o A grouping for the derived state data items is created, with a 631 similar naming convention as above, i.e., with a suffix such as 632 '-state' or '_state'. The BGP model uses "_state". 634 o A 'structural' grouping is created that instantiates both the 635 'config' and 'state' containers. The 'config' container should 636 include the "-config" grouping, whilst the state container has 637 both the "-config" and "-state" groupings, along with the 'config 638 false' statement. 640 A simple example in YANG is shown in Appendix B. 642 8.1.2. Handling lists 644 In YANG 1.0, lists have requirements that complicate the creation of 645 the parallel configuration and state data structures. First, keys 646 must be children of the list; they cannot be further down the data 647 hierarchy within a subsequent container. For example, the 648 'interface' list cannot be keyed by /interfaces/interface/config/ 649 name. Second, YANG requires that the list key is part of the 650 configuration or state data in each list member. 652 We consider two possible approaches for lists: 654 1. list keys appear only at the top level of the list, i.e., not 655 duplicated under the 'config' or 'state' containers within the 656 list 658 2. the data represented by the list key appears in the config and 659 state containers, and a key with type leafref is used in the top 660 level of the list pointing to the corresponding data node in the 661 config (or state) container. 663 Option 1 has the advantage of not duplicating data, but treats the 664 data item (or items) that are keys as special cases, i.e., not 665 included in the config or state containers. Option 2 is appealing in 666 that configurable data always appears in the config container, but 667 requires an arguably unnecessary key pointing to the data from the 668 top level of the list. 670 Appendix C shows a simple example of both options. 672 8.1.3. Selective use of state data from common groupings 674 In a number of cases, it is desirable that the same grouping be used 675 within different places in a model - but state information is only 676 relevant in one of these paths. For example, considering BGP, peer 677 configuration is relevant to both a "neighbor" (i.e., an individual 678 BGP peer), and also to a peer-group (a set of peers). Counters 679 relating to the number of received prefixes, or queued messages, are 680 relevant only within the 'state' container of the peer (rather than 681 the peer-group). In this case, use of the 'augment' statement to add 682 specific leaves to only one area of the tree is recommended, since it 683 allows a common grouping to be utilized otherwise. 685 8.1.4. Non-corresponding configuration and state data 687 There are some instances where only an operational state container is 688 relevant without a corresponding configuration data container. For 689 example, the list of currently active member interfaces in a LACP- 690 managed LAG is typically reported by the system as operational state 691 that is governed by the LACP protocol. Such data is not directly 692 configured. Similarly, counters and statistics do not have 693 corresponding configuration. In these cases, we can either omit the 694 config container from such leaves, or provide an empty container as 695 described earlier. With both options, the management system is able 696 to infer that such data is not configurable. 698 9. YANG language considerations 700 In adopting the approach described in this document for modeling 701 operational state data in YANG, we encounter several language 702 limitations that are described below. We discuss some initial 703 thoughts on possible changes to the language to more easily enable 704 the proposed model for operational state modeling. 706 9.1. Distinguishing derived operational state data and applied 707 configuration 709 As mentioned in Section 4, we require a way to separately query 710 operational state that is not part of applied configuration (e.g., 711 protocol-determined data, counters, etc.). YANG and NETCONF do not 712 distinguish types of operational state data, however. To overcome 713 this, we currently use a YANG language extension to mark such data as 714 'operational: true'. Ideally, this could be generalized beyond the 715 current 'config: true / false' to mark "data-type: intended", "data- 716 type: applied", "data-type: derived" to allow filtering of particular 717 types of data by a protocol RPC. 719 9.2. YANG lists as maps 721 YANG has two list constructs, the 'leaf-list' which is similar to a 722 list of scalars (arrays) in other programming languages, and the 723 'list' which allows a keyed list of complex structures, where the key 724 is also part of the data values. As described in Section 8.1.2, the 725 current requirements on YANG list keys require either duplication of 726 data, or treating some data (i.e., those that comprise list keys) as 727 a special case. One solution is to generalize lists to be more like 728 map data structures found in most modern programming languages, where 729 each list member has a key that is not required to part of the 730 configuration or state data, and also not subject to existing 731 "config-under-state limitations. This allows list keys to be 732 arbitrarily defined by the user if desired, or based on values of 733 data nodes. In the latter case, the specification of which data 734 nodes are used in constructing the list key could be indicated in the 735 meta-data associated with the key. 737 9.3. Configuration and state data hierarchy 739 YANG does not allow read-write configuration data to be child nodes 740 of read-only operational state data. This requires the definition of 741 separate state and config containers as described above. However, it 742 may be desirable to simplify the schema by 'flattening', e.g., having 743 the operational state as the root of the data tree, with only config 744 containers needed to specify the variables that are writable (in 745 general, the configuration data is much smaller than operational 746 state data). Naming the containers explicitly according the config / 747 state convention makes the intent of the data clear, and should allow 748 relaxing of the current YANG restrictions. That is, a read-write 749 config container makes explicit the nature of the enclosed data even 750 if the parent data nodes are read-only. This of course requires that 751 all data in a config container are in fact configurable -- this is 752 one of the motivations of pushing such containers as far down in the 753 schema hierarchy as possible. 755 10. Security Considerations 757 This document addresses the structure of configuration and 758 operational state data, both of which should be considered sensitive 759 from a security standpoint. Any data models that follow the proposed 760 structuring must be carefully evaluated to determine its security 761 risks. In general, access to both configuration (write) and 762 operational state (read) data must be controlled through appropriate 763 access control and authorization mechanisms. 765 11. References 767 11.1. Normative references 769 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 770 Network Configuration Protocol (NETCONF)", RFC 6020, 771 October 2010. 773 [RFC6244] Shafer, P., "An Architecture for Network Management Using 774 NETCONF and YANG", RFC 6244, June 2011. 776 [RFC3535] Schoenwaelder, J., "Overview of the 2002 IAB Network 777 Management Workshop", RFC 3535, May 2003. 779 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 780 Management", RFC 7223, May 2014. 782 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 783 System Management", RFC 7317, August 2014. 785 11.2. Informative references 787 [IETF-RTG] 788 Lhotka, L., "A YANG Data Model for Routing Management", 789 draft-ietf-netmod-routing-cfg-16 (work in progress), 790 October 2014. 792 [OC-BGP] Shaikh, A., D'Souza, K., Bansal, D., and R. Shakir, "BGP 793 Configuration Model for Service Provider Networks", draft- 794 shaikh-idr-bgp-model-01 (work in progress), March 2015. 796 Appendix A. Acknowledgments 798 The authors are grateful for valuable input to this document from: 799 Lou Berger, Martin Bjorklund, Paul Borman, Chris Chase, Raymond Cheh, 800 Feihong Chen, Benoit Claise, Josh George, Carl Moberg, Jason Sterne, 801 Jim Uttaro, and Kent Watsen. 803 Appendix B. Example YANG base structure 805 Below we show an example of the basic YANG building block for 806 organizing configuration and operational state data as described in 807 Section 6 809 grouping example-config { 810 description "configuration data for example container"; 812 leaf conf-1 { 813 type empty; 814 } 816 leaf conf-2 { 817 type string; 818 } 819 } 821 grouping example-state { 822 description 823 "operational state data (derived, counters, etc.) for example 824 container"; 826 leaf state-1 { 827 type boolean; 828 operational true; 829 } 831 leaf state-2 { 832 type string; 833 } 835 container counters { 836 description 837 "operational state counters for example container"; 839 operational true; 841 leaf counter-1 { 842 type uint32; 843 } 845 leaf counter-2 { 846 type uint64; 847 } 848 } 849 } 850 grouping example-structure { 851 description 852 "top level grouping for the example container -- this is used 853 to put the config and state subtrees in the appropriate 854 location"; 856 container example { 857 description 858 "top-level container for the example data"; 860 container config { 862 uses example-config; 864 } 866 container state { 868 config false; 869 uses example-config; 870 uses example-state; 871 } 872 } 873 } 875 uses example-structure; 877 The corresponding YANG data tree is: 879 +--rw example 880 +--rw config 881 | +--rw conf-1? empty 882 | +--rw conf-2? string 883 +--ro state 884 +--ro conf-1? empty 885 +--ro conf-2? string 886 +--ro state-1? boolean 887 +--ro state-2? string 888 +--ro counters 889 +--ro counter-1? uint32 890 +--ro counter-2? uint64 892 Appendix C. Example YANG list structure 894 As described in Section 8.1.2, there are two options we consider for 895 building lists according to the proposed structure. Both are shown 896 in the example YANG snippet below. The groupings defined above in 897 Appendix B are reused here. 899 grouping example-no-conf2-config { 900 description 901 "configuration data for example container but without the conf-2 902 data leaf which is used as a list key"; 904 leaf conf-1 { 905 type empty; 906 } 908 } 910 grouping example-structure { 911 description 912 "top level grouping for the example container -- this is used 913 to put the config and state subtrees in the appropriate 914 location"; 916 list example { 918 key conf-2; 919 description 920 "top-level list for the example data"; 922 leaf conf-2 { 923 type leafref { 924 path "../config/conf-2"; 925 } 926 } 928 container config { 930 uses example-config; 932 } 934 container state { 936 config false; 937 uses example-config; 938 uses example-state; 939 } 940 } 942 list example2 { 944 key conf-2; 945 description 946 "top-level list for the example data"; 948 leaf conf-2 { 949 type string; 950 } 952 container config { 954 uses example-no-conf2-config; 956 } 958 container state { 960 config false; 961 uses example-no-conf2-config; 962 uses example-state; 963 } 964 } 965 } 967 uses example-structure; 969 The corresponding YANG data tree is shown below for both styles of 970 lists. 972 +--rw example* [conf-2] 973 | +--rw conf-2 -> ../config/conf-2 974 | +--rw config 975 | | +--rw conf-1? empty 976 | | +--rw conf-2? string 977 | +--ro state 978 | +--ro conf-1? empty 979 | +--ro conf-2? string 980 | +--ro state-1? boolean 981 | +--ro state-2? string 982 | +--ro counters 983 | +--ro counter-1? uint32 984 | +--ro counter-2? uint64 985 +--rw example2* [conf-2] 986 +--rw conf-2 string 987 +--rw config 988 | +--rw conf-1? empty 989 +--ro state 990 +--ro conf-1? empty 991 +--ro state-1? boolean 992 +--ro state-2? string 993 +--ro counters 994 +--ro counter-1? uint32 995 +--ro counter-2? uint64 997 Appendix D. Changes between revisions -00 and -01 999 The -01 revision of this documents reflects a number of discussions 1000 with implementors and members of several IETF working groups, 1001 including NETMOD. Major changes from the prior version are 1002 summarized below. 1004 o Updated introduction to provide additional background on 1005 operational requirements. 1007 o Added a detailed terminology section and diagram to provide 1008 definitions of different types of modeled data based on working 1009 group discussions. 1011 o Added new discussion section summarizing issues that have been 1012 raised with the proposal as well as operator observations and 1013 comment. 1015 Authors' Addresses 1017 Rob Shakir 1018 BT 1019 pp. C3L, BT Centre 1020 81, Newgate Street 1021 London EC1A 7AJ 1022 UK 1024 Email: rob.shakir@bt.com 1025 URI: http://www.bt.com/ 1027 Anees Shaikh 1028 Google 1029 1600 Amphitheatre Pkwy 1030 Mountain View, CA 94043 1031 US 1033 Email: aashaikh@google.com 1035 Marcus Hines 1036 Google 1037 1600 Amphitheatre Pkwy 1038 Mountain View, CA 94043 1039 US 1041 Email: hines@google.com