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.

../_images/yang-push-overview.png

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.

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.

Dynamic custom event streams allow event streams to be added and deleted at run-time. 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 an 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>

Using Custom 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 NETCONF event stream. The notifications defined in ietf-netconf-notifications.yang are sent to this event stream.

Event streams can be used to group notification events for different reasons, such as by topic, or frequency, or severity..

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

Normally an event generated by internal YANG instrumentation will be sent to the NETCONF event stream. There are two ways for notifications to be sent to a configured stream:

  1. New Server API: The instrumentation can specify the event stream name. If this is configured it will be used for the queued notification. If the specified event stream is not found or no event stream is specified in the API call, then the server will check for an event-stream-map parameter for the module containing the notification.

  2. --event-stream-map CLI parameter:** The user can configure module to event stream mappings. 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 is found then the default event stream NETCONF is used.

Event Stream Monitoring

The event streams that are enabled on the 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 2019-08-30T00:20:32Z
        }
        stream  hardware {
          name hardware
          description 'vendor event stream'
          replaySupport true
          replayLogCreationTime 2019-08-30T00:20:32Z
        }
      }
    }
  }
}

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

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 <startTime> 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.

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.

The oldest event will be deleted when a new event is added, when this limit is reached.

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.

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:

  1. 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.

  2. 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.

  3. 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:

nc-notifications.yang

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:

nc-notifications.yang

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:

yuma-system.yang

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:

ietf-netconf-notifications.yang

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:

ietf-netconf-notifications.yang

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:

ietf-netconf-notifications.yang

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>

<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:

ietf-netconf-notifications.yang

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&amp;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:

ietf-netconf-notifications.yang

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:

ietf-yang-library.yang

Parameters:

  • leaf module-set-id

    • type:leafref. Path: /yanglib:modules-state/yanglib:module-set-id

    • usage: 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:

ietf-subscribed-notifications.yang

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:
ietf-subscribed-notifications.yang
ietf-yang-push.yang

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:

ietf-subscribed-notifications.yang

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:

ietf-yang-push.yang

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:

ietf-yang-push.yang

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