module ietf-yang-push {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
prefix yp;
import ietf-inet-types {
prefix inet;
}
import ietf-yang-types {
prefix yang;
}
import ietf-interfaces {
prefix if;
}
organization "IETF";
contact
"WG Web:
WG List:
WG Chair: Mahesh Jethanandani
WG Chair: Mehmet Ersue
Editor: Alexander Clemm
Editor: Eric Voit
Editor: Alberto Gonzalez Prieto
Editor: Ambika Prasad Tripathy
Editor: Einar Nilsen-Nygaard
";
description
"This module contains conceptual YANG specifications
for YANG push.";
revision 2016-03-21 {
description
"Changes to grouping structure, RPC definitions, filter
definitions, origin interface and receiver definitions.";
reference "YANG Datastore Push, draft-ietf-netconf-yang-push-02";
}
feature on-change {
description
"This feature indicates that on-change updates are
supported.";
}
feature json {
description
"This feature indicates that JSON encoding of push updates
is supported.";
}
feature configured-subscriptions {
description
"This feature indicates that management plane configuration
of subscription is supported.";
}
identity subscription-result {
description
"Base identity for RPC responses to requests surrounding
management (e.g. creation, modification) of
subscriptions.";
}
identity ok {
base subscription-result;
description
"OK - RPC was successful and was performed as requested.";
}
identity error {
base subscription-result;
description
"RPC was not successful.
Base identity for error return codes.";
}
identity error-no-such-subscription {
base error;
description
"A subscription with the requested subscription ID
does not exist.";
}
identity error-no-such-option {
base error;
description
"A requested parameter setting is not supported.";
}
identity error-insufficient-resources {
base error;
description
"The server has insufficient resources to support the
subscription as requested.";
}
identity error-data-not-authorized {
base error;
description
"No read authorization for a requested data node.";
}
identity error-configured-subscription {
base error;
description
"Cannot apply RPC to a configured subscription, i.e.
to a subscription that was not established via RPC.";
}
identity error-other {
base error;
description
"An unspecified error has occurred (catch all).";
}
identity subscription-stream-status {
description
"Base identity for the status of subscriptions and
datastreams.";
}
identity active {
base subscription-stream-status;
description
"Status is active and healthy.";
}
identity inactive {
base subscription-stream-status;
description
"Status is inactive, for example outside the
interval between start time and stop time.";
}
identity suspended {
base subscription-stream-status;
description
"The status is suspended, meaning that the push server
is currently unable to provide the negotiated updates
for the subscription.";
}
identity subscription-errors {
description
"Base identity for subscription error status.
This identity is not to be confused with error return
codes for RPCs";
}
identity internal-error {
base subscription-errors;
description
"Subscription failures caused by server internal error.";
}
identity no-resources {
base subscription-errors;
description
"Lack of resources, e.g. CPU, memory, bandwidth";
}
identity subscription-deleted {
base subscription-errors;
description
"The subscription was terminated because the subscription
was deleted.";
}
identity other {
base subscription-errors;
description
"Fallback reason - any other reason";
}
identity event-stream {
description
"Base identity to represent a generic stream of event
notifications.";
}
identity update-stream {
base event-stream;
description
"Base identity to represent a conceptual system-provided
datastream of datastore updates with predefined semantics.";
}
identity yang-push {
base update-stream;
description
"A conceptual datastream consisting of all datastore
updates, including operational and configuration data.";
}
identity operational-push {
base update-stream;
description
"A conceptual datastream consisting of updates of all
operational data.";
}
identity config-push {
base update-stream;
description
"A conceptual datastream consisting of updates of all
configuration data.";
}
identity custom-stream {
base update-stream;
description
"A category of customizable datastream for datastore
updates with contents that have defined by a user.";
}
identity netconf-stream {
base event-stream;
description
"Default notification stream";
}
identity encodings {
description
"Base identity to represent data encodings";
}
identity encode-xml {
base encodings;
description
"Encode data using XML";
}
identity encode-json {
base encodings;
description
"Encode data using JSON";
}
identity transport {
description
"An identity that represents a transport protocol for event updates";
}
identity netconf {
base transport;
description
"Netconf notifications as a transport";
}
identity restconf {
base transport;
description
"Restconf notifications as a transport";
}
typedef datastore-contents-xml {
type string;
description
"This type is be used to represent datastore contents,
i.e. a set of data nodes with their values, in XML.
The syntax corresponds to the syntax of the data payload
returned in a corresponding Netconf get operation with the
same filter parameters applied.";
reference "RFC 6241 section 7.7";
}
typedef datastore-changes-xml {
type string;
description
"This type is used to represent a set of changes in a
datastore encoded in XML, indicating for datanodes whether
they have been created, deleted, or updated. The syntax
corresponds to the syntax used to when editing a
datastore using the edit-config operation in Netconf.";
reference "RFC 6241 section 7.2";
}
typedef datastore-contents-json {
type string;
description
"This type is be used to represent datastore contents,
i.e. a set of data nodes with their values, in JSON.
The syntax corresponds to the syntax of the data
payload returned in a corresponding RESTCONF get
operation with the same filter parameters applied.";
reference "RESTCONF Protocol";
}
typedef datastore-changes-json {
type string;
description
"This type is used to represent a set of changes in a
datastore encoded in JSON, indicating for datanodes whether
they have been created, deleted, or updated. The syntax
corresponds to the syntax used to patch a datastore
using the yang-patch operation with Restconf.";
reference "draft-ietf-netconf-yang-patch";
}
typedef subscription-id {
type uint32;
description
"A type for subscription identifiers.";
}
typedef filter-id {
type uint32;
description
"A type to identify filters which can be associated with a
subscription.";
}
typedef subscription-result {
type identityref {
base subscription-result;
}
description
"The result of a subscription operation";
}
typedef subscription-term-reason {
type identityref {
base subscription-errors;
}
description
"Reason for a server to terminate a subscription.";
}
typedef subscription-susp-reason {
type identityref {
base subscription-errors;
}
description
"Reason for a server to suspend a subscription.";
}
typedef encoding {
type identityref {
base encodings;
}
description
"Specifies a data encoding, e.g. for a data subscription.";
}
typedef change-type {
type enumeration {
enum "create" {
description
"A new data node was created";
}
enum "delete" {
description
"A data node was deleted";
}
enum "modify" {
description
"The value of a data node has changed";
}
}
description
"Specifies different types of changes that may occur
to a datastore.";
}
typedef transport-protocol {
type identityref {
base transport;
}
description
"Specifies transport protocol used to send updates to a
receiver.";
}
typedef push-source {
type enumeration {
enum "interface-originated" {
description
"Pushes will be sent from a specific interface on a
Publisher";
}
enum "address-originated" {
description
"Pushes will be sent from a specific address on a
Publisher";
}
}
description
"Specifies from where objects will be sourced when being pushed
off a publisher.";
}
typedef update-stream {
type identityref {
base update-stream;
}
description
"Specifies a system-provided datastream.";
}
typedef filter-ref {
type leafref {
path "/yp:filters/yp:filter/yp:filter-id";
}
description
"This type is used to reference a yang push filter.";
}
grouping datatree-filter {
description
"This grouping defines filters for a datastore tree.";
choice filter-type {
description
"A filter needs to be a single filter of a given type.
Mixing and matching of multiple filters does not occur
at the level of this grouping.";
case subtree {
description
"Subtree filter.";
anyxml subtree-filter {
description
"Subtree-filter used to specify the data nodes targeted
for subscription within a subtree, or subtrees, of a
conceptual YANG datastore.
It may include additional criteria,
allowing users to receive only updates of a limited
set of data nodes that match those filter criteria.
This will be used to define what
updates to include in a stream of update events, i.e.
to specify for which data nodes update events should be
generated and specific match expressions that objects
need to meet. The syntax follows the subtree filter
syntax specified in RFC 6241, section 6.";
reference "RFC 6241 section 6";
}
}
case xpath {
description
"XPath filter";
leaf xpath-filter {
type yang:xpath1.0;
description
"Xpath defining the data items of interest.";
}
}
case rfc5277 {
anyxml filter {
description
"Subtree filter per RFC 5277";
}
}
}
}
grouping update-policy {
description
"This grouping describes the conditions under which an
update will be sent as part of an update stream.";
choice update-trigger {
description
"Defines necessary conditions for sending an event to
the subscriber.";
case periodic {
description
"The agent is requested to notify periodically the
current values of the datastore or the subset
defined by the filter.";
leaf period {
type yang:timeticks;
mandatory true;
description
"Duraton of time which should occur between periodic
push updates. Where the anchor of a start-time is
available, the push will include the objects and their
values which exist at an exact multiple of timeticks
aligning to this start-time anchor.";
}
}
case on-change {
if-feature "on-change";
description
"The agent is requested to notify changes in
values in the datastore or a subset of it defined
by a filter.";
leaf no-synch-on-start {
type empty;
description
"This leaf acts as a flag that determines behavior at the
start of the subscription. When present,
synchronization of state at the beginning of the
subscription is outside the scope of the subscription.
Only updates about changes that are observed from the
start time, i.e. only push-change-update notifications
are sent.
When absent (default behavior), in order to facilitate
a receiver's synchronization, a full update is sent
when the subscription starts using a push-update
notification, just like in the case of a periodic
subscription. After that, push-change-update
notifications are sent.";
}
leaf dampening-period {
type yang:timeticks;
mandatory true;
description
"Minimum amount of time that needs to have
passed since the last time an update was
provided.";
}
leaf-list excluded-change {
type change-type;
description
"Use to restrict which changes trigger an update.
For example, if modify is excluded, only creation and
deletion of objects is reported.";
}
}
}
}
grouping subscription-info {
description
"This grouping describes basic information concerning a
subscription.";
leaf stream {
type update-stream;
description
"The stream being subscribed to.";
}
leaf encoding {
type encoding;
default "encode-xml";
description
"The type of encoding for the subscribed data.
Default is XML";
}
leaf subscription-start-time {
type yang:date-and-time;
description
"Designates the time at which a subscription is supposed
to start, or immediately, in case the start-time is in
the past. For periodic subscription, the start time also
serves as anchor time from which the time of the next
update is computed. The next update will take place at the
next period interval from the anchor time.
For example, for an anchor time at the top of a minute
and a period interval of a minute, the next update will
be sent at the top of the next minute.";
}
leaf subscription-stop-time {
type yang:date-and-time;
description
"Designates the time at which a subscription will end.
When a subscription reaches its stop time, it will be
automatically deleted. No final push is required unless there
is exact alignment with the end of a periodic subscription
period.";
}
choice filterspec {
description
"The filter to be applied to the stream as part of the
subscription. The filter defines which updates of the
data stream are of interest to a subscriber.
The filter can be specified in-line
or configured separately and referenced here.
If no filter is specified, the entire datatree
is of interest.";
case inline {
description
"Filter is defined as part of the subscription.";
uses datatree-filter;
}
case by-reference {
description
"Incorporate a filter that has been configured
separately.";
leaf filter-ref {
type filter-ref;
description
"References filter which is associated with the
subscription.";
}
}
}
}
grouping push-source-info {
description
"Defines the sender source from which push updates
for a configured subscription are pushed.";
choice push-source {
description
"Identifies the egress interface on the Publisher from
which pushed updates will or are being sent.";
case interface-originated {
description
"When the push source is out of an interface on the
Publisher established via static configuration.";
leaf source-interface {
type if:interface-ref;
description
"References the interface for pushed updates.";
}
}
case address-originated {
description
"When the push source is out of an IP address on the
Publisher established via static configuration.";
leaf source-vrf {
type uint32 {
range "16..1048574";
}
description
"Label of the vrf.";
}
leaf source-address {
type inet:ip-address-no-zone;
mandatory true;
description
"The source address for the pushed objects.";
}
}
}
}
grouping receiver-info {
description
"Defines where and how to deliver push updates for a
configured subscription. This includes
specifying the receiver, as well as defining
any network and transport aspects when pushing of
updates occurs outside of Netconf or Restconf.";
list receiver {
key "address";
description
"A single host or multipoint address intended as a target
for the pushed updates for a subscription.";
leaf address {
type inet: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.";
}
leaf port {
type inet:port-number;
description
"This leaf specifies the port number to use for messages
destined for a receiver.";
}
leaf protocol {
type transport-protocol;
default "netconf";
description
"This leaf specifies the transport protocol used
to deliver messages destined for the receiver.";
}
}
}
grouping subscription-qos {
description
"This grouping describes Quality of Service information
concerning a subscription. This information is passed to lower
layers for transport priortization and treatment";
leaf dscp {
if-feature configured-subscriptions;
type inet:dscp;
default 0;
description
"The push update's IP packet transport priority.
This is made visible across network hops to receiver.
The transport priority is shared for all receivers of
a given subscription.";
}
leaf subscription-priority {
type uint8;
description
"Relative priority for a subscription. Allows an underlying
transport layer perform informed load balance allocations
between various subscriptions";
}
leaf subscription-dependency {
type string;
description
"Provides the Subscription ID of a parent subscription
without which this subscription should not exist. In
other words, there is no reason to stream these objects
if another subscription is missing.";
}
}
rpc establish-subscription {
description
"This RPC allows a subscriber to establish 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 by virtue of a delete-subscription request.
In case an error (as indicated by subscription-result)
is returned, the subscription is
not establishd. In that case, the RPC output
MAY include suggested parameter settings
that would have a high likelihood of succeeding in a
subsequent establish-subscription request.";
input {
uses subscription-info;
uses update-policy;
uses subscription-qos;
}
output {
leaf subscription-result {
type subscription-result;
mandatory true;
description
"Indicates whether subscription is operational,
or if a problem was encountered.";
}
choice result {
description
"Depending on the subscription result, different
data is returned.";
case success {
description
"This case is used when the subscription request
was successful and a subscription was established as
a result";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"Identifier used for this subscription.";
}
}
case no-success {
description
"This case applies when a subscription request
was not successful and no subscription was
established 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 request.";
uses subscription-info;
uses update-policy;
uses subscription-qos;
}
}
}
}
rpc modify-subscription {
description
"This RPC allows a subscriber to modify a subscription
that was previously established using establish-subscription.
If successful, the subscription
remains in effect for the duration of the subscriber's
association with the publisher, or until the subscription
is terminated by virtue of a delete-subscription request.
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 settings
that would have a high likelihood of succeeding in a
subsequent modify-subscription request.";
input {
leaf subscription-id {
type subscription-id;
description
"Identifier to use for this subscription.";
}
uses subscription-info;
uses update-policy;
uses subscription-qos;
}
output {
leaf subscription-result {
type subscription-result;
mandatory true;
description
"Indicates whether subscription was modified
or if a problem was encountered.
In case the subscription-result has a value
other than OK, the original subscription was not
changed.";
}
uses subscription-info;
uses update-policy;
uses subscription-qos;
}
}
rpc delete-subscription {
description
"This RPC allows a subscriber to delete a subscription that
was previously established using establish-subscription.";
input {
leaf subscription-id {
type subscription-id;
description
"Identifier of the subscription that is to be deleted.
Only subscriptions that were established using
establish-subscription can be deleted via this RPC.";
}
}
}
notification push-update {
description
"This notification contains a periodic push update.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the subscription because of which the
notification is sent.";
}
leaf time-of-update {
type yang:date-and-time;
description
"This leaf contains the time of the update.";
}
choice encoding {
description
"Distinguish between the proper encoding that was specified
for the subscription";
case encode-xml {
description
"XML encoding";
leaf datastore-contents-xml {
type datastore-contents-xml;
description
"This contains data encoded in XML,
per the subscription.";
}
}
case encode-json {
if-feature "json";
description
"JSON encoding";
leaf datastore-contents-json {
type datastore-contents-json;
description
"This leaf contains data encoded in JSON,
per the subscription.";
}
}
}
}
notification push-change-update {
if-feature "on-change";
description
"This notification contains an on-change push update.
This notification shall only be sent to the receivers
of a subscription; it does not constitute a general-purpose
notification.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the subscription because of which the
notification is sent.";
}
leaf time-of-update {
type yang:date-and-time;
description
"This leaf contains the time of the update, i.e. the
time at which the change was observed.";
}
choice encoding {
description
"Distinguish between the proper encoding that was specified
for the subscription";
case encode-xml {
description
"XML encoding";
leaf datastore-changes-xml {
type datastore-changes-xml;
description
"This contains datastore contents that has changed
since the previous update, per the terms of the
subscription. Changes are encoded analogous to
the syntax of a corresponding Netconf edit-config
operation.";
}
}
case encode-json {
if-feature "json";
description
"JSON encoding";
leaf datastore-changes-yang {
type datastore-changes-json;
description
"This contains datastore contents that has changed
since the previous update, per the terms of the
subscription. Changes are encoded analogous
to the syntax of a corresponding RESTCONF yang-patch
operation.";
}
}
}
}
notification subscription-started {
description
"This notification indicates that a subscription has
started and data updates are beginning to be sent.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
uses subscription-info;
uses update-policy;
uses subscription-qos;
}
notification subscription-suspended {
description
"This notification indicates that a suspension of the
subscription by the server has occurred. No further
datastore updates will be sent until subscription
resumes.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
leaf reason {
type subscription-susp-reason;
description
"Provides a reason for why the subscription was
suspended.";
}
}
notification subscription-resumed {
description
"This notification indicates that a subscription that had
previously been suspended has resumed. Datastore updates
will once again be sent.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
}
notification subscription-modified {
description
"This notification indicates that a subscription has
been modified. Datastore updates sent from this point
on will conform to the modified terms of the
subscription.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
uses subscription-info;
uses update-policy;
uses subscription-qos;
}
notification subscription-terminated {
description
"This notification indicates that a subscription has been
terminated.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
leaf reason {
type subscription-term-reason;
description
"Provides a reason for why the subscription was
terminated.";
}
}
container update-streams {
config false;
description
"This container contains a leaf list of built-in
streams that are provided by the system.";
leaf-list update-stream {
type update-stream;
description
"Identifies a built-in stream that is supported by the
system. Streams are associated with their own identities,
each of which carries a special semantics.";
}
}
container filters {
description
"This container contains a list of configurable filters
that can be applied to subscriptions. This facilitates
the reuse of complex filters once defined.";
list filter {
key "filter-id";
description
"A list of configurable filters that can be applied to
subscriptions.";
leaf filter-id {
type filter-id;
description
"An identifier to differentiate between filters.";
}
uses datatree-filter;
}
}
container subscription-config {
if-feature "configured-subscriptions";
description
"Contains the list of subscriptions that are configured,
as opposed to established via RPC or other means.";
list yang-push-subscription {
key "subscription-id";
description
"Content of a yang-push subscription.";
leaf subscription-id {
type subscription-id;
description
"Identifier to use for this subscription.";
}
uses subscription-info;
uses update-policy;
uses receiver-info;
uses push-source-info;
uses subscription-qos;
}
}
container subscriptions {
config false;
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, e.g. establish-subscription, delete-subscription,
and modify-subscription, as well as subscriptions that
have been established via configuration.";
list yang-push-subscription {
key "subscription-id";
config false;
description
"Content of a yang-push subscription.
Subscriptions can be established using a control channel
or RPC, or be established through configuration.";
leaf subscription-id {
type subscription-id;
description
"Identifier of this subscription.";
}
leaf configured-subscription {
if-feature "configured-subscriptions";
type empty;
description
"The presence of this leaf indicates that the
subscription originated from configuration, not through
a control channel or RPC.";
}
leaf subscription-status {
type identityref {
base subscription-stream-status;
}
description
"The status of the subscription.";
}
uses subscription-info;
uses update-policy;
uses receiver-info;
uses push-source-info;
uses subscription-qos;
}
}
}