netconfd-pro Notifications
The netconfd-pro server supports all the capabilities of RFC 5277, and the notification monitoring portion of the ietf-netconf-monitoring.yang data model. All standard NETCONF notifications are supported (RFC 5277 and RFC 6470). There are also some deprecated proprietary notifications defined in yuma-system.yang.
The netconfd-pro server now supports the new NETCONF notification subscription model defined in:
RFC 8639: Subscription to YANG Notifications
RFC 8640: Dynamic Subscription to YANG Events and Datastores over NETCONF
RFC 8641: Subscription to YANG Notifications for Datastore Updates
This data model includes traditional event stream subscriptions and YANG Push datastore subscriptions.
Note
The default format for the 'eventTime' leaf now includes microsecond resolution, as permitted in the 'date-and-time' data type. Set the --highres-event-time parameter to 'false' for the old behavior without the partial seconds field.
Enabling Notifications
The netconfd-pro server can be invoked with or without NETCONF notification support enabled. Notifications are enabled by default.
Note
By default, up to 1000 notifications will be saved in memory for Notification Replay.
This can utilize significant memory, especially if --with-yumaworks-config-change='true' (not the default). and many (or large) configuration edits are done.
To reduce memory usage, set the --eventlog-size parameter to a low number, such as '10'.
The --with-notifications CLI parameter is used to control this feature. This parameter only needs to be used to disable notifications. The parameter value --with-notifications=false will prevent the notification YANG modules from being loaded, prevent the :notifications and :interleave capabilities from being advertised in the <hello> message, and there will not be any event history buffer maintained.
Event Stream Model
NETCONF notifications use a generic “event stream” publishing model. The netconfd-pro server fully supports configuration of these event streams for the NETCONF protocol. Event streams allow the various notification messages to be partitioned, usually by topic, so the client can subscribe to the selected event stream and only receive the event types related to the published topic (e.g., stream name).
This form of content-filtering is much simpler to use than NETCONF notification filters specified in subtree or XPath form. There is a level of indirection added, so the exact notification messages do not need to be known in advance or maintained by the client.
Static event stream management with CLI parameters is supported. The
server configuration file (E.g. netconfd-pro.conf) has to be
modified, and/or the server restarted, to change the static event stream
configuration.
Dynamic custom event streams allow event streams to be added and deleted at run-time with the yumaworks-event-stream.yang module. This is enabled with the --with-yumaworks-event-stream CLI parameter.
Modules can be re-mapped to different streams, to redistribute or simply reconfigure the event stream content. Event stream replay buffers can be cleared using the <clear-eventlog> RPC operation.
YANG 1.1 Nested Notifications
Note
Nested notifications are only available in the 22.10 (and later) release train.
The server supports nested notification definitions defined in RFC 7950.
A nested notification is defined within a data node hierarchy, in the same way as a YANG 1.1 'action' statement.
The path to the notification node is used to identify the event type because the event type name does not have to be unique within the YANG module, like a top-level notification.
The <notification> element will not contain the notification directly.
The <notification> element will contain the hierarchy of data nodes from the notification to the top-level container or list.
The ancestor key leafs are the only other data nodes encoded in the data node ancestor hierarchy.
The notification event type is encoded as normal after the key leafs in the innermost nest level of the message.
Example YANG module showing nested notification statements:
module notif4 {
yang-version 1.1;
namespace "urn:yumaworks:params:xml:ns:notif4";
prefix "n4";
revision 2022-07-25 {
description
"YPW-1910: Support YANG 1.1 nested notifications";
}
revision 2022-03-25 {
description
"Initial revision.";
}
container A {
list B {
key "row column";
leaf row { type uint16; }
leaf column { type uint16; }
list BB {
key "idx";
leaf idx { type string; }
leaf col1 { type string; }
list BBB {
key "idx";
leaf idx { type string; }
leaf col1 { type string; }
notification N1 {
leaf parm1 { type string; }
leaf parm2 { type int16; }
}
action A1;
}
notification N1 {
leaf parm3 { type string; }
leaf parm4 { type int16; }
}
action A1;
}
notification N1 {
leaf parm1 { type string; }
leaf parm2 { type int16; }
}
action A1;
}
notification N1 {
leaf parm1 { type string; }
leaf parm2 { type int16; }
}
action A1;
}
notification N1 {
leaf parm1 { type string; }
leaf parm2 { type int16; }
}
}
In this test module, the 'N1' event type is defined at 5 levels:
Node Level |
Example Path to N1 |
|---|---|
1 (top-level) |
/N1 |
2 (container A) |
/A/N1 |
3 (list B) |
/A/B[row='3'][column='13']/N1 |
4 (list BB) |
/A/B[row='2'][column='20']/BB[idx='idx-dummy2']/N1 |
5 (list BBB) |
/A/B[row='1'][column='11']/BB[idx='idx-dummy']/BBB[idx='idx1-dummy']/N1 |
Nested Notification Message Examples
The following XML snippets show example messages of these nested notifications:
Level 1: /N1
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2022-04-03T16:47:11Z</eventTime>
<N1 xmlns="urn:yumaworks:params:xml:ns:notif4">
<parm1>parm1-dummy4</parm1>
<parm2>1000</parm2>
</N1>
</notification>
Level 2: /A/N1
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2022-04-03T16:47:11Z</eventTime>
<A xmlns="urn:yumaworks:params:xml:ns:notif4">
<N1>
<parm1>parm1-dummy3</parm1>
<parm2>800</parm2>
</N1>
</A>
</notification>
Level 3: /A/B[row='3'][column='13']/N1
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2022-04-03T16:47:11Z</eventTime>
<A xmlns="urn:yumaworks:params:xml:ns:notif4">
<B>
<row>3</row>
<column>13</column>
<N1>
<parm1>parm1-dummy2</parm1>
<parm2>600</parm2>
</N1>
</B>
</A>
</notification>
Level 4: /A/B[row='2'][column='20']/BB[idx='idx-dummy2']/N1
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2022-04-03T16:47:11Z</eventTime>
<A xmlns="urn:yumaworks:params:xml:ns:notif4">
<B>
<row>2</row>
<column>20</column>
<BB>
<idx>idx-dummy2</idx>
<N1>
<parm3>parm3-dummy</parm3>
<parm4>400</parm4>
</N1>
</BB>
</B>
</A>
</notification>
Level 5: /A/B[row='1'][column='11']/BB[idx='idx-dummy']/BBB[idx='idx1-dummy']/N1
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2022-04-03T16:47:11Z</eventTime>
<A xmlns="urn:yumaworks:params:xml:ns:notif4">
<B>
<row>1</row>
<column>11</column>
<BB>
<idx>idx-dummy</idx>
<BBB>
<idx>idx1-dummy</idx>
<N1>
<parm1>parm1-dummy</parm1>
<parm2>200</parm2>
</N1>
</BBB>
</BB>
</B>
</A>
</notification>
Default Event Streams
The NETCONF notification delivery system allows for multiple event streams. Each event stream has its own subscriptions and its own notification queue (replay buffer).
The server will always setup the default event stream.
By default, the notifications defined in ietf-netconf-notifications.yang are sent to this event stream.
For NETCONF, this stream is named 'NETCONF'
For RESTCONF this stream is named 'RESTCONF'
Using Custom Event Streams
Event streams can be used to group notification events for different reasons, such as by topic, or frequency, or severity. Clients can use NETCONF or RESTCONF to monitor any event stream.
Event Stream CLI Parameters
The --event-stream parameter is used to configure an additional event stream.
The --event-stream-map parameter is used to assign all notifications defined in a specific module to an event stream.
Example: create the ‘hardware’ event stream and 2 event-stream-map entries:
> netconfd-pro --event-stream=hardware \
--event-stream-map=ietf-hardware@hardware \
--event-stream-map=openconfig-platform@hardware
Event Stream YANG Module
The yumaworks-event-stream.yang module can be used to configure event streams at run-time. This method should be used instead of CLI parameters.
The event streams can only be created or deleted, and cannot be modified.
Only a --superuser can edit this YANG module by default, unless --access-control is disabled.
The 'eventlog-size' parameter allows Notification Replay to be configured per-stream, to override the --eventlog-size CLI parameter.
The 'description' parameter allows an administrative string to be used in the event stream description for monitoring purposes.
Example: Same as 'hardware' CLI example above with an eventlog size of 10 events and a custom description:
<event-streams xmlns="http://yumaworks.com/ns/yumaworks-event-stream">
<event-stream>
<name>hardware</name>
<eventlog-size>100</eventlog-size>
<description>hardware related events</description>
</event-stream>
<module-map>
<module-name>ietf-hardware</module-name>
<stream-name>hardware</stream-name>
</module-map>
<module-map>
<module-name>openconfig-platform</module-name>
<stream-name>hardware</stream-name>
</module-map>
</event-streams>
Event Stream Assignment
Normally an event generated by internal YANG instrumentation will be sent to the NETCONF event stream. There are three ways for notifications to be assigned to a configured stream, checked in this order:
New Server API: The instrumentation can specify the event stream name. If this is configured it will be used for the queued notification.
--event-stream-map CLI parameter:
The user can configure module to event stream mappings at boot-time.
These entries are added to the event stream monitoring data.
These entries cannot be removed at runtime.
-
The user can configure module to event stream mappings at run-time with a YANG module.
The entries are saved as normal YANG configuration and used immediately and at the next reboot.
See Using Dynamic Event Streams with yumaworks-event-streams.yang.
Notes:
If no event stream is specified by the event generator (e.g., SIL instrumentation) then the server will use the event-stream-map parameter to find a mapping.
If no mapping then the YANG module 'event-stream' entries are checked.
If no YANG entry for the module containing the notification is found then the default event stream 'NETCONF' (and 'RESTCONF') is used.
Event Stream Monitoring
NETCONF and RESTCONF have separate notification monitoring data.
NETCONF Event Stream Monitoring
The event streams that are enabled on the NETCONF server can be monitored using
the notifications.yang module, which contains a top-level container
called /netconf.
Example: /netconf/streams/stream list contains ‘NETCONF’ and
‘hardware’ streams.
andy@localhost> sget /netconf
Filling container /netconf:
RPC Data Reply 2 for session 3 [default]:
rpc-reply {
data {
netconf {
streams {
stream NETCONF {
name NETCONF
description 'default NETCONF event stream'
replaySupport true
replayLogCreationTime 2024-02-19T19:44:19.317184Z
}
stream hardware {
name hardware
description 'hardware related events'
replaySupport true
replayLogCreationTime 2024-02-19T19:44:19.317192Z
}
}
}
}
}
RESTCONF Event Stream Monitoring
The event streams that are enabled on the RESTCONF
server can be monitored using
the ietf-restconf-monitoring.yang module,
which contains a top-level container
called /restconf-state.
The 'location' leaf in each entry is used as the Request URI when retrieving RESTCONF notifications.
The legacy 'RESTCONF' stream is always found as the '/restconf/stream' location.
The 'NETCONF' stream is always found as the '/restconf/streams/NETCONF' location.
Custom event streams (if any) are found as the '/restconf/streams/<stream-name>' location, where '<stream-name>' is the configured stream name.
Only XML access is provided at this time.
Example: /restconf-state/streams/stream list contains ‘NETCONF’ and
‘hardware’ streams.
andy@localhost> sget /restconf-state/streams
Filling container /restconf-state/streams:
RPC Data Reply 5 for session 3 [default]:
rpc-reply {
data {
restconf-state {
streams {
stream NETCONF {
name NETCONF
description 'default NETCONF event stream'
replay-support true
replay-log-creation-time 2024-02-19T20:46:38Z
access xml {
encoding xml
location http://localhost/restconf/streams/NETCONF
}
}
stream hardware {
name hardware
description 'hardware related events'
replay-support true
replay-log-creation-time 2024-02-19T20:46:38Z
access xml {
encoding xml
location http://localhost/restconf/streams/hardware
}
}
stream RESTCONF {
name RESTCONF
description 'default RESTCONF event stream'
replay-support true
replay-log-creation-time 2024-02-19T20:46:38Z
access xml {
encoding xml
location http://localhost/restconf/stream
}
}
}
}
}
}
Using Dynamic Event Streams with yumaworks-event-streams.yang
Starting in release 20.10-7 the event streams can be configured at run-time using the yumaworks-event-stream.yang module.
This module provides configuration objects to match the --event-stream and --event-stream-map CLI parameters.
This module must be disabled using the --with-yumaworks-event-stream CLI parameter to prevent this module from being used. The default is to include this module.
The CLI parameters are still used, and any event streams configured with CLI parameters will be setup first, before any YANG-configured event streams. The name “NETCONF” is reserved and cannot be used.
list
event-streams/event-stream: Each configured event-stream can have a different replay buffer size, or replay can be disabled per event-stream. Names cannot conflict with any --event-stream values.list
event-streams/module-map: Each module can be mapped to zero or one event streams. The ‘stream-name’ parameter cannot conflict with any --event-stream values. This has the same effect as the event-stream-map parameter.rpc <clear-eventlog>: Clears all saved events in the replay buffer for the event stream
Subscriptions
RFC 5277 subscriptions
The <create-subscription> operation is used to start receiving notification.
It can be used in 4 different modes:
Get all or some of the stored notifications.
<startTime> and <stopTime> parameters used; The stop time is in the past.
Get all or some of the stored notifications, then receive live notifications until some point in the future.
<startTime> and <stopTime> parameters used; The stop time is in the future.
Get all or some of the stored notifications, then start receiving live notifications until the session is terminated.
<startTime> parameter used, but <stopTime> parameter is not used
Start receiving live notifications until the session is terminated
neither <startTime> or <stopTime> are used
Once a subscription is started, notifications may start arriving, after the <rpc-reply> for the <create-subscription> operation is sent.
If the <startTime> parameter is used, then zero or more stored notifications will be returned, followed by the <replayComplete> notification.
If the <stopTime> parameter is also used, then the <notificationComplete> notification will be sent when this stop time has passed. After that, no more notifications will be sent to the session, and the subscription is terminated. After this point, another subscription could be started.
Only one subscription can be active on a session at a time. There is no way to terminate a subscription, other than to close the session.
RFC 8639 Subscriptions
The <establish-subscription> operation from RFC 8639 is the replacement for <create-subscription> and should be used instead, if possible.
Features:
Improved filtering options
Multiple subscriptions per session allowed
Notification Log
Each system event is saved to the notification replay buffer for the NETCONF event stream.
The '<replayComplete>' and '<notificationComplete>' notifications are not saved to this buffer because they are subscription-specific events, and not system events.
Each event stream has its own replay buffer. The size of each replay buffer is controlled by the --eventlog-size configuration parameter.
The default size is 1000 events.
If the yumaworks-event-stream.yang module is used then the 'eventlog-size' leaf is used for the eventlog size.
The oldest event will be deleted when a new event is added, when this limit is reached. If the eventlog-size is zero then usually only one oldest event will be kept in memory.
If --eventlog-size is set to zero, then there will be no replayed notifications available, and the <replayComplete> notification will be sent right away, if <startTime> is present.
Each event in the replay buffer is assigned a sequential sequence ID, starting from 1. Each event stream has its own sequence ID counter. Values are only specific to one event stream and will be duplicated in each event stream.
The <sequence-id> leaf is an unsigned 32-bit integer, which is added to the <notification> element, after the event element. This sequence can be used to debug filters by comparing the sequence IDs of the notifications that were delivered against the expected sequence IDs. This leaf is only added to each notification if the agt_notif_sequence_id flag is set to 'true' in the agt_profile_t Struct for the server. By default, this flag is set to 'false'.
Using Event Filters
An event filter is a way to disable generation of specific notification event types from being added to the notification replay buffer. This can be useful if some events are not of interest to the applications, so there is no reason to use replay buffer resources to store them.
If RFC 8639 notifications are used, then the
module ietf-subscribed-notifications.yang provided
the /filters subtree. This should be used instead of
the older proprietary module.
If only RFC 5277 notifications, then the YANG
module yumaworks-event-filter.yang contains
the /event-filters definitions.
A client can configure event-filter list entries in
the /event-filters/event-filter list to suppress generation of
specific events.
Each entry is identified by the module name and the notification event name.
An entry does not have to reference a valid module and/or notification name. This allows filters to be present before modules are loaded into the server. If a module is loaded at run-time with the <load> or <load-bundle> operation, then the event filters will be checked and applied as needed at that time.
For example, the 'foo-event1' notification in the 'acme-foo' module might be defined as followed:
module acme-foo {
namespace “http://acme.com/ns/foo”;
prefix af;
notification foo-event1 {
leaf foo-count { type uint32; }
leaf foo-msg { type string; }
}
}
To create an event filter, the client may send an <edit-config> operation request as follows:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" trace-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<default-operation>merge</default-operation>
<test-option>set</test-option>
<config>
<event-filters xmlns="http://yumaworks.com/ns/yumaworks-event-filter">
<event-filter xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
nc:operation="merge">
<module>acme-foo</module>
<event>foo-event1</event>
</event-filter>
</event-filters>
</config>
</edit-config>
</rpc>
Logging Event Drops
If the --log-event-drops CLI parameter is set to 'true' then a log entry will be generated each time an event is dropped because it is suppressed.
The default is 'false' (event drops due to an event filter are not logged).
Event drops due to other reasons are not affected by this CLI parameter.
Using Notification Filters
Note
A notification filter is different than a <get> or <get-config> filter.
Instead of selecting sub-trees of the specified database, it is treated as a boolean expression. If the filter matches the content in the notification, then the notification is sent to that subscription. If the filter does not match the content, then the notification is not sent to that subscription.
A filter match for notification purposes means that the filter is conceptually applied, as if it were a <get> operation, and if any nodes are selected (non-empty result node-set), then the filter is a match. If no content is selected (empty result node-set), then the filter is not a match.
The first node that can appear in the filter is the event type. The <eventTime> and <sequence-id> nodes are siblings of the event type element, so they cannot be used in a notification filter.
<notification> Element
The notification element contains 2 or 3 child elements, in this order:
eventTime: timestamp for the event. The namespace URI for this element is
urn:ietf:params:xml:ns:netconf:notification:1.0. The --highres-event-time CLI parameter controls the format of this leaf.eventType: The real name will be the name of the YANG notification, such as 'sysStartup'. The contents of this element will depend on the YANG notification definition. The namespace URI for this element will be different for every event type. It will be the same value as the YANG namespace statement in the module that defines the notification statement for the particular event type.
sequence-id: The system event sequence ID. Session or subscription specific events, such as 'replayComplete' and 'notificationComplete' do not have this element. The namespace URI for this element is
http://netconfcentral.org/ns/system.This leaf is only added to each notification if the agt_notif_sequence_id field is set to 'true' in the agt_profile_t Struct for the server. By default, this leaf is not included in the notification. There is no CLI parameter to enable this leaf.
System Notifications
The ietf-netconf-notifications.yang module from RFC 6470 are implemented. These notifications are based on the yuma-system.yang notifications.
The --system-notifications CLI parameter can select the
IETF or deprecated yuma notifications. This parameter SHOULD NOT
be set to disable ietf system notifications.
Note
The yuma-system notifications are deprecated and SHOULD NOT be used.
<replayComplete> Event
The <replayComplete> event is generated on a subscription that requested notification replay (by supplying the <startTime> parameter). This event type cannot be filtered out. The server will always attempt to deliver this notification event type when it is generated.
+---n replayComplete
<replayComplete> Notification
Description: |
Buffered notification delivery has ended for a subscription |
Min parameters: |
0 |
Max parameters: |
0 |
YANG file: |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
<ncEvent:eventTime>2009-07-29T17:21:37Z</ncEvent:eventTime>
<manageEvent:replayComplete xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/>
</ncEvent:notification>
<notificationComplete> Event
The <notificationComplete> event is generated on a subscription that requested notification replay, and requested that the notification delivery stop (i.e., terminate subscription), after a certain time, using the <stopTime> parameter.
This event type cannot be filtered out. The server will always attempt to deliver this notification event type when it is generated.
+---n notificationComplete
<notificationComplete> Notification
Description: |
All notification delivery has ended, and the subscription is terminated. |
Min parameters: |
0 |
Max parameters: |
0 |
YANG file: |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
<ncEvent:eventTime>2009-07-29T17:31:22Z</ncEvent:eventTime>
<manageEvent:notificationComplete xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/>
</ncEvent:notification>
<sysStartup> Event
Note
The <sysStartup> notification is deprecated. So not use.
The <sysStartup> event is the first notification generated when the server starts or restarts. It contains the startup file source (if any) and lists any <rpc-error> contents that were detected at boot-time, during the copying of the startup configuration into the running configuration.
The system-notifications parameter must include “yuma” for this event to be generated.
+---n sysStartup
+--ro startupSource? string
+--ro bootError* []
+--ro error-type enumeration
+--ro error-tag nc:error-tag-type
+--ro error-severity nc:error-severity-type
+--ro error-app-tag? string
+--ro error-path? yang:xpath1.0
+--ro error-message? LangString2
+--ro error-info? <anyxml>
<sysStartup> Notification
Description: |
The netconfd-pro server has started |
Min parameters: |
0 |
Max parameters: |
2 |
YANG file: |
Parameters:
startupSource
type: string
usage: optional (will not be present if --no-startup was present)
This parameter identifies the local file specification associated with the source of the startup configuration contents.
bootError
type: list (same structure as <rpc-error> element)
usage: optional (will only be present if errors were recorded during boot)
There will be one entry for each <rpc-error> encountered during the load config operation. The <rpc-error> fields are used directly.
There is no particular order, so no key is defined.
All fields except <error-info> will be present from the original <rpc-error> that was generated during the boot process.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
<ncEvent:eventTime>2009-07-29T17:21:13Z</ncEvent:eventTime>
<sys:sysStartup xmlns:sys="http://netconfcentral.org/ns/system">
<sys:startupSource>/home/andy/swdev/yuma/trunk/netconf/data/startup-cfg.xml</sys:startupSource>
</sys:sysStartup>
<sys:sequence-id xmlns:sys="http://netconfcentral.org/ns/system">1</sys:sequence-id>
</ncEvent:notification>
<netconf-session-start> Event
The <netconf-session-start> notification is generated when a NETCONF session is started.
The username, remote address, and session ID that was assigned are returned in the event payload.
+---n netconf-session-start
+--ro username string
+--ro session-id nc:session-id-or-zero-type
+--ro source-host? inet:ip-address
<netconf-session-start> Notification
Description: |
A new NETCONF session has started. |
Min parameters: |
3 |
Max parameters: |
3 |
YANG file: |
Parameters:
username
type: string
usage: mandatory
This parameter identifies the SSH user name that is associated with the session.
session-id
type: uint32 (range 1 to max)
usage: mandatory
This parameter identifies the NETCONF session ID assigned to the session.
source-host
type: inet:ip-address
usage: mandatory
This parameter identifies the remote host IP address that is associated with the session.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-04-20T18:38:08Z</eventTime>
<netconf-session-start
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<username>andy</username>
<session-id>4</session-id>
<source-host>127.0.0.1</source-host>
</netconf-session-start>
</notification>
<netconf-session-end> Event
The <netconf-session-end> notification is generated when a NETCONF session is terminated.
The username, remote address, and session ID that was assigned are returned in the event payload. The termination reason is also included.
If the session was terminated before it properly started, it is possible that there will not be a <netconf-session-start> notification event to match the <netconf-session-end> event. For example, if the initial SSH connection setup fails before the <hello> message is processed, then only a <netconf-session-end> notification event will be generated. In this case, the user name and other session information may not be available.
+---n netconf-session-end
+--ro username string
+--ro session-id nc:session-id-or-zero-type
+--ro source-host? inet:ip-address
+--ro killed-by? nc:session-id-type
+--ro termination-reason enumeration
<netconf-session-end> Notification
Description: |
A NETCONF session has terminated. |
Min parameters: |
1 |
Max parameters: |
5 |
YANG file: |
Parameters:
username
type: string
usage: mandatory
This parameter identifies the SSH user name that is associated with the session.
session-id
type: uint32 (range 1 to max)
usage: mandatory
This parameter identifies the NETCONF session ID assigned to the session.
source-host
type: inet:ip-address
usage: mandatory
This parameter identifies the remote host IP address that is associated with the session.
killed-by
type: uint32 (range 1 to max)
usage: optional (will only be present if the terminationReason leaf is equal to 'killed'.
This parameter identifies the session number of the session that issued the <kill-session> operation.
termination-reason
type: enumeration (closed, killed, dropped, timeout, bad-start, bad-hello, other)
usage: mandatory
This parameter indicates why the session was terminated.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-04-20T18:41:01Z</eventTime>
<netconf-session-end
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<username>andy</username>
<session-id>4</session-id>
<source-host>127.0.0.1</source-host>
<killed-by>4</killed-by>
<termination-reason>closed</termination-reason>
</netconf-session-end>
</notification>
<netconf-config-change> Event
The <netconf-config-change> notification is generated when the <running> configuration database is altered by a NETCONF session.
If the :candidate capability is supported, then this event is generated when the <commit> operation completes.
If the :writable-running capability is supported instead, then this even is generated when the <edit-config> operation completes.
The user name, remote address, and session ID that made the change are reported.
A summary of the changes that were made is also included in the event payload.
If multiple changes are made at once, then one <netconf-config-change> event will be generated for each change.
If the --with-yumaworks-config-change parameter is set to ‘true’ then the <new-value> and <old-value> fields will be added to each edit list entry as needed.
+---n netconf-config-change
+--ro changed-by
| +--ro (server-or-user)
| +--:(server)
| | +--ro server? empty
| +--:(by-user)
| +--ro username string
| +--ro session-id nc:session-id-or-zero-type
| +--ro source-host? inet:ip-address
+--ro datastore? enumeration
+--ro edit* []
+--ro target? instance-identifier
+--ro operation? nc:edit-operation-type
<netconf-config-change> Notification
Description: |
The <running> configuration has been changed by a NETCONF session. |
Min parameters: |
4 |
Max parameters: |
4 |
YANG file: |
Parameters:
changed-by:
username
type: string
usage: mandatory
This parameter identifies the SSH user name that is associated with the session.
session-id
type: uint32 (range 1 to max)
usage: mandatory
This parameter identifies the NETCONF session ID assigned to the session.
source-host
type: inet:ip-address
usage: mandatory
This parameter identifies the remote host IP address that is associated with the session.
datastore
type: string
usage: mandatory
This parameter identifies the datastore that changed
edit
list (with no key) of edit operations performed, 1 entry for each edit:
target
type: instance-identifier
usage: mandatory
This parameter contains the absolute path expression of the database object node that was modified.
operation
type: enumeration (merge, replace, create, delete)
usage: mandatory
This parameter identifies the nc:operation that was performed on the target node in the database.
new-value
type: anyxml
usage: optional (if --with-yumaworks-config-change=true)
This parameter contains the new value for the associated 'target' if the operation is not 'delete' or 'remove'. This object should represent a container with one child node specifying the new value used in the associated edit.
old-value
type: anyxml
usage: optional (if --with-yumaworks-config-change=true)
This parameter contains the old value for the associate 'target' that was changed or deleted, if operation is not 'create', This object should represent a container with one child node specifying the current value used in the associated edit.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-04-20T19:31:44Z</eventTime>
<netconf-config-change
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<changed-by>
<username>andy</username>
<session-id>3</session-id>
<source-host>127.0.0.1</source-host>
</changed-by>
<datastore>running</datastore>
<edit>
<target xmlns:nacm="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">/nacm:nacm</target>
<operation>create</operation>
</edit>
</netconf-config-change>
</notification>
Examples --with-yumaworks-config-change:
Create Operation:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2019-06-11T02:39:15Z</eventTime>
<netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<changed-by>
<username>andy</username>
<session-id>3</session-id>
<source-host>127.0.0.1</source-host>
</changed-by>
<datastore>running</datastore>
<edit>
<target
xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target>
<operation>create</operation>
<new-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
<int8.1 xmlns="http://netconfcentral.org/ns/test">42</int8.1>
</new-value>
</edit>
</netconf-config-change>
</notification>
Modify Operation:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2019-06-11T02:42:19Z</eventTime>
<netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<changed-by>
<username>andy</username>
<session-id>3</session-id>
<source-host>127.0.0.1</source-host>
</changed-by>
<datastore>running</datastore>
<edit>
<target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target>
<operation>replace</operation>
<new-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
<int8.1 xmlns="http://netconfcentral.org/ns/test">1</int8.1>
</new-value>
<old-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
<int8.1 xmlns="http://netconfcentral.org/ns/test">42</int8.1>
</old-value>
</edit>
</netconf-config-change>
</notification>
Delete Operation:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2019-06-11T02:42:51Z</eventTime>
<netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<changed-by>
<username>andy</username>
<session-id>3</session-id>
<source-host>127.0.0.1</source-host>
</changed-by>
<datastore>running</datastore>
<edit>
<target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target>
<operation>delete</operation>
<old-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
<int8.1 xmlns="http://netconfcentral.org/ns/test">1</int8.1>
</old-value>
</edit>
</netconf-config-change>
</notification>
YANG Module Reference for Behavior Summary:
module test-notification {
namespace "http://example.com/ns/yang/test-notification";
prefix tn;
revision 2025-02-12;
container MAIN-CONT {
container NP-CONT1 {
leaf leaf1 {
type string;
default "info1";
}
}
container NP-CONT2 {
leaf leaf1 {
type string;
}
}
container P-CONT1 {
presence "Presence P-CONT1";
leaf leaf1 {
type string;
default "pinfo1";
}
}
container P-CONT2 {
presence "Presence P-CONT2";
leaf leaf1 {
type string;
}
}
list LIST1 {
key "name";
leaf name {
type string;
}
}
leaf hostname {
type string;
}
}
}
This module includes:
NP-CONT1: non-presence container with a default leaf
NP-CONT2: non-presence container without defaults
P-CONT1: presence container with a default leaf
P-CONT2: presence container without defaults
LIST1: list node
hostname: plain leaf
Behavior Summary
NP-CONT1 (non-presence, default):
Action
Target
Operation
Set leaf1
/tn:MAIN-CONT [1]
create
Delete leaf1
/tn:MAIN-CONT/tn:NP-CONT1/tn:leaf1
delete
Re-set leaf1
/tn:MAIN-CONT/tn:NP-CONT1/tn:leaf1
merge [2]
Notes
Example: Setting leaf1
<edit-config> <target> <running/> </target> <config> <MAIN-CONT xmlns="http://example.com/ns/yang/test-notification"> <NP-CONT1> <leaf1>new-value</leaf1> </NP-CONT1> </MAIN-CONT> </config> </edit-config>
Resulting notification:
Incoming notification for session 1 [default]: notification { eventTime 2025-05-07T17:13:30.320907Z netconf-config-change { changed-by { username restconf session-id 38 source-host ::1 } datastore running edit { target /tn:MAIN-CONT operation create } } }
NP-CONT2 (non-presence, no default):
Action
Target
Operation
Set leaf1
/tn:MAIN-CONT/tn:NP-CONT2 [3]
create
Delete leaf1
/tn:MAIN-CONT/tn:NP-CONT2/tn:leaf1
delete
Re-set leaf1
/tn:MAIN-CONT/tn:NP-CONT2/tn:leaf1
create
Modify leaf1
/tn:MAIN-CONT/tn:NP-CONT2/tn:leaf1
merge
Note
P-CONT1 (presence, default):
Action
Target
Operation
Set leaf1
/tn:MAIN-CONT/tn:P-CONT1 [3]
create
Delete leaf1
/tn:MAIN-CONT/tn:P-CONT1/tn:leaf1
delete
Re-set leaf1
/tn:MAIN-CONT/tn:P-CONT1/tn:leaf1
merge [2]
P-CONT2 (presence, no default):
Action
Target
Operation
Set leaf1
/tn:MAIN-CONT/tn:P-CONT2 [3]
create
Delete leaf1
/tn:MAIN-CONT/tn:P-CONT2/tn:leaf1
delete
Re-set leaf1
/tn:MAIN-CONT/tn:P-CONT2/tn:leaf1
create
Modify leaf1
/tn:MAIN-CONT/tn:P-CONT2/tn:leaf1
merge
LIST1:
Action
Target [4]
Operation
Create two entries
/tn:MAIN-CONT/tn:LIST1[tn:name="name-1"]
/tn:MAIN-CONT/tn:LIST1[tn:name="name-2"]
create
create
Create one more entry
/tn:MAIN-CONT/tn:LIST1[tn:name="name-3"]
create
Delete the second entry
/tn:MAIN-CONT/tn:LIST1[tn:name="name-2"]
delete
Note
hostname (plain leaf):
Action
Target
Operation
Set hostname
/tn:MAIN-CONT/tn:hostname
create
Modify hostname
/tn:MAIN-CONT/tn:hostname
merge
Delete hostname
/tn:MAIN-CONT/tn:hostname
delete
<netconf-capability-change> Event
The <netconf-capability-change> notification is generated when the set of active capabilities for the server has changed.
The most common way this notification is generated is after the <load> operation has been used to add a new YANG module to the system.
It is possible that this notification will be generated for removal of capabilities. However, at this time, there are no NETCONF capabilities that can be removed from the running system.
The <added-capability> leaf list will contain the capability URI for each new capability that has just been added.
The <deleted-capability> leaf list will contain the capability URI for each existing capability that has just been deleted.
The <changedBy> container will identity whether the server or a NETCONF session caused the capability change.
If the change was made by the server, then this container will have an empty leaf named <server>.
If the change was made by a NETCONF session, the user name, remote address, and session ID for the session that caused the change are reported.
When this notification is generated, the ietf-netconf-monitoring.yang data model <capabilities> data structure is updated to reflect the changes.
Note
The server generates one event for each changed capability. It does not combine multiple capability changes into one event.
+---n netconf-capability-change
+--ro changed-by
| +--ro (server-or-user)
| +--:(server)
| | +--ro server? empty
| +--:(by-user)
| +--ro username string
| +--ro session-id nc:session-id-or-zero-type
| +--ro source-host? inet:ip-address
+--ro added-capability* inet:uri
+--ro deleted-capability* inet:uri
+--ro modified-capability* inet:uri
<netconf-capability-change> Notification
Description: |
The set of currently active <capability> URIs has changed |
Min parameters: |
2 |
Max parameters: |
5 |
YANG file: |
Parameters:
choice changed-by (server or by-user)
server
type: empty
usage: mandatory
If this empty leaf is present, then the server caused the capability change.
case by-user (if a NETCONF session caused the capability change)
username
type: string
usage: mandatory
This parameter identifies the SSH user name that is associated with the session.
session-id
type: uint32 (range 1 to max)
usage: mandatory
This parameter identifies the NETCONF session ID assigned to the session.
source-host
type: inet:ip-address
usage: mandatory
This parameter identifies the remote host IP address that is associated with the session.
added-capability
type:leaf-list of capability URI strings
usage: optional
This parameter contains one entry for each capability that was just added
deleted-capability
type:leaf-list of capability URI strings
usage: optional
This parameter contains one entry for each capability that was just deleted.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-04-20T19:37:34Z</eventTime>
<netconf-capability-change
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<changed-by>
<username>andy</username>
<session-id>3</session-id>
<source-host>127.0.0.1</source-host>
</changed-by>
<added-capability>http://netconfcentral.org/ns/test4?module=test4&revision=2009-09-09</added-capability>
</netconf-capability-change>
</notification>
<netconf-confirmed-commit> Event
The <netconf-confirmed-commit> notification is generated when the state of the confirmed-commit procedure has changed.
The confirmed-commit procedure is started when a <commit> operation with a <confirmed/> parameter is executed.
A <netconf-confirmed-commit> notification is generated several times for a single confirmed-commit procedure. One or more of the following sub-events will be generated:
start: A confirmed-commit procedure has started.
Sent once when the first <commit> operation is executed.
This event starts the confirmed-commit procedure.
If the <candidate> database is not altered, then the confirmed commit procedure will be skipped.
cancel: A confirmed-commit procedure has been canceled
Sent only if the original session is terminated.
This event terminates the confirmed-commit procedure.
timeout: A confirmed-commit procedure has timed out.
Sent only if the confirm-timeout interval expires.
This event terminates the confirmed-commit procedure.
extend: A confirmed-commit procedure has been extended.
Sent if the 2nd to N-1th <confirm> operation contains a <confirmed/> parameter.
This event restarts the confirm-timeout interval, but does not reset the backup database.
Any new changes in the <candidate> database will be committed.
complete: A confirmed-commit procedure has completed.
Sent if the 2nd to Nth <commit> operation is executed before the confirm-timeout interval expires.
This event terminates the confirmed-commit procedure.
+---n netconf-confirmed-commit
+--ro username string
+--ro session-id nc:session-id-or-zero-type
+--ro source-host? inet:ip-address
+--ro confirm-event enumeration
+--ro timeout? uint32
<netconf-confirmed-commit> Notification
Description: |
The state of the confirmed-commit procedure has changed. |
Min parameters: |
1 |
Max parameters: |
4 |
YANG file: |
Parameters:
username
type: string
usage: mandatory
This parameter identifies the SSH user name that is associated with the session that caused the confirmed-commit procedure state change.
session-id
type: uint32 (range 1 to max)
usage: mandatory
This parameter identifies the NETCONF session ID assigned to the session.
source-host
type: inet:ip-address
usage: mandatory
This parameter identifies the remote host IP address that is associated with the session.
confirm-event
type: enumeration (start, cancel, timeout, extend, complete)
usage: mandatory
This parameter indicates why the confirmed-commit procedure changed state.
Example Confirm Commit Start Event:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-04-20T19:41:34Z</eventTime>
<netconf-confirmed-commit
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<username>andy</username>
<session-id>3</session-id>
<source-host>127.0.0.1</source-host>
<confirm-event>start</confirm-event>
<timeout>10</timeout>
</netconf-confirmed-commit>
</notification>
Example Confirm Commit Timeout Event:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-04-20T19:41:44Z</eventTime>
<netconf-confirmed-commit
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
<confirm-event>timeout</confirm-event>
</netconf-confirmed-commit>
</notification>
<yang-library-change> Event
The <yang-library-change> notification is generated when the set of modules and submodules supported by the server has changed.
The most common way this notification is generated is after the <load> or <unload> operation has been used to add a new YANG module to the system.
Note that for a NETCONF server that implements YANG 1.1, a change of the "module-set-id" value results in a new value for the :yang-library capability. Thus, if such a server implements NETCONF notifications, and the notification <netconf-capability-change>, a <netconf-capability-change> and <yang-library-change> notifications are generated whenever the "module-set-id" changes.
x---n yang-library-change
x--ro module-set-id -> /modules-state/module-set-id
<yang-library-change> Notification
Description: |
The module-set-id value has changed |
Min parameters: |
1 |
Max parameters: |
1 |
YANG file: |
Parameters:
leaf module-set-id
type:leafref. Path:
/yanglib:modules-state/yanglib:module-set-idusage: mandatory
Contains the module-set-id value representing the set of modules and submodules supported at the server at the time the notification is generated
Example:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2016-11-15T18:03:29Z</eventTime>
<yang-library-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set-id>6765</module-set-id>
</yang-library-change>
</notification>
<replay-completed> Event
The <replay-completed> notification is generated for an RFC 8639 subscription when the replay portion of the subscription has been completed.
+---n replay-completed {replay}?
+--ro id subscription-id
<replay-complete> Notification
Description: |
The replay events have completed |
Min parameters: |
1 |
Max parameters: |
1 |
YANG file: |
Parameters:
leaf subscription-id
type: uint32
usage: mandatory
Contains the subscription ID that has completed all replay events.
<subscription-modified> Event
The <subscription-modified> notification is generated for an RFC 8639 subscription when it has been modified using the <modify-subscription> operation.
+---n subscription-modified
+--ro id subscription-id
+--ro (target)
| +--:(stream)
| | +--ro (stream-filter)?
| | | +--:(by-reference)
| | | | +--ro stream-filter-name stream-filter-ref
| | | +--:(within-subscription)
| | | +--ro (filter-spec)?
| | | +--:(stream-subtree-filter)
| | | | +--ro stream-subtree-filter? <anydata> {subtree}?
| | | +--:(stream-xpath-filter)
| | | +--ro stream-xpath-filter? yang:xpath1.0 {xpath}?
| | +--ro stream stream-ref
| | +--ro replay-start-time? yang:date-and-time {replay}?
| +--:(yp:datastore)
| +--ro yp:datastore identityref
| +--ro (yp:selection-filter)?
| +--:(yp:by-reference)
| | +--ro yp:selection-filter-ref selection-filter-ref
| +--:(yp:within-subscription)
| +--ro (yp:filter-spec)?
| +--:(yp:datastore-subtree-filter)
| | +--ro yp:datastore-subtree-filter? <anydata> {sn:subtree}?
| +--:(yp:datastore-xpath-filter)
| +--ro yp:datastore-xpath-filter? yang:xpath1.0 {sn:xpath}?
+--ro stop-time? yang:date-and-time
+--ro dscp? inet:dscp {dscp}?
+--ro weighting? uint8 {qos}?
+--ro dependency? subscription-id {qos}?
+--ro transport? transport {configured}?
+--ro encoding? encoding
+--ro purpose? string {configured}?
+--ro (yp:update-trigger)?
+--:(yp:periodic)
| +--ro yp:periodic!
| +--ro yp:period centiseconds
| +--ro yp:anchor-time? yang:date-and-time
+--:(yp:on-change) {on-change}?
+--ro yp:on-change!
+--ro yp:dampening-period? centiseconds
+--ro yp:sync-on-start? boolean
+--ro yp:excluded-change* change-type
<subscription-modified> Notification
Description: |
The subscription parameters have changed |
Min parameters: |
1 |
Max parameters: |
7 |
YANG file: |
Parameters:
leaf id
type: uint32
usage: mandatory
Contains the subscription ID that has been modified.
<subscription-terminated> Event
The <subscription-terminated> notification is generated for an RFC 8639 subscription that has been terminated for any reason.
+---n subscription-terminated
+--ro id subscription-id
+--ro reason identityref
<subscription-terminated> Notification
Description: |
The subscription has been terminated |
Min parameters: |
2 |
Max parameters: |
2 |
YANG file: |
Parameters:
leaf id
type: uint32
usage: mandatory
Contains the subscription ID that has been terminated
leaf reason
type: identityref
usage: mandatory
Contains the identity describing the reason the subscription has been terminated
<push-update> Event
The <push-update> notification is generated for an RFC 8639 subscription when new datastore update information needs to be sent for a YANG Push subscription. This form of a PUSH update is used to send the complete contents of the target data nodes.
+---n push-update
+--ro id? sn:subscription-id
+--ro datastore-contents? <anydata>
+--ro incomplete-update? empty
<push-update> Notification
Description: |
Datastore contents have been updated |
Min parameters: |
2 |
Max parameters: |
3 |
YANG file: |
Parameters:
leaf id
type: uint32
usage: mandatory
Contains the subscription ID that is being updated
anydata datastore-contents
type: anydata
usage: mandatory
Container with the YANG data nodes sent in this update
leaf incomplete-update
type: empty
usage: optional
Flag indicating the datastore-contents are incomplete somehow
<push-change-update> Event
The <push-change-update> notification is generated for an RFC 8639 subscription when new datastore update information needs to be sent for a YANG Push subscription. This form of a PUSH update is used to send a patch since the last update. The YANG Patch data structure defined in RFC 8072 is used to convey the patch information.
+---n push-change-update {on-change}?
+--ro id? sn:subscription-id
+--ro datastore-changes
| +--ro yang-patch
| +--ro patch-id string
| +--ro comment? string
| +--ro edit* [edit-id]
| +--ro edit-id string
| +--ro operation enumeration
| +--ro target target-resource-offset
| +--ro point? target-resource-offset
| +--ro where? enumeration
| +--ro value? <anydata>
+--ro incomplete-update? empty
<push-change-update> Notification
Description: |
Datastore contents have been updated |
Min parameters: |
2 |
Max parameters: |
3 |
YANG file: |
Parameters:
leaf id
type: uint32
usage: mandatory
Contains the subscription ID that is being updated
container datastore-changes
type: anydata
usage: mandatory
Container with the YANG Patch sent in this update
leaf incomplete-update
type: empty
usage: optional
Flag indicating the datastore-contents are incomplete somehow