Subscription to YANG Notifications
Extracted elements (33)
For configured subscription replay, the publisher restart time is used as the earliest possible replay point rather than an arbitrary past time. This prevents duplicate event records from a previous boot cycle and guarantees all receivers — regardless of when they connect — receive the same set of replayed records.
The specification is deliberately transport-agnostic; transport bindings (NETCONF in RFC 8640, RESTCONF in a companion document) are defined separately and augment the base YANG module. This allows subscription semantics to be reused across transports without redefining them, and transport-specific lifecycle details are delegated to each binding specification.
There is no mixing of dynamic and configured operations on a single subscription: a configured subscription cannot be modified or deleted via RPCs, and a dynamic subscription cannot be directly modified or deleted via configuration. This clean separation avoids conflicting ownership semantics, though a configuration change to a referenced filter can indirectly affect a dynamic subscription.
This document supersedes RFC 5277 subscriptions. The new RPCs (establish-subscription, modify-subscription, delete-subscription, kill-subscription) replace RFC 5277's <create-subscription>. The RFC 5277 <notification> message format is reused. A publisher MAY implement both RFC 5277 and this document's mechanisms concurrently, and a single transport session may now intermix RPCs and notification messages for different subscriptions.
A notification message MUST include an <eventTime> object as specified in RFC 5277, Section 4, and this <eventTime> MUST be at the top level of the YANG structured event record.
A publisher MUST send subscription state change notifications when subscription management events occur. These notifications are never filtered out, cannot be stored in replay buffers, and are delivered only to impacted receivers.
A publisher supporting the 'configured' feature MUST also support at least one YANG data model that augments transport connectivity parameters on '/subscriptions/subscription/receivers/receiver'. Transport-specific parameters cannot be defined in the base module and must arrive via transport-specific augmentations.
Event records MUST NOT be delivered to a receiver in a different order than the order in which they were placed on an event stream.
For dynamic subscriptions, event records matching newly applied filter criteria MUST NOT be sent until after the RPC reply has been sent. For configured subscriptions, event records MUST NOT be sent until after the 'subscription-started' or 'subscription-modified' notification has been sent.
If a configured subscription's replay-start-time precedes retained history and a receiver needs pre-reboot records, the publisher MUST include the 'replay-previous-event-time' leaf in the 'subscription-started' notification, indicating that earlier events exist before the replay window. If the replay-start-time is earlier than retained history, the revised actual start time MUST be returned in 'replay-start-time-revision'.
If a subscription has the 'dependency' parameter set, buffered notification messages of the parent subscription MUST be dequeued before those of the dependent subscription. If a referenced dependency no longer exists or is inaccessible, it MUST be silently removed. Dependency and weighting are only enforced between subscriptions sharing the same 'dscp' value.
If no access control permissions are in place for event records on an event stream, a receiver MUST be allowed access to all event records. If subscriber permissions change during the lifecycle of a subscription and event stream access is no longer permitted, the subscription MUST be terminated.
If the publisher supports the 'dscp' feature, a subscription with a 'dscp' leaf MUST result in a corresponding DSCP marking in the IP header of all resulting notification messages and subscription state change notifications. Where TCP is used, all subscription traffic MUST share a single TCP session with the subscription's DSCP value; if this cannot be guaranteed, the establish-subscription RPC SHOULD be rejected with 'dscp-unavailable'.
Publishers supporting this document MUST indicate support of the 'ietf-subscribed-notifications' YANG module in their YANG library. All supported optional features (encode-xml, encode-json, configured, supports-vrf, qos, xpath, subtree, interface-designation, dscp, replay) MUST also be indicated.
When concurrently dequeuing notification messages from multiple subscriptions to a receiver, the publisher MUST allocate bandwidth proportional to the 'weighting' assigned to each subscription. Publisher support is optional and advertised via the 'qos' feature.
The 'delete-subscription' RPC cancels an existing dynamic subscription. Once the publisher accepts, it MUST NOT send any more notification messages for that subscription. Only the original subscriber's transport session may invoke this RPC; configured subscriptions cannot be deleted via this RPC.
The 'establish-subscription' RPC creates a dynamic subscription. Inputs include stream name, optional event stream filter (subtree or XPath), optional encoding, optional stop-time, and optional replay-start-time. On success the publisher returns a subscription-id and immediately starts streaming; on failure it MAY return error hints in an 'establish-subscription-stream-error-info' yang-data container.
The 'filters' container holds named event stream filters that persist beyond a single subscription's lifecycle, supporting subtree (RFC 6241) and XPath filter specifications. Predefined filters may be referenced by multiple subscriptions via 'stream-filter-ref', enabling filter reuse without repetition.
The 'kill-subscription' RPC allows an operator to terminate a dynamic subscription that is not associated with the current transport session. A publisher MUST terminate any dynamic subscription identified by the 'id' parameter. Publishers MUST reject any RPC attempt to kill a configured subscription.
The 'modify-subscription' RPC changes the filter and/or stop-time of an existing dynamic subscription. If accepted on a currently suspended subscription, the subscription immediately returns to 'active'. If rejected, the subscription is left unchanged; error hints MAY be returned in a 'modify-subscription-stream-error-info' yang-data container.
The 'replay-completed' notification (gated by the 'replay' feature) signals that all historical event records have been delivered to a receiver. It is sent before any notification message with a timestamp later than the stop-time or the subscription's start time. After this, live event records follow in sequence.
The 'streams' container is operational-state data listing all available event streams. Each entry carries 'name', 'description', optional 'replay-support', 'replay-log-creation-time', and optional 'replay-log-aged-time', allowing subscribers to discover supported streams and the time window available for replay.
The 'subscription-modified' notification indicates subscription parameters have changed. It is sent immediately after the last event records under the old parameters. It MUST also be sent when the contents of a filter referenced by 'stream-filter-ref' change, for any active receivers of a configured or dynamic subscription.
The 'subscription-started' notification (configured subscriptions only, gated by the 'configured' feature) indicates a configured subscription has started. It carries all subscription parameters except transport connection and egress origin information. If a referenced filter was used, the notification provides its contents inline under 'within-subscription'. No 'subscription-started' is ever sent for dynamic subscriptions.
The 'subscription-suspended' notification indicates the publisher has suspended delivery due to capacity constraints; 'reason' is either 'insufficient-resources' (cannot produce the stream) or 'unsupportable-volume' (bandwidth to receiver exceeded a threshold). It also signals possible loss of events; no further notifications are sent until resumption or termination.
The 'subscription-terminated' notification indicates no further event records should be expected. It carries a 'reason' identityref encoding the cause: 'no-such-subscription', 'filter-unavailable', 'stream-unavailable', or 'suspension-timeout'. This MUST be sent to a dynamic subscription's receiver when the subscription ends unexpectedly.
IANA registers the YANG module 'ietf-subscribed-notifications' (namespace 'urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications', prefix 'sn', revision 2019-09-09) in the IANA XML registry and the YANG module names registry. The module is part of RFC 8639.
Access control (per RFC 8341 NACM) may silently exclude event records from an event stream for which the receiver has no read access. A subscription MUST be terminated if permissions change such that event stream access is no longer permitted, preventing covert information delivery through lingering subscriptions.
Subscription state change notifications (subscription-started, subscription-modified, subscription-terminated, etc.) are never filtered out, cannot be stored in replay buffers, and are delivered only to impacted receivers. This ensures receivers are always notified of lifecycle events regardless of configured filter criteria.
Each receiver of a valid configured subscription has its own state machine with states: 'connecting', 'active', 'suspended', and 'disconnected'. A receiver becomes 'active' when subscription-started is successfully delivered (a); moves to 'suspended' on buffer overflow or insufficient CPU (d) with a subscription-suspended notification; and returns to 'active' when resources recover (e) via subscription-resumed or subscription-modified.
The publisher's state machine for a configured subscription has three states: 'valid', 'invalid', and 'concluded'. Creation or modification triggers evaluation; if supportable the subscription enters 'valid' and becomes operational; unsupportable conditions yield 'invalid' with a subscription-terminated notification; reaching stop-time transitions to 'concluded' with a subscription-completed notification.
The publisher's state machine for a dynamic subscription has two states: 'active' and 'suspended'. Successful establish-subscription or modify-subscription RPCs move the subscription to 'active'; insufficient CPU or bandwidth transitions it to 'suspended'; delete-subscription, kill-subscription, or reaching stop-time ends the subscription.
A notification message uses the RFC 5277 <notification> envelope with an <eventTime> element at the top level (yang:date-and-time encoding), followed by the YANG-defined event record payload. The encoding (XML or JSON) is negotiated per-subscription via the 'encoding' leaf.