summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8639.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc8639.txt')
-rw-r--r--doc/rfc/rfc8639.txt4315
1 files changed, 4315 insertions, 0 deletions
diff --git a/doc/rfc/rfc8639.txt b/doc/rfc/rfc8639.txt
new file mode 100644
index 0000000..cbeb4e5
--- /dev/null
+++ b/doc/rfc/rfc8639.txt
@@ -0,0 +1,4315 @@
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 1]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 2]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+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.
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 3]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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].
+
+
+
+
+
+Voit, et al. Standards Track [Page 4]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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].
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 5]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+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.
+
+
+
+
+Voit, et al. Standards Track [Page 6]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+Voit, et al. Standards Track [Page 7]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+Voit, et al. Standards Track [Page 8]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 9]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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].
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 10]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+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".
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 11]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+Voit, et al. Standards Track [Page 12]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 13]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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".
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 14]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 15]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 16]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 17]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 18]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 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.
+
+2.5. Configured Subscriptions
+
+ A configured subscription is a subscription installed via
+ configuration. Configured subscriptions may be modified by any
+ configuration client with the proper permissions. Subscriptions can
+ be modified or terminated via configuration at any point during their
+ lifetime. Multiple configured subscriptions MUST be supportable over
+ a single transport session.
+
+ Configured subscriptions have several characteristics distinguishing
+ them from dynamic subscriptions:
+
+ o persistence across publisher reboots,
+
+ o persistence even when transport is unavailable, and
+
+ o an ability to send notification messages to more than one
+ receiver. (Note that receivers are unaware of the existence of
+ any other receivers.)
+
+ On the publisher, support for configured subscriptions is optional
+ and advertised using the "configured" feature. On a receiver of a
+ configured subscription, support for dynamic subscriptions is
+ optional. However, if replaying missed event records is required for
+
+
+
+
+Voit, et al. Standards Track [Page 19]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ a configured subscription, support for dynamic subscription is highly
+ recommended. In this case, a separate dynamic subscription can be
+ established to retransmit the missing event records.
+
+ In addition to the subscription parameters available to dynamic
+ subscriptions as described in Section 2.4.2, the following additional
+ parameters are also available to configured subscriptions:
+
+ o A "transport", which identifies the transport protocol to use to
+ connect with all subscription receivers.
+
+ o One or more receivers, each intended as the destination for event
+ records. Note that each individual receiver is identifiable by
+ its "name".
+
+ o Optional parameters to identify where traffic should egress a
+ publisher:
+
+ * A "source-interface", which identifies the egress interface to
+ use from the publisher. Publisher support for this parameter
+ is optional and advertised using the "interface-designation"
+ feature.
+
+ * A "source-address" address, which identifies the IP address to
+ stamp on notification messages destined for the receiver.
+
+ * A "source-vrf", which identifies the Virtual Routing and
+ Forwarding (VRF) instance on which to reach receivers. This
+ VRF is a network instance as defined in [RFC8529]. Publisher
+ support for VRFs is optional and advertised using the
+ "supports-vrf" feature.
+
+ If none of the above parameters are set, notification messages
+ MUST egress the publisher's default interface.
+
+ A tree diagram that includes these parameters is provided in
+ Figure 20 in Section 3.3. These parameters are described in the YANG
+ module in Section 4.
+
+2.5.1. Configured Subscription State Machine
+
+ Below is the state machine for a configured subscription on the
+ publisher. This state machine describes the three states ("valid",
+ "invalid", and "concluded") as well as the transitions between these
+ states. Start and end states are depicted to reflect configured
+ subscription creation and deletion events. The creation or
+ modification of a configured subscription initiates an evaluation by
+ the publisher to determine if the subscription is in the
+
+
+
+Voit, et al. Standards Track [Page 20]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ "valid" state or the "invalid" state. The publisher uses its own
+ criteria in making this determination. If in the "valid" state, the
+ subscription becomes operational. See (1) in the diagram below.
+
+ .........
+ : start :-.
+ :.......: |
+ create .---modify-----.----------------------------------.
+ | | | |
+ V V .-------. ....... .---------.
+ .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded|
+ | '-------' :.....: '---------'
+ |-[evaluate]--no-(2). ^ ^ ^
+ | ^ | | | |
+ yes | '->unsupportable delete stop-time
+ | modify (subscription- (subscription- (subscription-
+ | | terminated*) terminated*) concluded*)
+ | | | | |
+ (1) | (3) (4) (5)
+ | .---------------------------------------------------------------.
+ '-->| valid |
+ '---------------------------------------------------------------'
+
+ Legend:
+ Dotted boxes: subscription added or removed via configuration
+ Dashed boxes: states for a subscription
+ [evaluate]: decision point on whether the subscription
+ is supportable
+ (*): resulting subscription state change notification
+
+ Figure 8: Publisher's State Machine for a Configured Subscription
+
+ A subscription in the "valid" state may move to the "invalid" state
+ in one of two ways. First, it may be modified in a way that fails a
+ re-evaluation. See (2) in the diagram. Second, the publisher might
+ determine that the subscription is no longer supportable. This could
+ be because of an unexpected but sustained increase in an event
+ stream's event records, degraded CPU capacity, a more complex
+ referenced filter, or other subscriptions that have usurped
+ resources. See (3) in the diagram. No matter the case, a
+ "subscription-terminated" notification is sent to any receivers in
+ the "active" or "suspended" state. A subscription in the
+ "valid" state may also transition to the "concluded" state via (5) if
+ a configured stop time has been reached. In this case, a
+ "subscription-concluded" notification is sent to any receivers in the
+ "active" or "suspended" state. Finally, a subscription may be
+ deleted by configuration (4).
+
+
+
+
+Voit, et al. Standards Track [Page 21]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ When a subscription is in the "valid" state, a publisher will attempt
+ to connect with all receivers of a configured subscription and
+ deliver notification messages. Below is the state machine for each
+ receiver of a configured subscription. This receiver state machine
+ is fully contained in the state machine of the configured
+ subscription and is only relevant when the configured subscription is
+ in the "valid" state.
+
+ .-----------------------------------------------------------------.
+ | valid |
+ | .----------. .------------. |
+ | | receiver |---timeout---------------->| receiver | |
+ | |connecting|<----------------reset--(c)|disconnected| |
+ | | |<-transport '------------' |
+ | '----------' loss,reset------------------------------. |
+ | (a) | | |
+ | subscription- (b) (b) |
+ | started* .--------. .---------. |
+ | '----->| |(d)-insufficient CPU,------->| | |
+ | |receiver| buffer overflow |receiver | |
+ | subscription-| active | |suspended| |
+ | modified* | |<----CPU, b/w sufficient,-(e)| | |
+ | '---->'--------' subscription-modified* '---------' |
+ '-----------------------------------------------------------------'
+
+ Legend:
+ Dashed boxes that include the word "receiver" show the possible
+ states for an individual receiver of a valid configured
+ subscription.
+
+ * indicates a subscription state change notification
+
+ Figure 9: Receiver State Machine for a Configured Subscription
+ on a Publisher
+
+ When a configured subscription first moves to the "valid" state, the
+ "state" leaf of each receiver is initialized to the "connecting"
+ state. If transport connectivity is not available to any receivers
+ and there are any notification messages to deliver, a transport
+ session is established (e.g., per [RFC8071]). Individual receivers
+ are moved to the "active" state when a "subscription-started"
+ subscription state change notification is successfully passed to that
+ receiver (a). Event records are only sent to active receivers.
+ Receivers of a configured subscription remain active on the publisher
+ if both (1) transport connectivity to the receiver is active and
+ (2) event records are not being dropped due to a publisher's sending
+ capacity being reached. In addition, a configured subscription's
+ receiver MUST be moved to the "connecting" state if the receiver is
+
+
+
+Voit, et al. Standards Track [Page 22]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ reset via the "reset" action (b), (c). For more on the "reset"
+ action, see Section 2.5.5. If transport connectivity cannot be
+ achieved while in the "connecting" state, the receiver MAY be moved
+ to the "disconnected" state.
+
+ A configured subscription's receiver MUST be moved to the "suspended"
+ state if there is transport connectivity between the publisher and
+ receiver but (1) delivery of notification messages is failing due to
+ a publisher's buffer capacity being reached or (2) notification
+ messages cannot be generated for that receiver due to insufficient
+ CPU (d). This is indicated to the receiver by the "subscription-
+ suspended" subscription state change notification.
+
+ A configured subscription's receiver MUST be returned to the "active"
+ state from the "suspended" state when notification messages can be
+ generated, bandwidth is sufficient to handle the notification
+ messages, and a receiver has successfully been sent a "subscription-
+ resumed" or "subscription-modified" subscription state change
+ notification (e). The choice as to which of these two subscription
+ state change notifications is sent is determined by whether the
+ subscription was modified during the period of suspension.
+
+ Modification of a configured subscription is possible at any time. A
+ "subscription-modified" subscription state change notification will
+ be sent to all active receivers, immediately followed by notification
+ messages conforming to the new parameters. Suspended receivers will
+ also be informed of the modification. However, this notification
+ will await the end of the suspension for that receiver (e).
+
+ The mechanisms described above are mirrored in the RPCs and
+ notifications defined in this document. It should be noted that
+ these RPCs and notifications have been designed to be extensible and
+ allow subscriptions into targets other than event streams. For
+ instance, the YANG module defined in Section 5 of [RFC8641] augments
+ "/sn:modify-subscription/sn:input/sn:target".
+
+2.5.2. Creating a Configured Subscription
+
+ Configured subscriptions are established using configuration
+ operations against the top-level "subscriptions" subtree.
+
+ Because there is no explicit association with an existing transport
+ session, configuration operations MUST include additional parameters
+ beyond those of dynamic subscriptions. These parameters identify
+ each receiver, how to connect with that receiver, and possibly
+ whether the notification messages need to come from a specific egress
+
+
+
+
+
+Voit, et al. Standards Track [Page 23]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ interface on the publisher. Receiver-specific transport connectivity
+ parameters MUST be configured via transport-specific augmentations to
+ this specification. See Section 2.5.7 for details.
+
+ After a subscription is successfully established, the publisher
+ immediately sends a "subscription-started" subscription state change
+ notification to each receiver. It is quite possible that upon
+ configuration, reboot, or even steady-state operations, a transport
+ session may not be currently available to the receiver. In this
+ case, when there is something to transport for an active
+ subscription, transport-specific "call home" operations [RFC8071]
+ will be used to establish the connection. When transport
+ connectivity is available, notification messages may then be pushed.
+
+ With active configured subscriptions, it is allowable to buffer event
+ records even after a "subscription-started" has been sent. However,
+ if events are lost (rather than just delayed) due to replay buffer
+ capacity being reached, a new "subscription-started" must be sent.
+ This new "subscription-started" indicates an event record
+ discontinuity.
+
+ To see an example of subscription creation using configuration
+ operations over NETCONF, see Appendix A.
+
+2.5.3. Modifying a Configured Subscription
+
+ Configured subscriptions can be modified using configuration
+ operations against the top-level "subscriptions" subtree.
+
+ If the modification involves adding receivers, added receivers are
+ placed in the "connecting" state. If a receiver is removed, the
+ subscription state change notification "subscription-terminated" is
+ sent to that receiver if that receiver is active or suspended.
+
+ If the modification involves changing the policies for the
+ subscription, the publisher sends to currently active receivers a
+ "subscription-modified" notification. For any suspended receivers, a
+ "subscription-modified" notification will be delayed until the
+ receiver's subscription has been resumed. (Note: In this case, the
+ "subscription-modified" notification informs the receiver that the
+ subscription has been resumed, so no additional "subscription-
+ resumed" need be sent. Also note that if multiple modifications have
+ occurred during the suspension, only the "subscription-modified"
+ notification describing the latest one need be sent to the receiver.)
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 24]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+2.5.4. Deleting a Configured Subscription
+
+ Subscriptions can be deleted through configuration against the
+ top-level "subscriptions" subtree.
+
+ Immediately after a subscription is successfully deleted, the
+ publisher sends to all receivers of that subscription a subscription
+ state change notification stating that the subscription has ended
+ (i.e., "subscription-terminated").
+
+2.5.5. Resetting a Configured Subscription's Receiver
+
+ It is possible that a configured subscription to a receiver needs to
+ be reset. This is accomplished via the "reset" action in the YANG
+ module at "/subscriptions/subscription/receivers/receiver/reset".
+ This action may be useful in cases where a publisher has timed out
+ trying to reach a receiver. When such a reset occurs, a transport
+ session will be initiated if necessary, and a new "subscription-
+ started" notification will be sent. This action does not have any
+ effect on transport connectivity if the needed connectivity already
+ exists.
+
+2.5.6. Replay for a Configured Subscription
+
+ It is possible to do replay on a configured subscription. This is
+ supported via the configuration of the "configured-replay" object on
+ the subscription. The setting of this object enables the streaming
+ of the buffered event records for the subscribed event stream. All
+ buffered event records that have been retained since the last
+ publisher restart will be sent to each configured receiver.
+
+ Replay of event records created since restart is useful. It allows
+ event records generated before transport connectivity establishment
+ to be passed to a receiver. Setting the restart time as the earliest
+ configured replay time precludes the possibility of resending event
+ records that were logged prior to publisher restart. It also ensures
+ that the same records will be sent to each configured receiver,
+ regardless of the speed of transport connectivity establishment to
+ each receiver. Finally, by establishing restart as the earliest
+ potential time for event records to be included in notification
+ messages, a well-understood timeframe for replay is defined.
+
+ As a result, when any configured subscription's receivers become
+ active, buffered event records will be sent immediately after the
+ "subscription-started" notification. If the publisher knows the last
+ event record sent to a receiver and the publisher has not rebooted,
+ the next event record on the event stream that meets filtering
+ criteria will be the leading event record sent. Otherwise, the
+
+
+
+Voit, et al. Standards Track [Page 25]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ leading event record will be the first event record meeting filtering
+ criteria subsequent to the latest of three different times: the
+ "replay-log-creation-time", the "replay-log-aged-time", or the most
+ recent publisher boot time. The "replay-log-creation-time" and
+ "replay-log-aged-time" are discussed in Section 2.4.2.1. The most
+ recent publisher boot time ensures that duplicate event records are
+ not replayed from a previous time the publisher was booted.
+
+ It is quite possible that a receiver might want to retrieve event
+ records from an event stream prior to the latest boot. If such
+ records exist where there is a configured replay, the publisher MUST
+ send the time of the event record immediately preceding the
+ "replay-start-time" in the "replay-previous-event-time" leaf.
+ Through the existence of the "replay-previous-event-time", the
+ receiver will know that earlier events prior to reboot exist. In
+ addition, if the subscriber was previously receiving event records
+ with the same subscription "id", the receiver can determine if there
+ was a time gap where records generated on the publisher were not
+ successfully received. And with this information, the receiver may
+ choose to dynamically subscribe to retrieve any event records placed
+ in the event stream before the most recent boot time.
+
+ All other replay functionality remains the same as with dynamic
+ subscriptions as described in Section 2.4.2.1.
+
+2.5.7. Transport Connectivity for a Configured Subscription
+
+ This specification is transport independent. However, supporting a
+ configured subscription will often require the establishment of
+ transport connectivity. And the parameters used for this transport
+ connectivity establishment are transport specific. As a result, the
+ YANG module defined in Section 4 is not able to directly define and
+ expose these transport parameters.
+
+ It is necessary for an implementation to support the connection
+ establishment process. To support this function, the YANG data model
+ defined in this document includes a node where transport-specific
+ parameters for a particular receiver may be augmented. This node is
+ "/subscriptions/subscription/receivers/receiver". By augmenting
+ transport parameters from this node, system developers are able to
+ incorporate the YANG objects necessary to support the transport
+ connectivity establishment process.
+
+ The result of this is the following requirement. A publisher
+ supporting the feature "configured" MUST also support at least one
+ YANG data model that augments transport connectivity parameters on
+ "/subscriptions/subscription/receivers/receiver". For an example of
+ such an augmentation, see Appendix A.
+
+
+
+Voit, et al. Standards Track [Page 26]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+2.6. Event Record Delivery
+
+ Whether dynamic or configured, once a subscription has been set up,
+ the publisher streams event records via notification messages per the
+ terms of the subscription. For dynamic subscriptions, notification
+ messages are sent over the session used to establish the
+ subscription. For configured subscriptions, notification messages
+ are sent over the connections specified by the transport and each
+ receiver of a configured subscription.
+
+ A notification message is sent to a receiver when an event record is
+ not blocked by either the specified filter criteria or receiver
+ permissions. This notification message MUST include an <eventTime>
+ object, as shown in [RFC5277], Section 4. This <eventTime> MUST be
+ at the top level of a YANG structured event record.
+
+ The following example of XML [W3C.REC-xml-20081126], adapted from
+ Section 4.2.10 of [RFC7950], illustrates a compliant message:
+
+ <notification
+ xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+ <eventTime>2007-09-01T10:00:00Z</eventTime>
+ <link-failure xmlns="https://acme.example.com/system">
+ <if-name>so-1/2/3.0</if-name>
+ <if-admin-status>up</if-admin-status>
+ <if-oper-status>down</if-oper-status>
+ </link-failure>
+ </notification>
+
+ Figure 10: Subscribed Notification Message
+
+ [RFC5277], Section 2.2.1 states that a notification message is to be
+ sent to a subscriber that initiated a <create-subscription>. With
+ this document, this statement from [RFC5277] should be more broadly
+ interpreted to mean that notification messages can also be sent to a
+ subscriber that initiated an "establish-subscription" or to a
+ configured receiver that has been sent a "subscription-started".
+
+ When a dynamic subscription has been started or modified with
+ "establish-subscription" or "modify-subscription", respectively,
+ event records matching the newly applied filter criteria MUST NOT be
+ sent until after the RPC reply has been sent.
+
+ When a configured subscription has been started or modified, event
+ records matching the newly applied filter criteria MUST NOT be sent
+ until after the "subscription-started" or "subscription-modified"
+ notification has been sent, respectively.
+
+
+
+
+Voit, et al. Standards Track [Page 27]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+2.7. Subscription State Change Notifications
+
+ In addition to sending event records to receivers, a publisher MUST
+ also send subscription state change notifications when events related
+ to subscription management have occurred.
+
+ Subscription state change notifications are unlike other
+ notifications in that they are never included in any event stream.
+ Instead, they are inserted (as defined in this section) into the
+ sequence of notification messages sent to a particular receiver.
+ Subscription state change notifications cannot be dropped or filtered
+ out, they cannot be stored in replay buffers, and they are delivered
+ only to impacted receivers of a subscription. The identification of
+ subscription state change notifications is easy to separate from
+ other notification messages through the use of the YANG extension
+ "subscription-state-notif". This extension tags a notification as a
+ subscription state change notification.
+
+ The complete set of subscription state change notifications is
+ described in the following subsections.
+
+2.7.1. "subscription-started"
+
+ This notification indicates that a configured subscription has
+ started, and event records may be sent. Included in this
+ subscription state change notification are all the parameters of the
+ subscription, except for (1) transport connection information for one
+ or more receivers and (2) origin information indicating where
+ notification messages will egress the publisher. Note that if a
+ referenced filter from the "filters" container has been used in the
+ subscription, the notification still provides the contents of that
+ referenced filter under the "within-subscription" subtree.
+
+ Note that for dynamic subscriptions, no "subscription-started"
+ notifications are ever sent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 28]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ Below is a tree diagram for "subscription-started". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n subscription-started {configured}?
+ +--ro id
+ | subscription-id
+ +--ro (target)
+ | +--:(stream)
+ | +--ro (stream-filter)?
+ | | +--:(by-reference)
+ | | | +--ro stream-filter-name
+ | | | stream-filter-ref
+ | | +--:(within-subscription)
+ | | +--ro (filter-spec)?
+ | | +--:(stream-subtree-filter)
+ | | | +--ro stream-subtree-filter? <anydata>
+ | | | {subtree}?
+ | | +--:(stream-xpath-filter)
+ | | +--ro stream-xpath-filter? yang:xpath1.0
+ | | {xpath}?
+ | +--ro stream stream-ref
+ | +--ro replay-start-time?
+ | | yang:date-and-time {replay}?
+ | +--ro replay-previous-event-time?
+ | yang:date-and-time {replay}?
+ +--ro stop-time?
+ | yang:date-and-time
+ +--ro dscp? inet:dscp
+ | {dscp}?
+ +--ro weighting? uint8 {qos}?
+ +--ro dependency?
+ | subscription-id {qos}?
+ +--ro transport? transport
+ | {configured}?
+ +--ro encoding? encoding
+ +--ro purpose? string
+ {configured}?
+
+ Figure 11: "subscription-started" Notification Tree Diagram
+
+2.7.2. "subscription-modified"
+
+ This notification indicates that a subscription has been modified by
+ configuration operations. It is delivered directly after the last
+ event records processed using the previous subscription parameters,
+ and before any event records processed after the modification.
+
+
+
+
+
+Voit, et al. Standards Track [Page 29]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ Below is a tree diagram for "subscription-modified". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n subscription-modified
+ +--ro id
+ | subscription-id
+ +--ro (target)
+ | +--:(stream)
+ | +--ro (stream-filter)?
+ | | +--:(by-reference)
+ | | | +--ro stream-filter-name
+ | | | stream-filter-ref
+ | | +--:(within-subscription)
+ | | +--ro (filter-spec)?
+ | | +--:(stream-subtree-filter)
+ | | | +--ro stream-subtree-filter? <anydata>
+ | | | {subtree}?
+ | | +--:(stream-xpath-filter)
+ | | +--ro stream-xpath-filter? yang:xpath1.0
+ | | {xpath}?
+ | +--ro stream stream-ref
+ | +--ro replay-start-time?
+ | yang:date-and-time {replay}?
+ +--ro stop-time?
+ | yang:date-and-time
+ +--ro dscp? inet:dscp
+ | {dscp}?
+ +--ro weighting? uint8 {qos}?
+ +--ro dependency?
+ | subscription-id {qos}?
+ +--ro transport? transport
+ | {configured}?
+ +--ro encoding? encoding
+ +--ro purpose? string
+ {configured}?
+
+ Figure 12: "subscription-modified" Notification Tree Diagram
+
+ A publisher most often sends this notification directly after the
+ modification of any configuration parameters impacting a configured
+ subscription. But it may also be sent at two other times:
+
+ 1. If a configured subscription has been modified during the
+ suspension of a receiver, the notification will be delayed until
+ the receiver's suspension is lifted. In this situation, the
+ notification indicates that the subscription has been both
+ modified and resumed.
+
+
+
+
+Voit, et al. Standards Track [Page 30]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 2. A "subscription-modified" subscription state change notification
+ MUST be sent if the contents of the filter identified by the
+ subscription's "stream-filter-ref" leaf have changed. This state
+ change notification is to be sent for a filter change impacting
+ any active receivers of a configured or dynamic subscription.
+
+2.7.3. "subscription-terminated"
+
+ This notification indicates that no further event records for this
+ subscription should be expected from the publisher. A publisher may
+ terminate the sending of event records to a receiver for the
+ following reasons:
+
+ 1. Configuration that removes a configured subscription, or a
+ "kill-subscription" RPC that ends a dynamic subscription. These
+ are identified via the reason "no-such-subscription".
+
+ 2. A referenced filter is no longer accessible. This reason is
+ identified by the "filter-unavailable" identity.
+
+ 3. The event stream referenced by a subscription is no longer
+ accessible by the receiver. This reason is identified by the
+ "stream-unavailable" identity.
+
+ 4. A suspended subscription has exceeded some timeout. This reason
+ is identified by the "suspension-timeout" identity.
+
+ Each reason listed above derives from the "subscription-terminated-
+ reason" base identity specified in the YANG data model in this
+ document.
+
+ Below is a tree diagram for "subscription-terminated". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n subscription-terminated
+ +--ro id subscription-id
+ +--ro reason identityref
+
+ Figure 13: "subscription-terminated" Notification Tree Diagram
+
+ Note: This subscription state change notification MUST be sent to a
+ dynamic subscription's receiver when the subscription ends
+ unexpectedly. This might happen when a "kill-subscription" RPC is
+ successful or when some other event, not including reaching the
+ subscription's "stop-time", results in a publisher choosing to end
+ the subscription.
+
+
+
+
+
+Voit, et al. Standards Track [Page 31]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+2.7.4. "subscription-suspended"
+
+ This notification indicates that a publisher has suspended the
+ sending of event records to a receiver and also indicates the
+ possible loss of events. Suspension happens when capacity
+ constraints stop a publisher from serving a valid subscription. The
+ two conditions where this is possible are:
+
+ 1. "insufficient-resources", when a publisher is unable to produce
+ the requested event stream of notification messages, and
+
+ 2. "unsupportable-volume", when the bandwidth needed to get
+ generated notification messages to a receiver exceeds a
+ threshold.
+
+ These conditions are encoded in the "reason" object. No further
+ notifications will be sent until the subscription resumes or is
+ terminated.
+
+ Below is a tree diagram for "subscription-suspended". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n subscription-suspended
+ +--ro id subscription-id
+ +--ro reason identityref
+
+ Figure 14: "subscription-suspended" Notification Tree Diagram
+
+2.7.5. "subscription-resumed"
+
+ This notification indicates that a previously suspended subscription
+ has been resumed under the unmodified terms previously in place.
+ Subscribed event records generated after the issuance of this
+ subscription state change notification may now be sent.
+
+ Below is a tree diagram for "subscription-resumed". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n subscription-resumed
+ +--ro id subscription-id
+
+ Figure 15: "subscription-resumed" Notification Tree Diagram
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 32]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+2.7.6. "subscription-completed"
+
+ This notification indicates that a subscription that includes a
+ "stop-time" has successfully finished passing event records upon
+ reaching that time.
+
+ Below is a tree diagram for "subscription-completed". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n subscription-completed {configured}?
+ +--ro id subscription-id
+
+ Figure 16: "subscription-completed" Notification Tree Diagram
+
+2.7.7. "replay-completed"
+
+ This notification indicates that all of the event records prior to
+ the current time have been passed to a receiver. It is sent before
+ any notification messages containing an event record with a timestamp
+ later than (1) the "stop-time" or (2) the subscription's start time.
+
+ If a subscription does not contain a "stop-time" or has a "stop-time"
+ that has not been reached, then after the "replay-completed"
+ notification has been sent, additional event records will be sent in
+ sequence as they arise naturally on the publisher.
+
+ Below is a tree diagram for "replay-completed". All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +---n replay-completed {replay}?
+ +--ro id subscription-id
+
+ Figure 17: "replay-completed" Notification Tree Diagram
+
+2.8. Subscription Monitoring
+
+ In the operational state datastore, the "subscriptions" container
+ maintains the state of all dynamic subscriptions as well as all
+ configured subscriptions. Using datastore retrieval operations
+ [RFC8641] or subscribing to the "subscriptions" container
+ (Section 3.3) allows the state of subscriptions and their
+ connectivity to receivers to be monitored.
+
+ Each subscription in the operational state datastore is represented
+ as a list element. Included in this list are event counters for each
+ receiver, the state of each receiver, and the subscription parameters
+ currently in effect. The appearance of the leaf "configured-
+ subscription-state" indicates that a particular subscription came
+
+
+
+Voit, et al. Standards Track [Page 33]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ into being via configuration. This leaf also indicates whether the
+ current state of that subscription is "valid", "invalid", or
+ "concluded".
+
+ To understand the flow of event records in a subscription, there are
+ two counters available for each receiver. The first counter is
+ "sent-event-records", which shows the number of events identified for
+ sending to a receiver. The second counter is "excluded-event-
+ records", which shows the number of event records not sent to a
+ receiver. "excluded-event-records" shows the combined results of
+ both access control and per-subscription filtering. For configured
+ subscriptions, counters are reset whenever the subscription's state
+ is evaluated as "valid" (see (1) in Figure 8).
+
+ Dynamic subscriptions are removed from the operational state
+ datastore once they expire (reaching "stop-time") or when they are
+ terminated. While many subscription objects are shown as
+ configurable, dynamic subscriptions are only included in the
+ operational state datastore and as a result are not configurable.
+
+2.9. Support for the "ietf-subscribed-notifications" YANG Module
+
+ Publishers supporting this document MUST indicate support of the YANG
+ module "ietf-subscribed-notifications" in the YANG library of the
+ publisher. In addition, if supported, the optional features
+ "encode-xml", "encode-json", "configured", "supports-vrf", "qos",
+ "xpath", "subtree", "interface-designation", "dscp", and "replay"
+ MUST be indicated.
+
+3. YANG Data Model Tree Diagrams
+
+ This section contains tree diagrams for nodes defined in Section 4.
+ For tree diagrams of subscription state change notifications, see
+ Section 2.7. For the tree diagrams for the RPCs, see Section 2.4.
+
+3.1. The "streams" Container
+
+ A publisher maintains a list of available event streams as
+ operational data. This list contains both standardized and
+ vendor-specific event streams. This enables subscribers to discover
+ what streams a publisher supports.
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 34]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ Below is a tree diagram for the "streams" container. All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +--ro streams
+ +--ro stream* [name]
+ +--ro name string
+ +--ro description string
+ +--ro replay-support? empty {replay}?
+ +--ro replay-log-creation-time yang:date-and-time
+ | {replay}?
+ +--ro replay-log-aged-time? yang:date-and-time
+ {replay}?
+
+ Figure 18: "streams" Container Tree Diagram
+
+3.2. The "filters" Container
+
+ The "filters" container maintains a list of all subscription filters
+ that persist outside the lifecycle of a single subscription. This
+ enables predefined filters that may be referenced by more than one
+ subscription.
+
+ Below is a tree diagram for the "filters" container. All objects
+ contained in this tree are described in the YANG module in Section 4.
+
+ +--rw filters
+ +--rw stream-filter* [name]
+ +--rw name string
+ +--rw (filter-spec)?
+ +--:(stream-subtree-filter)
+ | +--rw stream-subtree-filter? <anydata> {subtree}?
+ +--:(stream-xpath-filter)
+ +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
+
+ Figure 19: "filters" Container Tree Diagram
+
+3.3. The "subscriptions" Container
+
+ The "subscriptions" container maintains a list of all subscriptions
+ on a publisher, both configured and dynamic. It can be used to
+ retrieve information about the subscriptions that a publisher is
+ serving.
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 35]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ Below is a tree diagram for the "subscriptions" container. All
+ objects contained in this tree are described in the YANG module in
+ Section 4.
+
+ +--rw subscriptions
+ +--rw subscription* [id]
+ +--rw id
+ | subscription-id
+ +--rw (target)
+ | +--:(stream)
+ | +--rw (stream-filter)?
+ | | +--:(by-reference)
+ | | | +--rw stream-filter-name
+ | | | stream-filter-ref
+ | | +--:(within-subscription)
+ | | +--rw (filter-spec)?
+ | | +--:(stream-subtree-filter)
+ | | | +--rw stream-subtree-filter? <anydata>
+ | | | {subtree}?
+ | | +--:(stream-xpath-filter)
+ | | +--rw stream-xpath-filter?
+ | | yang:xpath1.0 {xpath}?
+ | +--rw stream stream-ref
+ | +--ro replay-start-time?
+ | | yang:date-and-time {replay}?
+ | +--rw configured-replay? empty
+ | {configured,replay}?
+ +--rw stop-time?
+ | yang:date-and-time
+ +--rw dscp? inet:dscp
+ | {dscp}?
+ +--rw weighting? uint8 {qos}?
+ +--rw dependency?
+ | subscription-id {qos}?
+ +--rw transport? transport
+ | {configured}?
+ +--rw encoding? encoding
+ +--rw purpose? string
+ | {configured}?
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 36]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ +--rw (notification-message-origin)? {configured}?
+ | +--:(interface-originated)
+ | | +--rw source-interface?
+ | | if:interface-ref {interface-designation}?
+ | +--:(address-originated)
+ | +--rw source-vrf?
+ | | -> /ni:network-instances/network-instance/name
+ | | {supports-vrf}?
+ | +--rw source-address?
+ | inet:ip-address-no-zone
+ +--ro configured-subscription-state? enumeration
+ | {configured}?
+ +--rw receivers
+ +--rw receiver* [name]
+ +--rw name string
+ +--ro sent-event-records?
+ | yang:zero-based-counter64
+ +--ro excluded-event-records?
+ | yang:zero-based-counter64
+ +--ro state enumeration
+ +---x reset {configured}?
+ +--ro output
+ +--ro time yang:date-and-time
+
+ Figure 20: "subscriptions" Container Tree Diagram
+
+4. Event Notification Subscription YANG Module
+
+ This module imports typedefs from [RFC6991], [RFC8343], [RFC8341],
+ [RFC8529], and [RFC8040]. It references [RFC6241], [XPATH] ("XML
+ Path Language (XPath) Version 1.0"), [RFC7049], [RFC8259], [RFC7950],
+ [RFC7951], and [RFC7540].
+
+<CODE BEGINS> file "ietf-subscribed-notifications@2019-09-09.yang"
+module ietf-subscribed-notifications {
+ yang-version 1.1;
+ namespace "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";
+ prefix sn;
+
+ import ietf-inet-types {
+ prefix inet;
+ reference
+ "RFC 6991: Common YANG Data Types";
+ }
+ import ietf-interfaces {
+ prefix if;
+ reference
+ "RFC 8343: A YANG Data Model for Interface Management";
+
+
+
+Voit, et al. Standards Track [Page 37]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ }
+ import ietf-netconf-acm {
+ prefix nacm;
+ reference
+ "RFC 8341: Network Configuration Access Control Model";
+ }
+ import ietf-network-instance {
+ prefix ni;
+ reference
+ "RFC 8529: YANG Data Model for Network Instances";
+ }
+ import ietf-restconf {
+ prefix rc;
+ reference
+ "RFC 8040: RESTCONF Protocol";
+ }
+ import ietf-yang-types {
+ prefix yang;
+ reference
+ "RFC 6991: Common YANG Data Types";
+ }
+
+ organization
+ "IETF NETCONF (Network Configuration) Working Group";
+ contact
+ "WG Web: <https:/datatracker.ietf.org/wg/netconf/>
+ WG List: <mailto:netconf@ietf.org>
+
+ Author: Alexander Clemm
+ <mailto:ludwig@clemm.org>
+
+ Author: Eric Voit
+ <mailto:evoit@cisco.com>
+
+ Author: Alberto Gonzalez Prieto
+ <mailto:alberto.gonzalez@microsoft.com>
+
+ Author: Einar Nilsen-Nygaard
+ <mailto:einarnn@cisco.com>
+
+ Author: Ambika Prasad Tripathy
+ <mailto:ambtripa@cisco.com>";
+ description
+ "This module defines a YANG data model for subscribing to event
+ records and receiving matching content in notification messages.
+
+ The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
+ NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
+
+
+
+Voit, et al. Standards Track [Page 38]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ 'MAY', and 'OPTIONAL' in this document are to be interpreted as
+ described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
+ they appear in all capitals, as shown here.
+
+ Copyright (c) 2019 IETF Trust and the persons identified as
+ authors of the code. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or
+ without modification, is permitted pursuant to, and subject to
+ the license terms contained in, the Simplified BSD License set
+ forth in Section 4.c of the IETF Trust's Legal Provisions
+ Relating to IETF Documents
+ (https://trustee.ietf.org/license-info).
+
+ This version of this YANG module is part of RFC 8639; see the
+ RFC itself for full legal notices.";
+
+ revision 2019-09-09 {
+ description
+ "Initial version.";
+ reference
+ "RFC 8639: A YANG Data Model for Subscriptions to
+ Event Notifications";
+ }
+
+ /*
+ * FEATURES
+ */
+
+ feature configured {
+ description
+ "This feature indicates that configuration of subscriptions is
+ supported.";
+ }
+
+ feature dscp {
+ description
+ "This feature indicates that a publisher supports the ability
+ to set the Differentiated Services Code Point (DSCP) value in
+ outgoing packets.";
+ }
+
+ feature encode-json {
+ description
+ "This feature indicates that JSON encoding of notification
+ messages is supported.";
+ }
+
+
+
+
+Voit, et al. Standards Track [Page 39]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ feature encode-xml {
+ description
+ "This feature indicates that XML encoding of notification
+ messages is supported.";
+ }
+
+ feature interface-designation {
+ description
+ "This feature indicates that a publisher supports sourcing all
+ receiver interactions for a configured subscription from a
+ single designated egress interface.";
+ }
+
+ feature qos {
+ description
+ "This feature indicates that a publisher supports absolute
+ dependencies of one subscription's traffic over another
+ as well as weighted bandwidth sharing between subscriptions.
+ Both of these are Quality of Service (QoS) features that allow
+ differentiated treatment of notification messages between a
+ publisher and a specific receiver.";
+ }
+
+ feature replay {
+ description
+ "This feature indicates that historical event record replay is
+ supported. With replay, it is possible for past event records
+ to be streamed in chronological order.";
+ }
+
+ feature subtree {
+ description
+ "This feature indicates support for YANG subtree filtering.";
+ reference
+ "RFC 6241: Network Configuration Protocol (NETCONF),
+ Section 6";
+ }
+
+ feature supports-vrf {
+ description
+ "This feature indicates that a publisher supports VRF
+ configuration for configured subscriptions. VRF support for
+ dynamic subscriptions does not require this feature.";
+ reference
+ "RFC 8529: YANG Data Model for Network Instances,
+ Section 6";
+ }
+
+
+
+
+Voit, et al. Standards Track [Page 40]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ feature xpath {
+ description
+ "This feature indicates support for XPath filtering.";
+ reference
+ "XML Path Language (XPath) Version 1.0
+ (https://www.w3.org/TR/1999/REC-xpath-19991116)";
+ }
+
+ /*
+ * EXTENSIONS
+ */
+
+ extension subscription-state-notification {
+ description
+ "This statement applies only to notifications. It indicates
+ that the notification is a subscription state change
+ notification. Therefore, it does not participate in a regular
+ event stream and does not need to be specifically subscribed
+ to in order to be received. This statement can only occur as
+ a substatement of the YANG 'notification' statement. This
+ statement is not for use outside of this YANG module.";
+ }
+
+ /*
+ * IDENTITIES
+ */
+ /* Identities for RPC and notification errors */
+
+ identity delete-subscription-error {
+ description
+ "Base identity for the problem found while attempting to
+ fulfill either a 'delete-subscription' RPC request or a
+ 'kill-subscription' RPC request.";
+ }
+
+ identity establish-subscription-error {
+ description
+ "Base identity for the problem found while attempting to
+ fulfill an 'establish-subscription' RPC request.";
+ }
+
+ identity modify-subscription-error {
+ description
+ "Base identity for the problem found while attempting to
+ fulfill a 'modify-subscription' RPC request.";
+ }
+
+ identity subscription-suspended-reason {
+
+
+
+Voit, et al. Standards Track [Page 41]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ description
+ "Base identity for the problem condition communicated to a
+ receiver as part of a 'subscription-suspended'
+ notification.";
+ }
+
+ identity subscription-terminated-reason {
+ description
+ "Base identity for the problem condition communicated to a
+ receiver as part of a 'subscription-terminated'
+ notification.";
+ }
+
+ identity dscp-unavailable {
+ base establish-subscription-error;
+ if-feature "dscp";
+ description
+ "The publisher is unable to mark notification messages with
+ prioritization information in a way that will be respected
+ during network transit.";
+ }
+
+ identity encoding-unsupported {
+ base establish-subscription-error;
+ description
+ "Unable to encode notification messages in the desired
+ format.";
+ }
+
+ identity filter-unavailable {
+ base subscription-terminated-reason;
+ description
+ "Referenced filter does not exist. This means a receiver is
+ referencing a filter that doesn't exist or to which it
+ does not have access permissions.";
+ }
+
+ identity filter-unsupported {
+ base establish-subscription-error;
+ base modify-subscription-error;
+ description
+ "Cannot parse syntax in the filter. This failure can be from
+ a syntax error or a syntax too complex to be processed by the
+ publisher.";
+ }
+
+ identity insufficient-resources {
+ base establish-subscription-error;
+
+
+
+Voit, et al. Standards Track [Page 42]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ base modify-subscription-error;
+ base subscription-suspended-reason;
+ description
+ "The publisher does not have sufficient resources to support
+ the requested subscription. An example might be that
+ allocated CPU is too limited to generate the desired set of
+ notification messages.";
+ }
+
+ identity no-such-subscription {
+ base modify-subscription-error;
+ base delete-subscription-error;
+ base subscription-terminated-reason;
+ description
+ "Referenced subscription doesn't exist. This may be as a
+ result of a nonexistent subscription ID, an ID that belongs to
+ another subscriber, or an ID for a configured subscription.";
+ }
+
+ identity replay-unsupported {
+ base establish-subscription-error;
+ if-feature "replay";
+ description
+ "Replay cannot be performed for this subscription. This means
+ the publisher will not provide the requested historic
+ information from the event stream via replay to this
+ receiver.";
+ }
+
+ identity stream-unavailable {
+ base subscription-terminated-reason;
+ description
+ "Not a subscribable event stream. This means the referenced
+ event stream is not available for subscription by the
+ receiver.";
+ }
+
+ identity suspension-timeout {
+ base subscription-terminated-reason;
+ description
+ "Termination of a previously suspended subscription. The
+ publisher has eliminated the subscription, as it exceeded a
+ time limit for suspension.";
+ }
+
+ identity unsupportable-volume {
+ base subscription-suspended-reason;
+ description
+
+
+
+Voit, et al. Standards Track [Page 43]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ "The publisher does not have the network bandwidth needed to
+ get the volume of generated information intended for a
+ receiver.";
+ }
+
+ /* Identities for encodings */
+
+ identity configurable-encoding {
+ description
+ "If a transport identity derives from this identity, it means
+ that it supports configurable encodings. An example of a
+ configurable encoding might be a new identity such as
+ 'encode-cbor'. Such an identity could use
+ 'configurable-encoding' as its base. This would allow a
+ dynamic subscription encoded in JSON (RFC 8259) to request
+ that notification messages be encoded via the Concise Binary
+ Object Representation (CBOR) (RFC 7049). Further details for
+ any specific configurable encoding would be explored in a
+ transport document based on this specification.";
+ reference
+ "RFC 8259: The JavaScript Object Notation (JSON) Data
+ Interchange Format
+ RFC 7049: Concise Binary Object Representation (CBOR)";
+ }
+
+ identity encoding {
+ description
+ "Base identity to represent data encodings.";
+ }
+
+ identity encode-xml {
+ base encoding;
+ if-feature "encode-xml";
+ description
+ "Encode data using XML as described in RFC 7950.";
+ reference
+ "RFC 7950: The YANG 1.1 Data Modeling Language";
+ }
+
+ identity encode-json {
+ base encoding;
+ if-feature "encode-json";
+ description
+ "Encode data using JSON as described in RFC 7951.";
+ reference
+ "RFC 7951: JSON Encoding of Data Modeled with YANG";
+ }
+
+
+
+
+Voit, et al. Standards Track [Page 44]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ /* Identities for transports */
+
+ identity transport {
+ description
+ "An identity that represents the underlying mechanism for
+ passing notification messages.";
+ }
+
+ /*
+ * TYPEDEFs
+ */
+
+ typedef encoding {
+ type identityref {
+ base encoding;
+ }
+ description
+ "Specifies a data encoding, e.g., for a data subscription.";
+ }
+
+ typedef stream-filter-ref {
+ type leafref {
+ path "/sn:filters/sn:stream-filter/sn:name";
+ }
+ description
+ "This type is used to reference an event stream filter.";
+ }
+
+ typedef stream-ref {
+ type leafref {
+ path "/sn:streams/sn:stream/sn:name";
+ }
+ description
+ "This type is used to reference a system-provided
+ event stream.";
+ }
+
+ typedef subscription-id {
+ type uint32;
+ description
+ "A type for subscription identifiers.";
+ }
+
+ typedef transport {
+ type identityref {
+ base transport;
+ }
+ description
+
+
+
+Voit, et al. Standards Track [Page 45]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ "Specifies the transport used to send notification messages
+ to a receiver.";
+ }
+
+ /*
+ * GROUPINGS
+ */
+
+ grouping stream-filter-elements {
+ description
+ "This grouping defines the base for filters applied to event
+ streams.";
+ choice filter-spec {
+ description
+ "The content filter specification for this request.";
+ anydata stream-subtree-filter {
+ if-feature "subtree";
+ description
+ "Event stream evaluation criteria encoded in the syntax of
+ a subtree filter as defined in RFC 6241, Section 6.
+
+ The subtree filter is applied to the representation of
+ individual, delineated event records as contained in the
+ event stream.
+
+ If the subtree filter returns a non-empty node set, the
+ filter matches the event record, and the event record is
+ included in the notification message sent to the
+ receivers.";
+ reference
+ "RFC 6241: Network Configuration Protocol (NETCONF),
+ Section 6";
+ }
+ leaf stream-xpath-filter {
+ if-feature "xpath";
+ type yang:xpath1.0;
+ description
+ "Event stream evaluation criteria encoded in the syntax of
+ an XPath 1.0 expression.
+
+ The XPath expression is evaluated on the representation of
+ individual, delineated event records as contained in
+ the event stream.
+
+ The result of the XPath expression is converted to a
+ boolean value using the standard XPath 1.0 rules. If the
+ boolean value is 'true', the filter matches the event
+ record, and the event record is included in the
+
+
+
+Voit, et al. Standards Track [Page 46]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ notification message sent to the receivers.
+
+ The expression is evaluated in the following XPath
+ context:
+
+ o The set of namespace declarations is the set of
+ prefix and namespace pairs for all YANG modules
+ implemented by the server, where the prefix is the
+ YANG module name and the namespace is as defined by
+ the 'namespace' statement in the YANG module.
+
+ If the leaf is encoded in XML, all namespace
+ declarations in scope on the 'stream-xpath-filter'
+ leaf element are added to the set of namespace
+ declarations. If a prefix found in the XML is
+ already present in the set of namespace
+ declarations, the namespace in the XML is used.
+
+ o The set of variable bindings is empty.
+
+ o The function library is comprised of the core
+ function library and the XPath functions defined in
+ Section 10 in RFC 7950.
+
+ o The context node is the root node.";
+ reference
+ "XML Path Language (XPath) Version 1.0
+ (https://www.w3.org/TR/1999/REC-xpath-19991116)
+ RFC 7950: The YANG 1.1 Data Modeling Language,
+ Section 10";
+ }
+ }
+ }
+
+ grouping update-qos {
+ description
+ "This grouping describes QoS information concerning a
+ subscription. This information is passed to lower layers
+ for transport prioritization and treatment.";
+ leaf dscp {
+ if-feature "dscp";
+ type inet:dscp;
+ default "0";
+ description
+ "The desired network transport priority level. This is the
+ priority set on notification messages encapsulating the
+ results of the subscription. This transport priority is
+ shared for all receivers of a given subscription.";
+
+
+
+Voit, et al. Standards Track [Page 47]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ }
+ leaf weighting {
+ if-feature "qos";
+ type uint8 {
+ range "0 .. 255";
+ }
+ description
+ "Relative weighting for a subscription. Larger weights get
+ more resources. Allows an underlying transport layer to
+ perform informed load-balance allocations between various
+ subscriptions.";
+ reference
+ "RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2),
+ Section 5.3.2";
+ }
+ leaf dependency {
+ if-feature "qos";
+ type subscription-id;
+ description
+ "Provides the 'subscription-id' of a parent subscription.
+ The parent subscription has absolute precedence should
+ that parent have push updates ready to egress the publisher.
+ In other words, there should be no streaming of objects from
+ the current subscription if the parent has something ready
+ to push.
+
+ If a dependency is asserted via configuration or via an RPC
+ but the referenced 'subscription-id' does not exist, the
+ dependency is silently discarded. If a referenced
+ subscription is deleted, this dependency is removed.";
+ reference
+ "RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2),
+ Section 5.3.1";
+ }
+ }
+
+ grouping subscription-policy-modifiable {
+ description
+ "This grouping describes all objects that may be changed
+ in a subscription.";
+ choice target {
+ mandatory true;
+ description
+ "Identifies the source of information against which a
+ subscription is being applied as well as specifics on the
+ subset of information desired from that source.";
+ case stream {
+ choice stream-filter {
+
+
+
+Voit, et al. Standards Track [Page 48]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ description
+ "An event stream filter can be applied to a subscription.
+ That filter will either come referenced from a global
+ list or be provided in the subscription itself.";
+ case by-reference {
+ description
+ "Apply a filter that has been configured separately.";
+ leaf stream-filter-name {
+ type stream-filter-ref;
+ mandatory true;
+ description
+ "References an existing event stream filter that is
+ to be applied to an event stream for the
+ subscription.";
+ }
+ }
+ case within-subscription {
+ description
+ "A local definition allows a filter to have the same
+ lifecycle as the subscription.";
+ uses stream-filter-elements;
+ }
+ }
+ }
+ }
+ leaf stop-time {
+ type yang:date-and-time;
+ description
+ "Identifies a time after which notification messages for a
+ subscription should not be sent. If 'stop-time' is not
+ present, the notification messages will continue until the
+ subscription is terminated. If 'replay-start-time' exists,
+ 'stop-time' must be for a subsequent time. If
+ 'replay-start-time' doesn't exist, 'stop-time', when
+ established, must be for a future time.";
+ }
+ }
+
+ grouping subscription-policy-dynamic {
+ description
+ "This grouping describes the only information concerning a
+ subscription that can be passed over the RPCs defined in this
+ data model.";
+ uses subscription-policy-modifiable {
+ augment "target/stream" {
+ description
+ "Adds additional objects that can be modified by an RPC.";
+ leaf stream {
+
+
+
+Voit, et al. Standards Track [Page 49]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ type stream-ref {
+ require-instance false;
+ }
+ mandatory true;
+ description
+ "Indicates the event stream to be considered for
+ this subscription.";
+ }
+ leaf replay-start-time {
+ if-feature "replay";
+ type yang:date-and-time;
+ config false;
+ description
+ "Used to trigger the 'replay' feature for a dynamic
+ subscription, where event records that are selected
+ need to be at or after the specified starting time. If
+ 'replay-start-time' is not present, this is not a replay
+ subscription and event record push should start
+ immediately. It is never valid to specify start times
+ that are later than or equal to the current time.";
+ }
+ }
+ }
+ uses update-qos;
+ }
+
+ grouping subscription-policy {
+ description
+ "This grouping describes the full set of policy information
+ concerning both dynamic and configured subscriptions, with the
+ exclusion of both receivers and networking information
+ specific to the publisher, such as what interface should be
+ used to transmit notification messages.";
+ uses subscription-policy-dynamic;
+ leaf transport {
+ if-feature "configured";
+ type transport;
+ description
+ "For a configured subscription, this leaf specifies the
+ transport used to deliver messages destined for all
+ receivers of that subscription.";
+ }
+ leaf encoding {
+ when 'not(../transport) or derived-from(../transport,
+ "sn:configurable-encoding")';
+ type encoding;
+ description
+ "The type of encoding for notification messages. For a
+
+
+
+Voit, et al. Standards Track [Page 50]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ dynamic subscription, if not included as part of an
+ 'establish-subscription' RPC, the encoding will be populated
+ with the encoding used by that RPC. For a configured
+ subscription, if not explicitly configured, the encoding
+ will be the default encoding for an underlying transport.";
+ }
+ leaf purpose {
+ if-feature "configured";
+ type string;
+ description
+ "Open text allowing a configuring entity to embed the
+ originator or other specifics of this subscription.";
+ }
+ }
+
+ /*
+ * RPCs
+ */
+
+ rpc establish-subscription {
+ description
+ "This RPC allows a subscriber to create (and possibly
+ negotiate) a subscription on its own behalf. If successful,
+ the subscription remains in effect for the duration of the
+ subscriber's association with the publisher or until the
+ subscription is terminated. If an error occurs or the
+ publisher cannot meet the terms of a subscription, an RPC
+ error is returned, and the subscription is not created.
+ In that case, the RPC reply's 'error-info' MAY include
+ suggested parameter settings that would have a higher
+ likelihood of succeeding in a subsequent
+ 'establish-subscription' request.";
+ input {
+ uses subscription-policy-dynamic;
+ leaf encoding {
+ type encoding;
+ description
+ "The type of encoding for the subscribed data. If not
+ included as part of the RPC, the encoding MUST be set by
+ the publisher to be the encoding used by this RPC.";
+ }
+ }
+ output {
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "Identifier used for this subscription.";
+
+
+
+Voit, et al. Standards Track [Page 51]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ }
+ leaf replay-start-time-revision {
+ if-feature "replay";
+ type yang:date-and-time;
+ description
+ "If a replay has been requested, this object represents
+ the earliest time covered by the event buffer for the
+ requested event stream. The value of this object is the
+ 'replay-log-aged-time' if it exists. Otherwise, it is
+ the 'replay-log-creation-time'. All buffered event
+ records after this time will be replayed to a receiver.
+ This object will only be sent if the starting time has
+ been revised to be later than the time requested by the
+ subscriber.";
+ }
+ }
+ }
+
+ rc:yang-data establish-subscription-stream-error-info {
+ container establish-subscription-stream-error-info {
+ description
+ "If any 'establish-subscription' RPC parameters are
+ unsupportable against the event stream, a subscription
+ is not created and the RPC error response MUST indicate the
+ reason why the subscription failed to be created. This
+ yang-data MAY be inserted as structured data in a
+ subscription's RPC error response to indicate the reason for
+ the failure. This yang-data MUST be inserted if hints are
+ to be provided back to the subscriber.";
+ leaf reason {
+ type identityref {
+ base establish-subscription-error;
+ }
+ description
+ "Indicates the reason why the subscription has failed to
+ be created to a targeted event stream.";
+ }
+ leaf filter-failure-hint {
+ type string;
+ description
+ "Information describing where and/or why a provided
+ filter was unsupportable for a subscription. The
+ syntax and semantics of this hint are
+ implementation specific.";
+ }
+ }
+ }
+
+
+
+
+Voit, et al. Standards Track [Page 52]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ rpc modify-subscription {
+ description
+ "This RPC allows a subscriber to modify a dynamic
+ subscription's parameters. If successful, the changed
+ subscription parameters remain in effect for the duration of
+ the subscription, until the subscription is again modified, or
+ until the subscription is terminated. In the case of an error
+ or an inability to meet the modified parameters, the
+ subscription is not modified and the original subscription
+ parameters remain in effect. In that case, the RPC error MAY
+ include 'error-info' suggested parameter hints that would have
+ a high likelihood of succeeding in a subsequent
+ 'modify-subscription' request. A successful
+ 'modify-subscription' will return a suspended subscription to
+ the 'active' state.";
+ input {
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "Identifier to use for this subscription.";
+ }
+ uses subscription-policy-modifiable;
+ }
+ }
+
+ rc:yang-data modify-subscription-stream-error-info {
+ container modify-subscription-stream-error-info {
+ description
+ "This yang-data MAY be provided as part of a subscription's
+ RPC error response when there is a failure of a
+ 'modify-subscription' RPC that has been made against an
+ event stream. This yang-data MUST be used if hints are to
+ be provided back to the subscriber.";
+ leaf reason {
+ type identityref {
+ base modify-subscription-error;
+ }
+ description
+ "Information in a 'modify-subscription' RPC error response
+ that indicates the reason why the subscription to an event
+ stream has failed to be modified.";
+ }
+ leaf filter-failure-hint {
+ type string;
+ description
+ "Information describing where and/or why a provided
+ filter was unsupportable for a subscription. The syntax
+
+
+
+Voit, et al. Standards Track [Page 53]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ and semantics of this hint are
+ implementation specific.";
+ }
+ }
+ }
+
+ rpc delete-subscription {
+ description
+ "This RPC allows a subscriber to delete a subscription that
+ was previously created by that same subscriber using the
+ 'establish-subscription' RPC.
+
+ If an error occurs, the server replies with an 'rpc-error'
+ where the 'error-info' field MAY contain a
+ 'delete-subscription-error-info' structure.";
+ input {
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "Identifier of the subscription that is to be deleted.
+ Only subscriptions that were created using
+ 'establish-subscription' from the same origin as this RPC
+ can be deleted via this RPC.";
+ }
+ }
+ }
+
+ rpc kill-subscription {
+ nacm:default-deny-all;
+ description
+ "This RPC allows an operator to delete a dynamic subscription
+ without restrictions on the originating subscriber or
+ underlying transport session.
+
+ If an error occurs, the server replies with an 'rpc-error'
+ where the 'error-info' field MAY contain a
+ 'delete-subscription-error-info' structure.";
+ input {
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "Identifier of the subscription that is to be deleted.
+ Only subscriptions that were created using
+ 'establish-subscription' can be deleted via this RPC.";
+ }
+ }
+
+
+
+Voit, et al. Standards Track [Page 54]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ }
+
+ rc:yang-data delete-subscription-error-info {
+ container delete-subscription-error-info {
+ description
+ "If a 'delete-subscription' RPC or a 'kill-subscription' RPC
+ fails, the subscription is not deleted and the RPC error
+ response MUST indicate the reason for this failure. This
+ yang-data MAY be inserted as structured data in a
+ subscription's RPC error response to indicate the reason
+ for the failure.";
+ leaf reason {
+ type identityref {
+ base delete-subscription-error;
+ }
+ mandatory true;
+ description
+ "Indicates the reason why the subscription has failed to be
+ deleted.";
+ }
+ }
+ }
+
+ /*
+ * NOTIFICATIONS
+ */
+
+ notification replay-completed {
+ sn:subscription-state-notification;
+ if-feature "replay";
+ description
+ "This notification is sent to indicate that all of the replay
+ notifications have been sent.";
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the affected subscription.";
+ }
+ }
+
+ notification subscription-completed {
+ sn:subscription-state-notification;
+ if-feature "configured";
+ description
+ "This notification is sent to indicate that a subscription has
+ finished passing event records, as the 'stop-time' has been
+ reached.";
+
+
+
+Voit, et al. Standards Track [Page 55]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the gracefully completed subscription.";
+ }
+ }
+
+ notification subscription-modified {
+ sn:subscription-state-notification;
+ description
+ "This notification indicates that a subscription has been
+ modified. Notification messages sent from this point on will
+ conform to the modified terms of the subscription. For
+ completeness, this subscription state change notification
+ includes both modified and unmodified aspects of a
+ subscription.";
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the affected subscription.";
+ }
+ uses subscription-policy {
+ refine "target/stream/stream-filter/within-subscription" {
+ description
+ "Filter applied to the subscription. If the
+ 'stream-filter-name' is populated, the filter in the
+ subscription came from the 'filters' container.
+ Otherwise, it is populated in-line as part of the
+ subscription.";
+ }
+ }
+ }
+
+ notification subscription-resumed {
+ sn:subscription-state-notification;
+ description
+ "This notification indicates that a subscription that had
+ previously been suspended has resumed. Notifications will
+ once again be sent. In addition, a 'subscription-resumed'
+ indicates that no modification of parameters has occurred
+ since the last time event records have been sent.";
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the affected subscription.";
+
+
+
+Voit, et al. Standards Track [Page 56]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ }
+ }
+
+ notification subscription-started {
+ sn:subscription-state-notification;
+ if-feature "configured";
+ description
+ "This notification indicates that a subscription has started
+ and notifications will now be sent.";
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the affected subscription.";
+ }
+ uses subscription-policy {
+ refine "target/stream/replay-start-time" {
+ description
+ "Indicates the time that a replay is using for the
+ streaming of buffered event records. This will be
+ populated with the most recent of the following:
+ the event time of the previous event record sent to a
+ receiver, the 'replay-log-creation-time', the
+ 'replay-log-aged-time', or the most recent publisher
+ boot time.";
+ }
+ refine "target/stream/stream-filter/within-subscription" {
+ description
+ "Filter applied to the subscription. If the
+ 'stream-filter-name' is populated, the filter in the
+ subscription came from the 'filters' container.
+ Otherwise, it is populated in-line as part of the
+ subscription.";
+ }
+ augment "target/stream" {
+ description
+ "This augmentation adds additional parameters specific to a
+ 'subscription-started' notification.";
+ leaf replay-previous-event-time {
+ when '../replay-start-time';
+ if-feature "replay";
+ type yang:date-and-time;
+ description
+ "If there is at least one event in the replay buffer
+ prior to 'replay-start-time', this gives the time of
+ the event generated immediately prior to the
+ 'replay-start-time'.
+
+
+
+
+Voit, et al. Standards Track [Page 57]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ If a receiver previously received event records for
+ this configured subscription, it can compare this time
+ to the last event record previously received. If the
+ two are not the same (perhaps due to a reboot), then a
+ dynamic replay can be initiated to acquire any missing
+ event records.";
+ }
+ }
+ }
+ }
+
+ notification subscription-suspended {
+ sn:subscription-state-notification;
+ description
+ "This notification indicates that a suspension of the
+ subscription by the publisher has occurred. No further
+ notifications will be sent until the subscription resumes.
+ This notification shall only be sent to receivers of a
+ subscription; it does not constitute a general-purpose
+ notification.";
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the affected subscription.";
+ }
+ leaf reason {
+ type identityref {
+ base subscription-suspended-reason;
+ }
+ mandatory true;
+ description
+ "Identifies the condition that resulted in the suspension.";
+ }
+ }
+
+ notification subscription-terminated {
+ sn:subscription-state-notification;
+ description
+ "This notification indicates that a subscription has been
+ terminated.";
+ leaf id {
+ type subscription-id;
+ mandatory true;
+ description
+ "This references the affected subscription.";
+ }
+ leaf reason {
+
+
+
+Voit, et al. Standards Track [Page 58]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ type identityref {
+ base subscription-terminated-reason;
+ }
+ mandatory true;
+ description
+ "Identifies the condition that resulted in the termination.";
+ }
+ }
+
+ /*
+ * DATA NODES
+ */
+
+ container streams {
+ config false;
+ description
+ "Contains information on the built-in event streams provided by
+ the publisher.";
+ list stream {
+ key "name";
+ description
+ "Identifies the built-in event streams that are supported by
+ the publisher.";
+ leaf name {
+ type string;
+ description
+ "A handle for a system-provided event stream made up of a
+ sequential set of event records, each of which is
+ characterized by its own domain and semantics.";
+ }
+ leaf description {
+ type string;
+ description
+ "A description of the event stream, including such
+ information as the type of event records that are
+ available in this event stream.";
+ }
+ leaf replay-support {
+ if-feature "replay";
+ type empty;
+ description
+ "Indicates that event record replay is available on this
+ event stream.";
+ }
+ leaf replay-log-creation-time {
+ when '../replay-support';
+ if-feature "replay";
+ type yang:date-and-time;
+
+
+
+Voit, et al. Standards Track [Page 59]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ mandatory true;
+ description
+ "The timestamp of the creation of the log used to support
+ the replay function on this event stream. This time
+ might be earlier than the earliest available information
+ contained in the log. This object is updated if the log
+ resets for some reason.";
+ }
+ leaf replay-log-aged-time {
+ when '../replay-support';
+ if-feature "replay";
+ type yang:date-and-time;
+ description
+ "The timestamp associated with the last event record that
+ has been aged out of the log. This timestamp identifies
+ how far back in history this replay log extends, if it
+ doesn't extend back to the 'replay-log-creation-time'.
+ This object MUST be present if replay is supported and any
+ event records have been aged out of the log.";
+ }
+ }
+ }
+ container filters {
+ description
+ "Contains a list of configurable filters that can be applied to
+ subscriptions. This facilitates the reuse of complex filters
+ once defined.";
+ list stream-filter {
+ key "name";
+ description
+ "A list of preconfigured filters that can be applied to
+ subscriptions.";
+ leaf name {
+ type string;
+ description
+ "A name to differentiate between filters.";
+ }
+ uses stream-filter-elements;
+ }
+ }
+ container subscriptions {
+ description
+ "Contains the list of currently active subscriptions, i.e.,
+ subscriptions that are currently in effect, used for
+ subscription management and monitoring purposes. This
+ includes subscriptions that have been set up via
+ RPC primitives as well as subscriptions that have been
+ established via configuration.";
+
+
+
+Voit, et al. Standards Track [Page 60]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ list subscription {
+ key "id";
+ description
+ "The identity and specific parameters of a subscription.
+ Subscriptions in this list can be created using a control
+ channel or RPC or can be established through configuration.
+
+ If the 'kill-subscription' RPC or configuration operations
+ are used to delete a subscription, a
+ 'subscription-terminated' message is sent to any active or
+ suspended receivers.";
+ leaf id {
+ type subscription-id;
+ description
+ "Identifier of a subscription; unique in a given
+ publisher.";
+ }
+ uses subscription-policy {
+ refine "target/stream/stream" {
+ description
+ "Indicates the event stream to be considered for this
+ subscription. If an event stream has been removed
+ and can no longer be referenced by an active
+ subscription, send a 'subscription-terminated'
+ notification with 'stream-unavailable' as the reason.
+ If a configured subscription refers to a nonexistent
+ event stream, move that subscription to the
+ 'invalid' state.";
+ }
+ refine "transport" {
+ description
+ "For a configured subscription, this leaf specifies the
+ transport used to deliver messages destined for all
+ receivers of that subscription. This object is
+ mandatory for subscriptions in the configuration
+ datastore. This object (1) is not mandatory for dynamic
+ subscriptions in the operational state datastore and
+ (2) should not be present for other types of dynamic
+ subscriptions.";
+ }
+ augment "target/stream" {
+ description
+ "Enables objects to be added to a configured stream
+ subscription.";
+ leaf configured-replay {
+ if-feature "configured";
+ if-feature "replay";
+ type empty;
+
+
+
+Voit, et al. Standards Track [Page 61]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ description
+ "The presence of this leaf indicates that replay for
+ the configured subscription should start at the
+ earliest time in the event log or at the publisher
+ boot time, whichever is later.";
+ }
+ }
+ }
+ choice notification-message-origin {
+ if-feature "configured";
+ description
+ "Identifies the egress interface on the publisher
+ from which notification messages are to be sent.";
+ case interface-originated {
+ description
+ "When notification messages are to egress a specific,
+ designated interface on the publisher.";
+ leaf source-interface {
+ if-feature "interface-designation";
+ type if:interface-ref;
+ description
+ "References the interface for notification messages.";
+ }
+ }
+ case address-originated {
+ description
+ "When notification messages are to depart from a
+ publisher using a specific originating address and/or
+ routing context information.";
+ leaf source-vrf {
+ if-feature "supports-vrf";
+ type leafref {
+ path "/ni:network-instances/ni:network-instance/ni:name";
+ }
+ description
+ "VRF from which notification messages should egress a
+ publisher.";
+ }
+ leaf source-address {
+ type inet:ip-address-no-zone;
+ description
+ "The source address for the notification messages.
+ If a source VRF exists but this object doesn't, a
+ publisher's default address for that VRF must
+ be used.";
+ }
+ }
+ }
+
+
+
+Voit, et al. Standards Track [Page 62]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ leaf configured-subscription-state {
+ if-feature "configured";
+ type enumeration {
+ enum valid {
+ value 1;
+ description
+ "The subscription is supportable with its current
+ parameters.";
+ }
+ enum invalid {
+ value 2;
+ description
+ "The subscription as a whole is unsupportable with its
+ current parameters.";
+ }
+ enum concluded {
+ value 3;
+ description
+ "A subscription is inactive, as it has hit a
+ stop time. It no longer has receivers in the
+ 'active' or 'suspended' state, but the subscription
+ has not yet been removed from configuration.";
+ }
+ }
+ config false;
+ description
+ "The presence of this leaf indicates that the subscription
+ originated from configuration, not through a control
+ channel or RPC. The value indicates the state of the
+ subscription as established by the publisher.";
+ }
+ container receivers {
+ description
+ "Set of receivers in a subscription.";
+ list receiver {
+ key "name";
+ min-elements 1;
+ description
+ "A host intended as a recipient for the notification
+ messages of a subscription. For configured
+ subscriptions, transport-specific network parameters
+ (or a leafref to those parameters) may be augmented to a
+ specific receiver in this list.";
+ leaf name {
+ type string;
+ description
+ "Identifies a unique receiver for a subscription.";
+ }
+
+
+
+Voit, et al. Standards Track [Page 63]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ leaf sent-event-records {
+ type yang:zero-based-counter64;
+ config false;
+ description
+ "The number of event records sent to the receiver. The
+ count is initialized when a dynamic subscription is
+ established or when a configured receiver
+ transitions to the 'valid' state.";
+ }
+ leaf excluded-event-records {
+ type yang:zero-based-counter64;
+ config false;
+ description
+ "The number of event records explicitly removed via
+ either an event stream filter or an access control
+ filter so that they are not passed to a receiver.
+ This count is set to zero each time
+ 'sent-event-records' is initialized.";
+ }
+ leaf state {
+ type enumeration {
+ enum active {
+ value 1;
+ description
+ "The receiver is currently being sent any
+ applicable notification messages for the
+ subscription.";
+ }
+ enum suspended {
+ value 2;
+ description
+ "The receiver state is 'suspended', so the
+ publisher is currently unable to provide
+ notification messages for the subscription.";
+ }
+ enum connecting {
+ value 3;
+ if-feature "configured";
+ description
+ "A subscription has been configured, but a
+ 'subscription-started' subscription state change
+ notification needs to be successfully received
+ before notification messages are sent.
+
+ If the 'reset' action is invoked for a receiver of
+ an active configured subscription, the state
+ must be moved to 'connecting'.";
+ }
+
+
+
+Voit, et al. Standards Track [Page 64]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ enum disconnected {
+ value 4;
+ if-feature "configured";
+ description
+ "A subscription has failed to send a
+ 'subscription-started' state change to the
+ receiver. Additional connection attempts are not
+ currently being made.";
+ }
+ }
+ config false;
+ mandatory true;
+ description
+ "Specifies the state of a subscription from the
+ perspective of a particular receiver. With this
+ information, it is possible to determine whether a
+ publisher is currently generating notification
+ messages intended for that receiver.";
+ }
+ action reset {
+ if-feature "configured";
+ description
+ "Allows the reset of this configured subscription's
+ receiver to the 'connecting' state. This enables the
+ connection process to be reinitiated.";
+ output {
+ leaf time {
+ type yang:date-and-time;
+ mandatory true;
+ description
+ "Time at which a publisher returned the receiver to
+ the 'connecting' state.";
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+<CODE ENDS>
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 65]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+5. IANA Considerations
+
+ IANA has registered one URI in the "ns" subregistry of the "IETF XML
+ Registry" [RFC3688] maintained at <https://www.iana.org/assignments/
+ xml-registry>. The following registration has been made per the
+ format in [RFC3688]:
+
+ URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
+ Registrant Contact: The NETCONF WG of the IETF.
+ XML: N/A; the requested URI is an XML namespace.
+
+ IANA has registered one YANG module in the "YANG Module Names"
+ registry [RFC6020] maintained at <https://www.iana.org/assignments/
+ yang-parameters>. The following registration has been made per the
+ format in [RFC6020]:
+
+ Name: ietf-subscribed-notifications
+ Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
+ Prefix: sn
+ Reference: RFC 8639
+
+6. Implementation Considerations
+
+ To support deployments that include both configured and dynamic
+ subscriptions, it is recommended that the subscription "id" domain be
+ split into static and dynamic halves. This will eliminate the
+ possibility of collisions if the configured subscriptions attempt to
+ set a "subscription-id" that might have already been dynamically
+ allocated. A best practice is to use the lower half of the "id"
+ object's integer space when that "id" is assigned by an external
+ entity (such as with a configured subscription). This leaves the
+ upper half of the subscription integer space available to be
+ dynamically assigned by the publisher.
+
+ If a subscription is unable to marshal a series of filtered event
+ records into transmittable notification messages, the receiver should
+ be suspended with the reason "unsupportable-volume".
+
+ For configured subscriptions, operations are performed against the
+ set of receivers using the subscription "id" as a handle for that
+ set. But for streaming updates, subscription state change
+ notifications are local to a receiver. In the case of this
+ specification, receivers do not get any information from the
+ publisher about the existence of other receivers. But if a network
+ operator wants to let the receivers correlate results, it is useful
+ to use the subscription "id" across the receivers to allow that
+
+
+
+
+
+Voit, et al. Standards Track [Page 66]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ correlation. Note that due to the possibility of different access
+ control permissions per receiver, each receiver may actually get a
+ different set of event records.
+
+ For configured replay subscriptions, the receiver is protected from
+ duplicated events being pushed after a publisher is rebooted.
+ However, it is possible that a receiver might want to acquire event
+ records that failed to be delivered just prior to the reboot.
+ Delivering these event records can be accomplished by leveraging the
+ <eventTime> [RFC5277] from the last event record received prior to
+ the receipt of a "subscription-started" subscription state change
+ notification. With this <eventTime> and the "replay-start-time" from
+ the "subscription-started" notification, an independent dynamic
+ subscription can be established that retrieves any event records that
+ may have been generated but not sent to the receiver.
+
+7. Transport Requirements
+
+ This section provides requirements for any subscribed notification
+ transport supporting the solution presented in this document.
+
+ The transport selected by the subscriber to reach the publisher MUST
+ be able to support multiple "establish-subscription" requests made in
+ the same transport session.
+
+ For both configured and dynamic subscriptions, the publisher MUST
+ authenticate a receiver via some transport-level mechanism before
+ sending any event records that the receiver is authorized to see. In
+ addition, the receiver MUST authenticate the publisher at the
+ transport level. The result is mutual authentication between
+ the two.
+
+ A secure transport is highly recommended. Beyond this, the publisher
+ MUST ensure that the receiver has sufficient authorization to perform
+ the function it is requesting against the specific subset of content
+ involved.
+
+ A specification for a transport built upon this document may or may
+ not choose to require the use of the same logical channel for the
+ RPCs and the event records. However, the event records and the
+ subscription state change notifications MUST be sent on the same
+ transport session to ensure properly ordered delivery.
+
+ A specification for a transport MUST identify any encodings that are
+ supported. If a configured subscription's transport allows different
+ encodings, the specification MUST identify the default encoding.
+
+
+
+
+
+Voit, et al. Standards Track [Page 67]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ A subscriber that includes a "dscp" leaf in an "establish-
+ subscription" request will need to understand and consider what the
+ corresponding DSCP value represents in the domain of the publisher.
+
+ Additional transport requirements will be dictated by the choice of
+ transport used with a subscription. For an example of such
+ requirements, see [RFC8640].
+
+8. Security Considerations
+
+ The YANG module specified in this document defines a schema for data
+ that is designed to be accessed via network management protocols such
+ as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
+ is the secure transport layer, and the mandatory-to-implement secure
+ transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
+ is HTTPS, and the mandatory-to-implement secure transport is TLS
+ [RFC5246].
+
+ The Network Configuration Access Control Model (NACM) [RFC8341]
+ provides the means to restrict access for particular NETCONF or
+ RESTCONF users to a preconfigured subset of all available NETCONF or
+ RESTCONF protocol operations and content.
+
+ With configured subscriptions, one or more publishers could be used
+ to overwhelm a receiver. To counter this, notification messages
+ SHOULD NOT be sent to any receiver that does not support this
+ specification. Receivers that do not want notification messages need
+ only terminate or refuse any transport sessions from the publisher.
+
+ When a receiver of a configured subscription gets a new
+ "subscription-started" message for a known subscription where it is
+ already consuming events, it may indicate that an attacker has done
+ something that has momentarily disrupted receiver connectivity. To
+ acquire events lost during this interval, the receiver SHOULD
+ retrieve any event records generated since the last event record was
+ received. This can be accomplished by establishing a separate
+ dynamic replay subscription with the same filtering criteria with the
+ publisher, assuming that the publisher supports the "replay" feature.
+
+ For dynamic subscriptions, implementations need to protect against
+ malicious or buggy subscribers that may send a large number of
+ "establish-subscription" requests and thereby use up system
+ resources. To cover this possibility, operators SHOULD monitor for
+ such cases and, if discovered, take remedial action to limit the
+ resources used, such as suspending or terminating a subset of the
+ subscriptions or, if the underlying transport is session based,
+ terminating the underlying transport session.
+
+
+
+
+Voit, et al. Standards Track [Page 68]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ The replay mechanisms described in Sections 2.4.2.1 and 2.5.6 provide
+ access to historical event records. By design, the access control
+ model that protects these records could enable subscribers to view
+ data to which they were not authorized at the time of collection.
+
+ Using DNS names for configured subscription's receiver "name" lookups
+ can cause situations where the name resolves differently than
+ expected on the publisher, so the recipient would be different than
+ expected.
+
+ An attacker that can cause the publisher to use an incorrect time can
+ induce message replay by setting the time in the past and can
+ introduce a risk of message loss by setting the time in the future.
+
+ There are a number of data nodes defined in this YANG module that are
+ writable/creatable/deletable (i.e., config true, which is the
+ default). These data nodes may be considered sensitive or vulnerable
+ in some network environments. Write operations (e.g., edit-config)
+ to these data nodes without proper protection can have a negative
+ effect on network operations. These are the subtrees and data nodes
+ and their sensitivity/vulnerability:
+
+ Container: "/filters"
+
+ o "stream-subtree-filter": Updating a filter could increase the
+ computational complexity of all referencing subscriptions.
+
+ o "stream-xpath-filter": Updating a filter could increase the
+ computational complexity of all referencing subscriptions.
+
+ Container: "/subscriptions"
+
+ The following considerations are only relevant for configuration
+ operations made upon configured subscriptions:
+
+ o "configured-replay": Can be used to send a large number of event
+ records to a receiver.
+
+ o "dependency": Can be used to force important traffic to be queued
+ behind updates that are not as important.
+
+ o "dscp": If unvalidated, can result in the sending of traffic with
+ a higher-priority marking than warranted.
+
+ o "id": Can overwrite an existing subscription, perhaps one
+ configured by another entity.
+
+
+
+
+
+Voit, et al. Standards Track [Page 69]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ o "name": Adding a new key entry can be used to attempt to send
+ traffic to an unwilling receiver.
+
+ o "replay-start-time": Can be used to push very large logs, wasting
+ resources.
+
+ o "source-address": The configured address might not be able to
+ reach a desired receiver.
+
+ o "source-interface": The configured interface might not be able to
+ reach a desired receiver.
+
+ o "source-vrf": Can place a subscription in a virtual network where
+ receivers are not entitled to view the subscribed content.
+
+ o "stop-time": Could be used to terminate content at an inopportune
+ time.
+
+ o "stream": Could set a subscription to an event stream that does
+ not contain content permitted for the targeted receivers.
+
+ o "stream-filter-name": Could be set to a filter that is not
+ relevant to the event stream.
+
+ o "stream-subtree-filter": A complex filter can increase the
+ computational resources for this subscription.
+
+ o "stream-xpath-filter": A complex filter can increase the
+ computational resources for this subscription.
+
+ o "weighting": Allocating a large weight can overwhelm the dequeuing
+ of other subscriptions.
+
+ Some of the readable data nodes in this YANG module may be considered
+ sensitive or vulnerable in some network environments. It is thus
+ important to control read access (e.g., via get, get-config, or
+ notification) to these data nodes. These are the subtrees and data
+ nodes and their sensitivity/vulnerability:
+
+ Container: "/streams"
+
+ o "name": If access control is not properly configured, can expose
+ system internals to those who should not have access to this
+ information.
+
+ o "replay-support": If access control is not properly configured,
+ can expose logs to those who should not have access.
+
+
+
+
+Voit, et al. Standards Track [Page 70]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ Container: "/subscriptions"
+
+ o "excluded-event-records": This leaf can provide information about
+ filtered event records. A network operator should have the proper
+ permissions to know about such filtering. However, exposing the
+ count of excluded events to a receiver could leak information
+ about the presence of access control filters that might be in
+ place for that receiver.
+
+ o "subscription": Different operational teams might have a desire to
+ set varying subsets of subscriptions. Access control should be
+ designed to permit read access to just the allowed set.
+
+ Some of the RPC operations in this YANG module may be considered
+ sensitive or vulnerable in some network environments. It is thus
+ important to control access to these operations. These are the
+ operations and their sensitivity/vulnerability:
+
+ RPC: all
+
+ o If a malicious or buggy subscriber sends an unexpectedly large
+ number of RPCs, the result might be an excessive use of system
+ resources on the publisher just to determine that these
+ subscriptions should be declined. In such a situation,
+ subscription interactions MAY be terminated by terminating the
+ transport session.
+
+ RPC: "delete-subscription"
+
+ o No special considerations.
+
+ RPC: "establish-subscription"
+
+ o Subscriptions could overload a publisher's resources. For this
+ reason, publishers MUST ensure that they have sufficient resources
+ to fulfill this request; otherwise, they MUST reject the request.
+
+ RPC: "kill-subscription"
+
+ o The "kill-subscription" RPC MUST be secured so that only
+ connections with administrative rights are able to invoke
+ this RPC.
+
+ RPC: "modify-subscription"
+
+ o Subscriptions could overload a publisher's resources. For this
+ reason, publishers MUST ensure that they have sufficient resources
+ to fulfill this request; otherwise, they MUST reject the request.
+
+
+
+Voit, et al. Standards Track [Page 71]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+9. References
+
+9.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <https://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black,
+ "Definition of the Differentiated Services Field (DS
+ Field) in the IPv4 and IPv6 Headers", RFC 2474,
+ DOI 10.17487/RFC2474, December 1998,
+ <https://www.rfc-editor.org/info/rfc2474>.
+
+ [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+ DOI 10.17487/RFC3688, January 2004,
+ <https://www.rfc-editor.org/info/rfc3688>.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246,
+ DOI 10.17487/RFC5246, August 2008,
+ <https://www.rfc-editor.org/info/rfc5246>.
+
+ [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
+ Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
+ <https://www.rfc-editor.org/info/rfc5277>.
+
+ [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
+ the Network Configuration Protocol (NETCONF)", RFC 6020,
+ DOI 10.17487/RFC6020, October 2010,
+ <https://www.rfc-editor.org/info/rfc6020>.
+
+ [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
+ and A. Bierman, Ed., "Network Configuration Protocol
+ (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
+ <https://www.rfc-editor.org/info/rfc6241>.
+
+ [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
+ Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
+ <https://www.rfc-editor.org/info/rfc6242>.
+
+ [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
+ RFC 6991, DOI 10.17487/RFC6991, July 2013,
+ <https://www.rfc-editor.org/info/rfc6991>.
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 72]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
+ RFC 7950, DOI 10.17487/RFC7950, August 2016,
+ <https://www.rfc-editor.org/info/rfc7950>.
+
+ [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
+ RFC 7951, DOI 10.17487/RFC7951, August 2016,
+ <https://www.rfc-editor.org/info/rfc7951>.
+
+ [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
+ Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
+ <https://www.rfc-editor.org/info/rfc8040>.
+
+ [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in
+ RFC 2119 Key Words", BCP 14, RFC 8174,
+ DOI 10.17487/RFC8174, May 2017,
+ <https://www.rfc-editor.org/info/rfc8174>.
+
+ [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
+ Access Control Model", STD 91, RFC 8341,
+ DOI 10.17487/RFC8341, March 2018,
+ <https://www.rfc-editor.org/info/rfc8341>.
+
+ [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
+ and R. Wilton, "Network Management Datastore Architecture
+ (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
+ <https://www.rfc-editor.org/info/rfc8342>.
+
+ [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
+ Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
+ <https://www.rfc-editor.org/info/rfc8343>.
+
+ [RFC8529] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
+ Liu, "YANG Data Model for Network Instances", RFC 8529,
+ DOI 10.17487/RFC8529, March 2019,
+ <https://www.rfc-editor.org/info/rfc8529>.
+
+ [W3C.REC-xml-20081126]
+ Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
+ F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
+ Edition)", World Wide Web Consortium Recommendation
+ REC-xml-20081126, November 2008,
+ <https://www.w3.org/TR/2008/REC-xml-20081126>.
+
+ [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
+ Version 1.0", November 1999,
+ <https://www.w3.org/TR/1999/REC-xpath-19991116>.
+
+
+
+
+
+Voit, et al. Standards Track [Page 73]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+9.2. Informative References
+
+ [RESTCONF-Notif]
+ Voit, E., Rahman, R., Nilsen-Nygaard, E., Clemm, A.,
+ and A. Bierman, "Dynamic subscription to YANG Events
+ and Datastores over RESTCONF", Work in Progress,
+ draft-ietf-netconf-restconf-notif-15, June 2019.
+
+ [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
+ Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
+ October 2013, <https://www.rfc-editor.org/info/rfc7049>.
+
+ [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
+ Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
+ DOI 10.17487/RFC7540, May 2015,
+ <https://www.rfc-editor.org/info/rfc7540>.
+
+ [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
+ for Subscription to YANG Datastores", RFC 7923,
+ DOI 10.17487/RFC7923, June 2016,
+ <https://www.rfc-editor.org/info/rfc7923>.
+
+ [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
+ RFC 8071, DOI 10.17487/RFC8071, February 2017,
+ <https://www.rfc-editor.org/info/rfc8071>.
+
+ [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+ Interchange Format", STD 90, RFC 8259,
+ DOI 10.17487/RFC8259, December 2017,
+ <https://www.rfc-editor.org/info/rfc8259>.
+
+ [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
+ BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
+ <https://www.rfc-editor.org/info/rfc8340>.
+
+ [RFC8640] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
+ E., and A. Tripathy, "Dynamic Subscription to YANG Events
+ and Datastores over NETCONF", RFC 8640,
+ DOI 10.17487/RFC8640, September 2019,
+ <https://www.rfc-editor.org/info/rfc8640>.
+
+ [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications
+ for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641,
+ September 2019, <https://www.rfc-editor.org/info/rfc8641>.
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 74]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+Appendix A. Example Configured Transport Augmentation
+
+ This appendix provides a non-normative example of how the YANG module
+ defined in Section 4 may be enhanced to incorporate the configuration
+ parameters needed to support the transport connectivity process.
+ This example is not intended to be a complete transport model. In
+ this example, connectivity via an imaginary transport type of "foo"
+ is explored. For more on the overall objectives behind configuring
+ transport connectivity for a configured subscription, see
+ Section 2.5.7.
+
+ The YANG module example defined in this appendix contains two main
+ elements. First is a transport identity "foo". This transport
+ identity allows a configuration agent to define "foo" as the selected
+ type of transport for a subscription. Second is a YANG case
+ augmentation "foo", which is made to the
+ "/subscriptions/subscription/receivers/receiver" node of Section 4.
+ In this augmentation are the transport configuration parameters
+ "address" and "port", which are necessary to make the connection to
+ the receiver.
+
+ module example-foo-subscribed-notifications {
+ yang-version 1.1;
+ namespace
+ "urn:example:foo-subscribed-notifications";
+
+ prefix fsn;
+
+ import ietf-subscribed-notifications {
+ prefix sn;
+ }
+ import ietf-inet-types {
+ prefix inet;
+ }
+
+ description
+ "Defines 'foo' as a supported type of configured transport for
+ subscribed event notifications.";
+
+ identity foo {
+ base sn:transport;
+ description
+ "Transport type 'foo' is available for use as a configured
+ subscription's transport protocol for subscribed
+ notifications.";
+ }
+
+
+
+
+
+Voit, et al. Standards Track [Page 75]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+ augment
+ "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" {
+ when 'derived-from(../../../transport, "fsn:foo")';
+ description
+ "This augmentation makes transport parameters specific to 'foo'
+ available for a receiver.";
+ leaf address {
+ type inet:host;
+ mandatory true;
+ description
+ "Specifies the address to use for messages destined for a
+ receiver.";
+ }
+ leaf port {
+ type inet:port-number;
+ mandatory true;
+ description
+ "Specifies the port number to use for messages destined for a
+ receiver.";
+ }
+ }
+ }
+
+ Figure 21: Example Transport Augmentation
+ for the Fictitious Protocol "foo"
+
+ This example YANG module for transport "foo" will not be seen in a
+ real-world deployment. For a real-world deployment supporting an
+ actual transport technology, a similar YANG module must be defined.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 76]
+
+RFC 8639 Subscribed Notifications September 2019
+
+
+Acknowledgments
+
+ For their valuable comments, discussions, and feedback, we wish to
+ acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen,
+ Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan
+ Hares, Michael Scharf, and Guangying Zheng.
+
+Authors' Addresses
+
+ Eric Voit
+ Cisco Systems
+
+ Email: evoit@cisco.com
+
+
+ Alexander Clemm
+ Futurewei
+
+ Email: ludwig@clemm.org
+
+
+ Alberto Gonzalez Prieto
+ Microsoft
+
+ Email: alberto.gonzalez@microsoft.com
+
+
+ Einar Nilsen-Nygaard
+ Cisco Systems
+
+ Email: einarnn@cisco.com
+
+
+ Ambika Prasad Tripathy
+ Cisco Systems
+
+ Email: ambtripa@cisco.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al. Standards Track [Page 77]
+