14 Event notifications

14.1 Overview

Clixon implements RFC 5277 NETCONF Event Notifications.

There are no pre-existing notification streams in Clixon, an application needs to implement them.

The main example illustrates an EXAMPLE stream notification that triggers every 5s.

To create a new event notification, there the following parts:

YANG: Define a schema event spec
Backend: and send server-side event messages
CLI: Subscribe to the event-stream, read and display events
Netconf
Restconf

14.1.1 Configure options

CLICON_STREAM_DISCOVERY_RFC5277: Enable event stream discovery as described in RFC 5277. This is the main option and should be true.
CLICON_STREAM_DISCOVERY_RFC8040: Enable monitoring information, including streams, for RESTCONF
CLICON_STREAM_URL: URL for locating event stream
CLICON_STREAM_RETENTION: Retention for stream replay buffers in seconds
CLICON_STREAM_PUB: NCHAN event publication. Obsolete

14.1.2 Restrictions

Limited replay support

14.2 Components

This section describes which components are involved to add a new event notification stream in Clixon.

14.2.1 YANG

The first step is to add an event notification in YANG. The notification statement is a part of the YANG specification

The main example defines an event notification following event which is also used in RFC8040 and RFC5277:

notification event {
   description "Example notification event.";
   leaf event-class {
      type string;
      description "Event class identifier.";
   }
   container reportingEntity {
      description "Event specific information.";
      leaf card {
         type string;
      }
   }
   leaf severity {
      type string;
   }
}

You can add any info to an event notifcation, the fields above are just examples.

14.2.2 Backend

The server-side first declares an event-stream, for example event my-event:

stream_add(h, "my-event", "Example notification event, 0, NULL)

Then, code needs to be added to generate event. This is highly application dependent.

Typically, events are either timer-based or event-based.

The main example uses a timer-based event, that is, a periodic timer is set that generates a periodic event.

One can also create an event-based event that triggers on things like commits or logs. Typically this code is added in applicatin user code.

You create a NETCONF notification event in XML, for example:

<my-event xmlns="urn:myuri...">
  <data-for-this-event>....
</my-event>

And then, assuming msg is a string variable with the notification, you send it with:

stream_notify(h, "my-event", msg)

14.2.3 CLI

You need to register a new socket “s”:

int s;
clicon_rpc_create_subscription(h, "my-event", NULL, &s)

Save the asynchronous socket “s” and read from it separately.

There are some examples on how to do this in the clixon main example and the controller, eg here: https://github.com/clicon/clixon-controller/blob/9a3ef161106207f6a49f3fbc14e50841f20f50e3/src/controller_cli_callbacks.c#L431 But it depends on how you want the CLI to behave.

14.2.4 Netconf

To start a notification stream via netconf:

<rpc><create-subscription xmlns="urn:ietf:params:xml:ns:netmod:notification"><stream>EXAMPLE</stream></create-subscription></rpc>]]>]]>
<rpc-reply><ok/></rpc-reply>]]>]]>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"><eventTime>2019-01-02T10:20:05.929272</eventTime><event><event-class>fault</event-class><reportingEntity><card>Ethernet0</card></reportingEntity><severity>major</severity></event></notification>]]>]]>

14.2.5 Restconf

An example using curl:

curl  -X GET -H "Accept: text/event-stream" -H "Cache-Control: no-cache" -H "Connection: keep-alive" https://thehost/streams/

14.3 Main example

The main example has an integrated CLI event notification. To try out:

clixon_cli -f /usr/local/etc/clixon/example.xml
cli> notify
cli> event-class fault;
reportingEntity {
  card Ethernet0;
}
severity major;

cli> no notify
cli>