idnits 2.17.1 draft-hares-dt-i2rs-protocol-strawman-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 301 has weird spacing: '...derived state...' == Line 614 has weird spacing: '...ro name yang:...' == Line 615 has weird spacing: '...evision union...' == Line 617 has weird spacing: '...mespace inet...' == Line 620 has weird spacing: '...ro name yang...' == (1 more instance...) == 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 (March 15, 2016) is 2963 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.ietf-i2rs-ephemeral-state' is mentioned on line 1225, but not defined == Missing Reference: 'I-D.ietf-netconf-restconf' is mentioned on line 1263, but not defined == Missing Reference: 'I-D.hares-i2rs-dataflow-req' is mentioned on line 1215, but not defined == Missing Reference: 'I-D.ietf-i2rs-pub-sub-requirements' is mentioned on line 1235, but not defined == Missing Reference: 'I-D.ietf-netconf-yang-push' is mentioned on line 1278, but not defined == Missing Reference: 'I-D.ietf-netmod-opstate-reqs' is mentioned on line 1284, but not defined == Missing Reference: 'I-D.ietf-i2rs-rib-data-model' is mentioned on line 1240, but not defined == Missing Reference: 'I-D.ietf-netconf-yang-library' is mentioned on line 1268, but not defined == Missing Reference: 'I-D.ietf-i2rs-architecture' is mentioned on line 1219, but not defined == Missing Reference: 'RFC6242' is mentioned on line 1294, but not defined == Missing Reference: 'RFC7589' is mentioned on line 1302, but not defined == Missing Reference: 'RFC7158' is mentioned on line 1298, but not defined ** Obsolete undefined reference: RFC 7158 (Obsoleted by RFC 7159) == Missing Reference: 'I-D.ietf-netconf-yang-patch' is mentioned on line 1273, but not defined == Missing Reference: 'I-D.ietf-i2rs-protocol-security-requirements' is mentioned on line 1230, but not defined == Missing Reference: 'I-D.ietf-i2rs-security-environment-reqs' is mentioned on line 1252, but not defined == Missing Reference: 'I-D.ietf-i2rs-rib-info-model' is mentioned on line 1247, but not defined == Missing Reference: 'I-D.ietf-i2rs-traceability' is mentioned on line 1257, but not defined == Missing Reference: 'I-D.ietf-netmod-yang-metadata' is mentioned on line 1289, but not defined == Unused Reference: 'RFC2119' is defined on line 1310, but no explicit reference was found in the text == Unused Reference: 'RFC6020' is defined on line 1315, but no explicit reference was found in the text == Unused Reference: 'RFC6536' is defined on line 1325, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 30 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 I2RS working group S. Hares 3 Internet-Draft Huawei 4 Intended status: Standards Track March 15, 2016 5 Expires: September 16, 2016 7 I2RS protocol strawman 8 draft-hares-dt-i2rs-protocol-strawman-00.txt 10 Abstract 12 This document provides a strawman proposal for the I2RS protocol 13 covering the ephemeral data store and data flow requirements not 14 covered by i2rs publication/subscription service or traceability. It 15 also proposes additions to YANG for the ephemeral data store and for 16 additional data flow requirements. It proposes additions to the 17 NETCONF and RESTCONF for these additions. Future versions of this 18 document will propose changes to support the I2RS protocol security 19 requirements. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on September 16, 2016. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Ephemeral Changes . . . . . . . . . . . . . . . . . . . . 4 57 1.2. Data Flow Changes . . . . . . . . . . . . . . . . . . . . 4 58 2. Definitions Related to Ephemeral Configuration . . . . . . . 5 59 3. Definition of ephemeral datastore for NETCONF/RESTCONF . . . 6 60 4. Error handling . . . . . . . . . . . . . . . . . . . . . . . 9 61 4.1. Syntax validation . . . . . . . . . . . . . . . . . . . . 10 62 4.2. Referential validation . . . . . . . . . . . . . . . . . 10 63 4.3. Grouping and Error handling . . . . . . . . . . . . . . . 11 64 4.3.1. Initial Support of Parital Writes . . . . . . . . . . 11 65 4.3.2. Future Scope of multiple message writes . . . . . . . 11 66 4.4. priority preemption . . . . . . . . . . . . . . . . . . . 12 67 4.4.1. Andy Bierman Priority Comment . . . . . . . . . . . . 12 68 5. transport protocol . . . . . . . . . . . . . . . . . . . . . 13 69 5.1. Secure Protocols . . . . . . . . . . . . . . . . . . . . 13 70 5.2. Insecure Protocol . . . . . . . . . . . . . . . . . . . . 13 71 6. Yang Library Use by Ephemeral . . . . . . . . . . . . . . . . 13 72 7. Simple Thermostat Model . . . . . . . . . . . . . . . . . . . 14 73 7.1. Yang changes . . . . . . . . . . . . . . . . . . . . . . 15 74 7.2. RESTCONF sequence . . . . . . . . . . . . . . . . . . . . 16 75 7.3. NETCONF messages . . . . . . . . . . . . . . . . . . . . 16 76 8. NETCONF protocol extensions for the ephemeral datastore . . . 17 77 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17 78 8.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . 18 79 8.3. Capability identifier . . . . . . . . . . . . . . . . . . 18 80 8.4. New Operations . . . . . . . . . . . . . . . . . . . . . 19 81 8.4.1. link-ephemeral . . . . . . . . . . . . . . . . . . . 19 82 8.4.2. Bulk-Write . . . . . . . . . . . . . . . . . . . . . 19 83 8.5. Modification to existing operations . . . . . . . . . . . 19 84 8.5.1. . . . . . . . . . . . . . . . . . . . . 19 85 8.5.2. . . . . . . . . . . . . . . . . . . . . 20 86 8.5.3. . . . . . . . . . . . . . . . . . . . . 21 87 8.5.4. . . . . . . . . . . . . . . . . . . . 21 88 8.5.5. and . . . . . . . . . . . . . . . . . 21 89 8.5.6. . . . . . . . . . . . . . . . . . . . . . . . . 22 90 8.5.7. and . . . . . . . . . 22 91 8.6. Interactions with Capabilities . . . . . . . . . . . . . 22 92 8.6.1. writable-running and candidate datastore . . . . . . 22 93 8.6.2. confirmed commmit . . . . . . . . . . . . . . . . . . 22 94 8.6.3. rollback-on-error . . . . . . . . . . . . . . . . . . 22 95 8.6.4. validate . . . . . . . . . . . . . . . . . . . . . . 22 96 8.6.5. Distinct Startup Capability . . . . . . . . . . . . . 23 97 8.6.6. URL capability and XPATH capability . . . . . . . . . 23 98 9. RESTCONF protocol extensions for the ephemeral datastore . . 23 99 9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 23 100 9.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . 23 101 9.3. Capability identifier . . . . . . . . . . . . . . . . . . 24 102 9.4. New Operations . . . . . . . . . . . . . . . . . . . . . 24 103 9.5. modification to data resources . . . . . . . . . . . . . 24 104 9.6. Modification to existing operations . . . . . . . . . . . 24 105 9.6.1. OPTIONS changes . . . . . . . . . . . . . . . . . . . 24 106 9.6.2. HEAD changes . . . . . . . . . . . . . . . . . . . . 24 107 9.6.3. GET changes . . . . . . . . . . . . . . . . . . . . . 24 108 9.6.4. POST changes . . . . . . . . . . . . . . . . . . . . 25 109 9.6.5. PUT changes . . . . . . . . . . . . . . . . . . . . . 25 110 9.6.6. PATCH changes . . . . . . . . . . . . . . . . . . . . 25 111 9.6.7. DELETE changes . . . . . . . . . . . . . . . . . . . 25 112 9.6.8. Query Parameters . . . . . . . . . . . . . . . . . . 25 113 9.7. Interactions with Notifications . . . . . . . . . . . . . 25 114 9.8. Interactions with Error Reporting . . . . . . . . . . . . 25 115 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 116 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 117 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26 118 13. Major Contributors . . . . . . . . . . . . . . . . . . . . . 27 119 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 120 14.1. Normative References: . . . . . . . . . . . . . . . . . 27 121 14.2. Informative References . . . . . . . . . . . . . . . . . 29 122 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 29 124 1. Introduction 126 This documents is a strawman for I2RS higher level protocol. The 127 I2RS protocol is a higher level protocol is comprised of a set 128 existing protocols which have been extended to work together to 129 support a new interface to the routing system. 131 This draft is input to a NETCONF review and design team. 133 This strawman proposal for the I2RS protocol covers the ephemeral 134 data store and data flow requirements not covered by I2RS 135 publication/subscription service or traceability. It also proposes 136 additions to YANG for the ephemeral data store and for these 137 additional data flow requirements. It also proposes extensions to 138 NETCONF and RESTCONF to support ephemeral state and I2RS. 140 draft-hares-i2rs-protocol-strawman-examples (pending) provides 141 examples of this strawman protocol use for I2RS. This draft uses a 142 simple thermostat model to illustrate commands. 144 1.1. Ephemeral Changes 146 This document proposes additions to support ephemeral state in the 147 datastores supported by NETCONF and RESTCONF, and in the YANG modules 148 that define these data stores. The requirements for the I2RS 149 ephemeral state are covered in [I-D.ietf-i2rs-ephemeral-state] 151 This draft provides suggests the following additions to support the 152 I2RS ephemeral state: 154 o Yang ephemeral statement, 156 o NETCONF ([RFC6241]) protocol extensions for the ephemeral data 157 store, 159 o RESTCONF ([I-D.ietf-netconf-restconf]) protocol extensions for the 160 ephemeral data store 162 1.2. Data Flow Changes 164 This document proposes additions to support data flows from different 165 data models for large data flows, traffic monitoring, actions and OAM 166 interaction, and flows during outages or attacks. The requirements 167 for these changes are define in [I-D.hares-i2rs-dataflow-req]. 169 Most large data flows will be handled utilizing the publication/ 170 subscription service define in the I2RS publication/subscription 171 service requirements specified in 172 [I-D.ietf-i2rs-pub-sub-requirements]. Extensions to NETCONF to 173 support a push publication/subscription service have been defined in 174 [I-D.ietf-netconf-yang-push]. This document does not propose a pull 175 publication/subscription (pull pub-sub) service for the first set of 176 component protocols for the I2RS higher level protocol. If 177 deployments require the pull pub-sub service, then an expansion of 178 the push service can provide one mechanism. 180 This document does provide support for the I2RS protocol to: 182 Support large data transfers in a data agnostic format (DF-REQ-02) 183 supporting transfers of data in any format (E.g. XML, JSON, MTL, 184 protobuf, ASCII) over any transport (DF-REQ-03). 186 Support the use of IPFIX as a component protocol to send traffic 187 monitoring data or any type of large data flow from I2RS agent to 188 I2RS client (DF-REQ-04), 190 Support exporting traffic statistics for filter-based policies 191 usage (BGP-FS, I2RS FB-FIB, policy routing), IPPM, SFLOW and other 192 traffic statistics using either yang models or IPFIX template 193 formats over any data encapsulation format over any transport (DF- 194 REQ-05). 196 2. Definitions Related to Ephemeral Configuration 198 Currently the configuration systems managed by NETCONF ([RFC6241]) or 199 RESTCONF ([I-D.ietf-netconf-restconf]) have three types of 200 configuration: candidate, running, and startup running under the 201 config=true flag. 203 o The candidate receives configuration changes from NETCONF/ 204 RESTCONF. 206 o The running configuration is the configuration currently operating 207 on a devices 209 o The start-up configuration is the configuration that survives a 210 reboot. 212 The config=false flag has operational data which exists alongside the 213 config=true data. However, at this point there is no datastored 214 defined for configuration false. 216 ........... ........... ........... 217 :Candidate : --> : running : --> :start-up : 218 ........... ........... ........... 220 config true 221 --------------------------------------------- 222 config false 224 Figure 1 226 The [I-D.ietf-netmod-opstate-reqs] defines new terms to clarify how 227 this works. In reality, the running configuration becomes the 228 intended configuration that is intended to be loaded into a device. 229 The loading of the update into the system can be either asynchronous 230 or synchronous. In the asynchronous case, the netconf server 231 responds to the client after the intended has been updated, but the 232 applied configuration is only updated later when the configuration 233 change has full impacted all components on the device. The 234 synchronous configuration operation occurs when both the intent 235 configuration has been updated and the actual configuration has been 236 loaded after resolving the necessary things to load in a box. 238 This document will use the terms defined in 239 [I-D.ietf-netmod-opstate-reqs]. 241 ........... ........... ........... 242 :Candidate : --> : running : --> :start-up : 243 ........... ......||... ........... 244 || 245 =======||======== 246 | Intended | 247 | configuration | 248 ======||========= 249 config true || 250 ----------------------||------------------- 251 config false || 252 +----------------||------+ 253 | operational || | 254 | state || | 255 | =========||== | 256 | | Applied | | 257 | | config | | 258 | ============= | 259 | _____________ | 260 | | derived | | 261 | | state | | 262 | |___________| | 263 +------------------------+ 264 Figure 2 266 3. Definition of ephemeral datastore for NETCONF/RESTCONF 268 This section describes the properties of the ephemeral datastore. 269 The ephemeral datastore is not unique to I2RS. This approach to the 270 ephemeral datastore is a panes-of-glass model. This definition of 271 I2RS does not support caching in the I2RS Agents. Future I2RS work 272 may reconsidered supporting caching. 274 ............ ............... ........... 275 :Candidate :-->: running :-->:start-up : 276 ............ ..|............ ........... 277 :ephemeral : | :ephemeral: 278 : candidate: | : running : 279 ............ | ........|.. 280 | | 281 | | 282 ===========|=========|========== 283 | Intended Ephemeral | 284 | configuration Intended | 285 | Configuration| 286 |===========||================== 287 || 288 config true || 289 -------------------||---------------------- 290 config false || 291 || 292 +-------------||--------------------+ 293 | operational || | 294 | state || | 295 | ======||=================== | 296 | | Applied Configuration | | 297 | |(from normal + ephemeral)| | 298 | | | | 299 | ========================== | 300 | _________________________ | 301 | | derived state | | 302 | |from normal + ephemeral)| | 303 | | RIB and protocols | | 304 | |________________________| | 305 +-----------------------------------+ 306 Figure 3 308 The ephemeral data store has the following qualities: 310 1. Ephemeral state is not unique to I2RS work. 312 2. The ephemeral datastore is never locked. 314 3. The ephemeral datastore is really a portion of the candidate, 315 running, and intended configuration that does not persist over a 316 reboot. 318 * Since Ephemeral is just about data not presisting over a 319 reboot, then in theory any node or group of nodes in a YANG 320 data model could be ephemeral. The YANG data module must 321 indicate what portion of the data model (if any) is ephemeral. 323 * A YANG data module could be all ephemeral (e.g. 324 [I-D.ietf-i2rs-rib-data-model]) with no directly associated 325 configuration models, 327 * A YANG model could be all ephemeral but associated with a 328 configuration model (E.g. (draft-hares-i2rs-bgp-dm-01), 330 * or a single data node or data tree could be made ephemeral. 332 4. The applied configuration is the result of the the intent 333 configuration (normal and ephemeral). Similarly, the derived 334 data is a result of the applied configuration. 336 5. Ephemeral portions (node, tree, or data model) need to be 337 signalled in the conformance portions of the NETCONF and RESTCONF 338 work. Conformance is signalled in the following ways: 340 * The conformance portion of NETCONF ([RFC6241]) is currently 341 signalled in the . 343 * Yang 1.1 and RESTCONF uses the module library 344 ([I-D.ietf-netconf-yang-library]) 346 * NETCONF may use the module library in the future. 348 * The ephemeral status in a module will be listed as "all, none 349 or partial". Optionally the module may provide a list of 350 nodes. 352 6. The ephemeral data store is treated as one pane of glass that an 353 I2RS client(s) may read/write which has the following 354 implications: 356 * The ephemeral datastore overlays the configuration datastore 357 at each point it touches (candidate, running, and intended 358 configuration) By overlays, the I2RS write overwrites a 359 previous configuration value, but if a local configuration 360 value changes after that over-write the default is to have the 361 local-config win. [aka Last Write wins.] 363 + An example may help to illustrate this default rule. Say a 364 configuration specifies a local route of 128.2/16 with a 365 nexthop of 192.5.10.1. Afterwards an ephemeral route is 366 added for 128.2/16 with nexthop of 192.5.10.2. This 367 ephemeral route would replace the first route. If the 368 configuration changes the underlying route (128.2/16 with 369 nexthop of 192.5.10.1) and the default rule of local 370 configuration is in effect, the local configuration value 371 (128.2/16 with nexthop of 192.5.10.1) would take effect. 372 This follows the normal netconf concept that Last 373 configured wins. The I2RS agent would notify the I2RS 374 Client that the ephemeral route (128.2/16 with nexthop of 375 192.5.10.2) had been overwritten by the local 376 configuration. 378 * The default of local can be changed by operator-applied policy 379 to allow ephemeral to always win or local configuration to 380 always win, but the status of the operator applied policy must 381 be queryable in the I2RS agent (if that scope) or in the I2RS 382 ephemeral data model. I2RS clients are required to understand 383 and handle if the an I2RS agent supports something different 384 than the default (aka Last write wins). 386 4. Error handling 388 Ephemeral nodes level of validation/error handling in the I2RS 389 protocol has three following three types: 391 o syntax validation only, 393 o Ephemeral data store allows for reduced error handling that 394 removes the requirements for referential checks [I2RS normal error 395 handling] 397 o ephemeral data store handling that uses normal NETCONF/RESTCONF 398 error handling with syntax and referential [full], 400 The default error handling is "no referential checking". 402 Normal error handling of I2RS Agent for an I2RS client's information 403 examines the following: 405 o message syntax validation, 407 o syntax validation for nodes of data model, 409 o removes referential requirements for leafref checking, MUST 410 clauses, and instance indentifier, 412 o grouping of data within a data models or across data models to 413 accomplish tasks, 415 o permission to write nodes of data model, 417 o grouping, 418 o priority to write nodes of data model being higher than existing 419 priority 421 The full error handling status includes all checks included for any 422 normal YANG data module uses by NETCONF/RESTCONF. This includes 423 referential checks for leafref checks, MUST clauses, and instance 424 identifiers. 426 The I2RS Data model sets permissible range of error handling for 427 writes on a data model (none, I2RS normal, full), and this may be 428 further restricted by an operator applied policy. If an I2RS client 429 requests a lower level of error handling that permissible, the I2RS 430 Agent will return an error. 432 Multiple I2RS clients writing to the same variable is considered an 433 "error condition" in the I2RS architecture 434 [I-D.ietf-i2rs-architecture], but the I2RS Agent must handle this 435 error condition. Upon multiple I2RS clients writing, the ephemeral 436 data store allows for priority pre-emption of the write operation. 437 Priority pre-emption means each I2RS client of the ephemeral I2RS 438 agent (netconf server) is associated with a priority. Priority pre- 439 emption occurs when a I2RS client with a higher priority writes a 440 node which has been written by an I2RS client (with the lower 441 priority). At this point, the I2RS agent (netconf server) allows the 442 write and provides a notification indication to the notification 443 publication/subscription service. 445 This section describes the ephemeral data stores handling of each of 446 these error functions. 448 4.1. Syntax validation 450 Syntax validation of the message should be done according to the 451 NETCONF or RESTCONF protocol features. New features for ephemeral 452 datastore should provide the error handling with the feature. 453 Message syntax validation can be for read, write, or rpc functions. 455 Syntax validation of the data model included in the ephemeral data 456 store should be done by I2RS Agent. 458 4.2. Referential validation 460 The ephemeral data store normal processing does not do the following 461 referencial checks: leafref, MUST, instance identifier. The removal 462 of these validations allows for intelligent I2RS clients to rapidly 463 read or write data, and handle error conditions at a higher level. 465 4.3. Grouping and Error handling 467 Yang 1.0 and Yang 1.1 provide the ability to group data in groupings, 468 leafref lists, lists, and containers. Data model group data in order 469 to group data that is logically associated with one another. Data 470 models may logical group data across groupings. One example of such 471 an association is the association of a static route with an 472 interface. The concepts of groupings apply to both ephemeral and 473 non-ephemeral nodes within a data model. 475 4.3.1. Initial Support of Parital Writes 477 The initial releases of I2RS will only require "all-or-nothing" in 478 the I2RS Agent. 480 4.3.2. Future Scope of multiple message writes 482 Error handling on writes of the ephemeral datastore is different for 483 nodes that are grouped versus orthogonal. Group nodes may need to be 484 all changed or all removed (all-or-nothing). In contrast, writing 485 orthogonal data nodes in the same data module or between data models 486 need to be added or deleted in sync. 488 The [I-D.ietf-i2rs-architecture] specifies three types of error 489 handling for a partial write operation: "all-or-nothing", "stop-on- 490 error", or "continue-on-error". Partial write operations of "stop- 491 on-error" or "continue-on-error" are allowed only for data writes 492 which are not a part of a grouping within a data model. The 493 definition of the I2RS error conditions are: 495 o stop-on-error - means that the configuration process stops when a 496 write to the configuration detects an error due to write conflict. 498 o continue-on-error - means the configuration process continues when 499 a write to the configuration detects an error due to write 500 process, and error reports are transmitted back to the client 501 writing the error. 503 o all-or-nothing - means that all of the configuration process is 504 correctly applied or no configuration process is applied. 505 (Inherent in all-or-nothing is the concept of checking all changes 506 before applying.) 508 4.3.2.1. NETCONF Support of Partial Writes 510 NETCONF does not support a mandated sequencing of edit functions or 511 write functions. Without this mandated sequences, NETCONF cannot 512 support partial edits. 514 4.3.2.2. RESTCONF Support of Partial Writes 516 RESTCONF has a complete set of operations per message. The RESTCONF 517 patch can support write functions per messages. 519 4.4. priority preemption 521 I2RS protocol uses priority to resolve two I2RS clients having 522 permissions to write the same pieces of data in an I2RS agent 523 (NETCONF server). If two (or more) I2RS clients attempt to write the 524 same data, the the one with the highest priority is enable to write 525 the data. In the case of two clients with teh sample priority 526 attempting to write data, the the first one to request write wins. 528 Each client has a unique priority. Client identities and priorities 529 are assigned outside of I2RS by exterior mechanisms such as AAA or 530 adminstrative interfaces. A valid I2RS client must have both an 531 identity and a priority. 533 A client-id and priority must be saved per node. 535 A sample container for I2RS client information is shown below. 537 container i2rs-clients { 538 leaf max-clients { 539 config false; 540 mandatory true; 541 type uint32 { 542 range "1 .. max"; 543 } 544 } 545 list i2rs-client { 546 key name; 547 unique priority; 548 leaf name { ... } 549 leaf priority { ... } 550 } 551 } 552 Figure 4 554 4.4.1. Andy Bierman Priority Comment 556 (Andy)The priority is not required to be densely numbered. Whether 557 there are 1 pane per client or 1 pane per priority or 1 giant blob 558 full of everything, the code will be the same. The goal of "unique 559 priority" is to require that only priority be saved in the meta-data 560 for the ephemeral datastore. Without that, client-id and priority 561 must be saved (per data node). 563 5. transport protocol 565 5.1. Secure Protocols 567 NETCONF's XML-based protocol ([RFC6241]) can operate over the 568 following secure and encrypted transport layer protocols: 570 SSH as defined in [RFC6242], 572 TLS with X.509 authentication [RFC7589] 574 RESTCONF's XML-based or JSON [RFC7158] data encodings of Yang 575 functions are passed over http with (GET, POST, PUT, PATCH, DELETE, 576 OPTIONS, and HEAD). 578 5.2. Insecure Protocol 580 The ephemeral database may support insecure protocols for information 581 which is ephemeral state which does not engage in configuration. The 582 insecure protocol must be defined in conjunction with a data model or 583 a subdata model. 585 6. Yang Library Use by Ephemeral 587 The data modules supporting the ephemeral datastore can use the Yang 588 module library to describe their datastore. Figure 5 shows the 589 module library data structure as found 590 [I-D.ietf-netconf-yang-library]. The I2RS modules will provide 591 features for I2RS ephemeral state and protocol of: 593 o protocol version support - "version 1", 595 o ephemeral model scope - ephemeral modules, mixed config module 596 (ephemeral and config), mixed derived state (ephemeral and 597 config). 599 o ephemeral checking - syntax only, I2RS normal (no referential), 600 full (RESTCONF/NETCONF) 602 o multiple message support - "all or nothing", 604 o pane of glass support - "single only". 606 o protocol supported - "NETCONF", "RESTCONF", "NETCONF pub-sub 607 push", 609 o encoding support - XML or JSON 610 o transports supported: "TCP", "SSH", "TLS", and others supported. 612 +--ro modules 613 +--ro module*[name revision] 614 +--ro name yang: yang-identifier 615 +--ro revision union; 616 +--ro schema? inet:uri 617 +--ro namespace inet:uri 618 +--ro feature* yang:yang-identifier 619 +--ro deviation* [name revision] 620 | +-- ro name yang:yang-identifier 621 | +-- ro revision union 622 +--ro conformance enumeration 623 +--ro submodules 624 +--ro submodule*[name revision] 625 +--ro name yang:yang-identifier 626 +--ro revision union 627 +--ro schema? inet:uri 629 Figure 5 631 7. Simple Thermostat Model 633 In this discussion of ephemeral configuration, this draft utilizes a 634 simple thermostat model with the YANG configuration found in figure 635 6. 637 module thermostat { 638 .. 639 leaf desired-temp { 640 type int32; 641 units "degrees Celsius"; 642 description "The desired temperature"; 643 } 645 leaf actual-temp { 646 type int32; 647 config false; 648 units "degrees Celsius"; 649 description "The measured temperature 650 (operational state)."; 651 } 652 } 654 Figure 6 - Simple thermostat model yabng 656 Figure 6 shows two I2RS clients talking to this model: scheduler and 657 hold-temp. Scheduler has a schedule set of temperatures to put in 658 the thermostat. Hold-temp holds the temperature at the same value. 659 The hold-temp I2RS client has a higher priority than the scheduler 660 client. 662 ........... ................... ........... 663 :Candidate :---:running config :--: start-up : 664 : : :desired-temp (cfg): : : 665 ........... .................. ........... 666 | :ephemeral : 667 | :config -----| 668 | : : | 669 | ..|....|.... | 670 | | | ============= 671 | | | |I2rs Client| 672 | | \ |scheduler | 673 V V \ ============ 674 .................. \ 675 Intended . ''''''''''''''' ============== 676 Config . 'desired-temp' |I2RS Client | 677 . '''''''''^'''' . | hold temp | 678 . | . ============== 679 ...........|....... 680 config true | 681 ------------------------|------------- 682 config false | (config down, 683 V status of config up) 684 ============= 685 | Actual |============ I2RS clients 686 | config | 687 ============= 689 ______________ 690 | actual temp |========== I2RS Clients 691 | (op-state) | 692 ---------------- 694 Figure 6 - Two I2RS clients 696 7.1. Yang changes 698 Yang needs to adds key word ephemeral with the following key words: 700 o full-check - defined as NETCONF/RESTCONF relevant error checks, 702 o I2RS checks - defined as no referential checks (see section 703 above), 705 o syntax only - defined as only message syntax and model syntax, 706 module thermostat { 707 .. 709 leaf desired-temp { 710 type int32; 711 units "degrees Celsius"; 712 ephemeral true; 713 ephemeral-validation full-check; 714 description "The desired temperature"; 715 } 717 leaf actual-temp { 718 type int32; 719 config false; 720 units "degrees Celsius"; 721 description "The measured temperature"; 722 } 723 } 725 Figure 7 - Simple Thermostat Yang with ephemeral 727 7.2. RESTCONF sequence 729 Figure 7 shows the thermostat model has ephemeral variable desired- 730 temp in the running configuration and the ephemeral data store. The 731 RESTCONF way of addressing is below: 733 RESTCONF running data store 735 PUT /restconf/data/thermostat:desired-temp 736 {"desired-temp":18} 738 RESTCONF ephemeral datastore 740 PUT /restconf/data/thermostat:desired-temp?datastore=ephemeral 741 ?ephemeral-validation="full-check" 742 {"desired-temp":19 } 744 Figure 8 - RESTCONF setting of ephemeral state 746 7.3. NETCONF messages 748 The NETCONF way of transmitting this data would be 749 751 752 753 754 true 755 756 757 fullcheck 758 759 760 761 allows the ephemeral datastore to be a pane of 846 glass that impacts either the running-config configuration pane of 847 glass or the candidate configuration pane of glass. 849 target-config 851 where target config is: 852 writable-running or candidate config. 854 8.4.2. Bulk-Write 856 Bulk Write allows for large scale writes with error handling that is 857 specified as syntax or reduced or full. Alternatively, the data 858 modules can utilize an RPC to do bulk reads/writes. The bulk write 859 will be first check for other I2RS clients having a higher priority 860 write value for any of the values. 862 Editor: Do we need something beyond rpc for bulk data writes? 864 8.5. Modification to existing operations 866 The capability for :ephemeral-datastore modifies the target for 867 existing operations. 869 8.5.1. 871 The :ephemeral-datastore capability modifies the to 872 accept the as a target for source, and allows the filters 873 focused on a particular module, submodule, or node. 875 The positive and negative responses remain the same. 877 Example - retrieve users subtree from 878 ephemeral database 880 882 883 884 885 886 887 888 889 890 891 892 894 8.5.2. 896 The :ephemeral-datastore capability modifies the to 897 accept the as a target for source with filters. The 898 operations of merge, replace, create, delete, and remove are 899 available, but each of these operations is modified by the priority 900 write as follows: 902 parameter is replaced by The current data 903 is modified by the new data in a merge fashion only if existing 904 data either does not exist, or is owned by a lower priority 905 client. If any data is replaced, this event is passed to the 906 notification function within the pub/sub and traceability. 908 is replaced by for ephemeral 909 datastore which replaces data if the existing data is owned by a 910 lower priority client. If data any data is replaced, this event 911 is passed to the notification function within pub/sub and 912 traceability for notification to the previous client. The success 913 or failure of the event is passed to traceabilty. 915 - the creation of the data node works as in [RFC6241] 916 except that the success or failure is passed to pub/sub and 917 traceability functions. 919 - the deletion of the data node works as in [RFC6241] 920 except event that the success or the error event is passed to the 921 notiication function withi pub/sub and traceability functions. 923 - the remove of the data node works as in [RFC6241] 924 except that all results are forwarded to traceabilty. 926 The existing parameters are modified as follows: 928 - add a target of :emphemeral-datastore 930 -allows only or 933 - the I2RS agent agent supports only the a"all-or- 934 nothing" equivalent to a "rollback-on-error" function. 936 positive response - the is sent for a positive response 937 within an . 939 negative response - the is sent for a negative 940 response within an . Note a negative respones may 941 evoke a publication of an event. 943 8.5.3. 945 Copy config allows for the complete replacement of all the ephemeral 946 nodes within a target. The alternation is that source is the 947 :ephemeral datastore with the filtering to match the datastore. The 948 following existing parameters are modified as follows: 950 - add a target of :emphemeral-datastore 952 - the I2RS agent agent supports only the a"all-or- 953 nothing" equivalent to a "rollback-on-error" function. 955 positive response - the is sent for a positive response 956 within an . 958 negative response - the is sent for a negative 959 response within an . 961 8.5.4. 963 The delete will delete all ephemeral nodes out of a datastore. The 964 target parameter must be changed to allow :ephemeral-datastore. and 965 filters. 967 8.5.5. and 969 Lock and unlock are not supported with a target of :ephemeral- 970 datastore. 972 8.5.6. 974 The is altered to allow a target of :ephemeral-datastore and 975 with the filters. 977 8.5.7. and 979 The close session is modified to take a target of :ephemeral- 980 datastore Since no locks are set, none should be released. 982 The kill session is modified to take a target of "ephemeral- 983 datastore. Since no locks are set, none should be released. 985 8.6. Interactions with Capabilities 987 [RFC6241] defines NETCONF capabilities for writeable-running 988 datastore, candidate config data store, confirmed commit, rollback- 989 on-error, validate, distinct start-up, URL capability, and XPATH 990 capability. 992 8.6.1. writable-running and candidate datastore 994 The writeable-running and the candidate datastore can be used in 995 conjunction with the ephemeral data store. Ephemeral database 996 overlays an intended configuration, and may overlay candidate and 997 running configuration data store. The operation 998 links to these two databases. 1000 8.6.2. confirmed commmit 1002 Confirmed commit capability is not supported for the ephemeral 1003 datastore. 1005 8.6.3. rollback-on-error 1007 The rollback-on-error when included with ephemeral state allows the 1008 error handling to be "all-or-nothing" (roll-back-on-error). 1010 8.6.4. validate 1012 The key word is expanded to support the following: 1014 source: ephemeral-datastore 1016 validate: (syntax, no-referential, full) with the following 1017 definitions: 1019 * syntax - validates only the message syntax and the data base 1020 syntax. 1022 * no-referentail - skips referential test (leafref, MUST clauses, 1023 and instance identifiers). 1025 * full - all normal netconf/restconf module error chcking 1027 8.6.5. Distinct Startup Capability 1029 This NETCONF capability appears to operate to load write-able running 1030 config, running-config, or candidate datastore. The ephemeral state 1031 does not change the environment based on this command. 1033 8.6.6. URL capability and XPATH capability 1035 The URL capabilities specify a in the and . 1036 The initial suggestion to allow both of these features to work with 1037 ephemeral operation. 1039 9. RESTCONF protocol extensions for the ephemeral datastore 1041 capability-name: ephemeral-datastore 1043 9.1. Overview 1045 This capability defines the RESTCONF protocol extensions for the 1046 ephemeral state. The ephemeral state has the features described in 1047 the previous section on NETCONF. 1049 9.2. Dependencies 1051 The ephemeral capabilities have the following dependencies: 1053 Yang data nodes, sub-modules, or modules must be flaged with the 1054 config datastore flag; 1056 The Yang modules must support the notification of write-conflicts. 1058 The I2RS Yang modules must support the following: 1060 the yang-patch features as specified in 1061 [I-D.ietf-netconf-yang-patch]. 1063 The yang module library feature 1064 [I-D.ietf-netconf-yang-library], 1066 9.3. Capability identifier 1068 The ephemeral-datastore capability is identified by the following 1069 capability string: (capability uri) 1071 9.4. New Operations 1073 none 1075 9.5. modification to data resources 1077 RESTCONF must be able to support the ephemeral datstore with its 1078 rules as part of the "{+restconf}/data" subtree. The "edit 1079 collision" features in RESTCONF must be able to provide notification 1080 to I2RS read functions or to rpc functions. The "timestamp" with a 1081 last modified features must support the traceability function. 1083 The "Entity Tag" could support saving a client-priority tuple as a 1084 opaque string, but it is important that that additions be made to 1085 restore client-priority so it can be compared with stromgs to be 1086 added. 1088 9.6. Modification to existing operations 1090 The current operations in RESTCONF are: OPTIONS, HEAD, GET, POST, 1091 PUT, PATCH, and DELETE. This section describes the modification to 1092 these exiting operations. 1094 9.6.1. OPTIONS changes 1096 The options methods should be augmented by the 1097 [I-D.ietf-netconf-yang-library] information that will provide an 1098 indication of what ephemeral state exists in a data modules, or a 1099 data modules sub-modules or nodes. 1101 9.6.2. HEAD changes 1103 The HEAD in retrieving the headers of a resources. It would be 1104 useful to changes these headers to indicate the datastore a node or 1105 submodule or module is in (ephemeral or normal), and allow filtering 1106 on ephemeral nodes or trees, submodules or module. 1108 9.6.3. GET changes 1110 GET must be able to read from the URL and a particular datastore. 1111 Similarly, it is important the Get be able to determine if it is a 1112 ephemeral data store. 1114 9.6.4. POST changes 1116 POST must simply be able to create resources in ephemeral datastores 1117 ("=datastore=ephemeral") and invoke operations defined in ephemeral 1118 data models using the rules of the ephemeral database. 1120 9.6.5. PUT changes 1122 PUT must be able to reference an ephemeral module, sub-module, and 1123 nodes ("?datastore=ephemeral"). 1125 9.6.6. PATCH changes 1127 Plain PATCH must be able to update or create child resources in an 1128 ephemeral datastore ("?datstore=ephemeral") The PATCH for the 1129 ephemeral state must be change to provide a merge or update of the 1130 original data only if the client's using the patch has a higher 1131 priority than an existing datastore's client, or if PATCH requests to 1132 create a new node, sub-module or module in the datastore. 1134 9.6.7. DELETE changes 1136 The phrase "?datastore=ephemeral" following an element will specify 1137 the ephemeral data store when deleting entry. 1139 9.6.8. Query Parameters 1141 The query parameters (content, depth, fields, insert, point, start- 1142 time, stop-time, and with-defaults (report-all, trim, explicit, 1143 report-all-tagged) must support ephemeral datastores 1144 ("?datastore=ephemeral") described above. 1146 9.7. Interactions with Notifications 1148 The ephemeral database must support subscribing to receiving 1149 notifications as Event stream. The event error stream processing 1150 should support the publication/subscription mechanisms for ephemeral 1151 state defined in [I-D.ietf-netconf-yang-push]. 1153 9.8. Interactions with Error Reporting 1155 The ephemeral database] support in RESTCONF must also support passing 1156 error information regarding ephemeral data access over to RESTCONF 1157 equivalent of the and traceability client. 1159 10. IANA Considerations 1161 This is a protocol strawman - nothing is going to IANA. 1163 11. Security Considerations 1165 The security requirements for the I2RS protocol are covered in 1166 [I-D.ietf-i2rs-protocol-security-requirements]. The security 1167 environment the I2RS protocol is covered in 1168 [I-D.ietf-i2rs-security-environment-reqs]. Any person implementing 1169 or deploying the I2RS protocol should consider both security 1170 requirements. 1172 12. Acknowledgements 1174 This document is an attempt to distill lengthy conversations on the 1175 I2RS proto design team from August 1177 Here's the list of the I2RS protocol design team members 1179 o Alia Atlas 1181 o Ignas Bagdonas 1183 o Andy Bierman 1185 o Alex Clemm 1187 o Eric Voit 1189 o Kent Watsen 1191 o Jeff Haas 1193 o Keyur Patel 1195 o Hariharan Ananthakrishnan 1197 o Dean Bogdanavich 1199 o Anu Nair 1201 o Juergen Schoenwaelder 1203 o Kent Watsen 1205 13. Major Contributors 1207 o Andy Bierman (Yuman Networks) - andy@yumaworks.com 1209 o Kent Watson (Juniper) (kwatsent@juniper.net) 1211 14. References 1213 14.1. Normative References: 1215 [I-D.hares-i2rs-dataflow-req] 1216 Hares, S., "I2RS Data Flow Requirements", draft-hares- 1217 i2rs-dataflow-req-01 (work in progress), March 2016. 1219 [I-D.ietf-i2rs-architecture] 1220 Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 1221 Nadeau, "An Architecture for the Interface to the Routing 1222 System", draft-ietf-i2rs-architecture-13 (work in 1223 progress), February 2016. 1225 [I-D.ietf-i2rs-ephemeral-state] 1226 Haas, J. and S. Hares, "I2RS Ephemeral State 1227 Requirements", draft-ietf-i2rs-ephemeral-state-04 (work in 1228 progress), March 2016. 1230 [I-D.ietf-i2rs-protocol-security-requirements] 1231 Hares, S., Migault, D., and J. Halpern, "I2RS Security 1232 Related Requirements", draft-ietf-i2rs-protocol-security- 1233 requirements-03 (work in progress), March 2016. 1235 [I-D.ietf-i2rs-pub-sub-requirements] 1236 Voit, E., Clemm, A., and A. Prieto, "Requirements for 1237 Subscription to YANG Datastores", draft-ietf-i2rs-pub-sub- 1238 requirements-05 (work in progress), February 2016. 1240 [I-D.ietf-i2rs-rib-data-model] 1241 Wang, L., Ananthakrishnan, H., Chen, M., 1242 amit.dass@ericsson.com, a., Kini, S., and N. Bahadur, "A 1243 YANG Data Model for Routing Information Base (RIB)", 1244 draft-ietf-i2rs-rib-data-model-04 (work in progress), 1245 November 2015. 1247 [I-D.ietf-i2rs-rib-info-model] 1248 Bahadur, N., Kini, S., and J. Medved, "Routing Information 1249 Base Info Model", draft-ietf-i2rs-rib-info-model-08 (work 1250 in progress), October 2015. 1252 [I-D.ietf-i2rs-security-environment-reqs] 1253 Migault, D., Halpern, J., and S. Hares, "I2RS Environment 1254 Security Requirements", draft-ietf-i2rs-security- 1255 environment-reqs-00 (work in progress), October 2015. 1257 [I-D.ietf-i2rs-traceability] 1258 Clarke, J., Salgueiro, G., and C. Pignataro, "Interface to 1259 the Routing System (I2RS) Traceability: Framework and 1260 Information Model", draft-ietf-i2rs-traceability-07 (work 1261 in progress), February 2016. 1263 [I-D.ietf-netconf-restconf] 1264 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1265 Protocol", draft-ietf-netconf-restconf-09 (work in 1266 progress), December 2015. 1268 [I-D.ietf-netconf-yang-library] 1269 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1270 Library", draft-ietf-netconf-yang-library-04 (work in 1271 progress), February 2016. 1273 [I-D.ietf-netconf-yang-patch] 1274 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 1275 Media Type", draft-ietf-netconf-yang-patch-07 (work in 1276 progress), December 2015. 1278 [I-D.ietf-netconf-yang-push] 1279 Clemm, A., Prieto, A., Voit, E., Tripathy, A., and E. 1280 Einar, "Subscribing to YANG datastore push updates", 1281 draft-ietf-netconf-yang-push-01 (work in progress), 1282 February 2016. 1284 [I-D.ietf-netmod-opstate-reqs] 1285 Watsen, K. and T. Nadeau, "Terminology and Requirements 1286 for Enhanced Handling of Operational State", draft-ietf- 1287 netmod-opstate-reqs-04 (work in progress), January 2016. 1289 [I-D.ietf-netmod-yang-metadata] 1290 Lhotka, L., "Defining and Using Metadata with YANG", 1291 draft-ietf-netmod-yang-metadata-06 (work in progress), 1292 March 2016. 1294 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1295 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1296 . 1298 [RFC7158] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1299 Interchange Format", RFC 7158, DOI 10.17487/RFC7158, March 1300 2014, . 1302 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 1303 NETCONF Protocol over Transport Layer Security (TLS) with 1304 Mutual X.509 Authentication", RFC 7589, 1305 DOI 10.17487/RFC7589, June 2015, 1306 . 1308 14.2. Informative References 1310 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1311 Requirement Levels", BCP 14, RFC 2119, 1312 DOI 10.17487/RFC2119, March 1997, 1313 . 1315 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1316 the Network Configuration Protocol (NETCONF)", RFC 6020, 1317 DOI 10.17487/RFC6020, October 2010, 1318 . 1320 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1321 and A. Bierman, Ed., "Network Configuration Protocol 1322 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1323 . 1325 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1326 Protocol (NETCONF) Access Control Model", RFC 6536, 1327 DOI 10.17487/RFC6536, March 2012, 1328 . 1330 Author's Address 1332 Susan Hares 1333 Huawei 1334 Saline 1335 US 1337 Email: shares@ndzh.com