idnits 2.17.1 draft-wilton-netmod-opstate-yang-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 is 1 instance of too long lines in the document, the longest one being 9 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 date (September 3, 2015) is 3157 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Unused Reference: 'I-D.ietf-netconf-restconf' is defined on line 553, but no explicit reference was found in the text == Unused Reference: 'RFC6020' is defined on line 568, but no explicit reference was found in the text == Unused Reference: 'RFC6241' is defined on line 573, but no explicit reference was found in the text == Unused Reference: 'RFC6243' is defined on line 578, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-07 == Outdated reference: A later version (-02) exists of draft-kwatsen-netmod-opstate-00 Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force R. Wilton 3 Internet-Draft Cisco Systems 4 Intended status: Experimental September 3, 2015 5 Expires: March 6, 2016 7 "With-config-state" Capability for NETCONF/RESTCONF 8 draft-wilton-netmod-opstate-yang-00 10 Abstract 12 This document proposes a possible alternative solution for handling 13 applied configuration state in YANG as described in draft-openconfig- 14 netmod-opstate-01. The proposed solution, roughly modelled on the 15 with-defaults NETCONF/RESTCONF capability, aims to meet the key 16 requirements set out in draft-openconfig-netmod-opstate-01 without 17 the need for YANG module authors to explicitly duplicate 18 configuration nodes in both configuration and operational containers. 19 This draft does not address the issue of co-location of configuration 20 and operational state for interfaces, nor does it provide a NETCONF 21 mechanism to retrieve operational data separately from configuration 22 data. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on March 6, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. "With-config-state" encoding scheme . . . . . . . . . . . . . 4 62 3.1. cfg-intended . . . . . . . . . . . . . . . . . . . . . . 5 63 3.2. cfg-applied . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.3. cfg-status . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.4. cfg-status-reason . . . . . . . . . . . . . . . . . . . . 6 66 3.5. Non-leaf config nodes . . . . . . . . . . . . . . . . . . 7 67 4. Retrieval of intended and applied configuration . . . . . . . 7 68 4.1. all-cfg . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 4.2. intended-cfg-only . . . . . . . . . . . . . . . . . . . . 8 70 4.3. applied-cfg-only . . . . . . . . . . . . . . . . . . . . 8 71 4.4. diff-cfg-only . . . . . . . . . . . . . . . . . . . . . . 8 72 5. "With-config-state" Capability . . . . . . . . . . . . . . . 8 73 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8 74 5.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . 9 75 5.3. Capability Identifier . . . . . . . . . . . . . . . . . . 9 76 6. Suggested layout of data models . . . . . . . . . . . . . . . 9 77 7. Addressing the requirements of the Consistent Modeling of 78 Operational State Data draft . . . . . . . . . . . . . . . . 9 79 7.1. Addressing requirement 3: 'To interact with both intended 80 and applied configuration' . . . . . . . . . . . . . . . 9 81 7.2. Addressing requirement 4.1: Applied config as part of 82 operational state . . . . . . . . . . . . . . . . . . . . 10 83 7.3. Addressing requirement 4.2: Support for both 84 transactional, synchronous management systems as well as 85 distributed, asynchronous management systems . . . . . . 10 86 7.4. Addressing requirement 4.3: Separation of configuration 87 and operational state data; ability to retrieve them 88 independently . . . . . . . . . . . . . . . . . . . . . . 11 89 7.5. Addressing requirement 4.4: Ability to retreive 90 operational state corresponding only to derived values, 91 statistics, etc . . . . . . . . . . . . . . . . . . . . . 11 92 7.6. Addressing requirement 4.5: Consistent schema locations 93 for configuration and corresponding operational state 94 data . . . . . . . . . . . . . . . . . . . . . . . . . . 11 95 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 96 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 97 10. Security Considerations . . . . . . . . . . . . . . . . . . . 12 98 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 99 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 100 11.2. Informative References . . . . . . . . . . . . . . . . . 13 101 Appendix A. Encoding examples for NETCONF and RESTCONF . . . . . 13 102 A.1. NETCONF get-config request using with-config-state with 103 all-cfg option . . . . . . . . . . . . . . . . . . . . . 14 104 A.2. NETCONF get-config request using with-config-state with 105 diff-cfg-only option . . . . . . . . . . . . . . . . . . 16 106 A.3. NETCONF get-config request using with-config-state with 107 applied-cfg-only option . . . . . . . . . . . . . . . . . 18 108 A.4. RESTCONF GET request using with-config-state with all-cfg 109 option (JSON) . . . . . . . . . . . . . . . . . . . . . . 20 110 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 112 1. Introduction 114 The Consistent Modeling of Operational State Data Internet Draft 115 [I-D.openconfig-netmod-opstate] sets out a number of operational 116 requirements and proposed solutions for handling intended and applied 117 config state when using YANG models. This document sets out a 118 possible alternative solution for some of those requirements. 120 The solution proposed in this document does not require any changes 121 to any existing YANG modules to support intended and applied config 122 state. In particular: the proposed solution does not require the 123 data models to be explicitly modelled with separate configuration and 124 operational containers, and it does not require that all 125 configuration and operational state nodes and leaves to be defined as 126 groupings. 128 Nor does the proposed solution make explicit use of separate 129 datastores to model intended configuration separately from applied 130 configuration. 132 Instead, the solution proposed here is a method for generating an 133 enhanced schema based on any YANG model that is optionally used by 134 network management protocols. This enhanced schema includes up to 135 four data leaves for each configuration node defined in the YANG 136 model. These cover both the intended and applied values, along with 137 an additional reason code and message if the applied configuration 138 does not match the intended configuration. 140 Although the solution described here is only defined in the context 141 of NETCONF and RESTCONF, it should be possible to extend the same 142 YANG config data encoding mechanism to other protocol schemes used to 143 access YANG data if required. 145 1.1. Terminology 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 149 document are to be interpreted as described in RFC 2119 [RFC2119]. 151 The following terms are defined in Consistent Modeling of Operational 152 State Data Internet Draft [I-D.openconfig-netmod-opstate], and 153 reproduced here for convenience. 155 intended configuration - this data represents the state that the 156 network operator intends the system to be in. This data is 157 colloquially referred to as the 'configuration' of the system. 159 applied configuration - this data represets the state that the 160 network element is actually in, i.e. that which is currently being 161 run by particular software modules (e.g. the BGP daemon), or other 162 systems within the device (e.g. a secondary control-plane, or line 163 card). 165 derived state - this data represents information which is 166 generated as part of the system's own interactions. For example, 167 derived state may consist of the results of protocol interactions 168 (such as the negotiated duplex state of an Ethernet link), 169 statistics (such as message queue depth), or counters (such as 170 packet input or output bytes). 172 The following additional terms are used in this document: 174 operational nodes - this term is colloquially used in this draft 175 to refer to "config false" YANG nodes. 177 2. Objectives 179 The aim of this draft is to provide a partial alternative solution to 180 the requirements set out in Consistent Modeling of Operational State 181 Data Internet Draft [I-D.openconfig-netmod-opstate]. An explanation 182 of how the specific requirements are addressed is described in 183 Section 7. 185 3. "With-config-state" encoding scheme 187 The solution proposed in this document makes use of a new encoding 188 scheme that is used to represent YANG configuration nodes in NETCONF 189 and RESTCONF. An optional parameter, called and 190 defined below, indicates when this new encoding scheme is used. 192 When the with-config-state option is used each YANG configuration 193 leaf in the datastore is returned in a different format. Rather than 194 being encoded as an XML or JSON leaf element that holds the 195 configured value, it is instead returned as a node element, with the 196 same name as the YANG config leaf, that contains up to four separate 197 leaf elements. The four leaf elements that the node may contain are 198 'cfg-intended', 'cfg-applied', 'cfg-status', and 'cfg-status-reason'. 199 Theses leaves are externally addressable through using the full path 200 of the leaf, providing explicit distinct paths for intended 201 configuration vs applied configuration. These elements are described 202 in more detail in the following sub-sections. Concrete examples of 203 the encoding for NETCONF and RESTCONF requests are given in 204 Appendix A. 206 3.1. cfg-intended 208 The cfg-intended leaf represents the intended configuration of the 209 device, and is of the same datatype and holds the same value as the 210 normal YANG data model configuration leaf. The cfg-intended leaf is 211 only present if the associated configuration node exists in the YANG 212 data model. 214 The cfg-intended leaf is semantically equivalent to the config leaf 215 in the YANG data model that is based on, and hence is logically read/ 216 writable. In particular, when the parameter is 217 used, management requests to modify the configuration may also use 218 the full path to the cfg-intended leaf. The server semantics for 219 writing to the cfg-intended leaf are exactly the same as for writing 220 to the standard YANG config node path - the flexibility is provided 221 as a convenience to the NMS client. 223 3.2. cfg-applied 225 The cfg-applied leaf represents the applied configuration, and is of 226 the same datatype as a normal YANG data model configuration leaf. If 227 there is no configuration currently in effect then the cfg-applied 228 leaf is not present. 230 The cfg-applied leaf is read only. 232 To give some examples: 234 If the configuration has been successfully applied then the cfg- 235 applied leaf would exactly match the cfg-intended leaf. 237 If a new item of configuration is in the process of being applied 238 then the cfg-intended leaf holds the intended configuration value, 239 and the cfg-applied leaf would not be present until the 240 configuration is in effect. 242 If an existing item of configuration is in the process of being 243 deleted then the cfg-applied leaf would hold the current 244 configuration value, and the cfg-intended leaf would not be 245 present. Once the delete operation has completed, the 246 configuration node element itself would logically be deleted. 248 If the configuration value of an existing item of configuration is 249 in the process of being changed, then the cfg-intended leaf would 250 hold the new proposed value, and the cfg-applied leaf would hold 251 the existing value that is currently in effect. 253 3.3. cfg-status 255 The cfg-status leaf is used, when required, to indicate why the value 256 of the cfg-applied leaf does not match the value of the cfg-intended 257 leaf. It is only present when the values of the cfg-intended and 258 cfg-applied leaves do not match. 260 The cfg-status leaf is read only. 262 The cfg-status leaf can take one of following values: 264 in-progress - the config operation is in the process of being 265 applied. 267 waiting - the config operation is waiting for other configuration 268 to be applied or hardware to be available before it can be 269 applied. Additional specific information may be provided in the 270 cfg-status-reason leaf. 272 failed - the config operation failed to be applied. Additional 273 information may be provided in the cfg-status-reason leaf to 274 indicate the reason for the failure. 276 3.4. cfg-status-reason 278 The cfg-status-reason leaf may be used to provide additional 279 information as to why the value of the cfg-applied leaf does not 280 match the value of the cfg-intended leaf. 282 The cfg-status-reason leaf may only be present in the case that the 283 cfg-status leaf is present and is set to either waiting or failed. 285 The cfg-status-reason leaf is read only. 287 3.5. Non-leaf config nodes 289 Non-leaf config nodes require some special handling. In particular, 290 containers with presence and list elements must be considered. 292 The proposed solution for both types of node is the same. The cfg- 293 intended, cfg-applied, cfg-status, and cfg-status-reason leaf nodes 294 are implicitly added as direct descendants of the presence-container 295 or list element. 297 Note: There is an open issue that using these leaves directly opens 298 up a potential naming clash between the "cfg-*" names above and 299 existing explicitly defined child nodes in the YANG module 300 definition. There are a few possible ways that this might be 301 addressed: 303 Making the four "cfg-*" leaves reserved names. I.e. to ensure 304 that they are not used in general YANG modules. 306 By inserting an implicit node between all child nodes under the 307 container or list element. This would automatically ensure that 308 there can be no naming clash between the defined YANG nodes and 309 the implicitly added "cfg-*" leaves. 311 By using a reserved namespace for the "cfg-*" leaves to ensure 312 that they cannot clash with any explicitly defined in the YANG 313 module. 315 4. Retrieval of intended and applied configuration 317 To make use of the new encoding scheme defined above, this document 318 defines a new parameter, called , which can be 319 added to specific NETCONF operation request messages, or as a 320 RESTCONF query parameter, to control how retrieval of configuration 321 nodes is treated by the server. 323 The parameter is supported for the following 324 NETCONF operations: , , , . 327 The query parameter is supported for the 328 following RESTCONF operations: GET, PUT, POST, PATCH, DELETE. 330 Use of the parameter ensures that all config 331 nodes are always returned using the defined encoding. It also allows 332 servers to explicitly reference the cfg-* leaves in requests and 333 updates. 335 A server that implements this specification MUST accept the parameter containing the enumeration for any of the 337 with-config-state modes it supports. The 338 parameter contains one of the four enumerated values defined in this 339 section. 341 4.1. all-cfg 343 When data is retrieved with a parameter equal to 344 'all-cfg', all 'cfg-*' nodes are reported using the encoding scheme 345 defined in Section 3. 347 4.2. intended-cfg-only 349 When data is retrieved with a parameter equal to 350 'intended-cfg', only the 'cfg-intended' leaves are reported using the 351 encoding scheme defined in Section 3. All other 'cfg-*' leaves are 352 omitted. 354 4.3. applied-cfg-only 356 When data is retrieved with a parameter equal to 357 'applied-cfg-only', only the 'cfg-applied' leaves are reported using 358 the encoding scheme defined in Section 3. All other 'cfg-*' leaves 359 are omitted. 361 4.4. diff-cfg-only 363 When data is retrieved with a parameter equal to 364 'diff-cfg-only', config nodes are only returned if the value of the 365 cfg-intended leaf does not match the value of the cfg-applied leaf. 366 If the config node is returned then all appropriate 'cfg-*' leaves 367 are returned as per the encoding scheme defined in Section 3. 369 5. "With-config-state" Capability 371 5.1. Overview 373 The :with-config-state capability indicates whether a server supports 374 the with-config-state functionality. For a server that indicates 375 support for the :with-config-state capability it must support at 376 least the 'all-cfg' option. It may also indicate support for the 377 additional with-config-state retrieval modes. 379 5.2. Dependencies 381 None 383 5.3. Capability Identifier 385 urn:ietf:params:netconf:capability:with-config-state:1.0 387 The identifer has a paramater: "also-supported". This parameter 388 indicates which additional enumeration values (besides 'all-cfg') the 389 server will accept for the parameter in 390 Section 4. The value of the parameter is a comma-separated list of 391 one or more modes that are supported. Possible modes are 'intended- 392 cfg-only', 'applied-cfg-only', 'diff-cfg-only' as defined in 393 Section 4. 395 6. Suggested layout of data models 397 Generally, to ensure that operational data and configuration data can 398 be easily related, this draft recommends that configuration and 399 associated operational nodes be co-located in the same YANG 400 container. More precisely, YANG clients should be able to assume 401 that configuration and operational nodes within the same container 402 are implicitly related. 404 7. Addressing the requirements of the Consistent Modeling of 405 Operational State Data draft 407 7.1. Addressing requirement 3: 'To interact with both intended and 408 applied configuration' 410 The proposed solution in this draft provides a way for a NMS to 411 explicitly access both the intended and applied configuration state 412 of configuration nodes. It also provides a convenient way that both 413 the intended and applied configuration values can be returned and 414 easily compared. It also has the following additional benefits: 416 It optionally provides additional information as to why the 417 applied configuration does not match the intended configuration. 419 It does not force the YANG modules to use groupings for 420 configuration data so that it can be mirrored in the operational 421 state. In particular, it places no burden to support an eventual 422 consistency configuration model on YANG modules that do not need 423 to operate in that environment. 425 The parameter in the extension allows the 426 client to request that only configuration nodes that are not in 427 the intended state are returned. 429 This draft also addresses the issue of allowing a NMS to easily 430 relate configuration and operational state. As should be clear the 431 relationship between cfg-intended and cfg-applied states for a 432 particular node are trivially and efficiently mappable for all YANG 433 configuration nodes. With the exception of interface operational 434 state, that is not addressed by this draft, the relationship between 435 configuration and derived state is acheived through the convention 436 that co-located configuration and operational state be held in the 437 same YANG container. This is semantically similar to the approach in 438 Consistent Modeling of Operational State Data Internet Draft 439 [I-D.openconfig-netmod-opstate] that implicitly binds the contents of 440 the 'config' and 'state' YANG container nodes together if they are 441 rooted to the same parent YANG container. 443 7.2. Addressing requirement 4.1: Applied config as part of operational 444 state 446 This requirement is met through the use of the separate cfg-intended 447 and cfg-applied implict leaf nodes that are available when using the 448 extension parameter set to 'intended-cfg-only' or 449 'applied-cfg-only' with either the NETCONF operation or 450 the RESTCONF GET request with the 'content' query parameter set to 451 'config'. 453 7.3. Addressing requirement 4.2: Support for both transactional, 454 synchronous management systems as well as distributed, 455 asynchronous management systems 457 Devices that only support a transactional sychronous management 458 system have the choice of either not supporting the extension, or alternatively may achieve compliance with this 460 extension fairly easily by returning the same value for both cfg- 461 intended and cfg-applied leaf nodes, and always omitting the cfg- 462 status and cfg-status-reason leaves. Any requests using the path to 463 the cfg-intended and cfg-applied leaves can be mapped back to the 464 base config leaf defined in the YANG data model. Any explicit 465 requests get or get-config requests for cfg-status and cfg-status- 466 reason can be rejected. 468 Devices that support an asynchronous configuration system would 469 implement support for the extension and provide the cfg-* leaves 470 defined in this draft when requested. 472 7.4. Addressing requirement 4.3: Separation of configuration and 473 operational state data; ability to retrieve them independently 475 The first point is addressed by the proposed solution. Config and 476 operational data are already split, and the naming of the cfg- 477 intended vs cfg-applied leaves provides a clear distinction between 478 intended configuration, applied configuration, and derived state. 480 The second point is not fully addressed by this draft. The proposed 481 protocol extension allows for just the intended config vs applied 482 config nodes to be returned. RESTCONF already supports querying 483 config separately from operational state through use of the 'content' 484 query paremeter. A separate NETCONF protocol extension would be 485 required to return just the operational nodes without any of the 486 configuration nodes, such as the enhancement described in 487 Operational State Enhancements for YANG, NETCONF, and RESTCONF 488 [I-D.kwatsen-netmod-opstate]. 490 7.5. Addressing requirement 4.4: Ability to retreive operational state 491 corresponding only to derived values, statistics, etc 493 Not directly addressed by this draft. RESTCONF already supports 494 querying config separately from operational state through use of the 495 'content' query paremeter. A separate NETCONF protocol extension 496 would be required to return just the operational nodes without any of 497 the configuration nodes, such as the enhancement 498 described in Operational State Enhancements for YANG, NETCONF, and 499 RESTCONF [I-D.kwatsen-netmod-opstate]. 501 7.6. Addressing requirement 4.5: Consistent schema locations for 502 configuration and corresponding operational state data 504 Section 4.5 of Consistent Modeling of Operational State Data Internet 505 Draft [I-D.openconfig-netmod-opstate] indicates that it is desirable 506 to have a well defined path to retrieve the cfg-intended vs cfg- 507 applied values to avoid requiring external context when referencing 508 that information. This is achieved by allowing paths in the NETCONF 509 and RESTCONF protocols to include one of the cfg-state leaves when 510 using the extension. E.g. if the path to a 511 particular config leaf was normally /..path-to-leaf../cfg-leaf then 512 the intended config value could be referenced and obtained by using 513 /..path-to-leaf../cfg-leaf/cfg-intended. The cfg-applied, cfg- 514 status, and cfg-status-reason leaves can all be referenced and 515 accessed in a similar fashion. 517 Containers with presence are not leaf nodes, and hence require 518 slightly differently handling to configuration leaf nodes. The 519 proposed solution is that containers with presence contain the cfg- 520 intended, cfg-applied, cfg-status, and cfg-status-reason leaf nodes 521 as direct descendants of the container node and hence can be accessed 522 using the same scheme as for config leaves. E.g. if the path to a 523 particular container with presence was normally /..path-to-p- 524 container../cfg-p-container/ then the intended config value could be 525 referenced and obtained by using /..path-to-p-container../cfg-p- 526 container/cfg-intended. The cfg-applied, cfg-status, and cfg-status- 527 reason leaves can all be referenced and accessed in a similar 528 fashion. 530 8. Acknowledgements 532 The authors wish to thank Einar Nilsen-Nygaard, Neil Ketley, Peyman 533 Owladi for their helpful comments, ideas and expertise contributing 534 to this draft. 536 9. IANA Considerations 538 TBD. This document would at least need to register a new capability 539 identifier URN in the 'Network Configuration Protocol (NETCONF) 540 Capability URNs' registry for the with-config-state optional 541 capability.'". 543 10. Security Considerations 545 The proposal in this document does not have any security 546 considerations beyond the existing NETCONF/RESTCONF/YANG security 547 considerations. 549 11. References 551 11.1. Normative References 553 [I-D.ietf-netconf-restconf] 554 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 555 Protocol", draft-ietf-netconf-restconf-07 (work in 556 progress), July 2015. 558 [I-D.openconfig-netmod-opstate] 559 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 560 of Operational State Data in YANG", draft-openconfig- 561 netmod-opstate-01 (work in progress), July 2015. 563 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 564 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 565 RFC2119, March 1997, 566 . 568 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 569 the Network Configuration Protocol (NETCONF)", RFC 6020, 570 DOI 10.17487/RFC6020, October 2010, 571 . 573 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 574 and A. Bierman, Ed., "Network Configuration Protocol 575 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 576 . 578 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 579 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 580 . 582 11.2. Informative References 584 [I-D.kwatsen-netmod-opstate] 585 Watsen, K., Bierman, A., Bjorklund, M., and J. 586 Schoenwaelder, "Operational State Enhancements for YANG, 587 NETCONF, and RESTCONF", draft-kwatsen-netmod-opstate-00 588 (work in progress), September 2015. 590 Appendix A. Encoding examples for NETCONF and RESTCONF 592 A sample encoding of the enhancement is described 593 below. 595 A simple example module is provided to illustrate the subsequent 596 examples. This is not a real module, and is not intended for any 597 real use. 599 module example { 601 namespace "http://example.com/ns/interfaces"; 603 prefix exam; 605 container interfaces { 606 description "Example interfaces group"; 608 list interface { 609 description "Example interface entry"; 610 key name; 612 leaf name { 613 description 614 "The administrative name of the interface."; 615 type string { 616 length "1 .. max"; 617 } 618 } 620 leaf mtu { 621 description 622 "The maximum transmission unit (MTU) value assigned to 623 this interface."; 624 type uint32; 625 default 1514; 626 } 627 } 628 } 630 A.1. NETCONF get-config request using with-config-state with all-cfg 631 option 633 A get-config request is made for the interfaces subtree using the 634 enhancement and 'all-cfg' option that returns all 635 config nodes with explicit cfg-intended and cfg-applied leaves, and 636 cfg-status and cfg-status-reason leaves when appropriate. 638 In this example, at the time of processing the get-config request, 639 the NETCONF server is also asynchronously processing a request to set 640 the MTU leaf to 9000 for 4 interface config nodes. 642 644 645 646 647 648 650 all-cfg 651 652 653 655 The response indicates that at the time of the reply: 657 The request to set the MTU leaf on eth0/0 to 9000 has completed. 659 The request to change the MTU leaf on eth0/1 from 2000 to 9000 is 660 in progress. 662 The request to set the MTU leaf on eth0/2 to 9000 is in progress. 664 The request to set the MTU leaf on eth1/0 to 9000 is blocked 665 because the necessary hardware is not present. 667 669 670 671 672 673 674 675 eth0/0 676 eth0/0 677 678 679 9000 680 9000 681 682 683 684 685 686 687 eth0/1 688 eth0/1 689 690 691 9000 692 2000 693 in-progress 694 695 696 697 698 699 700 eth0/2 701 eth0/2 702 703 704 9000 705 in-progress 706 707 708 709 710 waiting 711 Linecard 1 is not available 712 713 714 eth1/0 715 waiting 716 Linecard 1 is not available 717 718 719 720 9000 721 waiting 722 Linecard 1 is not available 723 724 725 726 727 728 730 A.2. NETCONF get-config request using with-config-state with diff-cfg- 731 only option 733 A get-config request is made for the interfaces subtree using the 734 enhancement and 'diff-cfg-only' option that only 735 returns nodes where the cfg-intended node does not match the cfg- 736 applied node. Appropriate parent nodes are also returned. 738 As per the previous examples, at the time of processing the get- 739 config request, the NETCONF server is also asynchronously processing 740 a request to set the MTU leaf to 9000 for 4 interface config nodes. 742 744 745 746 747 748 750 diff-cfg-only 751 752 753 755 The response indicates that the outstanding configuration requests 756 still to be processed are: 758 The request to change the MTU leaf on eth0/1 from 2000 to 9000 is 759 in progress. 761 The request to set the MTU leaf on eth0/2 to 9000 is in progress. 763 The request to set the MTU leaf on eth1/0 to 9000 is blocked 764 because the necessary hardware is not present. 766 768 769 770 771 772 773 774 eth0/1 775 eth0/1 776 777 778 9000 779 2000 780 in-progress 781 782 783 784 785 786 787 eth0/2 788 eth0/2 789 790 791 9000 792 in-progress 793 794 795 796 797 waiting 798 Linecard 1 is not available 799 800 801 eth1/0 802 waiting 803 Linecard 1 is not available 804 805 806 807 9000 808 waiting 809 Linecard 1 is not available 810 811 812 813 814 815 817 A.3. NETCONF get-config request using with-config-state with applied- 818 cfg-only option 820 A get-config request is made for the interfaces subtree using the 821 enhancement and 'applied-cfg-only' option that 822 only returns the currently applied configuration. 824 As per the previous examples, At the time of processing the get- 825 config request, the NETCONF server is also asynchronously processing 826 a request to set the MTU leaf to 9000 for 4 interface config nodes. 828 830 831 832 833 834 836 applied-cfg-only 837 838 839 841 The response indicates that the current applied configuration of the 842 selected nodes is: 844 The MTU leaf of eth0/0 is 9000. 846 The MTU leaf of eth0/1 is 2000. 848 Eth0/2 has no MTU leaf applied. 850 [Implicitly - there is no applied configuration for Eth1/0 since 851 the hardware is not present.] 853 855 856 857 858 859 860 eth0/0 861 862 863 9000 864 865 866 867 868 869 eth0/1 870 871 872 2000 873 874 875 876 877 878 eth0/2 879 880 881 882 883 885 A.4. RESTCONF GET request using with-config-state with all-cfg option 886 (JSON) 888 An equivalent RESTCONF/JSON example to Appendix A.1 is provided to 889 illustrate the equivalent JSON encoding. 891 A REST GET request is made for all config data using the enhancement and 'all-cfg' option that all returns all 893 config nodes with explicit cfg-intended and cfg-applied leaves. 895 In this example, at the time of processing the GET request, the 896 RESTCONF server is also asynchronously processing a request to set 897 the MTU leaf to 9000 for 4 interface config nodes. 899 GET /restconf/data/example-events:events?content=config&with-config-state=all-cfg 900 HTTP/1.1 901 Host: example.com 902 Accept: application/yang.data+json 904 As per Appendix A.1, the response indicates that at the time of the 905 reply: 907 The request to set the MTU leaf on eth0/0 to 9000 has completed. 909 The request to change the MTU leaf on eth0/1 from 2000 to 9000 is 910 in progress. 912 The request to set the MTU leaf on eth0/2 to 9000 is in progress. 914 The request to set the MTU leaf on eth1/0 to 9000 is blocked 915 because the necessary hardware is not present. 917 HTTP/1.1 200 OK 918 Date: Mon, 1 Apr 2015 04:01:00 GMT 919 Server: example-server 920 Content-Type: application/yang.data+json 922 { 923 "example:interfaces": [ 924 { 925 "cfg-intended" = null, 926 "cfg-actual" = null, 927 "name" : { 928 "cfg-intended" = "eth0/0", 929 "cfg-actual" = "eth0/0" 930 }, 931 "mtu" : { 932 "cfg-intended" = 9000, 933 "cfg-actual" = 9000 934 }, 935 }, 936 { 937 "cfg-intended" = null, 938 "cfg-actual" = null, 939 "name" : { 940 "cfg-intended" = "eth0/1", 941 "cfg-actual" = "eth0/1" 942 }, 943 "mtu" : { 944 "cfg-intended" = 9000, 945 "cfg-actual" = 2000, 946 "cfg-status" = "in-progress" 948 }, 949 }, 950 { 951 "cfg-intended" = null, 952 "cfg-actual" = null, 953 "name" : { 954 "cfg-intended" = "eth0/2", 955 "cfg-actual" = "eth0/2" 956 }, 957 "mtu" : { 958 "cfg-intended" = 9000, 959 "cfg-status" = "in-progress" 960 }, 961 }, 962 { 963 "cfg-intended" = null, 964 "cfg-status" = "waiting", 965 "cfg-status-reason" = "Linecard 1 is not available", 966 "name" : { 967 "cfg-intended" = "eth1/0", 968 "cfg-status" = "waiting", 969 "cfg-status-reason" = "Linecard 1 is not available", 970 }, 971 "mtu" : { 972 "cfg-intended" = 9000, 973 "cfg-status" = "waiting", 974 "cfg-status-reason" = "Linecard 1 is not available", 975 }, 976 }, 977 ] 978 } 980 Author's Address 982 Robert Wilton 983 Cisco Systems 985 Email: rwilton@cisco.com