Tech-invite   3GPPspecs   RFCs   Search in Tech-invite

868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100IETF‑orgGroupsStats
in Index   Prev   Next

RFC 8639

Subscription to YANG Notifications

Pages: 77
Group: NETCONF
Proposed STD
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