NTF User Guide

USER GUIDE

4/1553-APR 901 0444/4 Uen B

Copyright

© Ericsson AB 2016. All rights reserved. No part of this document may be

reproduced in any form without the written permission of the copyright owner.

Disclaimer

The contents of this document are subject to revision without notice due to
continued progress in methodology, design and manufacturing. Ericsson shall
have no liability for any error or damage of any kind resulting from the use of
this document.

Trademark List

All trademarks mentioned herein are the property of their respective owners.
These are shown in the document Trademark Information.

4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Contents

Contents

1 Introduction 1
1.1 Prerequisites 1

2 Basic Concepts 3
2.1 Notification Service 3
2.2 Notifications 4
2.3 Producers 9
2.4 Consumers 10
2.5 Summary 16

3 Application Programming Interface 17

3.1 Producer API 18
3.2 Consumer API 22

4 Information Model and Administrative Operations 29

4.1 Configuration 29
4.2 Command-Line Interface 29

5 General Concerns 33
5.1 Standards Compliance 33

Reference List 35

4/1553-APR 901 0444/4 Uen B | 2016-11-28

NTF User Guide

4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Introduction

1 Introduction

The Service Availability Forum (SA-Forum) is an industry consortium that has

defined a set of open Application Programming Interface (API) specifications to
enable building highly available carrier grade systems providing service continuity.
Ericsson has been active in creating the specifications and is a key contributor in
OpenSAF, an open source implementation of these specifications.

The Notification service (NTF) specification is part of the Management

Infrastructure Services suite. In the system, it provides a uniform way of reporting
incidents of significance for fault management and receiving them.

Scope
This document is a simplified version of the NTF specification but also contains
information related to the NTF system environment and other concerns.

Target Groups
This document is intended for application designers and developers.

1.1 Prerequisites
It is assumed that the reader is familiar with the SA-Forum system architecture
and concepts. For more information, refer to www.saforum.org.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 1

 NTF User Guide

2 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

2 Basic Concepts

2.1 Notification Service

The NTF provides a single well-known communication channel through which
system components can report issues they ‘‘consider’’ important or cannot deal
with. Any service or application can use the NTF for reporting situations of
significance. In NTF terms, these services and applications are the producers of
the incident reports referred as notifications. Also any service or application can
use the NTF to collect such notifications at runtime or on demand. According to
the NTF such users are the consumers of notifications.

The NTF provides a single (reliable) channel to disseminate selectively among

consumers the notifications generated by the producers, see Figure 1. It also has
the responsibility of logging notifications for offline processing. The Log service
(refer to Reference [7]) defines two configuration log streams dedicated to the
NTF.

CLM Node1 CLM Node2 CLM NodeN

NTF
NTF Notification NTF
producer1
NTF
producer1 producers producer4
producer3
Alarms and
security alarms
LOG
API
Cached
Configuration notifications
log streams Notification service accessible through
dedicated to NTF the Reader API

Notifications
NTF NTF NTF
subscriber1 subscriber2 Notification reader2
consumers
NTF
reader1

Figure 1 Overview of Notification Service

To facilitate the uniform interpretation of notifications, the NTF specification

defines different categories of notifications and their respective format.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 3

 NTF User Guide

However, the NTF does not interpret the notifications and does not maintain
any state information associated with them. These are the responsibilities of the
NTF users and in particular the producers. Consumers can also want to correlate
notifications.

These basic NTF concepts are reviewed in more detail in the following section.

2.2 Notifications
Most Application Interface Specification (AIS) services are producers of
notifications and the service specification defines the ‘‘situations of significance’’
that an implementation of the service must ‘‘consider’’ important and therefore is
to report.

The NTF specification (refer to Reference [8]) defines the following five categories
of notifications:

a Alarms

b Security alarms

c State change notifications

d Object create/delete notifications

e Attribute change notifications

These notification categories imply different importance. An alarm (a or b) is

perceived as an indication of some emergency. It usually reflects an incident
that the system cannot deal with partially or at all, and for complete resolution a
human intervention is required.

The other notification categories are typically consumed internally by other

services and applications of the system or provide context for the alarms.

The data structure of all notification categories includes a common part, which
is also referred as the notification header. This is extended by each notification
category with data appropriate for the purpose of the category.

Based on these data structures, an NTF implementation deploys some filtering so

that consumers receive only the notifications they are interested in and can handle.

Later versions of the NTF specification (starting from A.03.01, refer to Reference
[9]) also allow the suppression of notifications to preserve system resources,
especially in overload scenarios. The exceptions are the alarms and security
alarms, which never can be suppressed.

2.2.1 Notification Header

The common fields used by all alarms and notifications are described in Table 1.

4 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

Table 1 Notification Header

Field Description
Event type Different depending on the notification type. Characterizes the nature
of the event that is reported. The notification producer is to select an
appropriate value from those defined by the NTF specification (refer to
Reference [8]) in the SaNtfEventTypeT enum. The notification category
determines the applicable enum values.
Notification object Contains the Distinguished Name (DN) of the entity about which the
notification is generated.
Notifying object The DN of the entity generating the notification – the reporter itself.
Notification Class Allows filtering out of classes of notifications similar in some way.
Identifier (NCI) Applications and services can define their own classes. To avoid
conflicts, the NCI defines three fields: the first identifies the vendor,
while the second and third provide the major and minor identifiers for the
given notification class as defined by this vendor. The NTF specification
recommends using the SNMP enterprise number as the vendor ID.
For example, all AIS services define notifications for which the vendor is
set as SA_NTF_VENDOR_ID_SAF = 18568, the major ID is set to the AIS
service reporting the notification, for example, SA_SVC_IMM as defined
by the SaServicesT enum type. Each service defines its own minor IDs.
The vendor ID for Ericsson is 193. The major and minor IDs are
respectively the 16 most significant and least significant bits of the
Minor Type defined in the COM Fault Management model.
Notification identifier A unique ID generated by the NTF. It is used to reference the given
notification instance, for example, to correlate it with other related
notification instances or a consumer can use it to retrieve the notification
from the NTF.
Correlated notification Lists the notification IDs of notification instances that are related to the
s given instance. Related notifications can be organized into a tree at the
root of which there is the notification reported by the entity detecting
the event.
For example, when a component detects an error, it can generate a
notification itself and it reports the error to the Availability Management
Framework (AMF), refer to Reference [4]. The AMF in turn engages in
a fault recover procedure and as part of that it changes the different
states of the component and its peers and reports them as state
change notifications. At Root Cause Analysis, it is desirable that these
state change notifications can be correlated with the notification
generated initially by the component reporting the error. The correlated
notifications field serves this purpose. It is recommended to report in
the first position the ID of the notification at the root of this tree, in the
second position the ID of the immediate parent notification, and in the
third any sibling notification. More details on the subject are provided in
Section 2.4.4 Correlation of Notifications on page 13.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 5

 NTF User Guide

Table 1 Notification Header

Field Description
Event time The time of the detection of the event that is reported as opposed to
the time it is reported. A reporting entity can postpone the notification
generation, while it is in the critical path of dealing with the situation
and generate the related notifications with some delay.
Additional text Provided for service and application-specific information.
Additional information Provided for service and application-specific information as a data
structure.

2.2.2 Notification Categories

2.2.2.1 Alarms and Security Alarms

The NTF guarantees the delivery of alarms and security alarms and it also stores
them persistently in a log stream. Therefore, alarms cannot be suppressed (refer
to Reference [9]) and their log file cannot be filtered either (refer to Reference [7]).

This means that an application designer must take special care of deciding when
an alarm is necessary. To make this decision easier, it is worth mentioning that an
operator would map an alarm to an emergency call or paging of their maintenance
personnel urging them to attend the situation.

So even if the situation seems to be critical for the application, but there is another
entity within the system that takes care of it, there is no need for an alarm and a
notification is probably sufficient. For example, if a component error is detected,
which is then reported to the AMF, it is enough to generate a notification about
the error as the AMF is there to deal with the situation and repair the component.
In turn, when the AMF runs out of solutions it generates an appropriate alarm
as defined by the AMF specification (refer to Reference [4]) to seek for human
attendance.

The alarms and security alarms generated by the different AIS services are
defined in the respective specifications.

The category-specific fields are different for alarms and security alarms.

The fields for alarms are described in Table 2.

6 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

Table 2 Category-Specific Fields for Alarms

Field Description
Probable cause Complements the information of the event type field providing
information about the behavioral aspect of the entity. It is a value of the
SaNtfProbableCauseT enum type defined in the NTF specification,
which is used for both alarms and security alarms and follows the
X.733 (refer to Reference [1]) and X.736 (refer to Reference [2])
Recommendations respectively. A subset of these values is applicable
for alarms, while the rest is applicable for security alarms only. The COM
component currently ignores this field.
Perceived severity The reporting entity must indicate the seriousness of the situation
from its point of view. There are six levels of severity (of type
SaNtfSeverityT): Cleared, indeterminate, critical, major, minor, and
warning. Among these, the cleared value (SA_NTF_SEVERITY_CLEARED)
indicates the resolution of a previously reported alarm situation.
Specific problems An optional data structure that refines the information provided
in the probable cause field. The values for this data structure are
application-specific.
Trend indication In addition to the perceived severity, an entity can also report the
tendency in which the situation is changing.
Threshold information Optional. Provides a context for the alarm. The producer can also report
any threshold information.
Monitored attributes Optional. Provides a context for the alarm. The producer can also report
the monitored attributes.
Proposed repair A reporting entity can also have the perspective to be able to propose a
repair in the proposed repair field.

The fields for security alarms are described in Table 3.

Table 3 Category-Specific Fields for Security Alarms

Field Description
Security alarm cause Used the same way as the probable cause field of alarms, see Table 2.
Severity Used the same way as the severity field of alarms, see Table 2.
Detector Identifies the entity that detected the event leading to the
given security alarm. The NTF provides a data structure
SaNtfSecurityAlarmDetectorT consisting of a field for an NTF type
and another for its value with the identifier.
Service user The identifier of the user whose request led to the security alarm.
Defined as SaNtfServiceUserT type, which is similar to the
SaNtfSecurityAlarmDetectorT type.
Service provider Identifies the service the user intended to access and resulted in the
security alarm. Defined as SaNtfServiceUserT type, which is similar
to the SaNtfSecurityAlarmDetectorT type.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 7

 NTF User Guide

2.2.2.2 State Change Notifications and Attribute Change Notifications

As states are represented as attributes of the respective managed objects

in the information model, state change notifications and attribute change
notifications are very similar. The main difference is that AIS services define
state change notifications and therefore their implementations generate them;
the specifications do not typically mandate attribute change notifications. So
one can look at states as attributes of special significance. So much so that the
ITU defined the X.731 (refer to Reference [3]) Recommendation for the state
management function.

Two fields are reported for both state and attribute changes.

The source indicator field determines whether the change is one of the following:

— Because of an internal change such as some operational function of the entity

indicated in the notification object field

— A result of a management function operating on this entity

— Unknown

In the second field, the list of changed states/attributes is provided. Each change
includes the state/attribute ID, the new value, and can also indicate the old
value. For attribute changes, the attribute type is also provided, while states are
represented as integers because AIS specifications that define state change
notifications also define enum types for their states.

AIS specifications also define enum types that identify the states they can report
on.

If an application wants to generate attribute change notifications for its objects

in the information model, it must augment the classes with attribute IDs. Only
the Log service (refer to Reference [7]) API defines some attribute IDs for its
information model fragment. The Information Model Management service (IMM,
refer to Reference [6]) does not mandate such a parameter for the class attributes,
which means that only the application would be aware of it and can generate the
notification. Such is the case with the Log service (LOG).

2.2.2.3 Object Create/Delete Notifications

The object create/delete notifications are generated to indicate the creation or the
deletion of a service entity and its representing managed object in the information
model. Among the AIS services, the Log service communicates this way the
creation and deletion of runtime log streams in the system.

As for the state and attribute change notifications, the source indicator field
is defined for the object create/delete notifications with a similar meaning as
described in the previous section.

The object create/delete notification also lists the setting of the object attributes
at the moment of its creation or deletion. This again requires the attribute

8 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

identifiers for each of the listed attributes, their type and value. As the standard
information model has no provisioning for the attribute ID, the Log service defined
the necessary enum type as part of the service API. Applications must take a
similar approach.

2.3 Producers
Notification producers are the applications or system processes that generate
notifications using the NTF producer API. Producing a notification therefore
means creating and filling in the required data structure and submitting it to the
NTF. The producers and even the NTF are unaware of the consumers of these
notifications. They are posted much as a ‘‘to whom it may concern’’ message. It is
the predefined data structure that helps the NTF service and interested consumers
in sorting out the relevance and interpreting the notifications.

Another key point about producing notifications is that it often occurs during
some critical operations. For example, considering the AMF when it detects an
error and executes a failover: it produces a series of state change notifications
as the different entities change their states because of the failover. That is, they
change the presence, the readiness, and the High Availability (HA) states at
least, but the operational state can also change. Also, as multiple entities can
be involved in the failover, the AMF can produce many similar notifications for
them as the failover progresses.

The NTF producer API therefore offers the possibility of reusing notification data
structures, as allocations can take some time and they also use extra resources:

— If more than one notification of the same type must be sent (for example,
state change notifications for all components of a Service Unit (SU) failing
over its services), the notifications have the same data structure and even
portion of the data is the same.

— Therefore the producer can allocate the needed data structure only once
and reuse it as many times as needed. This is done by updating the values
that change from one notification to another, such as update the DN of the
components as the same state change is reported for each of them.

— Once all needed notifications are sent the producer (for example, the AMF)
can free the allocated data structure.

Such a reuse, however, serializes the operations as each data setting must be
sent before the data structure can be reused for the next notification. This can
be a problem considering the reported critical operation (for example, failover).
However, sometimes the serialization is necessary for the proper correlation of
notifications. This is because the notification ID of previous related notifications
must be included in the new notification. The unique notification ID is generated
by the NTF within the send request.

Notification producers do not need to log the alarms and security alarms as they
are logged by the NTF in the dedicated log stream defined by the Log service (refer
to Reference [7]). However, they can consider logging their other notifications as

4/1553-APR 901 0444/4 Uen B | 2016-11-28 9

 NTF User Guide

the current Core MW 3.0 NTF implementation (refer to refer to Reference [6])
does not log these.

2.4 Consumers
As mentioned earlier, the producers or the NTF do not know in advance which
processes are interested in the notifications, who are going to be the consumers.
Processes must express their interest to the NTF if they want to become a
consumer of some kinds of notifications.

The NTF provides two options:

— It can deliver the notifications as they are sent by the different producers. Such
a consumer is referred as a subscriber as it is a subscription-based mechanism.

— The NTF also stores the notifications produced in the system so that a
consumer can collect them later using the reader API. Such a consumer is
referred as a reader.

Regardless whether it is a ‘‘want to be subscriber’’ or a ‘‘want to be reader’’

consumer, the first task it must do is to set up the filters that describe the
notifications it wants to receive or read.

2.4.1 Filters
Setting up the filters requires similar data structures as the notification data
structures, as the filter conditions can be defined for the different portions of the
notification data structures. For each notification category a matching filter
data structure and allocation function are defined by the NTF API. These data
structures determine the notification parameters on which the filtering is enabled
for the given notification category. When a filter is applied by the NTF, only
notifications matching the filter setting pass the filter and are delivered to the
consumer.

Similarly to the notification data structures, the NTF API supports the reuse of the
notification filter data structures between different subscriptions or reads, or both.

2.4.2 Subscribers
Subscribers get a callback from the NTF each time a notification matching their
subscription becomes available. This means that a process wanting to become a
subscriber must provide this callback function (saNtfNotificationCallback)
when it initializes the NTF.

Once the different filters are in place, the user is ready to subscribe with the NTF
for notifications. Afterward it receives a callback if a notification matching any of
the filters becomes available in the system.

10 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

The NTF provides in the callback the notification itself and the subscriber can keep
the data structure as long as needed, that is, the NTF does not free the passed
data structure when the callback returns. This means that the subscriber has
the responsibility to free the allocation once it has processed the notification;
otherwise the NTF can run out of resources and start to discard notifications for
the given subscriber.

However, as the NTF is reliable, it still delivers the fact that some notifications
have been discarded if at initialization the subscriber also provided an appropriate
second callback (saNtfNotificationDiscardedCallback). When the NTF
invokes this callback, it contains the list of notification IDs that the NTF was
not able to deliver. As opposed to saNtfNotificationCallback, for the
saNtfNotificationDiscardedCallback the resources are handled by the NTF
only and they are freed when the callback returns. The subscriber must make a
copy of the notification IDs if it wants to retrieve them as a reader outside of
the callback.

2.4.3 Readers

To enable delayed reading of notifications, the NTF maintains a cache of the

notifications produced in the system. The Core MW 3.0 implementation of the
NTF (refer to Reference [6]) has a configurable cache, which by default collects
the latest 10000 alarms and security alarms. Rather than being called back by the
NTF, a reader itself must iterate through the cache and find what it is looking for.

As mentioned earlier, the filters are used by both subscribers and readers. The
moment in time when the subscription is submitted to the NTF determines from
where the NTF is to start delivering the notifications. In case of iterating through
the cache, there are potentially hundreds of notifications that would match the
filter.

Therefore, the read initialization besides the filter also includes the search criteria,
which determines the starting point from which the reader can iterate through
the notifications matching the filter.

Considering the cached notifications as a sequence of records, the reader can

iterate in either direction from the identified starting point.

The easiest way is clearly if the reader knows exactly the notification IDs it is
looking for, for example, from saNtfNotificationDiscardedCallback. A
notification ID is the perfect searching criteria as it uniquely identifies a notification
in the cache and the reader can collect it immediately with the first iteration.

If the reader does not know the notification ID, the starting point becomes time
based. The difficulty with this is that, as already mentioned, producers can delay
the notification generation and therefore the detection time of events (which is
given in the event time field of each notification) and the time the notification
is produced can differ. Also, in a distributed system, notifications are produced
concurrently and the NTF serializes them in a so called “chronological order” based
on the order it receives them and not necessarily as they were produced.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 11

 NTF User Guide

As a result, an event time criterion can result in no matching notification or many

scattered around in the cache records, as shown in Figure 2. The figure shows an
application of different search criteria to the sequence of notifications cached in
the chronological order the NTF received them. Therefore, the search mode part of
the search criteria refines further the selection.

SA_NTF_SEARCH_BEFORE_OR_AT_TIME
SA_NTF_SEARCH_AT_OR_AFTER_TIME
SA_NTF_SEARCH_BEFORE_TIME

SA_NTF_SEARCH_AFTER_TIME
SA_NTF_SEARCH_AT_TIME

Event time = T

T T T T

1 k k+1 k+2 k+3 k+4 k+5 k+6 k+7 k+8 n

SA_NTF_SEARCH_OLDER SA_NTF_SEARCH_YOUNGER
Ascending chronological order

Figure 2 Different Search Criteria to Sequence of Notifications Cached

As shown in Figure 2, if there are multiple matches (all marked with ‘‘T’’), the
following apply:

— SA_NTF_SEARCH_AT_OR_AFTER_TIME selects the first notification

on record that matches the event time (that is, k+1) while
SA_NTF_SEARCH_BEFORE_OR_AT_TIME selects the last such notification, that
is, k+7.

— SA_NTF_SEARCH_AFTER_TIME selects the first notification immediately after

the last on record that matches the event time. That is, this is the notification
following the one selected by SA_NTF_SEARCH_BEFORE_OR_AT_TIME, that is,
k+8.

— SA_NTF_SEARCH_BEFORE_TIME selects the last notification immediately

before the first one on record that matches the event time. That

12 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

is, this is the notification preceding the one selected by the

SA_NTF_SEARCH_AT_OR_AFTER_TIME.

— SA_NTF_SEARCH_AT _TIME selects the first notification on record that matches

the event time, the same way as SA_NTF_SEARCH_AT_OR_AFTER_TIME.

If only one notification matches the event time, not only SA_NTF_SEARCH_AT
_TIME and SA_NTF_SEARCH_AT_OR_AFTER_TIME coincide, but also
SA_NTF_SEARCH_BEFORE_OR_AT_TIME. That is to say all notifications in green
collapse into one.

If there is no match for the event time, SA_NTF_SEARCH_AT _TIME gives no

result and the iteration returns the SA_AIS_ERR_NOT_EXIST error. For the
other search modes, the starting point is either the first or the last notification
on record depending on the search direction selected in the first iteration.
SA_NTF_SEARCH_OLDER returns the first notification on record (that is, following
the ascending chronological order) while SA_NTF_SEARCH_YOUNGER returns the
last notification on record (following the descending chronological order).

The search criteria can also indicate that the reader only wants to apply the filter
(SA_NTF_SEARCH_ONLY_FILTER) in which case the iteration always starts from
the first notification on record.

In each iteration, the NTF returns exactly one notification from the set matching
the filter. The notification type is returned in the notification type field, which
determines the way the reader must process the notification data. Once the
reader completed the processing, it must release the allocated memory by calling
function saNtfNotificationFree.

2.4.4 Correlation of Notifications

Whichever way a consumer receives the notifications, it might like to be able to
sort out the relation between notifications to understand the sequence of events
that occurred in the system and the root cause so that it can be prevented in
the future. To facilitate this, notifications include in their header the correlated
notifications field.

In addition, starting with A.03.01 (refer to Reference [9]), the NTF specification
has defined the SaNtfCorrelationIdsT data structure to be used in application
APIs so that applications between themselves can pass notification IDs as
necessary. The AIS service APIs increasingly include such a parameter in calls
related to failures, failure handling, and status reports. Applications are strongly
encouraged to use such parameters and define their API in a similar manner.

2.4.4.1 Correlation Example

To demonstrate how notifications are correlated, this section shows an example

of a potential interaction of three of the AIS services: the Platform Management
service (PLM) (refer to Reference [10]), the Cluster Membership service (CLM)

4/1553-APR 901 0444/4 Uen B | 2016-11-28 13

 NTF User Guide

(refer to Reference [5]), and the AMF, when a physical node fails in the system. The
example indicates the correlated root and parent notification IDs in parentheses.

Typically it is the PLM that detects the node failure and maps it to the failure of
the Hardware Element (HE) representing this hardware node in the information
model. For hardware failure, it generates an alarm (assume that its notification
ID is #1). It sets the different states of the HE and the Execution Environment
(EE) hosted by the HE as appropriate for the failure. It also generates a set of
notifications starting with the HE representing the node (#2, #3, #4), and proceeds
to the affected EE hosted on the node (#5, #6).

In the different notifications, it includes the notification IDs of previous related

notifications. For example, when reporting the state change of the EE (the
dependent entity), it references in the notifications the notification ID of the
readiness state change notification of the HE (the sponsoring hosting entity)
(#4) as the trigger of the state change.

#1: PLM HE alarm (1,)

#2: PLM HE operational state change notification (1,1)
#3: PLM HE presence state change notification (1,1)
#4: PLM HE readiness state change notification (1,1)
#5: PLM EE presence state change notification (1,4)
#6: PLM EE readiness state change notification (1,4)

It is here assumed that the PLM generates the different state change notifications
for an entity in parallel, hence all referencing the same notification as root and
as parent. A PLM implementation can then generate in sequence, in which case
they would all reference #1 as the root, but as parent #2 would reference #1, #3
reference #2, and #4 reference #3, and so on.

In addition to these notifications through its tracking API, the PLM also informs all
its users tracking these changes. In the tracking callbacks, the PLM also provides
the correlated notification IDs (using the mentioned SaNtfCorrelationIdsT data
structure) so that its users can correlate any notifications they generate with
those the PLM has generated. Namely, in the callback for the HE readiness status
change it reports #1 as the root and as the parent notification ID, and #4 as the
notification ID reporting the readiness state change. For the EE, again the root is
#1, but the parent is #4 reporting the readiness state change of the HE. It passes
#6 as the notification reporting the EE readiness state change.

The CLM is one of the users of the PLM, which tracks the EEs on which CLM
nodes are configured. It receives the PLM track callback reporting the EE going
out-of-service. As a result, the CLM proceeds with the actions for the node leaving
the cluster. It produces its own notification about the membership change and
references the notifications produced by the PLM as it received them in the track
callback: #1 as the root and #6 as the parent:

#7: CLM member node exit notification (1, 6)

The same way as the PLM did, the CLM reports the membership change through
its track API also including the notification IDs: #1 as root, #6 as parent, and #7 as
the one reporting the node leaving the cluster.

14 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Basic Concepts

The AMF tracks the cluster membership, hence it receives the callback from
the CLM. It perceives the disappearance of a node as a node failure and all
components and SUs hosted on the nodes going out-of-service simultaneously
and become uninstantiated. The AMF reports these state changes following the
entity dependencies as applicable in a similar manner as in case of the PLM:
#8: AMF node operational state change notification (1, 7)
#9: AMF SU readiness state change notification (1, 8)
#10: AMF component readiness state change notification (1, 8)
#11: AMF component presence state change notification (1, 8)
#12: AMF SU presence state change notification (1, 8)

Again, in these state change notifications the AMF references the correlated
notification IDs. Also, the AMF performs the necessary failover procedures and so
calls back the standby components on other nodes to take the active assignments
of the components of this failed node. However, the AMF does not propagate
the notification identifiers automatically within its callbacks. A user process can
obtain the notification IDs by calling the appropriate API function and providing
the invocation identifier of the callback that triggered the request.

In this example, the AIS services were considered. However, any notification
producer process generating notifications is to follow the same principles in
correlating notifications and facilitate the Root Cause Analysis. If the PLM and the
CLM track APIs did not pass the correlated notification IDs, the CLM and the the
AMF are unable to correlate their notifications with the hardware failure reported
in the PLM HE alarm. One must take an extra effort to match them up.

Even with proper notification correlation it can be difficult to identify the root
cause as the different services have their own fault detection mechanisms and
many of them can fire simultaneously before the failure is reported through the
APIs. For example, one or more components of the failing node can miss their
health check before the AMF gets the track callback from the CLM reporting the
departure of the node.

There are also notifications that come in pairs. A typical example is the alarm,
which is used when an emergency situation occurs. When the situation is resolved,
a second alarm is generated to clear the emergency situation. To do so, the
second alarm references the first as a correlated notification and sets the severity
as cleared. For this example, the PLM alarm reported with the #1 notification ID
can be cleared later by #27, which references the root and parents as discussed
earlier in the first two positions and add a second reference to #1 as the alarm is
cleared. Such ‘‘sibling’’ notification is reported in the third position of correlated
notifications field:
#1: PLM HE alarm (1,)
[...]
#27: PLM HE alarm cleared (1, 26, 1)

In summary, the NTF only provides the means for correlating the notifications but
using these tools effectively remains the responsibility of the users.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 15

 NTF User Guide

2.5 Summary
To summarize, the NTF provides a common communication mechanism to report
primarily fault-related incidents and changes that can put these incidents into a
context. All this is to allow more educated reactions to emergency situations.
Depending on the contents, five categories of notifications are distinguished.
Each notification has a unique identifier. It can therefore be referenced, that
is, correlated with other notifications; the most important among which is the
clearing of an alarm raised earlier.

The NTF allows for these different functionalities, but it does not interpret the
notifications it delivers, it does not keep any related states or correlates them. It
only provides the infrastructure and expects the users, the notification producers
and consumers, to use this infrastructure meaningfully.

On the consumer side, it provides both push and pull mechanisms of dissemination.
It pushes notifications to subscribers in a timely fashion and reports if it cannot do
so. It provides the necessary delivery guarantees. For readers, the NTF provides a
pull interface through which the same information can be retrieved.

In both cases, the notifications are filtered so that consumers receive only the
information they need or can handle.

As it is a well-known mechanism, all entities in the system are to use the NTF
to provide the information that can be useful for fault management. Each AIS
services specification contains a section defining the alarms and notifications
the service generates.

16 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Application Programming Interface

3 Application Programming Interface

Core MW 3.0 is compliant to the SAI-AIS-NTF-A.01.01 version (refer to Reference

[8]) of the SA-Forum specifications, but it also contains elements of later versions,
as these specifications corrected some issues in the SAI-AIS-NTF-A.01.01 version.

The implementation is delivered with header file saNtf.h, which contains the data
type and function prototype declarations according to the SAI-AIS-NTF-A.03.01
version of the specification (refer to Reference [9]). However, the functionality
that has been implemented is compliant to the SAI-AIS-NTF-A.01.01 version
of the specification. If a requested function is not supported, it returns error
code SA_AIS_ERR_NOT_SUPPORTED. The version of the header file allows the
use of the SaNtfCorrelationIdsT data structure, as described in Section 2.4.4
in Reference [8].

The API follows the SA-Forum programming model according to which a user
must initialize the service to negotiate the service version and to obtain a handle
from the service by calling function saNtfInitialize. In spite of the version of
the header file, only the A.01.01 version can be initialized. The handle represents
one particular association between the caller process and the NTF service.

The same process can initialize the NTF multiple times, which provides separate
handles and therefore independent associations. Within the context of each
handle, only the API functions appropriate for the negotiated version of the
service can be used. However, a process can negotiate a different service version
for each of the handles it obtains when different versions become supported.

At initialization, the process must submit the callback functions (according to

structure SaNtfCallbacksT) appropriate for the role the user wants to play.
Currently only the subscriber callbacks are implemented. To detect the callbacks,
the process can use a selection object and, when they become available, dispatch
those callbacks in the context of a handle obtained at initialization.

The association created between a user process and the NTF at initialization
ceases to exist when the handle is finalized explicitly by the process, or implicitly
if the process ceases to exist.

Within the association represented by the NTF handle obtained at initialization,

the process can access the different functionalities offered by the service.
Some of these can result in obtaining more subhandles related to the accessed
functionality. In particular, a reader obtains a read handle when it initializes the
reader API using function saNtfNotificationReadInitialize. It represents
the context for the read and must be referenced throughout the read iteration
(saNtfNotificationReadNext). It is released when the API is finalized using
saNtfNotificationReadFinalize, after which the read context is not accessible
any more; any reference to the read subhandle returns an error.

Producers obtain a notification handle whenever they allocate a notification data

structure with the service. The allocation function is different for each notification

4/1553-APR 901 0444/4 Uen B | 2016-11-28 17

 NTF User Guide

category. They can manipulate and update this data structure through API
functions referencing the appropriate notification handle.

Consumers implicitly receive a similar handle whenever the NTF delivers them a
notification regardless whether it is delivered in a callback or as part of the read
iteration. Again, they must use this handle to access the different portions of the
delivered notification.

Consumers also obtain a notification filter handle with each type of notification
filter allocation. They can manipulate the filter data structure only through
the API functions referencing the appropriate notification filter handle. These
notifications, handled by the notification filter, cease to exist and the related data
structure allocation is freed with the invocation of the respective API functions
saNtfNotificationFree and saNtfNotificationFilterFree.

Implicit or explicit finalization of the NTF handle implies the release of any
subhandle that the process can have obtained using that NTF handle, as well as
all the resources associated with such subhandles.

3.1 Producer API

Processes that want to generate notifications can do so using the producer API. It
allows the user to perform the following:

1. Allocate the memory for the notification data structure for the notification
category that must be sent:

a Set the fields of the notification data structure as appropriate.

b Send the notification using the current content of the notification data
structure.

c Repeat (a) and (b) as many times as needed.

2. Release the memory allocated for the notification data structure.

The AMF sends a state change notification each time any of its entities change
their state. The following pieces of code are executed (the original code of
<opensaf>/osaf/services/saf/avsv/avd/avd_ntf.c has been modified; some
parts were omitted and comments were added to provide more explanation):

18 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Application Programming Interface

uint32_t sendStateChangeNotificationAvd(AVD_CL_CB *avd_cb,

SaNameT ntf_object,
SaUint8T *add_text,
SaUint16T majorId,
SaUint16T minorId,
uint32_t sourceIndicator,
SaUint16T stateId,
SaUint16T newState,
NCSCONTEXT add_info,
int type)
{
uint32_t status = NCSCC_RC_FAILURE;
// declare a state change notification structure
SaNtfStateChangeNotificationT myStateNotification;
SaUint16T add_info_items = 0;
SaUint64T allocation_size = 0;
// set the number of additional information items if needed and its size
if (type != 0) {
add_info_items = 1;
allocation_size = SA_NTF_ALLOC_SYSTEM_LIMIT; /* use the default size */
}

// allocate the required memory for the state change notification

// as needed for the provided input
status = saNtfStateChangeNotificationAllocate(
avd_cb->ntfHandle, /* AMF’s handle to NTF Service instance */
&myStateNotification, /* the notification structure declared above */
0, /* number of correlated notifications:
AMF does no correlation at this time */
strlen((char*)add_text)+1, /* length of additional text */
add_info_items, /* number of additional info items */
1, /* number of state changes: AMF generates
separate notification for each change */
allocation_size /* allocation size */);
// check if the allocation was successful
if (status != SA_AIS_OK) {

// omitted: log the failure

return NCSCC_RC_FAILURE;
}
// at this point we have a valid notification handle:
// myStateNotification.notificationHandle

// filling out the notification header is implemented as a separate

// function as it is used for all notifications, provide the needed data
status = fill_ntf_header_part_avd(&myStateNotification.notificationHeader,
SA_NTF_OBJECT_STATE_CHANGE,
ntf_object,
add_text,
majorId,
minorId,
AMF_NTF_SENDER,
add_info,
type,
myStateNotification.notificationHandle);

// check if filling the header was successful

if (status != SA_AIS_OK) {

// omitted: log the failure

4/1553-APR 901 0444/4 Uen B | 2016-11-28 19

 NTF User Guide

// since the allocation above was successful all used memory needs to be released
saNtfNotificationFree(myStateNotification.notificationHandle);
return NCSCC_RC_FAILURE;
}
// set the fields specific for state change notifications, i.e.
// the source indicator,
*(myStateNotification.sourceIndicator) = sourceIndicator;
// the state ID,
myStateNotification.changedStates->stateId = stateId;
// the indication that the old state is omitted by the current implementation,
myStateNotification.changedStates->oldStatePresent = SA_FALSE;
// and new state value
myStateNotification.changedStates->newState = newState;

// send the notification with the current information in the data structure
// referenced by the myStateNotification.notificationHandle
status = saNtfNotificationSend(myStateNotification.notificationHandle);

// omitted: check if the send was successful and log any failure

// release all the allocations

status = saNtfNotificationFree(myStateNotification.notificationHandle);

// omitted: check if freeing was successful and log any failure

return status;

The following code (also from avd_ntf.c) is used by the AMF to fill out the
notification header for all categories of notifications. Some comments are added
here although the code is straightforward.

20 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Application Programming Interface

SaAisErrorT fill_ntf_header_part_avd(SaNtfNotificationHeaderT *notificationHeader,

SaNtfEventTypeT eventType,
SaNameT obj_name,
SaUint8T *add_text,
SaUint16T majorId,
SaUint16T minorId,
SaInt8T *avd_name,
NCSCONTEXT add_info,
int type,
SaNtfNotificationHandleT notificationHandle)
{
// event type such as AMF object state change
*notificationHeader->eventType = eventType;
// event time: AMF does not report the time corrently
*notificationHeader->eventTime = (SaTimeT)SA_TIME_UNKNOWN;

// the length and value of the notification object’s name

notificationHeader->notificationObject->length = obj_name.length;
(void)memcpy(notificationHeader->notificationObject->value, obj_name.value,obj_name.length);

// the length and value of the notifying object’s name, i.e. AMF in this case
notificationHeader->notifyingObject->length = strlen(avd_name);
(void)memcpy(notificationHeader->notifyingObject->value, avd_name, strlen(avd_name));

// Fields of the NCI (notification class ID) as defined by the AMF specification
notificationHeader->notificationClassId->vendorId = SA_NTF_VENDOR_ID_SAF;
notificationHeader->notificationClassId->majorId = majorId;
notificationHeader->notificationClassId->minorId = minorId;

// the value of the additional text field

(void)strcpy(notificationHeader->additionalText, (SaInt8T*)add_text);

/* Fill the additional info if present */

if (type != 0) {
SaStringT dest_ptr;
SaAisErrorT ret;
SaNameT *name = (SaNameT*)(add_info);
if (type == 1) {
/* node_name */
notificationHeader->additionalInfo[0].infoId = SA_AMF_NODE_NAME;
notificationHeader->additionalInfo[0].infoType = SA_NTF_VALUE_LDAP_NAME;
} else if (type == 2) {
/* si_name */
notificationHeader->additionalInfo[0].infoId = SA_AMF_SI_NAME;
notificationHeader->additionalInfo[0].infoType = SA_NTF_VALUE_LDAP_NAME;

}
// use the provided API to allocate memory for variable length fields
ret = saNtfPtrValAllocate(notificationHandle,
sizeof (SaNameT) + 1,
(void**)&dest_ptr,
&(notificationHeader->additionalInfo[0].infoValue));

// omitted: check if allocation was successful and log any failure

memcpy(dest_ptr, name, sizeof(SaNameT));

}
return SA_AIS_OK;
}

Sending notifications is much about allocating the necessary memory, composing

the appropriate data in the allocated structures before sending the notification,
and then releasing the memory.

Each time an API function is invoked the outcome of the operation is checked if it
was successful. Once a notification allocation was successful and the process has
obtained a notification handle, it is important to release the memory allocations
even if there is a failure. Allocations for variable length fields, such as pointer
values and arrays, require the use of special allocation functions provided by

4/1553-APR 901 0444/4 Uen B | 2016-11-28 21

 NTF User Guide

the API. However, there is no need to release them separately as they become
associated with the notification handle and are released when the notification
structure is freed using this handle.

The provided examples do not reuse any memory allocation and dispose it after
the state change notification has been sent successfully.

3.2 Consumer API

Whether it is a subscriber or a reader, a consumer must create the set of filters that
identify the notifications it is interested in. The notification filter data structures
are very similar to the data structures of the notifications themselves and they
are handled in a similar manner as the notifications. Hence no example in that
regard is presented. The focus is first on the interpretation of notifications that is
performed by both types of consumers. Then special features of the subscriber
and the reader APIs are discussed.

3.2.1 Receiving Notifications

The following saNtfNotificationCallback is the callback function invoked

by the NTF when a notification matches the subscription of a subscriber. The
processing of the notification (of type SaNtfNotificationsT) is the same if it is
received using function saNtfNotificationReadNext.

The following example is based on the Command-Line interface (CLI) program

provided with the Core MW 3.0 implementation of the NTF and it is included in the
ntfclient.c file (in the <opensaf>/osaf/tools/safntf/src directory). Extra
comments have been added, while other parts have been removed for brevity.

22 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Application Programming Interface

void saNtfNotificationCallback(SaNtfSubscriptionIdT subscriptionId,

const SaNtfNotificationsT * notification)
{
SaInt32T i;
SaNtfNotificationHandleT notificationHandle;
const SaNtfNotificationHeaderT *notificationHeader;

// the data structure to be processed depends on the notification type field

switch (notification->notificationType) {

// we look into the state change notification only

// state change notifications are provided in the stateChangeNotification field
case SA_NTF_TYPE_STATE_CHANGE:
notificationHandle =
notification->notification.stateChangeNotification.
notificationHandle;
notificationHeader =
&notification>notification.stateChangeNotification.
notificationHeader;
printf("=== %s - State Change ===\n",
event_time(*notificationHeader->eventTime));

// the common header is printed by common functions for the header

print_header(notificationHeader, subscriptionId,
notification->notificationType);

// handing of the additional information is presented here

// inserted from the print_additional_info function
if (notificationHeader->additionalInfo != NULL) {
switch (notificationHeader->additionalInfo[0].infoType) {
case SA_NTF_VALUE_LDAP_NAME:{
SaNameT *dataPtr;
SaUint16T dataSize;
SaAisErrorT rc;

// using the special API to access variable length fields

rc = saNtfPtrValGet(notificationHandle,
&notificationHeader->
additionalInfo[0].infoValue,
(void **)&dataPtr,
&dataSize);
if (rc == SA_AIS_OK) {
printf("additionalInfo = \"%s\"\n",dataPtr->value);
} else
fprintf(stderr, "saNtfPtrValGet Error ""%d\n", rc);
break;
}
default:
printf("Unimplemented additionalInfo type\n");
break;
}
}

// handling the notification type specific parts

print_source_indicator(*(notification->notification.
stateChangeNotification.sourceIndicator));

// handling the array of state changes contained in the notification

if (verbose)
printf("Num of StateChanges: %d\n", notification->notification.
stateChangeNotification.numStateChanges);

/* Changed states */
for (i = 0;
i < notification->notification.stateChangeNotification.
numStateChanges; i++) {
print_change_states(notificationHeader->notificationClassId,
&notification->notification.
stateChangeNotification.changedStates[i]);
}
break;

case SA_NTF_TYPE_ALARM:
case SA_NTF_TYPE_OBJECT_CREATE_DELETE:
case SA_NTF_TYPE_ATTRIBUTE_CHANGE:
case SA_NTF_TYPE_SECURITY_ALARM:

4/1553-APR 901 0444/4 Uen B | 2016-11-28 23

 NTF User Guide

// handling of the other notifications is omitted

break;

default:
printf("unknown notification type %d",
(int)notification->notificationType);
break;
}

// free the memory allocation associated with the notification handle

saNtfNotificationFree(notificationHandle);
printf("\n");
}

The following are the most important points of handling received notifications:

— Depending on the notification category, different fields of the

SaNtfNotificationsT data structure must be interpreted.

— Fields of variable length values must be accessed using the special

saNtfPtrValGet and saNtfArrayValGet API functions; the notification
handle must also be provided in these calls.

— Although the user made no allocation, it must free the memory associated
with the notification handle received from the NTF implementation.

3.2.2 Subscribing to NTF

A consumer that wants to receive notifications as they are generated in the
system must subscribe to the NTF. A good example of how to do this can be
found in the implementation of CLI commands provided with Core MW 3.0
NTF implementation. The following excerpts are from the ntfsubscribe.c file
(located in the <opensaf>/osaf/tools/safntf/ntfsubscribe directory). Only
part of the code is shown with some added comments.

24 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Application Programming Interface

static SaAisErrorT subscribeForNotifications(const

saNotificationFilterAllocationParamsT
*notificationFilterAllocationParams,
SaNtfSubscriptionIdT subscriptionId)
{
SaAisErrorT errorCode = SA_AIS_OK;
SaNtfStateChangeNotificationFilterT stChFilter;

// omitted: some declarations including declarations for other filters

SaNtfNotificationTypeFilterHandlesT notificationFilterHandles;
memset(&notificationFilterHandles, 0, sizeof notificationFilterHandles);
// allocate and set the filter for state change notifications
errorCode = saNtfStateChangeNotificationFilterAllocate(ntfHandle,
&stChFilter,
notificationFilterAllocationParams->numEventTypes,
notificationFilterAllocationParams->numNotificationObjects,
notificationFilterAllocationParams->numNotifyingObjects,
notificationFilterAllocationParams->numNotificationClassIds,
0,
0);
// handle any returned error
if (errorCode != SA_AIS_OK) {
fprintf(stderr, "saNtfStateChangeNotificationFilterAllocate failed - %s\n",
error_output(errorCode));
return errorCode;
}

// use the received state change notification filter handle to set

// the appropriate field in the notificatioFilterHandles stucture
notificationFilterHandles.stateChangeFilterHandle =
stChFilter.notificationFilterHandle;

// omitted: similar allocations and settings of filters for other notification

// types as it may necessary
// subscribe to NTF using the notificatioFilterHandles structure that identifies
// the filters and the subscriptionId, which identifies this subscription within
// the context of the user application
errorCode =saNtfNotificationSubscribe(&notificationFilterHandles,subscriptionId);
// omitted: handling of any returned error

errorCode = saNtfNotificationFilterFree(
notificationFilterHandles.stateChangeFilterHandle);

// omitted: handling of any returned error

return errorCode;
}

To take advantage of the subscription, the user process must provide the
necessary callback at initializing the NTF service.

Subscribing to the NTF requires two attributes:

— A set of handles to the notification filters that the NTF is to use to match
notifications against this subscription.

— A subscription identifier, which for the user process identifies a particular

subscription. The NTF provides this subscription ID in its callbacks.

The set of notification filter handles can contain one filter for each notification
type referenced by its handle, and must include at least one such handle. For
notification types that the user is not interested in the appropriate field are to be
set to SA_NTF_FILTER_HANDLE_NULL. All handles in the structure must have been
allocated in association with the same NTF handle.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 25

 NTF User Guide

The NTF API does not allow the change of subscriptions. If a subscriber wants to
change its existing subscriptions, the only way is to remove the old one and create
a new subscription with the new modified filters. To ensure that no notification is
lost because of such a change, the subscriber can want to subscribe first with the
new filters, and when this subscription is in place remove the old subscription. This
means that the subscriber must use a new subscription ID for the new subscription.

Subscriptions can be removed calling function saNtfNotificationUnsubscribe

with the subscription ID and the NTF handle.

3.2.3 Reading the NTF Cache

By default the Core MW 3.0 implementation of the NTF stores the last 10000
alarms and security alarms issued in the system. These are accessible using the
reader API of the NTF.

The main principles of using the reader API were discussed in Section 2.4.3
Readers on page 11. A user must perform the following:

1. Create the filters to be used by the NTF to match the notifications in the cache.

2. Initialize the reader API using the created filters and optionally with a search
criteria, which identifies the first notification to be returned among those
matching the filters.

3. Free the notification filter handles to release the associated memory

allocations.

4. Iterate through the matched notifications using the saNtfNotificationRead

Next call; this can be repeated as many times as needed.

5. Finalize the reader API.

The implementation of the ntfread CLI command provided with the Core
MW 3.0 NTF implementation shows a good example of the use of the reader
API. The following excerpts are from the ntfread.c file (located in the
<opensaf>/osaf/tools/safntf/ntfread directory). The original code has
been edited.

26 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Application Programming Interface

static SaAisErrorT readAll() {

SaNtfNotificationsT n;
SaAisErrorT rc;
SaNtfNotificationTypeFilterHandlesT fhdls = {0};
SaNtfAlarmNotificationFilterT af;
SaNtfSearchCriteriaT searchCriteria = {SA_NTF_SEARCH_ONLY_FILTER,0,0};
SaNtfSearchDirectionT searchDirection = SA_NTF_SEARCH_YOUNGER;

// omitted: some declarations

// omitted: allocation and setting of the alarm and other notification filters

// set the alarm filter handle in the filter set

fhdls.alarmFilterHandle = af.notificationFilterHandle;

// omitted: the setting of any additional filter handles

// initialize the reader API with the search criteria and the allocated filters
rc = saNtfNotificationReadInitialize(searchCriteria, &fhdls, &readHandle);

// handle any returned error as needed

if (rc != SA_AIS_OK) {
fprintf(stderr, "saNtfNotificationReadInitialize failed - %s\n",
error_output(rc));
goto done;
}

// iterate through the matching notifications startin from the oldest

while ((rc = saNtfNotificationReadNext(readHandle, searchDirection, &n))
== SA_AIS_OK) {

// use the earlier saNtfNotificationCallback to process each notification read

saNtfNotificationCallback(0, &n);
}

if (rc == SA_AIS_ERR_NOT_EXIST) {
rc = SA_AIS_OK; /* no more notification exists */
} else {
fprintf(stderr, "saNtfNotificationReadNext failed - %s\n",
error_output(rc));
}
done:

// free all allocated notification filters

rc = saNtfNotificationFilterFree(fhdls.alarmFilterHandle);

// omitted: handling of return codes

return rc;
}

This example sets the search criteria so that only the filters are used to match the
notifications. The search mode is SA_NTF_SEARCH_ONLY_FILTER and the event
time and notification ID fields are ignored. This means that the NTF returns at
the first iteration with the oldest notification on record that matches the filters.
This also means that the search direction must be set to SA_NTF_SEARCH_YOUNGER
to iterate through all these notifications. This piece of code also invokes function
saNtfNotificationCallback, which is the subscriber’s callback function
discussed earlier.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 27

 NTF User Guide

28 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Information Model and Administrative Operations

4 Information Model and Administrative

Operations

The specification defines no information model for the NTF and therefore no
administrative operations.

However, the Core MW 3.0 NTF implementation provides a configuration file and
three CLI commands, ntfsend, ntfsubscribe, and ntfread, as extensions to
the specification.

4.1 Configuration
The NTF service implementation of Core MW 3.0 uses a configuration file,
ntfd.conf, with some environment variables that tailor the implementation
behavior. Its typical location is in the /etc/opensaf/ directory.

The ntfd.conf file is sourced by the NTF server at startup, so any change to the
file takes effect only once the server has been restarted.

The following is the content of the file that comes with the package:
# Uncomment the next line if you want to run the log server through valgrind
#export TOOL="valgrind --leak-check=full --log-file=/tmp/ntf.valgrind"

# Uncomment the next line to enable trace

#args="--tracemask=0xffffffff"

# Healthcheck keys
export NTFSV_ENV_HEALTHCHECK_KEY="Default"

# Uncomment the next line to enable info level logging

#args="--loglevel=info"
# Notification cache list size for Reader API
#export NTFSV_ENV_CACHE_SIZE="200"

As mentioned earlier, the NTFSV_ENV_CACHE_SIZE environment variable defines

the number of notifications (alarms and security alarms) cached by the NTF to
make the accessible through the reader API. It defaults to 10000; if it is required
in the configuration file, a different setting is desirable.

4.2 Command-Line Interface

The CLI commands can be used by themselves or in a script. They run as clients of
the NTF service. Bits and pieces of these programs are discussed as they provide
good examples for the use of the NTF.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 29

 NTF User Guide

4.2.1 Command ntfsend

The ntfsend CLI command can be used to send notifications with the parameters
provided as attribute to the command. Without any attributes, it generates a
single ‘‘default’’ alarm. -h or –-help prints the available options:
-a or --additionalText=TEXT additional text (string value)
-b or --burstTimeout=TIME send burst of notifications as defined by the
repeatSends [default: 1] attribute
and sleep TIME (usec)
-c or --notificationClassId=VE,MA,MI vendorid, majorid, minorid
-E or --eventTime=TIME numeric value of SaTimeT
-e or --eventType=16384...16389 numeric value of SaNtfEventTypeT
-n or --notificationObject=NOT_OBJ notification object (string value)
-N or --notifyingObject=NOTIFY_OBJ notififying object (string value)
-p or --probableCause=0..74 numeric value SaNtfProbableCauseT
-r or --repeatSends=NUM send the same notifification NUM times
-s or --perceivedSeverity=0...5 severity numeric value
-T or --notificationType=0x1000...0x5000 numeric value of SaNtfNotificationTypeT

The following example sends one security alarm with the perceived severity set to
SA_NTF_SEVERITY_MAJOR, probable cause to set SA_NTF_UNSPECIFIED_REASON,
and with the additional information string included as additional text.
Parameters not specified are set to their respective default values.
# ntfsend -T 0x5000 -s 4 --probableCause 74 -a “additional information

4.2.2 Command ntfsubscribe

The ntfsubscribe CLI command subscribes to the NTF and prints the received
notifications to stdout. The attributes of the command specify the time and the
filter, based on notification type, for the subscription. By default it subscribes to all
notifications. -h or –-help prints the available options:
-a or –alarm subscribe for alarm notifications only
-c or –attributeChange subscribe for attributeChange notifications only
-o or –objectCreateDelete subscribe for objectCreateDelete notifications only
-s or –stateChange subscribe for stateChange notifications only
-t or --timeout=TIME timeout (sec) waiting for notification
-y or –securityAlarm subscribe for securityAlarm notifications only

The security alarm sent by the ntfsend example in Section 4.2.1 Command
ntfsend on page 30 can be received by ntfsubscribe used with option –y and
the printout looks as follows:
=== Oct 6 11:42:42 - Security Alarm ===
eventType = SA_NTF_INTEGRITY_VIOLATION
notificationObject = "default notification object"
notifyingObject = "default notifying object"
notificationClassId = 193.0.0 (0x0)
additionalText = "additional information"
probableCause = SA_NTF_UNSPECIFIED_REASON
severity = SA_NTF_SEVERITY_MAJOR
Security Alarm Detector Type: 5
Security Alarm Detector Value: 1
ervice User Type: 5
Service User Value: 3
Service Provider Type: 5
Service Provider Value: 2

To receive the alarm, ntfsubscribe must be started before sending the alarm
with ntfsend.

30 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Information Model and Administrative Operations

4.2.3 Command ntfread

As opposed to ntfsubscribe, command ntfread collects the notifications using
the readers API, and therefore from the cache maintained by the NTF. It prints
them to stdout.

As the current implementation only caches alarms and security alarms, only these
can be read and filtered. By default, as shown in the reader API example, it reads
all alarms and security alarms starting from the oldest in the cache, which can be
up to 10000 notifications (or whatever is the value of the NTFSV_ENV_CACHE_SIZE
environment variable).

Note: Be cautious and use filters.

-h or –-help prints the available options:

-b or --searchMode=1..7 search mode for the search criteria, numeric
value of SaNtfSearchModeT
SA_NTF_SEARCH_BEFORE_OR_AT_TIME to
SA_NTF_SEARCH_ONLY_FILTER
-c or --notificationClassId=VE,MA,MI vendorid, majorid, minored
-d or --securityEventType=20480...20485 event type, the numeric value of
SaNtfEventTypeT applicable to security alarms
SA_NTF_SECURITY_ALARM_NOTIFICATIONS_START to
SA_NTF_TIME_VIOLATION
-e or --eventType=16384...16389 event type, the numeric value of
saNtfEventTypeT applicable to alarms
SA_NTF_ALARM_NOTIFICATIONS_START to
SA_NTF_ALARM_ENVIRONMENT
-E or --eventTime=TIME event time for the search criteria, the numeric
value of SaTimeT
-i or --notificationId=<nId> set search mode of the search criteria for a
specific notification id
-k or –onlyAlarm read alarms only
-l or –onlySecurityAlarm read security alarms only
-n or --notificationObject=NOT_OBJ read notifications for the give notification
object (string value)
-N or --notifyingObject=NOTIFY_OBJ read notifications generated by the notifying
object (string value)
-o or –searchOlder read in search direction SA_NTF_SEARCH_OLDER
(default is SA_NTF_SEARCH_YOUNGER)
-p or --probableCause=0..74 read notifications with give probable cause,
numeric value of SaNtfProbableCauseT
SA_NTF_ADAPTER_ERROR to
SA_NTF_UNSPECIFIED_REASON
-s or --perceivedSeverity=0...5 read alarms with give severity, numeric value
of SaNtfSeverityT (SA_NTF_SEVERITY_CLEARED = 0,
SA_NTF_SEVERITY_INDETERMINATE, SA_NTF_SEVERITY_WARNING,
SA_NTF_SEVERITY_MINOR,
SA_NTF_SEVERITY_MAJOR,
SA_NTF_SEVERITY_CRITICAL

The following example filters and reads the alarm generated by command
ntfsend shown earlier. It uses options -s 4 and --probableCause 74,
which correspond to severity SA_NTF_SEVERITY_MAJOR and probable cause
SA_NTF_UNSPECIFIED_REASON specified in the alarm. However, ntfread is to
be used after ntfsend.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 31

 NTF User Guide

# ntfread -s 4 --probableCause 74
=== Oct 6 12:20:41 - Security Alarm ===
eventType = SA_NTF_INTEGRITY_VIOLATION
notificationObject = "default notification object"
notifyingObject = "default notifying object"
notificationClassId = 193.0.0 (0x0)
additionalText = "additional information"
probableCause = SA_NTF_UNSPECIFIED_REASON
severity = SA_NTF_SEVERITY_MAJOR
Security Alarm Detector Type: 5
Security Alarm Detector Value: 1
Service User Type: 5
Service User Value: 3
Service Provider Type: 5
Service Provider Value: 2

32 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 General Concerns

5 General Concerns

5.1 Standards Compliance

It is recommended to comply with existing standards such as POSIX® and
Linux® Standard Base (LSB) for increased portability between different Linux
distributions or even Unix® dialects.

4/1553-APR 901 0444/4 Uen B | 2016-11-28 33

 NTF User Guide

34 4/1553-APR 901 0444/4 Uen B | 2016-11-28

 Reference List

Reference List

[1] International Telecommunication Union (1992). Information Technology

– Open Systems Interconnection – System Management: Alarm Reporting
Function. ITU-T Recommendation X.733, http://www.itu.int/rec/T-REC-X

[2] International Telecommunication Union (1992). Information

Technology – Open Systems Interconnection – System Management:
Security Alarm Reporting Function. ITU-T Recommendation X.736,
http://www.itu.int/rec/T-REC-X

[3] International Telecommunication Union (1992). Information Technology –

Open Systems Interconnection – System Management: State Management
Function. ITU-T Recommendation X.731, , http://www.itu.int/rec/T-REC-X

[4] SA-Forum (2011): Application Interface Specification, Availability

Management Framework; SAI-AIS-AMF-B.04.01, http://www.saforum.org/
hoa/assn16627/images/SAI-AIS-AMF-B.04.01.AL.pdf

[5] SA-Forum (2011): Application Interface Specification, Cluster Membership

Service; SAI-AIS-CLM-B.04.01, http://www.saforum.org/hoa/assn16627/i
mages/SAI-AIS-CLM-B.04.01.AL.pdf

[6] SA-Forum (2011): Application Interface Specification, Information Model

Management Service; SAI-AIS-IMM-A.03.01, http://www.saforum.org/hoa
/assn16627/images/SAI-AIS-IMM-A.03.01.AL.pdf

[7] SA-Forum (2011): Application Interface Specification, Log Service;

SAI-AIS-LOG-A.02.01, http://www.saforum.org/hoa/assn16627/images/S
AI-AIS-LOG-A.02.01.AL.pdf

[8] SA-Forum (2011): Application Interface Specification, Notification Service,

SAI-AIS-NTF-A.01.01, http://www.saforum.org/hoa/assn16627/images/S
AI-AIS-NTF-A.01.01.AL.pdf

[9] SA-Forum (2011): Application Interface Specification, Notification Service;

SAI-AIS-NTF-A.03.01, http://www.saforum.org/hoa/assn16627/images/S
AI-AIS-NTF-A.03.01.AL.pdf

[10] SA-Forum (2011): Application Interface Specification, Platform

Management Service; SAI-AIS-PLM-A.01.02, http://www.saforum.org/hoa
/assn16627/images/SAI-AIS-PLM-A.01.02.AL.pdf

4/1553-APR 901 0444/4 Uen B | 2016-11-28 35