--- /dev/null
+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";
+ }
+ 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',
+ '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.";
+ }
+
+ 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";
+ }
+
+ 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 {
+ 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;
+ 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
+ "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";
+ }
+
+ /* 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
+ "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
+ 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.";
+ }
+ 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 {
+ 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 {
+ 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
+ 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.";
+ }
+ 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.";
+ }
+ }
+ }
+
+ 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
+ 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.";
+ }
+ }
+ }
+
+ 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.";
+ 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.";
+ }
+ }
+
+ 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'.
+
+ 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 {
+ 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;
+ 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.";
+ 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;
+ 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.";
+ }
+ }
+ }
+ 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.";
+ }
+ 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'.";
+ }
+ 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 Review / netconf.git / commitdiff