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 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.
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.
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.
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.
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:
modulenotif4{yang-version1.1;namespace"urn:yumaworks:params:xml:ns:notif4";prefix"n4";revision2022-07-25{description"YPW-1910: Support YANG 1.1 nested notifications";}revision2022-03-25{description"Initial revision.";}containerA{listB{key"row column";leafrow{typeuint16;}leafcolumn{typeuint16;}listBB{key"idx";leafidx{typestring;}leafcol1{typestring;}listBBB{key"idx";leafidx{typestring;}leafcol1{typestring;}notificationN1{leafparm1{typestring;}leafparm2{typeint16;}}actionA1;}notificationN1{leafparm3{typestring;}leafparm4{typeint16;}}actionA1;}notificationN1{leafparm1{typestring;}leafparm2{typeint16;}}actionA1;}notificationN1{leafparm1{typestring;}leafparm2{typeint16;}}actionA1;}notificationN1{leafparm1{typestring;}leafparm2{typeint16;}}}
In this test module, the 'N1' event type is defined at 5 levels:
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.
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.
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.
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.
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
}
}
}
}
}
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 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
<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.
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'.
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.
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:
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
The <subscription-modified> notification is generated for an RFC 8639 subscription
when it has been modified using the <modify-subscription> operation.
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.
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.