draft-ietf-ccamp-alarm-module-08.txt   draft-ietf-ccamp-alarm-module-09.txt 
Network Working Group S. Vallin Network Working Group S. Vallin
Internet-Draft Stefan Vallin AB Internet-Draft Stefan Vallin AB
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: September 27, 2019 Cisco Expires: October 13, 2019 Cisco
March 26, 2019 April 11, 2019
YANG Alarm Module YANG Alarm Module
draft-ietf-ccamp-alarm-module-08 draft-ietf-ccamp-alarm-module-09
Abstract Abstract
This document defines a YANG module for alarm management. It This document defines a YANG module for alarm management. It
includes functions for alarm list management, alarm shelving and includes functions for alarm list management, alarm shelving and
notifications to inform management systems. There are also notifications to inform management systems. There are also
operations to manage the operator state of an alarm and operations to manage the operator state of an alarm and
administrative alarm procedures. The module carefully maps to administrative alarm procedures. The module carefully maps to
relevant alarm standards. relevant alarm standards.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 27, 2019. This Internet-Draft will expire on October 13, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology and Notation . . . . . . . . . . . . . . . . 3 1.1. Terminology and Notation . . . . . . . . . . . . . . . . 3
2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Alarm Module Concepts . . . . . . . . . . . . . . . . . . . . 5 3. Alarm Module Concepts . . . . . . . . . . . . . . . . . . . . 5
3.1. Alarm Definition . . . . . . . . . . . . . . . . . . . . 5 3.1. Alarm Definition . . . . . . . . . . . . . . . . . . . . 5
3.2. Alarm Type . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Alarm Type . . . . . . . . . . . . . . . . . . . . . . . 6
3.3. Identifying the Alarming Resource . . . . . . . . . . . . 8 3.3. Identifying the Alarming Resource . . . . . . . . . . . . 8
3.4. Identifying Alarm Instances . . . . . . . . . . . . . . . 9 3.4. Identifying Alarm Instances . . . . . . . . . . . . . . . 9
3.5. Alarm Life-Cycle . . . . . . . . . . . . . . . . . . . . 9 3.5. Alarm Lifecycle . . . . . . . . . . . . . . . . . . . . . 9
3.5.1. Resource Alarm Life-Cycle . . . . . . . . . . . . . . 10 3.5.1. Resource Alarm Lifecycle . . . . . . . . . . . . . . 10
3.5.2. Operator Alarm Life-cycle . . . . . . . . . . . . . . 10 3.5.2. Operator Alarm Lifecycle . . . . . . . . . . . . . . 10
3.5.3. Administrative Alarm Life-Cycle . . . . . . . . . . . 11 3.5.3. Administrative Alarm Lifecycle . . . . . . . . . . . 11
3.6. Root Cause, Impacted Resources and Related 3.6. Root Cause, Impacted Resources and Related
Alarms . . . . . . . . . . . . . . . . . . . . . . . . . 11 Alarms . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.7. Alarm Shelving . . . . . . . . . . . . . . . . . . . . . 13 3.7. Alarm Shelving . . . . . . . . . . . . . . . . . . . . . 13
3.8. Alarm Profiles . . . . . . . . . . . . . . . . . . . . . 13 3.8. Alarm Profiles . . . . . . . . . . . . . . . . . . . . . 13
4. Alarm Data Model . . . . . . . . . . . . . . . . . . . . . . 13 4. Alarm Data Model . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Alarm Control . . . . . . . . . . . . . . . . . . . . . . 15 4.1. Alarm Control . . . . . . . . . . . . . . . . . . . . . . 15
4.1.1. Alarm Shelving . . . . . . . . . . . . . . . . . . . 15 4.1.1. Alarm Shelving . . . . . . . . . . . . . . . . . . . 15
4.2. Alarm Inventory . . . . . . . . . . . . . . . . . . . . . 16 4.2. Alarm Inventory . . . . . . . . . . . . . . . . . . . . . 15
4.3. Alarm Summary . . . . . . . . . . . . . . . . . . . . . . 16 4.3. Alarm Summary . . . . . . . . . . . . . . . . . . . . . . 16
4.4. The Alarm List . . . . . . . . . . . . . . . . . . . . . 17 4.4. The Alarm List . . . . . . . . . . . . . . . . . . . . . 17
4.5. The Shelved Alarms List . . . . . . . . . . . . . . . . . 19 4.5. The Shelved Alarms List . . . . . . . . . . . . . . . . . 19
4.6. Alarm Profiles . . . . . . . . . . . . . . . . . . . . . 19 4.6. Alarm Profiles . . . . . . . . . . . . . . . . . . . . . 19
4.7. Operations . . . . . . . . . . . . . . . . . . . . . . . 20 4.7. Operations . . . . . . . . . . . . . . . . . . . . . . . 20
4.8. Notifications . . . . . . . . . . . . . . . . . . . . . . 20 4.8. Notifications . . . . . . . . . . . . . . . . . . . . . . 20
5. Relationship to the ietf-hardware YANG module . . . . . . . . 20 5. Relationship to the ietf-hardware YANG module . . . . . . . . 20
6. Alarm YANG Module . . . . . . . . . . . . . . . . . . . . . . 21 6. Alarm YANG Module . . . . . . . . . . . . . . . . . . . . . . 21
7. X.733 Extensions . . . . . . . . . . . . . . . . . . . . . . 53 7. X.733 Extensions . . . . . . . . . . . . . . . . . . . . . . 53
8. The X.733 Mapping Module . . . . . . . . . . . . . . . . . . 53 8. The X.733 Mapping Module . . . . . . . . . . . . . . . . . . 53
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65
10. Security Considerations . . . . . . . . . . . . . . . . . . . 65 10. Security Considerations . . . . . . . . . . . . . . . . . . . 65
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 66 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 66
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 67
12.1. Normative References . . . . . . . . . . . . . . . . . . 66 12.1. Normative References . . . . . . . . . . . . . . . . . . 67
12.2. Informative References . . . . . . . . . . . . . . . . . 68 12.2. Informative References . . . . . . . . . . . . . . . . . 68
Appendix A. Vendor-specific Alarm-Types Example . . . . . . . . 69 Appendix A. Vendor-specific Alarm Types Example . . . . . . . . 69
Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 70 Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 70
Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 71 Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 71
Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 72 Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 72
Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 73 Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 73
Appendix F. Relationship to other alarm standards . . . . . . . 74 Appendix F. Relationship to other alarm standards . . . . . . . 74
F.1. Alarm definition . . . . . . . . . . . . . . . . . . . . 74 F.1. Alarm definition . . . . . . . . . . . . . . . . . . . . 74
F.2. Data model . . . . . . . . . . . . . . . . . . . . . . . 76 F.2. Data model . . . . . . . . . . . . . . . . . . . . . . . 76
F.2.1. X.733 . . . . . . . . . . . . . . . . . . . . . . . . 76 F.2.1. X.733 . . . . . . . . . . . . . . . . . . . . . . . . 76
F.2.2. RFC 3877, the Alarm MIB . . . . . . . . . . . . . . . 76 F.2.2. RFC 3877, the Alarm MIB . . . . . . . . . . . . . . . 76
F.2.3. 3GPP Alarm IRP . . . . . . . . . . . . . . . . . . . 77 F.2.3. 3GPP Alarm IRP . . . . . . . . . . . . . . . . . . . 77
F.2.4. G.7710 . . . . . . . . . . . . . . . . . . . . . . . 77 F.2.4. G.7710 . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix G. Alarm Usability Requirements . . . . . . . . . . . . 77 Appendix G. Alarm Usability Requirements . . . . . . . . . . . . 77
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81
1. Introduction 1. Introduction
This document defines a YANG [RFC7950] module for alarm management. This document defines a YANG [RFC7950] module for alarm management.
The purpose is to define a standardized alarm interface for network The purpose is to define a standardized alarm interface for network
devices that can be easily integrated into management applications. devices that can be easily integrated into management applications.
The model is also applicable as a north-bound alarm interface in the The model is also applicable as a northbound alarm interface in the
management applications. management applications.
Alarm monitoring is a fundamental part of monitoring the network. Alarm monitoring is a fundamental part of monitoring the network.
Raw alarms from devices do not always tell the status of the network Raw alarms from devices do not always tell the status of the network
services or necessarily point to the root cause. However, being able services or necessarily point to the root cause. However, being able
to feed alarms to the alarm management application in a standardized to feed alarms to the alarm management application in a standardized
format is a starting point for performing higher level network format is a starting point for performing higher level network
assurance tasks. assurance tasks.
The design of the module is based on experience from using and The design of the module is based on experience from using and
skipping to change at page 4, line 8 skipping to change at page 4, line 8
o data tree o data tree
o server o server
The following terms are used within this document: The following terms are used within this document:
o Alarm (the general concept): An alarm signifies an undesirable o Alarm (the general concept): An alarm signifies an undesirable
state in a resource that requires corrective action. state in a resource that requires corrective action.
o Fault: A fault is the underlying cause of an undesired behaviour. o Fault: A fault is the underlying cause of an undesired behavior.
There is no trivial one-to-one mapping between faults and alarms. There is no trivial one-to-one mapping between faults and alarms.
One fault may result in several alarms in case the system lacks One fault may result in several alarms in case the system lacks
root-cause and correlation capabilities. An alarm might not have root-cause and correlation capabilities. An alarm might not have
an underlying fault as a cause, imagine a bad MOS score alarm from an underlying fault as a cause. For example, imagine a bad Mean
a VOIP probe and the cause being non-optimal QoS configuration. Opinion Score (MOS) alarm from a Voice over IP (VOIP) probe and
the cause being non-optimal QoS configuration.
o Alarm Type: An alarm type identifies a possible unique alarm state o Alarm Type: An alarm type identifies a possible unique alarm state
for a resource. Alarm types are names to identify the state like for a resource. Alarm types are names to identify the state like
"link-alarm", "jitter-violation", "high-disk-utilization". "link-alarm", "jitter-violation", "high-disk-utilization".
o Resource: A fine-grained identification of the alarming resource, o Resource: A fine-grained identification of the alarming resource,
for example: an interface, a process. for example: an interface, a process.
o Alarm Instance: The alarm state for a specific resource and alarm o Alarm Instance: The alarm state for a specific resource and alarm
type. For example (GigabitEthernet0/15, link-alarm). An entry in type. For example ("GigabitEthernet0/15", link-alarm). An entry
the alarm list. in the alarm list.
o Cleared alarm: A cleared alarm is an alarm where the system/server o Cleared alarm: A cleared alarm is an alarm where the system
considers the undesired state to be cleared. Operators can not considers the undesired state to be cleared. Operators can not
clear alarms, clearance is managed by the system. A linkUp clear alarms, clearance is managed by the system. For example, a
notification can be considered a clear condition for a linkDown linkUp notification can be considered a clear condition for a
state. linkDown state.
o Closed alarm: Operators can close alarms irrespective of the alarm o Closed alarm: Operators can close alarms irrespective of the alarm
being cleared or not. A closed alarm indicates that the alarm being cleared or not. A closed alarm indicates that the alarm
does not need attention, either since the corrective action has does not need attention, either since the corrective action has
been taken or that it can be ignored for other reasons. been taken or that it can be ignored for other reasons.
o Alarm Inventory: A list of all possible alarm types on a system. o Alarm Inventory: A list of all possible alarm types on a system.
o Alarm Shelving: Blocking alarms according to specific criteria. o Alarm Shelving: Blocking alarms according to specific criteria.
o Corrective Action: An action taken by an operator or automation o Corrective Action: An action taken by an operator or automation
routine in order to minimize the impact of the alarm or resolving routine in order to minimize the impact of the alarm or resolve
the root cause. the root cause.
o Management System: The alarm management application that consumes o Management System: The alarm management application that consumes
the alarms, i.e., acts as a client. the alarms, i.e., acts as a client.
o System: The system that implements this YANG alarm module, i.e., o System: The system that implements this YANG alarm module, i.e.,
acts as a server. This corresponds to a network device or a acts as a server. This corresponds to a network device or a
management application that provides a north-bound alarm management application that provides a northbound alarm interface.
interface.
Tree diagrams used in this document follow the notation defined in Tree diagrams used in this document follow the notation defined in
[RFC8340]. [RFC8340].
2. Objectives 2. Objectives
The objectives for the design of the Alarm Module are: The objectives for the design of the Alarm Module are:
o Simple to use. If a system supports this module, it shall be o Simple to use. If a system supports this module, it shall be
straight-forward to integrate this into a YANG based alarm straight-forward to integrate this into a YANG based alarm
manager. manager.
o View alarms as states on resources and not as discrete o View alarms as states on resources and not as discrete
notifications. notifications.
o Clear definition of "alarm" in order to exclude general events o To provide a precise definition of "alarm" in order to exclude
that should not be forwarded as alarm notifications. general events that should not be forwarded as alarm
notifications.
o Clear and precise identification of alarm types and alarm o To provide precise identification of alarm types and alarm
instances. instances.
o A management system should be able to pull all available alarm o A management system should be able to pull all available alarm
types from a system, i.e., read the alarm inventory from a system. types from a system, i.e., read the alarm inventory from a system.
This makes it possible to prepare alarm operators with This makes it possible to prepare alarm operators with
corresponding alarm instructions. corresponding alarm instructions.
o Address alarm usability requirements, see Appendix G. While IETF o Address alarm usability requirements, see Appendix G. While IETF
and telecom standards have addressed alarms mostly from a protocol and telecom standards have addressed alarms mostly from a protocol
perspective, the process industry has published several relevant perspective, the process industry has published several relevant
standards addressing requirements for a useful alarm interface; standards addressing requirements for a useful alarm interface;
[EEMUA], [ISA182]. This alarm module defines usability [EEMUA], [ISA182]. This alarm module defines usability
requirements as well as a YANG data model. requirements as well as a YANG data model.
o Mapping to X.733, which is a requirement for some alarm systems. o Mapping to [X.733], which is a requirement for some alarm systems.
Still, keep some of the X.733 concepts out of the core model in Still, keep some of the X.733 concepts out of the core model in
order to make the model small and easy to understand. order to make the model small and easy to understand.
3. Alarm Module Concepts 3. Alarm Module Concepts
This section defines the fundamental concepts behind the data model. This section defines the fundamental concepts behind the data model.
This section is rooted in the works of Vallin et. al [ALARMSEM]. This section is rooted in the works of Vallin et. al [ALARMSEM].
3.1. Alarm Definition 3.1. Alarm Definition
skipping to change at page 6, line 34 skipping to change at page 6, line 34
Standards and vendors should define their own alarm type identities Standards and vendors should define their own alarm type identities
based on this definition. based on this definition.
The use of YANG identities means that all possible alarms are The use of YANG identities means that all possible alarms are
identified at design time. This explicit declaration of alarm types identified at design time. This explicit declaration of alarm types
makes it easier to allow for alarm qualification reviews and makes it easier to allow for alarm qualification reviews and
preparation of alarm actions and documentation. preparation of alarm actions and documentation.
There are occasions where the alarm types are not known at design There are occasions where the alarm types are not known at design
time. For example, a system with digital inputs that allows users to time. An example is a system with digital inputs that allows users
connects detectors (e.g., smoke detector) to the inputs. In this to connect detectors, such as smoke detectors, to the inputs. In
case it is a configuration action that says that certain connectors this case it is a configuration action that says that certain
are fire alarms for example. connectors are fire alarms for example.
In order to allow for dynamic addition of alarm types the alarm In order to allow for dynamic addition of alarm types the alarm
module allows for further qualification of the identity based alarm module allows for further qualification of the identity-based alarm
type using a string. A potential drawback of this is that there is a type using a string. A potential drawback of this is that there is a
big risk that alarm operators will receive alarm types as a surprise, significant risk that alarm operators will receive alarm types as a
they do not know how to resolve the problem since a defined alarm surprise. They do not know how to resolve the problem since a
procedure does not necessarily exist. To avoid this risk the system defined alarm procedure does not necessarily exist. To avoid this
MUST publish all possible alarm types in the alarm inventory, see risk the system MUST publish all possible alarm types in the alarm
Section 4.2. inventory, see Section 4.2.
A vendor or standard organization can define their own alarm-type A vendor or standards organization can define their own alarm type
hierarchy. The example below shows a hierarchy based on X.733 event hierarchy. The example below shows a hierarchy based on X.733 event
types: types:
import ietf-alarms { import ietf-alarms {
prefix al; prefix al;
} }
identity vendor-alarms { identity vendor-alarms {
base al:alarm-type; base al:alarm-type;
} }
identity communications-alarm { identity communications-alarm {
skipping to change at page 9, line 16 skipping to change at page 9, line 16
like: "/mgr:devices/mgr:device[mgr:name='xyz123']/dev:interfaces/ like: "/mgr:devices/mgr:device[mgr:name='xyz123']/dev:interfaces/
dev:interface[dev:name='FastEthernet1/0']" dev:interface[dev:name='FastEthernet1/0']"
This module also allows for alternate naming of the alarming resource This module also allows for alternate naming of the alarming resource
if it is not available in the data tree. if it is not available in the data tree.
3.4. Identifying Alarm Instances 3.4. Identifying Alarm Instances
A primary goal of this alarm module is to remove any ambiguity in how A primary goal of this alarm module is to remove any ambiguity in how
alarm notifications are mapped to an update of an alarm instance. alarm notifications are mapped to an update of an alarm instance.
X.733 and especially 3GPP were not really clear on this point. This The X.733 and 3GPP documents were not clear on this point. This YANG
YANG alarm module states that the tuple (resource, alarm type alarm module states that the tuple (resource, alarm type identifier,
identifier, alarm type qualifier) corresponds to a single alarm alarm type qualifier) corresponds to a single alarm instance. This
instance. This means that alarm notifications for the same resource means that alarm notifications for the same resource and same alarm
and same alarm type are matched to update the same alarm instance. type are matched to update the same alarm instance. These three
These three leafs are therefore used as the key in the alarm list: leafs are therefore used as the key in the alarm list:
list alarm { list alarm {
key "resource alarm-type-id alarm-type-qualifier"; key "resource alarm-type-id alarm-type-qualifier";
... ...
} }
3.5. Alarm Life-Cycle 3.5. Alarm Lifecycle
The alarm model clearly separates the resource alarm life-cycle from The alarm model clearly separates the resource alarm lifecycle from
the operator and administrative life-cycles of an alarm. the operator and administrative lifecycles of an alarm.
o resource alarm life-cycle: the alarm instrumentation that controls o resource alarm lifecycle: the alarm instrumentation that controls
alarm raise, clearance, and severity changes. alarm raise, clearance, and severity changes.
o operator alarm life-cycle: operators acting upon alarms with o operator alarm lifecycle: operators acting upon alarms with
actions like acknowledgment and closing. Closing an alarm implies actions like acknowledgment and closing. Closing an alarm implies
that the operator considers the corrective action performed. that the operator considers the corrective action performed.
Operators can also shelf (block/filter) alarms in order to avoid Operators can also shelf (block/filter) alarms in order to avoid
nuisance alarms. nuisance alarms.
o administrative alarm life-cycle: purging (deleting) unwanted o administrative alarm lifecycle: purging (deleting) unwanted alarms
alarms and compressing the alarm status change list. This module and compressing the alarm status change list. This module exposes
exposes operations to manage the administrative life-cycle. The operations to manage the administrative lifecycle. The server may
server may also perform these operations based on other policies, also perform these operations based on other policies, but how
but how that is done is out of scope for this document. that is done is out of scope for this document.
A server SHOULD describe how long it retains cleared/closed alarms: A server SHOULD describe how long it retains cleared/closed alarms:
until manually purged or if it has an automatic removal policy. until manually purged or if it has an automatic removal policy. How
this is done is outside the scope of this document.
3.5.1. Resource Alarm Life-Cycle 3.5.1. Resource Alarm Lifecycle
From a resource perspective, an alarm can for example have the From a resource perspective, an alarm can for example have the
following life-cycle: raise, change severity, change severity, clear, following lifecycle: raise, change severity, change severity, clear,
being raised again, etc. All of these status changes can have being raised again, etc. All of these status changes can have
different alarm texts generated by the instrumentation. Two different alarm texts generated by the instrumentation. Two
important things to note: important things to note:
1. Alarms are not deleted when they are cleared. Deleting alarms is 1. Alarms are not deleted when they are cleared. Deleting alarms is
an administrative process. The alarm module defines an action an administrative process. The alarm module defines an action
"purge-alarms" that deletes alarms. "purge-alarms" that deletes alarms.
2. Alarms are not cleared by operators, only the underlying 2. Alarms are not cleared by operators, only the underlying
instrumentation can clear an alarm. Operators can close alarms. instrumentation can clear an alarm. Operators can close alarms.
The YANG tree representation below illustrates the resource oriented The YANG tree representation below illustrates the resource oriented
life-cycle: lifecycle:
+--ro alarm* [resource alarm-type-id alarm-type-qualifier] +--ro alarm* [resource alarm-type-id alarm-type-qualifier]
... ...
+--ro is-cleared boolean +--ro is-cleared boolean
+--ro last-changed yang:date-and-time +--ro last-changed yang:date-and-time
+--ro perceived-severity severity +--ro perceived-severity severity
+--ro alarm-text alarm-text +--ro alarm-text alarm-text
+--ro status-change* [time] {alarm-history}? +--ro status-change* [time] {alarm-history}?
+--ro time yang:date-and-time +--ro time yang:date-and-time
+--ro perceived-severity severity-with-clear +--ro perceived-severity severity-with-clear
skipping to change at page 10, line 44 skipping to change at page 10, line 44
For every status change from the resource perspective a row is added For every status change from the resource perspective a row is added
to the "status-change" list, if the server implements the feature to the "status-change" list, if the server implements the feature
"alarm-history". The feature "alarm-history" is optional to "alarm-history". The feature "alarm-history" is optional to
implement, since keeping the alarm history may have an impact on the implement, since keeping the alarm history may have an impact on the
server's memory resources. server's memory resources.
The last status values are also represented as leafs for the alarm. The last status values are also represented as leafs for the alarm.
Note well that the alarm severity does not include "cleared", alarm Note well that the alarm severity does not include "cleared", alarm
clearance is a boolean flag. clearance is a boolean flag.
An alarm can therefore look like this: ((GigabitEthernet0/25, link- An alarm can therefore look like this: (("GigabitEthernet0/25", link-
alarm,""), false, 2018-04-08T08:20:10.00Z, major, "Interface alarm,""), false, 2018-04-08T08:20:10.00Z, major, "Interface
GigabitEthernet0/25 down") GigabitEthernet0/25 down")
3.5.2. Operator Alarm Life-cycle 3.5.2. Operator Alarm Lifecycle
Operators can also act upon alarms using the set-operator-state Operators can act upon alarms using the set-operator-state action:
action:
+--ro alarm* [resource alarm-type-id alarm-type-qualifier] +--ro alarm* [resource alarm-type-id alarm-type-qualifier]
... ...
+--ro operator-state-change* [time] {operator-actions}? +--ro operator-state-change* [time] {operator-actions}?
| +--ro time yang:date-and-time | +--ro time yang:date-and-time
| +--ro operator string | +--ro operator string
| +--ro state operator-state | +--ro state operator-state
| +--ro text? string | +--ro text? string
+---x set-operator-state {operator-actions}? +---x set-operator-state {operator-actions}?
+---w input +---w input
+---w state writable-operator-state +---w state writable-operator-state
+---w text? string +---w text? string
The operator state for an alarm can be: "none", "ack", "shelved", and The operator state for an alarm can be: "none", "ack", "shelved", and
"closed". Alarm deletion (using the action "purge-alarms"), can use "closed". Alarm deletion (using the action "purge-alarms") can use
this state as a criterion. A closed alarm is an alarm where the this state as a criterion. For example, a closed alarm is an alarm
operator has performed any required corrective actions. Closed where the operator has performed any required corrective actions.
alarms are good candidates for being purged. Closed alarms are good candidates for being purged.
3.5.3. Administrative Alarm Life-Cycle 3.5.3. Administrative Alarm Lifecycle
Deleting alarms from the alarm list is considered an administrative Deleting alarms from the alarm list is considered an administrative
action. This is supported by the "purge-alarms" action. The "purge- action. This is supported by the "purge-alarms" action. The "purge-
alarms" action takes a filter as input. The filter selects alarms alarms" action takes a filter as input. The filter selects alarms
based on the operator and resource life-cycle such as "all closed based on the operator and resource lifecycle such as "all closed
cleared alarms older than a time specification". The server may also cleared alarms older than a time specification". The server may also
perform these operations based on other policies, but how that is perform these operations based on other policies, but how that is
done is out of scope for this document. done is out of scope for this document.
Purged alarms are removed from the alarm list. Note well, if the Purged alarms are removed from the alarm list. Note well, if the
alarm resource state changes after a purge, the alarm will reappear alarm resource state changes after a purge, the alarm will reappear
in the alarm list. in the alarm list.
Alarms can be compressed. Compressing an alarm deletes all entries Alarms can be compressed. Compressing an alarm deletes all entries
in the alarm's "status-change" list except for the last status in the alarm's "status-change" list except for the last status
skipping to change at page 12, line 17 skipping to change at page 12, line 17
disc partition. disc partition.
Service impact analysis: An alarm can refer to potential impacted Service impact analysis: An alarm can refer to potential impacted
resources, for example: an interface alarm referring to impacted resources, for example: an interface alarm referring to impacted
network services network services
Alarm correlation: Dependencies between alarms, several alarms can Alarm correlation: Dependencies between alarms, several alarms can
be grouped as relating to each other, for example a streaming be grouped as relating to each other, for example a streaming
media alarm relating to a high jitter alarm. media alarm relating to a high jitter alarm.
Different systems have various degrees of alarm correlation and Different systems have varying degrees of alarm correlation and
analysis capabilities, and the intent of the alarm module is to analysis capabilities, and the intent of the alarm module is to
enable any capability, including none. enable any capability, including none.
The general principle of this alarm module is to limit the amount of The general principle of this alarm module is to limit the amount of
alarms. In many cases several resources are affected for a given alarms. In many cases several resources are affected for a given
underlying problem. A full disk will of course impact databases and underlying problem. A full disk will of course impact databases and
applications as well. The recommendation is to have a single alarm applications as well. The recommendation is to have a single alarm
for the underlying problem and list the affected resources in the for the underlying problem and list the affected resources in the
alarm, rather than having separate alarms for each resource. alarm, rather than having separate alarms for each resource.
The alarm has one leaf-list to identify possible "impacted-resources" The alarm has one leaf-list to identify possible "impacted-resources"
and a leaf-list to identify possible "root-cause-resources". These and a leaf-list to identify possible "root-cause-resources". These
serves as hints only. It is up to the client application to use this serves as hints only. It is up to the client application to use this
information to present the overall status. Using the disk full information to present the overall status. Using the disk full
example, a "good" alarm would be to use the hard disk partition as example, a good alarm would be to use the hard disk partition as the
the alarming resource and add the database and applications into the alarming resource and add the database and applications into the
impacted-resources leaf-list. "impacted-resources" leaf-list.
A system should always strive to identify the resource that can be A system should always strive to identify the resource that can be
acted upon as the "resource" leaf. The "impacted-resource" leaf-list acted upon as the "resource" leaf. The "impacted-resource" leaf-list
shall be used to identify any side-effects of the alarm. The shall be used to identify any side-effects of the alarm. The
impacted resources can not be acted upon to fix the problem. The impacted resources can not be acted upon to fix the problem. The
disk full example above illustrates the principle; you can not fix disk full example above illustrates the principle; you can not fix
the underlying issue by database operations. However, you need to the underlying issue by database operations. However, you need to
pay attention to the database to perform any operations that limits pay attention to the database to perform any operations that limits
the impact of problem. the impact of problem.
In some occasions the system might not be capable of detecting the On some occasions the system might not be capable of detecting the
root cause, the resource that can be acted upon. The instrumentation root cause, the resource that can be acted upon. The instrumentation
in this case only monitors the side-effect and needs to represent an in this case only monitors the side-effect and raises an alarm to
alarm that indicates a situation that needs acting upon. The indicate a situation requiring attention. The instrumentation still
instrumentation still might identify possible candidates for the might identify possible candidates for the root-cause resource. In
root-cause resource. In this case the "root-cause-resource" leaf- this case the "root-cause-resource" leaf-list can be used to indicate
list can be used to indicate the candidate root-cause resources. An the candidate root-cause resources. An example of this kind of alarm
example of this kind of alarm might be an active test tool that might be an active test tool that detects an SLA violation on a VPN
detects an SLA violation on a VPN connection and identifies the connection and identifies the devices along the chain as candidate
devices along the chain as candidate root causes. root causes.
The alarm module also supports a way to associate different alarms to The alarm module also supports a way to associate different alarms to
each other with the "related-alarm" list. This list enables the each other with the "related-alarm" list. This list enables the
server to inform the client that certain alarms are related to other server to inform the client that certain alarms are related to other
alarms. alarms.
Note well that this module does not prescribe any dependencies or Note well that this module does not prescribe any dependencies or
preference between the above alarm correlation mechanisms. Different preference between the above alarm correlation mechanisms. Different
systems have different capabilities and the above described systems have different capabilities and the above described
mechanisms are available to support the instrumentation features. mechanisms are available to support the instrumentation features.
3.7. Alarm Shelving 3.7. Alarm Shelving
Alarm shelving is an important function in order for alarm management Alarm shelving is an important function in order for alarm management
applications and operators to stop superfluous alarms. A shelved applications and operators to stop superfluous alarms. A shelved
alarm implies that any alarms fulfilling these criteria are ignored alarm implies that any alarms fulfilling these criteria are ignored
(blocked/filtered). Shelved alarms appear in a dedicated shelved (blocked/filtered). Shelved alarms appear in a dedicated shelved
alarm list in order not to disturb the relevant alarms. Shelved alarm list in order to be filtered out from the alarm list in order
for the main alarm list to only contain entries of interest. Shelved
alarms do not generate notifications but the shelved alarm list is alarms do not generate notifications but the shelved alarm list is
updated with any alarm state changes. updated with any alarm state changes.
Alarm shelving is optional to implement, since matching alarms Alarm shelving is optional to implement, since matching alarms
against shelf criteria may have an impact on the server's processing against shelf criteria may have an impact on the server's processing
resources. resources.
3.8. Alarm Profiles 3.8. Alarm Profiles
Alarm profiles are used to configure further information to an alarm Alarm profiles are used to configure further information to an alarm
skipping to change at page 13, line 45 skipping to change at page 13, line 46
the system default levels. This corresponds to the Alarm Assignment the system default levels. This corresponds to the Alarm Assignment
Profile, ASAP, functionality in M.3100 [M.3100] and M.3160 [M.3160]. Profile, ASAP, functionality in M.3100 [M.3100] and M.3160 [M.3160].
Other standard or enterprise modules can augment this list with Other standard or enterprise modules can augment this list with
further alarm type information. further alarm type information.
4. Alarm Data Model 4. Alarm Data Model
The fundamental parts of the data model are the "alarm-list" with The fundamental parts of the data model are the "alarm-list" with
associated notifications and the "alarm-inventory" list of all associated notifications and the "alarm-inventory" list of all
possible alarm types. These MUST be implemented by a system. The possible alarm types. These MUST be implemented by a system. The
rest of the data model are made conditional with YANG the features rest of the data model are made conditional with the YANG features
"operator-actions", "alarm-shelving", "alarm-history", "alarm- "operator-actions", "alarm-shelving", "alarm-history", "alarm-
summary", "alarm-profile", and "severity-assignment". summary", "alarm-profile", and "severity-assignment".
The data model has the following overall structure: The data model has the following overall structure:
+--rw control +--rw control
| +--rw max-alarm-status-changes? union | +--rw max-alarm-status-changes? union
| +--rw notify-status-changes? enumeration | +--rw notify-status-changes? enumeration
| +--rw notify-severity-level? severity | +--rw notify-severity-level? severity
| +--rw alarm-shelving {alarm-shelving}? | +--rw alarm-shelving {alarm-shelving}?
skipping to change at page 15, line 11 skipping to change at page 15, line 11
+--rw alarm-severity-assignment-profile +--rw alarm-severity-assignment-profile
{severity-assignment}? {severity-assignment}?
... ...
4.1. Alarm Control 4.1. Alarm Control
The "/alarms/control/notify-status-changes" leaf controls if The "/alarms/control/notify-status-changes" leaf controls if
notifications are sent for all state changes, only raise and clear, notifications are sent for all state changes, only raise and clear,
or only notifications more severe than a configured level. This or only notifications more severe than a configured level. This
feature in combination with alarm shelving corresponds to the ITU feature in combination with alarm shelving corresponds to the ITU
Alarm Report Control functionality. Alarm Report Control functionality, see Appendix F.2.4.
Every alarm has a list of status changes. The length of this list is Every alarm has a list of status changes. The length of this list is
controlled by "/alarms/control/max-alarm-status-changes". When the controlled by "/alarms/control/max-alarm-status-changes". When the
list is full and a new entry created, the oldest entry is removed. list is full and a new entry created, the oldest entry is removed.
4.1.1. Alarm Shelving 4.1.1. Alarm Shelving
The shelving control tree is shown below: The shelving control tree is shown below:
+--rw control +--rw control
+--rw alarm-shelving {alarm-shelving}? +--rw alarm-shelving {alarm-shelving}?
+--rw shelf* [name] +--rw shelf* [name]
+--rw name string +--rw name string
+--rw resource* resource-match +--rw resource* resource-match
+--rw alarm-type* +--rw alarm-type*
| [alarm-type-id alarm-type-qualifier-match] | [alarm-type-id alarm-type-qualifier-match]
| +--rw alarm-type-id alarm-type-id | +--rw alarm-type-id alarm-type-id
| +--rw alarm-type-qualifier-match string | +--rw alarm-type-qualifier-match string
+--rw description? string +--rw description? string
Shelved alarms are shown in a dedicated shelved alarm list. The Shelved alarms are shown in a dedicated shelved alarm list. Matching
instrumentation MUST move shelved alarms from the alarm list alarms MUST appear in the /alarms/shelved-alarms/shelved-alarm list,
(/alarms/alarm-list) to the shelved alarm list (/alarms/shelved- and non-matching /alarms MUST appear in the /alarms/alarm-list/alarm
alarms/). Shelved alarms do not generate any notifications. When list. The server does not send any notifications for shelved alarms.
the shelving criteria is removed or changed the alarm list MUST be
updated to the correct actual state of the alarms.
Shelving and unshelving can only be performed by editing the shelf Shelving and unshelving can only be performed by editing the shelf
configuration. It cannot be performed on individual alarms. The configuration. It cannot be performed on individual alarms. The
server will add an operator state indicating that the alarm was server will add an operator state indicating that the alarm was
shelved/unshelved. shelved/unshelved.
A leaf (/alarms/summary/shelves-active) in the alarm summary A leaf (/alarms/summary/shelves-active) in the alarm summary
indicates if there are shelved alarms. indicates if there are shelved alarms.
A system can select to not support the shelving feature. A system can select to not support the shelving feature.
4.2. Alarm Inventory 4.2. Alarm Inventory
The alarm inventory represents all possible alarm types that may The alarm inventory represents all possible alarm types that may
occur in the system. A management system may use this to build alarm occur in the system. A management system may use this to build alarm
procedures. The alarm inventory is relevant for several reasons: procedures. The alarm inventory is relevant for several reasons:
The system might not instrument all defined alarm type identities, The system might not implement all defined alarm type identities,
and some alarm identities are abstract. and some alarm identities are abstract.
The system has configured dynamic alarm types using the alarm The system has configured dynamic alarm types using the alarm
qualifier. The inventory makes it possible for the management qualifier. The inventory makes it possible for the management
system to discover these. system to discover these.
Note that the mechanism whereby dynamic alarm types are added using Note that the mechanism whereby dynamic alarm types are added using
the alarm type qualifier MUST populate this list. the alarm type qualifier MUST populate this list.
The optional leaf-list "resource" in the alarm inventory enables the The optional leaf-list "resource" in the alarm inventory enables the
skipping to change at page 17, line 23 skipping to change at page 17, line 23
| +--ro cleared-closed? yang:gauge32 | +--ro cleared-closed? yang:gauge32
| | {operator-actions}? | | {operator-actions}?
| +--ro not-cleared-closed? yang:gauge32 | +--ro not-cleared-closed? yang:gauge32
| | {operator-actions}? | | {operator-actions}?
| +--ro not-cleared-not-closed? yang:gauge32 | +--ro not-cleared-not-closed? yang:gauge32
| {operator-actions}? | {operator-actions}?
+--ro shelves-active? empty {alarm-shelving}? +--ro shelves-active? empty {alarm-shelving}?
4.4. The Alarm List 4.4. The Alarm List
The alarm list (/alarms/alarm-list) is a function from (resource, The alarm list (/alarms/alarm-list) is a function from the tuple
alarm type, alarm type qualifier) to the current composite alarm (resource, alarm type, alarm type qualifier) to the current composite
state. The composite state includes states for the resource life- alarm state. The composite state includes states for the resource
cycle such as severity, clearance flag and operator states such as lifecycle such as severity, clearance flag and operator states such
acknowledgment. This means that for a given resource and alarm-type as acknowledgment. This means that for a given resource and alarm
the alarm list shows the current states of the alarm such as type the alarm list shows the current states of the alarm such as
acknowledged and cleared status. acknowledged and cleared status.
+--ro alarm-list +--ro alarm-list
+--ro number-of-alarms? yang:gauge32 +--ro number-of-alarms? yang:gauge32
+--ro last-changed? yang:date-and-time +--ro last-changed? yang:date-and-time
+--ro alarm* [resource alarm-type-id alarm-type-qualifier] +--ro alarm* [resource alarm-type-id alarm-type-qualifier]
| +--ro resource resource | +--ro resource resource
| +--ro alarm-type-id alarm-type-id | +--ro alarm-type-id alarm-type-id
| +--ro alarm-type-qualifier alarm-type-qualifier | +--ro alarm-type-qualifier alarm-type-qualifier
| +--ro alt-resource* resource | +--ro alt-resource* resource
skipping to change at page 19, line 31 skipping to change at page 19, line 31
available in the "operator-state-change" list. available in the "operator-state-change" list.
4.5. The Shelved Alarms List 4.5. The Shelved Alarms List
The shelved alarm list has the same structure as the alarm list The shelved alarm list has the same structure as the alarm list
above. It shows all the alarms that matches the shelving criteria above. It shows all the alarms that matches the shelving criteria
(/alarms/control/alarm-shelving). (/alarms/control/alarm-shelving).
4.6. Alarm Profiles 4.6. Alarm Profiles
Alarm profiles (/alarms/alarm-profile/) is a list of configurable Alarm profiles (/alarms/alarm-profile) is a list of configurable
alarm types. The list supports configurable alarm severity levels in alarm types. The list supports configurable alarm severity levels in
the container "alarm-severity-assignment-profile". If an alarm the container "alarm-severity-assignment-profile". If an alarm
matches the configured alarm type it MUST use the configured severity matches the configured alarm type it MUST use the configured severity
level(s) instead of the system default. This configuration MUST also level(s) instead of the system default. This configuration MUST also
be represented in the alarm inventory. be represented in the alarm inventory.
+--rw alarm-profile* +--rw alarm-profile*
[alarm-type-id alarm-type-qualifier-match resource] [alarm-type-id alarm-type-qualifier-match resource]
{alarm-profile}? {alarm-profile}?
+--rw alarm-type-id alarm-type-id +--rw alarm-type-id alarm-type-id
skipping to change at page 21, line 18 skipping to change at page 21, line 18
perceived-severity: Corresponding bit set in perceived-severity: Corresponding bit set in
"/hardware/component/state/alarm-state". "/hardware/component/state/alarm-state".
operator-state-change/state: If the alarm is acknowledged by the operator-state-change/state: If the alarm is acknowledged by the
operator, the bit "under-repair" is in "/hardware/component/state/ operator, the bit "under-repair" is in "/hardware/component/state/
alarm-state". alarm-state".
6. Alarm YANG Module 6. Alarm YANG Module
This YANG module references [RFC6991]. This YANG module references [RFC6991] and [XSD-TYPES].
<CODE BEGINS> file "ietf-alarms@2019-03-21.yang" <CODE BEGINS> file "ietf-alarms@2019-04-10.yang"
module ietf-alarms { module ietf-alarms {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-alarms"; namespace "urn:ietf:params:xml:ns:yang:ietf-alarms";
prefix al; prefix al;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
reference reference
"RFC 6991: Common YANG Data Types."; "RFC 6991: Common YANG Data Types.";
} }
skipping to change at page 24, line 5 skipping to change at page 24, line 5
Relating to IETF Documents Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX This version of this YANG module is part of RFC XXXX
(https://tools.ietf.org/html/rfcXXXX); see the RFC itself for (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for
full legal notices."; full legal notices.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2019-03-21 { revision 2019-04-10 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: YANG Alarm Module"; "RFC XXXX: YANG Alarm Module";
} }
/* /*
* Features * Features
*/ */
skipping to change at page 25, line 24 skipping to change at page 25, line 24
feature root-cause-analysis { feature root-cause-analysis {
description description
"The system supports identifying candidate root-cause "The system supports identifying candidate root-cause
resources for an alarm, for example a disc partition resources for an alarm, for example a disc partition
root cause for a logger failure alarm."; root cause for a logger failure alarm.";
} }
feature service-impact-analysis { feature service-impact-analysis {
description description
"The system supports identifying candidate impacted "The system supports identifying candidate impacted
resources for an alarm, for example a link being impacted resources for an alarm. For example, an interface state change
by an interface alarm."; resulting in a link alarm which can refer to a link as being
impacted.";
} }
feature alarm-correlation { feature alarm-correlation {
description description
"The system supports correlating/grouping alarms "The system supports correlating/grouping alarms
that belong together."; that belong together.";
} }
/* /*
* Identities * Identities
skipping to change at page 26, line 29 skipping to change at page 26, line 29
} }
type yang:object-identifier; type yang:object-identifier;
type string; type string;
type yang:uuid; type yang:uuid;
} }
description description
"This is an identification of the alarming resource, such as an "This is an identification of the alarming resource, such as an
interface. It should be as fine-grained as possible both to interface. It should be as fine-grained as possible both to
guide the operator and to guarantee uniqueness of the alarms. guide the operator and to guarantee uniqueness of the alarms.
If the alarming resource is modelled in YANG, this type will If the alarming resource is modeled in YANG, this type will
be an instance-identifier. be an instance-identifier.
If the resource is an SNMP object, the type will be an If the resource is an SNMP object, the type will be an
object-identifier. object-identifier.
If the resource is anything else, for example a distinguished If the resource is anything else, for example a distinguished
name or a CIM path, this type will be a string. name or a CIM path, this type will be a string.
If the alarming object is identified by a UUID use the uuid If the alarming object is identified by a UUID use the uuid
type. Be cautious when using this type, since a UUID is hard type. Be cautious when using this type, since a UUID is hard
skipping to change at page 27, line 35 skipping to change at page 27, line 35
identifier is a prefix of the resource's object identifier. identifier is a prefix of the resource's object identifier.
For example, the value: For example, the value:
1.3.6.1.2.1.2.2 1.3.6.1.2.1.2.2
would match the resource object identifier: would match the resource object identifier:
1.3.6.1.2.1.2.2.1.1.5 1.3.6.1.2.1.2.2.1.1.5
If the type is given as an UUID or a string, it is interpreted If the type is given as an UUID or a string, it is interpreted
as a W3C regular expression, which matches a resource of type as an XML Schema regular expression, which matches a resource
'yang:uuid' or 'string' if the given regular expression of type 'yang:uuid' or 'string' if the given regular
matches the resource string. expression matches the resource string.
If the type is given as an XPath expression it is evaluated If the type is given as an XPath expression it is evaluated
in the following XPath context: in the following XPath context:
o The set of namespace declarations is the set of prefix o The set of namespace declarations is the set of prefix
and namespace pairs for all YANG modules implemented by and namespace pairs for all YANG modules implemented by
the server, where the prefix is the YANG module name and the server, where the prefix is the YANG module name and
the namespace is as defined by the 'namespace' statement the namespace is as defined by the 'namespace' statement
in the YANG module. in the YANG module.
skipping to change at page 28, line 12 skipping to change at page 28, line 12
the set of namespace declarations. If a prefix found in the set of namespace declarations. If a prefix found in
the XML is already present in the set of namespace the XML is already present in the set of namespace
declarations, the namespace in the XML is used. declarations, the namespace in the XML is used.
o The set of variable bindings is empty. o The set of variable bindings is empty.
o The function library is the core function library o The function library is the core function library
and the functions defined in Section 10 of RFC 7950. and the functions defined in Section 10 of RFC 7950.
o The context node is the root node in the data tree."; o The context node is the root node in the data tree.";
reference
"XML Schema Part 2: Datatypes Second Edition,
World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028";
} }
typedef alarm-text { typedef alarm-text {
type string; type string;
description description
"The string used to inform operators about the alarm. This "The string used to inform operators about the alarm. This
MUST contain enough information for an operator to be able to MUST contain enough information for an operator to be able to
understand the problem and how to resolve it. If this string understand the problem and how to resolve it. If this string
contains structure, this format should be clearly documented contains structure, this format should be clearly documented
for programs to be able to parse that information."; for programs to be able to parse that information.";
skipping to change at page 32, line 24 skipping to change at page 32, line 27
type alarm-type-qualifier; type alarm-type-qualifier;
description description
"This leaf is used when the 'alarm-type-id' leaf cannot "This leaf is used when the 'alarm-type-id' leaf cannot
uniquely identify the alarm type. Normally, this is not the uniquely identify the alarm type. Normally, this is not the
case, and this leaf is the empty string."; case, and this leaf is the empty string.";
} }
leaf-list alt-resource { leaf-list alt-resource {
type resource; type resource;
description description
"Used if the alarming resource is available over other "Used if the alarming resource is available over other
interfaces. This field can contain SNMP OID's, CIM paths or interfaces. This field can contain SNMP OIDs, CIM paths or
3GPP Distinguished names for example."; 3GPP Distinguished names for example.";
} }
list related-alarm { list related-alarm {
if-feature "alarm-correlation"; if-feature "alarm-correlation";
key "resource alarm-type-id alarm-type-qualifier"; key "resource alarm-type-id alarm-type-qualifier";
description description
"References to related alarms. Note that the related alarm "References to related alarms. Note that the related alarm
might have been purged from the alarm list."; might have been purged from the alarm list.";
leaf resource { leaf resource {
type leafref { type leafref {
skipping to change at page 35, line 43 skipping to change at page 35, line 46
mandatory true; mandatory true;
description description
"An alarm may change severity level and toggle between "An alarm may change severity level and toggle between
active and cleared during its life-time. This leaf indicates active and cleared during its life-time. This leaf indicates
the last time it was last raised (is-cleared = false)."; the last time it was last raised (is-cleared = false).";
} }
leaf last-changed { leaf last-changed {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
description description
"A timestamp when the alarm status was last changed. Status "A timestamp when the 'status-change' or
changes are changes to 'is-cleared', 'perceived-severity', 'operator-state-change' list was last changed.";
and 'alarm-text'.";
} }
leaf perceived-severity { leaf perceived-severity {
type severity; type severity;
mandatory true; mandatory true;
description description
"The last severity of the alarm. "The last severity of the alarm.
If an alarm was raised with severity 'warning', but later If an alarm was raised with severity 'warning', but later
changed to 'major', this leaf will show 'major'."; changed to 'major', this leaf will show 'major'.";
} }
skipping to change at page 36, line 25 skipping to change at page 36, line 27
} }
list status-change { list status-change {
if-feature "alarm-history"; if-feature "alarm-history";
key "time"; key "time";
min-elements 1; min-elements 1;
description description
"A list of status change events for this alarm. "A list of status change events for this alarm.
The entry with latest time-stamp in this list MUST The entry with latest time-stamp in this list MUST
correspond to the leafs 'is-cleared', 'perceived-severity' correspond to the leafs 'is-cleared', 'perceived-severity'
and 'alarm-text' for the alarm. The time-stamp for that and 'alarm-text' for the alarm.
entry MUST be equal to the 'last-changed' leaf.
This list is ordered according to the timestamps of alarm This list is ordered according to the timestamps of alarm
state changes. The last item corresponds to the latest state changes. The first item corresponds to the latest
state change. state change.
The following state changes creates an entry in this The following state changes creates an entry in this
list: list:
- changed severity (warning, minor, major, critical) - changed severity (warning, minor, major, critical)
- clearance status, this also updates the 'is-cleared' - clearance status, this also updates the 'is-cleared'
leaf leaf
- alarm text update"; - alarm text update";
uses alarm-state-change-parameters; uses alarm-state-change-parameters;
} }
skipping to change at page 37, line 26 skipping to change at page 37, line 28
presence "Age specification"; presence "Age specification";
description description
"Matches the 'last-status-change' leaf in the alarm."; "Matches the 'last-status-change' leaf in the alarm.";
choice age-spec { choice age-spec {
description description
"Filter using date and time age."; "Filter using date and time age.";
case seconds { case seconds {
leaf seconds { leaf seconds {
type uint16; type uint16;
description description
"Seconds part"; "Age expressed in seconds.";
} }
} }
case minutes { case minutes {
leaf minutes { leaf minutes {
type uint16; type uint16;
description description
"Minute part"; "Age expressed in minutes.";
} }
} }
case hours { case hours {
leaf hours { leaf hours {
type uint16; type uint16;
description description
"Hours part."; "Age expressed in hours.";
} }
} }
case days { case days {
leaf days { leaf days {
type uint16; type uint16;
description description
"Day part"; "Age expressed in days.";
} }
} }
case weeks { case weeks {
leaf weeks { leaf weeks {
type uint16; type uint16;
description description
"Week part"; "Age expressed in weeks.";
} }
} }
} }
} }
container severity { container severity {
presence "Severity filter"; presence "Severity filter";
choice sev-spec { choice sev-spec {
description description
"Filter based on severity level."; "Filter based on severity level.";
leaf below { leaf below {
skipping to change at page 38, line 50 skipping to change at page 39, line 4
description description
"Filter on operator state."; "Filter on operator state.";
} }
leaf user { leaf user {
type string; type string;
description description
"Filter based on which operator."; "Filter based on which operator.";
} }
description description
"Filter based on operator state."; "Filter based on operator state.";
} }
} }
/* /*
* The /alarms data tree * The /alarms data tree
*/ */
container alarms { container alarms {
description description
"The top container for this module."; "The top container for this module.";
container control { container control {
description description
"Configuration to control the alarm behaviour."; "Configuration to control the alarm behavior.";
leaf max-alarm-status-changes { leaf max-alarm-status-changes {
type union { type union {
type uint16; type uint16;
type enumeration { type enumeration {
enum infinite { enum infinite {
description description
"The status change entries are accumulated "The status change entries are accumulated
infinitely."; infinitely.";
} }
} }
skipping to change at page 40, line 50 skipping to change at page 41, line 4
when '../notify-status-changes = "severity-level"'; when '../notify-status-changes = "severity-level"';
type severity; type severity;
description description
"Only send notifications for alarm state changes crossing "Only send notifications for alarm state changes crossing
the specified level. Always send clear notifications."; the specified level. Always send clear notifications.";
} }
container alarm-shelving { container alarm-shelving {
if-feature "alarm-shelving"; if-feature "alarm-shelving";
description description
"The alarm-shelving/shelf list is used to shelve "The alarm-shelving/shelf list is used to shelve
(block/filter) alarms. The first matching shelf is used, (block/filter) alarms. The conditions in the shelf
and an alarm is shelved only for this first match. criteria are logically ANDed. The first matching shelf is
The server will move any alarms corresponding to the used, and an alarm is shelved only for this first match.
shelving criteria from the Matching alarms MUST appear in the
alarms/alarm-list/alarm list to the /alarms/shelved-alarms/shelved-alarm list, and
alarms/shelved-alarms/shelved-alarm list. It will also non-matching /alarms MUST appear in the
stop sending notifications for the shelved alarms. The /alarms/alarm-list/alarm list. The server does not send
conditions in the shelf criteria are logically ANDed. any notifications for shelved alarms.
When the shelving criteria is deleted or changed, the
non-matching alarms MUST appear in the
alarms/alarm-list/alarm list according to the real state.
This means that the instrumentation MUST maintain states The server MUST maintain states (e.g., severity
for the shelved alarms. Alarms that match the criteria changes) for the shelved alarms.
shall have an operator-state 'shelved'. When the shelf
configuration removes an alarm from the shelf the Alarms that match the criteria shall have an
server shall add an operator state 'unshelved'."; operator state 'shelved'. When the shelf
configuration removes an alarm from the shelf the server
shall add an operator state 'un-shelved'.";
list shelf { list shelf {
key "name"; key "name";
ordered-by user; ordered-by user;
leaf name { leaf name {
type string; type string;
description description
"An arbitrary name for the alarm shelf."; "An arbitrary name for the alarm shelf.";
} }
description description
"Each entry defines the criteria for shelving alarms. "Each entry defines the criteria for shelving alarms.
skipping to change at page 41, line 50 skipping to change at page 42, line 4
MUST be matched."; MUST be matched.";
leaf alarm-type-id { leaf alarm-type-id {
type alarm-type-id; type alarm-type-id;
description description
"Shelve all alarms that have an alarm-type-id that is "Shelve all alarms that have an alarm-type-id that is
equal to or derived from the given alarm-type-id."; equal to or derived from the given alarm-type-id.";
} }
leaf alarm-type-qualifier-match { leaf alarm-type-qualifier-match {
type string; type string;
description description
"A W3C regular expression that is used to match an "An XML Schema regular expression that is used to
alarm type qualifier. Shelve all alarms that match an alarm type qualifier. Shelve all alarms
matches this regular expression for the alarm type that matches this regular expression for the alarm
qualifier."; type qualifier.";
reference
"XML Schema Part 2: Datatypes Second Edition,
World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028";
} }
} }
leaf description { leaf description {
type string; type string;
description description
"An optional textual description of the shelf. This "An optional textual description of the shelf. This
description should include the reason for shelving description should include the reason for shelving
these alarms."; these alarms.";
} }
} }
skipping to change at page 45, line 22 skipping to change at page 45, line 28
"For this severity level, the number of alarms that are "For this severity level, the number of alarms that are
not cleared and not closed."; not cleared and not closed.";
} }
} }
leaf shelves-active { leaf shelves-active {
if-feature "alarm-shelving"; if-feature "alarm-shelving";
type empty; type empty;
description description
"This is a hint to the operator that there are active "This is a hint to the operator that there are active
alarm shelves. This leaf MUST exist if the alarm shelves. This leaf MUST exist if the
alarms/shelved-alarms/number-of-shelved-alarms is > 0."; /alarms/shelved-alarms/number-of-shelved-alarms is > 0.";
} }
} }
container alarm-list { container alarm-list {
config false; config false;
description description
"The alarms in the system."; "The alarms in the system.";
leaf number-of-alarms { leaf number-of-alarms {
type yang:gauge32; type yang:gauge32;
description description
"This object shows the total number of "This object shows the total number of
skipping to change at page 46, line 8 skipping to change at page 46, line 14
"The list of alarms. Each entry in the list holds one "The list of alarms. Each entry in the list holds one
alarm for a given alarm type and resource. An alarm can alarm for a given alarm type and resource. An alarm can
be updated from the underlying resource or by the user. be updated from the underlying resource or by the user.
The following leafs are maintained by the resource: The following leafs are maintained by the resource:
is-cleared, last-change, perceived-severity, and is-cleared, last-change, perceived-severity, and
alarm-text. An operator can change: operator-state and alarm-text. An operator can change: operator-state and
operator-text. operator-text.
Entries appear in the alarm list the first time an alarm Entries appear in the alarm list the first time an alarm
becomes active for a given alarm-type and resource. becomes active for a given alarm-type and resource.
Entries do not get deleted when the alarm is cleared, this Entries do not get deleted when the alarm is cleared.
is a boolean state in the alarm. Clear status is represented as a boolean flag.
Alarm entries are removed, purged, from the list by an Alarm entries are removed, purged, from the list by an
explicit purge action. For example, purge all alarms that explicit purge action. For example, purge all alarms that
are cleared and in closed operator-state that are older are cleared and in closed operator-state that are older
than 24 hours. Purged alarms are removed from the alarm than 24 hours. Purged alarms are removed from the alarm
list. If the alarm resource state changes after a purge, list. If the alarm resource state changes after a purge,
the alarm will reappear in the alarm list. the alarm will reappear in the alarm list.
Systems may also remove alarms based on locally configured Systems may also remove alarms based on locally configured
policies which is out of scope for this module."; policies which is out of scope for this module.";
skipping to change at page 51, line 27 skipping to change at page 51, line 33
alarm severity levels. The alarm-profile is also a useful alarm severity levels. The alarm-profile is also a useful
augmentation point for specific additions to alarm types."; augmentation point for specific additions to alarm types.";
leaf alarm-type-id { leaf alarm-type-id {
type alarm-type-id; type alarm-type-id;
description description
"The alarm type identifier to match."; "The alarm type identifier to match.";
} }
leaf alarm-type-qualifier-match { leaf alarm-type-qualifier-match {
type string; type string;
description description
"A W3C regular expression that is used to match the alarm "An XML Schema regular expression that is used to match the
type qualifier."; alarm type qualifier.";
reference
"XML Schema Part 2: Datatypes Second Edition,
World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028";
} }
leaf resource { leaf resource {
type resource-match; type resource-match;
description description
"Specifies which resources to match."; "Specifies which resources to match.";
} }
leaf description { leaf description {
type string; type string;
mandatory true; mandatory true;
description description
skipping to change at page 52, line 15 skipping to change at page 52, line 24
description description
"Specifies the configured severity level(s) for the "Specifies the configured severity level(s) for the
matching alarm. If the alarm has several severity matching alarm. If the alarm has several severity
levels the leaf-list shall be given in rising severity levels the leaf-list shall be given in rising severity
order. The original M3100/M3160 ASAP function only order. The original M3100/M3160 ASAP function only
allows for a one-to-one mapping between alarm type and allows for a one-to-one mapping between alarm type and
severity but since the IETF alarm module supports severity but since the IETF alarm module supports
stateful alarms the mapping must allow for several stateful alarms the mapping must allow for several
severity levels. severity levels.
Assume a high-utilisation alarm type with two thresholds Assume a high-utilization alarm type with two thresholds
with the system default severity levels of threshold1 = with the system default severity levels of threshold1 =
warning and threshold2 = minor. Setting this leaf-list warning and threshold2 = minor. Setting this leaf-list
to (minor, major) will assign the severity levels to (minor, major) will assign the severity levels
threshold1 = minor and threshold2 = major"; threshold1 = minor and threshold2 = major";
} }
} }
} }
} }
/* /*
skipping to change at page 53, line 12 skipping to change at page 53, line 18
<CODE ENDS> <CODE ENDS>
7. X.733 Extensions 7. X.733 Extensions
Many alarm systems are based on the X.733, [X.733], and X.736 [X.736] Many alarm systems are based on the X.733, [X.733], and X.736 [X.736]
alarm standards. This module augments the alarm inventory, the alarm alarm standards. This module augments the alarm inventory, the alarm
lists and the alarm notification with X.733 and X.736 parameters. lists and the alarm notification with X.733 and X.736 parameters.
The module also supports a feature whereby the alarm manager can The module also supports a feature whereby the alarm manager can
configure the mapping from alarm types to X.733 event-type and configure the mapping from alarm types to X.733 "event-type" and
probable-cause parameters. This might be needed when the default "probable-cause" parameters. This might be needed when the default
mapping provided by the system is in conflict with other management mapping provided by the system is in conflict with other management
systems or not considered correct. systems or not considered correct.
Note that the IETF Alarm Module term 'resource' is synonymous to the Note that the IETF Alarm Module term "resource" is synonymous to the
ITU term 'managed object'. ITU term "managed object".
8. The X.733 Mapping Module 8. The X.733 Mapping Module
This YANG module references [X.721], [X.733] and [X.736]. This YANG module references [X.721], [X.733] and [X.736].
<CODE BEGINS> file "ietf-alarms-x733@2019-03-21.yang" <CODE BEGINS> file "ietf-alarms-x733@2019-03-21.yang"
module ietf-alarms-x733 { module ietf-alarms-x733 {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-alarms-x733"; namespace "urn:ietf:params:xml:ns:yang:ietf-alarms-x733";
prefix x733; prefix x733;
skipping to change at page 65, line 47 skipping to change at page 66, line 5
is the secure transport layer, and the mandatory-to-implement secure is the secure transport layer, and the mandatory-to-implement secure
transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
is HTTPS, and the mandatory-to-implement secure transport is TLS is HTTPS, and the mandatory-to-implement secure transport is TLS
[RFC8446]. [RFC8446].
The Network Configuration Access Control model (NACM) [RFC8341] The Network Configuration Access Control model (NACM) [RFC8341]
provides the means to restrict access for particular NETCONF or provides the means to restrict access for particular NETCONF or
RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or
RESTCONF protocol operations and content. RESTCONF protocol operations and content.
The list of alarms itself may be potentially sensitive from a
security perspective, in that it potentially gives an attacker an
authoritative picture of the (broken) state of the network.
There are a number of data nodes defined in this YANG module that are There are a number of data nodes defined in this YANG module that are
writable/creatable/deletable (i.e., config true, which is the writable/creatable/deletable (i.e., config true, which is the
default). These data nodes may be considered sensitive or vulnerable default). These data nodes may be considered sensitive or vulnerable
in some network environments. Write operations (e.g., edit-config) in some network environments. Write operations (e.g., edit-config)
to these data nodes without proper protection can have a negative to these data nodes without proper protection can have a negative
effect on network operations. These are the subtrees and data nodes effect on network operations. These are the subtrees and data nodes
and their sensitivity/vulnerability: and their sensitivity/vulnerability:
/alarms/control/notify-status-changes: This leaf controls whether an /alarms/control/notify-status-changes: This leaf controls whether an
alarm should notify based on various state changes. Unauthorized alarm should notify based on various state changes. Unauthorized
skipping to change at page 66, line 33 skipping to change at page 66, line 43
Some of the operations in this YANG module may be considered Some of the operations in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus sensitive or vulnerable in some network environments. It is thus
important to control access to these operations. These are the important to control access to these operations. These are the
operations and their sensitivity/vulnerability: operations and their sensitivity/vulnerability:
/alarms/alarm-list/purge-alarms: This action deletes alarms from the /alarms/alarm-list/purge-alarms: This action deletes alarms from the
alarm list. Unauthorized use of this action could jeopardize the alarm list. Unauthorized use of this action could jeopardize the
alarm management procedures since the deleted alarms may be vital alarm management procedures since the deleted alarms may be vital
for the alarm management application. for the alarm management application.
/alarms/alarm-list/alarm/set-operator-state: This action can be used
by the operator to indicate the level of human intervention on an
alarm. Unauthorized use of this action could result in alarms
being ignored by operators.
11. Acknowledgements 11. Acknowledgements
The authors wish to thank Viktor Leijon and Johan Nordlander for The authors wish to thank Viktor Leijon and Johan Nordlander for
their valuable input on forming the alarm model. their valuable input on forming the alarm model.
The authors also wish to thank Nick Hancock, Joey Boyd, Tom Petch and The authors also wish to thank Nick Hancock, Joey Boyd, Tom Petch and
Balazs Lengyel for their extensive reviews and contributions to this Balazs Lengyel for their extensive reviews and contributions to this
document. document.
12. References 12. References
12.1. Normative References 12.1. Normative References
[M.3100] International Telecommunications Union, "Generic Network [M.3100] International Telecommunications Union, "Generic Network
Information Model", ITU-T Recommendation M.3100, 2005. Information Model", ITU-T Recommendation M.3100, 2005.
[M.3160] International Telecommunications Union, "Generic, [M.3160] International Telecommunications Union, "Generic,
protocol-neutral management information model", ITU-T protocol-neutral management information model",
Recommendation M.3100, 2008. ITU-T Recommendation M.3100, 2008.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119,
RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<http://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020, the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010, DOI 10.17487/RFC6020, October 2010,
<http://www.rfc-editor.org/info/rfc6020>. <https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<http://www.rfc-editor.org/info/rfc6241>. <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>. <https://www.rfc-editor.org/info/rfc6242>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
6991, DOI 10.17487/RFC6991, July 2013, RFC 6991, DOI 10.17487/RFC6991, July 2013,
<http://www.rfc-editor.org/info/rfc6991>. <https://www.rfc-editor.org/info/rfc6991>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016, RFC 7950, DOI 10.17487/RFC7950, August 2016,
<http://www.rfc-editor.org/info/rfc7950>. <https://www.rfc-editor.org/info/rfc7950>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<http://www.rfc-editor.org/info/rfc8040>. <https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341, DOI 10.17487/ Access Control Model", STD 91, RFC 8341,
RFC8341, March 2018, <https://www.rfc-editor.org/info/ DOI 10.17487/RFC8341, March 2018,
rfc8341>. <https://www.rfc-editor.org/info/rfc8341>.
[RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A
YANG Data Model for Hardware Management", RFC 8348, DOI YANG Data Model for Hardware Management", RFC 8348,
10.17487/RFC8348, March 2018, <https://www.rfc- DOI 10.17487/RFC8348, March 2018,
editor.org/info/rfc8348>. <https://www.rfc-editor.org/info/rfc8348>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[X.721] International Telecommunications Union, "Information [X.721] International Telecommunications Union, "Information
Technology - Open Systems Interconnection - Structure of Technology - Open Systems Interconnection - Structure of
management information: Definition of management management information: Definition of management
information", ITU-T Recommendation X.721, 1992. information", ITU-T Recommendation X.721, 1992.
[X.733] International Telecommunications Union, "Information [X.733] International Telecommunications Union, "Information
Technology - Open Systems Interconnection - Systems Technology - Open Systems Interconnection - Systems
Management: Alarm Reporting Function", ITU-T Management: Alarm Reporting Function",
Recommendation X.733, 1992. ITU-T Recommendation X.733, 1992.
[XSD-TYPES]
Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
12.2. Informative References 12.2. Informative References
[ALARMIRP] [ALARMIRP]
3GPP, "Telecommunication management; Fault Management; 3GPP, "Telecommunication management; Fault Management;
Part 2: Alarm Integration Reference Point (IRP): Part 2: Alarm Integration Reference Point (IRP):
Information Service (IS)", 3GPP TS 32.111-2 3.4.0, March Information Service (IS)", 3GPP TS 32.111-2 3.4.0, March
2005. 2005.
[ALARMSEM] [ALARMSEM]
skipping to change at page 68, line 46 skipping to change at page 69, line 24
Systems: A Guide to Design, Management and Procurement.", Systems: A Guide to Design, Management and Procurement.",
2007. 2007.
[G.7710] ITU-T, "SERIES G: TRANSMISSION SYSTEMS AND MEDIA, DIGITAL [G.7710] ITU-T, "SERIES G: TRANSMISSION SYSTEMS AND MEDIA, DIGITAL
SYSTEMS AND NETWORKS Data over Transport - Generic aspects SYSTEMS AND NETWORKS Data over Transport - Generic aspects
- Transport network control aspects. Common equipment - Transport network control aspects. Common equipment
management function requirements", 2012. management function requirements", 2012.
[I-D.ietf-netmod-yang-instance-file-format] [I-D.ietf-netmod-yang-instance-file-format]
Lengyel, B. and B. Claise, "YANG Instance Data File Lengyel, B. and B. Claise, "YANG Instance Data File
Format", draft-ietf-netmod-yang-instance-file-format-00 Format", draft-ietf-netmod-yang-instance-file-format-02
(work in progress), November 2018. (work in progress), February 2019.
[ISA182] International Society of Automation,ISA, "ANSI/ISA- [ISA182] International Society of Automation,ISA, "ANSI/ISA-
18.2-2009 Management of Alarm Systems for the Process 18.2-2009 Management of Alarm Systems for the Process
Industries", 2009. Industries", 2009.
[RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management [RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management
Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877, Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877,
September 2004, <http://www.rfc-editor.org/info/rfc3877>. September 2004, <https://www.rfc-editor.org/info/rfc3877>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>. <https://www.rfc-editor.org/info/rfc8340>.
[X.736] International Telecommunications Union, "Information [X.736] International Telecommunications Union, "Information
Technology - Open Systems Interconnection - Systems Technology - Open Systems Interconnection - Systems
Management: Security alarm reporting function", ITU-T Management: Security alarm reporting function",
Recommendation X.736, 1992. ITU-T Recommendation X.736, 1992.
Appendix A. Vendor-specific Alarm-Types Example Appendix A. Vendor-specific Alarm Types Example
This example shows how to define alarm-types in a vendor-specific This example shows how to define alarm types in a vendor-specific
module. In this case the vendor "xyz" has chosen to define top level module. In this case the vendor "xyz" has chosen to define top level
identities according to X.733 event types. identities according to X.733 event types.
module example-xyz-alarms { module example-xyz-alarms {
namespace "urn:example:xyz-alarms"; namespace "urn:example:xyz-alarms";
prefix xyz-al; prefix xyz-al;
import ietf-alarms { import ietf-alarms {
prefix al; prefix al;
} }
skipping to change at page 70, line 49 skipping to change at page 70, line 49
identity high-jitter-alarm { identity high-jitter-alarm {
base quality-of-service-alarm; base quality-of-service-alarm;
} }
} }
Appendix B. Alarm Inventory Example Appendix B. Alarm Inventory Example
This shows an alarm inventory, it shows one alarm type defined only This shows an alarm inventory, it shows one alarm type defined only
with the identifier, and another dynamically configured. In the with the identifier, and another dynamically configured. In the
latter case a digital input has been connected to a smoke-detector, latter case a digital input has been connected to a smoke-detector,
therefore the 'alarm-type-qualifier' is set to "smoke-detector" and therefore the "alarm-type-qualifier" is set to "smoke-detector" and
the 'alarm-type-identity' to "environmental-alarm". the "alarm-type-id" to "environmental-alarm".
<alarms xmlns="urn:ietf:params:xml:ns:yang:ietf-alarms" <alarms xmlns="urn:ietf:params:xml:ns:yang:ietf-alarms"
xmlns:xyz-al="urn:example:xyz-alarms" xmlns:xyz-al="urn:example:xyz-alarms"
xmlns:dev="urn:example:device"> xmlns:dev="urn:example:device">
<alarm-inventory> <alarm-inventory>
<alarm-type> <alarm-type>
<alarm-type-id>xyz-al:link-alarm</alarm-type-id> <alarm-type-id>xyz-al:link-alarm</alarm-type-id>
<alarm-type-qualifier/> <alarm-type-qualifier/>
<resource> <resource>
/dev:interfaces/dev:interface /dev:interfaces/dev:interface
skipping to change at page 73, line 34 skipping to change at page 73, line 34
</alarm-type-qualifier-match> </alarm-type-qualifier-match>
</alarm-type> </alarm-type>
</shelf> </shelf>
</alarm-shelving> </alarm-shelving>
</control> </control>
</alarms> </alarms>
Appendix E. X.733 Mapping Example Appendix E. X.733 Mapping Example
This example shows how to map a dynamic alarm type (alarm-type- This example shows how to map a dynamic alarm type (alarm-type-
identity=environmental-alarm, alarm-type-qualifier=smoke-alarm) to id=environmental-alarm, alarm-type-qualifier=smoke-alarm) to the
the corresponding X.733 event-type and probable cause parameters. corresponding X.733 "event-type" and "probable-cause" parameters.
<alarms xmlns="urn:ietf:params:xml:ns:yang:ietf-alarms" <alarms xmlns="urn:ietf:params:xml:ns:yang:ietf-alarms"
xmlns:xyz-al="urn:example:xyz-alarms"> xmlns:xyz-al="urn:example:xyz-alarms">
<control> <control>
<x733-mapping <x733-mapping
xmlns="urn:ietf:params:xml:ns:yang:ietf-alarms-x733"> xmlns="urn:ietf:params:xml:ns:yang:ietf-alarms-x733">
<alarm-type-id>xyz-al:environmental-alarm</alarm-type-id> <alarm-type-id>xyz-al:environmental-alarm</alarm-type-id>
<alarm-type-qualifier-match> <alarm-type-qualifier-match>
smoke-alarm smoke-alarm
</alarm-type-qualifier-match> </alarm-type-qualifier-match>
skipping to change at page 74, line 21 skipping to change at page 74, line 21
The table below summarizes relevant definitions of the term "alarm" The table below summarizes relevant definitions of the term "alarm"
in other alarm standards. in other alarm standards.
+------------+---------------------------+--------------------------+ +------------+---------------------------+--------------------------+
| Standard | Definition | Comment | | Standard | Definition | Comment |
+------------+---------------------------+--------------------------+ +------------+---------------------------+--------------------------+
| X.733 | error: A deviation of a | The X.733 alarm | | X.733 | error: A deviation of a | The X.733 alarm |
| [X.733] | system from normal | definition is focused on | | [X.733] | system from normal | definition is focused on |
| | operation. fault: The | the notification as such | | | operation. fault: The | the notification as such |
| | physical or algorithmic | and not the state. It | | | physical or algorithmic | and not the state. X.733 |
| | cause of a malfunction. | also uses the basic | | | cause of a malfunction. | defines an alarm as a |
| | Faults manifest | criteria of deviation | | | Faults manifest | deviation from normal |
| | themselves as errors. | from normal condition. | | | themselves as errors. | condition, but without |
| | alarm: A notification, of | There is no requirement | | | alarm: A notification, of | the requirement that it |
| | the form defined by this | for an operation action | | | the form defined by this | needs corrective |
| | function, of a specific | to be required. | | | function, of a specific | actions. |
| | event. An alarm may or | | | | event. An alarm may or | |
| | may not represent an | | | | may not represent an | |
| | error. | | | | error. | |
| | | | | | | |
| G.7710 | Alarms are indications | The G.7710 definition is | | G.7710 | Alarms are indications | The G.7710 definition is |
| [G.7710] | that are automatically | close to the original | | [G.7710] | that are automatically | close to the original |
| | generated by an NE as a | X.733 definition. | | | generated by a device as | X.733 definition. |
| | result of the declaration | | | | a result of the | |
| | of a failure. | | | | declaration of a failure. | |
| | | | | | | |
| Alarm MIB | Alarm: Persistent | RFC 3877 defines the | | Alarm MIB | Alarm: Persistent | RFC 3877 defines the |
| [RFC3877] | indication of a fault. | term alarm referring | | [RFC3877] | indication of a fault. | term alarm referring |
| | Fault: Lasting error or | back to "a deviation | | | Fault: Lasting error or | back to "a deviation |
| | warning condition. | from normal operation". | | | warning condition. | from normal operation". |
| | Error: A deviation of a | The Alarm YANG model | | | Error: A deviation of a | The Alarm YANG model |
| | system from normal | adds the requirement | | | system from normal | adds the requirement |
| | operation. | that it should require a | | | operation. | that it should require a |
| | | corrective action and | | | | corrective action and |
| | | should be undesired, not | | | | should be undesired, not |
skipping to change at page 75, line 10 skipping to change at page 75, line 10
| | | is state oriented in the | | | | is state oriented in the |
| | | same way as the Alarm | | | | same way as the Alarm |
| | | YANG, it focuses on the | | | | YANG, it focuses on the |
| | | "lasting condition", | | | | "lasting condition", |
| | | not the individual | | | | not the individual |
| | | notifications. | | | | notifications. |
| | | | | | | |
| ISA | Alarm: An audible and/or | The ISA standard adds an | | ISA | Alarm: An audible and/or | The ISA standard adds an |
| [ISA182] | visible means of | important requirement to | | [ISA182] | visible means of | important requirement to |
| | indicating to the | the "deviation from | | | indicating to the | the "deviation from |
| | operator an equipment | normal condition state"; | | | operator an equipment | normal condition state": |
| | malfunction, process | requiring a response. | | | malfunction, process | requiring a response. |
| | deviation or abnormal | | | | deviation or abnormal | |
| | condition requiring a | | | | condition requiring a | |
| | response. | | | | response. | |
| | | | | | | |
| EEMUA | An alarm is an event to | This is the foundation | | EEMUA | An alarm is an event to | This is the foundation |
| [EEMUA] | which an operator must | for the definition of | | [EEMUA] | which an operator must | for the definition of |
| | knowingly react,respond, | alarm in this document. | | | knowingly react,respond, | alarm in this document. |
| | and acknowledge - not | It focuses on the core | | | and acknowledge - not | It focuses on the core |
| | simply acknowledge and | criteria that an action | | | simply acknowledge and | criteria that an action |
| | ignore. | is really needed. | | | ignore. | is really needed. |
| | | | | | | |
| 3GPP Alarm | 3GPP v15: An alarm | The latest 3GPP Alarm | | 3GPP Alarm | 3GPP v15: An alarm | The latest 3GPP Alarm |
| IRP | signifies an undesired | IRP version uses | | IRP | signifies an undesired | IRP version uses |
| [ALARMIRP] | condition of a resource | literally the same alarm | | [ALARMIRP] | condition of a resource | literally the same alarm |
| | (e.g. network element, | definition as this alarm | | | (e.g. device, link) for | definition as this alarm |
| | link) for which an | module. It is worth | | | which an operator action | module. It is worth |
| | operator action is | noting that earlier | | | is required. It | noting that earlier |
| | required. It emphasizes a | versions used a | | | emphasizes a key | versions used a |
| | key requirement that | definition not requiring | | | requirement that | definition not requiring |
| | operators [...] should | an operator action and | | | operators [...] should | an operator action and |
| | not be informed about an | the more broad | | | not be informed about an | the more broad |
| | undesired condition | definition of deviation | | | undesired condition | definition of deviation |
| | unless it requires | from normal condition. | | | unless it requires | from normal condition. |
| | operator action. 3GPP | The earlier version also | | | operator action. 3GPP | The earlier version also |
| | v12: alarm: abnormal | defined an alarm as a | | | v12: alarm: abnormal | defined an alarm as a |
| | network entity condition, | special case of "event". | | | network entity condition, | special case of "event". |
| | which categorizes an | | | | which categorizes an | |
| | event as a fault. fault: | | | | event as a fault. fault: | |
| | a deviation of a system | | | | a deviation of a system | |
skipping to change at page 76, line 8 skipping to change at page 76, line 8
Table 1: Definition of alarm in standards Table 1: Definition of alarm in standards
The evolution of the definition of alarm moves from focused on events The evolution of the definition of alarm moves from focused on events
reporting a deviation from normal operation towards a definition to a reporting a deviation from normal operation towards a definition to a
undesired *state* which *requires an operator action*. undesired *state* which *requires an operator action*.
F.2. Data model F.2. Data model
This section describes how this YANG alarm module relates to other This section describes how this YANG alarm module relates to other
standard data models. Note well that we cover other data-models for standard data models. Note well that we cover other data models for
alarm interfaces. Not other standards such as SDO specific alarms alarm interfaces. Not other standards such as SDO specific alarms
for example. for example.
F.2.1. X.733 F.2.1. X.733
X.733 has acted as a base for several alarm data models over the X.733 has acted as a base for several alarm data models over the
year. The YANG alarm module differs in the following ways: year. The YANG alarm module differs in the following ways:
X.733 models the alarm list as a list of notifications. The YANG X.733 models the alarm list as a list of notifications. The YANG
alarm module defines the alarm list as the current alarm states alarm module defines the alarm list as the current alarm states
for the resources, which is generated from the state change for the resources, which is generated from the state change
reporting notifications. reporting notifications.
In X.733 an alarm can have the severity level clear. In the YANG In X.733 an alarm can have the severity level clear. In the YANG
alarm module "clear" is not a severity level, it is a separate alarm module "clear" is not a severity level, it is a separate
state of the alarm. An alarm can have the following states for state of the alarm. An alarm can have the following states for
example (major, cleared), (minor, not cleared) example (major, cleared), (minor, not cleared)
X.733 uses a flat globally defined enumerated "probable cause" to X.733 uses a flat globally defined enumerated "probable-cause" to
identify alarm types. This alarm module uses a hierarchical YANG identify alarm types. This alarm module uses a hierarchical YANG
identity, alarm-type. This enables delegation of alarm types identity, "alarm-type". This enables delegation of alarm types
within organizations. It also lets management reason about within organizations. It also lets management reason about
"abstract" alarm-types corresponding to base identities, see abstract alarm types corresponding to base identities, see
Section 3.2. Section 3.2.
The YANG alarm module has not included the majority of the X.733 The YANG alarm module has not included the majority of the X.733
alarm attributes. Rather these are defined in an augmenting alarm attributes. Rather these are defined in an augmenting
module if "strict" X.733 compliance is needed. module if "strict" X.733 compliance is needed.
F.2.2. RFC 3877, the Alarm MIB F.2.2. RFC 3877, the Alarm MIB
The MIB in RFC 3877 takes a different approach, rather than defining The MIB in RFC 3877 takes a different approach, rather than defining
a concrete data model for alarms, it defines a model to map existing a concrete data model for alarms, it defines a model to map existing
skipping to change at page 77, line 17 skipping to change at page 77, line 17
The 3GPP Alarm IRP is an evolution of X.733. Main differences The 3GPP Alarm IRP is an evolution of X.733. Main differences
between the alarm YANG module and 3GPP are: between the alarm YANG module and 3GPP are:
3GPP keeps the majority of the X.733 attributes, the alarm YANG 3GPP keeps the majority of the X.733 attributes, the alarm YANG
module does not. module does not.
3GPP introduced overlapping and possibly conflicting keys for 3GPP introduced overlapping and possibly conflicting keys for
alarms, alarmId and (managed object, event type, probable cause, alarms, alarmId and (managed object, event type, probable cause,
specific problem). (See Annex C in [X.733] Example 3). In the specific problem). (See Annex C in [X.733] Example 3). In the
YANG alarm module the key for identifying an alarm instance is YANG alarm module the key for identifying an alarm instance is
clearly defined by (resource, alarm-type, alarm-type-qualifier). clearly defined by ("resource", "alarm-type-id", "alarm-type-
See also Section 3.4 for more information. qualifier"). See also Section 3.4 for more information.
The alarm YANG module clearly separates the resource/ The alarm YANG module clearly separates the resource/
instrumentation life cycle from the operator life cycle. 3GPP instrumentation life cycle from the operator life cycle. 3GPP
allows operators to set the alarm severity to clear, this is not allows operators to set the alarm severity to clear, this is not
allowed by this module, rather an operator closes an alarm which allowed by this module, rather an operator closes an alarm which
does not affect the severity. does not affect the severity.
F.2.4. G.7710 F.2.4. G.7710
G.7710 is different than the previous referenced alarm standards. It G.7710 is different than the previous referenced alarm standards. It
does define a data-model for alarm reporting. It defines common does not define a data model for alarm reporting. It defines common
equipment management function requirements including alarm equipment management function requirements including alarm
instrumentation. The scope is transport networks. instrumentation. The scope is transport networks.
The requirements in G.7710 corresponds to features in the alarm YANG The requirements in G.7710 corresponds to features in the alarm YANG
module in the following way: module in the following way:
Alarm Severity Assignment Profile (ASAP): the alarm profile Alarm Severity Assignment Profile (ASAP): the alarm profile
"/alarms/alarm-profile/". "/alarms/alarm-profile/".
Alarm Reporting Control (ARC): alarm shelving "/alarms/control/ Alarm Reporting Control (ARC): alarm shelving "/alarms/control/
alarm-shelving/" and the ability to control alarm notifications alarm-shelving/" and the ability to control alarm notifications
"/alarms/control/notify-status-changes". Alarm shelving "/alarms/control/notify-status-changes". Alarm shelving
corresponds to the use case of turning off alarm reporting for a corresponds to the use case of turning off alarm reporting for a
specific resource, the NALM state in M.3100. specific resource, the NALM state in M.3100.
Appendix G. Alarm Usability Requirements Appendix G. Alarm Usability Requirements
This section defines usability requirements for alarms. Alarm This section defines usability requirements for alarms. Alarm
usability is important for an alarm interface. A data-model will usability is important for an alarm interface. A data model will
help in defining the format but if the actual alarms are of low value help in defining the format but if the actual alarms are of low value
we have not gained the goal of alarm management. we have not gained the goal of alarm management.
Common alarm problems and the cause of the problems are summarized in Common alarm problems and the cause of the problems are summarized in
Table 2. This summary is adopted to networking based on the ISA Table 2. This summary is adopted to networking based on the ISA
[ISA182] and EEMUA [EEMUA] standards. [ISA182] and EEMUA [EEMUA] standards.
+------------------+--------------------------------+---------------+ +------------------+--------------------------------+---------------+
| Problem | Cause | How this | | Problem | Cause | How this |
| | | module | | | | module |
 End of changes. 110 change blocks. 
210 lines changed or deleted 237 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/