ZMQAPI Event Channel

The 'yangcli-gw' event channel is used to access the enhanced notification delivery features.

Your application is a subscriber and yangcli-gw is the publisher
yangcli-gw will publish events as they occur
NETCONF 'event stream' and YANG Push 'datastore' subscriptions are used to gather server data to deliver to the application.
There is no access to the NETCONF 'replay' feature. Only live notification delivery is supported.
Notification events will be delivered for all the active NETCONF sessions. The ZMQAPI REP SESSION Header is included in each notification message to identify the NETCONF server source.

PUB Message Flow

The PUB notification is a one-way message.

The yangcli-gw sends a ZMQAPI PUB Message to the application

The ZeroMQ socket specified by the --zmqapi-publisher-endpoint parameter is used for this message flow.

Event Types

There are 3 event types defined at this time:

Event Type	Event Enum	Description
PUB gw Event	`gw`	Events from yangcli-gw
PUB stream Event	`stream`	Events from managed server event streams
PUB data Event	`data`	Events from managed server datastores

Notification Configuration

The --autonotif parameter can be set to 'true' to cause automatic use of the <create-subscription> operation.
The <establish-subscription> operation should be used if possible.
TBD: advanced automatic configuration of best-available APIs

ZMQAPI PUB Message

The notification message is a multi-part message that has three headers, and usually one payload part.

Message Part	Description
ZMQAPI header	Text header line defining the message to follow
SESSION header	JSON header containing source session info
EVENT header	JSON header containing event info
Event Payload	Section will be present and encoded in the configured format in most cases. Omitted for some gateway event types.

PUB ZMQAPI Header

The ZMQAPI Message Header is the first message part.

ZMQAPI Header Fields For a PUB Message

Header Field	Description
Protocol ID	`ZMQAPI.1`
Message ID	`PUB`
Response Format	Default: `R2` TBD: configurable in yangcli-gw
Gateway ID	Default: `gateway1` Configurable with --zmqapi-gateway-id
Sequence ID	Notification Sequence Number (uint64)

Example Header

ZMQAPI.1 PUB R2 gateway1 2402

PUB SESSION Header

The ZMQAPI SESSION Header is the second message part. This identifies the session that is associated with the event:

PUB gw Event
- Depends on the message type. Usually this identifies the session that is the subject of the event, but it may sometimes just identify the current session status, same as for the ZMQAPI Dot Status Command.
PUB stream Event
- Identifies the session that received the event stream notification
PUB data Event
- Identifies the session that received the datastore notification

Example Header

{"count":1,"sid":1,"name":"dev1","server":"192.168.0.237","port":830,"user":"andy"}

PUB EVENT Header

The ZMQAPI EVENT Header is the third message part. This identifies the event that is being reported. Refer to the event definition section for the event type for details on the fields in this header.

PUB gw Event

The gw event type is used to convey yangcli-gw state changes to an application. This section defines the gateway event messages.

The 'name' field is used to indicate the gateway event that occurred.
In most cases there will not be an Event Payload section.
There will always be three message parts present and possibly four, if an Event Payload is present
The response type is set to R2 even if no Event Payload is present.
There is no indication other than ZeroMQ multi-part message processing to determine the an Event Payload is present in the message

ZMQAPI Gateway Events

Event Name	Description
callhome-start Event	Call Home session has started
session-closed Event	A session has closed
shutdown Event	The gateway is shutting down
startup Event	The gateway is starting up

PUB gw EVENT Header

The EVENT header for a gateway PUB message is set as follows:

EVENT Field	Value
type	`gw`
time	date-and-time timestamp when event was generated by yangcli-gw
observer	`0` (not used)
module	`yumaworks-zmqapi`
revision	`2023-06-22` (could change in the future)
name	name of the gateway event
path	`/` (not used)

Example Gateway EVENT Header

{"type":"gw","time":"2023-09-09T19:59:19Z","observer":0,"module":"yumaworks-zmqapi","revision":"2023-06-22","name":"session-closed","path":"/"}

callhome-start Event

The callhome-start event is sent when a new Call Home session to a managed server is ready to use.

This feature requires the Call Home Server feature to be properly configured.

Note

The Call Home session support is still preliminary.
The current session is not switched to a Call Home session for yangcli-gw. This must be done manually by your application.

This event is sent when a Call Home session is ready to use.

The 'name' field in the EVENT header will be set to callhome-start.
The show 'callhome' command will print the Call Home session names
The ZMQAPI SESSION Header will indicate the Call Home session that is starting.
- The 'name' field in the SESSION header is used to access this session

Example callhome-start Event

ZMQAPI.1 PUB R0 gateway1 401
{"count":1,"sid":2,"name":"andy-callhome-1","server":"::f8:365:fc7f:0","port":830,"user":"andy"}
{"type":"gw","time":"2023-09-18T23:18:03Z","observer":0,"module":"yumaworks-zmqapi","revision":"2023-06-22","name":"callhome-start","path":"/"}

session-closed Event

The session-closed event is sent when a connected session to a managed server is terminated.

Session could be closed intentionally (e.g., close-session command).
Session could be closed or dropped by the server.
The 'name' field in the EVENT header will be set to session-closed.
The ZMQAPI SESSION Header will indicate the session that was closed.
- The 'count' field in this header will include the session that is being closed

Example session-closed Event

ZMQAPI.1 PUB R2 gateway1 1420
{"count":1,"sid":1,"name":"default","server":"192.168.1.39","port":830,"user":"andy"}
{"type":"gw","time":"2023-09-09T19:59:19Z","observer":0,"module":"yumaworks-zmqapi","revision":"2023-06-22","name":"session-closed","path":"/"}

startup Event

The startup event is sent when the yangcli-gw process is starting up.

Example startup Event

ZMQAPI.1 PUB R0 gateway1 1
{"count":0,"sid":0,"name":"none","server":"","port":0,"user":""}
{"type":"gw","time":"2023-09-13T18:55:26Z","observer":0,"module":"yumaworks-zmqapi","revision":"2023-06-22","name":"startup","path":"/"}

shutdown Event

The shutdown event is sent when the yangcli-gw process is shutting down.

Example shutdown Event

ZMQAPI.1 PUB R0 gateway1 2416
{"count":0,"sid":0,"name":"none","server":"","port":0,"user":""}
{"type":"gw","time":"2023-09-13T19:52:59Z","observer":0,"module":"yumaworks-zmqapi","revision":"2023-06-22","name":"shutdown","path":"/"}

PUB stream Event

The stream event type is used to convey server event stream subscription messages to an application. This section defines the format of a stream event message.

The 'module', 'revision', and 'name' fields are used to indicate the YANG notification statement for the event stream event
In all cases there will be an Event Payload section representing the event portion of the notification message.
There will always be four message parts present.
The response type is set to R2 since the event format is JSON. This will configurable in a future release.
The 'path' indicates if the notification is nested or a top-level event.
- The string / indicates a top-level notification.
- Nested YANG 1.1 notifications and schema mounted notifications will both have the 'path' field set to the instance-identifier for the nested notification.

PUB stream EVENT Header

The EVENT header for an Event Stream PUB message is set as follows:

EVENT Field	Value
type	`stream`
time	date-and-time timestamp from eventTime field
observer	`0` (not used)
module	YANG module name defining the notification-stmt for the event
revision	YANG module revision date for the module field
name	name of the notification event
path	`/` for a top-level notification or full path to the nested notification

Example Event Stream EVENT Header

{"type":"stream","time":"2023-09-09T20:55:40.453425Z","observer":0,"module":"ietf-netconf-notifications","revision":"2012-02-06","name":"netconf-session-start","path":"/"}

Example: Top-Level netconf-session-start Event

This standard notification is only received if yangcli-gw is already listening for notifications from the server.

ZMQAPI.1 PUB R2 gateway1 23
{"count":1,"sid":2,"name":"default","server":"localhost","port":830,"user":"andy"}
{"type":"stream","time":"2023-09-09T20:55:40.453425Z","observer":0,"module":"ietf-netconf-notifications","revision":"2012-02-06","name":"netconf-session-start","path":"/"}
{
  "netconf-session-start": {
    "username":"andy",
    "session-id":7,
    "source-host":"127.0.0.1"
  }
}

Example: Nested toastDone Event

The example schema mount module 'vtoaster.yang' contains a notification that is sent when the virtual toast is done. The 'path' field in the EVENT header will contain the RESTCONF-encoded path string for the mount point.

ZMQAPI.1 PUB R2 gateway1 172
{"count":1,"sid":1,"name":"default","server":"localhost","port":830,"user":"andy"}
{"type":"stream","time":"2023-09-10T18:17:39.073694Z","observer":0,"module":"toaster","revision":"2009-11-20","name":"toastDone","path":"/vtoaster:vtoasters/vtoaster=1"}
{
  "toastDone": {
    "toastStatus":"done"
  }
}

PUB data Event

Note

The datastore subscription service is preliminary.
More high level commands will be added in the future
Additional EVENT header fields may be added in the future

The data event type is used to convey server datastore subscription messages to an application. This section defines the format of a datastore event message.

The 'module', 'revision', and 'name' fields are used to indicate the YANG notification statement for the event stream event
- module: ietf-yang-push.yang
- revision: 2019-09-09
- name: push-update or push-change-update
In all cases there will be an Event Payload section representing the event portion of the notification message.
There will always be four message parts present.
The response type is set to R2 since the event format is JSON. This will configurable in a future release.
The 'path' indicates if the notification is nested or a top-level event.
- The string / indicates a top-level notification.
- Nested YANG 1.1 notifications and schema mounted notifications will both have the 'path' field set to the instance-identifier for the nested notification.
TBD: new field called data-path to identify subscription filter target will be added in the future

Example: YANG Push update for Periodic Subscription

datastore: operational
target: /interfaces-state/interface[name='eno1']
event: push-update

ZMQAPI.1 PUB R2 gateway1 52
{"count":1,"sid":1,"name":"default","server":"localhost","port":830,"user":"andy"}
{"type":"data","time":"2023-09-14T00:28:18.936356Z","observer":0,"module":"ietf-yang-push","revision":"2019-09-09","name":"push-update","path":"/"}
{
  "push-update": {
    "id":3,
    "datastore-contents": {
      "interfaces-state": {
        "interface": {
          "name":"eno1",
          "type":"ianaift:ethernetCsmacd",
          "admin-status":"up",
          "oper-status":"up",
          "if-index":"2",
          "phys-address":"04:92:26:bf:c0:bd",
          "speed":"1000000000",
          "statistics": {
            "in-octets":"26054653001",
            "in-unicast-pkts":"24474437",
            "in-multicast-pkts":"1976584",
            "in-discards":"320",
            "in-errors":"0",
            "out-octets":"10276953033",
            "out-unicast-pkts":"16713430",
            "out-discards":"0",
            "out-errors":"0"
          }
        }
      }
    }
  }
}

Example: YANG Push update for On-Change Subscription

datastore: operational
target: /interfaces-state/interface[name='eno1']
event: push-change-update
--push-simop-patch-update parameter = 'true' (default)

ZMQAPI.1 PUB R2 gateway1 184
{"count":1,"sid":3,"name":"default","server":"localhost","port":830,"user":"andy"}
{"type":"data","time":"2023-09-14T01:44:54.951879Z","observer":0,"module":"ietf-yang-push","revision":"2019-09-09","name":"push-change-update","path":"/"}
{
  "push-change-update": {
    "id":1,
    "datastore-changes": {
      "yang-patch": {
        "patch-id":"0",
        "comment":"simop",
        "edit": [
          {
            "edit-id":"E1",
            "operation":"replace",
            "target":"/",
            "value": {
              "data": {
                "interfaces-state": {
                  "interface": {
                    "name":"eno1",
                    "type":"ianaift:ethernetCsmacd",
                    "admin-status":"up",
                    "oper-status":"up",
                    "if-index":"2",
                    "phys-address":"04:92:26:bf:c0:bd",
                    "speed":"1000000000",
                    "statistics": {
                      "in-octets":"26194419713",
                      "in-unicast-pkts":"24611887",
                      "in-multicast-pkts":"1986553",
                      "in-discards":"320",
                      "in-errors":"0",
                      "out-octets":"10322411286",
                      "out-unicast-pkts":"16811068",
                      "out-discards":"0",
                      "out-errors":"0"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}