Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8639

Subscription to YANG Notifications

Pages: 77
Proposed Standard
Errata
Part 1 of 4 – Pages 1 to 19
None   None   Next

Top   ToC   RFC8639 - Page 1
Internet Engineering Task Force (IETF)                           E. Voit
Request for Comments: 8639                                 Cisco Systems
Category: Standards Track                                       A. Clemm
ISSN: 2070-1721                                                Futurewei
                                                      A. Gonzalez Prieto
                                                               Microsoft
                                                       E. Nilsen-Nygaard
                                                             A. Tripathy
                                                           Cisco Systems
                                                          September 2019


                   Subscription to YANG Notifications

Abstract

This document defines a YANG data model and associated mechanisms enabling subscriber-specific subscriptions to a publisher's event streams. Applying these elements allows a subscriber to request and receive a continuous, customized feed of publisher-generated information. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8639.
Top   ToC   RFC8639 - Page 2
Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.
Top   ToC   RFC8639 - Page 3

Table of Contents

1. Introduction ....................................................3 1.1. Motivation .................................................4 1.2. Terminology ................................................4 1.3. Solution Overview ..........................................6 1.4. Relationship to RFC 5277 ...................................7 2. Solution ........................................................8 2.1. Event Streams ..............................................8 2.2. Event Stream Filters .......................................9 2.3. QoS ........................................................9 2.4. Dynamic Subscriptions .....................................10 2.5. Configured Subscriptions ..................................19 2.6. Event Record Delivery .....................................27 2.7. Subscription State Change Notifications ...................28 2.8. Subscription Monitoring ...................................33 2.9. Support for the "ietf-subscribed-notifications" YANG Module ...............................................34 3. YANG Data Model Tree Diagrams ..................................34 3.1. The "streams" Container ...................................34 3.2. The "filters" Container ...................................35 3.3. The "subscriptions" Container .............................35 4. Event Notification Subscription YANG Module ....................37 5. IANA Considerations ............................................66 6. Implementation Considerations ..................................66 7. Transport Requirements .........................................67 8. Security Considerations ........................................68 9. References .....................................................72 9.1. Normative References ......................................72 9.2. Informative References ....................................74 Appendix A. Example Configured Transport Augmentation .............75 Acknowledgments ...................................................77 Authors' Addresses ................................................77

1. Introduction

This document defines a YANG data model and associated mechanisms enabling subscriber-specific subscriptions to a publisher's event streams. This effectively enables a "subscribe, then publish" capability where the customized information needs and access permissions of each target receiver are understood by the publisher before subscribed event records are marshaled and pushed. The receiver then gets a continuous, customized feed of publisher-generated information.
Top   ToC   RFC8639 - Page 4
   While the functionality defined in this document is transport
   agnostic, transports like the Network Configuration Protocol
   (NETCONF) [RFC6241] or RESTCONF [RFC8040] can be used to configure or
   dynamically signal subscriptions.  Bindings for subscribed event
   record delivery for NETCONF and RESTCONF are defined in [RFC8640] and
   [RESTCONF-Notif], respectively.

   The YANG data model defined in this document conforms to the Network
   Management Datastore Architecture defined in [RFC8342].

1.1. Motivation

Various limitations to subscriptions as described in [RFC5277] were alleviated to some extent by the requirements provided in [RFC7923]. Resolving any remaining issues is the primary motivation for this work. Key capabilities supported by this document include: o multiple subscriptions on a single transport session o support for dynamic and configured subscriptions o modification of an existing subscription in progress o per-subscription operational counters o negotiation of subscription parameters (through the use of hints returned as part of declined subscription requests) o subscription state change notifications (e.g., publisher-driven suspension, parameter modification) o independence from transport

1.2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. o Client: Defined in [RFC8342]. o Configuration: Defined in [RFC8342]. o Configuration datastore: Defined in [RFC8342].
Top   ToC   RFC8639 - Page 5
   o  Configured subscription: A subscription installed via
      configuration into a configuration datastore.

   o  Dynamic subscription: A subscription created dynamically by a
      subscriber via a Remote Procedure Call (RPC).

   o  Event: An occurrence of something that may be of interest.
      Examples include a configuration change, a fault, a change in
      status, crossing a threshold, or an external input to the system.

   o  Event occurrence time: A timestamp matching the time an
      originating process identified as when an event happened.

   o  Event record: A set of information detailing an event.

   o  Event stream: A continuous, chronologically ordered set of events
      aggregated under some context.

   o  Event stream filter: Evaluation criteria that may be applied
      against event records in an event stream.  Event records pass the
      filter when specified criteria are met.

   o  Notification message: Information intended for a receiver
      indicating that one or more events have occurred.

   o  Publisher: An entity responsible for streaming notification
      messages per the terms of a subscription.

   o  Receiver: A target to which a publisher pushes subscribed event
      records.  For dynamic subscriptions, the receiver and subscriber
      are the same entity.

   o  Subscriber: A client able to request and negotiate a contract for
      the generation and push of event records from a publisher.  For
      dynamic subscriptions, the receiver and subscriber are the same
      entity.

   o  Subscription: A contract with a publisher, stipulating the
      information that one or more receivers wish to have pushed from
      the publisher without the need for further solicitation.

   All YANG tree diagrams used in this document follow the notation
   defined in [RFC8340].
Top   ToC   RFC8639 - Page 6

1.3. Solution Overview

This document describes a transport-agnostic mechanism for subscribing to and receiving content from an event stream in a publisher. This mechanism operates through the use of a subscription. Two types of subscriptions are supported: 1. Dynamic subscriptions, where a subscriber initiates a subscription negotiation with a publisher via an RPC. If the publisher is able to serve this request, it accepts it and then starts pushing notification messages back to the subscriber. If the publisher is not able to serve it as requested, then an error response is returned. This response MAY include hints for subscription parameters that, had they been present, may have enabled the dynamic subscription request to be accepted. 2. Configured subscriptions, which allow the management of subscriptions via a configuration so that a publisher can send notification messages to a receiver. Support for configured subscriptions is optional, with its availability advertised via a YANG feature. Additional characteristics differentiating configured from dynamic subscriptions include the following: o The lifetime of a dynamic subscription is bound by the transport session used to establish it. For connection-oriented stateful transports like NETCONF, the loss of the transport session will result in the immediate termination of any associated dynamic subscriptions. For connectionless or stateless transports like HTTP, a lack of receipt acknowledgment of a sequential set of notification messages and/or keep-alives can be used to trigger a termination of a dynamic subscription. Contrast this to the lifetime of a configured subscription. This lifetime is driven by relevant configuration being present in the publisher's applied configuration. Being tied to configuration operations implies that (1) configured subscriptions can be configured to persist across reboots and (2) a configured subscription can persist even when its publisher is fully disconnected from any network. o Configured subscriptions can be modified by any configuration client with write permission on the configuration of the subscription. Dynamic subscriptions can only be modified via an RPC request made by the original subscriber or by a change to configuration data referenced by the subscription.
Top   ToC   RFC8639 - Page 7
   Note that there is no mixing and matching of dynamic and configured
   operations on a single subscription.  Specifically, a configured
   subscription cannot be modified or deleted using RPCs defined in this
   document.  Similarly, a dynamic subscription cannot be directly
   modified or deleted by configuration operations.  It is, however,
   possible to perform a configuration operation that indirectly impacts
   a dynamic subscription.  By changing the value of a preconfigured
   filter referenced by an existing dynamic subscription, the selected
   event records passed to a receiver might change.

   Also note that transport-specific specifications based on this
   specification MUST detail the lifecycle of dynamic subscriptions as
   well as the lifecycle of configured subscriptions (if supported).

   A publisher MAY terminate a dynamic subscription at any time.
   Similarly, it MAY decide to temporarily suspend the sending of
   notification messages for any dynamic subscription, or for one or
   more receivers of a configured subscription.  Such termination or
   suspension is driven by internal considerations of the publisher.

1.4. Relationship to RFC 5277

This document is intended to provide a superset of the subscription capabilities initially defined in [RFC5277]. It is important to understand what has been reused and what has been replaced, especially when extending an existing implementation that is based on [RFC5277]. Key relationships between these two documents include the following: o This document defines a transport-independent capability; [RFC5277] is specific to NETCONF. o For the new operations, the data model defined in this document is used instead of the data model defined in Section 3.4 of [RFC5277]. o The RPC operations in this document replace the operation <create-subscription> as defined in [RFC5277], Section 4. o The <notification> message of [RFC5277], Section 4 is used. o The included contents of the "NETCONF" event stream are identical between this document and [RFC5277]. o A publisher MAY implement both the Notification Management Schema and RPCs defined in [RFC5277] and this document concurrently.
Top   ToC   RFC8639 - Page 8
   o  Unlike [RFC5277], this document enables a single transport session
      to intermix notification messages and RPCs for different
      subscriptions.

   o  A subscription "stop-time" can be specified as part of a
      notification replay.  This supports a capability analogous to the
      <stopTime> parameter of [RFC5277].  However, in this
      specification, a "stop-time" parameter can also be applied without
      replay.

2. Solution

Per the overview provided in Section 1.3, this section details the overall context, state machines, and subsystems that may be assembled to allow the subscription of events from a publisher.

2.1. Event Streams

An event stream is a named entity on a publisher; this entity exposes a continuously updating set of YANG-defined event records. An event record is an instantiation of a "notification" YANG statement. If the "notification" is defined as a child to a data node, the instantiation includes the hierarchy of nodes that identifies the data node in the datastore (see Section 7.16.2 of [RFC7950]). Each event stream is available for subscription. Identifying a) how event streams are defined (other than the NETCONF stream), b) how event records are defined/generated, and c) how event records are assigned to event streams is out of scope for this document. There is only one reserved event stream name in this document: "NETCONF". The "NETCONF" event stream contains all NETCONF event record information supported by the publisher, except where an event record has explicitly been excluded from the stream. Beyond the "NETCONF" stream, implementations MAY define additional event streams. As YANG-defined event records are created by a system, they may be assigned to one or more streams. The event record is distributed to a subscription's receiver(s) where (1) a subscription includes the identified stream and (2) subscription filtering does not exclude the event record from that receiver. Access control permissions may be used to silently exclude event records from an event stream for which the receiver has no read access. See [RFC8341], Section 3.4.6 for an example of how this might be accomplished. Note that per Section 2.7 of this document, subscription state change notifications are never filtered out.
Top   ToC   RFC8639 - Page 9
   If no access control permissions are in place for event records on an
   event stream, then a receiver MUST be allowed access to all the event
   records.  If subscriber permissions change during the lifecycle of a
   subscription and event stream access is no longer permitted, then the
   subscription MUST be terminated.

   Event records MUST NOT be delivered to a receiver in a different
   order than the order in which they were placed on an event stream.

2.2. Event Stream Filters

This document defines an extensible filtering mechanism. The filter itself is a boolean test that is placed on the content of an event record. A "false" filtering result causes the event record to be excluded from delivery to a receiver. A filter never results in information being stripped from an event record prior to that event record being encapsulated in a notification message. The two optional event stream filtering syntaxes supported are [XPATH] and subtree [RFC6241]. If no event stream filter is provided in a subscription, all event records on an event stream are to be sent.

2.3. QoS

This document provides for several Quality of Service (QoS) parameters. These parameters indicate the treatment of a subscription relative to other traffic between publisher and receiver. Included are: o A "dscp" marking to differentiate prioritization of notification messages during network transit. o A "weighting" so that bandwidth proportional to this weighting can be allocated to this subscription relative to other subscriptions. o A "dependency" upon another subscription. If the publisher supports the "dscp" feature, then a subscription with a "dscp" leaf MUST result in a corresponding Differentiated Services Code Point (DSCP) marking [RFC2474] being placed in the IP header of any resulting notification messages and subscription state change notifications. A publisher MUST respect the DSCP markings for subscription traffic egressing that publisher.
Top   ToC   RFC8639 - Page 10
   Different DSCP code points require different transport connections.
   As a result, where TCP is used, a publisher that supports the "dscp"
   feature must ensure that a subscription's notification messages are
   returned in a single TCP transport session where all traffic shares
   the subscription's "dscp" leaf value.  If this cannot be guaranteed,
   any "establish-subscription" RPC request SHOULD be rejected with a
   "dscp-unavailable" error.

   For the "weighting" parameter, when concurrently dequeuing
   notification messages from multiple subscriptions to a receiver, the
   publisher MUST allocate bandwidth to each subscription proportional
   to the weights assigned to those subscriptions.  "Weighting" is an
   optional capability of the publisher; support for it is identified
   via the "qos" feature.

   If a subscription has the "dependency" parameter set, then any
   buffered notification messages containing event records selected by
   the parent subscription MUST be dequeued prior to the notification
   messages of the dependent subscription.  If notification messages
   have dependencies on each other, the notification message queued the
   longest MUST go first.  If a "dependency" included in an RPC
   references a subscription that does not exist or is no longer
   accessible to that subscriber, that "dependency" MUST be silently
   removed.  "Dependency" is an optional capability of the publisher;
   support for it is identified via the "qos" feature.

   "Dependency" and "weighting" parameters will only be respected and
   enforced between subscriptions that share the same "dscp" leaf value.

   There are additional types of publisher capacity overload that this
   specification does not address, as they are out of scope.  For
   example, the prioritization of which subscriptions have precedence
   when the publisher CPU is overloaded is not discussed.  As a result,
   implementation choices will need to be made to address such
   considerations.

2.4. Dynamic Subscriptions

Dynamic subscriptions are managed via protocol operations (in the form of RPCs, per [RFC7950], Section 7.14) made against targets located in the publisher. These RPCs have been designed extensibly so that they may be augmented for subscription targets beyond event streams. For examples of such augmentations, see the RPC augmentations in the YANG data model provided in [RFC8641].
Top   ToC   RFC8639 - Page 11

2.4.1. Dynamic Subscription State Machine

Below is the publisher's state machine for a dynamic subscription. Each state is shown in its own box. It is important to note that such a subscription doesn't exist at the publisher until an "establish-subscription" RPC is accepted. The mere request by a subscriber to establish a subscription is not sufficient for that subscription to be externally visible. Start and end states are depicted to reflect subscription creation and deletion events. ......... : start : :.......: | establish-subscription | | .-------modify-subscription--------. v v | .-----------. .-----------. .--------. | receiver |--insufficient CPU, b/w-->| receiver | modify- '| active | | suspended | subscription | |<----CPU, b/w sufficient--| | ---------->'-----------' '-----------' | | delete/kill-subscription delete/kill- | subscription v | ......... | : end :<---------------------------------' :.......: Figure 1: Publisher's State Machine for a Dynamic Subscription Of interest in this state machine are the following: o Successful "establish-subscription" or "modify-subscription" RPCs move the subscription to the "active" state. o Failed "modify-subscription" RPCs will leave the subscription in its previous state, with no visible change to any streaming updates. o A "delete-subscription" or "kill-subscription" RPC will end the subscription, as will reaching a "stop-time".
Top   ToC   RFC8639 - Page 12
   o  A publisher may choose to suspend a subscription when there is not
      sufficient CPU or bandwidth available to service the subscription.
      This is announced to the subscriber via the "subscription-
      suspended" subscription state change notification.

   o  A suspended subscription may be modified by the subscriber (for
      example, in an attempt to use fewer resources).  Successful
      modification returns the subscription to the "active" state.

   o  Even without a "modify-subscription" request, a publisher may
      return a subscription to the "active" state when sufficient
      resources are again available.  This is announced to the
      subscriber via the "subscription-resumed" subscription state
      change notification.

2.4.2. Establishing a Dynamic Subscription

The "establish-subscription" RPC allows a subscriber to request the creation of a subscription. The input parameters of the operation are: o A "stream" name, which identifies the targeted event stream against which the subscription is applied. o An event stream filter, which may reduce the set of event records pushed. o If the transport used by the RPC supports multiple encodings, an optional "encoding" for the event records pushed. If no "encoding" is included, the encoding of the RPC MUST be used. o An optional "stop-time" for the subscription. If no "stop-time" is present, notification messages will continue to be sent until the subscription is terminated. o An optional "replay-start-time" for the subscription. The "replay-start-time" MUST be in the past and indicates that the subscription is requesting a replay of previously generated information from the event stream. For more on replay, see Section 2.4.2.1. If there is no "replay-start-time", the subscription starts immediately. If the publisher can satisfy the "establish-subscription" request, it replies with an identifier for the subscription and then immediately starts streaming notification messages.
Top   ToC   RFC8639 - Page 13
   Below is a tree diagram for "establish-subscription".  All objects
   contained in this tree are described in the YANG module in Section 4.

       +---x establish-subscription
          +---w input
          |  +---w (target)
          |  |  +--:(stream)
          |  |     +---w (stream-filter)?
          |  |     |  +--:(by-reference)
          |  |     |  |  +---w stream-filter-name
          |  |     |  |          stream-filter-ref
          |  |     |  +--:(within-subscription)
          |  |     |     +---w (filter-spec)?
          |  |     |        +--:(stream-subtree-filter)
          |  |     |        |  +---w stream-subtree-filter?   <anydata>
          |  |     |        |          {subtree}?
          |  |     |        +--:(stream-xpath-filter)
          |  |     |           +---w stream-xpath-filter?
          |  |     |                   yang:xpath1.0 {xpath}?
          |  |     +---w stream                               stream-ref
          |  |     +---w replay-start-time?
          |  |             yang:date-and-time {replay}?
          |  +---w stop-time?
          |  |       yang:date-and-time
          |  +---w dscp?                                      inet:dscp
          |  |       {dscp}?
          |  +---w weighting?                                 uint8
          |  |       {qos}?
          |  +---w dependency?
          |  |       subscription-id {qos}?
          |  +---w encoding?                                  encoding
          +--ro output
             +--ro id                            subscription-id
             +--ro replay-start-time-revision?   yang:date-and-time
                     {replay}?

            Figure 2: "establish-subscription" RPC Tree Diagram

   A publisher MAY reject the "establish-subscription" RPC for many
   reasons, as described in Section 2.4.6.  The contents of the
   resulting RPC error response MAY include details on input parameters
   that, if considered in a subsequent "establish-subscription" RPC, may
   result in successful subscription establishment.  Any such hints MUST
   be transported in a yang-data "establish-subscription-stream-error-
   info" container included in the RPC error response.
Top   ToC   RFC8639 - Page 14
   Below is a tree diagram for "establish-subscription-stream-error-
   info" RPC yang-data.  All objects contained in this tree are
   described in the YANG module in Section 4.

       yang-data establish-subscription-stream-error-info
         +--ro establish-subscription-stream-error-info
            +--ro reason?                   identityref
            +--ro filter-failure-hint?      string

           Figure 3: "establish-subscription-stream-error-info"
                        RPC yang-data Tree Diagram

2.4.2.1. Requesting a Replay of Event Records
Replay provides the ability to establish a subscription that is also capable of passing event records generated in the recent past. In other words, as the subscription initializes itself, it sends any event records in the target event stream that meet the filter criteria that have an event time that is after the "replay-start- time" and also have an event time before the "stop-time" should this "stop-time" exist. The end of these historical event records is identified via a "replay-completed" subscription state change notification. Any event records generated since the subscription establishment may then follow. For a particular subscription, all event records will be delivered in the order in which they are placed in the event stream. Replay is an optional feature that is dependent on an event stream supporting some form of logging. This document puts no restrictions on the size or form of the log, where it resides in the publisher, or when event record entries in the log are purged. The inclusion of a "replay-start-time" in an "establish-subscription" RPC indicates a replay request. If the "replay-start-time" contains a value that is earlier than what a publisher's retained history supports, then if the subscription is accepted, the actual publisher's revised start time MUST be set in the returned "replay-start-time-revision" object. A "stop-time" parameter may be included in a replay subscription. For a replay subscription, the "stop-time" MAY be earlier than the current time but MUST be later than the "replay-start-time".
Top   ToC   RFC8639 - Page 15
   If the given "replay-start-time" is later than the time marked in any
   event records retained in the replay buffer, then the publisher MUST
   send a "replay-completed" notification immediately after a successful
   "establish-subscription" RPC response.

   If an event stream supports replay, the "replay-support" leaf is
   present in the "/streams/stream" list entry for the event stream.  An
   event stream that does support replay is not expected to have an
   unlimited supply of saved notifications available to accommodate any
   given replay request.  To assess the timeframe available for replay,
   subscribers can read the leafs "replay-log-creation-time" and
   "replay-log-aged-time".  See Figure 18 for the YANG tree and
   Section 4 for the YANG module describing these elements.  The actual
   size of the replay log at any given time is a publisher-specific
   matter.  Control parameters for the replay log are outside the scope
   of this document.

2.4.3. Modifying a Dynamic Subscription

The "modify-subscription" operation permits changing the terms of an existing dynamic subscription. Dynamic subscriptions can be modified any number of times. Dynamic subscriptions can only be modified via this RPC using a transport session connecting to the subscriber. If the publisher accepts the requested modifications, it acknowledges success to the subscriber, then immediately starts sending event records based on the new terms. Subscriptions created by configuration cannot be modified via this RPC. However, configuration may be used to modify objects referenced by the subscription (such as a referenced filter).
Top   ToC   RFC8639 - Page 16
   Below is a tree diagram for "modify-subscription".  All objects
   contained in this tree are described in the YANG module in Section 4.

       +---x modify-subscription
          +---w input
             +---w id
             |       subscription-id
             +---w (target)
             |  +--:(stream)
             |     +---w (stream-filter)?
             |        +--:(by-reference)
             |        |  +---w stream-filter-name
             |        |          stream-filter-ref
             |        +--:(within-subscription)
             |           +---w (filter-spec)?
             |              +--:(stream-subtree-filter)
             |              |  +---w stream-subtree-filter?   <anydata>
             |              |          {subtree}?
             |              +--:(stream-xpath-filter)
             |                 +---w stream-xpath-filter?
             |                         yang:xpath1.0 {xpath}?
             +---w stop-time?
                     yang:date-and-time

             Figure 4: "modify-subscription" RPC Tree Diagram

   If the publisher accepts the requested modifications on a currently
   suspended subscription, the subscription will immediately be resumed
   (i.e., the modified subscription is returned to the "active" state).
   The publisher MAY immediately suspend this newly modified
   subscription through the "subscription-suspended" notification before
   any event records are sent.

   If the publisher rejects the RPC request, the subscription remains as
   it was prior to the request.  That is, the request has no impact
   whatsoever.  Rejection of the RPC for any reason is indicated via an
   RPC error as described in Section 2.4.6.  The contents of such a
   rejected RPC MAY include hints on inputs that (if considered) may
   result in a successfully modified subscription.  These hints MUST be
   transported in a yang-data "modify-subscription-stream-error-info"
   container inserted into the RPC error response.
Top   ToC   RFC8639 - Page 17
   Below is a tree diagram for "modify-subscription-stream-error-info"
   RPC yang-data.  All objects contained in this tree are described in
   the YANG module in Section 4.

       yang-data modify-subscription-stream-error-info
         +--ro modify-subscription-stream-error-info
            +--ro reason?                identityref
            +--ro filter-failure-hint?   string

             Figure 5: "modify-subscription-stream-error-info"
                        RPC yang-data Tree Diagram

2.4.4. Deleting a Dynamic Subscription

The "delete-subscription" operation permits canceling an existing subscription. If the publisher accepts the request and the publisher has indicated success, the publisher MUST NOT send any more notification messages for this subscription. Below is a tree diagram for "delete-subscription". All objects contained in this tree are described in the YANG module in Section 4. +---x delete-subscription +---w input +---w id subscription-id Figure 6: "delete-subscription" RPC Tree Diagram Dynamic subscriptions can only be deleted via this RPC using a transport session connecting to the subscriber. Configured subscriptions cannot be deleted using RPCs.

2.4.5. Killing a Dynamic Subscription

The "kill-subscription" operation permits an operator to end a dynamic subscription that is not associated with the transport session used for the RPC. A publisher MUST terminate any dynamic subscription identified by the "id" parameter in the RPC request, if such a subscription exists. Configured subscriptions cannot be killed using this RPC. Instead, configured subscriptions are deleted as part of regular configuration operations. Publishers MUST reject any RPC attempt to kill a configured subscription.
Top   ToC   RFC8639 - Page 18
   Below is a tree diagram for "kill-subscription".  All objects
   contained in this tree are described in the YANG module in Section 4.

       +---x kill-subscription
          +---w input
             +---w id     subscription-id

              Figure 7: "kill-subscription" RPC Tree Diagram

2.4.6. RPC Failures

Whenever an RPC is unsuccessful, the publisher returns relevant information as part of the RPC error response. Transport-level error processing MUST be done before the RPC error processing described in this section. In all cases, RPC error information returned by the publisher will use existing transport-layer RPC structures, such as those seen with NETCONF (Appendix A of [RFC6241]) or RESTCONF (Section 7.1 of [RFC8040]). These structures MUST be able to encode subscription-specific errors identified below and defined in this document's YANG data model. As a result of this variety, how subscription errors are encoded in an RPC error response is transport dependent. Valid errors that can occur for each RPC are as follows: establish-subscription modify-subscription ---------------------- ---------------------- dscp-unavailable filter-unsupported encoding-unsupported insufficient-resources filter-unsupported no-such-subscription insufficient-resources replay-unsupported delete-subscription kill-subscription ---------------------- ---------------------- no-such-subscription no-such-subscription To see a NETCONF-based example of an error response from the list above, see the "no-such-subscription" error response illustrated in [RFC8640], Figure 10.
Top   ToC   RFC8639 - Page 19
   There is one final set of transport-independent RPC error elements
   included in the YANG data model defined in this document: three
   yang-data structures that enable the publisher to provide to the
   receiver any error information that does not fit into existing
   transport-layer RPC structures.  These structures are:

   1.  "establish-subscription-stream-error-info": This MUST be returned
       with the leaf "reason" populated if an RPC error reason has not
       been placed elsewhere in the transport portion of a failed
       "establish-subscription" RPC response.  This MUST be sent if
       hints on how to overcome the RPC error are included.

   2.  "modify-subscription-stream-error-info": This MUST be returned
       with the leaf "reason" populated if an RPC error reason has not
       been placed elsewhere in the transport portion of a failed
       "modify-subscription" RPC response.  This MUST be sent if hints
       on how to overcome the RPC error are included.

   3.  "delete-subscription-error-info": This MUST be returned with the
       leaf "reason" populated if an RPC error reason has not been
       placed elsewhere in the transport portion of a failed
       "delete-subscription" or "kill-subscription" RPC response.



(page 19 continued on part 2)

Next Section