idnits 2.17.1 draft-voit-restconf-yang-push-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 13, 2015) is 3116 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft A. Clemm 4 Intended status: Informational A. Tripathy 5 Expires: April 15, 2016 E. Nilsen-Nygaard 6 A. Gonzalez Prieto 7 Cisco Systems 8 October 13, 2015 10 Restconf subscription and HTTP push for YANG datastores 11 draft-voit-restconf-yang-push-00 13 Abstract 15 This document defines Restconf subscription and push mechanisms to 16 continuously stream information from YANG datastores over HTTP. 17 These mechanisms allow client applications or operations support 18 systems to request custom sets of updates from a YANG datastore. 19 This document also specifies how to stream updates over HTTP without 20 Restconf. In either case, updates are pushed by a datastore to a 21 receiver per a subscription policy, without requiring continuous 22 requests. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 15, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 4 62 3.2. Subscription states at Publisher . . . . . . . . . . . . 5 63 3.3. Mechanisms for Subscription Establishment and Maintenance 6 64 3.4. Negotiation of Subscription Policies . . . . . . . . . . 8 65 3.5. Support for Periodic and On-change . . . . . . . . . . . 8 66 3.6. Filters and Streams . . . . . . . . . . . . . . . . . . . 9 67 3.7. Authorization . . . . . . . . . . . . . . . . . . . . . . 9 68 3.8. Subscription Multiplexing . . . . . . . . . . . . . . . . 9 69 3.9. Push Data Stream and Transport Mapping . . . . . . . . . 10 70 3.10. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . 14 71 4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 15 72 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 73 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 74 6.1. Normative References . . . . . . . . . . . . . . . . . . 18 75 6.2. Informative References . . . . . . . . . . . . . . . . . 19 76 Appendix A. Dynamic YANG Subscription when the Subscriber and 77 Receiver are different . . . . . . . . . . . . . . . 20 78 Appendix B. End-to-End Deployment Guidance . . . . . . . . . . . 21 79 B.1. Call Home . . . . . . . . . . . . . . . . . . . . . . . . 21 80 B.2. TLS Heartbeat . . . . . . . . . . . . . . . . . . . . . . 21 81 B.3. Putting it together . . . . . . . . . . . . . . . . . . . 22 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 84 1. Introduction 86 Requirements for subscriptions to YANG datastores are defined in 87 [pub-sub-reqs]. Mechanisms to support YANG subscriptions and 88 datastore object push over a NETCONF are defined in 89 [netconf-yang-push]. Restconf support of subscriptions, with HTTP 90 transport of pushed updates is also needed by the market. This 91 document provides such a specification. 93 Key benefits of pushing data via HTTP include: 95 o Ability to configure static subscriptions on a Publisher 96 o Ability for the Publisher to initiate communications with the 97 Receiver 99 o Ability of a Subscriber to be different from the Receiver 101 There are also additional benefits which can be realized when pushing 102 updates via HTTP/2 [RFC7540]: 104 o Subscription multiplexing over independent HTTP/2 streams 106 o Stream prioritization 108 o Stream dependencies 110 o Flow control on independent streams 112 o Header compression 114 These additional benefits will address issues resulting from head-of- 115 line blocking and relative subscription priority. 117 To maximize transport independence of YANG subscription methods, this 118 document reuses many capabilities of [netconf-yang-push][] including: 120 o Operations for creating, modifying and deleting subscriptions 122 o Syntax and parameters for negotiating the subscription 124 o YANG data model to manage subscriptions 126 o Mechanisms to communicate subscription filters and data streams 128 2. Terminology 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in RFC 2119 [RFC2119]. 134 Datastore: a conceptual store of instantiated management information, 135 with individual data items represented by data nodes which are 136 arranged in hierarchical manner. 138 Dynamic YANG Subscription: Subscription negotiated with Publisher via 139 create, modify, and delete control plane signaling messages. 141 Publisher: an entity responsible for distributing subscribed YANG 142 object data per the terms of a Subscription. In general, a Publisher 143 is the owner of the YANG datastore that is subjected to the 144 Subscription. 146 Receiver: the target where a Publisher pushes updates. In many 147 deployments, the Receiver and Subscriber will be the same entity. 149 Static YANG Subscription: A Subscription installed via a 150 configuration interface. 152 Subscriber: An entity able to request and negotiate a contract for 153 push updates from a Publisher. 155 Subscription: A contract between a Subscriber and a Publisher, 156 stipulating which information the Receiver wishes to have pushed from 157 the Publisher without the need for further solicitation. 159 Subscription Update: Set of data nodes and object values pushed 160 together as a unit and intended to meet the obligations of a single 161 subscription at a snapshot in time. 163 3. Solution 165 This document specifies mechanisms that allow subscribed information 166 updates to be pushed from a YANG datastore. Subscriptions may either 167 be initiated via requests by Subscribers, or statically configured on 168 a Publisher. As in [netconf-yang-push], Publisher must respond to a 169 subscription request explicitly positively or negatively. Negative 170 responses will include information about why the Subscription was not 171 accepted, in order to facilitate converging on an acceptable set of 172 Subscription parameters. 174 Once a Subscription has been established, updates are pushed to the 175 Receiver until the Subscription terminates. Based on parameters 176 within the Subscription, these updates can be streamed immediately as 177 any subscribed objects change, or sent periodically. 179 3.1. Subscription Model 181 Subscriptions use the base data model from [netconf-yang-push]. This 182 model is extended with several optional parameters for Subscription 183 Priority and Subscription Dependency. These parameters allow a 184 Subscriber or other configuration interface to assert how it prefers 185 the Publisher allocate resources when handling multiple 186 Subscriptions. These parameters are intended to be used in 187 conjunction with the transport layer. Specifically, when a new 188 Subscription is being established with an underlying transport is 189 HTTP/2, these parameters may be directly mapped into HTTP/2 to 190 prioritize transport and to assist with flow control of individual 191 streams. 193 3.2. Subscription states at Publisher 195 Below is the state machine for the Publisher. It is important to 196 note that a Subscription doesn't exist at the Publisher until it is 197 accepted and made active. The assertion of a 198 by a Subscriber is insufficient for that asserted subscription to be 199 externally visible via this state machine. 201 Subscription states at Publisher 203 .-------. 204 | start | 205 '-------' 206 | 207 create 208 | 209 | .----------modify-------------. 210 v v ' 211 .-----------. .-----------. 212 .--------. | |------>suspend------->| | 213 modify '| active | | suspended | 214 '--------->| |<----reactivate<------| | 215 '-----------' '-----------' 216 | | 217 delete delete 218 | | 219 v | 220 .-------. | 221 | end |<-----------------------------' 222 '-------' 224 Of interest in this state machine are the following: 226 o Successful or actions 227 must put the subscription into an active state. 229 o Failed actions will leave the subscription 230 in its previous state, with no visible change to any streaming 231 updates. 233 o A action will delete the entire 234 subscription. 236 3.3. Mechanisms for Subscription Establishment and Maintenance 238 On a Publisher, it must be possible to instantiate a Subscription via 239 dynamic Subscriber signaling, as well as via Static configuration. 241 Dynamic YANG Subscriptions are signaled Subscriptions aimed at the 242 running datastore and are unable to impact the startup configuration. 243 They should always terminate when there is loss of transport session 244 connectivity between the Publisher and Receiver. 246 Static Subscriptions are applied via an operations interface to the 247 startup and running configurations. Loss or non-availability of 248 transport session connectivity will place the Subscription into the 249 suspended state. Logic beyond the scope of this specification will 250 dictate when any particular Subscription should be reactivated. 251 There are three models for Subscription establishment and 252 maintenance: 254 1. Dynamic YANG Subscription: Subscriber and Receiver are the same 256 2. Static YANG Subscription 258 3. Dynamic YANG Subscription: Subscriber and Receiver are different 260 The first two are described in this section. The third is described 261 in Appendix A. This third option can be moved into the body of this 262 specification should the IETF community desire. In theory, all three 263 models may be intermixed in a single deployment. Figure 2 shows such 264 a scenario. 266 .---------------. 267 | Publisher | 268 '---------------' 269 ^ ^ | ^ 270 | | | | 271 .-----Restconf----' | | '-----Restconf----. 272 | .-----' '-HTTP-. | 273 V | V | 274 .-------------. .------------. .----------. .------------. 275 | Subscriber+ | | Operations | | Receiver | | Subscriber | 276 | Receiver | | /Config | '----------' '------------' 277 '-------------' '------------' ^ ^ ^ 278 ^ (out of scope) : : : 279 : ^ : :....Model 3....: 280 Model 1 :...Model 2...: (out of scope) 282 3.3.1. Dynamic YANG Subscription: Subscriber and Receiver are the same 284 With all Dynamic YANG Subscriptions, as with [netconf-yang-push] it 285 must be possible to configure and manage Subscriptions via signaling. 286 This signaling is transported over [restconf]. Once established, 287 streaming Subscription Updates are then delivered via Restconf SSE. 289 3.3.2. Static YANG Subscription 291 With a Static YANG Subscription, all information needed to establish 292 a secure object push relationship with that Receiver must be 293 configured via a configuration interface on the Publisher. This 294 information includes all the information 295 identified in section 3.3.1. This information also includes the 296 Receiver address, encoding selection, and any security credentials 297 required to establish TLS between the Publisher and Receiver. 298 Mechanisms for locally configuring these parameters are outside the 299 scope of this document. 301 With this information, the Publisher will establish a secure 302 transport connection with the Receiver and then begin pushing the 303 streaming updates to the Receiver. Since Restconf might not exist on 304 the Receiver, it is not desirable to require that updates be pushed 305 via Restconf. In place of Restconf, a TLS secured HTTP Client 306 connection must be established with an HTTP Server located on the 307 Receiver. Subscription Updates will then be sent via HTTP Post 308 messages to the Receiver. 310 Post messages will be addressed to HTTP augmentation code on the 311 Receiver capable accepting and responding to Subscription Updates. 312 At least the initial Post message must include the URI for the 313 subscribed resource. This URI can be retained for future use by the 314 Receiver. 316 After successful receipt of an initial Subscription Update for a 317 particular Subscription, this augmentation should reply back with an 318 HTTP status code of 201 (Created). Further successful receipts 319 should result in the return of code of 202 (Accepted). At any point, 320 receipt of any status codes from 300-510 with the exception of 408 321 (Request Timeout) should result in the movement of the Subscription 322 to the suspended state. A sequential series of multiple 408 323 exceptions should also drive the Subscription to a suspended state. 325 Security on an HTTP client/Publisher can be strengthened by only 326 accepting Response code feedback for recently initiated HTTP POSTs. 328 Figure 3 depicts this message flow. 330 +-----------+ +----------+ 331 | Publisher | | Receiver | 332 +-----------+ +----------+ 333 |<--------------TLS------------>| 334 | | 335 |HTTP POST (Sub ID, URI, data1) | 336 |------------------------------>| 337 | HTTP 201 (Created)| 338 |<------------------------------| 339 |HTTP POST (Sub ID, data2) | 340 |------------------------------>| 341 | HTTP 200 or 202 (Accepted)| 342 |<------------------------------| 343 | data3 | 344 |<----------------------------->| 346 If HTTP/2 transport is available to a Receiver, the Publisher should 347 also: 349 o point individual Subscription Updates to a unique HTTP/2 stream 350 for that Subscription, 352 o take any subscription-priority and provision it into the HTTP/2 353 stream priority, and 355 o take any subscription-dependency and provision it into the HTTP/2 356 stream dependency. 358 3.4. Negotiation of Subscription Policies 360 When using signaling to create a Dynamic YANG Subscription, 361 negotiable parameters will include the same negotiable parameters 362 defined within [netconf-yang-push]. 364 Additionally, negotiation may also include Subscription Priority. A 365 Publisher may accept a Subscriber asserted Priority, as well as 366 rejecting a subscription with a hint at what priority might be 367 accepted. 369 3.5. Support for Periodic and On-change 371 Implementations must support periodic and/or on-change subscriptions 372 as defined in [netconf-yang-push]. 374 3.6. Filters and Streams 376 Implementations must support filters and streams as defined in 377 [netconf-yang-push]. 379 3.7. Authorization 381 Same authorization model for data as [netconf-yang-push] will be 382 used. This includes functions of the Netconf Access Control Model 383 [RFC6536] applied to objects to be pushed via Restconf. 385 A Subscription (including a Static YANG Subscription) may only be 386 established if the Subscriber or some entity statically configuring 387 via the Publisher's operational interface has read access to the 388 target data node. 390 3.8. Subscription Multiplexing 392 When pushed directly over HTTP/2, it is expected that each 393 Subscription Update will be allocated a separate Stream. The will 394 enable multiplexing, and address issues of Head-of-line blocking with 395 different priority Subscriptions. 397 When pushed via Restconf over HTTP/2, different Subscriptions will 398 not be mapped to independent HTTP/2 streams. When Restconf specifies 399 this mapping, it should be integrated into this specification. 401 Even without HTTP/2 multiplexing, it is possible that updates might 402 be delivered in a different sequence than generated. Reasons for 403 this might include (but are not limited to): 405 o different durations needed to create various Subscription Updates, 407 o marshalling and bundling of multiple Subscription Updates for 408 transport, and 410 o parallel HTTP1.1 sessions 412 Therefore each Subscription Update will include a microsecond level 413 timestamp to ensure that a receiver understands the time when a that 414 update was generated. Use of this timestamp can give an indication 415 of the state of objects at a Publisher when state-entangled 416 information is received across different subscriptions. The use of 417 the latest Subscription Update timestamp for a particular object 418 update can introduce errors. So when state-entangled updates have 419 inconsistent object values and temporally close timestamps, a 420 Receiver might consider performing a 'get' to validate the current 421 state of objects. 423 3.9. Push Data Stream and Transport Mapping 425 Transported updates will contain data for one or more Subscription 426 Updates. Each transported Subscription Update notification contains 427 several parameters: 429 o A global subscription ID correlator, referencing the name of the 430 Subscription on whose behalf the notification is sent. 432 o Data nodes containing a representation of the datastore subtree 433 containing the updates. The set of data nodes must be filtered 434 per access control rules to contain only data that the subscriber 435 is authorized to see. 437 o An event time which contains the time stamp at publisher when the 438 event is generated. 440 3.9.1. Pushing Subscription Updates via Restconf 442 Subscribers can dynamically learn whether a RESTCONF server supports 443 yang-push. This is done by issuing an HTTP request OPTIONS, HEAD, or 444 GET on the stream push-update. E.g.: 446 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 447 streams/stream=yang-push HTTP/1.1 448 Host: example.com 449 Accept: application/yang.data+xml 451 If the server supports it, it may respond 453 HTTP/1.1 200 OK 454 Content-Type: application/yang.api+xml 455 456 yang-push 457 Yang push stream 458 459 xml 460 https://example.com/streams/yang-push-xml 461 462 463 464 json 465 https://example.com/streams/yang-push-json 466 467 468 470 If the server does not support yang push, it may respond 471 HTTP/1.1 404 Not Found 472 Date: Mon, 25 Apr 2012 11:10:30 GMT 473 Server: example-server 475 Subscribers can determine the URL to receive updates by sending an 476 HTTP GET request for the "location" leaf with the stream list entry. 477 The stream to use for yang push is the push-update stream. The 478 location returned by the publisher can be used for the actual 479 notification subscription. Note that different encodings are 480 supporting using different locations. For example, he subscriber 481 might send the following request: 483 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 484 streams/stream=yang-push/access=xml/location HTTP/1.1 485 Host: example.com 486 Accept: application/yang.data+xml 488 The publisher might send the following response: 490 HTTP/1.1 200 OK 491 Content-Type: application/yang.api+xml 492 494 https://example.com/streams/yang-push-xml 495 497 To subscribe and start receiving updates, the subscriber can then 498 send an HTTP GET request for the URL returned by the publisher in the 499 request above. The accept header must be "text/event -stream". The 500 publisher handles the connection as an event stream, using the Server 501 Sent Events[W3C-20121211] transport strategy. 503 The publisher MUST support as query parameters for a GET method on 504 this resource all the parameters of a subscription. The only 505 exception is the encoding, which is embedded in the URI. An example 506 of this is: 508 // subtree filter = /foo 509 // periodic updates, every 5 seconds 510 GET /mystreams/yang-push?subscription-id=my-sub&period=5& 511 xpath-filter=%2Fex:foo[starts-with("bar"."some"] 513 Should the publisher not support the requested subscription, it may 514 reply: 516 HTTP/1.1 501 Not Implemented 517 Date: Mon, 23 Apr 2012 17:11:00 GMT 518 Server: example-server 519 Content-Type: application/yang.errors+xml 520 521 522 application 523 operation-not-supported 524 error 525 Xpath filters not supported 526 527 529 530 531 532 533 535 with an equivalent JSON encoding representation of: 537 HTTP/1.1 501 Not Implemented 538 Date: Mon, 23 Apr 2012 17:11:00 GMT 539 Server: example-server 540 Content-Type: application/yang.errors+json 541 { 542 "ietf-restconf:errors": { 543 "error": { 544 "error-type": "protocol", 545 "error-tag": "operation-not-supported", 546 "error-message": "Xpath filters not supported." 547 "error-info": { 548 "datastore-push:supported-subscription": { 549 "subtree-filter": [null] 550 } 551 } 552 } 553 } 554 } 556 The following is an example of a push Subscription Update data for 557 the subscription above. It contains a subtree with root foo that 558 contains a leaf called bar: 560 XML encoding representation: 561 562 563 565 my-sub 566 567 2015-03-09T19:14:56Z 568 570 571 some_string 572 573 574 576 Or with the equivalent YANG over JSON encoding representation as 577 defined in[yang-json] : 579 { 580 "ietf-restconf:notification": { 581 "datastore-push:subscription-id": "my-sub", 582 "eventTime": "2015-03-09T19:14:56Z", 583 "datastore-push:datastore-contents": { 584 "example-mod:foo": { "bar": "some_string" } 585 } 586 } 587 } 589 To modify a subscription, the subscriber issues another GET request 590 on the provided URI using the same subscription-id as in the original 591 request. For example, to modify the update period to 10 seconds, the 592 subscriber may send: 594 GET /mystreams/yang-push?subscription-id=my-sub&period=10& 595 subtree-filter=%2Ffoo' 597 To delete a subscription, the subscriber issues a DELETE request on 598 the provided URI using the same subscription-id as in the original 599 request 601 DELETE /mystreams/yang-push?subscription-id=my-sub 603 3.9.2. Pushing Subscription Updates directly via HTTP 605 For any version of HTTP, the basic encoding will look as below is the 606 above JSON representation wrapped in an HTTP header. Mechanism will 607 be 608 POST (IP+Port) HTTP/1.1 609 From: (Identifier for Network Element) 610 User-Agent: (CiscoYANGPubSub/1.0) 611 Content-Type: multipart/form-data 612 Content-Length: (determined runtime) 613 { 614 "ietf-yangpush:notification": { 615 "datastore-push:subscription-id": "my-sub", 616 "eventTime": "2015-03-09T19:14:56Z", 617 "datastore-push:datastore-contents": { 618 "foo": { "bar": "some_string" } 619 } 620 } 621 } 623 3.10. YANG Tree 625 Below is the object tree for the model. All items are imported from 626 [netconf-yang-push] except for the addition of "subscription- 627 priority" and "subscription-dependency". 629 module: ietf-restconf-yang-push 630 +-ro system-streams 631 | +-ro system-stream* system-stream 632 +-rw filters 633 | +-rw filter* [filter-id] 634 | +-rw filter-id filter-id 635 | +-rw subtree-filter? subtree-filter 636 | +-rw xpath-filter? yang:xpath1.0 637 +-rw subscription-config 638 | +-rw datastore-push-subscription* [subscription-id] 639 | +--rw datastore-push-subscription* [subscription-id] 640 | +--rw subscription-id subscription-id 641 | +--rw target-datastore? datastore 642 | +--rw stream? system-stream 643 | +--rw encoding? encoding 644 | +--rw start-time? yang:date-and-time 645 | +--rw stop-time? yang:date-and-time 646 | +--rw (update-trigger)? 647 | | +--:(periodic) 648 | | | +--rw period? yang:timeticks 649 | | +--:(on-change) 650 | | +--rw no-synch-on-start? empty 651 | | +--rw dampening-period yang:timeticks 652 | | +--rw excluded-change* change-type 653 | +--rw (filterspec)? 654 | | +--:(inline) 655 | | | +--rw subtree-filter? subtree-filter 656 | | | +--rw xpath-filter? yang:xpath1.0 657 | | +--:(by-reference) 658 | | +--rw filter-ref? filter-ref 659 | +--rw receiver-address 660 | | +-rw (push-base-transport)? 661 | | +-:(tcpudp) 662 | | +-rw tcpudp 663 | | +-rw address? inet:host 664 | | +-rw port? inet:port-number 665 | +--rw subscription-priority? uint8 666 | +--rw subscription-dependency? string 667 +-ro subscriptions 668 +--ro datastore-push-subscription* [subscription-id] 669 +--ro subscription-id subscription-id 670 +--ro configured-subscription? empty 671 +--ro subscription-status? identityref 672 +--ro target-datastore? datastore 673 +--ro stream? system-stream 674 +--ro encoding? encoding 675 +--ro start-time? yang:date-and-time 676 +--ro stop-time? yang:date-and-time 677 +--ro (update-trigger)? 678 | +--:(periodic) 679 | | +--ro period? yang:timeticks 680 | +--:(on-change) 681 | +--ro no-synch-on-start? empty 682 | +--ro dampening-period yang:timeticks 683 | +--ro excluded-change* change-type 684 +--ro (filterspec)? 685 | +--:(inline) 686 | | +--ro subtree-filter? subtree-filter 687 | | +--ro xpath-filter? yang:xpath1.0 688 | +--:(by-reference) 689 | +--ro filter-ref? filter-ref 690 +--ro receiver-address 691 | +--ro (push-base-transport)? 692 | +--:(tcpudp) 693 | +--ro tcpudp 694 | +--ro address? inet:host 695 | +--ro port? inet:port-number 696 +--rw subscription-priority? uint8 697 +--rw subscription-dependency? string 699 4. YANG Module 701 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-push"; 703 prefix "rc-push"; 704 import ietf-datastore-push { 705 prefix ds-push; 706 } 708 organization 709 "IETF NETCONF (Network Configuration) Working Group"; 711 contact 712 "WG Web: 713 WG List: 715 WG Chair: Mahesh Jethanandani 716 718 WG Chair: Mehmet Ersue 719 721 Editor: Eric Voit 722 724 Editor: Alexander Clemm 725 727 Editor: Ambika Prasad Tripathy 728 730 Editor: Einar Nilsen-Nygaard 731 733 Editor: Alberto Gonzalez Prieto 734 "; 736 description 737 "This module contains conceptual YANG specifications for 738 Restconf datastore push."; 740 revision 2015-10-01 { 741 description 742 "Initial revision."; 743 reference "restconf YANG Datastore push"; 744 } 746 grouping subscription-qos { 747 description 748 "This grouping describes Quality of Service information 749 concerning a subscription. This information is passed to lower 750 layers for transport priortization and treatment"; 751 leaf subscription-priority { 752 type uint8; 753 description 754 "Relative priority for a subscription. Allows an underlying 755 transport layer perform informed load balance allocations 756 between various subscriptions"; 757 } 758 leaf subscription-dependency { 759 type string; 760 description 761 "Provides the Subscription ID of a parent subscription 762 without which this subscription should not exist. In 763 other words, there is no reason to stream these objects 764 if another subscription is missing."; 765 } 766 } 768 augment "/ds-push:subscription-config/" + 769 "ds-push:datastore-push-subscription" { 770 description 771 "Aguments configured subscriptions with QoS parameters."; 772 uses subscription-qos; 773 } 775 augment "/ds-push:subscriptions/" + 776 "ds-push:datastore-push-subscription" { 777 description 778 "Aguments the list of currently active subscriptions 779 with QoS parameters."; 780 uses subscription-qos; 781 } 783 augment "/ds-push:create-subscription/" + 784 "ds-push:input" { 785 description 786 "Aguments the create subscription rpc with QoS parameters."; 787 uses subscription-qos; 788 } 790 augment "/ds-push:modify-subscription/" + 791 "ds-push:input" { 792 description 793 "Aguments the modify subscription rpc with QoS parameters."; 794 uses subscription-qos; 795 } 797 } 799 5. Security Considerations 801 Subscriptions could be used to intentionally or accidentally overload 802 resources of a Publisher. For this reason, it is important that the 803 Publisher has the ability to prioritize the establishment and push of 804 updates where there might be resource exhaust potential. In 805 addition, a server needs to be able to suspend existing subscriptions 806 when needed. When this occurs, the subscription status must be 807 updated accordingly and the clients are notified. 809 A Subscription could be used to retrieve data in subtrees that a 810 client has not authorized access to. Therefore it is important that 811 data pushed via a Subscription is authorized equivalently with 812 regular data retrieval operations. Data being pushed to a client 813 needs therefore to be filtered accordingly, just like if the data 814 were being retrieved on-demand. The Netconf Authorization Control 815 Model [RFC6536] applies. 817 One or more Publishers could be used to overwhelm a Receiver which 818 doesn't even support subscriptions. Therefore Updates MUST only be 819 transmittable over Encrypted transports. Clients which do not want 820 pushed data need only terminate or refuse any transport sessions from 821 the Publisher. 823 One or more Publishers could overwhelm a Receiver which is unable to 824 control or handle the volume of Updates received. In deployments 825 where this might be a concern, transports supporting per-subscription 826 Flow Control and Prioritization (such as HTTP/2) should be selected. 828 Another benefit is that a well-behaved Publisher implementation is 829 that it is difficult to a Publisher to perform a DoS attack on a 830 Receiver. DoS attack protection comes from: 832 o the requirement for trust of a TLS session before publication, 834 o the need for an HTTP transport augmentation on the Receiver, and 836 o that the Publication process is suspended when the Receiver 837 doesn't respond. 839 6. References 841 6.1. Normative References 843 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 844 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 845 RFC2119, March 1997, 846 . 848 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 849 Layer Security (TLS) and Datagram Transport Layer Security 850 (DTLS) Heartbeat Extension", RFC 6520, DOI 10.17487/ 851 RFC6520, February 2012, 852 . 854 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 855 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 856 10.17487/RFC6536, March 2012, 857 . 859 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 860 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 861 10.17487/RFC7540, May 2015, 862 . 864 6.2. Informative References 866 [call-home] 867 Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 868 July 2015, . 871 [netconf-yang-push] 872 Clemm, Alexander., Gonzalez Prieto, Alberto., and Eric. 873 Voit, "Subscribing to YANG datastore push updates", 874 October 2015, . 877 [pub-sub-reqs] 878 Voit, Eric., Clemm, Alexander., and Alberto. Gonzalez 879 Prieto, "Subscribing to datastore push updates", October 880 2015, . 883 [restconf] 884 Bierman, Andy., Bjorklund, Martin., and Kent. Watsen, 885 "RESTCONF Protocol", July 2015, 886 . 889 [W3C-20121211] 890 "Server-Sent Events, World Wide Web Consortium CR CR- 891 eventsource-20121211", December 2012, 892 . 894 [yang-json] 895 Lhotka, Ladislav., "JSON Encoding of Data Modeled with 896 YANG", October 2015, . 899 Appendix A. Dynamic YANG Subscription when the Subscriber and Receiver 900 are different 902 The methods of Sections 3.3.1 and 3.3.2 can be combined to enable 903 deployment models where the Subscriber and Receiver are different. 904 Such separation can be useful with some combination of: 906 o An operator wants any Subscriptions immediately deleted should TLS 907 connectivity be lost. (I.e., Subscriptions don't default into a 908 'Suspended' state on the Publisher.) 910 o An operator wants the Publisher to include highly restrictive 911 capacity management and security mechanisms outside of domain of 912 existing operational or programmatic interfaces. 914 o Restconf is not desired on the Receiver. 916 o The Publisher doesn't want to maintain Restconf subscriptions with 917 many Receivers. 919 To do this, first the necessary information must be signaled as part 920 of the . This includes all the information 921 described in section 3.3.2, with the exception of the security 922 credentials. (It is assumed that any security credentials required 923 for establishing any transport connections are pre-provisioned on all 924 devices.) 926 Using this set of Subscriber provided information, the same process 927 described within section 3.3.2 will be followed. There is one 928 exception. When an HTTP status code is 201 is received by the 929 Publisher, it will inform the Subscriber of Subscription 930 establishment success via its Restconf connection. 932 After successful establishment, if the Subscriber wishes to maintain 933 the state of Receiver subscriptions, it can simply place a separate 934 on-change Subscription into the "Subscriptions" subtree of the YANG 935 Datastore on the Publisher. 937 Putting it all together, the message flow is: 939 +------------+ +-----------+ +----------+ 940 | Subscriber | | Publisher | | Receiver | 941 +------------+ +-----------+ +----------+ 942 | Restconf PUT: | | 943 | | | 944 |--------------------->| | 945 | | | 946 | |<-----------TLS------------>| 947 | | | 948 | |HTTP POST (Sub ID, data1, | 949 | |(stream ID, URI?)) | 950 | |--------------------------->| 951 | | HTTP 201 (Created)| 952 | |<---------------------------| 953 | Success: HTTP 204| | 954 |<---------------------| | 955 | |HTTP POST (Sub ID, data2) | 956 | |--------------------------->| 957 | | HTTP 200 or 202 (Accepted)| 958 | |<---------------------------| 959 | | data3 | 960 | |<-------------------------->| 961 | | | 963 Appendix B. End-to-End Deployment Guidance 965 Several technologies are expected to be seen within a deployment to 966 achieve security and ease-of-use requirements. These are not 967 necessary for an implementation of this specification, but will be 968 useful to consider when considering the operational context. 970 B.1. Call Home 972 Pub/Sub implementations should have the ability to transparently 973 incorporate lower layer technologies such as Call Home so that secure 974 TLS connections are always originated from the Publisher. There is a 975 Restconf Call home function in [call-home]. For security reasons, 976 this should be implemented as desired. 978 B.2. TLS Heartbeat 980 Unlike NETCONF, HTTP sessions might not quickly allow a Subscriber to 981 recognize when the communication path has been lost from the 982 Publisher. To recognize this, it is possible for a Receiver (usually 983 the subscriber) to establish a TLS heartbeat [RFC6520]. In the case 984 where a TLS heartbeat is included, it should be sent just from 985 Receiver to Publisher. Loss of the heartbeat should result in the 986 Subscription being terminated with the Subscriber (even when the 987 Subscriber and Receiver are different). The Subscriber can then 988 attempt to re-establish the subscription if desired. If the 989 Subscription remains active on the Publisher, future receipt of 990 objects associated with that (or any other unknown) subscription ID 991 should result in a being returned to the 992 Publisher from the Receiver. 994 B.3. Putting it together 996 If Subscriber and receiver are same entity then subscriber can direct 997 send create_subscription message to publisher. Once the subscription 998 moved to accepted state, the receiver can use Server Sent Events 999 [W3C-20121211] transport strategy to subscriber event notifications 1000 for the data as defined in[restconf]. 1002 Authors' Addresses 1004 Eric Voit 1005 Cisco Systems 1007 Email: evoit@cisco.com 1009 Alexander Clemm 1010 Cisco Systems 1012 Email: alex@cisco.com 1014 Ambika Prasad Tripathy 1015 Cisco Systems 1017 Email: ambtripa@cisco.com 1019 Einar Nilsen-Nygaard 1020 Cisco Systems 1022 Email: einarnn@cisco.com 1024 Alberto Gonzalez Prieto 1025 Cisco Systems 1027 Email: albertgo@cisco.com