RFC 5277
NETCONF Event Notifications
Network Working Group 🌸 RFC 5277: NETCONF Event Notifications 🦋
Authors: S. Chisholm (Nortel) and H. Trevino (Cisco) Category: Standards Track Date: July 2008
Status of This Memo ✨
okay so this doc is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🫶. For the official standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Also, distribution of this memo is unlimited, so share away 💅.
Abstract 💜
this doc defines mechanisms that give NETCONF an asynchronous message notification delivery service. It's an optional capability built on top of the base NETCONF definition, and it lays out the capabilities and operations needed to make it work 🧚.
Table of Contents 🎀
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 3
1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 5
2. Notification-Related Operations . . . . . . . . . . . . . . . 5
2.1. Subscribing to Receive Event Notifications . . . . . . . . 5
2.1.1. <create-subscription> . . . . . . . . . . . . . . . . 6
2.2. Sending Event Notifications . . . . . . . . . . . . . . . 9
2.2.1. <notification> . . . . . . . . . . . . . . . . . . . . 9
2.3. Terminating the Subscription . . . . . . . . . . . . . . . 9
3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 10
3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 10
3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 10
3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 10
3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 10
3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 12
3.2.2. Event Stream Content Format . . . . . . . . . . . . . 12
3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 12
3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 12
3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 12
3.3. Notification Replay . . . . . . . . . . . . . . . . . . . 15
3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 15
3.3.2. Creating a Subscription with Replay . . . . . . . . . 16
3.4. Notification Management Schema . . . . . . . . . . . . . . 16
3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 20
3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 20
3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 20
3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 20
4. XML Schema for Event Notifications . . . . . . . . . . . . . . 22
5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 26
5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 28
5.2. XPATH Filters . . . . . . . . . . . . . . . . . . . . . . 29
6. Interleave Capability . . . . . . . . . . . . . . . . . . . . 30
6.1. Description . . . . . . . . . . . . . . . . . . . . . . . 30
6.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 30
6.3. Capability Identifier . . . . . . . . . . . . . . . . . . 30
6.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 31
6.5. Modifications to Existing Operations . . . . . . . . . . . 31
7. Security Considerations . . . . . . . . . . . . . . . . . . . 31
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33
10. Normative References . . . . . . . . . . . . . . . . . . . . . 331. Introduction ✨
bestie, so [NETCONF] can be split up conceptually into four layers 🍓:
Layer Example
+-------------+ +-------------------------------------------+
| Content | | Configuration data |
+-------------+ +-------------------------------------------+
| |
+-------------+ +-------------------------------------------+
| Operations | |<get-config>, <edit-config>, <notification>|
+-------------+ +-------------------------------------------+
| | |
+-------------+ +-----------------------------+ |
| RPC | | <rpc>, <rpc-reply> | |
+-------------+ +-----------------------------+ |
| | |
+-------------+ +-------------------------------------------+
| Transport | | BEEP, SSH, SSL, console |
| Protocol | | |
+-------------+ +-------------------------------------------+
Figure 1this doc defines the mechanisms that give the [NETCONF] protocol an asynchronous message notification delivery service 🔥. It's an optional capability built on top of the base NETCONF definition, and this memo lays out the capabilities and operations you need to support it 💅.
1.1. Definition of Terms 📖
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in [RFC2119]. ngl, these are the rules for how to read the requirement words 🤓.
- Element: An [XML] Element.
- Subscription: An agreement and method to receive event notifications over a NETCONF session. It's a concept tied to the delivery of notifications (if there are any to send) and it involves the destination and the selection of notifications. A subscription is bound to the lifetime of a session 🎀.
- Operation: This term refers to NETCONF protocol operations [NETCONF]. Within this document, "operation" specifically means the NETCONF protocol operations defined to support NETCONF notifications 🧚.
- Event: An event is something that happens that may be of interest, like a configuration change, a fault, a change in status, crossing a threshold, or an external input to the system. Often, it results in an asynchronous message (sometimes called a notification or event notification) being sent to interested parties to let them know the event happened 👀.
- Replay: The ability to send or re-send previously logged notifications on request. These notifications are sent asynchronously. The NETCONF server implements this feature and the NETCONF client invokes it 🦋.
- Stream: An event stream is a set of event notifications that match some forwarding criteria and are available to NETCONF clients for subscription 🌈.
- Filter: A parameter that says which subset of all possible events are of interest. A filter is one or more filter elements [NETCONF], and each one identifies a portion of the overall filter 💖.
1.2. Motivation 💭
the whole point of this work is to enable asynchronous messages that are consistent with the data model (content) and the security model used within a NETCONF implementation. Main character energy 👑.
the scope aims at meeting these operational needs:
- Initial release should ensure it supports notifications in support of configuration operations.
- It should be possible to use the same data model for notifications as for configuration operations.
- The solution should support a reasonable message size limit (i.e., not too short).
- The notifications should be carried over a connection-oriented delivery mechanism.
- A subscription mechanism for notifications should be provided. This takes into account that a NETCONF server does not send notifications before being asked to do so, and that it is the NETCONF client who initiates the flow of notifications.
- A filtering mechanism for sending notifications should be put in place within the NETCONF server.
- The information contained in a notification should be sufficient so that it can be analyzed independent of the transport mechanism. In other words, the data content fully describes a notification; protocol information is not needed to understand a notification 🫶.
- The server should have the capability to replay locally logged notifications.
1.3. Event Notifications in NETCONF 🔔
this memo defines how the NETCONF client shows interest in event notifications from a NETCONF server: it creates a subscription to receive them 🙈. The NETCONF server replies to say whether the subscription request worked. If it did, the server starts sending event notifications to the client as events happen in the system. These keep coming until either the NETCONF session ends or the subscription terminates for some other reason. The subscription gives the client a bunch of options to pick which events it cares about, and those get set when the subscription is created. Heads up: a subscription cannot be modified once it's created 🚫.
Heads up: The NETCONF server MUST accept and process the <close-session> operation, even while the notification subscription is active.
The NETCONF server MAY accept and process other commands. If it doesn't, those commands get rejected, and the server MUST send a 'resource-denied' error. A NETCONF server advertises that it can process other commands through the :interleave capability 🧚.
2. Notification-Related Operations 🎀
2.1. Subscribing to Receive Event Notifications 💌
the event notification subscription is started by the NETCONF client and answered by the NETCONF server. A subscription is bound to a single stream for its whole lifetime 🦋. When the subscription is created, the events of interest get specified.
content for an event notification subscription can be picked out by applying user-specified filters 💅.
2.1.1. <create-subscription> 💅
okay bestie, this is the big one 🦋 <create-subscription> kicks off an event notification subscription, and from then on the server keeps sending you asynchronous event notifications until that subscription ends. it's giving main character energy 👑
Parameters:
- Stream: an optional
<stream>param that says which stream of events you're hoping to catch 🌸 if you leave it out, you get events from the default NETCONF stream. - Filter: an optional
<filter>param that picks out a subset of all the possible events 💜 the format is the same as the filter parameter in the NETCONF protocol operations. if you don't include it, you get every event that your other params don't rule out. see section 3.6 for more on filters ✨ - Start Time: a
<startTime>param that triggers the replay feature and says where the replay should start 🕰️ no<startTime>means it's not a replay subscription. you can't ask for a start time later than the current time (rude 💀). if your<startTime>is older than the log can handle, the replay just starts at the earliest notification that's still available. this param is type dateTime and compliant to [RFC3339]. implementations must support time zones 🌍 - Stop Time: an optional
<stopTime>param, used together with the optional replay feature, to say where your newest notifications of interest end 🏁 if you skip it, notifications keep coming until the subscription is terminated. it has to be used with a<startTime>and be later than it. future values of<stopTime>are totally valid 🔮 this param is also type dateTime and compliant to [RFC3339], and implementations must support time zones too 🫶
Positive Response:
if the NETCONF server can handle your request, it sends back an <ok> element 🎀
Negative Response:
if the request can't be completed for any reason, an <rpc-error> element shows up inside the <rpc-reply> 😭 subscription requests will fail if you send a filter with invalid syntax, or if you ask for a stream name that doesn't exist.
if you set a <stopTime> without a <startTime>, you get this error:
Tag: missing-element
Error-type: protocol
Severity: error
Error-info: <bad-element>: startTime
Description: An expected element is missing.if you ask for the optional replay feature and the NETCONF server doesn't support it, you get this one:
Tag: operation-failed
Error-type: protocol
Severity: error
Error-info: none
Description: Request could not be completed because the
requested operation failed for some reason not covered by any
other error condition.if your <stopTime> is earlier than your <startTime>, you get this:
Tag: bad-element
Error-type: protocol
Severity: error
Error-info: <bad-element>: stopTime
Description: An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.and if your <startTime> is later than the current time, you get this:
Tag: bad-element
Error-type: protocol
Severity: error
Error-info: <bad-element>: startTime
Description: An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.2.1.1.1. Usage Example 🧚
here's a simple subscription so you can see the vibe. for fancier ones, check out section 5 🌈
<netconf:rpc message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
</create-subscription>
</netconf:rpc>2.2. Sending Event Notifications 📬
once the subscription is set up, the NETCONF server sends event notifications to you asynchronously over the connection. no need to keep asking, the notifications just show up 💖
2.2.1. <notification> 🔔
an event notification gets sent to the client that started a <create-subscription> command, asynchronously, whenever an event of interest happens (aka one that meets your filtering criteria) ✨ an event notification is a complete, well-formed XML document. quick note: <notification> is not a Remote Procedure Call (RPC) method. it's the top-level element that marks the one-way message as a notification 💅
Parameters:
eventTimeis the time the event was generated by the event source ⏰ this param is type dateTime and compliant to [RFC3339], and implementations must support time zones.
the notification can also contain notification-specific tagged content, if any 🎁 apart from <eventTime>, that content is beyond the scope of this document 🙈
Response:
no response. not applicable 🫠
2.3. Terminating the Subscription 🛑
closing a subscription can be done with the <close-session> operation from the subscription's session 🚪 you can also end it by terminating the NETCONF session (<kill-session>), or by terminating the underlying transport session from another session. if you set a stop time when you created the subscription, the subscription terminates once that stop time is reached. in that case, the NETCONF session is still an active session, so you're not kicked out 🙌
3. Supporting Concepts 🌸
3.1. Capabilities Exchange 🤝
the ability to process and send event notifications gets advertised during the capability exchange between the NETCONF client and server 📣
3.1.1. Capability Identifier 🪪
"urn:ietf:params:netconf:capability:notification:1.0"3.1.2. Capability Example 🍓
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>
urn:ietf:params:xml:ns:netconf:base:1.0
</capability>
<capability>
urn:ietf:params:netconf:capability:startup:1.0
</capability>
<capability>
urn:ietf:params:netconf:capability:notification:1.0
</capability>
</capabilities>
<session-id>4</session-id>
</hello>3.2. Event Streams 🌊
an event stream is defined as a set of event notifications that match some forwarding criteria 💜
figure 2 shows the notification flow and concepts from this document 🎨 it doesn't force or rule out any particular implementation, so don't go thinking it's the only way to build it. here's the tea: system components (c1..cn) generate event notifications, which get passed to a central component for classification and distribution. the central component checks each event notification against the set of stream definitions. when there's a match, that event notification counts as a member of that event stream (stream 1..stream n). an event notification can be part of multiple event streams, which is so cool 🤯
after the NETCONF server gets the internal event from a stream, the server converts it to an appropriate XML encoding, and a <notification> element is ready to go out to every NETCONF session subscribed to that stream 📤
once the <notification> element is generated, the server applies access control. if a session doesn't have permission to receive the <notification>, it gets discarded for that session, and processing of the internal event is wrapped up for that session 🔒
when a NETCONF client subscribes to an event stream, any user-defined filter elements (if they apply) get applied to the stream, and the matching event notifications get forwarded to the NETCONF server for distribution to subscribed NETCONF clients 🎯 a filter gets sent from the client to the server during the <create-subscription> operation, and it's applied to each <notification> element the stream generates. for more on filtering, see Section 3.6 ✨
there might also be a notification-logging service, in which case the central component logs notifications 📝 the NETCONF server can later pull those logged notifications back out using the optional replay feature. for more on replay, see section 3.3 ⏪
+----+
| c1 |----+ available streams
+----+ | +---------+
+----+ | |central |-> stream 1
| c2 | +--->|event |-> stream 2 filter +-------+
+----+ | |processor|-> NETCONF stream ----->|NETCONF|
... | | |-> stream n |server |
System | +---------+ +-------+
Components| | /\
... | | ||
+----+ | | (------------) ||
| cn |----+ | (notification) ||
+----+ +-----> ( logging ) ||
( service ) ||
(------------) ||
||
||
\/
+-------+
|NETCONF|
|client |
+-------+
Figure 23.2.1. Event Stream Definition 🧩
event streams are predefined on the managed device 🖥️ how streams get configured is outside the scope of this document. but it's envisioned that event streams are pre-established by the vendor (pre-configured), user configurable (like, part of the device's configuration), or both. device vendors may allow event stream configuration through the NETCONF protocol (aka the <edit-config> operation) 💅
3.2.2. Event Stream Content Format 📄
the contents of all event streams made available to a NETCONF client (aka the notification the NETCONF server sends) MUST be encoded in XML. no other vibes allowed 🙅♀️
3.2.3. Default Event Stream 🌈
a NETCONF server that supports the notification capability MUST support the "NETCONF" notification event stream 👑 this stream has all the NETCONF XML event notifications the NETCONF server supports. the exact string "NETCONF" is used when advertising stream support, both during the <get> operation on <streams> and during the <create-subscription> operation. defining the event notifications and their contents for this stream, beyond including <eventTime>, is outside the scope of this document 🤷♀️
3.2.4. Event Stream Sources 🛰️
apart from the default event stream (NETCONF), specifying additional event stream sources (e.g., Simple Network Management Protocol (SNMP), syslog) is outside the scope of this document. NETCONF server implementations may use any event stream source they want when creating their supported event streams 🦋
3.2.5. Event Stream Discovery 🔍
a NETCONF client gets the list of supported event streams from a NETCONF server using the <get> operation 💖
3.2.5.1. Name Retrieval Using <get> Operation
okay so, step one is finding out which event streams you can even subscribe to 👀✨ You do that by asking for the <streams> subtree with a <get> operation. The server sends back the streams that are available to your session, each with a <name> and a <description>. The <name> is mandatory 💅, and its value has to be unique within the scope of a NETCONF server, so no two streams can share a name 🫶 If your <get> filters rule everything out, you just get an empty reply back. That's not an error, it just means nothing matched 🙈
You also get a little extra info about each stream, like whether replay is supported and, if it is, the timestamp of the oldest notification you can replay 🕰️✨
Here's what asking for the list looks like 🎀
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams/>
</netconf>
</filter>
</get>
</rpc>And the server replies with the streams you can subscribe to. In this example that's NETCONF, SNMP, and syslog-critical 🌈
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams>
<stream>
<name>NETCONF</name>
<description>default NETCONF event stream
</description>
<replaySupport>true</replaySupport>
<replayLogCreationTime>
2007-07-08T00:00:00Z
</replayLogCreationTime>
</stream>
<stream>
<name>SNMP</name>
<description>SNMP notifications</description>
<replaySupport>false</replaySupport>
</stream>
<stream>
<name>syslog-critical</name>
<description>Critical and higher severity
</description>
<replaySupport>true</replaySupport>
<replayLogCreationTime>
2007-07-01T00:00:00Z
</replayLogCreationTime>
</stream>
</streams>
</netconf>
</data>
</rpc-reply>3.2.5.2. Event Stream Subscription
so the flow is: check the list of streams available to your session, then send a <create-subscription> request with the name of the stream you want 🦋 If you leave the stream name out of the <create-subscription> request, you get subscribed to the default NETCONF event stream. Easy peasy 💖
3.2.5.2.1. Filtering Event Stream Contents
you can narrow down what shows up in a stream too 😤 Add a user-specified filter to your <create-subscription> request, and only the notifications that match it get delivered. This filter is transient 🌸 It's tied to that one notification subscription and doesn't change the stream's configuration at all. Also, the filter gets applied to the contents of the <notification> wrapper, not the wrapper itself, which is a detail people totally miss 👑 Check section 5 for examples. You can use either subtree or XPATH filtering.
XPATH support for the Notification capability is advertised as part of the normal XPATH capability advertisement 📣 If the XPATH capability is advertised, then XPATH works for notification filtering. If that capability isn't advertised, then XPATH is not supported for notification filtering. Clear as glass ✨
3.3. Notification Replay
3.3.1. Overview
replay is basically the ability to set up a subscription that resends recently generated notifications, or in some cases sends them for the first time to a particular NETCONF client ⏪💜 Replayed notifications get sent the same way as normal ones, so nothing fancy on the delivery side 🫶
You ask for a replay by including the optional <startTime> parameter in your subscription command. That's the start time of the replay 🕰️ The end time goes in the optional <stopTime> parameter. If you don't include <stopTime>, notifications keep coming until the subscription is terminated.
a stream that supports replay is not expected to have an unlimited supply of saved notifications, so it can't promise it'll have everything you ask for 🥺 To figure out what's actually available, clients can look at<replayLogCreationTime>and<replayLogAgedTime>.
How many notifications are stored at any given moment is up to the NETCONF server implementation 🤷♀️ The control parameters for that are outside the scope of this document, so we're not getting into them here.
Replay depends on the stream supporting some kind of notification logging 📚 The document doesn't put any restrictions on the size or form of that log, or on where it lives in the device, so that's all open. To check whether a stream supports replay, do a <get> on the <streams> element of the Notification Management Schema and look at the <replaySupport> value 🔍 That same schema also gives you <replayLogCreationTime>, which tells you the earliest logged notification that's available.
3.3.2. Creating a Subscription with Replay
replay uses some optional parameters on the <create-subscription> command, called <startTime> and <stopTime> 💅 <startTime> sets the earliest date and time you care about for the notifications being replayed. It also tells the server that this subscription is going to be a replay. Anything generated before that time doesn't get matched 🙅♀️ <stopTime> is the latest date and time you care about. If you leave it out, notifications keep flowing until the subscription ends 🌊
Heads up, <startTime> and <stopTime> are tied to the time the event was generated by the event source, not when anyone received it ⏰✨
A <replayComplete> notification tells you that all the replay notifications have been sent. It must not be sent for any other reason 🎀 If your subscription has a stop time, then the session goes back to being a normal NETCONF session. At that point the NETCONF server will accept <rpc> operations, even if it didn't accept them before because it doesn't support interleave 🫧 If there's no stop time, then after <replayComplete> goes out, you can expect everything generated since the subscription was created to show up, followed by notifications as they happen naturally in the system 🌈
Last thing, and it's important 🚨 <replayComplete> and <notificationComplete> can't be filtered out. They'll always be sent on a replay subscription that specified a <startTime> and a <stopTime>, respectively 💖
3.4. Notification Management Schema
okay so this schema is the one you use to find out which event streams the system supports 👀✨ it also defines the <replayComplete> and <notificationComplete> notifications. <replayComplete> tells you a replay has sent every applicable notification, and <notificationComplete> tells you the subscription has ended 🎀
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0"
xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"
targetNamespace="urn:ietf:params:xml:ns:netmod:notification"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xml:lang="en" version="1.0">
<xs:annotation>
<xs:documentation xml:lang="en">
A schema that can be used to learn about current
event streams. It also contains the replayComplete
and notificationComplete notification.
</xs:documentation>
</xs:annotation>
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
schemaLocation="netconf.xsd"/>
<xs:import namespace=
"urn:ietf:params:xml:ns:netconf:notification:1.0"
schemaLocation="notification.xsd"/>
<xs:element name="netconf" type="manageEvent:Netconf"/>
<xs:complexType name="Netconf">
<xs:sequence>
<xs:element name="streams" >
<xs:annotation>
<xs:documentation>
The list of event streams supported by the
system. When a query is issued, the returned
set of streams is determined based on user
privileges.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence minOccurs="1" maxOccurs="unbounded">
<xs:element name="stream">
<xs:annotation>
<xs:documentation>
Stream name, description, and other information.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="name"
type="ncEvent:streamNameType">
<xs:annotation>
<xs:documentation>
The name of the event stream. If this is
the default NETCONF stream, this must have
the value "NETCONF".
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="description"
type="xs:string">
<xs:annotation>
<xs:documentation>
A description of the event stream, including
such information as the type of events that
are sent over this stream.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="replaySupport"
type="xs:boolean">
<xs:annotation>
<xs:documentation>
An indication of whether or not event replay
is available on this stream.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="replayLogCreationTime"
type="xs:dateTime" minOccurs="0">
<xs:annotation>
<xs:documentation>
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
notification in the log. This object
is updated if the log resets
for some reason. This
object MUST be present if replay is
supported.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="replayLogAgedTime"
type="xs:dateTime" minOccurs="0">
<xs:annotation>
<xs:documentation>
The timestamp of the last notification
aged out of the log. This
object MUST be present if replay is
supported and any notifications
have been aged out of the log.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ReplayCompleteNotificationType">
<xs:complexContent>
<xs:extension base="ncEvent:NotificationContentType"/>
</xs:complexContent>
</xs:complexType>
<xs:element name="replayComplete"
type="manageEvent:ReplayCompleteNotificationType"
substitutionGroup="ncEvent:notificationContent">
<xs:annotation>
<xs:documentation>
This notification is sent to signal the end of a replay
portion of a subscription.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:complexType name="NotificationCompleteNotificationType">
<xs:complexContent>
<xs:extension base="ncEvent:NotificationContentType"/>
</xs:complexContent>
</xs:complexType>
<xs:element name="notificationComplete"
type="manageEvent:NotificationCompleteNotificationType"
substitutionGroup="ncEvent:notificationContent">
<xs:annotation>
<xs:documentation>
This notification is sent to signal the end of a
notification subscription. It is sent in the case
that stopTime was specified during the creation of
the subscription.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:schema>3.5. Subscriptions Data
subscriptions are non-persistent state, so they only live as long as their session does, or until the <stopTime> parameter says it's over 🥺🌸
3.6. Filter Mechanics
filtering is where it gets a little picky 💅 if a filter is looking for a particular value and the data item isn't in the event notification to be checked, the notification gets filtered out. for example, say you check for severity=critical in a configuration event notification where that field isn't supported. the notification is filtered out, no exceptions 🙈
for subtree filtering, a non-empty node set means the filter matches 🌈 for XPath filtering, the mechanisms defined in [XPATH] should be used to convert the returned value to boolean ✨
3.6.1. Filtering
filtering is set up when the event notification subscription gets created, through the filter parameter 🧚 and honestly a Filter only exists as a parameter to the subscription, so it's not floating around anywhere else 💜
3.7. Message Flow
okay so bestie, this part is the picture of how the whole thing actually plays out between a NETCONF client (C) and a NETCONF server (S) 🎀✨. First up, the client creates a subscription that has a <startTime>, so the server kicks things off by replaying the notifications it logged 🦋. Lowkey, it's giving "rewind then fast-forward." 🍓 Lots of rpc/rpc-reply back-and-forth can happen before the subscription exists, but the figure doesn't bother showing that, so don't be confused if it looks like it's missing 🙈.
C S
| |
| capability exchange |
|-------------------------->|
|<------------------------->|
| |
| <create-subscription> | (startTime)
|-------------------------->|
|<--------------------------|
| <rpc-reply> |
| |
| <notification> |
|<--------------------------|
| |
| <notification> |
|<--------------------------|
| <notification> | (replayComplete)
|<--------------------------|
| |
| |
| |
| <notification> |
|<--------------------------|
| |
| |
| <notification> |
|<--------------------------|
| |
| |Figure 3
Now the second version is the one with a <startTime> and a <stopTime> 💅. This subscription replays the logged notifications first, and then the session goes back to being a normal command-response NETCONF session once <replayComplete> and <notificationComplete> have been sent 🌸. After that it's ready to handle <rpc> requests again. Same deal as before: plenty of rpc/rpc-reply sequences might happen before the subscription gets created, and the figure skips them 💜.
C S
| |
| capability exchange |
|-------------------------->|
|<------------------------->|
| |
| <create-subscription> | (startTime,
|-------------------------->| stopTime)
|<--------------------------|
| <rpc-reply> |
| |
| <notification> |
|<--------------------------|
| |
| <notification> |
|<--------------------------|
| <notification> | (replayComplete)
|<--------------------------|
| <notification> |(notificationComplete)
|<--------------------------|
| |
| |
| |
| <rpc> |
|-------------------------->|
|<--------------------------|
| <rpc-reply> |
| |Figure 4
4. XML Schema for Event Notifications ✨
Here's the [XMLSchema] that defines NETCONF Event Notifications 🧚. It's the official blueprint, so it's worth reading carefully 💖.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"
targetNamespace=
"urn:ietf:params:xml:ns:netconf:notification:1.0"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xml:lang="en">
<!-- import standard XML definitions -->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd">
<xs:annotation>
<xs:documentation>
This import accesses the xml: attribute groups for the
xml:lang as declared on the error-message element.
</xs:documentation>
</xs:annotation>
</xs:import>
<!-- import base netconf definitions -->
<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
schemaLocation="netconf.xsd"/>
<!-- ************** Symmetrical Operations ********************-->
<!-- <create-subscription> operation -->
<xs:complexType name="createSubscriptionType">
<xs:complexContent>
<xs:extension base="netconf:rpcOperationType">
<xs:sequence>
<xs:element name="stream"
type="streamNameType" minOccurs="0">
<xs:annotation>
<xs:documentation>
An optional parameter that indicates
which stream of events is of interest.
If not present, then events in the
default NETCONF stream will be sent.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="filter"
type="netconf:filterInlineType"
minOccurs="0">
<xs:annotation>
<xs:documentation>
An optional parameter that indicates
which subset of all possible events
is of interest. The format of this
parameter is the same as that of the
filter parameter in the NETCONF
protocol operations. If not
present, all events not precluded
by other parameters will be sent.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="startTime" type="xs:dateTime"
minOccurs="0" >
<xs:annotation>
<xs:documentation>
A parameter used to trigger the replay
feature indicating that the replay
should start at the time specified. If
start time is not present, this is not a
replay subscription.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="stopTime" type="xs:dateTime"
minOccurs="0" >
<xs:annotation>
<xs:documentation>
An optional parameter used with the
optional replay feature to indicate the
newest notifications of interest. If
stop time is not present, the
notifications will continue until the
subscription is terminated. Must be
used with startTime.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:simpleType name="streamNameType">
<xs:annotation>
<xs:documentation>
The name of an event stream.
</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string"/>
</xs:simpleType>
<xs:element name="create-subscription"
type="createSubscriptionType"
substitutionGroup="netconf:rpcOperation">
<xs:annotation>
<xs:documentation>
The command to create a notification subscription. It
takes as argument the name of the notification stream
and filter. Both of those options
limit the content of the subscription. In addition,
there are two time-related parameters, startTime and
stopTime, which can be used to select the time interval
of interest to the notification replay feature.
</xs:documentation>
</xs:annotation>
</xs:element>
<!-- ************** One-way Operations ******************-->
<!-- <Notification> operation -->
<xs:complexType name="NotificationContentType"/>
<xs:element name="notificationContent"
type="NotificationContentType" abstract="true"/>
<xs:complexType name="NotificationType">
<xs:sequence>
<xs:element name="eventTime" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
The time the event was generated by the event source.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element ref="notificationContent"/>
</xs:sequence>
</xs:complexType>
<xs:element name="notification" type="NotificationType"/>
</xs:schema>5. Filtering Examples ✨
okay so this section is where we get to actually see filters in action 🎀 these examples all use some made-up event notifications so we have something to filter on.
To make the filter expressions make sense, we have to pretend the event notification content looks a certain way. The examples assume the event notification schema has a top-level <event> element made up of an event class (like fault, state, or config), a reporting entity, and either a severity or an operational state.
Every example in this section comes from this fictional schema 💅
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://example.com/event/1.0"
xmlns="http://example.com/event/1.0"
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
<xs:import namespace=
"urn:ietf:params:xml:ns:netconf:notification:1.0"
schemaLocation="notification.xsd"/>
<xs:complexType name="eventType">
<xs:complexContent>
<xs:extension base="ncEvent:NotificationContentType">
<xs:sequence>
<xs:element name="eventClass" />
<xs:element name="reportingEntity">
<xs:complexType>
<xs:sequence>
<xs:any namespace="##any"
processContents="lax"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:choice>
<xs:element name="severity"/>
<xs:element name="operState"/>
</xs:choice>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="event"
type="eventType"
substitutionGroup="ncEvent:notificationContent"/>
</xs:schema>Using that made-up schema, you can get this sample notification list, which the rest of the section uses 🦋
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-07-08T00:01:00Z</eventTime>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<reportingEntity>
<card>Ethernet0</card>
</reportingEntity>
<severity>major</severity>
</event>
</notification>
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-07-08T00:02:00Z</eventTime>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<reportingEntity>
<card>Ethernet2</card>
</reportingEntity>
<severity>critical</severity>
</event>
</notification>
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-07-08T00:04:00Z</eventTime>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<reportingEntity>
<card>ATM1</card>
</reportingEntity>
<severity>minor</severity>
</event>
</notification>
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-07-08T00:10:00Z</eventTime>
<event xmlns="http://example.com/event/1.0">
<eventClass>state</eventClass>
<reportingEntity>
<card>Ethernet0</card>
</reportingEntity>
<operState>enabled</operState>
</event>
</notification>5.1. Subtree Filtering
ngl subtree filtering is not the move if you want fancy filters 😭 it only does equality checks and the logical OR. so you can say "give me the events where severity=critical, severity=major, OR severity=minor," but that's about it. It's still fine for simple event forwarding filters though, and the examples below show how 🌸
This first example picks out fault events whose severity is critical, major, or minor. Here's how the filtering criteria get evaluated:
((fault & severity=critical) | (fault & severity=major) | (fault & severity=minor))<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<filter netconf:type="subtree">
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<severity>critical</severity>
</event>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<severity>major</severity>
</event>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<severity>minor</severity>
</event>
</filter>
</create-subscription>
</netconf:rpc>This next one selects state or config event classes, plus fault events that come from card Ethernet0. The filtering criteria look like this:
( state | config | ( fault & ( card=Ethernet0)))<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<filter netconf:type="subtree">
<event xmlns="http://example.com/event/1.0">
<eventClass>state</eventClass>
</event>
<event xmlns="http://example.com/event/1.0">
<eventClass>config</eventClass>
</event>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<reportingEntity>
<card>Ethernet0</card>
</reportingEntity>
</event>
</filter>
</create-subscription>
</netconf:rpc>5.2. XPATH Filters
Now we're getting into the fancier stuff with [XPATH] 🧚 This example picks out fault EventClass notifications with severities of critical, major, or minor. The filtering criteria look like this:
((fault) & ((severity=critical) | (severity=major) | (severity = minor)))<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<filter netconf:type="xpath"
xmlns:ex="http://example.com/event/1.0"
select="/ex:event[ex:eventClass='fault' and
(ex:severity='minor' or ex:severity='major'
or ex:severity='critical')]"/>
</create-subscription>
</netconf:rpc>Last one! This example picks out state and config event classes, plus fault events of any severity from card Ethernet0. The filtering criteria are:
( state | config | (fault & card=Ethernet0))<netconf:rpc message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<filter netconf:type="xpath"
xmlns:ex="http://example.com/event/1.0"
select="/ex:event[
(ex:eventClass='state' or ex:eventClass='config') or
((ex:eventClass='fault' and ex:card='Ethernet0'))]"/>
</create-subscription>
</netconf:rpc>6. Interleave Capability 🦋
6.1. Description
The :interleave capability says the NETCONF peer can squeeze other NETCONF operations into a notification subscription while it's running 🙌 So the NETCONF server MUST receive, process, and respond to NETCONF requests on a session that has an active notification subscription. Honestly this is so good for scalability, because you don't need as many NETCONF sessions for each operator or management app 💜
6.2. Dependencies
This capability only works if the notification capability is supported too 🫶
6.3. Capability Identifier
The :interleave capability is identified by this capability string:
urn:ietf:params:netconf:capability:interleave:1.06.4. New Operations
None. 🍓
6.5. Modifications to Existing Operations
If a <create-subscription> gets sent while another subscription is already active on that session, the server returns this error:
Tag: operation-failed
Error-type: protocol
Severity: error
Error-info: none
Description: Request could not be completed because the requested
operation failed for some reason not covered by any other error
condition.7. Security Considerations 🔐
okay bestie, this part is serious, so read it carefully 💀
The security considerations from the base [NETCONF] document also apply to the Notification capability.
The access control framework and the choice of transport will have a major impact on how secure the whole solution is.
The <notification> elements are never sent before the transport layer and the NETCONF layer, including capabilities exchange, have been established and the manager has been identified and authenticated.
It is recommended that care be taken to secure execution of:
<create-subscription>invocation<get>on read-only data models<notification>content
Secure execution means making sure a secure transport is used, AND that the user has enough authorization to do the thing they're asking for against the specific subset of NETCONF content involved. When a <get> comes in that refers to the content defined in this memo, clients should only be able to view the content they have sufficient privileges for. A <create-subscription> operation can be considered like a deferred <get>, and the content different users can access may vary. That different access is reflected in the <notification> that different users are able to subscribe to.
One potential security issue is transporting data from non-NETCONF streams, like syslog and SNMP. This data may be more vulnerable (or less vulnerable) when it's carried over NETCONF than when it's carried by the protocol normally used for it, depending on the security credentials of the two subsystems. The NETCONF server is responsible for applying access control to stream content.
The contents of notifications, plus the names of event streams, may contain sensitive information, so take care that only authorized users can view them. The NETCONF server MUST NOT include any content in a notification that the user is not authorized to view. 🙅♀️
If a subscription is created with a <stopTime>, the NETCONF session goes back to being a normal command-response NETCONF session once the replay is completed. It is the responsibility of the NETCONF client to close this session when it is no longer of use.
If a malicious or buggy NETCONF client sends a bunch of <create-subscription> requests, those subscriptions pile up and can eat up system resources 😱 In that situation, the subscriptions can be terminated by terminating the suspect underlying NETCONF sessions using the <kill-session> operation.
8. IANA Considerations ✨
okay so this one's the paperwork part, but it's still important bestie 📋. This document registers three URIs for the NETCONF XML namespace in the IETF XML registry [RFC3688]. Yep, three. We'll get to the list in a sec 🎀
IANA followed the format from RFC 3688 for the registration. The capability URNs also follow section 10.3 of [NETCONF], so everything lines up 💅
+--------------------+----------------------------------------------+
| Index | Capability Identifier |
+--------------------+----------------------------------------------+
| :notification | urn:ietf:params:netconf:capability: |
| | notification:1.0 |
| | |
| :interleave | urn:ietf:params:netconf:capability: |
| | interleave:1.0 |
+--------------------+----------------------------------------------+
URI: urn:ietf:params:xml:ns:netmod:notification
URI: urn:ietf:params:xml:ns:netconf:notification:1.0
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.IANA also registered the XML Schema defined in Section 4 🧚
9. Acknowledgements 💖
thank you thank you 🫶 Gilbert Gagnon, Greg Wilbur, and Kim Curran gave input during the early work on this doc, so they get a big shoutout ✨
The editors also want to thank the people who helped at the Vancouver editing session: Orly Nicklass, James Balestriere, Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, Dave Partain, Ray Atarashi, and David Perkins 🌸
Then there's the Montreal editing session crew: Balazs Lengyel, Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, and William Chow 👑
Extra thanks to Li Yan for the many reviews 🙌 and to Suresh Krishnan for the gen-art review of the document 💜
10. Normative References 📚
These are the docs the spec leans on, so implementers need them too:
- [NETCONF]: Enns, R., Ed., "NETCONF Configuration Protocol", RFC 4741, December 2006.
- [RFC2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC3339]: Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002.
- [RFC3688]: Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
- [XML]: World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C XML, February 1998,
http://www.w3.org/TR/1998/REC-xml-19980210. - [XMLSchema]: Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML Schema Part 1: Structures Second Edition", W3C
http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/structures.html, October 2004. - [XPATH]: Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", W3C
http://www.w3.org/TR/1999/REC-xpath-19991116, November 1999.
Authors' Addresses 🦋
Who wrote this? Meet the authors:
Sharon Chisholm
Nortel
3500 Carling Ave
Nepean, Ontario K2H 8E9
Canada
EMail: schishol@nortel.com
Hector Trevino
Cisco
Suite 400
9155 E. Nichols Ave
Englewood, CO 80112
USA
EMail: htrevino@cisco.comFull Copyright Statement ⚖️
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions contained in BCP 78. Except as set out there, the authors keep all their rights 🔒
This document and the information in it are provided on an "AS IS" basis. THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 😭
Intellectual Property 💜
The IETF doesn't take a position on whether any Intellectual Property Rights or other rights claimed for the technology in this document are valid or in scope. It also doesn't say whether licenses for those rights are available, and it hasn't independently checked for any such rights 🧐 For the procedures on rights in RFC documents, look at BCP 78 and BCP 79.
Copies of IPR disclosures sent to the IETF Secretariat, assurances of licenses, and the results of attempts to get a general license or permission for implementers or users are available from the IETF's online IPR repository at http://www.ietf.org/ipr.
The IETF invites anyone to point out any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard. Send that info to the IETF at ietf-ipr@ietf.org 🫶
📦 where this page comes from
- ietf: rfc5277 2008-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms