netconfcentral logo

ietf-subscribed-notifications

HTML

ietf-subscribed-notifications@2017-10-27



  module ietf-subscribed-notifications {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";

    prefix sn;

    import ietf-yang-types {
      prefix yang;
    }
    import ietf-inet-types {
      prefix inet;
    }
    import ietf-interfaces {
      prefix if;
    }

    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";

    }


    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 configured {
      description
        "This feature indicates that configuration of subscription is
      supported.";
    }

    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 xpath {
      description
        "This feature indicates support for xpath filtering.";
      reference
        "http://www.w3.org/TR/1999/REC-xpath-19991116";

    }

    feature subtree {
      description
        "This feature indicates support for YANG subtree filtering.";
      reference
        "RFC 6241, Section 6.";

    }

    extension subscription-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.";
    }

    identity subscription-result {
      base 
      description
        "Base identity for RPC responses and State Change Notifications
      providing information on the creation, modification, deletion of
       subscriptions.";
    }

    identity ok {
      base subscription-result;
      description
        "OK - RPC was successful and was performed as requested.";
    }

    identity error {
      base subscription-result;
      description
        "Problem with subscription.  Base identity for error return
      codes for RPCs and State Change Notifications.";
    }

    identity suspension-timeout {
      base error;
      description
        "Termination of previously suspended subscription. The publisher
      has eliminated the subscription as it exceeded a time limit for
      suspension.";
    }

    identity stream-unavailable {
      base error;
      description
        "Stream does not exist or is not available to the receiver.";
    }

    identity encoding-unavailable {
      base error;
      description "Encoding not supported";
    }

    identity replay-unsupported {
      base error;
      description
        "Replay cannot be performed for this subscription. The publisher
     does not provide the requested historic information via replay.";
    }

    identity history-unavailable {
      base error;
      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.";
    }

    identity filter-unavailable {
      base error;
      description
        "Referenced filter does not exist";
    }

    identity filter-type-unsupported {
      base error;
      description
        "Publisher does not support filters constructed using this
     filtering technology syntax.";
    }

    identity filter-unsupported {
      base error;
      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.";
    }

    identity namespace-unavailable {
      base error;
      description
        "Referenced namespace doesn't exist or is unavailable
      to the receiver.";
    }

    identity no-such-subscription {
      base error;
      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.";
    }

    identity insufficient-resources {
      base error;
      description
        "The publisher has insufficient resources to support the
       subscription as requested by an RPC.";
    }

    identity unsupportable-volume {
      base error;
      description
        "The publisher cannot support the volume of information intended
      to be sent for an existing subscription.";
    }

    identity error-no-such-option {
      base error;
      description
        "A requested parameter setting is not supported.";
    }

    identity encodings {
      base 
      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 {
      base 
      description
        "An identity that represents a the underlying mechanism for
      passing notification messages.";
    }

    identity netconf {
      base transport;
      description
        "Netconf is used a transport for notification messages and state
       change notifications.";
      reference
        "draft-ietf-netconf-netconf-event-notifications";

    }

    identity http2 {
      base transport;
      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";

    }

    identity http1.1 {
      base transport;
      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";

    }

    typedef subscription-id {
      type uint32;
      description
        "A type for subscription identifiers.";
    }

    typedef filter-id {
      type string;
      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-errors {
      type identityref {
        base error;
      }
      description
        "The reason for the failure of an RPC request or the sending
       of a subscription suspension or termination state change
       notification";
    }

    typedef encoding {
      type identityref {
        base encodings;
      }
      description
        "Specifies a data encoding, e.g. for a data subscription.";
    }

    typedef transport {
      type identityref {
        base transport;
      }
      description
        "Specifies protocol used to send notification messages to a
       receiver.";
    }

    typedef stream {
      type string;
      description
        "Specifies a system-provided datastream.";
    }

    typedef stream-filter-ref {
      type leafref {
        path "/sn:filters/sn:stream-filter/sn:identifier";
      }
      description
        "This type is used to reference a stream filter.";
    }

    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 subtree-filter {
          if-feature subtree;
          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).";
        }
        leaf xpath-filter {
          if-feature xpath;
          type yang: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-elements

    grouping subscription-policy-modifiable {
      description
        "This grouping describes all objects which may be changed
      in a subscription via an RPC.";
      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.  This choice
        exists so that additional filter types can be added via
        augmentation.";
        choice stream-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.";
          case by-reference {
            description
              "Apply a filter that has been configured separately.";
            leaf stream-filter-ref {
              type stream-filter-ref;
              mandatory true;
              description
                "References an existing stream-filter which is to
                be applied to stream for the subscription.";
            }
          }  // case by-reference

          case within-subscription {
            description
              "Local definition allows a filter to have the same
              lifecycle as the subscription.";
            uses stream-filter-elements;
          }  // case within-subscription
        }  // choice stream-filter
      }  // choice target

      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 must be for a future time.";
      }
    }  // grouping subscription-policy-modifiable

    grouping subscription-policy {
      description
        "This grouping describes information concerning a subscription.";
      leaf encoding {
        type encoding;
        mandatory true;
        description
          "The type of encoding for the subscribed data.";
      }

      uses subscription-policy-modifiable {
        augment target/stream {
          description
            "Adds additional objects which must be set just by RPC.";
          leaf stream {
            type stream;
            mandatory true;
            description
              "Indicates a stream of event records against which to apply
            a stream filter.";
          }

          leaf replay-start-time {
            if-feature replay;
            type yang: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-policy

    grouping notification-origin-info {
      description
        "Defines the sender source from which notification messages for a
       configured subscription are sent.";
      choice notification-message-origin {
        description
          "Identifies the egress interface on the Publisher from which
         notification messages are to be 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 notification messages.";
          }
        }  // case interface-originated

        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 string;
            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.";
          }

          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.";
          }
        }  // case address-originated
      }  // choice notification-message-origin
    }  // grouping notification-origin-info

    grouping receiver-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.";
      container receivers {
        description
          "Set of receivers in a subscription.";
        list receiver {
          key "address port";
          min-elements 1;
          description
            "A single host or multipoint address intended as a target
           for the notification messages of 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;
            mandatory true;
            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-info

    grouping error-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.";
      leaf error-id {
        type subscription-errors;
        mandatory true;
        description
          "Identifies the subscription error condition.";
      }
    }  // grouping error-identifier

    grouping hints {
      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.";
      leaf filter-failure {
        type string;
        description
          "Information describing where and/or why a provided filter was
        unsupportable for a subscription.";
      }
    }  // grouping hints

    grouping subscription-response-with-hints {
      description
        "Defines the output for the establish-subscription and
       modify-subscription RPCs.";
      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 no-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.";
          uses hints;
        }  // case no-success
      }  // choice result
    }  // grouping subscription-response-with-hints

    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. 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 {
        uses subscription-policy {
          refine encoding {
            mandatory false;
            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 {
        uses subscription-response-with-hints {
          augment result {
            description
              "Allows information to be passed back as part of a
             successful subscription establishment.";
            case success {
              description
                "This case is used when the subscription request was
               successful.";
              leaf identifier {
                type subscription-id;
                mandatory true;
                description
                  "Identifier used for this subscription.";
              }
            }  // case success
          }

          augment result/no-success {
            description
              "Contains establish RPC specific objects which can be
             returned as hints for future attempts.";
            leaf replay-start-time-hint {
              type yang: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-subscription

    rpc modify-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 {
        leaf identifier {
          type subscription-id;
          description
            "Identifier to use for this subscription.";
        }

        uses subscription-policy-modifiable;
      }

      output {
        uses subscription-response-with-hints;
      }
    }  // rpc modify-subscription

    rpc delete-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 {
        leaf identifier {
          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.";
        }
      }

      output {
        leaf subscription-result {
          type subscription-result;
          mandatory true;
          description
            "Indicates whether subscription has been deleted, or if a
          problem was encountered.";
        }
      }
    }  // rpc delete-subscription

    rpc kill-subscription {
      description
        "This RPC allows an operator to delete a dynamic subscription
      without restrictions on the originating subscriber or underlying
      transport session.";
      input {
        leaf identifier {
          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.";
        }
      }

      output {
        leaf subscription-result {
          type subscription-result;
          mandatory true;
          description
            "Indicates whether subscription has been killed, or if a
           problem was encountered.";
        }
      }
    }  // rpc kill-subscription

    notification replay-completed {
      sn:subscription-state-notif;
      if-feature replay;
      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.";
      leaf identifier {
        type subscription-id;
        mandatory true;
        description
          "This references the affected subscription.";
      }
    }  // notification replay-completed

    notification subscription-completed {
      sn:subscription-state-notif;
      description
        "This notification is sent to indicate that a subscription has
       finished passing event records.";
      leaf identifier {
        type subscription-id;
        mandatory true;
        description
          "This references the gracefully completed subscription.";
      }
    }  // notification subscription-completed

    notification subscription-started {
      sn:subscription-state-notif;
      if-feature configured;
      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.";
      leaf identifier {
        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 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-started

    notification subscription-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.";
      leaf identifier {
        type subscription-id;
        mandatory true;
        description
          "This references the affected subscription.";
      }
    }  // notification subscription-resumed

    notification subscription-modified {
      sn:subscription-state-notif;
      if-feature configured;
      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.";
      leaf identifier {
        type subscription-id;
        mandatory true;
        description
          "This references the affected subscription.";
      }

      uses subscription-policy;
    }  // notification subscription-modified

    notification subscription-terminated {
      sn:subscription-state-notif;
      description
        "This notification indicates that a subscription has been
       terminated.";
      leaf identifier {
        type subscription-id;
        mandatory true;
        description
          "This references the affected subscription.";
      }

      uses error-identifier;

      uses hints;
    }  // notification subscription-terminated

    notification subscription-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.";
      leaf identifier {
        type subscription-id;
        mandatory true;
        description
          "This references the affected subscription.";
      }

      uses error-identifier;

      uses hints;
    }  // notification subscription-suspended

    container streams {
      config false;
      description
        "This container contains information on the built-in streams
      provided by the publisher.";
      list stream {
        key "name";
        description
          "Identifies the built-in streams that are supported by the
         publisher.";
        leaf name {
          type stream;
          description
            "A handle for a sequential set of event records, each of which
           is characterized by its own domain and semantics.";
        }

        leaf description {
          type string;
          mandatory true;
          description
            "A description of the event stream, including such information
           as the type of event records that are available within this
           stream.";
        }

        leaf replay-support {
          if-feature replay;
          type empty;
          description
            "Indicates that event record replay is available on this
          stream.";
        }

        leaf replay-log-creation-time {
          if-feature replay;
          type yang: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.";
        }

        leaf replay-log-aged-time {
          if-feature replay;
          type yang: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 streams

    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 stream-filter {
        key "identifier";
        description
          "A list of pre-positioned filters that can be applied to
        subscriptions.";
        leaf identifier {
          type filter-id;
          description
            "An identifier to differentiate between filters.";
        }

        uses stream-filter-elements;
      }  // list stream-filter
    }  // container filters

    container subscription-config {
      if-feature configured;
      description
        "Contains the list of subscriptions that are configured,
       as opposed to established via RPC or other means.";
      list subscription {
        key "identifier";
        description
          "The identity and specific parameters of a subscription.";
        leaf identifier {
          type subscription-id;
          description
            "Identifier to use for this subscription.";
        }

        uses subscription-policy;

        uses receiver-info {
          augment receivers/receiver {
            description
              "include operational data for receivers.";
            leaf status {
              type enumeration {
                enum "connecting" {
                  value 5;
                  description
                    "A subscription has been configured, and a
                  subscription-started state change notification should
                  be sent as quickly as possible.";
                }
                enum "suspended" {
                  value 3;
                  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.";
            }
          }
        }

        uses notification-origin-info;
      }  // list subscription
    }  // container subscription-config

    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 as well as subscriptions
       that have been established via configuration.";
      list subscription {
        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.";
        leaf identifier {
          type subscription-id;
          description
            "Identifier of a subscription; unique within a publisher";
        }

        leaf configured-subscription {
          if-feature configured;
          type empty;
          description
            "The presence of this leaf indicates that the subscription
          originated from configuration, not through a control channel
          or RPC.";
        }

        uses subscription-policy;

        uses notification-origin-info;

        uses receiver-info {
          augment receivers/receiver {
            description
              "include operational data for receivers.";
            leaf pushed-notifications {
              type yang:counter64;
              description
                "Operational data which provides the number of update
               notification messages pushed to a receiver.";
            }

            leaf excluded-notifications {
              type yang: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.";
            }

            leaf status {
              type enumeration {
                enum "active" {
                  value 1;
                  description
                    "Connection is active and healthy.";
                }
                enum "concluded" {
                  value 2;
                  description
                    "A subscription is inactive as it has hit a stop time,
                  but not yet been removed.";
                }
                enum "suspended" {
                  value 3;
                  description
                    "The status is suspended, meaning that the publisher
                  is currently unable to provide notification messages
                  for the subscription.";
                }
                enum "in-error" {
                  value 4;
                  description
                    "The status is in error or degraded, meaning that a
                  subscription is unsupportable with its current
                  parameters.";
                }
                enum "connecting" {
                  value 5;
                  description
                    "A subscription has been configured, but a
                  subscription-started state change notification has not
                  yet been succesfully received.";
                }
              }
              mandatory true;
              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

Summary

  
  
Organization IETF
  
Module ietf-subscribed-notifications
Version 2017-10-27
File ietf-subscribed-notifications@2017-10-27.yang
  
Prefix sn
Namespace urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
  
Cooked /cookedmodules/ietf-subscribed-notifications/2017-10-27
YANG /src/ietf-subscribed-notifications@2017-10-27.yang
XSD /xsd/ietf-subscribed-notifications@2017-10-27.xsd
  
Abstract Contains a YANG specification for subscribing to event records and receiving matching content within notification messages.
  
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.

Typedefs

Typedef Base type Abstract
encoding identityref Specifies a data encoding, e.g. for a data subscription.
filter-id string A type to identify filters which can be associated with a subscription.
stream string Specifies a system-provided datastream.
stream-filter-ref leafref This type is used to reference a stream filter.
subscription-errors identityref The reason for the failure of an RPC request or the sending of a subscription suspension or termination state change notification
subscription-id uint32 A type for subscription identifiers.
subscription-result identityref The result of a subscription operation
transport identityref Specifies protocol used to send notification messages to a receiver.

Groupings

Grouping Objects Abstract
error-identifier error-id 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.
hints filter-failure 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.
notification-origin-info notification-message-origin Defines the sender source from which notification messages for a configured subscription are sent.
receiver-info receivers 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.
stream-filter-elements filter-spec This grouping defines the base for filters applied to event streams.
subscription-policy encoding target stop-time This grouping describes information concerning a subscription.
subscription-policy-modifiable target stop-time This grouping describes all objects which may be changed in a subscription via an RPC.
subscription-response-with-hints subscription-result result Defines the output for the establish-subscription and modify-subscription RPCs.

Objects

Type Key
Mandatory config
Optional config
Not config
Object Type Abstract
filters container This container contains a list of configurable filters that can be applied to subscriptions. This facilitates the reuse of complex filters once defined.
   stream-filter list A list of pre-positioned filters that can be applied to subscriptions.
      filter-spec choice The content filter specification for this request.
         subtree-filter case subtree-filter
            subtree-filter anydata 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 ...
         xpath-filter case xpath-filter
            xpath-filter leaf 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 ...
      identifier leaf An identifier to differentiate between filters.
streams container This container contains information on the built-in streams provided by the publisher.
   stream list Identifies the built-in streams that are supported by the publisher.
      description leaf A description of the event stream, including such information as the type of event records that are available within this stream.
      name leaf A handle for a sequential set of event records, each of which is characterized by its own domain and semantics.
      replay-log-aged-time leaf 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.
      replay-log-creation-time leaf 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 objec...
      replay-support leaf Indicates that event record replay is available on this stream.
subscription-config container Contains the list of subscriptions that are configured, as opposed to established via RPC or other means.
   subscription list The identity and specific parameters of a subscription.
      encoding leaf The type of encoding for the subscribed data.
      identifier leaf Identifier to use for this subscription.
      notification-message-origin choice Identifies the egress interface on the Publisher from which notification messages are to be sent.
         address-originated case When the push source is out of an IP address on the Publisher established via static configuration.
            source-address leaf 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.
            source-vrf leaf 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.
         interface-originated case When the push source is out of an interface on the Publisher established via static configuration.
            source-interface leaf References the interface for notification messages.
      receivers container Set of receivers in a subscription.
         receiver list A single host or multipoint address intended as a target for the notification messages of a subscription.
            address leaf 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.
            port leaf This leaf specifies the port number to use for messages destined for a receiver.
            protocol leaf 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.
            status leaf Allows state initialization of a particular receiver.
      stop-time leaf 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 su...
      target choice 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.
         stream case stream-filter stream replay-start-time
            replay-start-time leaf 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 ...
            stream leaf Indicates a stream of event records against which to apply a stream filter.
            stream-filter choice 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.
               by-reference case Apply a filter that has been configured separately.
                  stream-filter-ref leaf References an existing stream-filter which is to be applied to stream for the subscription.
               within-subscription case Local definition allows a filter to have the same lifecycle as the subscription.
                  filter-spec choice The content filter specification for this request.
                     subtree-filter case subtree-filter
                        subtree-filter anydata 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 ...
                     xpath-filter case xpath-filter
                        xpath-filter leaf 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 ...
subscriptions container 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 th...
   subscription list 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.
      configured-subscription leaf The presence of this leaf indicates that the subscription originated from configuration, not through a control channel or RPC.
      encoding leaf The type of encoding for the subscribed data.
      identifier leaf Identifier of a subscription; unique within a publisher
      notification-message-origin choice Identifies the egress interface on the Publisher from which notification messages are to be sent.
         address-originated case When the push source is out of an IP address on the Publisher established via static configuration.
            source-address leaf 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.
            source-vrf leaf 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.
         interface-originated case When the push source is out of an interface on the Publisher established via static configuration.
            source-interface leaf References the interface for notification messages.
      receivers container Set of receivers in a subscription.
         receiver list A single host or multipoint address intended as a target for the notification messages of a subscription.
            address leaf 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.
            excluded-notifications leaf 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.
            port leaf This leaf specifies the port number to use for messages destined for a receiver.
            protocol leaf 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.
            pushed-notifications leaf Operational data which provides the number of update notification messages pushed to a receiver.
            status leaf 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.
      stop-time leaf 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 su...
      target choice 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.
         stream case stream-filter stream replay-start-time
            replay-start-time leaf 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 ...
            stream leaf Indicates a stream of event records against which to apply a stream filter.
            stream-filter choice 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.
               by-reference case Apply a filter that has been configured separately.
                  stream-filter-ref leaf References an existing stream-filter which is to be applied to stream for the subscription.
               within-subscription case Local definition allows a filter to have the same lifecycle as the subscription.
                  filter-spec choice The content filter specification for this request.
                     subtree-filter case subtree-filter
                        subtree-filter anydata 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 ...
                     xpath-filter case xpath-filter
                        xpath-filter leaf 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 ...

RPC Methods

RPC Abstract
delete-subscription This RPC allows a subscriber to delete a subscription that was previously created from by that same subscriber using the establish-subscription RPC.
establish-subscription 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 terminat...
kill-subscription This RPC allows an operator to delete a dynamic subscription without restrictions on the originating subscriber or underlying transport session.
modify-subscription 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 su...

Notifications

Notification Abstract
replay-completed This notification is sent to indicate that all of the replay notifications have been sent. It must not be sent for any other reason.
subscription-completed This notification is sent to indicate that a subscription has finished passing event records.
subscription-modified 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-m...
subscription-resumed This notification indicates that a subscription that had previously been suspended has resumed. Notifications will once again be sent.
subscription-started 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.
subscription-suspended 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 consti...
subscription-terminated This notification indicates that a subscription has been terminated.

Extensions

Extension Argument Abstract
subscription-state-notif   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. ...