Custom Subscription to Event Streams
draft-ietf-netconf-subscribed-notifications-10

#x27; rpc request or a 'kill-subscription'

Voit, et al.             Expires August 27, 2018               [Page 29]
Internet-Draft          Subscribed Notifications           February 2018

      rpc request. ";
  }

  identity subscription-terminated-reason {
     description
      "Problem condition communicated to a receiver as part of absolute
      'subscription-terminated' notification. ";
  }

  identity subscription-suspended-reason {
     description
      "Problem condition communicated to a receiver as part of absolute
      'subscription-terminated' notification. ";
  }

  identity dscp-unavailable {
    base establish-subscription-error;
    description
      "Requested DSCP marking not allocatable.";
  }

  identity filter-unavailable {
    base subscription-terminated-reason;
    description
     "Referenced filter does not exist.  This means a receiver is
     referencing a filter which doesn't exist, or to which they do not
     have access permissions.";
  }

  identity filter-unsupported {
    base establish-subscription-error;
    base modify-subscription-error;
    description
     "Cannot parse syntax within the filter.  This failure can be from
     a syntax error, or a syntax too complex to be processed by the
     publisher.";
  }

  identity history-unavailable {
    base establish-subscription-error;
    description
     "Replay request too far into the past. This means the publisher
      does store historic information for the requested stream, but
      not back to the requested timestamp.";
  }

  identity insufficient-resources {
    base establish-subscription-error;

Voit, et al.             Expires August 27, 2018               [Page 30]
Internet-Draft          Subscribed Notifications           February 2018

    base modify-subscription-error;
    base subscription-suspended-reason;
    description
      "The publisher has insufficient resources to support the
       requested subscription.";
  }

  identity no-such-subscription {
    base modify-subscription-error;
    base delete-subscription-error;
    base subscription-terminated-reason;
    description
     "Referenced subscription doesn't exist. This may be as a result of
      a non-existent subscription ID, an ID which belongs to another
      subscriber, or an ID for configured subscription.";
  }

  identity replay-unsupported {
    base establish-subscription-error;
    description
     "Replay cannot be performed for this subscription. This means the
      publisher will not provide the requested historic information from
      the stream via replay to this receiver.";
  }

  identity stream-unavailable {
    base subscription-terminated-reason;
    description
     "Not a subscribable stream.  This means the referenced stream is
      not available for subscription by the receiver.";
  }

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

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

  /* Identities for encodings */

Voit, et al.             Expires August 27, 2018               [Page 31]
Internet-Draft          Subscribed Notifications           February 2018

  identity encodings {
    description
      "Base identity to represent data encodings";
  }

  identity encode-xml {
    base encodings;
    if-feature "encode-xml";
    description
      "Encode data using XML";
  }

  identity encode-json {
    base encodings;
    if-feature "encode-json";
    description
      "Encode data using JSON";
  }

  /* Identities for transports */
  identity transport {
    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.1" +
      "3.1.3";
  }

  identity http1.1 {
    base transport;
    description
      "HTTP1.1 is used a transport for notification messages and state
       change notifications.";

Voit, et al.             Expires August 27, 2018               [Page 32]
Internet-Draft          Subscribed Notifications           February 2018

    reference "draft-ietf-netconf-restconf-notif-03, Section 3.1.2";
  }

  /*
   * TYPEDEFs
   */

  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 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-ref {
    type leafref {
      path "/sn:streams/sn:stream/sn:name";
    }
    description
      "This type is used to reference a system-provided datastream.";
  }

  typedef stream-filter-ref {
    type leafref {
      path "/sn:filters/sn:stream-filter/sn:identifier";

Voit, et al.             Expires August 27, 2018               [Page 33]
Internet-Draft          Subscribed Notifications           February 2018

    }
    description
      "This type is used to reference a configured stream filter.";
  }

  /*
   * GROUPINGS
   */

  grouping stream-filter-elements {
    description
      "This grouping defines the base for filters applied to event
       streams.";
    choice filter-spec {
      description
        "The content filter specification for this request.";
      anydata stream-subtree-filter {
        if-feature "subtree";
        description
          "Event stream evaluation criteria encoded in the syntax of a
          subtree filter as defined in RFC 6241, Section 6.

          The subtree filter is applied to the representation of
          individual, delineated event records as contained 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 subtree filter returns a non-empty node set, the filter
          matches the event record, and the it is included in the
          notification message sent to the receivers.";
        reference "RFC 6241, Section 6.";
      }
      leaf stream-xpath-filter {
        if-feature "xpath";
        type yang:xpath1.0;
        description
          "Event stream evaluation criteria encoded in the syntax of
           an XPath 1.0 expression.

           The XPath expression is evaluated on the representation of
           individual, delineated event records as contained 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, and the root node has this top-level element
           as the only child.

Voit, et al.             Expires August 27, 2018               [Page 34]
Internet-Draft          Subscribed Notifications           February 2018

           The result of the XPath expression is converted to a
           boolean value using the standard XPath 1.0 rules.  If the
           boolean value is 'true', the filter matches the event
           record, and the it is included in the notification message
           sent to the receivers.

           The expression is evaluated in the following XPath context:

             o  The set of namespace declarations are those in scope on
                the 'xpath-filter' leaf element

             o  The set of variable bindings is empty.

             o  The function library is the core function library, and
                the XPath functions defined in section 10 in RFC 7950.

             o  The context node is the root node.";
        reference
          "http://www.w3.org/TR/1999/REC-xpath-19991116
           RFC 7950, Section 10.";

      }
    }
  }

  grouping update-qos {
    description
      "This grouping describes Quality of Service information
       concerning a subscription.  This information is passed to lower
       layers for transport prioritization and treatment";
    leaf dscp {
      if-feature "qos";
      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 weighting {
      if-feature "qos";
      type uint8 {
         range "0 .. 255";
      }
      description
        "Relative weighting for a subscription. Allows an underlying
         transport layer perform informed load balance allocations
         between various subscriptions";

Voit, et al.             Expires August 27, 2018               [Page 35]
Internet-Draft          Subscribed Notifications           February 2018

      reference
        "RFC-7540, section 5.3.2";
    }
    leaf dependency {
      if-feature "qos";
      type subscription-id;
      description
        "Provides the Subscription ID of a parent subscription which
         has absolute priority should that parent have push updates
         ready to egress the publisher. In other words, there should be
         no streaming of objects from the current subscription if
         the parent has something ready to push.";
      reference
        "RFC-7540, section 5.3.1";
    }
  }

  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.";
      case stream {
        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 within-subscription {
            description
              "Local definition allows a filter to have the same
              lifecycle as the subscription.";

Voit, et al.             Expires August 27, 2018               [Page 36]
Internet-Draft          Subscribed Notifications           February 2018

            uses stream-filter-elements;
          }
        }
      }
    }
    leaf stop-time {
      type yang:date-and-time;
      description
        "Identifies a time after which notification messages for a
        subscription should not be sent.  If stop-time is not present,
        the notification messages will continue until the subscription
        is terminated.  If replay-start-time exists, stop-time must be
        for a subsequent time. If replay-start-time doesn't exist,
        stop-time must be for a future time.";
    }
  }

  grouping subscription-policy-dynamic {
    description
      "This grouping describes information concerning a subscription
      which can just be passed over the RPCs defined in this model.";
    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 can be modified by RPC.";
        leaf stream {
          type stream-ref {
            require-instance false;
          }
          mandatory true;
          description
            "Indicates the stream of event records to be considered for
            this subscription.";
        }
        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.

Voit, et al.             Expires August 27, 2018               [Page 37]
Internet-Draft          Subscribed Notifications           February 2018

            It is never valid to specify start times that are later than
            or equal to the current time.";
        }
      }
    }
    uses update-qos;
  }

  grouping subscription-policy {
    description
      "This grouping describes the full set of policy information
      concerning both dynamic and configured subscriptions, except for
      configured receivers.";
    leaf protocol {
      if-feature "configured";
      type transport;
      mandatory true;
      description
        "This leaf specifies the transport protocol used to deliver
        messages destined to all receivers of a subscription.";
    }
    uses subscription-policy-dynamic;
  }

  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 notification messages to egress a specific, designated
           interface on the Publisher.";
        leaf source-interface {
          type if:interface-ref;
          description
            "References the interface for notification messages.";
        }
      }
      case address-originated {
        description
          "When notification messages are to depart from a publisher
             using specfic originating address and/or routing context
           information.";
        leaf source-vrf {

Voit, et al.             Expires August 27, 2018               [Page 38]
Internet-Draft          Subscribed Notifications           February 2018

          if-feature "supports-vrf";
          type leafref {
            path "/ni:network-instances/ni:network-instance/ni:name";
          }
          description
            "VRF from which notification messages should egress a
            publisher.";
        }
        leaf source-address {
          type inet:ip-address-no-zone;
          description
            "The source address for the notification messages.  If a
            source VRF exists, but this object doesn't, a publisher's
            default address for that VRF must be used.";
        }
      }
    }
  }

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

Voit, et al.             Expires August 27, 2018               [Page 39]
Internet-Draft          Subscribed Notifications           February 2018

    }
  }

  /*
   * RPCs
   */

  rpc establish-subscription {
    description
      "This RPC allows a subscriber to create (and possibly negotiate)
       a subscription on its own behalf.  If successful, the
       subscription remains in effect for the duration of the
       subscriber's association with the publisher, or until the
       subscription is terminated. In case an error occurs, or the
       publisher cannot meet the terms of a subscription, and RPC error
       is returned, the subscription is not created.  In that case, the
       RPC reply's error-info MAY include suggested parameter settings
       that would have a higher likelihood of succeeding in a subsequent
       establish-subscription request.";
    input {
      uses subscription-policy-dynamic {
        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.";
        }
      }
    }
  }

  rc:yang-data establish-subscription-error-stream {
    container establish-subscription-error-stream {
      description
        "If any 'establish-subscription' RPC parameters are
        unsupportable against the event stream, a subscription is not
        created and the RPC error response MUST indicate the reason
        why the subscription failed to be created. This yang-data MAY be
        inserted as structured data within a subscription's RPC error
        response to indicate the failure reason.  This yang-data MUST be
        inserted if hints are to be provided back to the subscriber.";
      leaf reason {
        type identityref {
          base establish-subscription-error;
        }

Voit, et al.             Expires August 27, 2018               [Page 40]
Internet-Draft          Subscribed Notifications           February 2018

        description
          "Indicates the reason why the subscription has failed to
          be created to a targeted stream.";
        }
      leaf filter-failure-hint {
        type string;
          description
            "Information describing where and/or why a provided filter
             was unsupportable for a subscription.";
      }
      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 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 of an
       error or an inability to meet the modified parameters, the
       subscription is not modified and the original subscription
       parameters remain in effect.  In that case, the rpc error
       MAY include error-info suggested parameter hints that would have
       a high likelihood of succeeding in a subsequent
       modify-subscription request.  A successful modify-subscription
       will return a suspended subscription to an active state.";
    input {
      leaf identifier {
        type subscription-id;
        description
          "Identifier to use for this subscription.";
      }
      uses subscription-policy-modifiable;
    }
  }

  rc:yang-data modify-subscription-error-stream {
    container modify-subscription-error-stream {
      description
        "This yang-data MAY be provided as part of a subscription's RPC

Voit, et al.             Expires August 27, 2018               [Page 41]
Internet-Draft          Subscribed Notifications           February 2018

        error response when there is a failure of a
        'modify-subscription' RPC which has been made against a
        stream.  This yang-data MUST be used if hints are to be
        provides back to the subscriber.";
      leaf reason {
        type identityref {
          base modify-subscription-error;
        }
        description
          "Information in a modify-subscription RPC error response which
          indicates the reason why the subscription to an event stream
          has failed to be modified.";
      }
      leaf filter-failure-hint {
        type string;
          description
            "Information describing where and/or why a provided filter
             was unsupportable for a subscription.";
      }
    }
  }

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

  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;

Voit, et al.             Expires August 27, 2018               [Page 42]
Internet-Draft          Subscribed Notifications           February 2018

        description
          "Identifier of the subscription that is to be deleted. Only
            subscriptions that were created using establish-subscription
           can be deleted via this RPC.";
      }
    }
  }

  rc:yang-data delete-subscription-error {
    container delete-subscription-error {
      description
        "If a 'delete-subscription' RPC or a 'kill-subscription' RPC
        fails, the subscription is not deleted and the RPC error
        response MUST indicate the reason for this failure. This
        yang-data MAY be inserted as structured data within a
        subscription's RPC error response to indicate the failure
        reason.";
      leaf reason {
        type identityref {
          base delete-subscription-error;
        }
        mandatory true;
        description
          "Indicates the reason why the subscription has failed to be
          deleted.";
      }
    }
  }

  /*
   * NOTIFICATIONS
   */

  notification replay-completed {
    sn:subscription-state-notification;
    if-feature "replay";
    description
      "This notification is sent to indicate that all of the replay
        notifications have been sent. It must not be sent for any other
       reason.";
    leaf identifier {
      type subscription-id;
      mandatory true;
      description
        "This references the affected subscription.";
    }
  }

Voit, et al.             Expires August 27, 2018               [Page 43]
Internet-Draft          Subscribed Notifications           February 2018

  notification subscription-completed {
    sn:subscription-state-notification;
    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-started {
    sn:subscription-state-notification;
    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.";
      }
      refine "target/stream/stream-filter/within-subscription" {
        description
          "Filter applied to the subscription.  If the
          'stream-filter-ref' is populated, the filter within the
          subscription came from the 'filters' container.  Otherwise it
          is populated in-line as part of the subscription.";
      }
    }
  }

  notification subscription-resumed {
    sn:subscription-state-notification;

Voit, et al.             Expires August 27, 2018               [Page 44]
Internet-Draft          Subscribed Notifications           February 2018

    description
      "This notification indicates that a subscription that had
       previously been suspended has resumed. Notifications will once
       again be sent.  In addition, a subscription-resumed indicates
       that no modification of parameters has occurred since the last
       time event records have been sent.";
    leaf identifier {
      type subscription-id;
      mandatory true;
      description
        "This references the affected subscription.";
    }
  }

  notification subscription-modified {
    sn:subscription-state-notification;
    description
      "This notification indicates that a subscription has been
       modified.  Notification messages sent from this point on will
       conform to the modified terms of the subscription.  For
       completeness, this 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 {
      refine "target/stream/stream-filter/within-subscription" {
        description
          "Filter applied to the subscription.  If the
          'stream-filter-ref' is populated, the filter within the
          subscription came from the 'filters' container.  Otherwise it
          is populated in-line as part of the subscription.";
      }
    }
  }

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

Voit, et al.             Expires August 27, 2018               [Page 45]
Internet-Draft          Subscribed Notifications           February 2018

        "This references the affected subscription.";
    }
    leaf reason {
      type identityref {
        base subscription-terminated-reason;
      }
      mandatory true;
      description
        "Identifies the condition which resulted in the termination .";
    }
  }

  notification subscription-suspended {
    sn:subscription-state-notification;
    description
      "This notification indicates that a suspension of the
       subscription by the publisher has occurred.  No further
       notifications will be sent until the subscription resumes.
       This notification shall only be sent to receivers of a
       subscription; it does not constitute a general-purpose
       notification.";
    leaf identifier {
      type subscription-id;
      mandatory true;
      description
        "This references the affected subscription.";
    }
    leaf reason {
      type identityref {
        base subscription-suspended-reason;
      }
      mandatory true;
      description
        "Identifies the condition which resulted in the suspension.";
    }
  }

  /*
   * DATA NODES
   */

  container streams {
    config false;
    description
      "This container contains information on the built-in streams
      provided by the publisher.";
    list stream {
      key "name";

Voit, et al.             Expires August 27, 2018               [Page 46]
Internet-Draft          Subscribed Notifications           February 2018

      description
        "Identifies the built-in streams that are supported by the
         publisher.";
      leaf name {
        type string;
        description
          "A handle for a system-provided datastream made up of 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.";
      }
    }
  }

  container filters {
    description

Voit, et al.             Expires August 27, 2018               [Page 47]
Internet-Draft          Subscribed Notifications           February 2018

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

  container subscriptions {
    description
      "Contains the list of currently active subscriptions, i.e.
       subscriptions that are currently in effect, used for subscription
       management and monitoring purposes. This includes subscriptions
       that have been setup via RPC primitives as well as subscriptions
       that have been established via configuration.";
    list subscription {
      key "identifier";
      description
        "The identity and specific parameters 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-state {
        if-feature "configured";
        type enumeration {
          enum valid {
            value 1;
            description
              "Connection is active and healthy.";
          }
          enum invalid {
            value 2;
            description
              "The subscription as a whole is unsupportable with its
              current parameters.";

Voit, et al.             Expires August 27, 2018               [Page 48]
Internet-Draft          Subscribed Notifications           February 2018

          }
          enum concluded {
            value 3;
              description
                "A subscription is inactive as it has hit a stop time,
                but not yet been removed from configuration.";
          }
        }
        config false;
        description
          "The presence of this leaf indicates that the subscription
          originated from configuration, not through a control channel
          or RPC.  The value indicates the system established state
          of the subscription.";
      }
      leaf purpose {
        if-feature "configured";
        type string;
        description
          "Open text allowing a configuring entity to embed the
          originator or other specifics of this subscription.";
      }
      uses subscription-policy {
        refine "target/stream/stream" {
          description
            "Indicates the stream of event records to be considered for
            this subscription.   If a stream has been removed, and no
            longer can be referenced by an active subscription, send a
            'subscription-terminated' notification with
            'stream-unavailable' as the reason.  If a configured
            subscription refers to a non-existent stream, move that
            subscription to the 'invalid' state.";
        }
      }
      uses notification-origin-info {
        if-feature "configured";
      }
      uses receiver-info {
        augment receivers/receiver {
          description
            "include operational data for receivers.";
          leaf pushed-notifications {
            type yang:counter64;
            config false;
            description
              "Operational data which provides the number of update
               notification messages pushed to a receiver.";
            }

Voit, et al.             Expires August 27, 2018               [Page 49]
Internet-Draft          Subscribed Notifications           February 2018

          leaf excluded-notifications {
            type yang:counter64;
            config false;
            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 state {
            type enumeration {
              enum active {
                value 1;
                description
                  "Receiver is currently being sent any applicable
                  notification messages for the subscription.";
              }
              enum suspended {
                value 2;
                description
                  "Receiver state is suspended, so the publisher
                  is currently unable to provide notification messages
                  for the subscription.";
              }
              enum connecting {
                value 3;
                if-feature "configured";
                description
                  "A subscription has been configured, but a
                  subscription-started state change notification needs
                  to be successfully received before notification
                  messages are sent.";
              }
              enum timeout {
                value 4;
                if-feature "configured";
                description
                  "A subscription has failed in sending a subscription
                  started state change to the receiver.
                  Additional attempts at connection attempts are not
                  currently being made.";
              }
            }
            config false;
            mandatory true;
            description
              "Specifies the state of a subscription from the
              perspective of a particular receiver.  With this info it
              is possible to determine whether a subscriber is currently

Voit, et al.             Expires August 27, 2018               [Page 50]
Internet-Draft          Subscribed Notifications           February 2018

              generating notification messages intended for that
              receiver.";
          }
          action reset {
            description
              "Allows the reset of this configured subscription receiver
              to the 'connecting' state. This enables the
              connection process to be reinitiated.";
            output {
              leaf time {
                type yang:date-and-time;
                mandatory true;
                description
                  "Time a publisher returned the receiver to a
                  connecting state.";
              }
            }
          }
        }
      }
    }
  }
}
<CODE ENDS>

5.  Considerations

5.1.  Implementation Considerations

   For a deployment including both configured and dynamic subscriptions,
   split subscription identifiers into static and dynamic halves.  That
   way it is unlikely there will be collisions if the configured
   subscriptions attempt to set a subscription-id which might have
   already been dynamically allocated.  The lower half the "identifier"
   object in the subscriptions container SHOULD be used when the
   "identifier" is selected and assigned by an external entity (such as
   with a configured subscription).  And the upper half SHOULD be used
   for subscription identifiers dynamically chosen and assigned by the
   publisher

   Neither state change notification nor subscribed event records within
   notification messages may be sent before the transport layer,
   including any required capabilities exchange, has been established.

   An implementation may choose to transition between active and
   suspended subscription states more frequently than required by this
   specification.  However if a subscription is unable to marshal all
   intended updates into a transmittable message in multiple successive

Voit, et al.             Expires August 27, 2018               [Page 51]
Internet-Draft          Subscribed Notifications           February 2018

   intervals, the subscription SHOULD be suspended with the reason
   "unsupportable-volume".

   For configured subscriptions, operations are against the set of
   receivers using the subscription identifier as a handle for that set.
   But for streaming updates, state change notifications are local to a
   receiver.  In this specification it is the case that receivers get no
   information from the publisher about the existence of other
   receivers.  But if an operator wants to let the receivers correlate
   results, it is useful to use the subscription identifier handle
   across the receivers to allow that correlation.

5.2.  IANA Considerations

   This document registers the following namespace URI in the "IETF XML
   Registry" [RFC3688]:

   URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
   Registrant Contact: The IESG.
   XML: N/A; the requested URI is an XML namespace.

   This document registers the following YANG module in the "YANG Module
   Names" registry [RFC6020]:

   Name: ietf-subscribed-notifications
   Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications
   Prefix: sn
   Reference: draft-ietf-netconf-ietf-subscribed-notifications-08.txt
   (RFC form)

5.3.  Security Considerations

   For dynamic subscriptions the publisher MUST authenticate and
   authorize all RPC requests.

   Subscriptions could overload a publisher's CPU.  For this reason, the
   publisher MUST have the ability to decline a dynamic subscription
   request, and provide the appropriate RPC error response to a
   subscriber should the proposed subscription overly deplete the
   publisher's resources.

   A publisher needs to be able to suspend an existing dynamic or
   configured subscription based on capacity constraints.  When this
   occurs, the subscription state MUST be updated accordingly and the
   receivers notified with subscription state notifications.

   If a malicious or buggy subscriber sends an unexpectedly large number
   of RPCs, the result might be an excessive use of system resources.

Voit, et al.             Expires August 27, 2018               [Page 52]
Internet-Draft          Subscribed Notifications           February 2018

   In such a situation, subscription interactions MAY be terminated by
   terminating the transport session.

   For both configured and dynamic subscriptions the publisher MUST
   authenticate and authorize a receiver via some transport level
   mechanism before sending any updates.

   A secure transport is highly recommended and the publisher MUST
   ensure that the receiver has sufficient authorization to perform the
   function they are requesting against the specific subset of content
   involved.

   A publisher MUST NOT include any content in a notification message
   for which the receiver has not been authorized.

   With configured subscriptions, one or more publishers could be used
   to overwhelm a receiver.  No notification messages SHOULD be sent to
   any receiver which doesn't even support subscriptions.  Receivers
   that do not want notification messages need only terminate or refuse
   any transport sessions from the publisher.

   The NETCONF Authorization Control Model [RFC6536bis] SHOULD be used
   to control and restrict authorization of subscription configuration.
   This control models permits specifying per-receiver permissions to
   receive event records from specific streams.

   Where NACM is available, the NACM "very-secure" tag MUST be placed on
   the "kill-subscription" RPC so that only administrators have access
   to use this.

   One subscription id can be used for two or more receivers of the same
   configured subscription.  But due to the possibility of different
   access control permissions per receiver, it SHOULD NOT be assumed
   that each receiver is getting identical updates.

6.  Acknowledgments

   For their valuable comments, discussions, and feedback, we wish to
   acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen,
   Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan
   Hares, Michael Scharf, and Guangying Zheng.

7.  References

Voit, et al.             Expires August 27, 2018               [Page 53]
Internet-Draft          Subscribed Notifications           February 2018

7.1.  Normative References

   [I-D.draft-ietf-rtgwg-ni-model]
              Berger, L., Hopps, C., and A. Lindem, "YANG Network
              Instances", draft-ietf-rtgwg-ni-model-06 (work in
              progress), January 2018.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC5277]  Chisholm, S. and H. Trevino, "NETCONF Event
              Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
              <https://www.rfc-editor.org/info/rfc5277>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6536bis]
              Bierman, A. and M. Bjorklund, "Network Configuration
              Protocol (NETCONF) Access Control Model", draft-ietf-
              netconf-rfc6536bis-09 (work in progress), December 2017.

   [RFC7540]  Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
              Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
              DOI 10.17487/RFC7540, May 2015,
              <https://www.rfc-editor.org/info/rfc7540>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [XPATH]    Clark, J. and S. DeRose, "XML Path Language (XPath)
              Version 1.0", November 1999,
              <http://www.w3.org/TR/1999/REC-xpath-19991116>.

7.2.  Informative References

Voit, et al.             Expires August 27, 2018               [Page 54]
Internet-Draft          Subscribed Notifications           February 2018

   [I-D.draft-ietf-netconf-netconf-event-notifications]
              Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
              Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H.
              Trevino, "NETCONF support for event notifications",
              October 2017, <https://datatracker.ietf.org/doc/
              draft-ietf-netconf-netconf-event-notifications/>.

   [I-D.draft-ietf-netconf-restconf-notif]
              Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen-
              Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and
              HTTP transport for event notifications", January 2018,
              <https://datatracker.ietf.org/doc/
              draft-ietf-netconf-restconf-notif/>.

   [I-D.ietf-netconf-yang-push]
              Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto.,
              Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B.
              Lengyel, "YANG Datastore Subscription", December 2017,
              <https://datatracker.ietf.org/doc/
              draft-ietf-netconf-yang-push/>.

   [I.D.draft-ietf-netconf-notification-messages]
              Voit, Eric., Clemm, Alexander., Bierman, A., and T.
              Jenkins, "YANG Notification Headers and Bundles",
              September 2017, <https://datatracker.ietf.org/doc/
              draft-ietf-netconf-notification-messages>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.

   [RFC7923]  Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
              for Subscription to YANG Datastores", RFC 7923,
              DOI 10.17487/RFC7923, June 2016,
              <https://www.rfc-editor.org/info/rfc7923>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

Appendix A.  Changes between revisions

   (To be removed by RFC editor prior to publication)

   v09 - v10

   o  Typos and tweaks

Voit, et al.             Expires August 27, 2018               [Page 55]
Internet-Draft          Subscribed Notifications           February 2018

   v08 - v09

   o  NMDA model supported.  Non NMDA version at https://github.com/
      netconf-wg/rfc5277bis/

   o  Error mechanism revamped to match to embedded implementations.

   o  Explicitly identified error codes relevant to each RPC/
      Notification

   v07 - v08

   o  Split YANG trees to separate document subsections.

   o  Clarified configured state machine based on Balazs comments, and
      moved it into the configured subscription subsections.

   o  Normative reference to Network Instance model for VRF

   o  One transport protocol for all receivers of configured
      subscriptions.

   o  QoS section moved in from yang-push

   v06 - v07

   o  Clarification on state machine for configured subscriptions.

   v05 - v06

   o  Made changes proposed by Martin, Kent, and others on the list.
      Most significant of these are Stream returned to string (with the
      SYSLOG identity removed), intro section on 5277 relationship, an
      identity set moved to an enumeration, clean up of definitions/
      terminology, state machine proposed for configured subscriptions
      with a clean-up of subscription state options.

   o  JSON and XML become features.  Also Xpath and subtree filtering
      become features

   o  Terminology updates with event records, and refinement of filters
      to just stream filters.

   o  Encoding refined in establish-subscription so it takes the RPC's
      encoding as the default.

   o  Namespaces in examples fixed.

Voit, et al.             Expires August 27, 2018               [Page 56]
Internet-Draft          Subscribed Notifications           February 2018

   v04 - v05

   o  Returned to the explicit filter subtyping of v00

   o  stream object changed to 'name' from 'stream'

   o  Cleaned up examples

   o  Clarified that JSON support needs notification-messages draft.

   v03 - v04

   o  Moved back to the use of RFC5277 one-way notifications and
      encodings.

   v03 - v04

   o  Replay updated

   v02 - v03

   o  RPCs and Notification support is identified by the Notification
      2.0 capability.

   o  Updates to filtering identities and text

   o  New error type for unsupportable volume of updates

   o  Text tweaks.

   v01 - v02

   o  Subscription status moved under receiver.

   v00 - v01

   o  Security considerations updated

   o  Intro rewrite, as well as scattered text changes

   o  Added Appendix A, to help match this to related drafts in progress

   o  Updated filtering definitions, and filter types in yang file, and
      moved to identities for filter types

   o  Added Syslog as a stream

   o  HTTP2 moved in from YANG-Push as a transport option

Voit, et al.             Expires August 27, 2018               [Page 57]
Internet-Draft          Subscribed Notifications           February 2018

   o  Replay made an optional feature for events.  Won't apply to
      datastores

   o  Enabled notification timestamp to have different formats.

   o  Two error codes added.

   v01 5277bis - v00 subscribed notifications

   o  Kill subscription RPC added.

   o  Renamed from 5277bis to Subscribed Notifications.

   o  Changed the notification capabilities version from 1.1 to 2.0.

   o  Extracted create-subscription and other elements of RFC5277.

   o  Error conditions added, and made specific in return codes.

   o  Simplified yang model structure for removal of 'basic' grouping.

   o  Added a grouping for items which cannot be statically configured.

   o  Operational counters per receiver.

   o  Subscription-id and filter-id renamed to identifier

   o  Section for replay added.  Replay now cannot be configured.

   o  Control plane notification renamed to subscription state
      notification

   o  Source address: Source-vrf changed to string, default address
      option added

   o  In yang model: 'info' changed to 'policy'

   o  Scattered text clarifications

   v00 - v01 of 5277bis

   o  YANG Model changes.  New groupings for subscription info to allow
      restriction of what is changeable via RPC.  Removed notifications
      for adding and removing receivers of configured subscriptions.

   o  Expanded/renamed definitions from event server to publisher, and
      client to subscriber as applicable.  Updated the definitions to
      include and expand on RFC 5277.

Voit, et al.             Expires August 27, 2018               [Page 58]
Internet-Draft          Subscribed Notifications           February 2018

   o  Removal of redundancy with other drafts

   o  Many other clean-ups of wording and terminology

Authors' Addresses

   Eric Voit
   Cisco Systems

   Email: evoit@cisco.com

   Alexander Clemm
   Huawei

   Email: ludwig@clemm.org

   Alberto Gonzalez Prieto
   VMWare

   Email: agonzalezpri@vmware.com

   Einar Nilsen-Nygaard
   Cisco Systems

   Email: einarnn@cisco.com

   Ambika Prasad Tripathy
   Cisco Systems

   Email: ambtripa@cisco.com

Voit, et al.             Expires August 27, 2018               [Page 59]