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

ZMQAPI PUB Message

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

../_images/zmqapi_pub_block.png

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.

../_images/zmqapi_header_pub.png

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

CallHome 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 CallHome session to a managed server is ready to use.

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

Note

  • CallHome session processing is still preliminary.

  • The current session will switch to the CallHome session when it starts. This will be fixed in the next release.

This event is sent when a CallHome session is ready to use.

  • The 'name' field in the EVENT header will be set to callhome-start.

  • The ZMQAPI SESSION Header will indicate the CallHome 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

  • 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"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}