idnits 2.17.1 draft-bjorklund-netmod-operational-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (Using the creation date from RFC6020, updated by this document, for RFC5378 checks: 2008-05-14) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 5, 2012) is 4214 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 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: 6020 (if approved) L. Lhotka 5 Intended status: Standards Track CZ.NIC 6 Expires: April 8, 2013 October 5, 2012 8 Operational Data in NETCONF and YANG 9 draft-bjorklund-netmod-operational-00 11 Abstract 13 This document defines the concept of operational state data in the 14 context of YANG and the Network Configuration Protocol (NETCONF). It 15 updates RFC 6020 with rules for how to model the operational state, 16 and defines NETCONF operations to retrieve and modify the operational 17 state. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 8, 2013. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1.1. Terms . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 5 58 3.1. Modeling and Retrieving Operational State . . . . . . . . 5 59 3.1.1. Example: Interface List . . . . . . . . . . . . . . . 5 60 3.2. Modifying the Operational State . . . . . . . . . . . . . 6 61 3.2.1. Example: Routing Table Modification . . . . . . . . . 7 62 4. Datastores . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4.1. Operational State Datastore . . . . . . . . . . . . . . . 8 64 4.2. Configuration Datastore . . . . . . . . . . . . . . . . . 9 65 5. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 5.1. Alternative A . . . . . . . . . . . . . . . . . . . . . . 10 67 5.2. Alternative B . . . . . . . . . . . . . . . . . . . . . . 10 68 5.3. Alternative C . . . . . . . . . . . . . . . . . . . . . . 10 69 6. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 11 70 6.1. . . . . . . . . . . . . . . . . . . . . 11 71 6.1.1. Example: Ethernet Duplex . . . . . . . . . . . . . . . 11 72 6.2. . . . . . . . . . . . . . . . . . . . . 12 73 7. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 16 76 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 77 10.1. Normative References . . . . . . . . . . . . . . . . . . . 17 78 10.2. Informative References . . . . . . . . . . . . . . . . . . 17 79 Appendix A. Example: Interface List . . . . . . . . . . . . . . . 18 80 Appendix B. Example: Ethernet Duplex . . . . . . . . . . . . . . 19 81 Appendix C. Example: Admin vs. Oper State . . . . . . . . . . . . 20 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 84 1. Introduction 86 1.1. Terminology 88 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 90 "OPTIONAL" in this document are to be interpreted as described in BCP 91 14, [RFC2119]. 93 1.1.1. Terms 95 The following terms are defined in [RFC6241] and are not redefined 96 here: 98 o client 100 o configuration datastore 102 o datastore 104 o server 106 The following terms are defined in [RFC6020] and are not redefined 107 here: 109 o data model 111 o schema tree 113 o data node 115 The following terms are used within this document: 117 o operational state data: The data in the operational state 118 datastore. 120 o operational state datastore: A conceptual data structure from 121 which one can determine device state and behavior. 123 2. Objectives 125 o Develop a general model applicable not only to NETCONF but also to 126 other approaches (RESTful, editable state data etc.). 128 o Develop a specific model for NETCONF and YANG. 130 o As little changes to NETCONF and YANG as possible. 132 o Clarification of the terms "operational state data" and 133 "configuration". 135 3. Problem Statement 137 3.1. Modeling and Retrieving Operational State 139 The NETCONF operation returns both device state data and the 140 running configuration. Quite often, device parameters require a dual 141 representation, both as configuration and state data. 143 For instance, an IP address may be specified in an interface 144 configuration but, depending on other circumstances, this address may 145 not be used for that interface. In any case, an operator should be 146 able to obtain the addresses that are in operational use. 148 This implies that some state data must be modeled separately from the 149 configuration data, which leads to a certain amount of duplication in 150 data models. This approach has other drawbacks, too. It is counter- 151 intuitive to data model designers, for whom configuration and state 152 parameters are closely related (see Section 3.1.1 for an example). 153 Data model duplication is error prone and leads to bigger data 154 models, that are more difficult to understand. Further, there is no 155 formal information in the data model about the relationship between 156 the configuration and operational state data. 158 3.1.1. Example: Interface List 160 Suppose we want to model a list of interfaces. We allow pre- 161 configuration, i.e., it is legal to configure an interface for which 162 there is currently no hardware present in the system. In this simple 163 example, each interface has a name and a counter of the number of 164 packets received. The counter is operational state data. 166 list interface { 167 key name; 169 leaf name { ... } 170 leaf in-packets { 171 type yang:counter64; 172 config false; 173 } 174 ... 175 } 177 A particular device has hardware for two interfaces with names "eth0" 178 and "eth1". In the configuration there is: 180 181 eth0 182 ... 183 184 185 eth2 186 ... 187 189 We can see this by doing . 191 Operationally, however, the interfaces used are "eth0" and "eth1", 192 although "eth1" does not have any configuration and does not send or 193 receive packets. 195 How can an operator learn about the presence of "eth1"? The 196 operation returns the running configuration and state data together. 197 So, will not show "eth1", since it is not present in the 198 running configuration. 200 With NETCONF as currently defined, the only alternative is to 201 duplicate the data model: 203 list interface { 204 key name; 206 leaf name { ...} 207 ... 208 } 210 list interface-oper { 211 config false; 212 key name; 214 leaf name { ...} 215 leaf in-packets { ... } 216 ... 217 } 219 3.2. Modifying the Operational State 221 In some cases, it is useful for clients to directly modify the 222 operational state. An example of this is the recent discussions 223 around an Interface to the Routing System (IRS), where a client needs 224 to modify the routing table, without storing routes in the 225 configuration. 227 With NETCONF as currently designed, the only way to do this is to 228 define separate rpc operations. This leads to another kind of data 229 model duplication, where every writable parameter is modeled both as 230 state data that can be retrieved using the operation, and also 231 as input parameters to at least one rpc operation. 233 3.2.1. Example: Routing Table Modification 235 Suppose we want to model IPv4 routing tables as operational state, 236 and we also want to be able to let a client modify this data. We 237 have to do: 239 list routing-table { 240 config false; 241 key name; 243 leaf name { ... } 244 list route { 245 key id; 247 leaf id { ... } 248 leaf dest-prefix { ... } 249 leaf next-hop { ... } 250 ... 251 } 252 } 254 rpc add-route { 255 input { 256 leaf routing-table-name { ... } 257 leaf route-id { ... } 258 leaf dest-prefix { ... } 259 leaf next-hop { ... } 260 } 261 } 263 rpc delete-route { 264 input { 265 leaf routing-table-name { ... } 266 leaf route-id { ... } 267 } 268 } 270 4. Datastores 272 The fundamental idea of this document is to define operational state 273 data as an explicit data structure called the operational state 274 datastore. It is available to all management interfaces, which 275 includes NETCONF but also other interfaces such as SNMP. 277 The "running" configuration datastore is viewed as a separate overlay 278 data structure whose layout is identical to the subset of the 279 operational state datastore that represents configuration. 281 4.1. Operational State Datastore 283 The operational state datastore consists of all parameters that 284 provide information about the instantaneous state of the device and 285 immediately influence the device's behavior. 287 The operational state datastore is a conceptual data structure. This 288 means that implementations may choose any suitable representation of 289 the datastore, or even generate it dynamically upon request. 291 Operational state may be modified through one or more management 292 interfaces, or through the operation of network protocols. All such 293 means of accessing and changing the operational state act 294 conceptually on the same data - the operational state datastore. It 295 means, for instance, that any change caused by a network protocol is 296 immediately visible to all management interfaces. 298 The schema for the operational state datastore is made up of all data 299 nodes defined in YANG modules, specifically both "config true" and 300 "config false" data nodes. 302 Note that when is used to retrieve a "config true" node, 303 the value stored in the configuration datastore is returned. When 304 is used to retrieve the same node, the value 305 actually used by the device is returned. This value may or may not 306 be the same as the value in the datastore. 308 +-------------------------------------------------------------------+ 309 | Open Question | 310 +-------------------------------------------------------------------+ 311 | Should there be a YANG statement 'operational ' so that | 312 | config true nodes can be marked as not being part of the | 313 | operational schema? | 314 +-------------------------------------------------------------------+ 316 Nodes in the operational data store cannot be directly modified using 317 the standard NETCONF operations. 319 +-------------------------------------------------------------------+ 320 | Open Question | 321 +-------------------------------------------------------------------+ 322 | introduce oper:writable for nodes that can be modified by | 323 | . | 324 +-------------------------------------------------------------------+ 326 4.2. Configuration Datastore 328 The configuration datastore can be thought of as a blueprint for the 329 operational datastore. Specifically, the schema for the 330 configuration datastore is congruent to a subtree of the schema for 331 operational state datastore containing only "config true" nodes. In 332 other words, every data node in the configuration datastore schema 333 has a corresponding data node with the same name in the operational 334 datastore schema, and the latter data node is "config true". 336 Whenever a NETCONF client modifies the configuration datastore, the 337 server MUST immediately attempt to project the changes into the 338 operational state datastore. Most of the time, it simply means 339 copying the values in the configuration datastore to the 340 corresponding nodes in the operational state datastore. If a leaf's 341 default value is in use (See section 7.6.1. of RFC 6020), the default 342 value is copied to the operational data store. 344 The configuration datastore may contain data nodes that are not 345 projected into the operational state datastore. This happens in the 346 following three scenarios: 348 1. Pre-provisioned configuration prepared for hardware components 349 that are not yet present in the device. See Section 3.1.1 above. 351 2. Pre-provisioned configuration for components (hardware, 352 protocols, etc.) that are intended to replace an existing item 353 but are of a different type. 355 3. Parts of configuration that are momentarily not applicable. 357 5. Constraints 359 This document updates section 8 of RFC 6020 with rules for the 360 operational state datastore. 362 NOTE: The rest of this section documents some alternatives that the 363 authors want to discuss 365 There are a couple of design alternatives here: 367 5.1. Alternative A 369 No constraints ("must", "mandatory", "unique", "min-elements", 370 "max-elements") are enforced on the operational state datastore. For 371 example, this means that a mandatory "config true" leaf does not have 372 to be present in the operational state datastore. 374 The problem with this approach is that there is no way to formally 375 define constraints on the OSD in the data model. This may be needed 376 in order to allow for coexistence of NETCONF with other management 377 interfaces that do not use the configuration datastore. Such 378 constraints can be specified in description statement though. 380 5.2. Alternative B 382 Change the definitions of mandatory, must, to work on osd instead of 383 config. 385 This would be a major backwards incompatible change to YANG, and it 386 would not be possible to define constraints on the configuration. 388 5.3. Alternative C 390 Introduce new YANG statements for OSD constraints, e.g. osd:must, 391 osd:mandatory etc. 393 The drawback with this is that it adds complexity. 395 6. Protocol Operations 397 6.1. 399 This document introduces a new operation , which is 400 used to retrieve the operational state data from a device. Note how 401 this operation differs from , which is used to retrieve both the 402 running configuration and state data. 404 takes the same parameters as . 406 Since leafs with default values defined in the data model are always 407 explicitly set in the operational data store, there is no need for 408 :with-defaults handling in the operation. 410 6.1.1. Example: Ethernet Duplex 412 As an example, consider a very simplified data model with a single 413 leaf for ethernet duplex: 415 leaf duplex { 416 type enumeration { 417 enum "half"; 418 enum "full"; 419 enum "auto"; 420 } 421 config true; 422 } 424 Suppose a device with this data model implements the candidate 425 datastore. The following is an example of data from such a device: 427 get-config from candidate: 429 half 431 get-config from running: 433 auto 435 get-operational: 437 full 439 In this example, the running configuration tells the device to 440 negotiate the duplex mode, and the current, operationally used, value 441 is "full". At the same time, the (uncommitted) candidate 442 configuration contains the value "half". 444 6.2. 446 [Editor's note: NOT FINISHED - not clear if we need this] 448 Introduce edit-operational. This modifies the subset of the 449 operational data tree that is also marked as writable. 451 Drawback: does not handle persistent operational data. If we have 452 persistent operational data, this has to be its own data store that 453 can be read and written. 455 A data model w/o the writable markers cannot be written to. This is 456 a problem, since it is not obvious that the original designer though 457 about future use cases. For example, our route tables are read-only. 458 Then IRS comes along and wants to write to this data. Do we have to 459 update our spec? Not good. One option is for IRS to publish a 460 deviation data model that added the writable statement to our model. 461 This would be backwards compliant and good. Even better would be if 462 they could publish a conformance statement in a module, w/o the need 463 for deviations. 465 7. YANG Module 467 RFC Ed.: update the date below with the date of RFC publication and 468 remove this note. 470 file "ietf-netconf-operational.yang" 472 module ietf-netconf-operational { 474 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-operational"; 475 prefix "oper"; 477 import ietf-yang-types { 478 prefix yang; 479 } 480 import ietf-inet-types { 481 prefix inet; 482 } 483 import ietf-netconf { 484 prefix nc; 485 } 487 rpc get-operational { 488 input { 489 choice filter-spec { 490 anyxml subtree-filter { 491 description 492 "This parameter identifies the portions of the 493 operational state datastore to retrieve."; 494 reference "RFC 6241, Section 6."; 495 } 496 leaf xpath-filter { 497 if-feature nc:xpath; 498 type yang:xpath1.0; 499 description 500 "This parameter contains an XPath expression 501 identifying the portions of the operational state 502 datastore to retrieve."; 503 } 504 } 505 } 507 output { 508 anyxml data { 509 description 510 "Copy of the operational state data that matched the filter 511 criteria (if any). An empty data container indicates that 512 the request did not produce any results."; 514 } 515 } 516 } 518 rpc edit-operational { 519 input { 520 leaf default-operation { 521 type enumeration { 522 enum merge { 523 description 524 "The default operation is merge."; 525 } 526 enum replace { 527 description 528 "The default operation is replace."; 529 } 530 enum none { 531 description 532 "There is no default operation."; 533 } 534 } 535 default "merge"; 536 description 537 "The default operation to use."; 538 } 540 choice edit-content { 541 mandatory true; 542 description 543 "The content for the edit operation."; 545 anyxml data { 546 description 547 "Inline data content."; 548 } 549 leaf url { 550 if-feature nc:url; 551 type inet:uri; 552 description 553 "URL-based config content."; 554 } 555 } 556 } 557 } 558 } 560 562 8. IANA Considerations 564 This document registers a URI in the IETF XML registry [RFC3688]. 565 Following the format in RFC 3688, the following registration is 566 requested to be made. 568 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-operational 570 Registrant Contact: The NETMOD WG of the IETF. 572 XML: N/A, the requested URI is an XML namespace. 574 This document registers a YANG module in the YANG Module Names 575 registry [RFC6020]. 577 name: ietf-netconf-operational 578 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-operational 579 prefix: oper 580 reference: RFC XXXX 582 9. Security Considerations 584 This document does not introduce any new security concerns in 585 addition to those specified in [RFC6020] and [RFC6241]. 587 10. References 589 10.1. Normative References 591 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 592 Requirement Levels", BCP 14, RFC 2119, March 1997. 594 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 595 Network Configuration Protocol (NETCONF)", RFC 6020, 596 October 2010. 598 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 599 and A. Bierman, Ed., "Network Configuration Protocol 600 (NETCONF)", RFC 6241, June 2011. 602 10.2. Informative References 604 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 605 January 2004. 607 Appendix A. Example: Interface List 609 With the proposed solution, the interface list example from ^ex-if- 610 list-2, can be solved with a single list: 612 list interface { 613 key name; 615 leaf name { ... } 616 leaf in-packets { 617 type yang:counter64; 618 config false; 619 } 620 ... 621 } 623 The operation will return the interfaces available 624 on the device: 626 627 eth0 628 ... 629 630 631 eth1 632 ... 633 635 And on running will return the configured interfaces, 636 just as before: 638 639 eth0 640 ... 641 642 643 eth2 644 ... 645 647 Appendix B. Example: Ethernet Duplex 649 A typical problem is when the value space for the configuration data 650 is a super set of the value space for the operational state data. An 651 example of this is Ethernet duplex, which can be configured as 652 "half", "full", or "auto", but the operationally used value is either 653 "half" or "full". Without the definition of operational state in 654 this document, this would have to be modeled as two separate leafs: 656 leaf duplex { 657 type enumeration { 658 enum "half"; 659 enum "full"; 660 enum "auto"; 661 } 662 } 664 leaf oper-duplex { 665 type enumeration { 666 enum "half"; 667 enum "full"; 668 } 669 } 671 With the solution defined in this document, a single leaf is 672 sufficient: 674 leaf duplex { 675 type enumeration { 676 enum "half"; 677 enum "full"; 678 enum "auto"; 679 } 680 } 682 Appendix C. Example: Admin vs. Oper State 684 Another common problem is when the value space for the configured 685 data is a subset of the operational state data. An example is an 686 interface's desired state, and its operational state. The desired 687 state can be "up" or "down", but the operational state can be "up", 688 "lower-layer-down", "testing", etc. 690 These kind of situations are still best modeled as two separate 691 leafs, one "admin-state" and one "oper-state". 693 Authors' Addresses 695 Martin Bjorklund 696 Tail-f Systems 698 Email: mbj@tail-f.com 700 Ladislav Lhotka 701 CZ.NIC 703 Email: lhotka@nic.cz