idnits 2.17.1 draft-kwatsen-netmod-opstate-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 : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (September 2, 2015) is 3158 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: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track A. Bierman 5 Expires: March 5, 2016 Yumaworks 6 M. Bjorklund 7 Tail-f Systems 8 J. Schoenwaelder 9 Jacobs University Bremen 10 September 2, 2015 12 Operational State Enhancements for YANG, NETCONF, and RESTCONF 13 draft-kwatsen-netmod-opstate-00 15 Abstract 17 This document presents enhancements to YANG, NETCONF, and RESTCONF to 18 better support the definition of and access to operational state 19 data. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 5, 2016. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Conceptual Model . . . . . . . . . . . . . . . . . . . . . . 4 58 4. Enhancements to YANG . . . . . . . . . . . . . . . . . . . . 5 59 4.1. The related-state Statement . . . . . . . . . . . . . . . 5 60 4.1.1. YANG Module . . . . . . . . . . . . . . . . . . . . . 6 61 4.1.2. Usage Example . . . . . . . . . . . . . . . . . . . . 6 62 5. Enhancements to NETCONF . . . . . . . . . . . . . . . . . . . 7 63 5.1. The Operation . . . . . . . . . . . . . . . . 7 64 5.1.1. YANG Module . . . . . . . . . . . . . . . . . . . . . 8 65 5.2. The Applied Configuration Capability . . . . . . . . . . 8 66 5.2.1. Description . . . . . . . . . . . . . . . . . . . . . 8 67 5.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 9 68 5.2.3. Capability Identifier . . . . . . . . . . . . . . . . 9 69 5.2.4. New Operations . . . . . . . . . . . . . . . . . . . 9 70 5.2.5. Modifications to Existing Operations . . . . . . . . 9 71 5.2.6. YANG Module . . . . . . . . . . . . . . . . . . . . . 9 72 5.2.7. Example . . . . . . . . . . . . . . . . . . . . . . . 10 73 6. Enhancements to RESTCONF . . . . . . . . . . . . . . . . . . 10 74 6.1. The Applied Configuration Capability . . . . . . . . . . 10 75 6.1.1. Description . . . . . . . . . . . . . . . . . . . . . 10 76 6.1.2. The applied capability . . . . . . . . . . . . . . . 11 77 6.1.3. The "applied" Query Parameter . . . . . . . . . . . . 11 78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 80 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 10.1. Normative References . . . . . . . . . . . . . . . . . . 11 83 10.2. Informative References . . . . . . . . . . . . . . . . . 12 85 1. Introduction 87 Support for operational state has been defined in YANG [RFC6020], 88 NETCONF [RFC6241], and RESTCONF [draft-ietf-netconf-restconf] since 89 their beginnings. However, after some operational experience, the 90 support defined by these standards has been found to be limiting 91 [draft-openconfig-netmod-opstate] as follows: 93 o YANG 95 * Inability to associate operational state with configured state 97 o NETCONF 99 * Inability to retrieve operational state without also retrieving 100 running configuration 102 * Inability to inspect the configuration as it is operationally 103 running 105 o RESTCONF 107 * Inability to inspect the configuration as it is operationally 108 running 110 Addressing these limitations is the focus of this document. 112 2. Terminology 114 The following terms are defined in [draft-openconfig-netmod-opstate], 115 but are redefined here as follows: 117 o intended configuration - this data represents the configuration 118 state that the network operator intends the configuration 119 controlled by the NETCONF/RESTCONF server to be in. In the 120 NETCONF protocol, the intended configuration is specified in the 121 "running" datastore. In the RESTCONF protocol, the intended 122 configuration is specified in its conceptual datastore. 124 o applied configuration - this data represents the configuration 125 state that the NETCONF/RESTCONF server is actually in, i.e., that 126 which is currently being run by particular software modules (e.g., 127 the BGP daemon), or other systems within the server (e.g., a 128 secondary control-plane, or line card). The data model for 129 applied configuration is the same as the intended configuration's 130 data model. That is, the applied configuration data model is also 131 defined by the config true nodes in YANG modules supported by the 132 NETCONF/RESTCONF server. The data within the applied 133 configuration is the same as the data within the intended 134 configuration except as follows: 136 * When the intended configuration has not been communicated to an 137 external software entity 139 * When post-processing or flattening of the intended 140 configuration occurs to present a simpler view to the external 141 software entities 143 The transition from intended config to applied config commences in 144 NETCONF when or is called, for :writable- 145 running or :candidate respectively, and in RESTCONF immediately 146 whenever a POST, PUT, DELETE, or PATCH operation is called. 147 Neither NETCONF nor RESTCONF currently enable inspection of the 148 applied configuration. 150 o derived state - this data represents information which is 151 generated as part of the system's own interactions. For example, 152 derived state may consist of the results of protocol interactions 153 (the negotiated duplex state of an Ethernet link), statistics 154 (such as message queue depth), or counters (such as packet input 155 or output bytes). Derived stated is defined in YANG using config 156 false nodes, retrievable in NETCONF using the RPC, and 157 retrievable in RESTCONF using the content=nonconfiguration query 158 parameter. 160 The following terms are defined in this document: 162 o intended state - a synonym for "intended configuration". 164 o operational state - the combination of applied state and derived 165 state. 167 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 168 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 169 document are to be interpreted as described in RFC 2119 [RFC2119]. 171 3. Conceptual Model 173 The following diagram illustrates the conceptual model presented in 174 this document: 176 + 177 intended | operational 178 state | state 179 | 180 | 181 +----------+ | +---------+ 182 config true | intended | | | applied | 183 YANG nodes | config | | | config | 184 +----------+ | +---------+ 185 | 186 +-------------------------------------------------------+ 187 | 188 | +---------+ 189 config false | | derived | 190 YANG nodes | | state | 191 | +---------+ 192 | 193 + 195 Not illustrated in the diagram above: 197 o The intended and applied configurations share the same YANG- 198 defined data model, specified by the config true nodes in the YANG 199 modules supported by the server. 201 o The transition of the intended config to the applied commences 202 immediately, whenever the intended config is updated. 204 4. Enhancements to YANG 206 4.1. The related-state Statement 208 The "related-state" statement identifies a path to where additional 209 operational state associated for a config true node can be found. 210 This operational state being in addition to any descendant config 211 false nodes, which are implicitly associated to the parent config 212 true node. 214 The "related-state" statement takes as an argument a string that is 215 used to specify the path to a config false node holding the 216 associated operational state. The format of the argument is the same 217 as for the leafref's "path" statement, Section 9.9.2 in [RFC6020]. 219 4.1.1. YANG Module 221 module ietf-yang-related-state { 222 namespace urn:example:ietf-yang-related-state; 223 prefix yrs; 225 extension related-state { 226 argument path; 227 description 228 "The related-state statement is used to identify a node that 229 contains additional operational state associated for a config 230 true node. 232 The format of the argument is the same as for a leafref's "path" 233 statement. 235 The related-state statement can be specified in the following 236 YANG statements: 238 o leaf 239 o leaf-list 240 o container 241 o list 243 The related-state statement allows the following YANG substatements: 245 o description 247 Multiple related-state statements can be given in a specific node."; 248 } 250 } 252 4.1.2. Usage Example 254 The following example illustrates the related-state statement in use: 256 module ex-interfaces { 257 namespace "http://example.com/interfaces"; 258 prefix xif; 260 import ietf-yang-related-state { 261 prefix yrs; 262 } 264 container interfaces { 265 list interface { 266 key name; 267 yrs:related-state 268 "/interfaces-state/interface[name=current()/name]"; 270 leaf name { type string } 271 leaf mtu { type uint16; } 272 ... 273 } 274 } 275 container interfaces-state { 276 config false; 277 list interface { 278 key name; 279 leaf name { type string; } 280 ... 281 } 282 } 283 } 285 5. Enhancements to NETCONF 287 5.1. The Operation 289 One of the limitations identified in the Section 1 section was the 290 inability for the NETCONF protocol to retrieve operational state 291 without also retrieving running configuration. That is, the only 292 defined NETCONF operation capable of returning operational state is 293 the operation ([RFC6241], Section 7.7), but it also returns the 294 "running" configuration for the nodes selected by the passed filter. 295 While it is possible to construct data-models whereby configuration 296 and operational state are in completely isolated sub-trees, and 297 thereby eliminate the retrieval of configuration when selecting an 298 operational state node, requiring all models to be structured this 299 way is not ideal. 301 5.1.1. YANG Module 303 module ietf-netconf-get-state { 304 namespace urn:example:ietf-netconf-get-state; 305 prefix ncgs; 307 import ietf-netconf { 308 prefix nc; 309 } 311 rpc get-state { 312 description 313 "Retrieve device state information."; 315 reference "RFC 6241, Section 7.7"; 317 input { 318 anyxml filter { 319 description 320 "This parameter specifies the portion of the system 321 configuration and state data to retrieve."; 322 nc:get-filter-element-attributes; 323 } 324 } 326 output { 327 anyxml data { 328 description 329 "Copy of the running datastore subset and/or state 330 data that matched the filter criteria (if any). 331 An empty data container indicates that the request 332 did not produce any results."; 333 } 334 } 335 } 336 } 338 5.2. The Applied Configuration Capability 340 5.2.1. Description 342 The applied configuration capability indicates that the device 343 supports an applied configuration datastore, which is used to hold a 344 read-only copy of configuration data as it is known to the 345 operational components of the system (e.g., the data plane). 347 The applied configuration datastore contains applied configuration, 348 as defined in Section 2. 350 5.2.2. Dependencies 352 None. 354 5.2.3. Capability Identifier 356 The :applied capability is identified by the following capability 357 string: 359 :ietf:params:netconf:capability:applied:1.0 361 5.2.4. New Operations 363 None. 365 5.2.5. Modifications to Existing Operations 367 The :applied capability enables to be passed as the 368 argument to the and operations. 370 The :applied capability does not modify any other existing 371 operations. In particular, the value may not be used as 372 the argument to any operation. 374 Note, the :applied capability has no impact to the operation 375 because the operation is defined as returning the "running" 376 configuration, without any parameter to specify otherwise. 378 The parameter is formally defined in Section 5.2.6. 380 5.2.6. YANG Module 381 module ietf-netconf-applied-config { 382 namespace urn:example:ietf-netconf-applied-config; 383 prefix ncac; 385 import ietf-netconf { 386 prefix nc; 387 } 389 augment /nc:get-config/nc:input/nc:source/nc:config-source { 390 leaf applied { 391 type empty; 392 } 393 } 394 augment /nc:copy-config/nc:input/nc:source/nc:config-source { 395 leaf applied { 396 type empty; 397 } 398 } 399 } 401 5.2.7. Example 403 To retrieve the "/interfaces" subtree from the applied configuration 404 datastore: 406 408 409 410 411 412 413 414 415 416 418 6. Enhancements to RESTCONF 420 6.1. The Applied Configuration Capability 422 6.1.1. Description 424 The applied configuration capability indicates that the device 425 supports an applied configuration datastore, which is used to hold a 426 read-only copy of configuration data as it is known to the 427 operational components of the system (e.g., the data plane). 429 The applied configuration datastore contains applied configuration, 430 as defined in section Section 2. 432 6.1.2. The applied capability 434 A RESTCONF server supports the applied configuration datastore when 435 it presents the following URI in its "capability" leaf-list, as 436 defined in [RFC6241], Section 9.3. 438 urn:ietf:params:restconf:capability:applied:1.0 440 6.1.3. The "applied" Query Parameter 442 The "applied" parameter is only available when the RESTCONF server 443 supports the "urn:ietf:params:restconf:capability:applied:1.0" 444 capability. 446 The "applied" parameter is used to specify that the GET request 447 should be directed to the applied configuration datastore. 449 The "applied" parameter does not have a value assignment. 451 This parameter is only allowed for GET methods on API, datastore, and 452 data resources. A 400 Bad Request error is returned if it used for 453 other methods or resource types. 455 7. Security Considerations 457 TBD 459 8. IANA Considerations 461 TBD 463 9. Acknowledgements 465 TBD 467 10. References 469 10.1. Normative References 471 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 472 Requirement Levels", BCP 14, RFC 2119, March 1997. 474 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 475 Network Configuration Protocol (NETCONF)", RFC 6020, 476 October 2010. 478 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 479 Bierman, "Network Configuration Protocol (NETCONF)", RFC 480 6241, June 2011. 482 [draft-ietf-netconf-restconf] 483 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 484 Protocol", draft-ieft-netconf-restconf-04 (work in 485 progress), 2014, . 488 10.2. Informative References 490 [draft-openconfig-netmod-opstate] 491 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 492 of Operational State Data in YANG", 2015, 493 . 496 Authors' Addresses 498 Kent Watsen 499 Juniper Networks 501 EMail: kwatsen@juniper.net 503 Andy Bierman 504 Yumaworks 506 EMail: andy@yumaworks.com 508 Martin Bjorklund 509 Tail-f Systems 511 EMail: mbj@tail-f.com 513 Juergen Schoenwaelder 514 Jacobs University Bremen 516 EMail: j.schoenwaelder@jacobs-university.de