Module `_ncs.events`

Low level module for subscribing to NCS event notifications.

This module is used to connect to NCS and subscribe to certain events generated by NCS. The API to receive events from NCS is a socket based API whereby the application connects to NCS and receives events on a socket. See also the Notifications chapter in the User Guide. The program misc/notifications/confd_notifications.c in the examples collection illustrates subscription and processing for all these events, and can also be used standalone in a development environment to monitor NCS events.

This documentation should be read together with the confd_lib_events(3) man page.

Functions

def diff_notification_done(sock, tctx)

If the received event was NOTIF_COMMIT_DIFF it is important that we call this function when we are done reading the transaction diffs over MAAPI. The transaction is hanging until this function gets called. This function also releases memory associated to the transaction in the library.

Keyword arguments:

sock – a previously connected notification socket
tctx – a transaction context

def notifications_connect(sock, mask, ip, port, path)

This function creates a notification socket.

Keyword arguments:

sock – a Python socket instance
mask – a bitmask of one or several notification type values
ip – the ip address if socket is AF_INET (optional)
port – the port if socket is AF_INET (optional)
path – a filename if socket is AF_UNIX (optional).

def notifications_connect2(sock, mask, data, ip, port, path)

This variant of notifications_connect is required if we wish to subscribe to NOTIF_HEARTBEAT, NOTIF_HEALTH_CHECK, or NOTIF_STREAM_EVENT events.

Keyword arguments:

sock – a Python socket instance
mask – a bitmask of one or several notification type values
data – a _events.NotificationsData instance
ip – the ip address if socket is AF_INET (optional)
port – the port if socket is AF_INET (optional)
path – a filename if socket is AF_UNIX (optional)

def read_notification(sock) ‑> dict

The application is responsible for polling the notification socket. Once data is available to be read on the socket the application must call read_notification() to read the data from the socket. On success a dictionary containing notification information will be returned (see below).

Keyword arguments:

sock – a previously connected notification socket

On success the returned dict will contain information corresponding to the c struct confd_notification. The notification type is accessible through the 'type' key. The remaining information will be different depending on which type of notification this is (described below).

Keys for type NOTIF_AUDIT (struct confd_audit_notification):

logno
user
msg
usid

Keys for type NOTIF_DAEMON, NOTIF_NETCONF, NOTIF_DEVEL, NOTIF_JSONRPC, NOTIF_WEBUI, or NOTIF_TAKEOVER_SYSLOG (struct confd_syslog_notification):

prio
logno
msg

Keys for type NOTIF_COMMIT_SIMPLE (struct confd_commit_notification):

database
diff_available
flags
uinfo

Keys for type NOTIF_COMMIT_DIFF (struct confd_commit_diff_notification):

database
flags
uinfo
tctx
label (optional)
comment (optional)

Keys for type NOTIF_USER_SESSION (struct confd_user_sess_notification):

type
uinfo
database

Keys for type NOTIF_HA_INFO (struct confd_ha_notification):

type (1)
nomaster - if (1) is HA_INFO_NOMASTER
slave_died - if (1) is HA_INFO_SLAVE_DIED (see below)
slave_arrived - if (1) is HA_INFO_SLAVE_ARRIVED (see below)
cb_initialized_by_copy - if (1) is HA_INFO_SLAVE_INITIALIZED
beslave_result - if (1) is HA_INFO_BESLAVE_RESULT

If slave_died or slave_arrived is present they will in turn contain a dictinary with the following keys:

nodeid
af (1)
ip4 - if (1) is AF_INET
ip6 - if (1) is AF_INET6
str - if (1) if AF_UNSPEC

Keys for type NOTIF_SUBAGENT_INFO (struct confd_subagent_notification):

type
name

Keys for type NOTIF_COMMIT_FAILED (struct confd_commit_failed_notification):

provider (1)
dbname
port - if (1) is DP_NETCONF
af (2) - if (1) is DP_NETCONF
ip4 - if (2) is AF_INET
ip6 - if (2) is AF_INET6
daemon_name - if (1) is DP_EXTERNAL

Keys for type NOTIF_SNMPA (struct confd_snmpa_notification):

pdu_type (1)
request_id
error_status
error_index
port
af (2)
ip4 - if (3) is AF_INET
ip6 - if (3) is AF_INET6
vb (optional)
generic_trap - if (1) is SNMPA_PDU_V1TRAP
specific_trap - if (1) is SNMPA_PDU_V1TRAP
time_stamp - if (1) is SNMPA_PDU_V1TRAP
enterprise - if (1) is SNMPA_PDU_V1TRAP (optional)

Keys for type NOTIF_FORWARD_INFO (struct confd_forward_notification):

type
target
uinfo

Keys for type NOTIF_CONFIRMED_COMMIT (struct confd_confirmed_commit_notification):

type
timeout
uinfo

Keys for type NOTIF_UPGRADE_EVENT (struct confd_upgrade_notification):

event

Keys for type NOTIF_COMMIT_PROGRESS and NOTIF_PROGRESS (struct confd_progress_notification):

type (1)
timestamp
duration if (1) is CONFD_PROGRESS_STOP
usid
tid
datastore
context
phase (optional)
msg
annotation (optional)
service (optional)
service_phase (optional)
commit_queue_id (optional)
node (optional)
device (optional)
device_phase (optional)
package (optional)

Keys for type NOTIF_STREAM_EVENT (struct confd_stream_notification):

type (1)
error - if (1) is STREAM_REPLAY_FAILED
event_time - if (1) is STREAM_NOTIFICATION_EVENT
values - if (1) is STREAM_NOTIFICATION_EVENT

Keys for type NOTIF_CQ_PROGRESS (struct ncs_cq_progress_notification):

type
timestamp
cq_tag
cq_id
completed_devices (optional)
transient_devices (optional)
failed_devices (optional)
failed_reasons - if failed_devices is present
completed_services (optional)
completed_services_completed_devices - if completed_services is present
failed_services (optional)
failed_services_completed_devices - if failed_services is present
failed_services_failed_devices - if failed_services is present

Keys for type NOTIF_CALL_HOME_INFO (struct ncs_call_home_notification):

type (1)
device - if (1) is CALL_HOME_DEVICE_CONNECTED
af (2)
ip4 - if (2) is AF_INET
ip6 - if (2) is AF_INET6
port
ssh_host_key
ssh_key_alg

def sync_audit_network_notification(sock, usid)

If the received event was NOTIF_AUDIT_NETWORK, and we are subscribing to notifications with the flag NOTIF_AUDIT_NETWORK_SYNC, this function must be called when we are done processing the notification. The user session is hanging until this function gets called.

Keyword arguments:

sock – a previously connected notification socket
usid – the user session id

def sync_audit_notification(sock, usid)

If the received event was NOTIF_AUDIT, and we are subscribing to notifications with the flag NOTIF_AUDIT_SYNC, this function must be called when we are done processing the notification. The user session is hanging until this function gets called.

Keyword arguments:

sock – a previously connected notification socket
usid – the user session id

def sync_ha_notification(sock)

If the received event was NOTIF_HA_INFO, and we are subscribing to notifications with the flag NOTIF_HA_INFO_SYNC, this function must be called when we are done processing the notification. All HA processing is blocked until this function gets called.

Keyword arguments:

sock – a previously connected notification socket

Classes

class Notification (...)

This is a placeholder for the c-type struct confd_notification.

Notification cannot be directly instantiated from Python.

class NotificationsData (hearbeat_interval, health_check_interval, stream_name, start_time, stop_time, xpath_filter, usid, verbosity)

This type represents the c-type struct confd_notifications_data.

The contructor for this type has the following signature:

NotificationsData(hearbeat_interval, health_check_interval, stream_name, start_time, stop_time, xpath_filter, usid, verbosity) -> object

Keyword arguments:

heartbeat_interval – time in milli seconds (int)
health_check_interval – time in milli seconds (int)
stream_name – name of the notification stream (string)
start_time – the start time (Value)
stop_time – the stop time (Value)
xpath_filter – XPath filter for the stream (string) - optional
usid – user session id for AAA restriction (int) - optional
verbosity – progress verbosity level (int) - optional