idnits 2.17.00 (12 Aug 2021) /tmp/idnits22700/draft-wilton-netconf-opstate-metadata-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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 276: '...fault option and MUST be supported by ...' RFC 2119 keyword, line 296: '... This option MAY be supported by ser...' RFC 2119 keyword, line 309: '...applied in a concise way and SHOULD be...' RFC 2119 keyword, line 485: '...ents this module MUST also advertise a...' RFC 2119 keyword, line 490: '... The identifier MUST have a parameter...' (4 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2016) is 2138 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) == Unused Reference: 'RFC7223' is defined on line 619, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-i2rs-ephemeral-state' is defined on line 625, but no explicit reference was found in the text == Unused Reference: 'I-D.schoenw-netmod-revised-datastores' is defined on line 635, but no explicit reference was found in the text == Unused Reference: 'RFC6242' is defined on line 645, but no explicit reference was found in the text == Unused Reference: 'RFC6244' is defined on line 653, but no explicit reference was found in the text ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-opstate-reqs (ref. 'I-D.ietf-netmod-opstate-reqs') ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) == Outdated reference: draft-ietf-i2rs-ephemeral-state has been published as RFC 8242 == Outdated reference: draft-ietf-netmod-yang-metadata has been published as RFC 7952 == Outdated reference: A later version (-01) exists of draft-wilton-netmod-refined-datastores-00 Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force R. Wilton, Ed. 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track July 6, 2016 5 Expires: January 7, 2017 7 Refined YANG datastores with Meta-data 8 draft-wilton-netconf-opstate-metadata-00 10 Abstract 12 draft-wilton-netmod-refined-datastores defines refined YANG datastore 13 definitions to provide an explicit Operational State Datastore and a 14 clean separation between the 'intended configuration' for a device 15 and the 'applied configuration' that is in effect on a device. This 16 draft builds on draft-wilton-netmod-refined-datastores by describing 17 a YANG Metadata based extension that can be used by protocols such as 18 NETCONF and RESTCONF to allow the key information from the various 19 operational state related datatstores to be made available without 20 requiring the client to explicitly read and monitor each abstract 21 datastore separately. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on January 7, 2017. 40 Copyright Notice 42 Copyright (c) 2016 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.2. Objectives . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.3. Overview of a refined model of datastores . . . . . . . . 5 61 2. Applied Configuration Metadata Option to NETCONF and RESTCONF 6 62 2.1. 'with-applied-config-metadata' modes query parameter . . 7 63 2.1.1. selectively-annotate . . . . . . . . . . . . . . . . 7 64 2.1.2. annotate-all . . . . . . . . . . . . . . . . . . . . 7 65 2.1.3. annotated-diff . . . . . . . . . . . . . . . . . . . 8 66 2.2. Datastore specific handling . . . . . . . . . . . . . . . 8 67 2.3. Applied Configuration Metadata YANG Definition . . . . . 8 68 2.4. :with-applied-cfg-metadata Capability . . . . . . . . . . 11 69 2.4.1. Capability Identifier . . . . . . . . . . . . . . . . 11 70 2.4.1.1. datastore parameter . . . . . . . . . . . . . . . 12 71 2.4.1.2. supported-modes parameter . . . . . . . . . . . . 12 72 2.4.1.3. Examples . . . . . . . . . . . . . . . . . . . . 12 73 2.5. NETCONF specifics . . . . . . . . . . . . . . . . . . . . 12 74 2.6. RESTCONF specifics . . . . . . . . . . . . . . . . . . . 13 75 3. Discussion Points . . . . . . . . . . . . . . . . . . . . . . 13 76 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 77 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 79 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 81 7.2. Informative References . . . . . . . . . . . . . . . . . 14 82 Appendix A. Usage examples . . . . . . . . . . . . . . . . . . . 15 83 A.1. NETCONF Persistent datastore get-config request using 84 with-applied-cfg-metadata . . . . . . . . . . . . . . . . 16 85 A.2. NETCONF Operational State Datastore get request using 86 with-applied-cfg-metadata . . . . . . . . . . . . . . . . 18 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 89 1. Introduction 91 This document describes an optional extension to NETCONF/RESTCONF, 92 based on With-defaults Capability for NETCONF [RFC6243], and Metadata 93 with YANG [I-D.ietf-netmod-yang-metadata], that allow servers to 94 communicate the content of the Applied Configuration Abstract 95 Datastore and Operational State Datastore defined in 97 [I-D.wilton-netmod-refined-datastores] to clients in an efficient 98 way. 100 Operator requirements state that there needs to be a clear separation 101 between the configuration that has been sent to the device and the 102 actual configuration that the device is actually acting on. 104 For some simple 'opstate unware' devices, if it is sufficient to 105 assume that the configuration is applied instantaneously and also 106 that none of the configuration can fail, then the intended and 107 applied configuration can be regarded as being exactly the same, and 108 a formal split between intended and applied configuration is 109 unnecessary. 111 For other more complex 'opstate aware' devices, the assumptions above 112 do not always hold: Devices may take several minutes (or even tens of 113 minutes) to apply the configuration, some of the configuration may 114 fail, or it may not be possible to apply some of the configuration 115 due to either insufficient resources or due to a requisite piece of 116 hardware not being present in the device. 118 This extension is primarily aimed at this latter class of opstate 119 aware devices, but to improve interoperability it is anticipated that 120 it could also fairly easily be implemented on opstate unaware devices 121 as well. 123 The extension uses YANG Metadata to allow a client to quickly 124 determine whether the configuration has or has not been successfully 125 applied. Semantically, this is similar to performing a "diff" 126 between two related configuration datastores, but with the content of 127 the diff returned relative to one of those datastores. 129 1.1. Definitions 131 Definitions of the following terms are taken from 132 [I-D.wilton-netmod-refined-datastores]: 134 opstate aware device - a device that implements the requirements 135 specified in [I-D.ietf-netmod-opstate-reqs], in particular the 136 device must expose the split between the device's 'intended 137 configuration' vs 'applied configuration'. 139 opstate unaware device - a device that is not an 'opstate aware 140 device'. In particular, it does not draw a clear distinction 141 between 'intended configuration' vs 'applied configuration', and 142 generally treats them as having exactly the same contents. 144 abstract datastore - a new variant of YANG datastore that 145 represents a particular common property of the contents (e.g. 146 'applied configuration'). Servers could allow it to be external 147 referenced as a named datastore, but generally that is not 148 expected or required. 150 The following datastore definitions are taken from NETCONF [RFC6241]: 152 o candidate ds - represents candidate configuration 154 o startup ds - represents startup configuration 156 The following datastore definitions are taken from 157 [I-D.wilton-netmod-refined-datastores]: 159 o Persistent Configuration - holds the client provided configuration 160 that is written to the Startup Datastore and is recovered after 161 device reboot. 163 o Ephemeral Configuration - an optional datastore that holds client 164 provided transient configuration that is discarded after device 165 reboot. 167 o Operational State - a read-only datastore that holds all of the 168 operational state of the device. Specifically it holds: the exact 169 configuration that has been applied, along with any system 170 controlled configuration, and all system state (including 171 statistics and any ephemeral state). 173 o Intended Configuration - abstractly represents the combined 174 desired configuration of the device 176 o Applied Configuration - abstractly represents the actual applied 177 configuration of the device 179 o Running Configuration - abstractly represents the combined 180 intended and applied datastores, logically equivalent to the 181 definition given in [RFC6241] 183 1.2. Objectives 185 The objectives of this draft are: 187 to minimize the number of explicit datastores that NETCONF/ 188 RESTCONF servers must implement and clients must manage, whilst 189 providing a clean separation between intended configuration, 190 applied configuration, and operational state. 192 to provide an efficient mechanism to query and monitor whether all 193 of the intended configuration has been applied, and view any 194 configuration that has not been applied. 196 to provide an efficient mechanism to query and monitor the 197 operational state of the device. 199 1.3. Overview of a refined model of datastores 201 The following diagram, taken from 202 [I-D.wilton-netmod-refined-datastores], illustrates how all of the 203 abstract and concrete datastores (except running) relate to each 204 other: 206 +-------------+ +-----------+ 207 | | | | 208 | (ct, rw) |<---+ +--->| (ct, rw) | 209 +-------------+ | | +-----------+ 210 | | | | 211 | .....|........|........ | 212 | . +-----------------+ . | 213 +------->| |<---+ 214 . | (ct, rw) | . 215 Intended . +-----------------+ . 216 Config ==> . v . 217 Datastore . +-----------------+ . 218 (abstract) . | |<--- Can override persistent 219 . | (ct, rw) | . cfg. Optional 220 . +-----------------+ . 221 ..........|............ 222 | 223 +---------v-----------+ 224 | ................... | 225 | . .<--- Actual cfg in effect 226 Operational | . (ct, ro) . | 227 State ==> | ................... | 228 Datastore | + | 229 | system cfg <--- System created config 230 | + | 231 | system state <--- All config false nodes 232 +---------------------+ 234 Key 235 Solid boxes (-----) indicate normal datastores: 236 (i.e Startup, Persistent Cfg, Ephemeral Cfg, Operational State) 238 Dotted boxes (.....) indicate abstract datastores: 239 (i.e. Intended Config and Applied Config) 241 ct = config true, rw = read/write, ro = read/only 243 2. Applied Configuration Metadata Option to NETCONF and RESTCONF 245 The applied configuration metadata option is an optional extension to 246 NETCONF/RESTCONF, loosely based on With-defaults Capability for 247 NETCONF [RFC6243], that uses YANG Metadata 248 [I-D.ietf-netmod-yang-metadata] to annotate the Persistent 249 Configuration, Ephemeral Configuration, Operational State, or Running 250 Configuration Datastores with additional metadata that partially 251 reflects the contents of the abstract datastores illustrated in 252 Section 1.3. 254 Principally, the metadata annotations allow the client to see whether 255 the configuration has been applied or failed; the reason for the 256 failure if it has failed; or whether the configuration node only 257 exists because it has been created by the system. This is achieved 258 without the client having to query or explicitly monitor any of the 259 extra abstract datastores. 261 2.1. 'with-applied-config-metadata' modes query parameter 263 The 'with-applied-config-metadata' option supports further refinement 264 of the nodes and metadata that is returned through a query parameter 265 that supports three modes. 267 2.1.1. selectively-annotate 269 For a given NETCONF/RESTCONF query, the 'selectively-annotate' option 270 returns all the nodes what would have been returned for that query 271 anyway, but with additional metadata annotations for any nodes in the 272 request datastore that differ from the equivalent node in the applied 273 configuration datastore (i.e. it would exclude metadata annotations 274 for nodes that would be reported as "cfg-status=applied"). 276 This is the default option and MUST be supported by all servers 277 implementing the with-applied-config option. 279 This option allows a client to both monitor the exact configuration 280 that the device is trying to converge to, and also the status of 281 whether that configuration has been applied. This is achieved in a 282 way that uses a single request, and in the context of a single 283 datastore. In the case that the applied configuration exactly 284 matches the intended configuration then clearly no additional 285 metadata annotations are returned. 287 2.1.2. annotate-all 289 For a given NETCONF/RESTCONF query, the 'annotate-all' option returns 290 all the nodes what would have been returned for that query anyway, 291 but with opstate metadata annotations for all nodes that are 292 returned. I.e. this is the same data that would be returned using 293 the 'selectively-annotate' option except that it also includes 294 metadata for nodes that are reported as "cfg-status=applied". 296 This option MAY be supported by servers implementing the opstate 297 metadata option. It may be useful for clients that prefer explicit 298 applied configuration annotations for every node. 300 2.1.3. annotated-diff 302 For a given NETCONF/RESTCONF query, the 'annotated-diff' option 303 filters the nodes returned in the standard query, so that only nodes 304 that are not reported as "cfg-status=applied" are returned. Applied 305 configuration metadata annotations are included for all nodes that 306 are returned. 308 This option makes it easy for clients to determine whether their 309 configuration is fully applied in a concise way and SHOULD be 310 supported by all servers implementing the with-applied-config option. 312 2.2. Datastore specific handling 314 The Applied Configuration Metadata could be used with any of 315 following configuration datastores (persistent, ephemeral, intended, 316 applied, running), or the Operational State Datastore. However, not 317 all values of the "cfg-status" make sense for all datastores, so the 318 values that may be used for particular datastores are restricted as 319 follows: 321 Persistent Cfg Ds - applying, applied, applied-deviation, 322 overridden, blocked, failed 324 Ephemeral Cfg Ds - applying, applied, applied-deviation, 325 overridden, blocked, failed 327 Intended Cfg Ds - applying, applied, applied-deviation, blocked, 328 failed 330 Applied Cfg Ds - applying, applied, applied-deviation, failed 332 Operational State Ds - applying, applied, applied-deviation, 333 system-controlled, failed 335 If the Running Configuration Datastore is handled as described in 336 [I-D.wilton-netmod-refined-datastores], then NETCONF requests 337 are handled as if they are against the Operational State Datastore, 338 and requests are handled as if they are made against the 339 Intended Configuration Datastore, which indicates which metadata 340 values can be used. 342 2.3. Applied Configuration Metadata YANG Definition 344 Defines the applied configuration datastore metadata that is used in 345 both NETCONF and RESTCONF 346 file "ietf-yang-opstate-metadata@2016-07-06.yang" 347 module ietf-yang-opstate-metadata { 348 namespace 349 "urn:ietf:params:xml:ns:yang:ietf-yang-opstate-metadata"; 351 prefix "opstate"; 353 import ietf-yang-metadata { 354 prefix "md"; 355 } 357 organization 358 "IETF NETCONF (Network Configuration Protocol) Working Group"; 360 contact 361 "WG Web: 363 WG List: 365 WG Chair: Mahesh Jethanandani 366 368 WG Chair: Mehmet Ersue 369 371 Editor: Robert Wilton 372 "; 374 description 375 "This module defines YANG metadata to allow the reason why 376 a config true node exists in the operational state datastore 377 to be determined using YANG metadata. 379 Copyright (c) 2016 IETF Trust and the persons identified as 380 authors of the code. All rights reserved. 382 Redistribution and use in source and binary forms, with or 383 without modification, is permitted pursuant to, and subject 384 to the license terms contained in, the Simplified BSD License 385 set forth in Section 4.c of the IETF Trust's Legal Provisions 386 Relating to IETF Documents 387 (http://trustee.ietf.org/license-info). 389 This version of this YANG module is part of 390 draft-wilton-netconf-opstate-metadata-00; see the Internet 391 draft itself for full legal notices."; 393 revision 2016-07-06 { 394 description "Initial revision"; 396 reference 397 "Internet draft: draft-wilton-netconf-opstate-metadata-00"; 398 } 400 md:annotation cfg-status { 401 type enumeration { 402 enum applying { 403 description 404 "The configuration for the annotated node is currently 405 changing (i.e. being created, deleted or changing in 406 value) as part of an ongoing configuration operation"; 407 } 408 enum applied { 409 description 410 "The configuration is fully applied. The node exists in 411 both the intended and applied datastores and has exactly 412 the same value in both."; 413 } 414 enum applied-deviation { 415 description 416 "The configuration has been applied to the extend the 417 server is able to, but the value in the applied 418 configuration datastore does not exactly match the value 419 in the intended configuration datastore."; 420 } 421 enum overridden { 422 description 423 "The configuration node value has been overridden by the 424 same node in another configuration datastore."; 425 } 426 enum system-controlled { 427 description 428 "The configuration node only exists in the Operational 429 State Datastore because it is system controlled. It is 430 not present in the abstract applied configuration 431 datastore."; 432 } 433 enum blocked { 434 description 435 "The system cannot apply the configuration because 436 the required hardware resources are not present. The 437 configuration node does not exist in the applied 438 configuration datastore."; 439 } 440 enum failed { 441 description 442 "The system cannot apply the configuration due to an 443 error. The configuration node does not exist in the 444 applied configuration datastore."; 445 } 446 } 447 description 448 "Status indicates why a configuration node (i.e. config=true) 449 in the operational-state datastore does not match the 450 corresponding node in the intended config datastore"; 451 } 453 md:annotation cfg-status-reason { 454 when "../status = 'blocked' or ../status = 'failed'" { 455 description 456 "An optional status reason can be provided for blocked or 457 failed configuration"; 458 } 459 type string; 460 description 461 "Indicates the reason why the applied configuration node is 462 blocked or failed"; 463 } 464 } 465 467 2.4. :with-applied-cfg-metadata Capability 469 The :with-applied-cfg-metadata capability for NETCONF and RESTCONF 470 indicates that the server is capable of returning applied 471 configuration metadata. 473 2.4.1. Capability Identifier 475 Equivalent capabilities are defined for both NETCONF and RESTCONF: 477 NETCONF: urn:ietf:params:netconf:capability:with-applied-cfg- 478 metadata:1.0 480 RESTCONF: urn:ietf:params:restconf:capability:with-applied-cfg- 481 metadata:1.0 483 Note that this protocol capability URI is separate from the YANG 484 module capability URI for the YANG module is Section XXX. A server 485 that implements this module MUST also advertise a YANG module 486 capability URI according to the rules specified in [RFC6020]. 488 2.4.1.1. datastore parameter 490 The identifier MUST have a parameter: "supported-datastores". This 491 indicates which datastores the server allows the :with-applied-cfg- 492 metadata option to be used on. 494 The datastores that may be supported are described in Section 1.1. 495 The allowed values of this parameter include 'persistent', 496 'ephemeral', 'opstate', 'running', and any other appropriate 497 configuration datastores supported by the server. Both 'persistent' 498 and 'operational state' datastores MUST be supported. 500 2.4.1.2. supported-modes parameter 502 The identifier MUST also have the parameter: "supported-modes". This 503 indicates which particular operations are supported. 505 Possible modes are 'selectively-annotate', 'annotate-all', and 506 'annotated-diff' as defined in Section 2.1. The 'selectively- 507 annotate' option MUST be supported, and the 'annotated-diff' option 508 SHOULD be supported. 510 2.4.1.3. Examples 512 NETCONF and RESTCONF capability examples: 514 urn:ietf:params:netconf:capability:with-applied-cfg- 515 metadata:1.0?supported-datastores=persistent,intended&supported- 516 modes=selectively-annotate 518 urn:ietf:params:restconf:capability:with-applied-cfg- 519 metadata:1.0?supported-datastores=running&supported- 520 modes=selectively-annotate,annotated-diff 522 2.5. NETCONF specifics 524 Further details for the option need to 525 still be fleshed out here: 527 The option would only be supported for NETCONF and requests. 530 NETCONF would need to add support for the new datastores (as least 531 "persistent", "opstate"). 533 2.6. RESTCONF specifics 535 Further details for the option need to 536 still be fleshed out here: 538 The option would only be supported for RESTCONF GET requests. 540 The option could be used when accessing the default combined 541 datastore view, or with new datastore specific REST paths (e.g. as 542 least "persistent", "opstate"). 544 3. Discussion Points 546 This section lists some points that may warrant further discussion: 548 The proposal is written in terms of NETCONF/RESTCONF "get" 549 requests but it is desirable if the metadata could also apply to 550 YANG Pub/Sub as well. 552 Should the extension target adding opstate specific metadata, or 553 is it just applied configuration metadata? 555 The proposed YANG model merges several different opstate 556 properties into a single 'cfg-status' leaf, possibly these could 557 be separated out into separate leaves. 559 One of the aims of the approach described in 560 [I-D.wilton-netmod-refined-datastores] and in this document is to 561 allow opstate unaware servers to fairly easily add basic support 562 for the operational state extensions. This provides an 563 opportunity to improve interoperability with NETCONF/RESTCONF 564 clients because they can treat opstate aware and opstate aware 565 servers in exactly the same way. Does the approach in this draft 566 achieve this goal? 568 4. Acknowledgements 570 This document arose through discussions to find a consensual solution 571 to the operational state problem. The following people were actively 572 involved in the discussions that indirectly led to this document: 574 o Lou Berger, Labn Consulting, 576 o Martin Bjorklund, Tail-f Systems, 578 o Christian Hopps, Deutsche Telekom, 580 o Acee Lindem, Cisco Systems, 581 o Juergen Schoenwaelder, Jacobs University Bremen 582 584 o Rob Shakir, Jive Communications, 586 o Kent Watsen, Juniper Networks, 588 The author would also like the thank the following people who have 589 kindly provided feedback on this draft: Matt Hall, Einar Nilsen- 590 Nygaard. 592 5. IANA Considerations 594 None 596 6. Security Considerations 598 TBD. 600 7. References 602 7.1. Normative References 604 [I-D.ietf-netmod-opstate-reqs] 605 Watsen, K. and T. Nadeau, "Terminology and Requirements 606 for Enhanced Handling of Operational State", draft-ietf- 607 netmod-opstate-reqs-04 (work in progress), January 2016. 609 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 610 the Network Configuration Protocol (NETCONF)", RFC 6020, 611 DOI 10.17487/RFC6020, October 2010, 612 . 614 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 615 and A. Bierman, Ed., "Network Configuration Protocol 616 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 617 . 619 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 620 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 621 . 623 7.2. Informative References 625 [I-D.ietf-i2rs-ephemeral-state] 626 Haas, J. and S. Hares, "I2RS Ephemeral State 627 Requirements", draft-ietf-i2rs-ephemeral-state-10 (work in 628 progress), June 2016. 630 [I-D.ietf-netmod-yang-metadata] 631 Lhotka, L., "Defining and Using Metadata with YANG", 632 draft-ietf-netmod-yang-metadata-07 (work in progress), 633 March 2016. 635 [I-D.schoenw-netmod-revised-datastores] 636 Schoenwaelder, J., "A Revised Conceptual Model for YANG 637 Datastores", draft-schoenw-netmod-revised-datastores-01 638 (work in progress), June 2016. 640 [I-D.wilton-netmod-refined-datastores] 641 Wilton, R., "Refined YANG datastores", draft-wilton- 642 netmod-refined-datastores-00 (work in progress), June 643 2016. 645 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 646 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 647 . 649 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 650 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 651 . 653 [RFC6244] Shafer, P., "An Architecture for Network Management Using 654 NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244, June 655 2011, . 657 Appendix A. Usage examples 659 A sample encoding of the enhancement is 660 described below. 662 A simple example module is provided to illustrate the subsequent 663 examples. This is not a real module, and is not intended for any 664 real use. 666 module example-interfaces { 668 namespace "http://example.com/ns/interfaces"; 670 prefix exam; 672 container interfaces { 673 description "Example interfaces group"; 675 list interface { 676 key name; 677 description "Example interface entry"; 678 leaf name { 679 type string { 680 length "1 .. max"; 681 } 682 description 683 "The administrative name of the interface."; 684 } 686 leaf mtu { 687 type uint32; 688 default 1514; 689 description 690 "The maximum transmission unit (MTU) value assigned to 691 this interface."; 692 } 694 leaf enabled { 695 type boolean; 696 default "true"; 697 description "Enable the interface"; 698 } 700 leaf oper-status { 701 config false; 702 type enumeration { 703 enum up { 704 description 705 "Ready to pass packets."; 706 } 707 enum down; { 708 description 709 "The interface does not pass any packets."; 710 } 711 } 712 } 713 } 714 } 715 } 717 A.1. NETCONF Persistent datastore get-config request using with- 718 applied-cfg-metadata 720 This example illustrates a request made against the 721 Persistent Configuration Datastore using the with-applied-cfg- 722 metadata selectively-annotate option using the example YANG module 723 above: 725 727 728 729 730 731 732 733 734 735 xmlns="urn:...:ietf-netconf-with-applied-cfg-metadata"> 736 selectively-annotate 737 738 739 741 The response indicates that at the time of the reply: 743 The system has failed to apply the MTU configuration of 9001 on 744 eth0/0 due to a hardware programming error. 746 The request to change the MTU leaf on eth0/1 to 9000 is still in 747 the process of being applied. 749 The MTU configuration on eth0/2 has been successfully applied. 751 754 755 756 757 eth0/0 758 760 9001 761 762 763 764 eth0/1 765 766 9000 767 768 769 770 eth0/2 771 2000 772 773 774 775 777 A.2. NETCONF Operational State Datastore get request using with- 778 applied-cfg-metadata 780 This example illustrates a request made against the Operational 781 State Datastore using the with-applied-cfg-metadata selectively- 782 annotate option using the example YANG module above: 784 786 787 788 789 790 791 792 793 794 xmlns="urn:...:ietf-netconf-with-applied-cfg-metadata"> 795 selectively-annotate 796 797 798 799 An example response is given below. This response assumes that the 800 device is in the same state as for the example given 801 above, and assumes that the device uses NETCONF with-default 802 "explicit" mode. The response indicates that at the time of the 803 reply: 805 The MTU on eth0/0 is still at the YANG default of 1514. This 806 differs from the intended configuration because the configuration 807 failed to be applied. 809 The configuration request to change the MTU leaf on eth0/1 from 810 1514 to 9000 is still in the process of being applied, and the 811 device is still currently using an MTU of 1514. 813 The MTU configuration of 2000 on eth0/2 has been successfully 814 applied. 816 eth0/3 has not been configured, but exists in the Operational 817 State Datastore because it is automatically created by the device. 818 The MTU leaf (which has the default value) must also be marked as 819 system-controlled because there is no implicit or explicit MTU 820 leaf in the intended configuration for eth0/3. The enabled leaf 821 is also system-controlled but with a non default value, since the 822 device does not allow the interface to be enabled without being 823 explicitly configured. 825 828 829 830 831 eth0/0 832 834 1514 835 836 true 837 up 838 839 840 eth0/1 841 842 1514 843 844 true 845 up 846 847 848 eth0/2 849 2000 850 true 851 up 852 853 854 855 eth0/3 856 857 858 1514 859 860 861 false 862 863 down 864 865 866 867 869 Author's Address 871 Robert Wilton (editor) 872 Cisco Systems 874 Email: rwilton@cisco.com