idnits 2.17.1 draft-bierman-netconf-efficiency-extensions-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 == Line 1188 has weird spacing: '...eration enu...' == Line 1221 has weird spacing: '...edit-id strin...' == 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). -- The document date (October 19, 2013) is 3842 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-10) exists of draft-ietf-json-rfc4627bis-03 == Outdated reference: A later version (-04) exists of draft-bierman-netconf-restconf-02 -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD' Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks, Inc. 4 Intended status: Standards Track October 19, 2013 5 Expires: April 22, 2014 7 NETCONF Efficiency Extensions 8 draft-bierman-netconf-efficiency-extensions-00 10 Abstract 12 This document describes protocol extensions to improve the efficiency 13 of the Network Configuration Protocol (NETCONF). Protocol 14 capabilities and operations are defined to reduce network usage and 15 transaction complexity. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 22, 2014. 34 Copyright Notice 36 Copyright (c) 2013 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.1.3. RESTCONF . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 6 58 1.2. Problem Statement . . . . . . . . . . . . . . . . . . . . 6 59 1.2.1. Exchange . . . . . . . . . . . . . . . . . . . 6 60 1.2.2. Initial Configuration Retrieval . . . . . . . . . . . 6 61 1.2.3. Message Encoding . . . . . . . . . . . . . . . . . . . 7 62 1.2.4. Datastore Editing . . . . . . . . . . . . . . . . . . 7 63 1.2.5. Data Retrieval . . . . . . . . . . . . . . . . . . . . 9 64 1.3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 1.3.1. Capability ID Exchange . . . . . . . . . . . . . . . . 10 66 1.3.2. Configuration ID Advertisement . . . . . . . . . . . . 11 67 1.3.3. Message Encoding Negotiation . . . . . . . . . . . . . 11 68 1.3.4. Operation . . . . . . . . . . . . . . . . . . 11 69 1.3.5. Operation . . . . . . . . . . . . . . . . . . . 12 70 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 13 71 2.1. "capability-id" Capability . . . . . . . . . . . . . . . . 13 72 2.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 13 73 2.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . . 18 74 2.1.3. Capability Identifier . . . . . . . . . . . . . . . . 18 75 2.1.4. New Operations . . . . . . . . . . . . . . . . . . . . 18 76 2.1.5. Modifications to Existing Operations . . . . . . . . . 18 77 2.1.6. Interactions with Other Capabilities . . . . . . . . . 19 78 2.2. "config-id" Capability . . . . . . . . . . . . . . . . . . 19 79 2.2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 19 80 2.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . 21 81 2.2.3. Capability Identifier . . . . . . . . . . . . . . . . 21 82 2.2.4. New Operations . . . . . . . . . . . . . . . . . . . . 21 83 2.2.5. Modifications to Existing Operations . . . . . . . . . 22 84 2.2.6. Interactions with Other Capabilities . . . . . . . . . 22 85 2.3. "encoding" Capability . . . . . . . . . . . . . . . . . . 22 86 2.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 22 87 2.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . . 24 88 2.3.3. Capability Identifier . . . . . . . . . . . . . . . . 24 89 2.3.4. New Operations . . . . . . . . . . . . . . . . . . . . 25 90 2.3.5. Modifications to Existing Operations . . . . . . . . . 25 91 2.3.6. Interactions with Other Capabilities . . . . . . . . . 25 92 2.4. Protocol Operation . . . . . . . . . . . . . . . . 25 93 2.4.1. Input . . . . . . . . . . . . . . . . . . . . 26 94 2.4.2. Output . . . . . . . . . . . . . . . . . . . . 27 95 2.4.3. YANG Tree Diagram . . . . . . . . . . . . . . 27 96 2.4.4. Example . . . . . . . . . . . . . . . . . . . 28 98 2.5. Operation . . . . . . . . . . . . . . . 30 99 2.5.1. Input . . . . . . . . . . . . . . . 30 100 2.5.2. Output . . . . . . . . . . . . . . . 30 101 2.5.3. YANG Tree Diagram . . . . . . . . . 31 102 2.5.4. Example . . . . . . . . . . . . . . 31 103 2.6. Operation . . . . . . . . . . . . . . . . 31 104 2.6.1. Input . . . . . . . . . . . . . . . . 31 105 2.6.2. Output . . . . . . . . . . . . . . . . 31 106 2.6.3. YANG Tree Diagram . . . . . . . . . . 32 107 2.6.4. Example . . . . . . . . . . . . . . . 32 108 2.7. Protocol Operation . . . . . . . . . . . . . . . . 32 109 2.7.1. Depth Filters . . . . . . . . . . . . . . . . . . . . 32 110 2.7.2. Time Filters . . . . . . . . . . . . . . . . . . . . . 33 111 2.7.3. Input . . . . . . . . . . . . . . . . . . . . . 33 112 2.7.4. Output . . . . . . . . . . . . . . . . . . . . 34 113 2.7.5. YANG Tree Diagram . . . . . . . . . . . . . . . 35 114 2.7.6. Example . . . . . . . . . . . . . . . . . . . . 35 115 2.8. NETCONF-EX YANG Module . . . . . . . . . . . . . . . . . . 36 116 2.9. XSD for NETCONF-EX Metadata . . . . . . . . . . . . . . . 53 117 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 118 3.1. NETCONF-EX XML Namespace . . . . . . . . . . . . . . . . . 55 119 3.2. NETCONF-EX XML Schema . . . . . . . . . . . . . . . . . . 55 120 3.3. NETCONF-EX YANG Module . . . . . . . . . . . . . . . . . . 55 121 4. Security Considerations . . . . . . . . . . . . . . . . . . . 56 122 5. Normative References . . . . . . . . . . . . . . . . . . . . . 57 123 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 58 124 A.1. resource-identifier-type . . . . . . . . . . . . . . . . . 58 125 A.2. no YANG for top-level message nodes . . . . . . . . . . . 58 126 A.3. only 1 location returned per edit . . . . . . . . . . . . 58 127 A.4. config-id attribute . . . . . . . . . . . . . . . . . . . 58 128 A.5. nodeset retrieval . . . . . . . . . . . . . . . . . 58 129 Appendix B. Additional Examples . . . . . . . . . . . . . . . . . 59 130 B.1. YANG Module Used in Examples . . . . . . . . . . . . . . . 59 131 B.2. YANG Data Used in Examples . . . . . . . . . . . . . . . . 60 132 B.3. Examples . . . . . . . . . . . . . . . . . . . . . 61 133 B.3.1. Confirmed Commit on the "running" Datastore . . . . . 61 134 B.3.2. Conditional Editing with "if-match" Parameter . . . . 63 135 B.3.3. Bulk Editing with "target-resource" Parameter . . . . 65 136 B.3.4. Edit Validation with "test-only" Parameter . . . . . . 67 137 B.4. Examples . . . . . . . . . . . . . . . . . . . . . 69 138 B.4.1. If-Modified-Since Non-Empty Filter Retrieval . . . . . 69 139 B.4.2. If-Modified-Since Empty Filter Retrieval . . . . . . . 71 140 B.4.3. Keys Only Filter Retrieval . . . . . . . . . . . . . . 71 141 B.4.4. Test for Node Existence with Depth=1 . . . . . . . . . 73 142 B.4.5. Retrieve Only Non-Configuration Data Nodes . . . . . . 74 143 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 76 145 1. Introduction 147 There is a need for standard mechanisms to allow NETCONF [RFC6241] 148 application designers to manage NETCONF servers more efficiently when 149 used in network environments with poor connectivity, low bandwidth, 150 and/or high latency. In such conditions, it is desirable to minimize 151 network usage wrt/ the size of protocol messages and the number of 152 protocol operations required to perform a network management 153 function. 155 1.1. Terminology 157 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 159 "OPTIONAL" in this document are to be interpreted as described in BCP 160 14, [RFC2119]. 162 1.1.1. NETCONF 164 The following terms are defined in [RFC6241]: 166 o candidate configuration datastore 168 o client 170 o configuration data 172 o datastore 174 o configuration datastore 176 o protocol operation 178 o running configuration datastore 180 o server 182 o startup configuration datastore 184 1.1.2. YANG 186 The following terms are defined in [RFC6020]: 188 o container 190 o data node 191 o key leaf 193 o leaf 195 o leaf-list 197 o list 199 1.1.3. RESTCONF 201 The following terms are defined in [RESTCONF]: 203 o data resource 205 o datastore resource 207 o YANG Patch 209 1.1.4. Terms 211 The following terms are defined: 213 o capability ID: An opaque string identifier that represents the 214 current state of the server capability set. A new capability ID 215 is chosen by the server each time the server capability set is 216 altered in any way. 218 o capability set: The conceptual set of all capability URIs that are 219 active on the server, including all parameters. This set does not 220 include the ":config-id" capability if it is supported. 222 o config ID: An opaque string identifier that represents the state 223 of the running datastore contents on the server. A new config ID 224 is chosen by the server each time the server running configuration 225 datastore is altered in any way. 227 o depth filter: A mechanism implemented within the NETCONF server to 228 allow a client to retrieve only a limited number of levels within 229 the a subtree, instead of retrieving the entire subtree. 231 o time filter: A mechanism implemented within the NETCONF server to 232 allow a client to retrieve only data that has been modified since 233 a specified data and time. 235 1.1.5. Tree Diagrams 237 A simplified graphical representation of the data model is used in 238 this document. The meaning of the symbols in these diagrams is as 239 follows: 241 o Brackets "[" and "]" enclose list keys. 243 o Abbreviations before data node names: "rw" means configuration 244 (read-write) and "ro" state data (read-only). 246 o Symbols after data node names: "?" means an optional node and "*" 247 denotes a "list" and "leaf-list". 249 o Parentheses enclose choice and case nodes, and case nodes are also 250 marked with a colon (":"). 252 o Ellipsis ("...") stands for contents of subtrees that are not 253 shown. 255 1.2. Problem Statement 257 This document attempts to address the following problems with NETCONF 258 protocol procedures. 260 1.2.1. Exchange 262 The server message can be rather large (e.g., greater than 263 10,000 bytes), and the information it contains tends to be rather 264 static in practice. If a large number of server connections are lost 265 and then restarted, the quantity of large messages from every 266 server could impact network performance. 268 It would be useful if the message exchange could be enhanced 269 so the server message size could be minimized. The new 270 message exchange must be completely backward compatible such 271 that existing client or server implementations will continue to 272 function. 274 1.2.2. Initial Configuration Retrieval 276 A client application often needs to retrieve the entire running 277 configuration datastore contents, usually at the start of an editing 278 session. The for this request can be very 279 large (e.g., greater than 250,000 bytes). 281 If a large number of server connections are lost and then restarted, 282 the quantity of large messages from every server could 283 severely impact network performance. 285 It would be useful if the message exchange could be enhanced 286 so an entity-tag value for the current running datastore 287 configuration is included in the server message. A client 288 can cache the server configuration identifier and omit an initial 289 operation if the value from the server message 290 matches the cached value. 292 1.2.3. Message Encoding 294 NETCONF uses a hard-wired message encoding format, namely XML. 295 However, XML tends to be verbose, especially for YANG data models 296 that have long data node identifiers. 298 There is no reason for the NETCONF message encoding to be hardwired, 299 except for the message. It would be useful if the NETCONF 300 protocol could support other message encoding formats, such as JSON 301 [JSON]. The message exchange could be enhanced so the client 302 and server negotiated the message encoding to use for all other 303 messages via an capability exchange included in both 304 messages. 306 1.2.4. Datastore Editing 308 There are several deficiencies with the NETCONF editing procedures 309 that could be improved. 311 Multi-operation functions can be required. A single edit can take up 312 to 9 operations. Several operations are required to complete a set 313 of 1 or more edits on a NETCONF server. Each operation uses 1 314 request and 1 response message. If the candidate datastore is used, 315 then 1 extra operation is required (for the operation) to 316 activate the edit(s). If the startup datastore is used then 1 extra 317 operation is required (for the operation) to save the 318 running datastore contents in non-volatile storage. If global 319 locking is used, then 2 extra operations are required for each 320 datastore involved (candidate, running, startup) Since the datastore 321 is locked at the start and unlocked at the end of the entire edit 322 operation, these extra roundtrip times are intervals in which the 323 datastore is being locked, but no datastore access is being done. 325 Obtaining locks can be expensive. If the server has more than 1 326 datastore (e.g., candidate + running or running + startup), then 327 multiple lock requests are required, since the and 328 operations on affect 1 datastore at a time. This can cause a long 329 delay or even deadlock if multiple clients are attempting to obtain 330 global locks at once. E.g., client 1 holds a lock on the candidate 331 datastore and is trying to lock the running datastore. At the same 332 time, client 2 holds a lock on the running datastore and is trying to 333 lock the candidate datastore. 335 Using locks can be brittle. NETCONF clients are intended to be 336 programmatic, so is not likely that locks will be long-lived. Global 337 locks are designed to be short-lived since they block write access to 338 the entire datastore. If lock collisions do occur, they are likely 339 to be cleared very quickly. It would be useful if the client could 340 request how long to wait for locks to clear instead of immediately 341 rejecting an edit request due to an 'in-use' error. 343 Edit operations are implied by content. NETCONF uses a 344 default operation and explicit operation attribute within an 345 arbitrarily complete XML subtree to represent a configuration 346 datastore. There are several corner-cases that are not standardized, 347 and very implementation-dependent: 349 - interpretation of implied operations vs. explicit operations 350 - order the edits are processed 351 - handling of nested operation attributes 352 - handling of duplicate subtrees 353 - error handling (code points, number of errors, etc.) 354 - move operations are not explicit and can interpreted as 355 a request to remove and re-add an entry, not just move 356 user-ordered data 358 Edit operations are not protected against multi-client alterations. 359 It is a simple and common practice to retrieve a configuration data 360 resource, changing 1 or more fields, and then update the resource on 361 the server. Since retrieval and edit operations are separate there 362 is always a chance that another client has altered the resource after 363 the operation, but before the operation, 364 by the first client. Each client could be protected if there was an 365 entity tag associated with each data resource, and an edit request 366 could be rejected if the client attempted to edit a different version 367 of the data resource than expected. 369 There is no bulk-edit support. If the same edit is needed in 370 multiple instances of a particular data resource, then the data must 371 be repeated for each instance in the or 372 request. The request message size could be minimized if there was a 373 way to apply a set of edits to multiple target nodes at once. 375 There is no confirmed commit support for the running datastore. The 376 ability to backup the running datastore, change it, and revert it 377 unless the client confirms the changes has nothing to do with the 378 candidate datastore. A NETCONF server with limited memory is not 379 likely to support the candidate datastore. This feature is useful 380 for any type of network-wide configuration change, regardless of 381 device size. 383 1.2.5. Data Retrieval 385 NETCONF data retrieval via the and operations can 386 be very inefficient. Some vendors do not even support because 387 it can be such a resource-intensive operation and return an enormous 388 amount of data, especially if all server data is requested at once. 390 A client cannot retrieve just the non-configuration data. The 391 NETCONF operation allows a client to retrieve data from the 392 server but it returns all data, including configuration datastore 393 nodes. The operation already returns all configuration 394 datastore nodes. 396 It was originally thought that should return all nodes so the 397 client would not have to correlate configuration and non- 398 configuration data nodes, since they would be mixed together in the 399 reply. Operational experience has shown that the operation 400 without reasonable filters to reduce the returned data can 401 significantly degrade device performance and return enormous XML 402 instance documents in the . 404 There is no "last-modified" indication or time filtering. The 405 NETCONF protocol has no standard mechanisms to indicate to a client 406 when a datastore was last modified, or to allow a client to retrieve 407 data only if it has been modified since a specified time. This makes 408 polling applications very inefficient because they will regularly 409 burden the server and the network and themselves with retrieval and 410 processing requests for data that has not changed. 412 There is no simple list instance discovery mechanism. Sometimes the 413 client application wants to discover what data exists on the server, 414 particularly list entries. There is a need for a simple mechanism to 415 retrieve just the key leaf nodes within a subtree. The NETCONF 416 subtree filtering mechanism does provide a very complex way for the 417 client to request just key leafs for specific list entries. A 418 simpler mechanism is needed which will allow the client to discover 419 the list instances present. 421 There is no subtree depth control. NETCONF filters allow the client 422 to select specific sub-trees within the conceptual datastore on the 423 server. However, sometimes the client does not really need the 424 entire subtree, which may contain many nested list entries, and be 425 very large. There is sometimes a need to limit the depth of the sub- 426 trees retrieved from the server. A consistent and simple algorithm 427 for determining what data nodes start a new level is needed. 429 The content filter specification is not extensible. The NETCONF 430 and operations use a hard-coded content filtering 431 mechanism. They use a "type" XML attribute to indicate which of two 432 filter specification types they support, and a "select" XML attribute 433 if the :xpath capability is supported and an XPath [XPATH] expression 434 filter specification is provided. 436 This design does not allow additional content filter specification 437 types to be supported by an implementation. It does not allow the 438 standard to be easily extended in a modular fashion. In addition, 439 this design does not allow YANG statements to be used to properly 440 describe the protocol operation. The special 441 "get-filter-element-attributes" YANG extension in the ietf-netconf 442 module is not extensible, and it does not really count as proper 443 YANG, since this extension is outside the YANG language definition. 445 There is no standard metadata or standard way to retrieve metadata. 446 The parameter allows 1 specific type of metadata to 447 be returned (i.e., 'report-all-tagged' mode). This ad-hoc approach 448 does not scale well and is not extensible. It would be useful if 449 standard and vendor-specific metadata could be identified and 450 retrieved with standard operations. 452 1.3. Solution 454 This document defines some NETCONF protocol operations and new 455 capabilities to reduce network usage and increase functionality at 456 the same time. 458 All NETCONF efficiency extensions are completely backward-compatible 459 with the current definitions in [RFC6241]. An old server will ignore 460 any new URIs sent by a new client. An old client will 461 ignore any new URIs sent by the server, and will not use 462 the new operations. No existing operations are affected by the new 463 operations, so the extensions will be transparent to an existing 464 NETCONF client. 466 1.3.1. Capability ID Exchange 468 A new capability called "capability-id" is defined to identify the 469 current set of NETCONF URIs with an opaque string. A 470 client can cache this value for each server that supports this 471 capability, and send the value in a "capability-id" URI 472 in its message. 474 The server will slightly delay sending its message to attempt 475 to process the client first. If the client is 476 received, and the "capability-id" URI is found and matches the server 477 value, then an abbreviated server message is sent instead of 478 a full message. Refer to Section 2.1 for details on the 479 capability ID exchange procedure. 481 1.3.2. Configuration ID Advertisement 483 A new capability called "config-id" is defined to identify the 484 current running datastore configuration contents with an opaque 485 string. A client can cache this value for each server that supports 486 this capability, along with a copy of its running configuration. 487 When a new session is started, the client can examine the "config-id" 488 URI sent by the server. If it is the same as the cached 489 value then the client can use the cached running datastore copy 490 instead of sending an initial operation to the server. 491 The :config-id capability is ignored in the calculation of the 492 :capability-id capability. Refer to Section 2.2 for details on 493 configuration ID advertisement. 495 1.3.3. Message Encoding Negotiation 497 A new capability called "encoding" is defined to allow a client to 498 request that an alternate message encoding be used for the NETCONF 499 session. The capability is encoded as a comma-separated list of 500 media types. This list is ordered by the client in the order of 501 highest preference first. The server list is unordered. The first 502 match (done in client priority) is the message encoding used for the 503 rest of session. Refer to Section 2.3 for details on message 504 encoding negotiation. 506 1.3.4. Operation 508 A new NETCONF protocol operation called is defined to address 509 the deficiencies described in Section 1.2.4. This operation allows 510 the entire NETCONF edit procedure to be accomplished with 1 request 511 message. The editing procedures are aligned with the resource model 512 defined in [RESTCONF]. Refer to Section 2.4 for details on 513 operation. 515 The "confirmed-commit" procedure has been integrated into the 516 operation, and can be supported by any server without requiring 517 support for the candidate datastore. It is optional to implement, 518 based on the "confirmed-edit" capability defined in Section 2.8. 520 Refer to Section 2.5 for details on the operation 521 and Section 2.6 for details on the operation. 523 1.3.5. Operation 525 A new NETCONF protocol operation called is defined to address 526 the deficiencies described in Section 1.2.5. This operation allows 527 several filter types to be combined to control the data that is 528 returned in the message, and an extensible framework for 529 retrieving metadata associated with datastore or data resources. 530 Refer to Section 2.7 for details on operation. 532 2. Definitions 534 This section defines the NETCONF efficiency extensions: 536 - :capability-id Capability 537 - :config-id Capability 538 - :encoding Capability 539 - Operation 540 - Operation 541 - Operation 542 - Operation 544 2.1. "capability-id" Capability 546 2.1.1. Overview 548 The :capability-id capability is used by the client to request an 549 abbreviated message instead of a full message from 550 the server. 552 1) Client keeps a cache of server capability sets 554 2) Client sends with "capability-id" set 555 to the cached value 557 Client Client message 558 +---------------+ +--------------------+ 559 | Server | | capability-id=5555 | 560 | Capability | ---> | | --> server 561 | Cache | | ... | 562 +---------------+ +--------------------+ 564 3) Server waits a small interval for the client . 565 It will send either a full or an abbreviated 567 4) Client received in time and it contains a 568 capability-id value that matches the server's current value. 569 The server sends an abbreviated with just 2 570 URIs 572 Client Server X Abbreviated message 573 +---------------+ +--------------------+ 574 | Server | | config-id=1234 | 575 | Capability | <------- | capability-id=5555 | 576 | Cache | +--------------------+ 577 +---------------+ 579 5) The client gets the server and sees that it has 580 a capability-id value and it matches the value that 581 was sent by the client. It determines the server returned 582 an abbreviated and uses the cached capability set 584 The server MUST maintain a capability ID that represents the current 585 state of the capability set. The :config-id capability defined in 586 Section 2.2 is not included in this set of capabilities. It is 587 ignored for purposes capability set identification. Otherwise the 588 :capability-id value would change every time the :config-id value 589 changed. 591 The server will slightly delay sending its message to attempt 592 to process the client first. If the client is 593 received, and "capability-id" URI is found and matches the server 594 value, then an abbreviated server message is sent instead of 595 a full message. Refer to Section 2.1 for details on the 596 capability ID exchange procedure. 598 2.1.1.1. :capability-id Capability Example 600 Initially, the client does not know the current capability-id of the 601 server, so it does not include it in its message to the 602 server: 604 # Client requests a new session 605 606 607 urn:ietf:params:netconf:base:1.0 608 urn:ietf:params:netconf:base:1.1 609 611 The server delays sending its message and within 1 second 612 receives the client message. The server determines that the 613 :capability-id capability is not present in the client 614 message, so a full server message is sent, which includes the 615 current "capability-id" URI value for the capability set. 617 In this example, only a small number of YANG module capabilities are 618 reported. In a real server, there are usually many YANG module 619 capabilities (e.g., 25 - 50) to report. Extra whitespace has been 620 added to the XML for display purposes only. 622 # Server starts session 1 with full 623 624 625 urn:ietf:params:netconf:base:1.0 626 urn:ietf:params:netconf:base:1.1 627 628 urn:ietf:params:netconf:capability:candidate:1.0 629 630 631 urn:ietf:params:netconf:capability:confirmed-commit:1.0 632 633 634 urn:ietf:params:netconf:capability:confirmed-commit:1.1 635 636 637 urn:ietf:params:netconf:capability:rollback-on-error:1.0 638 639 640 urn:ietf:params:netconf:capability:validate:1.0 641 642 643 urn:ietf:params:netconf:capability:validate:1.1 644 645 646 urn:ietf:params:netconf:capability:url:1.0?scheme=file 647 648 649 urn:ietf:params:netconf:capability:xpath:1.0 650 651 652 urn:ietf:params:netconf:capability:notification:1.0 653 654 655 urn:ietf:params:netconf:capability:interleave:1.0 656 657 658 urn:ietf:params:netconf:capability:partial-lock:1.0 659 660 661 urn:ietf:params:netconf:capability:with-defaults:1.0? 662 basic-mode=explicit&also-supported=trim,report-all, 663 report-all-tagged 664 665 666 urn:ietf:params:xml:ns:netconf:base:1.0? 667 module=ietf-netconf&revision=2011-06-01 668 669 670 urn:ietf:params:xml:ns:yang:ietf-netconf-ex? 671 module=ietf-netconf-ex&revision=2013-10-19 672 673 674 urn:ietf:params:xml:ns:yang:ietf-inet-types? 675 module=ietf-inet-types&revision=2013-07-15 676 677 678 urn:ietf:params:xml:ns:yang:ietf-netconf-acm? 679 module=ietf-netconf-acm&revision=2012-02-22 680 681 682 urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring? 683 module=ietf-netconf-monitoring&revision=2010-10-04 684 685 686 urn:ietf:params:xml:ns:yang:ietf-netconf-notifications? 687 module=ietf-netconf-notifications&revision=2012-02-06 688 689 690 urn:ietf:params:xml:ns:netconf:partial-lock:1.0? 691 module=ietf-netconf-partial-lock&revision=2009-10-19 692 693 694 urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults? 695 module=ietf-netconf-with-defaults&revision=2011-06-01 696 697 698 urn:ietf:params:xml:ns:yang:ietf-yang-types? 699 module=ietf-yang-types&revision=2013-07-15 700 701 702 http://example.com/ns/example-ex? 703 module=example-ex&revision=2013-10-19 704 705 706 urn:ietf:params:netconf:capability:capability-id:1.0?id=64ae3ffa 707 708 709 urn:ietf:params:netconf:capability:config-id?id=1455 710 711 712 1 713 715 The next time the client starts a session with this server, it 716 includes the server capability ID it saved from session 1: 718 # Client requests another session 719 720 721 urn:ietf:params:netconf:base:1.0 722 urn:ietf:params:netconf:base:1.1 723 724 urn:ietf:params:netconf:capability:capability-id:1.0?id=64ae3ffa 725 726 728 The server examines the capability-id URI and determines 729 that the capability ID value matches its own current capability ID 730 value, so it sends an abbreviated message to the client: 732 # Server starts session 2 with an abbreviated 733 734 735 736 urn:ietf:params:netconf:capability:capability-id:1.0?id=64ae3ffa 737 738 739 urn:ietf:params:netconf:capability:config-id?id=2130 740 741 742 2 743 745 2.1.2. Dependencies 747 The :capability-id capability is not dependent on any other 748 capabilities. 750 2.1.3. Capability Identifier 752 The :capability-id capability is identified by the following 753 capability string: 755 urn:ietf:params:netconf:capability:capability-id:1.0 757 This capability MUST be advertised in every server message. 758 The :capability-id capability URI MUST contain an "id" argument 759 assigned an opaque string value indicating the current capability ID 760 value for the server capability set. For example: 762 urn:ietf:params:netconf:capability:capability-id:1.0?id=64ae3ffa 764 The current config ID value MUST be updated any time a 765 "netconf-capability-change" event would be generated by the server. 767 If [RFC6470] is supported, then the "capability-id" leaf defined in 768 Section 2.8 MUST be included in event 769 notifications. 771 2.1.4. New Operations 773 The :capability-id capability does not introduce any new protocol 774 operations. 776 2.1.5. Modifications to Existing Operations 778 The message exchange is modified to allow the server to send 779 an abbreviated capability list. If the client does not send this 780 capability, or the capability ID value it sends is not the same as 781 the current server capability ID, then there are no changes to the 782 exchange, as the server will send a full message to 783 the client, as defined in [RFC6241]. 785 2.1.5.1. Abbreviated Exchange 787 If the server supports the :capability-id capability it SHOULD delay 788 sending its message for a short amount of time. This value 789 (called the "hello delay" parameter) is not specified here because a 790 standard "hello-timeout" parameter is not available to configure 791 NETCONF servers. It is RECOMMENDED that server wait up to 10% of its 792 hello timeout interval for the client to send a message. 794 If the message is received before the hello delay timeout 795 occurs, then the server examines the client and sends either 796 a full or abbreviated message right away. 798 If the hello delay timeout expires before the client message 799 is received then the server sends a full message right away. 801 If the client sends a matching config ID value, the the server MUST 802 send the "capability-id" and "config-id" 803 (if supported), in an abbreviated message. The server SHOULD 804 omit all other elements in the message. 805 Otherwise the server MUST send a full message, which MUST 806 include a "capability-id" URI identifying the current 807 capability ID for the server. 809 2.1.6. Interactions with Other Capabilities 811 The :capability-id capability interacts with the :config-id 812 capability. The :config-id capability is ignored by the server when 813 calculating a new config ID value. The :config-id capability is also 814 included in abbreviated messages. 816 2.2. "config-id" Capability 818 2.2.1. Overview 820 The :config-id capability indicates that the server maintains a 821 config ID for the running configuration datastore. This identifier 822 value is selected by the server and treated as an opaque string by 823 the client. 825 1) Client keeps a cache of server configurations. 826 2) Server always sends its current config-id value 827 in the "config-id" URI. 829 Client Server X message 830 +---------------+ +------------------+ 831 | | | config-id=1234 | 832 | Server Config | <------- | | 833 | Cache | | ... | 834 +---------------+ +------------------+ 836 3) Client checks cache for server X, config-id=1234. 837 If found, then OK to use the cached configuration copy. 838 If not found, then send a for the running 839 configuration to create or update the cached copy. 841 The server SHOULD save the config ID for the running datastore in 842 non-volatile storage. When the server boots or restarts, the initial 843 configuration ID SHOULD be the same as the last instantiation, if the 844 server does not support the :startup capability (so the non-volatile 845 stored version mirrors the running datastore). If the server does 846 support the :startup capability, then the initial configuration ID 847 SHOULD be the same as the version last saved to non-volatile storage. 849 2.2.1.1. :config-id Capability Example 851 The client may or may not have the current config ID value for the 852 server when a session starts. Only the server message will 853 include a config-id URI. This example assumes the 854 abbreviated message can be sent to the client for brevity. 856 # Client requests another session 857 858 859 urn:ietf:params:netconf:base:1.0 860 urn:ietf:params:netconf:base:1.1 861 862 urn:ietf:params:netconf:capability:capability-id:1.0?id=692267fa 863 864 866 The server examines the capability-id URI and determines 867 that the capability ID value matches its own current capability ID 868 value, so it sends an abbreviated message to the client. The 869 :config-id capability is sent in every server message. The 870 "id" parameter for the :config-id capability is set to the current 871 config ID for the running datastore on the server: 873 # Server starts session 3 with an abbreviated 874 875 876 877 urn:ietf:params:netconf:capability:capability-id:1.0?id=692267fa 878 879 880 urn:ietf:params:netconf:capability:config-id?id=4284 881 882 883 3 884 886 2.2.2. Dependencies 888 The :config-id capability is not dependent on any other capabilities. 890 2.2.3. Capability Identifier 892 The :config-id capability is identified by the following capability 893 string: 895 urn:ietf:params:netconf:capability:config-id:1.0 897 This capability MUST be advertised in every server message. 898 The :config-id capability URI MUST contain an "id" argument assigned 899 an opaque string value indicating the current config ID value for the 900 running datastore. For example: 902 urn:ietf:params:netconf:capability:config-id:1.0?id=6882391 904 The current config ID value MUST be updated any time a 905 "netconf-config-change" event would be generated by the server. 907 If [RFC6470] is supported, then the "config-id" leaf defined in 908 Section 2.8 MUST be included in event 909 notifications. 911 If the "with-metadata" parameter in the operation specifies 912 the "config-id" identity, then the server MUST return the current 913 config ID for the running datastore, if the "source" parameter 914 identifies the running datastore. The server MAY maintain config IDs 915 for other datastores as well. 917 2.2.4. New Operations 919 The :config-id capability does not introduce any new protocol 920 operations. 922 2.2.5. Modifications to Existing Operations 924 The :config-id capability does not modify any existing protocol 925 operations. 927 2.2.6. Interactions with Other Capabilities 929 The :config-id capability does not interact with any other 930 capabilities. 932 2.3. "encoding" Capability 934 2.3.1. Overview 936 The :encoding capability is used by the client to request an 937 alternate message encoding be used instead of XML. The client and 938 server both send a list of media types for the message encodings they 939 support, encoded as a comma-separated list (with no whitespace). The 940 client list is an ordered by preference. The server list is 941 unordered. 943 +-----------+ +-----------+ +--------------+ 944 | | Client and | | | | 945 | | server select | | | | 946 | | protocol base | | | | 947 +-----------+ and encoding +-----------+ +--------------+ 949 Always encoded --- > Start encoding all messages 950 in XML w/base:1.0 in the selected encoding 951 message framing and message framing 953 Both the client and server will examine the others message 954 for the "encoding" URI. If not present, then the 955 default encoding is used, which is XML. 957 The client list is compared against the server list, checked in the 958 client specified order. If the same media type appears in the server 959 list, then that is the encoding that will be active for the remainder 960 of the session (i.e., starting with the first request). All 961 , , and messages MUST be encoded in 962 the negotiated encoding. 964 Both the client and server MUST support the "application/xml" media 965 type to be backward-compatible with [RFC6241]. 967 If "application/json" encoding is used, then the encoding defined in 968 [I-D.lhotka-netmod-json] MUST be used so namespaces will be properly 969 identified. Any metadata that needs to encoded MUST be encoded 970 according to the procedure defined in [RESTCONF], section 4.4. 972 The message framing used for the session is unaffected by this 973 capability. The "base1.0" vs. "base1.1" negotiation defined in 974 [RFC6241] determines the message framing that is used for the entire 975 session. 977 2.3.1.1. :encoding Capability Example 979 In this example, the client supports the following message encodings, 980 shown in the preferred order. 982 - Efficient XML Interchange (EXI) 983 - JSON 984 - XML 986 Some extra whitespace has been added for display purposes only. 988 # Client requests a new session with alternate encoding 989 # also requesting an abbreviated hello 990 991 992 urn:ietf:params:netconf:base:1.0 993 urn:ietf:params:netconf:base:1.1 994 995 urn:ietf:params:netconf:capability:capability-id:1.0?id=64ae3ffa 996 997 998 urn:ietf:params:netconf:capability:encoding:1.0? 999 types=application/exi,application/json,application/xml 1000 1001 1003 The server supports the following encodings: 1005 - XML 1006 - JSON 1008 Since the most preferred media type in common is "application/json", 1009 the JSON encoding used for the remainder of the session. 1011 In this example, the server sends an full message to the 1012 client, truncated for brevity. Extra whitespace has been added for 1013 display purposes only. 1015 # Server starts session 4 with JSON encoding 1016 1017 1018 urn:ietf:params:netconf:base:1.0 1019 urn:ietf:params:netconf:base:1.1 1020 1021 urn:ietf:params:netconf:capability:encoding:1.0? 1022 types=application/xml,application/json 1023 1024 1025 urn:ietf:params:netconf:capability:capability-id:1.0?id=64ae3ffa 1026 1027 1028 urn:ietf:params:netconf:capability:config-id?id=2130 1029 1030 1031 1032 4 1033 1035 At this point, both the client and server switch to JSON encoding: 1037 # client send a request 1038 { "ietf-netconf:rpc" : { 1039 "@message-id" : "201", 1040 "kill-session" : { 1041 "session-id" : 42 1042 } 1043 } 1044 } 1046 # server sends an reply 1047 { "ietf-netconf:rpc-reply" : { 1048 "@message-id" : "201", 1049 "ok" : [null] 1050 } 1051 } 1053 2.3.2. Dependencies 1055 The :encoding capability is not dependent on any other capabilities. 1057 2.3.3. Capability Identifier 1059 The :encoding capability is identified by the following capability 1060 string: 1062 urn:ietf:params:netconf:capability:encoding:1.0 1064 This capability MUST be advertised in every server message. 1065 The "encoding" capability URI MUST contain a "types" argument 1066 containing a comma-separated list of media types that represent the 1067 message encoding formats supported by the server. 1069 If the client supports the :encoding capability, it SHOULD include an 1070 "encoding" URI in its message. The client MAY 1071 omit this capability if XML encoding is desired. 1073 For example (line wrapped for display purposes only) 1075 urn:ietf:params:netconf:capability:encoding:1.0? 1076 types=application/json,application/xml 1078 2.3.4. New Operations 1080 The :encoding capability does not introduce any new protocol 1081 operations. 1083 2.3.5. Modifications to Existing Operations 1085 The :encoding capability does not modify any existing protocol 1086 operations. 1088 2.3.6. Interactions with Other Capabilities 1090 The :encoding capability does not interact with any other 1091 capabilities. 1093 2.4. Protocol Operation 1095 The operation is specified with a YANG "rpc" statement, 1096 defined in Section 2.8. This operation allows the entire NETCONF 1097 transaction procedure to be performed in a single operation or 1098 multiple operations, depending on the input parameters used. 1100 There are no XML attributes used (e.g., "operation" from RFC 6241, 1101 "insert", "value" from RFC 6020). Instead, configuration edits are 1102 specified with an edit list, using the YANG Patch mechanism defined 1103 in [RESTCONF]. This is used instead of a complete XML instance 1104 document, e.g. element, to represent an unordered patch list 1105 inferred from the diffs. (Although YANG Patch can be used in this 1106 mode if client wants to merge or replace the entire configuration 1107 datastore). 1109 2.4.1. Input 1111 o target: name of the configuration datastore being edited 1113 o target-resource: XPath node-set expression representing 1 or more 1114 target resources within the datastore to edit. 1116 o yang-patch: container of ordered edits to apply to the target 1117 resource(s). 1119 o test-only: flag to request that the edit request be validated but 1120 no edits should actually be applied 1122 o if-match: if the entity tag for the target resource(s) does not 1123 exactly match the supplied value then the edit request is 1124 rejected. 1126 o with-locking: if present then the server will provide exclusive 1127 write access to this operation and possible confirmed- 1128 commit procedure. 1130 o max-lock-wait: amount of time the client is willing to wait for 1131 locks to clear, if "with-locking" parameter is present. 1133 o activate-now: if present and the target is the candidate 1134 datastore, then an implicit operation will be performed 1135 if the edit operation is successfully applied. 1137 o nvstore-now: if present and the server supports the startup 1138 datastore, and the edits have been activated in the running 1139 datastore, then an implicit operation (from the 1140 running to the startup datastore) will be attempted by the server. 1142 o confirmed: request that a confirmed commit be started or extended. 1144 o confirm-timeout: the amount of time for the server to wait for an 1145 request that extends, a request to 1146 finish, or a request to cancel a confirmed commit 1147 procedure in progress. 1149 o persist: identifier string to use in the "persist-id" parameter to 1150 extend, complete, or cancel a confirmed commit procedure. 1152 o persist-id: identifier string to extend a confirmed commit 1153 procedure in progress. 1155 2.4.2. Output 1157 Positive Response: 1159 This operation returns data containing a "yang-patch-status" report 1160 (defined in [RESTCONF]) instead of an "ok" element. This report 1161 contains an "ok" element that is present if the entire operation 1162 succeeded. 1164 Error Response: 1166 The element can be returned, e.g., if the message 1167 contains invalid parameter syntax. The server MUST report editing 1168 errors in the "edit" list within the "yang-patch-status" container. 1170 2.4.3. YANG Tree Diagram 1172 Key: DRI = data-resource-identifier 1174 +---x edit2 1175 +--ro input 1176 | +--ro target 1177 | | +--ro (datastore-target) 1178 | | +--:(candidate) 1179 | | | +--ro candidate? empty 1180 | | +--:(running) 1181 | | +--ro running? empty 1182 | +--ro target-resource? yang:xpath1.0 1183 | +--ro yang-patch 1184 | | +--ro patch-id? string 1185 | | +--ro comment? string 1186 | | +--ro edit [edit-id] 1187 | | +--ro edit-id string 1188 | | +--ro operation enumeration 1189 | | +--ro target data-resource-identifier 1190 | | +--ro point? data-resource-identifier 1191 | | +--ro where? enumeration 1192 | | +--ro value 1193 | +--ro test-only? empty 1194 | +--ro if-match? yang-entity-tag 1195 | +--ro with-locking? empty 1196 | +--ro max-lock-wait? uint32 1197 | +--ro activate-now? empty 1198 | +--ro nvstore-now? empty 1199 | +--ro confirmed? empty 1200 | +--ro confirm-timeout? uint32 1201 | +--ro persist? string 1202 | +--ro persist-id? string 1203 +--ro output 1204 +--ro yang-patch-status 1205 +--ro patch-id? string 1206 +--ro (global-status)? 1207 | +--:(global-errors) 1208 | | +--ro errors 1209 | | +--ro error 1210 | | +--ro error-type enumeration 1211 | | +--ro error-tag string 1212 | | +--ro error-app-tag? string 1213 | | +--ro error-path? DRI 1214 | | +--ro error-message? string 1215 | | +--ro error-info 1216 | | 1217 | +--:(ok) 1218 | +--ro ok? empty 1219 +--ro edit-status 1220 +--ro edit [edit-id] 1221 +--ro edit-id string 1222 +--ro (edit-status-choice)? 1223 +--:(ok) 1224 | +--ro ok? empty 1225 +--:(location) 1226 | +--ro location? inet:uri 1227 +--:(errors) 1228 +--ro errors 1229 +--ro error 1230 +--ro error-type enumeration 1231 +--ro error-tag string 1232 +--ro error-app-tag? string 1233 +--ro error-path? DRI 1234 +--ro error-message? string 1235 +--ro error-info 1237 2.4.4. Example 1239 In this example, an "all-in-one" YANG Patch edit is shown. the 1240 following conditions apply: 1242 - The server supports the :candidate and :startup capabilities 1243 - The "example-ex" YANG module is supported by the server 1245 The starting state of the "/forests" data structure is described in 1246 Appendix B.2. The client is adding an "oak" tree and changing the 1247 location of the "birch" tree in the "north" forest. 1249 1251 1253 1254 1255 /ex:forests/ex:forest[ex:name='north'] 1256 1257 1258 north-forest-patch 1259 1260 Add an oak tree and change location of the birch tree 1261 1262 1263 oak 1264 create 1265 /ex:trees 1266 1267 1268 oak 1269 hillside 1270 1271 1272 1273 1274 birch 1275 merge 1276 /ex:trees/ex:tree/birch 1277 1278 west valley 1279 1280 1281 1282 1283 1284 1285 1287 The edit succeeds, and the "yang-patch-status" container is returned 1288 to the client with the path expression of the new palm 1289 tree resource, and status for the birch tree edit: 1291 1293 1296 north-forest patch 1297 1298 1299 1300 oak 1301 1302 /ex:forests/ex:forest/north/ex:trees/ex:tree/oak 1303 1304 1305 1306 birch 1307 1308 1309 1310 1311 1313 Refer to Appendix B.3 for additional protocol operation 1314 examples. 1316 2.5. Operation 1318 A new NETCONF protocol operation called is defined 1319 to complete a confirmed commit procedure. 1321 2.5.1. Input 1323 There is one optional parameter for this protocol operation: 1325 o persist-id: an identifier string that MUST match the "persist" 1326 value, if it was used in the confirmed-commit procedure. 1328 2.5.2. Output 1330 Positive Response: 1332 The there is a confirmed-commit procedure in progress and it is 1333 successfully completed, then an element is returned. 1335 Negative Response: An response is sent if the request 1336 cannot be completed for any reason. 1338 2.5.3. YANG Tree Diagram 1340 +---x complete-commit 1341 +--ro input 1342 +--ro persist-id? string 1344 2.5.4. Example 1346 In this example, the client has previously started a confirmed commit 1347 procedure using the "persist" parameter set to the value "abcdef". 1349 1351 1353 abcdef 1354 1355 1357 1359 1360 1362 2.6. Operation 1364 A new NETCONF protocol operation called is defined to 1365 cancel a confirmed commit procedure and revert the running datastore. 1366 The operation in [RFC6241] cannot be used because it 1367 requires the implementation of the candidate capability. 1369 2.6.1. Input 1371 There is one optional parameter for this protocol operation: 1373 o persist-id: an identifier string that MUST match the "persist" 1374 value, if it was used in the confirmed-commit procedure. 1376 2.6.2. Output 1378 Positive Response: 1380 If there is a confirmed-commit procedure in progress and it is 1381 successfully cancelled, and the running datastore successfully 1382 reverted, then an element is returned. 1384 Negative Response: An response is sent if the request 1385 cannot be completed for any reason. 1387 2.6.3. YANG Tree Diagram 1389 +---x revert-commit 1390 +--ro input 1391 +--ro persist-id? string 1393 2.6.4. Example 1395 In this example, the client has previously started a confirmed commit 1396 procedure using the "persist" parameter set to the value "abcdef". 1398 1400 1402 abcdef 1403 1404 1406 1408 1409 1411 2.7. Protocol Operation 1413 The operation is specified with a YANG "rpc" statement, 1414 defined in Section 2.8. A specific datastore is selected for the 1415 source of the retrieval operation. Several different types of 1416 filters are provided. Filters are combined in a conceptual 1417 "logical-AND" operation, and are optional to use by the client. Not 1418 all filtering mechanisms are mandatory-to-implement for the server. 1420 2.7.1. Depth Filters 1422 A depth filter indicates how many subtree levels should be returned 1423 in the . This filter is specified with the "depth" input 1424 parameter for the protocol operation. The default "0" 1425 indicates that all levels from the requested subtrees should be 1426 returned. 1428 A new level is started for each YANG data node within the requested 1429 subtree. All top level data nodes are considered to be child nodes 1430 (level 1) of a conceptual root. 1432 If no content filters are provided, then level 1 is considered to 1433 include all top-level data nodes within the source datastore. 1434 Otherwise only the levels in selected subtrees will be considered, 1435 and not any additional top-level data nodes. 1437 If the depth requested is equal to "1", then only the requested data 1438 nodes (or top-level data nodes) will be returned. This mechanism can 1439 be used to detect the existence of containers and list entries within 1440 a particular subtree, without returning any of the descendant nodes. 1442 Higher depth values indicates the number of descendant nodes to 1443 include in the response. For example, if the depth requested is 1444 equal to "2", then only the requested data nodes (or top-level data 1445 nodes) and their immediate child data nodes will be returned. 1447 2.7.2. Time Filters 1449 A time filter specifies that data should only be returned if the 1450 last-modified timestamp for the target datastore is more recent than 1451 the timestamp specified in the "if-modified-since" parameter. 1453 If this feature is supported, then the server will maintain a 1454 "last-modified" timestamp for the running datastore. The server MAY 1455 support additional nested timestamps for data nodes within the 1456 datastore. The server MAY support timestamps for other datastores. 1458 When a request containing the "if-modified-since" parameter is 1459 received, the server will compare that timestamp to the 1460 "last-modified" timestamp for the source datastore. If it is greater 1461 than the specified value then data may be returned (depending on 1462 other filters). If the datastore timestamp value is less than or 1463 equal to the specified value, then an empty element will be 1464 returned in the . 1466 If the "full-delta" parameter is present, and the server maintains 1467 "last-modified" timestamps for any data nodes within the source 1468 datastore, then the same type of comparison will be done for the data 1469 node to determine if it should be included in the response. If no 1470 "last-modified" timestamp is maintained for a data node, then the 1471 server will use the "last-modified" timestamp for its nearest 1472 ancestor, or for the datastore itself if there are none. 1474 2.7.3. Input 1476 o source: A container indicating the conceptual datastore for the 1477 retrieval request. 1479 o filter-spec: A choice indicating the content filter specification 1480 for the retrieval request. 1482 o keys-only: A leaf indicating that only the key leafs, combined 1483 with other filtering criteria, should be returned. 1485 o if-modified-since: A leaf indicating the time filter specification 1486 for the retrieval request, according to the procedures in 1487 Section 2.7.2. 1489 o full-delta: If present and the "if-modified-since" parameter is 1490 also present, then the entire datastore will be filtered by last 1491 modification time, not just the entire datastore. 1493 o depth: A leaf indicating the subtree depth level for the retrieval 1494 request, according to the procedures in Section 2.7.1. 1496 o with-defaults: A leaf indicating the type of defaults handling 1497 requested, according to procedures in [RFC6243]. 1499 o with-metadata: A leaf-list indicating the specific metadata that 1500 the server should add to the response, such as "last-modified" or 1501 "etag", encoded in XML according to the schema in Section 2.9. 1503 o with-locking: if present then the server will provide exclusive 1504 write access to this operation so the target datastore is 1505 not modified during the entire retrieval operation. 1507 o max-lock-wait: amount of time the client is willing to wait for 1508 locks to clear, if "with-locking" parameter is present. 1510 2.7.4. Output 1512 Positive Response: A element is returned which contains the 1513 data corresponding to the input parameters specified in the request. 1514 The child nodes of the container correspond to top-level YANG 1515 data nodes. 1517 If the server supports the "timestamps" YANG feature, and the target 1518 is the running datastore, then a "last-modified" attribute SHOULD be 1519 included in the element. 1521 Negative Response: An response is sent if the request 1522 cannot be completed for any reason. 1524 2.7.5. YANG Tree Diagram 1526 +---x get2 1527 +--ro input 1528 | +--ro source 1529 | | +--ro (datastore-source)? 1530 | | +--:(candidate) 1531 | | | +--ro candidate? empty 1532 | | +--:(running) 1533 | | | +--ro running? empty 1534 | | +--:(startup) 1535 | | | +--ro startup? empty 1536 | | +--:(url) 1537 | | | +--ro url? inet:uri 1538 | | +--:(operational) 1539 | | +--ro operational? empty 1540 | +--ro (filter-spec)? 1541 | | +--:(subtree-filter) 1542 | | | +--ro subtree-filter 1543 | | +--:(xpath-filter) 1544 | | +--ro xpath-filter? yang:xpath1.0 1545 | +--ro keys-only? empty 1546 | +--ro if-modified-since? yang:date-and-time 1547 | +--ro full-delta? empty 1548 | +--ro depth? uint32 1549 | +--ro with-defaults? with-defaults-mode 1550 | +--ro with-metadata* identityref 1551 | +--ro with-locking? empty 1552 | +--ro max-lock-wait? uint32 1553 +--ro output 1554 +--ro data 1556 2.7.6. Example 1558 In this example, the retrieval the "forests" resource is shown. the 1559 following conditions apply: 1561 - The server supports the :candidate and :startup capabilities 1562 - The "example-ex" YANG module is supported by the server 1564 The starting state of the "/forests" data structure is described in 1565 Appendix B.2. The client is retrieving just the "forests" node, 1566 along with the "last-modified" and "etag" metadata for that node. 1567 The "config-id" for the datastore is also requested. Locking is 1568 requested (with a maximum lock wait time of 5 seconds), just to make 1569 sure the metadata does not change during the request. 1571 1573 1575 1576 1577 1578 1 1579 ncex:timestamps 1580 ncex:etags 1581 ncex:config-id 1582 1583 5 1584 1585 1587 The server has a "forests" node so this node is returned along with 1588 the requested metadata for the node. Note that the XML namespace for 1589 the "ncex" metadata is the XSD target namespace defined in 1590 Section 2.9, not the YANG namespace URI defined in Section 2.8. 1592 1594 1598 1601 1602 1604 Refer to Appendix B.4 for additional protocol operation 1605 examples. 1607 2.8. NETCONF-EX YANG Module 1609 This module imports the "with-defaults-parameters" grouping from 1610 [RFC6243]. 1612 Several YANG features are imported from [RFC6241]. These correspond 1613 to the NETCONF capabilities (e.g., candidate, url, startup, xpath) 1614 but defined as YANG features instead of URIs. 1616 Some data types are imported from [RFC6991]: 1618 - date-and-time 1619 - uri 1620 - xpath1.0 1622 Several YANG groupings are imported from [RESTCONF]: 1624 - errors 1625 - yang-patch 1626 - pang-patch-status 1628 Two notifications are augmented from [RFC6470]. 1630 - netconf-capability-change 1631 - netconf-configuration-change 1633 RFC Ed.: update the date below with the date of RFC publication and 1634 remove this note. 1636 file "ietf-netconf-ex@2013-10-19.yang" 1638 module ietf-netconf-ex { 1640 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-ex"; 1641 prefix ncex; 1643 import ietf-inet-types { 1644 prefix inet; 1645 } 1647 import ietf-netconf { 1648 prefix nc; 1649 } 1651 import ietf-netconf-notifications { 1652 prefix ncn; 1653 } 1655 import ietf-netconf-with-defaults { 1656 prefix ncwd; 1657 } 1659 import ietf-restconf { 1660 prefix rc; 1661 } 1663 import ietf-yang-types { 1664 prefix yang; 1665 } 1666 organization 1667 "IETF NETCONF (Network Configuration Protocol) Working Group"; 1669 contact 1670 "WG Web: 1671 WG List: 1673 WG Chair: Mehmet Ersue 1674 1676 WG Chair: Bert Wijnen 1677 1679 Editor: Andy Bierman 1680 "; 1682 description 1683 "This module contains a collection of YANG definitions for the 1684 efficient operation of a NETCONF server. Protocol operations 1685 are defined to reduce network usage and transaction complexity. 1687 Copyright (c) 2013 IETF Trust and the persons identified as 1688 authors of the code. All rights reserved. 1690 Redistribution and use in source and binary forms, with or 1691 without modification, is permitted pursuant to, and subject 1692 to the license terms contained in, the Simplified BSD License 1693 set forth in Section 4.c of the IETF Trust's Legal Provisions 1694 Relating to IETF Documents 1695 (http://trustee.ietf.org/license-info). 1697 This version of this YANG module is part of RFC XXXX; see 1698 the RFC itself for full legal notices."; 1700 // RFC Ed.: replace XXXX with actual RFC number and remove this 1701 // note. 1703 // RFC Ed.: remove this note 1704 // Note: extracted from 1705 // draft-bierman-netconf-efficiency-extensions-00.txt 1707 // RFC Ed.: update the date below with the date of RFC publication 1708 // and remove this note. 1709 revision "2013-10-19" { 1710 description 1711 "Initial revision. operation originally published 1712 in draft-bierman-netconf-get2-03.txt"; 1713 reference 1714 "RFC XXXX: NETCONF Efficiency Extensions"; 1715 } 1717 /* Features */ 1719 feature timestamps { 1720 description 1721 "This feature indicates that the server implements 1722 the operations parameters which require 1723 last modification timestamps to be maintained by 1724 the server. 1726 If this feature is advertised then one global 1727 'last-modified' timestamp for the entire 1728 running configuration datastore MUST be supported. 1730 The server MAY support additional timestamps 1731 for additional datastores and data nodes 1732 within a datastore. The 'with-metadata' 1733 parameter can be used to identify 1734 which data nodes support a 'last-modified' 1735 timestamp."; 1736 } 1738 feature with-defaults { 1739 description 1740 "This feature indicates that the server supports the 1741 'with-defaults' parameter for the operation. 1742 A NETCONF server SHOULD support this feature."; 1743 reference 1744 "RFC 6243: With-defaults Capability for NETCONF"; 1745 } 1747 feature confirmed-edit { 1748 description 1749 "This feature indicates that the server supports the 1750 confirmed commit procedure for the protocol 1751 operation."; 1752 } 1754 /* Identities */ 1756 identity metadata { 1757 description 1758 "Base for all metadata identifiers used by the 1759 'with-metadata' parameter in the operation."; 1761 } 1763 identity timestamps { 1764 base metadata; 1765 description 1766 "Describes metadata identifying the last modification 1767 time of the associated datastore or data resource."; 1768 } 1770 identity etags { 1771 base metadata; 1772 description 1773 "Describes metadata identifying the entity tag value 1774 of the associated datastore or data resource."; 1775 } 1777 identity config-id { 1778 base metadata; 1779 description 1780 "Describes metadata identifying the config ID 1781 of the associated datastore or data resource."; 1782 } 1784 /* Typedefs */ 1786 typedef yang-entity-tag { 1787 type string; 1788 description 1789 "Contains an opaque string representing a specific instance 1790 of a datastore or data resource. A client can use this 1791 string for equality comparisons between yang-entity-tag 1792 values. 1794 If any configuration data node values changes, or the 1795 relative order of any user-ordered data changes, then 1796 the server MUST change the entity tag value for the 1797 running datastore to a different value. If the server 1798 maintains entity-tag values for configuration data nodes, 1799 then the server MUST change the yang-entity-tag value for 1800 any affected data node. 1802 Only yang-entity-tag values for the same target resource 1803 instance can be compared. Only the 'strong entity tag' 1804 form is required. A server MAY support the 'weak 1805 entity tag' form. If so, then 2 YANG data node resource 1806 instances are considered to be equivalent if they 1807 contain the same value subtrees and all user-ordered 1808 data nodes share the same relative order."; 1809 reference 1810 "RFC 2616, section 3.11."; 1811 } 1813 /* Groupings */ 1815 grouping lock-parms { 1816 description 1817 "Common parameters to control datastore locking."; 1819 leaf with-locking { 1820 type empty; 1821 description 1822 "If this parameter is present then the request MUST be 1823 performed with exclusive write access to all datastores 1824 involved in the operation. An 'operation-not-supported' 1825 error-tag value is returned if the target datastore for 1826 the operation does not support locking (e.g., 'url' or 1827 'operational'). 1829 If the server cannot provide exclusive write access 1830 for the entire requested operation then an 'in-use' 1831 error-tag value is returned. 1833 If the 'max-lock-wait' parameter is also present then 1834 the server MAY choose to wait up to that amount of 1835 time attempting to obtain exclusive write access, 1836 before returning an error."; 1837 } 1839 leaf max-lock-wait { 1840 when "../with-locking" { 1841 description 1842 "Only relevant if locking is requested."; 1843 } 1844 type uint32 { 1845 range "1 .. 600"; 1846 } 1847 units seconds; 1848 description 1849 "If this parameter is present and the 'with-locking' 1850 parameter is also present, then the server MAY wait 1851 up to the specified number of seconds attempting 1852 to obtain exclusive write access for the requested 1853 operation."; 1854 } 1856 } 1858 /* Protocol Operations */ 1860 rpc get2 { 1861 description 1862 "Retrieve NETCONF datastore information"; 1863 input { 1864 container source { 1865 description 1866 "The datastore (or non-configuration data) 1867 to use for the source for the retrieval operation."; 1869 choice datastore-source { 1870 default running; 1871 description 1872 "The configuration source for the retrieval operation. 1873 The running configuration is the default choice if 1874 this parameter is not present."; 1875 leaf candidate { 1876 if-feature nc:candidate; 1877 type empty; 1878 description 1879 "The candidate configuration datastore is the 1880 retrieval source."; 1881 } 1882 leaf running { 1883 type empty; 1884 description 1885 "The running configuration datastore is the 1886 retrieval source."; 1887 } 1888 leaf startup { 1889 if-feature nc:startup; 1890 type empty; 1891 description 1892 "The startup configuration datastore is the 1893 retrieval source."; 1894 } 1895 leaf url { 1896 if-feature nc:url; 1897 type inet:uri; 1898 description 1899 "The URL-based configuration is the 1900 retrieval source."; 1901 } 1902 leaf operational { 1903 type empty; 1904 description 1905 "The retrieval source is the collection of all 1906 operational (non-configuration) data nodes supported 1907 by the server. 1909 Any ancestor container and/or list and list key nodes 1910 are also returned. No other leafs or leaf-lists will 1911 be included in the reply. 1913 The server MAY return ancestor container, and/or list 1914 and list key nodes that do not contain any 1915 non-configuration nodes. This can occur for several 1916 reasons, e.g., the implementation streams replies 1917 and cannot defer instrumentation or access control 1918 filtering of descendant data nodes."; 1919 } 1920 } 1921 } 1923 choice filter-spec { 1924 description 1925 "The content filter specification for this request"; 1927 anyxml subtree-filter { 1928 description 1929 "This parameter identifies the portions of the 1930 target datastore to retrieve."; 1931 reference "RFC 6241, Section 6."; 1932 } 1933 leaf xpath-filter { 1934 if-feature nc:xpath; 1935 type yang:xpath1.0; 1936 description 1937 "This parameter contains an XPath expression 1938 identifying the portions of the target 1939 datastore to retrieve."; 1940 } 1941 } 1943 leaf keys-only { 1944 type empty; 1945 description 1946 "This parameter selects only data nodes which 1947 are key leaf nodes. Parent container and 1948 list nodes are also returned, but no other leafs, 1949 or any leaf-lists will be included in the reply."; 1950 } 1951 leaf if-modified-since { 1952 if-feature timestamps; 1953 type yang:date-and-time; 1954 description 1955 "This parameter selects the target datastore 1956 only if the last-modified timestamp for the 1957 datastore is more recent than the specified time. 1958 If not, then an empty element is returned. 1960 If the target datastore does not maintain a 1961 last-modified timestamp, then this parameter is 1962 ignored."; 1963 } 1965 leaf full-delta { 1966 if-feature timestamps; 1967 type empty; 1968 description 1969 "This parameter selects only data nodes which 1970 have been modified since the specified time. 1971 It is ignored unless the 'if-modified-since' 1972 parameter is also provided and the target datastore 1973 supports a last-modified timestamp."; 1974 } 1976 leaf depth { 1977 type uint32; 1978 default 0; 1979 description 1980 "This parameter selects how many conceptual 1981 sub-tree levels should be returned in the 1982 . 1984 If this parameter is equal to '0', then entire 1985 subtrees will be returned. 1987 If this parameter is greater than '0', then 1988 only the specified number of subtree levels will 1989 be returned."; 1990 } 1992 uses ncwd:with-defaults-parameters { 1993 if-feature with-defaults; 1994 description 1995 "This parameter controls the retrieval of 1996 default values."; 1997 reference 1998 "RFC 6243: With-defaults Capability for NETCONF"; 2000 } 2002 leaf-list with-metadata { 2003 type identityref { 2004 base metadata; 2005 } 2006 description 2007 "This parameter will cause the server to return 2008 metadata in the (e.g. as XML attributes 2009 in XML encoding) associated with the specified 2010 metadata identity. If the server does not support 2011 any specified metadata identifier, then the 2012 operation fails with an 'invalid-value' error."; 2013 } 2015 uses lock-parms { 2016 description 2017 "Exclusive write access can be requested to 2018 ensure that no other sessions modify the 2019 configuration data during the retrieval operation"; 2020 } 2022 } 2024 output { 2025 anyxml data { 2026 description 2027 "Copy of the requested datastore subset which 2028 matched the filter criteria (if any). 2029 An empty data container indicates that the 2030 request did not produce any results."; 2031 } 2032 } 2033 } 2035 rpc edit2 { 2036 description 2037 "Edit NETCONF datastore contents. 2038 All operations requested in the yang-patch edit list 2039 are applied, or the target datastore is left unchanged."; 2041 input { 2042 container target { 2043 description 2044 "The datastore to use as the target for this 2045 edit operation."; 2047 choice datastore-target { 2048 mandatory true; 2049 description 2050 "The configuration target for the edit operation."; 2052 leaf candidate { 2053 if-feature nc:candidate; 2054 type empty; 2055 description 2056 "The candidate configuration datastore is the 2057 edit target."; 2058 } 2059 leaf running { 2060 if-feature nc:writable-running; 2061 type empty; 2062 description 2063 "The running configuration datastore is the 2064 edit target."; 2065 } 2066 } 2067 } 2069 leaf target-resource { 2070 if-feature nc:xpath; 2071 type yang:xpath1.0; 2072 description 2073 "This parameter identifies 1 or more data node 2074 instances for which the yang-patch edits 2075 will be applied. The target-resource expression 2076 MUST evaluate to a node-set result. 2078 Each operation in the yang-patch edit list will 2079 be applied to each target-resource instance, as if 2080 it were the document root for the operation. 2082 If multiple instances are represented by the 2083 target-resource value, then the server will apply 2084 all edits to all instances. If any errors occur, 2085 then all edits from this request will be undone 2086 from the target datastore. 2088 The user MUST have appropriate write permissions for 2089 all data accessed by every operation within the edit 2090 list. 2092 If this parameter is not present or not supported 2093 then the target resource is the root node of the 2094 datastore identified by the 'target' parameter."; 2096 } 2098 uses rc:yang-patch { 2099 description 2100 "The yang-patch parameter contains the ordered list 2101 of edits to perform on the target resource(s). 2103 The conceptual document root for the 'target' 2104 parameter is defined to be the value of a data node 2105 represented by the 'target-resource' parameter or the 2106 target datastore conceptual root node if that parameter 2107 is not present."; 2108 } 2110 leaf test-only { 2111 type empty; 2112 description 2113 "If this parameter is present the server will not 2114 actually perform the requested edits. Instead the 2115 edit request will be validated as if it were going 2116 to be applied. Any parameter errors or datastore 2117 validation errors SHOULD be reported in the response. 2119 No attempt to apply, activate the edits or save them 2120 in non-volatile storage will be made if this parameter 2121 is present."; 2122 } 2124 leaf if-match { 2125 type yang-entity-tag; 2126 description 2127 "If this parameter is set, then the entire edit request 2128 will be rejected unless the entity tag for the target 2129 resource matches this value. An rpc-error with 2130 an 'operation-failed' error-tag value MUST returned, 2131 and the edit operation MUST NOT be attempted. 2132 The 'error-app-tag' field SHOULD be set to 2133 'precondition-failed'. 2135 If the target datastore does not maintain a 2136 last-modified timestamp, then this parameter is 2137 ignored."; 2138 } 2140 uses lock-parms { 2141 description 2142 "Exclusive write access can be requested to 2143 ensure that no other sessions modify the 2144 configuration data during the edit operation 2145 and possibly the entire confirmed commit procedure. 2147 If the 'with-locking' parameter is used to start or 2148 extend a confirmed commit procedure, then the 2149 exclusive write access will be maintained until the 2150 confirmed commit procedure terminates somehow. 2152 If the 'with-locking' parameter is used for a 2153 plain edit operation, then exclusive write access 2154 will be maintained until this operation has completed."; 2155 } 2157 leaf activate-now { 2158 type empty; 2159 description 2160 "If present and the edit operation succeeds, 2161 then the server will activate the configuration 2162 changes right away. The server will conceptually 2163 perform a operation after the edit 2164 operation. The user MUST have execute 2165 permission for the operation or 2166 the operation fails with an 'access-denied' error. 2168 This parameter has no affect unless the 2169 'datasource-target' choice is the 'candidate' leaf."; 2170 } 2172 leaf nvstore-now { 2173 type empty; 2174 description 2175 "If present and the edit operation succeeds, 2176 and the configuration changes are activated 2177 in the running datastore, then the server 2178 will persist the configuration changes right away 2179 in non-volatile store. The server will conceptually 2180 perform a operation from the running 2181 to the startup datastore. The user MUST have execute 2182 permission for the operation or 2183 the operation fails with an 'access-denied' error. 2185 This parameter has no affect unless the 2186 'startup' capability is supported by the server."; 2187 } 2189 leaf confirmed { 2190 if-feature confirmed-edit; 2191 type empty; 2192 description 2193 "If the requested edit operation succeeds and the 2194 configuration changes are applied to the running 2195 datastore, then a confirmed commit procedure is 2196 requested by the client. 2198 A confirmed commit procedure is an operation 2199 that contains this parameter. The 2200 operation is used to complete the confirmed commit 2201 procedure. The operation is used 2202 to cancel the confirmed commit procedure and 2203 revert the running datastore back to the contents 2204 before the first confirmed commit operation. 2206 If no or operation 2207 is invoked within the timeout interval then 2208 the server will revert the running datastore 2209 back to the contents before the first confirmed 2210 edit operation. 2212 This is the same as the confirmed commit procedure 2213 in RFC 6241 except the candidate capability is 2214 not required. 2216 The server will save the running datastore contents 2217 before the edit operation is activated, if there 2218 is no confirmed edit already in progress. 2220 If the 'with-locking' parameter is present then 2221 the server will maintain exclusive write access 2222 for the specified session until the confirmed 2223 edit procedure is completed somehow."; 2224 reference 2225 "RFC 6241, Section 8.3.4.1"; 2226 } 2228 leaf confirm-timeout { 2229 when "../confirmed" { 2230 description 2231 "Only relevant if the parameter is present"; 2232 } 2233 if-feature confirmed-edit; 2234 type uint32 { 2235 range "1..max"; 2236 } 2237 units "seconds"; 2238 default "600"; // 10 minutes 2239 description 2240 "The timeout interval for a confirmed edit procedure. 2241 If exclusive write access was granted for this confirmed 2242 commit procedure, then it is removed if the timeout 2243 occurs and the confirmed commit procedure is terminated."; 2245 reference "RFC 6241, Section 8.3.4.1"; 2246 } 2248 leaf persist { 2249 if-feature confirmed-edit; 2250 type string; 2251 description 2252 "This parameter is used to make a confirmed commit 2253 procedure persistent. A persistent confirmed commit 2254 is not aborted if the NETCONF session terminates. 2255 The only way to abort a persistent confirmed commit 2256 is to let the timer expire, or to use the 2257 operation. 2259 The value of this parameter is a token that MUST be 2260 given in the 'persist-id' parameter of the , 2261 , or operations in 2262 order to extend, confirm, or cancel the persistent 2263 confirmed commit procedure. 2265 The token SHOULD be a random string."; 2266 reference "RFC 6241, Section 8.3.4.1"; 2267 } 2269 leaf persist-id { 2270 if-feature confirmed-edit; 2271 type string; 2272 description 2273 "This parameter is given in order to extend a persistent 2274 confirmed edit. The value must be equal to the value 2275 given in the 'persist' parameter to the 2276 operation. If it does not match, the operation fails 2277 with an 'invalid-value' error."; 2278 reference "RFC 6241, Section 8.3.4.1"; 2279 } 2280 } 2282 output { 2283 uses rc:yang-patch-status; 2284 } 2285 } 2286 rpc complete-commit { 2287 if-feature confirmed-edit; 2288 description 2289 "This operation is used to complete an ongoing confirmed 2290 commit procedure. If exclusive write access was granted 2291 for this confirmed commit procedure, then it is removed 2292 if this operation is successfully completed. 2294 If the confirmed commit is persistent, the parameter 2295 'persist-id' MUST be given, and it MUST match the value of 2296 the 'persist' parameter given in the operation. 2297 If not confirmed commit procedure is in progress then 2298 the operation fails with an 'operation-failed' error."; 2299 reference "RFC 6241, Section 8.4.5.1"; 2301 input { 2302 leaf persist-id { 2303 type string; 2304 description 2305 "This parameter is given in order to complete a 2306 persistent confirmed commit procedure. The 2307 value MUST be equal to the value given in the 2308 'persist' parameter to the operation. 2309 If it does not match, the operation fails with 2310 an 'invalid-value' error."; 2311 } 2312 } 2313 } 2315 rpc revert-commit { 2316 if-feature confirmed-edit; 2317 description 2318 "This operation is used to cancel an ongoing confirmed commit. 2319 If exclusive write access was granted for this confirmed 2320 commit procedure, then it is removed if this operation 2321 is successfully completed. 2323 If the confirmed commit is persistent, the parameter 2324 'persist-id' MUST be given, and it MUST match the value of 2325 the 'persist' parameter. If not confirmed commit 2326 procedure is in progress then the operation fails 2327 with an 'operation-failed' error."; 2328 reference "RFC 6241, Section 8.4.4.1"; 2330 input { 2331 leaf persist-id { 2332 type string; 2333 description 2334 "This parameter is given in order to cancel a persistent 2335 confirmed commit and revert the running configuration 2336 datastore to its state before the confirmed commit 2337 procedure started. The value MUST be equal to the value 2338 given in the 'persist' parameter to the 2339 operation. 2341 If it does not match, the operation fails with an 2342 'invalid-value' error."; 2343 } 2344 } 2345 } 2347 /* Notifications */ 2349 augment /ncn:netconf-capability-change { 2350 description 2351 "Add the updated capability-id capability value 2352 to a capability change event."; 2354 leaf capability-id { 2355 type string; 2356 description 2357 "Contains the new capability ID for the server, 2358 representing the capability set after the 2359 capability changes."; 2360 } 2361 } 2363 augment /ncn:netconf-config-change { 2364 description 2365 "Add the updated config-id capability value 2366 to a configuration change event."; 2368 leaf config-id { 2369 type string; 2370 description 2371 "Contains the new configuration ID for the 2372 running datastore on the server, representing 2373 the datastore after the configuration changes."; 2374 } 2375 } 2377 } 2378 2380 2.9. XSD for NETCONF-EX Metadata 2382 The following XML Schema document [XSD] defines the "last-modified" 2383 and "etag" attributes, described within this document. The 2384 "last-modified" attribute is only relevant if the server supports the 2385 "timestamps" YANG feature within the "ietf-netconf-ex" YANG module. 2387 The "last-modified" attribute uses the XSD data type "dateTime", in 2388 accordance with Section 3.2.7.1 of XML Schema Part 2: Datatypes. 2389 This is equivalent to the YANG data type "date-and-time". 2391 The "etag" attribute uses the XSD data type "string", in accordance 2392 with the "yang-entity-tag" YANG typedef defined in Section 2.8. 2394 The "config-id" attribute uses the XSD data type "string". 2396 file "netconf-ex.xsd" 2398 2399 2406 2407 2408 This schema defines the syntax for the "last-modified" 2409 and "etag" attributes described within this document. 2410 2411 2413 2416 2417 2418 2419 This attribute indicates the current config ID 2420 for the running configuration datastore, 2421 corresponding to the XML element containing this attribute. 2422 2423 2424 2425 2428 2429 2430 2431 This attribute indicates the date and time when 2432 a modification was last detected by the server 2433 for the datastore or data node corresponding to 2434 the XML element containing this attribute. 2435 2436 2437 2439 2442 2443 2444 2445 This attribute indicates the entity tag 2446 for the datastore or data node corresponding to 2447 the XML element containing this attribute. 2448 2449 2450 2452 2454 2456 3. IANA Considerations 2458 3.1. NETCONF-EX XML Namespace 2460 This document registers a URI in the IETF XML registry [RFC3688]. 2461 Following the format in RFC 3688, the following registration is 2462 requested: 2464 URI: urn:ietf:params:xml:ns:netconf:netconf-ex:1.0 2465 Registrant Contact: The NETCONF WG of the IETF. 2466 XML: N/A, the requested URI is an XML namespace. 2468 3.2. NETCONF-EX XML Schema 2470 This document registers a URI for the NETCONF XML schema in the IETF 2471 XML registry [RFC3688]. 2473 // RFC Ed. remove this line and uncomment next line when published 2474 //IANA has updated the following URI to reference this document. 2476 URI: urn:ietf:params:xml:schema:netconf-ex 2478 3.3. NETCONF-EX YANG Module 2480 This document registers 1 YANG module in the YANG Module Names 2481 registry [RFC6020]. 2483 name: ietf-netconf-ex 2484 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-ex 2485 prefix: ncex 2486 // RFC Ed. remove this line and replace XXXX in next line 2487 reference: RFC XXXX 2489 4. Security Considerations 2491 This document does not introduce any new security concerns in 2492 addition to those specified in [RFC6241], section 9. 2494 5. Normative References 2496 [I-D.lhotka-netmod-json] 2497 Lhotka, L., "Modeling JSON Text with YANG", 2498 draft-lhotka-netmod-yang-json-02 (work in progress), 2499 September 2013. 2501 [JSON] Bray, T., Ed., "The JSON Data Interchange Format", 2502 draft-ietf-json-rfc4627bis-03 (work in progress), 2503 September 2013. 2505 [RESTCONF] 2506 Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, 2507 "RESTCONF Protocol", draft-bierman-netconf-restconf-02 2508 (work in progress), October 2013. 2510 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2511 Requirement Levels", BCP 14, RFC 2119, March 1997. 2513 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2514 January 2004. 2516 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2517 Network Configuration Protocol (NETCONF)", RFC 6020, 2518 October 2010. 2520 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2521 and A. Bierman, Ed., "Network Configuration Protocol 2522 (NETCONF)", RFC 6241, June 2011. 2524 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 2525 NETCONF", RFC 6243, June 2011. 2527 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2528 Base Notifications", RFC 6470, February 2012. 2530 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2531 July 2013. 2533 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 2534 Version 1.0", World Wide Web Consortium 2535 Recommendation REC-xpath-19991116, November 1999, 2536 . 2538 [XSD] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 2539 Second Edition", World Wide Web Consortium 2540 Recommendation REC-xmlschema-2-20041028, October 2004, 2541 . 2543 Appendix A. Open Issues 2545 A.1. resource-identifier-type 2547 The resource-identifier-type typedef from yang-patch is a RESTCONF 2548 path expression, not an XPath path expression. The error-path 2549 parameter also uses RESTCONF path strings. Should either or both of 2550 these be XPath instead? 2552 A.2. no YANG for top-level message nodes 2554 The YANG module of the node is needed for JSON encoding, but there is 2555 no YANG schema definition for the , , or 2556 elements. The namespace for and is 2557 "ietf-netconf", but no module name at all exists for the 2558 element. 2560 A.3. only 1 location returned per edit 2562 The bulk edit mode of can allow multiple sub-resources to be 2563 created at once. YANG Patch does not support bulk editing, so only 2564 one "location" leaf is allowed to be returned in the 2565 "yang-patch-status" response for a bulk edit 2567 A.4. config-id attribute 2569 Should the "config-id" (etag for the running datastore root) be 2570 returned in every response or only if requested? (Currently 2571 only if requested.) 2573 A.5. nodeset retrieval 2575 Should there be a retrieval mode for where only the nodes in 2576 an XPath node-set are returned? NETCONF returns all ancestor nodes 2577 and all ancestor or sibling key leafs as well. Sometime the XPath 2578 designer knows the context of the result node-set (e.g. path 2579 expression for 1 instance of a nested list). The XML scaffolding can 2580 add a lot of extra bytes to the . 2582 Appendix B. Additional Examples 2584 B.1. YANG Module Used in Examples 2586 The "example-ex" YANG module models a collection of forests. Each 2587 forest has a collection of trees. For simplicity, only 1 tree of 2588 each type is allowed in a forest. 2590 +--rw forests 2591 +--rw forest [name] 2592 +--rw name string 2593 +--ro tree-count? uint32 2594 +--rw trees 2595 +--rw tree [name] 2596 +--rw name string 2597 +--rw location? string 2598 +--ro height? decimal64 2600 module example-ex { 2602 namespace "http://example.com/ns/example-ex"; 2603 prefix ex; 2604 organization "Example, Inc."; 2605 contact "support@example.com"; 2607 description "Module used in NETCONF-EX examples."; 2608 revision 2013-10-19 { 2609 description "Initial version"; 2610 reference "Example Spec 12.44"; 2611 } 2613 container forests { 2614 description "A collection of forests"; 2616 list forest { 2617 key name; 2618 description "A single forest"; 2620 leaf name { 2621 type string; 2622 description "The forest name"; 2623 } 2625 leaf tree-count { 2626 type uint32; 2627 config false; 2628 description "The number of trees in this forest"; 2630 } 2632 container trees { 2633 description "A collection of trees"; 2635 list tree { 2636 key name; 2637 description "A single tree"; 2639 leaf name { 2640 type string; 2641 description "The tree name"; 2642 } 2643 leaf location { 2644 type string; 2645 description "The tree location"; 2646 } 2648 leaf height { 2649 type decimal64 { 2650 fraction-digits 3; 2651 } 2652 units meters; 2653 config false; 2654 description "The tree height"; 2655 } 2656 } // list tree 2657 } // container trees 2658 } // list forest 2659 } // container forests 2660 } 2662 B.2. YANG Data Used in Examples 2664 The follow instances are assumed in the following examples. 2666 list forest: "north": 2667 list tree: "birch", "ash", "maple" 2669 list forest: "south": 2670 list tree: "banyan", "palm" 2672 leaf "location": "hillside", "west valley", "southwest pasture", 2673 "east meadow", "greenhouse" 2675 The forests and trees are configured, which represent trees the 2676 company has planted and growing over time. 2678 The operational data (tree height) represents the data that the 2679 company monitors for each tree over time. 2681 B.3. Examples 2683 B.3.1. Confirmed Commit on the "running" Datastore 2685 In this example, the server supports the :writable-running and 2686 :startup capabilities: 2688 2690 2692 2693 2694 /ex:forests/ex:forest[ex:name='north'] 2695 2696 2697 oak-tree-patch 2698 Create an oak tree 2699 2700 oak 2701 create 2702 /ex:trees 2703 2704 2705 oak 2706 hillside 2707 2708 2709 2710 2711 2712 10 2713 2714 60 2715 24ef8829a4 2716 2717 2719 The edit succeeds, and the "yang-patch-status" container is returned 2720 to the client with the path expression of the new oak tree 2721 resource. The candidate and running datastores remain locked after 2722 this operation because a confirmed commit procedure is in progress. 2723 The startup datastore was not locked during this operation because 2724 the "nvstore-now" parameter was not provided. 2726 2728 2731 oak-tree-patch 2732 2733 2734 2735 oak 2736 2737 /ex:forests/ex:forest/north/ex:trees/ex:tree/oak 2738 2739 2740 2741 2742 2744 After configuration verification (e.g., 20 seconds), the client 2745 decides to keep these configuration changes and sends a 2746 request. 2748 2750 2752 24ef8829a4 2753 2754 2756 The server completes the confirmed commit procedure and returns an 2757 "ok" element to indicate success: 2759 2761 2762 2764 After the operation succeeds, the server releases all locks that were 2765 being held to allow exclusive write access for the entire confirmed 2766 commit procedure. 2768 The client can now save the activated configuration changes to the 2769 startup configuration using the protocol operation, as 2770 described in RFC 6241, section 8.7.5.1. 2772 B.3.2. Conditional Editing with "if-match" Parameter 2774 In this example the client is going to change the location of the 2775 "palm" tree is the "south" forest. The entity tag for the tree 2776 resource is retrieved with the resource: 2778 2780 2782 2783 /ex:forests/ex:forest[ex:name='south']/ex:trees/ 2784 ex:tree[ex:name='palm'] 2785 2786 1 2787 ncex:etags 2788 2789 2791 The server returns a subtree containing data nodes representing the 2792 "palm" tree. The "etag" attribute is returned for this resource and 2793 its ancestors. Only the "tree" node itself, as requested with the 2794 "depth parameter. 2796 2799 2801 2803 2804 south 2805 2806 2807 2808 2809 2810 2811 2813 The client then edits the list entry (e.g, reassigns tree location) 2814 but submits an "if-match" parameter with the "etag" value it received 2815 for the tree resource being edited: 2817 2819 2821 2822 2823 /ex:forests/ex:forest[ex:name='south']/ex:trees 2824 /ex:tree[ex:name='palm'] 2825 2826 2827 move-palm-tree 2828 Move the palm tree 2829 2830 palm 2831 merge 2832 / 2833 2834 greenhouse 2835 2836 2837 2838 3477cc82 2839 2840 10 2841 2842 2843 2844 2846 In this example the tree resource has been edited by another client 2847 since the reply for this client, so the edit request is not 2848 even attempted. Instead an "operation-failed" is returned: 2850 2852 2855 move-palm-tree 2856 2857 2858 protocol 2859 operation-failed 2860 precondition-failed 2861 2862 /ex:forests/ex:forest[ex:name='south']/ex:trees/ 2863 ex:tree[ex:name='palm'] 2864 2865 2866 if-match precondition failed 2867 2868 2869 2870 2871 2873 B.3.3. Bulk Editing with "target-resource" Parameter 2875 In this example, the server supports the :candidate and :startup 2876 capabilities, so all 3 datastores (including running) are locked for 2877 the operation. There is a new pine tree for each forest that 2878 is being created and sent to the greenhouse. 2880 2882 2884 2885 2886 /ex:forests/ex:forest 2887 2888 2889 pine-tree-patch 2890 Add 2 new pine trees to greenhouse 2891 2892 pine 2893 create 2894 /ex:trees 2895 2896 2897 pine 2898 greenhouse 2899 2900 2901 2902 2903 2904 10 2905 2906 2907 2908 2910 The edit succeeds, and the "yang-patch-status" container is returned 2911 to the client with the status information. 2913 2915 2918 pine-tree-patch 2919 2920 2921 2922 pine 2923 2924 /ex:forests/ex:forest/north/ex:trees/ex:tree/pine 2925 2926 2932 2933 2934 2935 2937 B.3.4. Edit Validation with "test-only" Parameter 2939 In this example, the client is checking if it can change the location 2940 field in the "palm" tree list entry by using the "test-only" 2941 parameter: 2943 2945 2947 2948 2949 /ex:forests/ex:forest[ex:name='south']/ex:trees 2950 2951 2952 palm-tree-move 2953 Move the palm tree to riverside 2954 2955 palm 2956 merge 2957 /ex:tree/palm 2958 2959 riverside 2960 2961 2962 2963 2964 2965 2967 Since "riverside" is not a supported location, an "invalid-value" 2968 error is returned for the requested edit operation: 2970 2972 2975 palm-tree-move 2976 2977 2978 palm 2979 2980 2981 protocol 2982 invalid-value 2983 2984 /ex:forests/ex:forest[ex:name='south']/ex:trees/ 2985 ex:tree[ex:name='palm'] 2986 2987 2988 value is invalid 2989 2990 2991 2992 2993 2994 2995 2997 B.4. Examples 2999 B.4.1. If-Modified-Since Non-Empty Filter Retrieval 3001 In this example, the running datastore was last modified at 3002 "2012-09-09T01:43:27Z" because the forest named "north" was modified 3003 at this time. 3005 o The forest named "north" was last modified after the specified 3006 "if-modified-since" timestamp. 3008 o The forest named "south" was last modified before the specified 3009 "if-modified-since" timestamp. 3011 o The server maintains a last-modified timestamp for the running 3012 datastore and the "forest" list entries. 3014 o The client is requesting only the changed entries after 2012-09- 3015 09T01:43:27Z, so the "full-delta" parameter is set. 3017 o The client is also requesting that timestamps be returned within 3018 the data nodes. If any part of the "forest" subtree is modified 3019 then this timestamp will be updated. 3021 3023 3025 3026 3027 3028 2012-09-09T01:43:27Z 3029 3030 ncex:timestamps 3031 3032 3034 3037 3039 3040 3041 north 3042 3043 3044 birch 3045 hillside 3046 3047 3048 ash 3049 southwest pasture 3050 3051 3052 maple 3053 east meadow 3054 3055 3056 3057 3058 3059 3061 B.4.2. If-Modified-Since Empty Filter Retrieval 3063 In this example the client has changed the "if-modified-since" 3064 timestamp to a time in the future. 3066 o No "forest" list entry has been modified since this time so an 3067 empty data node is returned. 3069 o Note that the "last-modified" timestamp is returned for the node 3070 representing the datastore, even though no data nodes have been 3071 modified since the specified time. This allows the client to 3072 easily retrieve the last-modified timestamp for the entire 3073 datastore. 3075 3077 3079 3080 3081 3082 2012-09-09T03:43:27Z 3083 ncex:timestamps 3084 3085 3087 3090 3092 3094 B.4.3. Keys Only Filter Retrieval 3096 This example retrieves only the names from the "forests" subtree in 3097 the running datastore. 3099 o The default source (running) is used. 3101 o The default depth="0" is used to retrieve all subtree levels. 3103 o The "keys-only" leaf is set 3105 o The "forests" subtree is selected. The xpath-filter is used 3106 instead of the subtree-filter. 3108 o Whitespace added to xpath-filter element for display purposes 3109 only. 3111 3113 3114 3115 /ex:forests 3116 3117 3118 3119 3121 3123 3124 3125 3126 north 3127 3128 3129 birch 3130 3131 3132 ash 3133 3134 3135 maple 3136 3137 3138 3139 3140 south 3141 3142 3143 banyan 3144 3145 3146 palm 3147 3148 3149 3150 3151 3152 3154 B.4.4. Test for Node Existence with Depth=1 3156 This example retrieves the "trees" node to determine which forests 3157 have any trees. 3159 o Only 1 subtree level is requested, instead of the default of all 3160 levels. 3162 o The default source (running) is used. 3164 o The "trees" subtree is selected. 3166 o The depth parameter is set to "1" to only retrieve the requested 3167 layer "trees" and its ancestor nodes and the configuration leaf 3168 nodes from each "forest" entry. 3170 3172 3173 3174 3175 3176 3177 3178 3179 3180 1 3181 3182 3184 3186 3187 3188 3189 north 3190 3191 3192 3193 south 3194 3195 3196 3197 3198 3200 B.4.5. Retrieve Only Non-Configuration Data Nodes 3202 This example retrieves only the name leafs from the "forest" list 3203 within the "forests" subtree, in the running datastore. 3205 o The "source" leaf is set to the "operational" data source 3207 o The "forests" subtree is selected 3208 3210 3211 3212 3213 3214 3215 3216 3218 3220 3221 3222 3223 north 3224 3225 3226 birch 3227 41.013 3228 3229 3230 ash 3231 16.523 3232 3233 3234 maple 3235 51.204 3236 3237 3238 3239 3240 south 3241 3242 3243 banyan 3244 91.433 3245 3246 3247 palm 3248 83.439 3249 3250 3251 3252 3253 3254 3256 Author's Address 3258 Andy Bierman 3259 YumaWorks, Inc. 3261 Email: andy@yumaworks.com