moduleietf-subscribed-notifications {
yang-version1.1;
namespace"urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";
prefixsn;
importietf-yang-types {
prefixyang;
}
importietf-inet-types {
prefixinet;
}
importietf-interfaces {
prefixif;
}
organization"IETF";
contact"WG Web: <http:/tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Editor: Alexander Clemm
<mailto:ludwig@clemm.org>
Editor: Eric Voit
<mailto:evoit@cisco.com>
Editor: Alberto Gonzalez Prieto
<mailto:agonzalezpri@vmware.com>
Editor: Einar Nilsen-Nygaard
<mailto:einarnn@cisco.com>
Editor: Ambika Prasad Tripathy
<mailto:ambtripa@cisco.com>";
description"Contains a YANG specification for subscribing to event records
and receiving matching content within notification messages.";
revision"2017-10-27" {
description"Initial version";
reference"draft-ietf-netconf-subscribed-notifications-06";
}
featureencode-json {
description"This feature indicates that JSON encoding of notification
messages is supported.";
}
featureencode-xml {
description"This feature indicates that XML encoding of notification
messages is supported.";
}
featureconfigured {
description"This feature indicates that configuration of subscription is
supported.";
}
featurereplay {
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.";
}
featurexpath {
description"This feature indicates support for xpath filtering.";
reference"http://www.w3.org/TR/1999/REC-xpath-19991116";
}
featuresubtree {
description"This feature indicates support for YANG subtree filtering.";
reference"RFC 6241, Section 6.";
}
extensionsubscription-state-notif {
description"This statement applies only to notifications. It indicates that
the notification is a subscription state 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 to the YANG
'notification' statement.";
}
identitysubscription-result {
basedescription"Base identity for RPC responses and State Change Notifications
providing information on the creation, modification, deletion of
subscriptions.";
}
identityok {
basesubscription-result;
description"OK - RPC was successful and was performed as requested.";
}
identityerror {
basesubscription-result;
description"Problem with subscription. Base identity for error return
codes for RPCs and State Change Notifications.";
}
identitysuspension-timeout {
baseerror;
description"Termination of previously suspended subscription. The publisher
has eliminated the subscription as it exceeded a time limit for
suspension.";
}
identitystream-unavailable {
baseerror;
description"Stream does not exist or is not available to the receiver.";
}
identityencoding-unavailable {
baseerror;
description"Encoding not supported";
}
identityreplay-unsupported {
baseerror;
description"Replay cannot be performed for this subscription. The publisher
does not provide the requested historic information via replay.";
}
identityhistory-unavailable {
baseerror;
description"Replay request too far into the past. The publisher does store
historic information for all parts of requested subscription, but
not back to the requested timestamp.";
}
identityfilter-unavailable {
baseerror;
description"Referenced filter does not exist";
}
identityfilter-type-unsupported {
baseerror;
description"Publisher does not support filters constructed using this
filtering technology syntax.";
}
identityfilter-unsupported {
baseerror;
description"Failure can be from a syntax error, or a syntax too complex to be
processed by the platform. The supplemental info should include
the invalid part of the filter.";
}
identitynamespace-unavailable {
baseerror;
description"Referenced namespace doesn't exist or is unavailable
to the receiver.";
}
identityno-such-subscription {
baseerror;
description"Referenced subscription doesn't exist. This may be as a result of
a non-existent subscription ID, an ID which belongs to another
subscriber, or an ID for acceptable subscription which has been
statically configured.";
}
identityinsufficient-resources {
baseerror;
description"The publisher has insufficient resources to support the
subscription as requested by an RPC.";
}
identityunsupportable-volume {
baseerror;
description"The publisher cannot support the volume of information intended
to be sent for an existing subscription.";
}
identityerror-no-such-option {
baseerror;
description"A requested parameter setting is not supported.";
}
identityencodings {
basedescription"Base identity to represent data encodings";
}
identityencode-xml {
baseencodings;
description"Encode data using XML";
}
identityencode-json {
baseencodings;
description"Encode data using JSON";
}
identitytransport {
basedescription"An identity that represents a the underlying mechanism for
passing notification messages.";
}
identitynetconf {
basetransport;
description"Netconf is used a transport for notification messages and state
change notifications.";
reference"draft-ietf-netconf-netconf-event-notifications";
}
identityhttp2 {
basetransport;
description"HTTP2 is used a transport for notification messages and state
change notifications.";
reference"draft-ietf-netconf-restconf-notif-03, Sections 3.1.13.1.3";
}
identityhttp1.1 {
basetransport;
description"HTTP1.1 is used a transport for notification messages and state
change notifications.";
reference"draft-ietf-netconf-restconf-notif-03, Section 3.1.2";
}
typedefsubscription-id {
typeuint32;
description"A type for subscription identifiers.";
}
typedeffilter-id {
typestring;
description"A type to identify filters which can be associated with a
subscription.";
}
typedefsubscription-result {
typeidentityref {
basesubscription-result;
}
description"The result of a subscription operation";
}
typedefsubscription-errors {
typeidentityref {
baseerror;
}
description"The reason for the failure of an RPC request or the sending
of a subscription suspension or termination state change
notification";
}
typedefencoding {
typeidentityref {
baseencodings;
}
description"Specifies a data encoding, e.g. for a data subscription.";
}
typedeftransport {
typeidentityref {
basetransport;
}
description"Specifies protocol used to send notification messages to a
receiver.";
}
typedefstream {
typestring;
description"Specifies a system-provided datastream.";
}
typedefstream-filter-ref {
typeleafref {
path"/sn:filters/sn:stream-filter/sn:identifier";
}
description"This type is used to reference a stream filter.";
}
groupingstream-filter-elements {
description"This grouping defines the base for filters applied to event
streams.";
choicefilter-spec {
description"The content filter specification for this request.";
anydatasubtree-filter {
if-featuresubtree;
description"Event stream evaluation criteria encoded in a syntax of a
supported type of an RFC 6241, Section 6 filter. The subtree
filter is applied to the representation of individual,
delineated event records as contained within the event
stream. For example, if the notification message contains an
instance of a notification defined in YANG, then the top-
level element is the name of the YANG notification. If the
stream filter matches an event record from the stream, the
event record should be included in a notification message
to the receiver(s).";
}
leafxpath-filter {
if-featurexpath;
typeyang:xpath1.0;
description"Event stream evaluation criteria encoded in a syntax of xpath
1.0 and applied against an event stream. The result of
applying XPath expression is converted to a boolean value
using the standard XPath 1.0 rules. If the boolean value is
'true', the stream filter matches an event record within the
stream, and the notification message should be sent to the
receiver(s).";
}
} // choice filter-spec
} // grouping stream-filter-elementsgroupingsubscription-policy-modifiable {
description"This grouping describes all objects which may be changed
in a subscription via an RPC.";
choicetarget {
mandatorytrue;
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. This choice
exists so that additional filter types can be added via
augmentation.";
choicestream-filter {
description"An event stream filter can be applied to a subscription.
That filter will come either referenced from a global list,
or be provided within the subscription itself.";
caseby-reference {
description"Apply a filter that has been configured separately.";
leafstream-filter-ref {
typestream-filter-ref;
mandatorytrue;
description"References an existing stream-filter which is to
be applied to stream for the subscription.";
}
} // case by-referencecasewithin-subscription {
description"Local definition allows a filter to have the same
lifecycle as the subscription.";
usesstream-filter-elements;
} // case within-subscription
} // choice stream-filter
} // choice targetleafstop-time {
typeyang: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 must be for a future time.";
}
} // grouping subscription-policy-modifiablegroupingsubscription-policy {
description"This grouping describes information concerning a subscription.";
leafencoding {
typeencoding;
mandatorytrue;
description"The type of encoding for the subscribed data.";
}
usessubscription-policy-modifiable {
augmenttarget/stream {
description"Adds additional objects which must be set just by RPC.";
leafstream {
typestream;
mandatorytrue;
description"Indicates a stream of event records against which to apply
a stream filter.";
}
leafreplay-start-time {
if-featurereplay;
typeyang:date-and-time;
description"Used to trigger the replay feature and indicate that the
replay should start at the time specified. 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.";
}
}
}
} // grouping subscription-policygroupingnotification-origin-info {
description"Defines the sender source from which notification messages for a
configured subscription are sent.";
choicenotification-message-origin {
description"Identifies the egress interface on the Publisher from which
notification messages are to be sent.";
caseinterface-originated {
description"When the push source is out of an interface on the
Publisher established via static configuration.";
leafsource-interface {
typeif:interface-ref;
description"References the interface for notification messages.";
}
} // case interface-originatedcaseaddress-originated {
description"When the push source is out of an IP address on the
Publisher established via static configuration.";
leafsource-vrf {
typestring;
description"Network instance name for the VRF. This could also have
been a leafref to draft-ietf-rtgwg-ni-model, but that model
is not complete, and might not be implemented on a box.";
}
leafsource-address {
typeinet: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.";
}
} // case address-originated
} // choice notification-message-origin
} // grouping notification-origin-infogroupingreceiver-info {
description"Defines where and how to get notification messages for a
configured subscriptions to one or more targeted recipient. This
includes specifying the destination addressing as well as a
transport protocol acceptable to the receiver.";
containerreceivers {
description"Set of receivers in a subscription.";
listreceiver {
key "addressport";
min-elements1;
description"A single host or multipoint address intended as a target
for the notification messages of a subscription.";
leafaddress {
typeinet:host;
description"Specifies the address for the traffic to reach a remote
host. One of the following must be specified: an ipv4
address, an ipv6 address, or a host name.";
}
leafport {
typeinet:port-number;
description"This leaf specifies the port number to use for messages
destined for a receiver.";
}
leafprotocol {
typetransport;
mandatorytrue;
description"This leaf specifies the transport protocol used
to deliver messages destined for the receiver. Each
protocol may use the address and port information
differently as applicable.";
}
} // list receiver
} // container receivers
} // grouping receiver-infogroupingerror-identifier {
description"A code passed back within an RPC response to describe why the RFC
has failed, or within a state change notification to describe why
the change has occurred.";
leaferror-id {
typesubscription-errors;
mandatorytrue;
description"Identifies the subscription error condition.";
}
} // grouping error-identifiergroupinghints {
description"Objects passed back within an RPC response to describe why the
RFC has failed, or within a state change notification to
describe why the change has occurred.";
leaffilter-failure {
typestring;
description"Information describing where and/or why a provided filter was
unsupportable for a subscription.";
}
} // grouping hintsgroupingsubscription-response-with-hints {
description"Defines the output for the establish-subscription and
modify-subscription RPCs.";
leafsubscription-result {
typesubscription-result;
mandatorytrue;
description"Indicates whether subscription is operational, or if a problem
was encountered.";
}
choiceresult {
description"Depending on the subscription result, different data is
returned.";
caseno-success {
description"This case applies when a subscription request was not
successful and no subscription was created (or modified) as a
result. In this case, information MAY be returned that
indicates suggested parameter settings that would have a
high likelihood of succeeding in a subsequent establish-
subscription or modify-subscription request.";
useshints;
} // case no-success
} // choice result
} // grouping subscription-response-with-hintsrpcestablish-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. In case an error (as indicated by
subscription-result) is returned, the subscription is not
created. In that case, the RPC reply MAY include suggested
parameter settings that would have a higher likelihood of
succeeding in a subsequent establish-subscription request.";
input {
usessubscription-policy {
refineencoding {
mandatoryfalse;
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 {
usessubscription-response-with-hints {
augmentresult {
description"Allows information to be passed back as part of a
successful subscription establishment.";
casesuccess {
description"This case is used when the subscription request was
successful.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"Identifier used for this subscription.";
}
} // case success
}
augmentresult/no-success {
description"Contains establish RPC specific objects which can be
returned as hints for future attempts.";
leafreplay-start-time-hint {
typeyang:date-and-time;
description"If a replay has been requested, but the requested replay
time cannot be honored, this may provide a hint at an
alternate time which may be supportable.";
}
}
}
}
} // rpc establish-subscriptionrpcmodify-subscription {
description"This RPC allows a subscriber to modify a subscription that was
previously created using establish-subscription. If successful,
the changed subscription remains in effect for the duration of
the subscriber's association with the publisher, or until the
subscription is again modified or terminated. In case an error
is returned (as indicated by subscription-result), the
subscription is not modified and the original subscription
parameters remain in effect. In that case, the rpc error
response MAY include suggested parameter hints that would have
a high likelihood of succeeding in a subsequent
modify-subscription request.";
input {
leafidentifier {
typesubscription-id;
description"Identifier to use for this subscription.";
}
usessubscription-policy-modifiable;
}
output {
usessubscription-response-with-hints;
}
} // rpc modify-subscriptionrpcdelete-subscription {
description"This RPC allows a subscriber to delete a subscription that
was previously created from by that same subscriber using the
establish-subscription RPC.";
input {
leafidentifier {
typesubscription-id;
mandatorytrue;
description"Identifier of the subscription that is to be deleted.
Only subscriptions that were created using
establish-subscription can be deleted via this RPC.";
}
}
output {
leafsubscription-result {
typesubscription-result;
mandatorytrue;
description"Indicates whether subscription has been deleted, or if a
problem was encountered.";
}
}
} // rpc delete-subscriptionrpckill-subscription {
description"This RPC allows an operator to delete a dynamic subscription
without restrictions on the originating subscriber or underlying
transport session.";
input {
leafidentifier {
typesubscription-id;
mandatorytrue;
description"Identifier of the subscription that is to be deleted. Only
subscriptions that were created using establish-subscription
can be deleted via this RPC.";
}
}
output {
leafsubscription-result {
typesubscription-result;
mandatorytrue;
description"Indicates whether subscription has been killed, or if a
problem was encountered.";
}
}
} // rpc kill-subscriptionnotificationreplay-completed {
sn:subscription-state-notif;
if-featurereplay;
description"This notification is sent to indicate that all of the replay
notifications have been sent. It must not be sent for any other
reason.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the affected subscription.";
}
} // notification replay-completednotificationsubscription-completed {
sn:subscription-state-notif;
description"This notification is sent to indicate that a subscription has
finished passing event records.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the gracefully completed subscription.";
}
} // notification subscription-completednotificationsubscription-started {
sn:subscription-state-notif;
if-featureconfigured;
description"This notification indicates that a subscription has started and
notifications are beginning to be sent. This notification shall
only be sent to receivers of a subscription; it does not
constitute a general-purpose notification.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the affected subscription.";
}
usessubscription-policy {
refinetarget/stream/replay-start-time {
description"Indicates the time that a replay using for the streaming of
buffered event records. This will be populated with the most
recent of the following: replay-log-creation-time,
replay-log-aged-time, replay-start-time, or the most recent
publisher boot time.";
}
}
} // notification subscription-startednotificationsubscription-resumed {
sn:subscription-state-notif;
description"This notification indicates that a subscription that had
previously been suspended has resumed. Notifications will once
again be sent.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the affected subscription.";
}
} // notification subscription-resumednotificationsubscription-modified {
sn:subscription-state-notif;
if-featureconfigured;
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 state change notification includes both
modified and non-modified aspects of a subscription.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the affected subscription.";
}
usessubscription-policy;
} // notification subscription-modifiednotificationsubscription-terminated {
sn:subscription-state-notif;
description"This notification indicates that a subscription has been
terminated.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the affected subscription.";
}
useserror-identifier;
useshints;
} // notification subscription-terminatednotificationsubscription-suspended {
sn:subscription-state-notif;
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.";
leafidentifier {
typesubscription-id;
mandatorytrue;
description"This references the affected subscription.";
}
useserror-identifier;
useshints;
} // notification subscription-suspendedcontainerstreams {
configfalse;
description"This container contains information on the built-in streams
provided by the publisher.";
liststream {
key "name";
description"Identifies the built-in streams that are supported by the
publisher.";
leafname {
typestream;
description"A handle for a sequential set of event records, each of which
is characterized by its own domain and semantics.";
}
leafdescription {
typestring;
mandatorytrue;
description"A description of the event stream, including such information
as the type of event records that are available within this
stream.";
}
leafreplay-support {
if-featurereplay;
typeempty;
description"Indicates that event record replay is available on this
stream.";
}
leafreplay-log-creation-time {
if-featurereplay;
typeyang:date-and-time;
description"The timestamp of the creation of the log used to support the
replay function on this stream. Note that this might be
earlier then the earliest available information contained in
the log. This object is updated if the log resets for some
reason. This object MUST be present if replay is supported.";
}
leafreplay-log-aged-time {
if-featurereplay;
typeyang:date-and-time;
description"The timestamp of the last event record aged out of the log.
This object MUST be present if replay is supported and any
event record have been aged out of the log.";
}
} // list stream
} // container streamscontainerfilters {
description"This container contains a list of configurable filters
that can be applied to subscriptions. This facilitates
the reuse of complex filters once defined.";
liststream-filter {
key "identifier";
description"A list of pre-positioned filters that can be applied to
subscriptions.";
leafidentifier {
typefilter-id;
description"An identifier to differentiate between filters.";
}
usesstream-filter-elements;
} // list stream-filter
} // container filterscontainersubscription-config {
if-featureconfigured;
description"Contains the list of subscriptions that are configured,
as opposed to established via RPC or other means.";
listsubscription {
key "identifier";
description"The identity and specific parameters of a subscription.";
leafidentifier {
typesubscription-id;
description"Identifier to use for this subscription.";
}
usessubscription-policy;
usesreceiver-info {
augmentreceivers/receiver {
description"include operational data for receivers.";
leafstatus {
typeenumeration {
enum"connecting" {
value5;
description"A subscription has been configured, and a
subscription-started state change notification should
be sent as quickly as possible.";
}
enum"suspended" {
value3;
description"The status is suspended, meaning that the publisher is
currently will not provide notification messages for
the subscription until some status change.";
}
}
default"connecting";
description"Allows state initialization of a particular receiver.";
}
}
}
usesnotification-origin-info;
} // list subscription
} // container subscription-configcontainersubscriptions {
configfalse;
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 setup via RPC primitives as well as subscriptions
that have been established via configuration.";
listsubscription {
key "identifier";
description"The identity and specific parameterst of a subscription.
Subscriptions within this list can be created using a control
channel or RPC, or be established through configuration.";
leafidentifier {
typesubscription-id;
description"Identifier of a subscription; unique within a publisher";
}
leafconfigured-subscription {
if-featureconfigured;
typeempty;
description"The presence of this leaf indicates that the subscription
originated from configuration, not through a control channel
or RPC.";
}
usessubscription-policy;
usesnotification-origin-info;
usesreceiver-info {
augmentreceivers/receiver {
description"include operational data for receivers.";
leafpushed-notifications {
typeyang:counter64;
description"Operational data which provides the number of update
notification messages pushed to a receiver.";
}
leafexcluded-notifications {
typeyang:counter64;
description"Operational data which provides the number of event
records from a stream explicitly removed via filtering so
that they are not sent to a receiver.";
}
leafstatus {
typeenumeration {
enum"active" {
value1;
description"Connection is active and healthy.";
}
enum"concluded" {
value2;
description"A subscription is inactive as it has hit a stop time,
but not yet been removed.";
}
enum"suspended" {
value3;
description"The status is suspended, meaning that the publisher
is currently unable to provide notification messages
for the subscription.";
}
enum"in-error" {
value4;
description"The status is in error or degraded, meaning that a
subscription is unsupportable with its current
parameters.";
}
enum"connecting" {
value5;
description"A subscription has been configured, but a
subscription-started state change notification has not
yet been succesfully received.";
}
}
mandatorytrue;
description"Specifies the status of a subscription from the
perspective of a particular receiver. With this info it
is possible to determine whether a subscriber is currently
generating notification messages intended for that
receiver.";
}
}
}
} // list subscription
} // container subscriptions
} // module ietf-subscribed-notifications