draft-ietf-ccamp-alarm-module-09.txt   rfc8632.txt 
Network Working Group S. Vallin Internet Engineering Task Force (IETF) S. Vallin
Internet-Draft Stefan Vallin AB Request for Comments: 8632 Stefan Vallin AB
Intended status: Standards Track M. Bjorklund Category: Standards Track M. Bjorklund
Expires: October 13, 2019 Cisco ISSN: 2070-1721 Cisco
April 11, 2019 September 2019
YANG Alarm Module A YANG Data Model for Alarm Management
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 is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on October 13, 2019. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc8632.
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
(https://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
skipping to change at page 2, line 12 skipping to change at page 2, line 10
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 Data Model 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 Lifecycle . . . . . . . . . . . . . . . . . . . . . 9 3.5. Alarm Lifecycle . . . . . . . . . . . . . . . . . . . . . 9
3.5.1. Resource Alarm Lifecycle . . . . . . . . . . . . . . 10 3.5.1. Resource Alarm Lifecycle . . . . . . . . . . . . . . 10
3.5.2. Operator Alarm Lifecycle . . . . . . . . . . . . . . 10 3.5.2. Operator Alarm Lifecycle . . . . . . . . . . . . . . 11
3.5.3. Administrative Alarm Lifecycle . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . 15 4.2. Alarm Inventory . . . . . . . . . . . . . . . . . . . . . 16
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-Alarm 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. The X.733 Mapping Module . . . . . . . . . . . . . . . . . . 53
8. The X.733 Mapping Module . . . . . . . . . . . . . . . . . . 53 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65 9. Security Considerations . . . . . . . . . . . . . . . . . . . 65
10. Security Considerations . . . . . . . . . . . . . . . . . . . 65 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 67
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 66 10.1. Normative References . . . . . . . . . . . . . . . . . . 67
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 67 10.2. Informative References . . . . . . . . . . . . . . . . . 68
12.1. Normative References . . . . . . . . . . . . . . . . . . 67 Appendix A. Vendor-Specific Alarm Types Example . . . . . . . . 70
12.2. Informative References . . . . . . . . . . . . . . . . . 68 Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 71
Appendix A. Vendor-specific Alarm Types Example . . . . . . . . 69
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 . . . . . . . . . . . . . . . 73
Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 73 Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 74
Appendix F. Relationship to other alarm standards . . . . . . . 74 Appendix F. Relationship to Other Alarm Standards . . . . . . . 74
F.1. Alarm definition . . . . . . . . . . . . . . . . . . . . 74 F.1. Definition of "Alarm" . . . . . . . . . . . . . . . . . . 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. The Alarm MIB (RFC 3877) . . . . . . . . . . . . . . 77
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 . . . . . . . . . . . . . . . . . . . . . . . 78
Appendix G. Alarm Usability Requirements . . . . . . . . . . . . 77
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81 Appendix G. Alarm-Usability Requirements . . . . . . . . . . . . 78
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 82
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82
1. Introduction 1. Introduction
This document defines a YANG [RFC7950] module for alarm management. This document defines a YANG module [RFC7950] 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 northbound 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
implementing available alarm standards from ITU [X.733], 3GPP implementing available alarm standards from ITU [X.733], 3GPP
[ALARMIRP] and ANSI [ISA182]. [ALARMIRP], and ANSI [ISA182].
1.1. Terminology and Notation 1.1. Terminology and Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The following terms are defined in [RFC7950]: The following terms are defined in [RFC7950]:
o action o action
o client o client
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 Alarm (the general concept): An alarm signifies an undesirable state
state in a resource that requires corrective action. in a resource that requires corrective action.
o Fault: A fault is the underlying cause of an undesired behavior. 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. For example, imagine a bad Mean an underlying fault as a cause. For example, imagine a bad Mean
Opinion Score (MOS) alarm from a Voice over IP (VOIP) probe and Opinion Score (MOS) alarm from a Voice over IP (VOIP) probe and
the cause being non-optimal QoS configuration. the cause being non-optimal QoS configuration.
o Alarm Type: An alarm type identifies a possible unique alarm state 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", and "high-disk-utilization".
o Resource: A fine-grained identification of the alarming resource, Resource: A fine-grained identification of the alarming resource,
for example: an interface, a process. for example, an interface and a process.
o Alarm Instance: The alarm state for a specific resource and alarm Alarm Instance: The alarm state for a specific resource and alarm
type. For example ("GigabitEthernet0/15", link-alarm). An entry type, for example, ("GigabitEthernet0/15", "link-alarm"). An
in the alarm list. entry in the alarm list.
o Cleared alarm: A cleared alarm is an alarm where the system 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 cannot
clear alarms, clearance is managed by the system. For example, a clear alarms; clearance is managed by the system. For example, a
linkUp notification can be considered a clear condition for a "linkUp" notification can be considered a clear condition for a
linkDown state. "linkDown" state.
o Closed alarm: Operators can close alarms irrespective of the alarm 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 because either the corrective action has
been taken or that it can be ignored for other reasons. been taken or it can be ignored for other reasons.
o Alarm Inventory: A list of all possible alarm types on a system. Alarm Inventory: A list of all possible alarm types on a system.
o Alarm Shelving: Blocking alarms according to specific criteria. Alarm Shelving: Blocking alarms according to specific criteria.
o Corrective Action: An action taken by an operator or automation Corrective Action: An action taken by an operator or automation
routine in order to minimize the impact of the alarm or resolve 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 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., System: The system that implements this YANG module, i.e., acts as a
acts as a server. This corresponds to a network device or a server. This corresponds to a network device or a management
management application that provides a northbound alarm interface. application that provides a northbound alarm 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 data model are:
o Simple to use. If a system supports this module, it shall be o Users find it simple to use. If a system supports this module, it
straight-forward to integrate this into a YANG based alarm shall be straightforward to integrate it into a YANG-based alarm
manager. manager.
o View alarms as states on resources and not as discrete o Alarms are viewed as states on resources and not as discrete
notifications. notifications.
o To provide a precise definition of "alarm" in order to exclude o A precise definition of "alarm" is provided in order to exclude
general events that should not be forwarded as alarm general events that should not be forwarded as alarm
notifications. notifications.
o To provide precise identification of alarm types and alarm o Precise identification of alarm types and alarm instances is
instances. provided.
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 Alarm-usability requirements are addressed; see Appendix G. While
and telecom standards have addressed alarms mostly from a protocol IETF and telecom standards have addressed alarms mostly from a
perspective, the process industry has published several relevant protocol perspective, the process industry has published several
standards addressing requirements for a useful alarm interface; relevant standards addressing requirements for a useful alarm
[EEMUA], [ISA182]. This alarm module defines usability interface; see [EEMUA] and [ISA182]. This document defines
requirements as well as a YANG data model. usability 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 is achievable. Still, keep some of the X.733 concepts out of the
order to make the model small and easy to understand. core model in order to make the model small and easy to
understand.
3. Alarm Module Concepts 3. Alarm Data Model 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
An alarm signifies an undesirable state in a resource that requires An alarm signifies an undesirable state in a resource that requires
corrective action. corrective action.
There are two main things to remember from this definition: There are two main things to remember from this definition:
1. the definition focuses on leaving out events and logging 1. It focuses on leaving out events and logging information in
information in general. Alarms should only be used for undesired general. Alarms should only be used for undesired states that
states that require action. require action.
2. the definition also focuses on alarms as a state on a resource, 2. It also focuses on alarms as a state on a resource, not the
not the notifications that report the state changes. notifications that report the state changes.
See Appendix F for information how this definition relates to other See Appendix F for information on how this definition relates to
alarm standards. other alarm standards.
3.2. Alarm Type 3.2. Alarm Type
This document defines an alarm type with an alarm type id and an This document defines an alarm type with an alarm-type id and an
alarm type qualifier. alarm-type qualifier.
The alarm type id is modeled as a YANG identity. With YANG The alarm-type id is modeled as a YANG identity. With YANG
identities, new alarm types can be defined in a distributed fashion. identities, new alarm types can be defined in a distributed fashion.
YANG identities are hierarchical, which means that a hierarchy of YANG identities are hierarchical, which means that a hierarchy of
alarm types can be defined. alarm types can be defined.
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. An example is a system with digital inputs that allows users time. An example is a system with digital inputs that allows users
to connect detectors, such as smoke detectors, to the inputs. In to connect detectors, such as smoke detectors, to the inputs. In
this case it is a configuration action that says that certain this case, it is a configuration action that says certain connectors
connectors are fire alarms for example. 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 data
module allows for further qualification of the identity-based alarm model permits further qualification of the identity-based alarm type
type using a string. A potential drawback of this is that there is a using a string. A potential drawback of this is that there is a
significant risk that alarm operators will receive alarm types as a significant risk that alarm operators will receive alarm types as a
surprise. They do not know how to resolve the problem since a surprise. They do not know how to resolve the problem since a
defined alarm procedure does not necessarily exist. To avoid this defined alarm procedure does not necessarily exist. To avoid this
risk the system MUST publish all possible alarm types in the alarm risk, the system MUST publish all possible alarm types in the alarm
inventory, see Section 4.2. inventory; see Section 4.2.
A vendor or standards 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 7, line 24 skipping to change at page 7, line 28
identity link-alarm { identity link-alarm {
base communications-alarm; base communications-alarm;
} }
Alarm types can be abstract. An abstract alarm type is used as a Alarm types can be abstract. An abstract alarm type is used as a
base for defining hierarchical alarm types. Concrete alarm types are base for defining hierarchical alarm types. Concrete alarm types are
used for alarm states and appear in the alarm inventory. There are used for alarm states and appear in the alarm inventory. There are
two kinds of concrete alarm types: two kinds of concrete alarm types:
1. The last subordinate identity in the "alarm-type-id" hierarchy is 1. The last subordinate identity in the "alarm-type-id" hierarchy is
concrete, for example: "alarm-identity.environmental- concrete, for example, "alarm-identity.environmental-
alarm.smoke". In this example "alarm-identity" and alarm.smoke". In this example, "alarm-identity" and
"environmental-alarm" are abstract YANG identities, whereas "environmental-alarm" are abstract YANG identities, whereas
"smoke" is a concrete YANG identity. "smoke" is a concrete YANG identity.
2. The YANG identity hierarchy is abstract and the concrete alarm 2. The YANG identity hierarchy is abstract, and the concrete alarm
type is defined by the dynamic alarm qualifier string, for type is defined by the dynamic alarm-qualifier string, for
example: "alarm-identity.environmental-alarm.external-detector" example, "alarm-identity.environmental-alarm.external-detector"
with alarm-type-qualifier "smoke". with alarm-type-qualifier "smoke".
For example: For example:
// Alternative 1: concrete alarm type identity // Alternative 1: concrete alarm type identity
import ietf-alarms { import ietf-alarms {
prefix al; prefix al;
} }
identity environmental-alarm { identity environmental-alarm {
base al:alarm-type; base al:alarm-type;
skipping to change at page 8, line 29 skipping to change at page 8, line 31
import ietf-alarms { import ietf-alarms {
prefix al; prefix al;
} }
identity environmental-alarm { identity environmental-alarm {
base al:alarm-type; base al:alarm-type;
description "Abstract alarm type"; description "Abstract alarm type";
} }
identity external-detector { identity external-detector {
base environmental-alarm; base environmental-alarm;
description description
"Abstract alarm type, a run-time configuration "Abstract alarm type; a runtime configuration
procedure sets the type of alarm detected. This will procedure sets the type of alarm detected. This will
be reported in the alarm-type-qualifier."; be reported in the alarm-type-qualifier.";
} }
A server SHOULD strive to minimize the number of dynamically defined A server SHOULD strive to minimize the number of dynamically defined
alarm types. alarm types.
3.3. Identifying the Alarming Resource 3.3. Identifying the Alarming Resource
It is of vital importance to be able to refer to the alarming It is of vital importance to be able to refer to the alarming
resource. This reference must be as fine-grained as possible. If resource. This reference must be as fine-grained as possible. If
the alarming resource exists in the data tree then an instance- the alarming resource exists in the data tree, an instance-identifier
identifier MUST be used with the full path to the object. MUST be used with the full path to the object.
When the module is used in a controller/orchestrator/manager the When the module is used in a controller/orchestrator/manager, the
original device resource identification can be modified to include original device resource identification can be modified to include
the device in the path. The details depend on how devices are the device in the path. The details depend on how devices are
identified, and are out of scope for this specification. identified and are out of scope for this specification.
Example: Example:
The original device alarm might identify the resource as The original device alarm might identify the resource as
"/dev:interfaces/dev:interface[dev:name='FastEthernet1/0']". "/dev:interfaces/dev:interface[dev:name='FastEthernet1/0']".
The resource identification in the manager could look something The resource identification in the manager could look something
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 the alarm data model is to remove any ambiguity in
alarm notifications are mapped to an update of an alarm instance. how alarm notifications are mapped to an update of an alarm instance.
The X.733 and 3GPP documents were not clear on this point. This YANG The X.733 [X.733] and 3GPP [ALARMIRP] documents were not clear on
alarm module states that the tuple (resource, alarm type identifier, this point. This alarm data model states that the tuple (resource,
alarm type qualifier) corresponds to a single alarm instance. This alarm-type identifier, and alarm-type qualifier) corresponds to a
means that alarm notifications for the same resource and same alarm single alarm instance. This means that alarm notifications for the
type are matched to update the same alarm instance. These three same resource and same alarm type are matched to update the same
leafs are therefore used as the key in the alarm list: alarm instance. These three 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 Lifecycle 3.5. Alarm Lifecycle
The alarm model clearly separates the resource alarm lifecycle from The alarm model clearly separates the resource alarm lifecycle from
the operator and administrative lifecycles of an alarm. the operator and administrative lifecycles of an alarm.
o resource alarm lifecycle: 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 lifecycle: 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 acknowledging 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 shelve (block/filter) alarms in order to avoid
nuisance alarms. nuisance alarms.
o administrative alarm lifecycle: purging (deleting) unwanted alarms o administrative alarm lifecycle: purging (deleting) unwanted alarms
and compressing the alarm status change list. This module exposes and compressing the alarm status-change list. This module exposes
operations to manage the administrative lifecycle. The server may operations to manage the administrative lifecycle. The server may
also perform these operations based on other policies, but how also perform these operations based on other policies, 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. How until they are manually purged or if it has an automatic removal
this is done is outside the scope of this document. policy. How this is done is outside the scope of this document.
3.5.1. Resource Alarm Lifecycle 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 lifecycle: 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 "ietf-alarms" YANG module defines
"purge-alarms" that deletes alarms. an action "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
lifecycle: 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-raised yang:date-and-time
+--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
+--ro alarm-text alarm-text +--ro alarm-text alarm-text
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- Therefore, an alarm can look like this: (("GigabitEthernet0/25",
alarm,""), false, 2018-04-08T08:20:10.00Z, major, "Interface "link-alarm",""), false, 2018-04-08T08:20:10.00Z,
GigabitEthernet0/25 down") 2018-04-08T08:20:10.00Z, major, "Interface GigabitEthernet0/25
down").
3.5.2. Operator Alarm Lifecycle 3.5.2. Operator Alarm Lifecycle
Operators can act upon alarms using the set-operator-state action: Operators can act upon alarms using the set-operator-state 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. For example, a closed alarm is an alarm this state as a criterion. For example, a closed alarm is an alarm
where the operator has performed any required corrective actions. where the operator has performed any required corrective actions.
Closed alarms are good candidates for being purged. Closed alarms are good candidates for being purged.
3.5.3. Administrative Alarm Lifecycle 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 lifecycle such as "all closed based on the operator and resource alarm lifecycle such as "all
cleared alarms older than a time specification". The server may also closed cleared alarms older than a time specification". The server
perform these operations based on other policies, but how that is may also perform these operations based on other policies, but how
done is out of scope for this document. that is 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 that 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
change. A client can perform this using the "compress-alarms" change. A client can perform this using the "compress-alarms"
action. The server may also perform these operations based on other action. The server may also perform these operations based on other
policies, but how that is done is out of scope for this document. policies, but how that is done is out of scope for this document.
3.6. Root Cause, Impacted Resources and Related Alarms 3.6. Root Cause, Impacted Resources, and Related Alarms
The alarm module does not mandate any requirements for the system to The alarm data model does not mandate any requirements for the system
support alarm correlation or root-cause and service-impact analysis. to support alarm correlation or root-cause and service-impact
However, if such features are supported, this section describes how analysis. However, if such features are supported, this section
the results of such analysis are represented in the data model. describes how the results of such analysis are represented in the
These parts of the model are optional. The module supports three data model. These parts of the model are optional. The module
scenarios: supports three scenarios:
Root cause analysis: An alarm can indicate candidate root cause Root-cause analysis: An alarm can indicate candidate root-cause
resources, for example: a database issue alarm referring to a full resources, for example, a database issue alarm referring to a
disc partition. full-disk 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 varying 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 data model 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 data model is to limit the amount
alarms. In many cases several resources are affected for a given of 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 a possible "impacted-
and a leaf-list to identify possible "root-cause-resources". These resource" and a leaf-list to identify a possible "root-cause-
serves as hints only. It is up to the client application to use this resource". These serve as hints only. It is up to the client
information to present the overall status. Using the disk full application to use this information to present the overall status.
example, a good alarm would be to use the hard disk partition as the Using the disk-full example, a good alarm would be to use the hard-
alarming resource and add the database and applications into the disk partition as the alarming resource and add the database and
"impacted-resources" leaf-list. applications into the "impacted-resource" 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 cannot be acted upon to fix the problem. The disk
disk full example above illustrates the principle; you can not fix full example above illustrates the principle; you cannot fix the
the underlying issue by database operations. However, you need to underlying issue by database operations. However, you need to pay
pay attention to the database to perform any operations that limits attention to the database to perform any operations that limit the
the impact of problem. impact of the problem.
On 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 raises an alarm to in this case only monitors the side effect and raises an alarm to
indicate a situation requiring attention. The instrumentation still indicate a situation requiring attention. The instrumentation still
might identify possible candidates for the root-cause resource. In might identify possible candidates for the root-cause resource. In
this case the "root-cause-resource" leaf-list can be used to indicate this case, the "root-cause-resource" leaf-list can be used to
the candidate root-cause resources. An example of this kind of alarm indicate the candidate root-cause resources. An example of this kind
might be an active test tool that detects an SLA violation on a VPN of alarm might be an active test tool that detects a Service Level
connection and identifies the devices along the chain as candidate Agreement (SLA) violation on a VPN connection and identifies the
root causes. devices along the chain as candidate root causes.
The alarm module also supports a way to associate different alarms to The alarm data model also supports a way to associate different
each other with the "related-alarm" list. This list enables the alarms with each other using the "related-alarm" list. This list
server to inform the client that certain alarms are related to other enables the server to inform the client that certain alarms are
alarms. related to other 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 to be filtered out from the alarm list in order alarm list; thus, they can be filtered out so that the main alarm
for the main alarm list to only contain entries of interest. Shelved list only contains entries of interest. Shelved alarms do not
alarms do not generate notifications but the shelved alarm list is generate notifications, but the shelved-alarm list is updated with
updated with any alarm state changes. 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
type. This module supports configuring severity levels overriding type. This module supports configuring severity levels overriding
the system default levels. This corresponds to the Alarm Assignment the system-default levels. This corresponds to the Alarm Severity
Profile, ASAP, functionality in M.3100 [M.3100] and M.3160 [M.3160]. Assignment Profile (ASAP) functionality in M.3100 [M.3100] and M.3160
Other standard or enterprise modules can augment this list with [M.3160]. Other standard or enterprise modules can augment this list
further alarm type information. with 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 the YANG features rest of the data model is made conditional with these 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 7 skipping to change at page 15, line 7
+--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 resource resource-match +--rw resource resource-match
+--rw description string +--rw description string
+--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 whether
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, see Appendix F.2.4. 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. Matching Shelved alarms are shown in a dedicated shelved-alarm list. Matching
alarms MUST appear in the /alarms/shelved-alarms/shelved-alarm list, alarms MUST appear in the "/alarms/shelved-alarms/shelved-alarm"
and non-matching /alarms MUST appear in the /alarms/alarm-list/alarm list, and non-matching alarms MUST appear in the "/alarms/alarm-list/
list. The server does not send any notifications for shelved alarms. alarm" list. The server does not send any notifications for shelved
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 not to 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 the following
reasons:
The system might not implement 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
system to publish for which resources a given alarm type may appear. system to publish for which resources a given alarm type may appear.
A server MUST implement the alarm inventory in order to enable A server MUST implement the alarm inventory in order to enable
controlled alarm procedures in the client. controlled alarm procedures in the client.
A server implementer may want to document the alarm inventory for A server implementer may want to document the alarm inventory for
off-line processing by clients. The file format defined in offline processing by clients. The file format defined in
[I-D.ietf-netmod-yang-instance-file-format] can be used for this [YANG-INSTANCE] can be used for this purpose.
purpose.
The alarm inventory tree is shown below: The alarm inventory tree is shown below:
+--ro alarm-inventory +--ro alarm-inventory
+--ro alarm-type* [alarm-type-id alarm-type-qualifier] +--ro alarm-type* [alarm-type-id alarm-type-qualifier]
+--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 resource* resource-match +--ro resource* resource-match
+--ro will-clear boolean +--ro will-clear boolean
+--ro severity-levels* severity +--ro severity-level* severity
+--ro description string +--ro description string
4.3. Alarm Summary 4.3. Alarm Summary
The alarm summary list summarizes alarms per severity; how many The alarm summary list summarizes alarms per severity: how many
cleared, cleared and closed, and closed. It also gives an indication cleared, cleared and closed, and closed. It also gives an indication
if there are shelved alarms. if there are shelved alarms.
The alarm summary tree is shown below: The alarm summary tree is shown below:
+--ro summary {alarm-summary}? +--ro summary {alarm-summary}?
+--ro alarm-summary* [severity] +--ro alarm-summary* [severity]
| +--ro severity severity | +--ro severity severity
| +--ro total? yang:gauge32 | +--ro total? yang:gauge32
| +--ro not-cleared? yang:gauge32 | +--ro not-cleared? yang:gauge32
skipping to change at page 17, line 23 skipping to change at page 17, line 25
| +--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 the tuple The alarm list, "/alarms/alarm-list", is a function from the tuple
(resource, alarm type, alarm type qualifier) to the current composite (resource, alarm type, alarm-type qualifier) to the current composite
alarm state. The composite state includes states for the resource alarm state. The composite state includes states for the resource
lifecycle such as severity, clearance flag and operator states such alarm lifecycle such as severity, clearance flag, and operator states
as acknowledgment. This means that for a given resource and alarm such as acknowledged. This means that for a given resource and alarm
type 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.
+--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
| +--ro related-alarm* | +--ro related-alarm*
skipping to change at page 19, line 15 skipping to change at page 19, line 17
| +--ro purged-alarms? uint32 | +--ro purged-alarms? uint32
+---x compress-alarms {alarm-history}? +---x compress-alarms {alarm-history}?
+---w input +---w input
| +---w resource? resource-match | +---w resource? resource-match
| +---w alarm-type-id? | +---w alarm-type-id?
| | -> /alarms/alarm-list/alarm/alarm-type-id | | -> /alarms/alarm-list/alarm/alarm-type-id
| +---w alarm-type-qualifier? leafref | +---w alarm-type-qualifier? leafref
+--ro output +--ro output
+--ro compressed-alarms? uint32 +--ro compressed-alarms? uint32
Every alarm has three important states, the resource clearance state Every alarm has three important states: the resource clearance state
"is-cleared", the severity "perceived-severity" and the operator "is-cleared", the severity "perceived-severity", and the operator
state available in the operator state change list. state available in the operator-state change list.
In order to see the alarm history the resource state changes are In order to see the alarm history, the resource state changes are
available in the "status-change" list and the operator history is available in the "status-change" list, and the operator history is
available in the "operator-state-change" list. available in the "operator-state-change" list.
4.5. The Shelved Alarms List 4.5. The Shelved-Alarm 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 match 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
level(s) instead of the system default. This configuration MUST also severity level(s) instead of the system default. This configuration
be represented in the alarm inventory. MUST also 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
+--rw alarm-type-qualifier-match string +--rw alarm-type-qualifier-match string
+--rw resource resource-match +--rw resource resource-match
+--rw description string +--rw description string
+--rw alarm-severity-assignment-profile +--rw alarm-severity-assignment-profile
{severity-assignment}? {severity-assignment}?
+--rw severity-levels* severity +--rw severity-level* severity
4.7. Operations 4.7. Operations
The alarm module supports the following actions to manage the alarms: The alarm data model supports the following actions to manage the
alarms:
/alarms/alarm-list/purge-alarms: Delete alarms from the "alarm-list" "/alarms/alarm-list/purge-alarms": Delete alarms from the "alarm-
according to specific criteria, for example all cleared alarms list" according to specific criteria, for example, all cleared
older than a specific date. alarms older than a specific date.
/alarms/alarm-list/compress-alarms: Compress the "status-change" "/alarms/alarm-list/compress-alarms": Compress the "status-change"
list for the alarms. list for the alarms.
/alarms/alarm-list/alarm/set-operator-state: Change the operator "/alarms/alarm-list/alarm/set-operator-state": Change the operator
state for an alarm. For example, an alarm can be acknowledged by state for an alarm. For example, an alarm can be acknowledged by
setting the operator state to "ack". setting the operator state to "ack".
/alarms/shelved-alarm-list/purge-shelved-alarms: Delete alarms from "/alarms/shelved-alarm-list/purge-shelved-alarms": Delete alarms
the "shelved-alarm-list" according to specific criteria, for from the "shelved-alarm-list" according to specific criteria, for
example all alarms older than a specific date. example, all alarms older than a specific date.
/alarms/shelved-alarm-list/compress-shelved-alarms: Compress the "/alarms/shelved-alarm-list/compress-shelved-alarms": Compress the
"status-change" list for the alarms. "status-change" list for the alarms.
4.8. Notifications 4.8. Notifications
The alarm module supports a general notification to report alarm The alarm data model supports a general notification to report alarm-
state changes. It carries all relevant parameters for the alarm state changes. It carries all relevant parameters for the alarm-
management application. management application.
There is also a notification to report that an operator changed the There is also a notification to report that an operator changed the
operator state on an alarm, like acknowledge. operator state on an alarm, like acknowledged.
If the alarm inventory is changed, for example a new card type is If the alarm inventory is changed, for example, a new card type is
inserted, a notification will tell the management application that inserted, a notification will tell the management application that
new alarm types are available. new alarm types are available.
5. Relationship to the ietf-hardware YANG module 5. Relationship to the ietf-hardware YANG Module
RFC 8348 [RFC8348] defines the "ietf-hardware" YANG data model for RFC 8348 [RFC8348] defines the "ietf-hardware" YANG data model for
the management of hardware. The "alarm-state" in RFC 8348 is a the management of hardware. The "alarm-state" in RFC 8348 is a
summary of the alarm severity levels that may be active on the summary of the alarm severity levels that may be active on the
specific hardware component. It does not say anything about how specific hardware component. It does not say anything about how
alarms are reported, and it doesn't provide any details of the alarms are reported, and it doesn't provide any details of the
alarms. alarms.
The mapping between the alarm YANG data model and the "alarm-state" The mapping between the alarm YANG data model, prefix "al", and the
in RFC 8348 is as follows: "alarm-state" in RFC 8348, prefix "hw", is as follows:
resource: Corresponds to an entry in the list "/hardware/component/" "al:resource": Corresponds to an entry in the list
"/hw:hardware/hw:component/".
is-cleared: No bit set in "/hardware/component/state/alarm-state" "al:is-cleared": No bit set in "/hw:hardware/hw:component/hw:state/
hw:alarm-state".
perceived-severity: Corresponding bit set in "al:perceived-severity": Corresponding bit set in
"/hardware/component/state/alarm-state". "/hw:hardware/hw:component/hw:state/hw:alarm-state".
operator-state-change/state: If the alarm is acknowledged by the "al:operator-state-change/al:state": If the alarm is acknowledged by
operator, the bit "under-repair" is in "/hardware/component/state/ the operator, the bit "hw:under-repair" is set in
alarm-state". "/hw:hardware/hw:component/hw:state/hw:alarm-state".
6. Alarm YANG Module 6. Alarm YANG Module
This YANG module references [RFC6991] and [XSD-TYPES]. This YANG module references [RFC6991] and [XSD-TYPES].
<CODE BEGINS> file "ietf-alarms@2019-04-10.yang" <CODE BEGINS> file "ietf-alarms@2019-09-11.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 {
prefix yang;
reference
"RFC 6991: Common YANG Data Types.";
}
organization
"IETF CCAMP Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/ccamp>
WG List: <mailto:ccamp@ietf.org>
Editor: Stefan Vallin
<mailto:stefan@wallan.se>
Editor: Martin Bjorklund
<mailto:mbj@tail-f.com>";
// RFC Ed.: replace XXXX with actual RFC number and import ietf-yang-types {
// remove this note. prefix yang;
reference
"RFC 6991: Common YANG Data Types.";
}
description organization
"This module defines an interface for managing alarms. Main "IETF CCAMP Working Group";
inputs to the module design are the 3GPP Alarm IRP, ITU-T X.733 contact
and ANSI/ISA-18.2 alarm standards. "WG Web: <https://trac.ietf.org/trac/ccamp>
WG List: <mailto:ccamp@ietf.org>
Main features of this module include: Editor: Stefan Vallin
<mailto:stefan@wallan.se>
* Alarm list: Editor: Martin Bjorklund
A list of all alarms. Cleared alarms stay in <mailto:mbj@tail-f.com>";
the list until explicitly purged. description
"This module defines an interface for managing alarms. Main
inputs to the module design are the 3GPP Alarm Integration
Reference Point (IRP), ITU-T X.733, and ANSI/ISA-18.2 alarm
standards.
* Operator actions on alarms: Main features of this module include:
Acknowledging and closing alarms.
* Administrative actions on alarms: * Alarm list:
Purging alarms from the list according to specific A list of all alarms. Cleared alarms stay in
criteria. the list until explicitly purged.
* Alarm inventory: * Operator actions on alarms:
A management application can read all Acknowledging and closing alarms.
alarm types implemented by the system.
* Alarm shelving: * Administrative actions on alarms:
Shelving (blocking) alarms according Purging alarms from the list according to specific
to specific criteria. criteria.
* Alarm profiles: * Alarm inventory:
A management system can attach further A management application can read all
information to alarm types, for example alarm types implemented by the system.
overriding system default severity
levels.
This module uses a stateful view on alarms. An alarm is a state * Alarm shelving:
for a specific resource (note that an alarm is not a Shelving (blocking) alarms according
notification). An alarm type is a possible alarm state for a to specific criteria.
resource. For example, the tuple:
('link-alarm', 'GigabitEthernet0/25') * Alarm profiles:
A management system can attach further
information to alarm types, for example,
overriding system-default severity
levels.
is an alarm of type 'link-alarm' on the resource This module uses a stateful view on alarms. An alarm is a state
'GigabitEthernet0/25'. for a specific resource (note that an alarm is not a
notification). An alarm type is a possible alarm state for a
resource. For example, the tuple:
Alarm types are identified using YANG identities and an optional ('link-alarm', 'GigabitEthernet0/25')
string-based qualifier. The string-based qualifier allows for
dynamic extension of the statically defined alarm types. Alarm
types identify a possible alarm state and not the individual
notifications. For example, the traditional 'link-down' and
'link-up' notifications are two notifications referring to the
same alarm type 'link-alarm'.
With this design there is no ambiguity about how alarm and alarm is an alarm of type 'link-alarm' on the resource
clear correlation should be performed: notifications that report 'GigabitEthernet0/25'.
the same resource and alarm type are considered updates of the
same alarm, e.g., clearing an active alarm or changing the
severity of an alarm.
The instrumentation can update 'severity' and 'alarm-text' on an Alarm types are identified using YANG identities and an optional
existing alarm. The above alarm example can therefore look string-based qualifier. The string-based qualifier allows for
like: dynamic extension of the statically defined alarm types. Alarm
types identify a possible alarm state and not the individual
notifications. For example, the traditional 'link-down' and
'link-up' notifications are two notifications referring to the
same alarm type 'link-alarm'.
(('link-alarm', 'GigabitEthernet0/25'), With this design, there is no ambiguity about how alarm and
warning, alarm clear correlation should be performed; notifications that
'interface down while interface admin state is up') report the same resource and alarm type are considered updates
of the same alarm, e.g., clearing an active alarm or changing
the severity of an alarm. The instrumentation can update the
severity and alarm text on an existing alarm. The above alarm
example can therefore look like the following:
There is a clear separation between updates on the alarm from (('link-alarm', 'GigabitEthernet0/25'),
the underlying resource, like clear, and updates from an warning,
operator like acknowledge or closing an alarm: 'interface down while interface admin state is up')
(('link-alarm', 'GigabitEthernet0/25'), There is a clear separation between updates on the alarm from
warning, the underlying resource, like clear, and updates from an
'interface down while interface admin state is up', operator, like acknowledging or closing an alarm:
cleared,
closed)
Administrative actions like removing closed alarms older than a (('link-alarm', 'GigabitEthernet0/25'),
given time is supported. warning,
'interface down while interface admin state is up',
cleared,
closed)
This alarm module does not define how the underlying Administrative actions like removing closed alarms older than a
instrumentation detects and clears the specific alarms. That given time is supported.
belongs to the SDO or enterprise that owns that specific
technology.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL This YANG module does not define how the underlying
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', instrumentation detects and clears the specific alarms. That
'MAY', and 'OPTIONAL' in this document are to be interpreted as belongs to the Standards Development Organization (SDO) or
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, enterprise that owns that specific technology.
they appear in all capitals, as shown here.
Copyright (c) 2019 IETF Trust and the persons identified as The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
authors of the code. All rights reserved. NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.
Redistribution and use in source and binary forms, with or Copyright (c) 2019 IETF Trust and the persons identified as
without modification, is permitted pursuant to, and subject to authors of the code. All rights reserved.
the license terms contained in, the Simplified BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX Redistribution and use in source and binary forms, with or
(https://tools.ietf.org/html/rfcXXXX); see the RFC itself for without modification, is permitted pursuant to, and subject to
full legal notices."; the license terms contained in, the Simplified BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
// RFC Ed.: update the date below with the date of RFC publication This version of this YANG module is part of RFC 8632; see
// and remove this note. the RFC itself for full legal notices.";
revision 2019-04-10 { revision 2019-09-11 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: YANG Alarm Module"; "RFC 8632: A YANG Data Model for Alarm Management";
} }
/* /*
* Features * Features
*/ */
feature operator-actions { feature operator-actions {
description description
"This feature indicates that the system supports operator "This feature indicates that the system supports operator
states on alarms."; states on alarms.";
} }
feature alarm-shelving { feature alarm-shelving {
description description
"This feature indicates that the system supports shelving "This feature indicates that the system supports shelving
(blocking) alarms. (blocking) alarms.
Alarm shelving may have an impact on server processing Alarm shelving may have an impact on server processing
resources in order to match alarms against shelf resources in order to match alarms against shelf
criteria."; criteria.";
} }
feature alarm-history { feature alarm-history {
description description
"This feature indicates that server maintains a history of "This feature indicates that the server maintains a history
state changes for each alarm. For example, if an alarm of state changes for each alarm. For example, if an alarm
toggles between cleared and active 10 times, these state toggles between cleared and active 10 times, these state
changes are present in a separate list in the alarm. changes are present in a separate list in the alarm.
Keeping the alarm history may have an impact on server memory Keeping the alarm history may have an impact on server
resources."; memory resources.";
} }
feature alarm-summary { feature alarm-summary {
description description
"This feature indicates that the server summarizes the number "This feature indicates that the server summarizes the number
of alarms per severity and operator state."; of alarms per severity and operator state.";
} }
feature alarm-profile { feature alarm-profile {
description description
"The system supports clients to configure further information "The system enables clients to configure further information
to each alarm type."; to each alarm type.";
}
feature severity-assignment {
description
"The system supports configurable alarm severity levels.";
reference
"ITU-T Recommendation M.3100:
Generic network information model
ITU-T Recommendation M.3160:
Generic, protocol-neutral management information model";
}
} feature root-cause-analysis {
description
"The system supports identifying candidate root-cause
resources for an alarm, for example, a disk partition
root cause for a logger failure alarm.";
}
feature severity-assignment { feature service-impact-analysis {
description description
"The system supports configurable alarm severity levels."; "The system supports identifying candidate-impacted
reference resources for an alarm, for example, an interface state change
"M.3160/M.3100 Alarm Severity Assignment Profile, ASAP"; resulting in a link alarm, which can refer to a link as being
} impacted.";
}
feature root-cause-analysis { feature alarm-correlation {
description description
"The system supports identifying candidate root-cause "The system supports correlating/grouping alarms
resources for an alarm, for example a disc partition that belong together.";
root cause for a logger failure alarm."; }
}
feature service-impact-analysis { /*
description * Identities
"The system supports identifying candidate impacted */
resources for an alarm. For example, an interface state change
resulting in a link alarm which can refer to a link as being
impacted.";
}
feature alarm-correlation { identity alarm-type-id {
description description
"The system supports correlating/grouping alarms "Base identity for alarm types. A unique identification of
that belong together."; the alarm, not including the resource. Different resources
} can share alarm types. If the resource reports the same
alarm type, it is considered to be the same alarm. The alarm
type is a simplification of the different X.733 and 3GPP Alarm
IRP correlation mechanisms, and it allows for
hierarchical extensions.
/* A string-based qualifier can be used in addition to the
* Identities identity in order to have different alarm types based on
*/ information not known at design time, such as values in
textual SNMP Notification varbinds.
identity alarm-type-id { Standards and vendors can define sub-identities to clearly
description identify specific alarm types.
"Base identity for alarm types. A unique identification of the
alarm, not including the resource. Different resources can
share alarm types. If the resource reports the same alarm
type, it is to be considered to be the same alarm. The alarm
type is a simplification of the different X.733 and 3GPP alarm
IRP alarm correlation mechanisms and it allows for
hierarchical extensions.
A string-based qualifier can be used in addition to the This identity is abstract and MUST NOT be used for alarms.";
identity in order to have different alarm types based on }
information not known at design-time, such as values in
textual SNMP Notification var-binds.
Standards and vendors can define sub-identities to clearly /*
identify specific alarm types. * Common types
*/
This identity is abstract and MUST NOT be used for alarms."; typedef resource {
} type union {
type instance-identifier {
require-instance false;
}
type yang:object-identifier;
type string;
type yang:uuid;
}
description
"This is an identification of the alarming resource, such as an
interface. It should be as fine-grained as possible to both
guide the operator and guarantee uniqueness of the alarms.
/* If the alarming resource is modeled in YANG, this type will
* Common types be an instance-identifier.
*/
typedef resource { If the resource is an SNMP object, the type will be an
type union { 'object-identifier'.
type instance-identifier {
require-instance false;
}
type yang:object-identifier;
type string;
type yang:uuid;
}
description
"This is an identification of the alarming resource, such as an
interface. It should be as fine-grained as possible both to
guide the operator and to guarantee uniqueness of the alarms.
If the alarming resource is modeled in YANG, this type will If the resource is anything else, for example, a distinguished
be an instance-identifier. name or a Common Information Model (CIM) path, this type will
be a string.
If the resource is an SNMP object, the type will be an If the alarming object is identified by a Universally Unique
object-identifier. Identifier (UUID), use the uuid type. Be cautious when using
this type, since a UUID is hard to use for an operator.
If the resource is anything else, for example a distinguished If the server supports several models, the precedence should
name or a CIM path, this type will be a string. be in the order as given in the union definition.";
}
If the alarming object is identified by a UUID use the uuid typedef resource-match {
type. Be cautious when using this type, since a UUID is hard type union {
to use for an operator. type yang:xpath1.0;
type yang:object-identifier;
type string;
}
description
"This type is used to match resources of type 'resource'.
Since the type 'resource' is a union of different types, the
'resource-match' type is also a union of corresponding types.
If the server supports several models, the precedence should If the type is given as an XPath 1.0 expression, a resource
be in the order as given in the union definition."; of type 'instance-identifier' matches if the instance is part
} of the node set that is the result of evaluating the XPath 1.0
expression. For example, the XPath 1.0 expression:
typedef resource-match { /ietf-interfaces:interfaces/ietf-interfaces:interface
type union { [ietf-interfaces:type='ianaift:ethernetCsmacd']
type yang:xpath1.0;
type yang:object-identifier;
type string;
}
description
"This type is used to match resources of type 'resource'.
Since the type 'resource' is a union of different types, the
'resource-match' type is also a union of corresponding types.
If the type is given as an XPath 1.0 expression, a resource of would match the resource instance-identifier:
type 'instance-identifier' matches if the instance is part of
the node set that is the result of evaluating the XPath 1.0
expression. For example, the XPath 1.0 expression:
/ietf-interfaces:interfaces/ietf-interfaces:interface /if:interfaces/if:interface[if:name='eth1'],
[ietf-interfaces:type='ianaift:ethernetCsmacd']
would match the resource instance-identifier: assuming that the interface 'eth1' is of type
'ianaift:ethernetCsmacd'.
/if:interfaces/if:interface[if:name='eth1'], If the type is given as an object identifier, a resource of
type 'object-identifier' matches if the match object
identifier is a prefix of the resource's object identifier.
For example, the value:
assuming that the interface 'eth1' is of type 1.3.6.1.2.1.2.2
'ianaift:ethernetCsmacd'.
If the type is given as an object identifier, a resource of would match the resource object identifier:
type 'object-identifier' matches if the match object
identifier is a prefix of the resource's object identifier.
For example, the value:
1.3.6.1.2.1.2.2 1.3.6.1.2.1.2.2.1.1.5
would match the resource object identifier: If the type is given as an UUID or a string, it is interpreted
as an XML Schema regular expression, which matches a resource
of type 'yang:uuid' or 'string' if the given regular
expression matches the resource string.
1.3.6.1.2.1.2.2.1.1.5 If the type is given as an XPath expression, it is evaluated
in the following XPath context:
If the type is given as an UUID or a string, it is interpreted o The set of namespace declarations is the set of prefix
as an XML Schema regular expression, which matches a resource and namespace pairs for all YANG modules implemented by
of type 'yang:uuid' or 'string' if the given regular the server, where the prefix is the YANG module name and
expression matches the resource string. the namespace is as defined by the 'namespace' statement
in the YANG module.
If the type is given as an XPath expression it is evaluated If a leaf of this type is encoded in XML, all namespace
in the following XPath context: declarations in scope on the leaf element are added to
the set of namespace declarations. If a prefix found in
the XML is already present in the set of namespace
declarations, the namespace in the XML is used.
o The set of namespace declarations is the set of prefix o The set of variable bindings is empty.
and namespace pairs for all YANG modules implemented by
the server, where the prefix is the YANG module name and
the namespace is as defined by the 'namespace' statement
in the YANG module.
If a leaf of this type is encoded in XML, all namespace o The function library is the core function library, and
declarations in scope on the leaf element are added to the functions are defined in Section 10 of RFC 7950.
the set of namespace declarations. If a prefix found in
the XML is already present in the set of namespace
declarations, the namespace in the XML is used.
o The set of variable bindings is empty. 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";
}
o The function library is the core function library typedef alarm-text {
and the functions defined in Section 10 of RFC 7950. type string;
description
"The string used to inform operators about the alarm. This
MUST contain enough information for an operator to be able to
understand the problem and how to resolve it. If this string
contains structure, this format should be clearly documented
for programs to be able to parse that information.";
}
o The context node is the root node in the data tree."; typedef severity {
reference type enumeration {
"XML Schema Part 2: Datatypes Second Edition, enum indeterminate {
World Wide Web Consortium Recommendation value 2;
REC-xmlschema-2-20041028"; description
} "Indicates that the severity level could not be
determined. This level SHOULD be avoided.";
}
enum warning {
value 3;
description
"The 'warning' severity level indicates the detection of a
potential or impending service-affecting fault, before any
significant effects have been felt. Action should be
taken to further diagnose (if necessary) and correct the
problem in order to prevent it from becoming a more
serious service-affecting fault.";
}
enum minor {
value 4;
description
"The 'minor' severity level indicates the existence of a
non-service-affecting fault condition and that corrective
action should be taken in order to prevent a more serious
(for example, service-affecting) fault. Such a severity
can be reported, for example, when the detected alarm
condition is not currently degrading the capacity of the
resource.";
}
enum major {
value 5;
description
"The 'major' severity level indicates that a service-
affecting condition has developed and an urgent corrective
action is required. Such a severity can be reported, for
example, when there is a severe degradation in the
capability of the resource and its full capability must be
restored.";
}
enum critical {
value 6;
description
"The 'critical' severity level indicates that a service-
affecting condition has occurred and an immediate
corrective action is required. Such a severity can be
reported, for example, when a resource becomes totally out
of service and its capability must be restored.";
}
}
description
"The severity level of the alarm. Note well that the value
'clear' is not included. Whether or not an alarm is cleared
is a separate boolean flag.";
reference
"ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
}
typedef alarm-text { typedef severity-with-clear {
type string; type union {
description type enumeration {
"The string used to inform operators about the alarm. This enum cleared {
MUST contain enough information for an operator to be able to value 1;
understand the problem and how to resolve it. If this string description
contains structure, this format should be clearly documented "The alarm is cleared by the instrumentation.";
for programs to be able to parse that information."; }
} }
type severity;
typedef severity { }
type enumeration { description
enum indeterminate { "The severity level of the alarm including clear. This is used
value 2; only in notifications reporting state changes for an alarm.";
description }
"Indicates that the severity level could not be
determined. This level SHOULD be avoided.";
}
enum warning {
value 3;
description
"The 'warning' severity level indicates the detection of a
potential or impending service affecting fault, before any
significant effects have been felt. Action should be
taken to further diagnose (if necessary) and correct the
problem in order to prevent it from becoming a more
serious service affecting fault.";
}
enum minor {
value 4;
description
"The 'minor' severity level indicates the existence of a
non-service affecting fault condition and that corrective
action should be taken in order to prevent a more serious
(for example, service affecting) fault. Such a severity
can be reported, for example, when the detected alarm
condition is not currently degrading the capacity of the
resource.";
}
enum major {
value 5;
description
"The 'major' severity level indicates that a service
affecting condition has developed and an urgent corrective
action is required. Such a severity can be reported, for
example, when there is a severe degradation in the
capability of the resource and its full capability must be
restored.";
}
enum critical {
value 6;
description
"The 'critical' severity level indicates that a service
affecting condition has occurred and an immediate
corrective action is required. Such a severity can be
reported, for example, when a resource becomes totally out
of service and its capability must be restored.";
}
}
description
"The severity level of the alarm. Note well that value 'clear'
is not included. If an alarm is cleared or not is a separate
boolean flag.";
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
}
typedef severity-with-clear { typedef writable-operator-state {
type union { type enumeration {
type enumeration { enum none {
enum cleared { value 1;
value 1; description
description "The alarm is not being taken care of.";
"The alarm is cleared by the instrumentation."; }
} enum ack {
} value 2;
type severity; description
} "The alarm is being taken care of. Corrective action not
description taken yet or has failed";
"The severity level of the alarm including clear. This is used }
only in notifications reporting state changes for an alarm."; enum closed {
} value 3;
description
"Corrective action taken successfully.";
}
}
description
"Operator states on an alarm. The 'closed' state indicates
that an operator considers the alarm being resolved. This is
separate from the alarm's 'is-cleared' leaf.";
}
typedef writable-operator-state { typedef operator-state {
type enumeration { type union {
enum none { type writable-operator-state;
value 1; type enumeration {
description enum shelved {
"The alarm is not being taken care of."; value 4;
} description
enum ack { "The alarm is shelved. Alarms in /alarms/shelved-alarms/
value 2; MUST be assigned this operator state by the server as
description the last entry in the 'operator-state-change' list. The
"The alarm is being taken care of. Corrective action not text for that entry SHOULD include the shelf name.";
taken yet, or failed"; }
} enum un-shelved {
enum closed { value 5;
value 3; description
description "The alarm is moved back to 'alarm-list' from a shelf.
"Corrective action taken successfully."; Alarms that are moved from /alarms/shelved-alarms/ to
} /alarms/alarm-list MUST be assigned this state by the
} server as the last entry in the 'operator-state-change'
description list. The text for that entry SHOULD include the shelf
"Operator states on an alarm. The 'closed' state indicates name.";
that an operator considers the alarm being resolved. This is }
separate from the alarm's 'is-cleared' leaf."; }
} }
description
"Operator states on an alarm. The 'closed' state indicates
that an operator considers the alarm being resolved. This is
separate from the alarm's 'is-cleared' leaf.";
}
typedef operator-state { /* Alarm type */
type union {
type writable-operator-state;
type enumeration {
enum shelved {
value 4;
description
"The alarm is shelved. Alarms in /alarms/shelved-alarms/
MUST be assigned this operator state by the server as
the last entry in the operator-state-change list. The
text for that entry SHOULD include the shelf name.";
}
enum un-shelved {
value 5;
description
"The alarm is moved back to 'alarm-list' from a shelf.
Alarms that are moved from /alarms/shelved-alarms/ to
/alarms/alarm-list MUST be assigned this state by the
server as the last entry in the 'operator-state-change'
list. The text for that entry SHOULD include the shelf
name.";
}
}
}
description
"Operator states on an alarm. The 'closed' state indicates
that an operator considers the alarm being resolved. This is
separate from the alarm's 'is-cleared' leaf.";
}
/* Alarm type */ typedef alarm-type-id {
type identityref {
base alarm-type-id;
}
description
"Identifies an alarm type. The description of the alarm type
id MUST indicate whether or not the alarm type is abstract.
An abstract alarm type is used as a base for other alarm type
ids and will not be used as a value for an alarm or be present
in the alarm inventory.";
}
typedef alarm-type-id { typedef alarm-type-qualifier {
type identityref { type string;
base alarm-type-id; description
} "If an alarm type cannot be fully specified at design time by
description 'alarm-type-id', this string qualifier is used in addition to
"Identifies an alarm type. The description of the alarm type fully define a unique alarm type.
id MUST indicate if the alarm type is abstract or not. An
abstract alarm type is used as a base for other alarm type ids
and will not be used as a value for an alarm or be present in
the alarm inventory.";
}
typedef alarm-type-qualifier { The definition of alarm qualifiers is considered to be part of
type string; the instrumentation and is out of scope for this module. An
description empty string is used when this is part of a key.";
"If an alarm type can not be fully specified at design time by }
alarm-type-id, this string qualifier is used in addition to
fully define a unique alarm type.
The definition of alarm qualifiers is considered being part of /*
the instrumentation and out of scope for this module. An * Groupings
empty string is used when this is part of a key."; */
}
/* grouping common-alarm-parameters {
* Groupings description
*/ "Common parameters for an alarm.
grouping common-alarm-parameters { This grouping is used both in the alarm list and in the
description notification representing an alarm-state change.";
"Common parameters for an alarm. leaf resource {
type resource;
mandatory true;
description
"The alarming resource. See also 'alt-resource'. This could
be, for example, a reference to the alarming interface";
}
leaf alarm-type-id {
type alarm-type-id;
mandatory true;
description
"This leaf and the leaf 'alarm-type-qualifier' together
provide a unique identification of the alarm type.";
}
leaf alarm-type-qualifier {
type alarm-type-qualifier;
description
"This leaf is used when the 'alarm-type-id' leaf cannot
uniquely identify the alarm type. Normally, this is not the
case, and this leaf is the empty string.";
}
leaf-list alt-resource {
type resource;
description
"Used if the alarming resource is available over other
interfaces. This field can contain SNMP OIDs, CIM paths, or
3GPP distinguished names, for example.";
}
list related-alarm {
if-feature "alarm-correlation";
key "resource alarm-type-id alarm-type-qualifier";
description
"References to related alarms. Note that the related alarm
might have been purged from the alarm list.";
leaf resource {
type leafref {
path "/alarms/alarm-list/alarm/resource";
require-instance false;
}
description
"The alarming resource for the related alarm.";
}
leaf alarm-type-id {
type leafref {
path "/alarms/alarm-list/alarm"
+ "[resource=current()/../resource]"
+ "/alarm-type-id";
This grouping is used both in the alarm list and in the require-instance false;
notification representing an alarm state change."; }
leaf resource { description
type resource; "The alarm type identifier for the related alarm.";
mandatory true; }
description leaf alarm-type-qualifier {
"The alarming resource. See also 'alt-resource'. This could type leafref {
for example be a reference to the alarming interface"; path "/alarms/alarm-list/alarm"
} + "[resource=current()/../resource]"
leaf alarm-type-id { + "[alarm-type-id=current()/../alarm-type-id]"
type alarm-type-id; + "/alarm-type-qualifier";
mandatory true; require-instance false;
description }
"This leaf and the leaf 'alarm-type-qualifier' together description
provides a unique identification of the alarm type."; "The alarm qualifier for the related alarm.";
} }
leaf alarm-type-qualifier { }
type alarm-type-qualifier; leaf-list impacted-resource {
description if-feature "service-impact-analysis";
"This leaf is used when the 'alarm-type-id' leaf cannot type resource;
uniquely identify the alarm type. Normally, this is not the description
case, and this leaf is the empty string."; "Resources that might be affected by this alarm. If the
} system creates an alarm on a resource and also has a mapping
leaf-list alt-resource { to other resources that might be impacted, these resources
type resource; can be listed in this leaf-list. In this way, the system
description can create one alarm instead of several. For example, if an
"Used if the alarming resource is available over other interface has an alarm, the 'impacted-resource' can
interfaces. This field can contain SNMP OIDs, CIM paths or reference the aggregated port channels.";
3GPP Distinguished names for example."; }
} leaf-list root-cause-resource {
list related-alarm { if-feature "root-cause-analysis";
if-feature "alarm-correlation"; type resource;
key "resource alarm-type-id alarm-type-qualifier"; description
description "Resources that are candidates for causing the alarm. If the
"References to related alarms. Note that the related alarm system has a mechanism to understand the candidate root
might have been purged from the alarm list."; causes of an alarm, this leaf-list can be used to list the
leaf resource { root-cause candidate resources. In this way, the system can
type leafref { create one alarm instead of several. An example might be a
path "/alarms/alarm-list/alarm/resource"; logging system (alarm resource) that fails; the alarm can
require-instance false; reference the file system in the 'root-cause-resource'
} leaf-list. Note that the intended use is not to also send
description an alarm with the 'root-cause-resource' as an alarming
"The alarming resource for the related alarm."; resource. The 'root-cause-resource' leaf-list is a hint and
} should not also generate an alarm for the same problem.";
leaf alarm-type-id { }
type leafref { }
path "/alarms/alarm-list/alarm"
+ "[resource=current()/../resource]"
+ "/alarm-type-id";
require-instance false;
}
description
"The alarm type identifier for the related alarm.";
}
leaf alarm-type-qualifier {
type leafref {
path "/alarms/alarm-list/alarm"
+ "[resource=current()/../resource]"
+ "[alarm-type-id=current()/../alarm-type-id]"
+ "/alarm-type-qualifier";
require-instance false;
}
description
"The alarm qualifier for the related alarm.";
}
}
leaf-list impacted-resource {
if-feature "service-impact-analysis";
type resource;
description
"Resources that might be affected by this alarm. If the
system creates an alarm on a resource and also has a mapping
to other resources that might be impacted, these resources
can be listed in this leaf-list. In this way the system can
create one alarm instead of several. For example, if an
interface has an alarm, the 'impacted-resource' can
reference the aggregated port channels.";
}
leaf-list root-cause-resource {
if-feature "root-cause-analysis";
type resource;
description
"Resources that are candidates for causing the alarm. If the
system has a mechanism to understand the candidate root
causes of an alarm, this leaf-list can be used to list the
root cause candidate resources. In this way the system can
create one alarm instead of several. An example might be a
logging system (alarm resource) that fails, the alarm can
reference the file-system in the 'root-cause-resource'
leaf-list. Note that the intended use is not to also send
an an alarm with the root-cause-resource as alarming
resource. The root-cause-resource leaf list is a hint and
should not also generate an alarm for the same problem.";
}
}
grouping alarm-state-change-parameters { grouping alarm-state-change-parameters {
description description
"Parameters for an alarm state change. "Parameters for an alarm-state change.
This grouping is used both in the alarm list's status-change This grouping is used both in the alarm list's status-change
list and in the notification representing an alarm state list and in the notification representing an alarm-state
change."; change.";
leaf time { leaf time {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
description description
"The time the status of the alarm changed. The value "The time the status of the alarm changed. The value
represents the time the real alarm state change appeared in represents the time the real alarm-state change appeared in
the resource and not when it was added to the alarm the resource and not when it was added to the alarm
list. The /alarm-list/alarm/last-changed MUST be set to the list. The /alarm-list/alarm/last-changed MUST be set to the
same value."; same value.";
} }
leaf perceived-severity { leaf perceived-severity {
type severity-with-clear; type severity-with-clear;
mandatory true; mandatory true;
description description
"The severity of the alarm as defined by X.733. Note that "The severity of the alarm as defined by X.733. Note that
this may not be the original severity since the alarm may this may not be the original severity since the alarm may
have changed severity."; have changed severity.";
reference reference
"ITU Recommendation X.733: Information Technology "ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function"; - System Management: Alarm Reporting Function";
} }
leaf alarm-text { leaf alarm-text {
type alarm-text; type alarm-text;
mandatory true; mandatory true;
description description
"A user friendly text describing the alarm state change."; "A user-friendly text describing the alarm-state change.";
reference reference
"ITU Recommendation X.733: Information Technology "ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function"; - System Management: Alarm Reporting Function";
} }
} }
grouping operator-parameters { grouping operator-parameters {
description description
"This grouping defines parameters that can be changed by an "This grouping defines parameters that can be changed by an
operator."; operator.";
leaf time { leaf time {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
description description
"Timestamp for operator action on alarm."; "Timestamp for operator action on the alarm.";
} }
leaf operator { leaf operator {
type string; type string;
mandatory true; mandatory true;
description description
"The name of the operator that has acted on this alarm."; "The name of the operator that has acted on this alarm.";
} }
leaf state { leaf state {
type operator-state; type operator-state;
mandatory true; mandatory true;
description description
"The operator's view of the alarm state."; "The operator's view of the alarm state.";
} }
leaf text { leaf text {
type string; type string;
description description
"Additional optional textual information provided by the "Additional optional textual information provided by the
operator."; operator.";
} }
} }
grouping resource-alarm-parameters { grouping resource-alarm-parameters {
description description
"Alarm parameters that originates from the resource view."; "Alarm parameters that originate from the resource view.";
leaf is-cleared { leaf is-cleared {
type boolean; type boolean;
mandatory true; mandatory true;
description description
"Indicates the current clearance state of the alarm. An "Indicates the current clearance state of the alarm. An
alarm might toggle from active alarm to cleared alarm and alarm might toggle from active alarm to cleared alarm and
back to active again."; back to active again.";
} }
leaf last-raised { leaf last-raised {
type yang:date-and-time; type yang:date-and-time;
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 lifetime. This leaf indicates
the last time it was last raised (is-cleared = false)."; the last time it was 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 'status-change' or "A timestamp when the 'status-change' or
'operator-state-change' list was last changed."; 'operator-state-change' list was last changed.";
} }
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'.";
} }
leaf alarm-text { leaf alarm-text {
type alarm-text; type alarm-text;
mandatory true; mandatory true;
description description
"The last reported alarm text. This text should contain "The last reported alarm text. This text should contain
information for an operator to be able to understand the information for an operator to be able to understand the
problem and how to resolve it."; problem and how to resolve it.";
} }
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 timestamp 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. and 'alarm-text' for the alarm.
This list is ordered according to the timestamps of alarm This list is ordered according to the timestamps of alarm
state changes. The first 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 create 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;
} }
} }
grouping filter-input { grouping filter-input {
description description
"Grouping to specify a filter construct on alarm information."; "Grouping to specify a filter construct on alarm information.";
leaf alarm-clearance-status { leaf alarm-clearance-status {
type enumeration { type enumeration {
enum any { enum any {
description description
"Ignore alarm clearance status."; "Ignore alarm-clearance status.";
} }
enum cleared { enum cleared {
description description
"Filter cleared alarms."; "Filter cleared alarms.";
} }
enum not-cleared { enum not-cleared {
description description
"Filter not cleared alarms."; "Filter not-cleared alarms.";
} }
} }
mandatory true; mandatory true;
description description
"The clearance status of the alarm."; "The clearance status of the alarm.";
} }
container older-than { container older-than {
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
"Age expressed in seconds."; "Age expressed in seconds.";
} }
} }
case minutes { case minutes {
leaf minutes { leaf minutes {
type uint16; type uint16;
description description
"Age expressed in minutes."; "Age expressed in minutes.";
} }
} }
case hours { case hours {
leaf hours { leaf hours {
type uint16; type uint16;
description description
"Age expressed in hours."; "Age expressed in hours.";
} }
} }
case days { case days {
leaf days { leaf days {
type uint16; type uint16;
description description
"Age expressed in days."; "Age expressed in days.";
} }
} }
case weeks { case weeks {
leaf weeks { leaf weeks {
type uint16; type uint16;
description description
"Age expressed in weeks."; "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 {
type severity; type severity;
description description
"Severity less than this leaf."; "Severity less than this leaf.";
} }
leaf is { leaf is {
type severity; type severity;
description description
"Severity level equal this leaf."; "Severity level equal to this leaf.";
} }
leaf above { leaf above {
type severity; type severity;
description description
"Severity level higher than this leaf."; "Severity level higher than this leaf.";
} }
} }
description description
"Filter based on severity."; "Filter based on severity.";
} }
container operator-state-filter { container operator-state-filter {
if-feature "operator-actions"; if-feature "operator-actions";
presence "Operator state filter"; presence "Operator state filter";
leaf state { leaf state {
type operator-state; type operator-state;
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
"Filter based on operator state.";
} }
} description
"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 behavior."; "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.";
} }
} }
} }
default "32"; default "32";
description description
"The status-change entries are kept in a circular list per "The 'status-change' entries are kept in a circular list
alarm. When this number is exceeded, the oldest status per alarm. When this number is exceeded, the oldest
change entry is automatically removed. If the value is status change entry is automatically removed. If the
'infinite', the status change entries are accumulated value is 'infinite', the status-change entries are
infinitely."; accumulated infinitely.";
} }
leaf notify-status-changes { leaf notify-status-changes {
type enumeration { type enumeration {
enum all-state-changes { enum all-state-changes {
description description
"Send notifications for all status changes."; "Send notifications for all status changes.";
} }
enum raise-and-clear { enum raise-and-clear {
description description
"Send notifications only for raise, clear, and "Send notifications only for raise, clear, and
re-raise. Notifications for severity level changes or re-raise. Notifications for severity-level changes or
alarm text changes are not sent."; alarm-text changes are not sent.";
} }
enum severity-level { enum severity-level {
description description
"Only send notifications for alarm state changes "Only send notifications for alarm-state changes
crossing the level specified in crossing the level specified in
'notify-severity-level'. Always send clear 'notify-severity-level'. Always send clear
notifications."; notifications.";
} }
} }
must '. != "severity-level" or ../notify-severity-level' { must '. != "severity-level" or ../notify-severity-level' {
description description
"When notify-status-changes is 'severity-level', a value "When notify-status-changes is 'severity-level', a value
must be given for notify-severity-level."; must be given for 'notify-severity-level'.";
} }
default "all-state-changes"; default "all-state-changes";
description description
"This leaf controls the notifications sent for alarm status "This leaf controls the notifications sent for alarm status
updates. There are three options: updates. There are three options:
1. Notifications are sent for all updates, severity level 1. Notifications are sent for all updates, severity-level
changes and alarm text changes changes, and alarm-text changes.
2. Notifications are only sent for alarm raise and clear 2. Notifications are only sent for alarm raise and clear.
3. Notifications are sent for status changes equal to or 3. Notifications are sent for status changes equal to or
above the specified severity level. Clear above the specified severity level. Clear
notifications shall always be sent. Notifications shall notifications shall always be sent. Notifications
also be sent for state changes that makes an alarm less shall also be sent for state changes that make an
severe than the specified level. alarm less severe than the specified level.
For example, in option 3, assuming the severity level is For example, in option 3, assume that the severity level
set to major and that the alarm has the following state is set to major and that the alarm has the following state
changes: changes:
[(Time, severity, clear)]: [(Time, severity, clear)]:
[(T1, major, -), (T2, minor, -), (T3, warning, -), [(T1, major, -), (T2, minor, -), (T3, warning, -),
(T4, minor, -), (T5, major, -), (T6, critical, -), (T4, minor, -), (T5, major, -), (T6, critical, -),
(T7, major. -), (T8, major, clear)] (T7, major. -), (T8, major, clear)]
In that case, notifications will be sent at times In that case, notifications will be sent at times
T1, T2, T5, T6, T7 and T8."; T1, T2, T5, T6, T7, and T8.";
} }
leaf notify-severity-level { leaf notify-severity-level {
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 conditions in the shelf (block/filter) alarms. The conditions in the shelf
criteria are logically ANDed. The first matching shelf is criteria are logically ANDed. The first matching shelf is
used, and an alarm is shelved only for this first match. used, and an alarm is shelved only for this first match.
Matching alarms MUST appear in the Matching alarms MUST appear in the
/alarms/shelved-alarms/shelved-alarm list, and /alarms/shelved-alarms/shelved-alarm list, and
non-matching /alarms MUST appear in the non-matching /alarms MUST appear in the
/alarms/alarm-list/alarm list. The server does not send /alarms/alarm-list/alarm list. The server does not send
any notifications for shelved alarms. any notifications for shelved alarms.
The server MUST maintain states (e.g., severity The server MUST maintain states (e.g., severity
changes) for the shelved alarms. changes) for the shelved alarms.
Alarms that match the criteria shall have an Alarms that match the criteria shall have an
operator state 'shelved'. When the shelf operator state 'shelved'. When the shelf
configuration removes an alarm from the shelf the server configuration removes an alarm from the shelf, the server
shall add an operator state 'un-shelved'."; shall add the 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.
Criteria are ANDed. If no criteria are specified, Criteria are ANDed. If no criteria are specified,
all alarms will be shelved."; all alarms will be shelved.";
leaf-list resource { leaf-list resource {
type resource-match; type resource-match;
description description
"Shelve alarms for matching resources."; "Shelve alarms for matching resources.";
} }
list alarm-type { list alarm-type {
key "alarm-type-id alarm-type-qualifier-match"; key "alarm-type-id alarm-type-qualifier-match";
description description
"Any alarm matching the combined criteria of "Any alarm matching the combined criteria of
alarm-type-id and alarm-type-qualifier-match 'alarm-type-id' and 'alarm-type-qualifier-match'
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
equal to or derived from the given alarm-type-id."; is equal to or derived from the given
} 'alarm-type-id'.";
leaf alarm-type-qualifier-match {
type string;
description
"An XML Schema regular expression that is used to
match an alarm type qualifier. Shelve all alarms
that matches this regular expression for the alarm
type qualifier.";
reference
"XML Schema Part 2: Datatypes Second Edition,
World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028";
}
}
leaf description {
type string;
description
"An optional textual description of the shelf. This
description should include the reason for shelving
these alarms.";
}
}
}
}
container alarm-inventory {
config false;
description
"This alarm-inventory/alarm-type list contains all possible
alarm types for the system.
If the system knows for which resources a specific alarm }
type can appear, this is also identified in the inventory. leaf alarm-type-qualifier-match {
The list also tells if each alarm type has a corresponding type string;
clear state. The inventory shall only contain concrete description
alarm types. "An XML Schema regular expression that is used to
match an alarm type qualifier. Shelve all alarms
that match this regular expression for the alarm
type qualifier.";
reference
"XML Schema Part 2: Datatypes Second Edition,
World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028";
}
}
leaf description {
type string;
description
"An optional textual description of the shelf. This
description should include the reason for shelving
these alarms.";
}
}
}
}
container alarm-inventory {
config false;
description
"The 'alarm-inventory/alarm-type' list contains all possible
alarm types for the system.
The alarm inventory MUST be updated by the system when new If the system knows for which resources a specific alarm
alarms can appear. This can be the case when installing new type can appear, it is also identified in the inventory.
software modules or inserting new card types. A The list also tells if each alarm type has a corresponding
notification 'alarm-inventory-changed' is sent when the clear state. The inventory shall only contain concrete
inventory is changed."; alarm types.
list alarm-type {
key "alarm-type-id alarm-type-qualifier";
description
"An entry in this list defines a possible alarm.";
leaf alarm-type-id {
type alarm-type-id;
description
"The statically defined alarm type identifier for this
possible alarm.";
}
leaf alarm-type-qualifier {
type alarm-type-qualifier;
description
"The optionally dynamically defined alarm type identifier
for this possible alarm.";
}
leaf-list resource {
type resource-match;
description
"Optionally, specifies for which resources the alarm type
is valid.";
}
leaf will-clear {
type boolean;
mandatory true;
description
"This leaf tells the operator if the alarm will be
cleared when the correct corrective action has been
taken. Implementations SHOULD strive for detecting the
cleared state for all alarm types.
If this leaf is 'true', the operator can monitor the The alarm inventory MUST be updated by the system when new
alarm until it becomes cleared after the corrective alarms can appear. This can be the case when installing new
action has been taken. software modules or inserting new card types. A
notification 'alarm-inventory-changed' is sent when the
inventory is changed.";
list alarm-type {
key "alarm-type-id alarm-type-qualifier";
description
"An entry in this list defines a possible alarm.";
leaf alarm-type-id {
type alarm-type-id;
description
"The statically defined alarm type identifier for this
possible alarm.";
}
leaf alarm-type-qualifier {
type alarm-type-qualifier;
description
"The optionally dynamically defined alarm type identifier
for this possible alarm.";
}
leaf-list resource {
type resource-match;
description
"Optionally, specifies for which resources the alarm type
is valid.";
}
leaf will-clear {
type boolean;
mandatory true;
description
"This leaf tells the operator if the alarm will be
cleared when the correct corrective action has been
taken. Implementations SHOULD strive for detecting the
cleared state for all alarm types.
If this leaf is 'false', the operator needs to validate If this leaf is 'true', the operator can monitor the
that the alarm is no longer active using other alarm until it becomes cleared after the corrective
mechanisms. Alarms can lack a corresponding clear due action has been taken.
to missing instrumentation or that there is no logical
corresponding clear state.";
}
leaf-list severity-levels {
type severity;
description
"This leaf-list indicates the possible severity levels of
this alarm type. Note well that 'clear' is not part of
the severity type. In general, the severity level
should be defined by the instrumentation based on
dynamic state and not defined statically by the alarm
type in order to provide relevant severity level based
on dynamic state and context. However most alarm types
have a defined set of possible severity levels and this
should be provided here.";
}
leaf description {
type string;
mandatory true;
description
"A description of the possible alarm. It SHOULD include
information on possible underlying root causes and
corrective actions.";
}
}
}
container summary {
if-feature "alarm-summary";
config false;
description
"This container gives a summary of number of alarms.";
list alarm-summary {
key "severity";
description
"A global summary of all alarms in the system. The summary
does not include shelved alarms.";
leaf severity {
type severity;
description
"Alarm summary for this severity level.";
}
leaf total {
type yang:gauge32;
description
"Total number of alarms of this severity level.";
}
leaf not-cleared {
type yang:gauge32;
description
"Total number of alarms of this severity level
that are not cleared.";
}
leaf cleared {
type yang:gauge32;
description
"For this severity level, the number of alarms that are
cleared.";
}
leaf cleared-not-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
cleared but not closed.";
}
leaf cleared-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
cleared and closed.";
}
leaf not-cleared-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
not cleared but closed.";
}
leaf not-cleared-not-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
not cleared and not closed.";
}
}
leaf shelves-active {
if-feature "alarm-shelving";
type empty;
description
"This is a hint to the operator that there are active
alarm shelves. This leaf MUST exist if the
/alarms/shelved-alarms/number-of-shelved-alarms is > 0.";
}
}
container alarm-list {
config false;
description
"The alarms in the system.";
leaf number-of-alarms {
type yang:gauge32;
description
"This object shows the total number of
alarms in the system, i.e., the total number
of entries in the alarm list.";
}
leaf last-changed {
type yang:date-and-time;
description
"A timestamp when the alarm list was last
changed. The value can be used by a manager to
initiate an alarm resynchronization procedure.";
}
list alarm {
key "resource alarm-type-id alarm-type-qualifier";
description
"The list of alarms. Each entry in the list holds one
alarm for a given alarm type and resource. An alarm can
be updated from the underlying resource or by the user.
The following leafs are maintained by the resource:
is-cleared, last-change, perceived-severity, and
alarm-text. An operator can change: operator-state and
operator-text.
Entries appear in the alarm list the first time an alarm If this leaf is 'false', the operator needs to validate
becomes active for a given alarm-type and resource. that the alarm is no longer active using other
Entries do not get deleted when the alarm is cleared. mechanisms. Alarms can lack a corresponding clear due
Clear status is represented as a boolean flag. to missing instrumentation or no logical
corresponding clear state.";
}
leaf-list severity-level {
type severity;
description
"This leaf-list indicates the possible severity levels of
this alarm type. Note well that 'clear' is not part of
the severity type. In general, the severity level
should be defined by the instrumentation based on the
dynamic state, rather than being defined statically by
the alarm type, in order to provide a relevant severity
level based on dynamic state and context. However, most
alarm types have a defined set of possible severity
levels, and this should be provided here.";
}
leaf description {
type string;
mandatory true;
description
"A description of the possible alarm. It SHOULD include
information on possible underlying root causes and
corrective actions.";
}
}
}
container summary {
if-feature "alarm-summary";
config false;
description
"This container gives a summary of the number of alarms.";
list alarm-summary {
key "severity";
description
"A global summary of all alarms in the system. The summary
does not include shelved alarms.";
leaf severity {
type severity;
description
"Alarm summary for this severity level.";
}
leaf total {
type yang:gauge32;
description
"Total number of alarms of this severity level.";
}
leaf not-cleared {
type yang:gauge32;
description
"Total number of alarms of this severity level
that are not cleared.";
}
leaf cleared {
type yang:gauge32;
description
"For this severity level, the number of alarms that are
cleared.";
}
leaf cleared-not-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
cleared but not closed.";
}
leaf cleared-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
cleared and closed.";
}
leaf not-cleared-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
not cleared but closed.";
}
leaf not-cleared-not-closed {
if-feature "operator-actions";
type yang:gauge32;
description
"For this severity level, the number of alarms that are
not cleared and not closed.";
}
}
leaf shelves-active {
if-feature "alarm-shelving";
type empty;
description
"This is a hint to the operator that there are active
alarm shelves. This leaf MUST exist if the
/alarms/shelved-alarms/number-of-shelved-alarms is > 0.";
}
}
container alarm-list {
config false;
description
"The alarms in the system.";
leaf number-of-alarms {
type yang:gauge32;
description
"This object shows the total number of
alarms in the system, i.e., the total number
of entries in the alarm list.";
}
leaf last-changed {
type yang:date-and-time;
description
"A timestamp when the alarm list was last
changed. The value can be used by a manager to
initiate an alarm resynchronization procedure.";
Alarm entries are removed, purged, from the list by an }
explicit purge action. For example, purge all alarms that list alarm {
are cleared and in closed operator-state that are older key "resource alarm-type-id alarm-type-qualifier";
than 24 hours. Purged alarms are removed from the alarm description
list. If the alarm resource state changes after a purge, "The list of alarms. Each entry in the list holds one
the alarm will reappear in the alarm list. alarm for a given alarm type and resource. An alarm can
be updated from the underlying resource or by the user.
The following leafs are maintained by the resource:
'is-cleared', 'last-change', 'perceived-severity', and
'alarm-text'. An operator can change 'operator-state' and
'operator-text'.
Systems may also remove alarms based on locally configured Entries appear in the alarm list the first time an alarm
policies which is out of scope for this module."; becomes active for a given alarm type and resource.
uses common-alarm-parameters; Entries do not get deleted when the alarm is cleared.
leaf time-created { Clear status is represented as a boolean flag.
type yang:date-and-time;
mandatory true;
description
"The time-stamp when this alarm entry was created. This
represents the first time the alarm appeared, it can
also represent that the alarm re-appeared after a purge.
Further state-changes of the same alarm does not change
this leaf, these changes will update the 'last-changed'
leaf.";
}
uses resource-alarm-parameters;
list operator-state-change {
if-feature "operator-actions";
key "time";
description
"This list is used by operators to indicate the state of
human intervention on an alarm. For example, if an
operator has seen an alarm, the operator can add a new
item to this list indicating that the alarm is
acknowledged.";
uses operator-parameters;
}
action set-operator-state {
if-feature "operator-actions";
description
"This is a means for the operator to indicate the level
of human intervention on an alarm.";
input {
leaf state {
type writable-operator-state;
mandatory true;
description
"Set this operator state.";
}
leaf text {
type string;
description
"Additional optional textual information.";
}
}
}
notification operator-action {
if-feature "operator-actions";
description
"This notification is used to report that an operator
acted upon an alarm.";
uses operator-parameters;
}
}
action purge-alarms {
description
"This operation requests the server to delete entries from
the alarm list according to the supplied criteria.
Typically this operation is used to delete alarms that are Alarm entries are removed, i.e., purged, from the list by
in closed operator state and older than a specified time. an explicit purge action. For example, purge all alarms
that are cleared and in closed operator state that are
older than 24 hours. Purged alarms are removed from the
alarm list. If the alarm resource state changes after a
purge, the alarm will reappear in the alarm list.
The number of purged alarms is returned as an output Systems may also remove alarms based on locally configured
parameter."; policies; this is out of scope for this module.";
input { uses common-alarm-parameters;
uses filter-input; leaf time-created {
} type yang:date-and-time;
output { mandatory true;
leaf purged-alarms { description
type uint32; "The timestamp when this alarm entry was created. This
description represents the first time the alarm appeared; it can
"Number of purged alarms."; also represent that the alarm reappeared after a purge.
} Further state changes of the same alarm do not change
} this leaf; these changes will update the 'last-changed'
} leaf.";
action compress-alarms { }
if-feature "alarm-history"; uses resource-alarm-parameters;
description list operator-state-change {
"This operation requests the server to compress entries in if-feature "operator-actions";
the alarm list by removing all but the latest key "time";
'status-change' entry for all matching alarms. Conditions description
in the input are logically ANDed. If no input condition "This list is used by operators to indicate the state of
is given, all alarms are compressed."; human intervention on an alarm. For example, if an
input { operator has seen an alarm, the operator can add a new
leaf resource { item to this list indicating that the alarm is
type resource-match; acknowledged.";
description
"Compress the alarms matching this resource.";
}
leaf alarm-type-id {
type leafref {
path "/alarms/alarm-list/alarm/alarm-type-id";
require-instance false;
}
description
"Compress alarms with this alarm-type-id.";
}
leaf alarm-type-qualifier {
type leafref {
path "/alarms/alarm-list/alarm/alarm-type-qualifier";
require-instance false;
}
description
"Compress the alarms with this alarm-type-qualifier.";
}
}
output {
leaf compressed-alarms {
type uint32;
description
"Number of compressed alarm entries.";
}
}
}
}
container shelved-alarms {
if-feature "alarm-shelving";
config false;
description
"The shelved alarms. Alarms appear here if they match the
criteria in /alarms/control/alarm-shelving. This list does
not generate any notifications. The list represents alarms
that are considered not relevant by the operator. Alarms in
this list have an operator-state of 'shelved'. This can not
be changed.";
leaf number-of-shelved-alarms { uses operator-parameters;
type yang:gauge32; }
description action set-operator-state {
"This object shows the total number of currently if-feature "operator-actions";
alarms, i.e., the total number of entries description
in the alarm list."; "This is a means for the operator to indicate the level
} of human intervention on an alarm.";
leaf shelved-alarms-last-changed { input {
type yang:date-and-time; leaf state {
description type writable-operator-state;
"A timestamp when the shelved alarm list was last changed. mandatory true;
The value can be used by a manager to initiate an alarm description
resynchronization procedure."; "Set this operator state.";
} }
list shelved-alarm { leaf text {
key "resource alarm-type-id alarm-type-qualifier"; type string;
description description
"The list of shelved alarms. Shelved alarms can only be "Additional optional textual information.";
updated from the underlying resource, no operator actions }
are supported."; }
uses common-alarm-parameters; }
leaf shelf-name { notification operator-action {
type leafref { if-feature "operator-actions";
path "/alarms/control/alarm-shelving/shelf/name"; description
require-instance false; "This notification is used to report that an operator
} acted upon an alarm.";
description uses operator-parameters;
"The name of the shelf."; }
} }
uses resource-alarm-parameters; action purge-alarms {
list operator-state-change { description
if-feature "operator-actions"; "This operation requests that the server delete entries
key "time"; from the alarm list according to the supplied criteria.
description
"This list is used by operators to indicate the state of
human intervention on an alarm. For shelved alarms, the
system has set the list item in the list to 'shelved'.";
uses operator-parameters;
}
}
action purge-shelved-alarms {
description
"This operation requests the server to delete entries from
the shelved alarms list according to the supplied
criteria.
In the shelved alarm list it makes sense to delete alarms Typically, this operation is used to delete alarms that
that are not relevant anymore. are in closed operator state and older than a specified
time.
The number of purged alarms is returned as an output The number of purged alarms is returned as an output
parameter."; parameter.";
input { input {
uses filter-input; uses filter-input;
} }
output { output {
leaf purged-alarms { leaf purged-alarms {
type uint32; type uint32;
description description
"Number of purged alarms."; "Number of purged alarms.";
}
}
}
action compress-shelved-alarms {
if-feature "alarm-history";
description
"This operation requests the server to compress entries in
the shelved alarm list by removing all but the latest
'status-change' entry for all matching shelved alarms.
Conditions in the input are logically ANDed. If no input
condition is given, all alarms are compressed.";
input {
leaf resource {
type leafref {
path "/alarms/shelved-alarms/shelved-alarm/resource";
require-instance false;
}
description
"Compress the alarms with this resource.";
}
leaf alarm-type-id {
type leafref {
path "/alarms/shelved-alarms/shelved-alarm"
+ "/alarm-type-id";
require-instance false;
}
description
"Compress alarms with this alarm-type-id.";
}
leaf alarm-type-qualifier {
type leafref {
path "/alarms/shelved-alarms/shelved-alarm"
+ "/alarm-type-qualifier";
require-instance false;
}
description
"Compress the alarms with this alarm-type-qualifier.";
}
} }
output { }
leaf compressed-alarms { }
type uint32; action compress-alarms {
description if-feature "alarm-history";
"Number of compressed alarm entries."; description
} "This operation requests that the server compress
} entries in the alarm list by removing all but the
} latest 'status-change' entry for all matching alarms.
} Conditions in the input are logically ANDed. If no
list alarm-profile { input condition is given, all alarms are compressed.";
if-feature "alarm-profile"; input {
key "alarm-type-id alarm-type-qualifier-match resource"; leaf resource {
ordered-by user; type resource-match;
description description
"This list is used to assign further information or "Compress the alarms matching this resource.";
configuration for each alarm type. This module supports a }
mechanism where the client can override the system default leaf alarm-type-id {
alarm severity levels. The alarm-profile is also a useful type leafref {
augmentation point for specific additions to alarm types."; path "/alarms/alarm-list/alarm/alarm-type-id";
leaf alarm-type-id { require-instance false;
type alarm-type-id; }
description description
"The alarm type identifier to match."; "Compress alarms with this 'alarm-type-id'.";
} }
leaf alarm-type-qualifier-match { leaf alarm-type-qualifier {
type string; type leafref {
description path "/alarms/alarm-list/alarm/alarm-type-qualifier";
"An XML Schema regular expression that is used to match the require-instance false;
alarm type qualifier."; }
reference description
"XML Schema Part 2: Datatypes Second Edition, "Compress the alarms with this
World Wide Web Consortium Recommendation 'alarm-type-qualifier'.";
REC-xmlschema-2-20041028"; }
} }
leaf resource { output {
type resource-match; leaf compressed-alarms {
description type uint32;
"Specifies which resources to match."; description
} "Number of compressed alarm entries.";
leaf description { }
type string; }
mandatory true; }
description }
"A description of the alarm profile."; container shelved-alarms {
} if-feature "alarm-shelving";
container alarm-severity-assignment-profile { config false;
if-feature "severity-assignment"; description
description "The shelved alarms. Alarms appear here if they match the
"The client can override the system default severity criteria in /alarms/control/alarm-shelving. This list does
level."; not generate any notifications. The list represents alarms
reference that are considered not relevant by the operator. Alarms in
"ITU M.3100, ITU M.3160 this list have an 'operator-state' of 'shelved'. This
- Generic Network Information Model, Alarm Severity cannot be changed.";
Assignment Profile"; leaf number-of-shelved-alarms {
leaf-list severity-levels { type yang:gauge32;
type severity; description
ordered-by user; "This object shows the total number of current
description alarms, i.e., the total number of entries
"Specifies the configured severity level(s) for the in the alarm list.";
matching alarm. If the alarm has several severity }
levels the leaf-list shall be given in rising severity leaf shelved-alarms-last-changed {
order. The original M3100/M3160 ASAP function only type yang:date-and-time;
allows for a one-to-one mapping between alarm type and description
severity but since the IETF alarm module supports "A timestamp when the shelved-alarm list was last changed.
stateful alarms the mapping must allow for several The value can be used by a manager to initiate an alarm
severity levels. resynchronization procedure.";
}
list shelved-alarm {
key "resource alarm-type-id alarm-type-qualifier";
description
"The list of shelved alarms. Shelved alarms can only be
updated from the underlying resource; no operator actions
are supported.";
uses common-alarm-parameters;
leaf shelf-name {
type leafref {
path "/alarms/control/alarm-shelving/shelf/name";
require-instance false;
}
description
"The name of the shelf.";
}
uses resource-alarm-parameters;
list operator-state-change {
if-feature "operator-actions";
key "time";
description
"This list is used by operators to indicate the state of
human intervention on an alarm. For shelved alarms, the
system has set the list item in the list to 'shelved'.";
uses operator-parameters;
}
}
action purge-shelved-alarms {
description
"This operation requests that the server delete entries from
the shelved-alarm list according to the supplied criteria.
In the shelved-alarm list, it makes sense to delete alarms
that are not relevant anymore.
Assume a high-utilization alarm type with two thresholds The number of purged alarms is returned as an output
with the system default severity levels of threshold1 = parameter.";
warning and threshold2 = minor. Setting this leaf-list input {
to (minor, major) will assign the severity levels uses filter-input;
threshold1 = minor and threshold2 = major"; }
} output {
} leaf purged-alarms {
} type uint32;
} description
"Number of purged alarms.";
}
}
}
action compress-shelved-alarms {
if-feature "alarm-history";
description
"This operation requests that the server compress entries
in the shelved-alarm list by removing all but the latest
'status-change' entry for all matching shelved alarms.
Conditions in the input are logically ANDed. If no input
condition is given, all alarms are compressed.";
input {
leaf resource {
type leafref {
path "/alarms/shelved-alarms/shelved-alarm/resource";
require-instance false;
}
description
"Compress the alarms with this resource.";
}
leaf alarm-type-id {
type leafref {
path "/alarms/shelved-alarms/shelved-alarm"
+ "/alarm-type-id";
require-instance false;
}
description
"Compress alarms with this 'alarm-type-id'.";
}
leaf alarm-type-qualifier {
type leafref {
path "/alarms/shelved-alarms/shelved-alarm"
+ "/alarm-type-qualifier";
/* require-instance false;
* Notifications }
*/ description
"Compress the alarms with this
'alarm-type-qualifier'.";
}
}
output {
leaf compressed-alarms {
type uint32;
description
"Number of compressed alarm entries.";
}
}
}
}
list alarm-profile {
if-feature "alarm-profile";
key "alarm-type-id alarm-type-qualifier-match resource";
ordered-by user;
description
"This list is used to assign further information or
configuration for each alarm type. This module supports a
mechanism where the client can override the system-default
alarm severity levels. The 'alarm-profile' is also a useful
augmentation point for specific additions to alarm types.";
leaf alarm-type-id {
type alarm-type-id;
description
"The alarm type identifier to match.";
}
leaf alarm-type-qualifier-match {
type string;
description
"An XML Schema regular expression that is used to match the
alarm type qualifier.";
reference
"XML Schema Part 2: Datatypes Second Edition,
World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028";
}
leaf resource {
type resource-match;
description
"Specifies which resources to match.";
}
leaf description {
type string;
mandatory true;
description
"A description of the alarm profile.";
}
container alarm-severity-assignment-profile {
if-feature "severity-assignment";
description
"The client can override the system-default severity
level.";
reference
"ITU-T Recommendation M.3100:
Generic network information model
ITU-T Recommendation M.3160:
Generic, protocol-neutral management information model";
leaf-list severity-level {
type severity;
ordered-by user;
description
"Specifies the configured severity level(s) for the
matching alarm. If the alarm has several severity
levels, the leaf-list shall be given in rising severity
order. The original M3100/M3160 ASAP function only
allows for a one-to-one mapping between alarm type and
severity, but since YANG module supports stateful
alarms, the mapping must allow for several severity
levels.
notification alarm-notification { Assume a high-utilization alarm type with two thresholds
description with the system-default severity levels of threshold1 =
"This notification is used to report a state change for an warning and threshold2 = minor. Setting this leaf-list
alarm. The same notification is used for reporting a newly to (minor, major) will assign the severity levels as
raised alarm, a cleared alarm or changing the text and/or threshold1 = minor and threshold2 = major";
severity of an existing alarm."; }
uses common-alarm-parameters; }
uses alarm-state-change-parameters; }
} }
notification alarm-inventory-changed { /*
description * Notifications
"This notification is used to report that the list of possible */
alarms has changed. This can happen when for example if a new
software module is installed, or a new physical card is
inserted.";
}
}
<CODE ENDS> notification alarm-notification {
description
"This notification is used to report a state change for an
alarm. The same notification is used for reporting a newly
raised alarm, a cleared alarm, or changing the text and/or
severity of an existing alarm.";
uses common-alarm-parameters;
uses alarm-state-change-parameters;
}
7. X.733 Extensions notification alarm-inventory-changed {
description
"This notification is used to report that the list of possible
alarms has changed. This can happen when, for example, a new
software module is installed or a new physical card is
inserted.";
}
}
<CODE ENDS>
Many alarm systems are based on the X.733, [X.733], and X.736 [X.736] 7. The X.733 Mapping Module
alarm standards. This module augments the alarm inventory, the alarm
lists and the alarm notification with X.733 and X.736 parameters. Many alarm systems are based on the X.733 [X.733] and X.736 [X.736]
alarm standards. This module "ietf-alarms-x733" augments the alarm
inventory, the alarm 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 term "resource" in this document is synonymous to the
ITU term "managed object". ITU term "managed object".
8. The X.733 Mapping Module This YANG module references [RFC6991], [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-09-11.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;
import ietf-alarms { import ietf-alarms {
prefix al; prefix al;
} }
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
skipping to change at page 53, line 47 skipping to change at page 54, line 4
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";
} }
organization organization
"IETF CCAMP Working Group"; "IETF CCAMP Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/ccamp> "WG Web: <https://trac.ietf.org/trac/ccamp>
WG List: <mailto:ccamp@ietf.org> WG List: <mailto:ccamp@ietf.org>
Editor: Stefan Vallin Editor: Stefan Vallin
<mailto:stefan@wallan.se> <mailto:stefan@wallan.se>
Editor: Martin Bjorklund Editor: Martin Bjorklund
<mailto:mbj@tail-f.com>"; <mailto:mbj@tail-f.com>";
description description
"This module augments the ietf-alarms module with X.733 alarm "This module augments the ietf-alarms module with X.733 alarm
parameters. parameters.
The following structures are augmented with X.733 event type The following structures are augmented with the X.733 event type
and probable cause: and probable cause:
1) alarms/alarm-inventory: all possible alarm types 1) alarms/alarm-inventory: all possible alarm types
2) alarms/alarm-list: every alarm in the system 2) alarms/alarm-list: every alarm in the system
3) alarm-notification: notifications indicating alarm state 3) alarm-notification: notifications indicating alarm-state
changes changes
4) alarms/shelved-alarms 4) alarms/shelved-alarms
The module also optionally allows the alarm management system The module also optionally allows the alarm-management system
to configure the mapping from the IETF Alarm module alarm keys to configure the mapping from the ietf-alarms' alarm keys
to the ITU tuple (event-type, probable-cause). to the ITU tuple (event-type, probable-cause).
The mapping does not include a corresponding X.733 specific The mapping does not include a corresponding problem value
problem value. The recommendation is to use the specific to X.733. The recommendation is to use the
'alarm-type-qualifier' leaf which serves the same purpose. 'alarm-type-qualifier' leaf, which serves the same purpose.
The module uses an integer and a corresponding string for The module uses an integer and a corresponding string for
probable cause instead of a globally defined enumeration, in probable cause instead of a globally defined enumeration, in
order to be able to manage conflicting enumeration definitions. order to be able to manage conflicting enumeration definitions.
A single globally defined enumeration is challenging to A single globally defined enumeration is challenging to
maintain. maintain.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
skipping to change at page 54, line 51 skipping to change at page 55, line 8
Copyright (c) 2019 IETF Trust and the persons identified as Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject to without modification, is permitted pursuant to, and subject to
the license terms contained in, the Simplified BSD License set the license terms contained in, the Simplified BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions forth in Section 4.c of the IETF Trust's Legal Provisions
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 8632; see
(https://tools.ietf.org/html/rfcXXXX); see the RFC itself for the RFC itself for full legal notices.";
full legal notices.";
reference reference
"ITU Recommendation X.733: Information Technology "ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function"; - System Management: Alarm Reporting Function";
revision 2019-03-21 { revision 2019-09-11 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: YANG Alarm Module"; "RFC 8632: A YANG Data Model for Alarm Management";
} }
/* /*
* Features * Features
*/ */
feature configure-x733-mapping { feature configure-x733-mapping {
description description
"The system supports configurable X733 mapping from "The system supports configurable X733 mapping from
the IETF alarm module alarm-type to X733 event-type the ietf-alarms' alarm-type to X733 event-type
and probable-cause."; and probable-cause.";
} }
/* /*
* Typedefs * Typedefs
*/ */
typedef event-type { typedef event-type {
type enumeration { type enumeration {
enum other { enum other {
skipping to change at page 56, line 29 skipping to change at page 56, line 32
value 6; value 6;
description description
"An alarm of this type is principally associated with a "An alarm of this type is principally associated with a
condition relating to an enclosure in which the equipment condition relating to an enclosure in which the equipment
resides."; resides.";
} }
enum integrity-violation { enum integrity-violation {
value 7; value 7;
description description
"An indication that information may have been illegally "An indication that information may have been illegally
modified, inserted or deleted."; modified, inserted, or deleted.";
} }
enum operational-violation { enum operational-violation {
value 8; value 8;
description description
"An indication that the provision of the requested service "An indication that the provision of the requested service
was not possible due to the unavailability, malfunction or was not possible due to the unavailability, malfunction,
incorrect invocation of the service."; or incorrect invocation of the service.";
} }
enum physical-violation { enum physical-violation {
value 9; value 9;
description description
"An indication that a physical resource has been violated "An indication that a physical resource has been violated
in a way that suggests a security attack."; in a way that suggests a security attack.";
} }
enum security-service-or-mechanism-violation { enum security-service-or-mechanism-violation {
value 10; value 10;
description description
skipping to change at page 57, line 11 skipping to change at page 57, line 16
enum time-domain-violation { enum time-domain-violation {
value 11; value 11;
description description
"An indication that an event has occurred at an unexpected "An indication that an event has occurred at an unexpected
or prohibited time."; or prohibited time.";
} }
} }
description description
"The event types as defined by X.733 and X.736."; "The event types as defined by X.733 and X.736.";
reference reference
"ITU Recommendation X.733: Information Technology "ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function - System Management: Alarm Reporting Function
ITU Recommendation X.736: Information Technology ITU-T Recommendation X.736: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Security Alarm Reporting Function"; - System Management: Security Alarm Reporting Function";
} }
typedef trend { typedef trend {
type enumeration { type enumeration {
enum less-severe { enum less-severe {
description description
"There is at least one outstanding alarm of a "There is at least one outstanding alarm of a
severity higher (more severe) than that in the severity higher (more severe) than that in the
skipping to change at page 57, line 42 skipping to change at page 57, line 47
} }
enum more-severe { enum more-severe {
description description
"The Perceived severity in the current alarm is "The Perceived severity in the current alarm is
higher (more severe) than that reported in any higher (more severe) than that reported in any
of the outstanding alarms."; of the outstanding alarms.";
} }
} }
description description
"This type is used to describe the "This type is used to describe the
severity trend of the alarming resource"; severity trend of the alarming resource.";
reference reference
"ITU Recommendation X.721: Information Technology "ITU-T Recommendation X.721: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- Structure of management information: - Structure of management information:
Definition of management information Definition of management information
Module Attribute-ASN1Module"; Module Attribute-ASN1Module";
} }
typedef value-type { typedef value-type {
type union { type union {
type int64; type int64;
type uint64; type uint64;
type decimal64 { type decimal64 {
fraction-digits 2; fraction-digits 2;
} }
} }
description description
"A generic union type to match ITU choice of integer "A generic union type to match the ITU choice of
and real."; integer and real.";
} }
/* /*
* Groupings * Groupings
*/ */
grouping x733-alarm-parameters { grouping x733-alarm-parameters {
description description
"Common X.733 parameters for alarms."; "Common X.733 parameters for alarms.";
leaf event-type { leaf event-type {
skipping to change at page 58, line 36 skipping to change at page 58, line 40
"The X.733/X.736 event type for this alarm."; "The X.733/X.736 event type for this alarm.";
} }
leaf probable-cause { leaf probable-cause {
type uint32; type uint32;
description description
"The X.733 probable cause for this alarm."; "The X.733 probable cause for this alarm.";
} }
leaf probable-cause-string { leaf probable-cause-string {
type string; type string;
description description
"The user friendly string matching "The user-friendly string matching
the probable cause integer value. The string the probable cause integer value. The string
SHOULD match the X.733 enumeration. For example, SHOULD match the X.733 enumeration. For example,
value 27 is 'localNodeTransmissionError'."; value 27 is 'localNodeTransmissionError'.";
} }
container threshold-information { container threshold-information {
description description
"This parameter shall be present when the alarm "This parameter shall be present when the alarm
is a result of crossing a threshold. "; is a result of crossing a threshold. ";
leaf triggered-threshold { leaf triggered-threshold {
type string; type string;
description description
"The identifier of the threshold attribute that "The identifier of the threshold attribute that
caused the notification."; caused the notification.";
} }
leaf observed-value { leaf observed-value {
type value-type; type value-type;
description description
"The value of the gauge or counter which crossed "The value of the gauge or counter that crossed
the threshold. This may be different from the the threshold. This may be different from the
threshold value if, for example, the gauge may threshold value if, for example, the gauge may
only take on discrete values."; only take on discrete values.";
} }
choice threshold-level { choice threshold-level {
description description
"In the case of a gauge the threshold level specifies "In the case of a gauge, the threshold level specifies
a pair of threshold values, the first being the value a pair of threshold values: the first is the value
of the crossed threshold and the second, its corresponding of the crossed threshold, and the second is its
hysteresis; in the case of a counter the threshold level corresponding hysteresis; in the case of a counter,
specifies only the threshold value."; the threshold level specifies only the threshold
value.";
case up { case up {
leaf up-high { leaf up-high {
type value-type; type value-type;
description description
"The going up threshold for rising the alarm."; "The going-up threshold for raising the alarm.";
} }
leaf up-low { leaf up-low {
type value-type; type value-type;
description description
"The threshold level for clearing the alarm. "The going-down threshold for clearing the alarm.
This is used for hysteresis functions for gauges."; This is used for hysteresis functions for gauges.";
} }
} }
case down { case down {
leaf down-low { leaf down-low {
type value-type; type value-type;
description description
"The going down threshold for rising the alarm."; "The going-down threshold for raising the alarm.";
} }
leaf down-high { leaf down-high {
type value-type; type value-type;
description description
"The threshold level for clearing the alarm. "The going-up threshold for clearing the alarm.
This is used for hysteresis functions for gauges."; This is used for hysteresis functions for gauges.";
} }
} }
} }
leaf arm-time { leaf arm-time {
type yang:date-and-time; type yang:date-and-time;
description description
"For a gauge threshold, the time at which the threshold "For a gauge threshold, it's the time at which the
was last re-armed, namely the time after the previous threshold was last re-armed; namely, it's the time after
threshold crossing at which the hysteresis value of the the previous threshold crossing at which the hysteresis
threshold was exceeded thus again permitting generation value of the threshold was exceeded, thus again permitting
of notifications when the threshold is crossed. the generation of notifications when the threshold is
For a counter threshold, the later of the time at which crossed. For a counter threshold, it's the later of the
the threshold offset was last applied, or the time at time at which the threshold offset was last applied or the
which the counter was last initialized (for resettable counter was last initialized (for resettable counters).";
counters).";
} }
} }
list monitored-attributes { list monitored-attributes {
uses attribute; uses attribute;
key "id"; key "id";
description description
"The Monitored attributes parameter, when present, defines "The Monitored attributes parameter, when present, defines
one or more attributes of the resource and their one or more attributes of the resource and their
corresponding values at the time of the alarm."; corresponding values at the time of the alarm.";
} }
leaf-list proposed-repair-actions { leaf-list proposed-repair-actions {
type string; type string;
description description
"This parameter, when present, is used if the cause is "This parameter, when present, is used if the cause is
known and the system being managed can suggest one or known and the system being managed can suggest one or
more solutions (such as switch in standby equipment, more solutions (such as switch in standby equipment,
retry, replace media)."; retry, and replace media).";
} }
leaf trend-indication { leaf trend-indication {
type trend; type trend;
description description
"This parameter specifies the current "This parameter specifies the current severity
severity trend of the resource. If present it trend of the resource. If present, it indicates
indicates that there are one or more alarms that there are one or more alarms ('outstanding
('outstanding alarms') which have not been cleared, alarms') that have not been cleared and that
and pertain to the same resource as that to which pertain to the same resource as this alarm
this alarm ('current alarm') pertains. ('current alarm') does. The possible values are:
The possible values are:
more-severe: The Perceived severity in the current more-severe: The Perceived severity in the current
alarm is higher (more severe) than that reported in alarm is higher (more severe) than that reported in
any of the outstanding alarms. any of the outstanding alarms.
no-change: The Perceived severity reported in the no-change: The Perceived severity reported in the
current alarm is the same as the highest (most severe) current alarm is the same as the highest (most severe)
of any of the outstanding alarms. of any of the outstanding alarms.
less-severe: There is at least one outstanding alarm less-severe: There is at least one outstanding alarm
skipping to change at page 60, line 49 skipping to change at page 61, line 4
alarm is higher (more severe) than that reported in alarm is higher (more severe) than that reported in
any of the outstanding alarms. any of the outstanding alarms.
no-change: The Perceived severity reported in the no-change: The Perceived severity reported in the
current alarm is the same as the highest (most severe) current alarm is the same as the highest (most severe)
of any of the outstanding alarms. of any of the outstanding alarms.
less-severe: There is at least one outstanding alarm less-severe: There is at least one outstanding alarm
of a severity higher (more severe) than that in the of a severity higher (more severe) than that in the
current alarm."; current alarm.";
} }
leaf backedup-status { leaf backedup-status {
type boolean; type boolean;
description description
"This parameter, when present, specifies whether or not "This parameter, when present, specifies whether or not the
the object emitting the alarm has been backed-up, and object emitting the alarm has been backed up; therefore, it
services provided to the user have, therefore, not been is possible to know whether or not services provided to the
disrupted. The use of this field in conjunction with the user have been disrupted when this parameter is included.
severity field provides information in an independent form The use of this field in conjunction with the
to qualify the seriousness of the alarm and the ability of 'perceived-severity' field provides information in an
the system as a whole to continue to provide services. independent form to qualify the seriousness of the alarm and
If the value of this parameter is true, it indicates that the ability of the system as a whole to continue to provide
the object emitting the alarm has been backed-up; if false, services. If the value of this parameter is true, it
the object has not been backed-up."; indicates that the object emitting the alarm has been backed
up; if false, the object has not been backed up.";
} }
leaf backup-object { leaf backup-object {
type al:resource; type al:resource;
description description
"This parameter shall be present when the Backed-up status "This parameter SHALL be present when the 'backedup-status'
parameter is present and has the value true. This parameter parameter is present and has the value 'true'. This
specifies the managed object instance that is providing parameter specifies the managed object instance that is
back-up services for the managed object about which the providing back-up services for the managed object to which
notification pertains. This parameter is useful, the notification pertains. This parameter is useful, for
for example, when the back-up object is from a pool of example, when the back-up object is from a pool of objects,
objects any of which may be dynamically allocated to any of which may be dynamically allocated to replace a
replace a faulty object."; faulty object.";
} }
list additional-information { list additional-information {
key "identifier"; key "identifier";
description description
"This parameter allows the inclusion of a "This parameter allows the inclusion of an additional
set of additional information in the alarm. It is information set in the alarm. It is a series of data
a series of data structures each of which contains three structures, each of which contains three items of
items of information: an identifier, a significance information: an identifier, a significance indicator,
indicator, and the problem information."; and the problem information.";
leaf identifier { leaf identifier {
type string; type string;
description description
"Identifies the data-type of the information parameter."; "Identifies the data type of the information parameter.";
} }
leaf significant { leaf significant {
type boolean; type boolean;
description description
"Set to true if the receiving system must be able to "Set to 'true' if the receiving system must be able to
parse the contents of the information subparameter parse the contents of the information subparameter
for the event report to be fully understood."; for the event report to be fully understood.";
} }
leaf information { leaf information {
type string; type string;
description description
"Additional information about the alarm."; "Additional information about the alarm.";
} }
} }
leaf security-alarm-detector { leaf security-alarm-detector {
type al:resource; type al:resource;
description description
"This parameter identifies the detector of the security "This parameter identifies the detector of the security
alarm."; alarm.";
} }
leaf service-user { leaf service-user {
type al:resource; type al:resource;
skipping to change at page 62, line 27 skipping to change at page 62, line 30
for service led to the generation of the security alarm."; for service led to the generation of the security alarm.";
} }
leaf service-provider { leaf service-provider {
type al:resource; type al:resource;
description description
"This parameter identifies the intended service-provider "This parameter identifies the intended service-provider
of the service that led to the generation of the security of the service that led to the generation of the security
alarm."; alarm.";
} }
reference reference
"ITU Recommendation X.733: Information Technology "ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function - System Management: Alarm Reporting Function
ITU Recommendation X.736: Information Technology ITU-T Recommendation X.736: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Security Alarm Reporting Function"; - System Management: Security Alarm Reporting Function";
} }
grouping x733-alarm-definition-parameters { grouping x733-alarm-definition-parameters {
description description
"Common X.733 parameters for alarm definitions. "Common X.733 parameters for alarm definitions.
This grouping is used to define those alarm This grouping is used to define those alarm
attributes that can be mapped from the alarm-type attributes that can be mapped from the alarm-type
mechanism in the ietf-alarm module."; mechanism in the ietf-alarms module.";
leaf event-type { leaf event-type {
type event-type; type event-type;
description description
"The alarm type has this X.733/X.736 event type."; "The alarm type has this X.733/X.736 event type.";
} }
leaf probable-cause { leaf probable-cause {
type uint32; type uint32;
description description
"The alarm type has this X.733 probable cause value. "The alarm type has this X.733 probable cause value.
This module defines probable cause as an integer This module defines probable cause as an integer
and not as an enumeration. The reason being that the and not as an enumeration. The reason being that the
primary use of probable cause is in the management primary use of probable cause is in the management
application if it is based on the X.733 standard. application if it is based on the X.733 standard.
However, most management applications have their own However, most management applications have their own
defined enum definitions and merging enums from defined enum definitions and merging enums from
different systems might create conflicts. By using different systems might create conflicts. By using
a configurable uint32 the system can be configured a configurable uint32, the system can be configured
to match the enum values in the management application."; to match the enum values in the management application.";
} }
leaf probable-cause-string { leaf probable-cause-string {
type string; type string;
description description
"This string can be used to give a user friendly string "This string can be used to give a user-friendly string
to the probable cause value."; to the probable cause value.";
} }
} }
grouping attribute { grouping attribute {
description description
"A grouping to match the ITU generic reference to "A grouping to match the ITU generic reference to
an attribute."; an attribute.";
leaf id { leaf id {
type al:resource; type al:resource;
description description
"The resource representing the attribute."; "The resource representing the attribute.";
} }
leaf value { leaf value {
type string; type string;
description description
"The value represented as a string since it could "The value represented as a string since it could
be of any type."; be of any type.";
} }
reference reference
"ITU Recommendation X.721: Information Technology "ITU-T Recommendation X.721: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- Structure of management information: - Structure of management information:
Definition of management information Definition of management information
Module Attribute-ASN1Module"; Module Attribute-ASN1Module";
} }
/* /*
* Add X.733 parameters to the alarm definitions, alarms, * Add X.733 parameters to the alarm definitions, alarms,
* and notification. * and notification.
*/ */
skipping to change at page 64, line 16 skipping to change at page 64, line 21
*/ */
augment "/al:alarms/al:control" { augment "/al:alarms/al:control" {
description description
"Add X.733 mapping capabilities. "; "Add X.733 mapping capabilities. ";
list x733-mapping { list x733-mapping {
if-feature "configure-x733-mapping"; if-feature "configure-x733-mapping";
key "alarm-type-id alarm-type-qualifier-match"; key "alarm-type-id alarm-type-qualifier-match";
description description
"This list allows a management application to control the "This list allows a management application to control the
X.733 mapping for all alarm types in the system. Any entry X.733 mapping for all alarm types in the system. Any entry
in this list will allow the alarm manager to over-ride the in this list will allow the alarm manager to override the
default X.733 mapping in the system and the final mapping default X.733 mapping in the system, and the final mapping
will be shown in the alarm inventory."; will be shown in the alarm inventory.";
leaf alarm-type-id { leaf alarm-type-id {
type al:alarm-type-id; type al:alarm-type-id;
description description
"Map the alarm type with this alarm type identifier."; "Map the alarm type with this alarm type identifier.";
} }
leaf alarm-type-qualifier-match { leaf alarm-type-qualifier-match {
type string; type string;
description description
"A W3C regular expression that is used when mapping an "A W3C regular expression that is used when mapping an
skipping to change at page 64, line 46 skipping to change at page 65, line 4
description description
"Augment X.733 information to the alarm."; "Augment X.733 information to the alarm.";
uses x733-alarm-parameters; uses x733-alarm-parameters;
} }
augment "/al:alarms/al:shelved-alarms/al:shelved-alarm" { augment "/al:alarms/al:shelved-alarms/al:shelved-alarm" {
description description
"Augment X.733 information to the alarm."; "Augment X.733 information to the alarm.";
uses x733-alarm-parameters; uses x733-alarm-parameters;
} }
augment "/al:alarm-notification" { augment "/al:alarm-notification" {
description description
"Augment X.733 information to the alarm notification."; "Augment X.733 information to the alarm notification.";
uses x733-alarm-parameters; uses x733-alarm-parameters;
} }
} }
<CODE ENDS> <CODE ENDS>
9. IANA Considerations 8. IANA Considerations
This document registers two URIs in the IETF XML registry [RFC3688]. This document registers two URIs in the "IETF XML Registry"
Following the format in RFC 3688, the following registrations are [RFC3688]. Following the format in RFC 3688, the following
requested to be made. registrations have been made.
URI: urn:ietf:params:xml:ns:yang:ietf-alarms URI: urn:ietf:params:xml:ns:yang:ietf-alarms
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A; the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-alarms-x733 URI: urn:ietf:params:xml:ns:yang:ietf-alarms-x733
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A; the requested URI is an XML namespace.
This document registers two YANG modules in the YANG Module Names This document registers two YANG modules in the "YANG Module Names"
registry [RFC6020]. registry [RFC6020].
name: ietf-alarms name: ietf-alarms
namespace: urn:ietf:params:xml:ns:yang:ietf-alarms namespace: urn:ietf:params:xml:ns:yang:ietf-alarms
prefix: al prefix: al
reference: RFC XXXX reference: RFC 8632
name: ietf-alarms-x733 name: ietf-alarms-x733
namespace: urn:ietf:params:xml:ns:yang:ietf-alarms-x733 namespace: urn:ietf:params:xml:ns:yang:ietf-alarms-x733
prefix: x733 prefix: x733
reference: RFC XXXX reference: RFC 8632
10. Security Considerations 9. Security Considerations
The YANG module specified in this document defines a schema for data The YANG modules specified in this document define a schema for data
that is designed to be accessed via network management protocols such that is designed to be accessed via network management protocols such
as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
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 The list of alarms itself may be potentially sensitive from a
security perspective, in that it potentially gives an attacker an security perspective, in that it potentially gives an attacker an
authoritative picture of the (broken) state of the network. 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 the YANG modules 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: in the "ietf-alarms" module and their sensitivity/vulnerability:
/alarms/control/notify-status-changes: This leaf controls whether an "/alarms/control/notify-status-changes": This leaf controls whether
alarm should notify based on various state changes. Unauthorized an alarm should notify based on various state changes.
access to this leaf could have a negative impact on operational Unauthorized access to this leaf could have a negative impact on
procedures relying on fine-grained alarm state change reporting operational procedures relying on fine-grained alarm-state change
reporting.
/alarms/control/alarm-shelving/shelf: This list controls the "/alarms/control/alarm-shelving/shelf": This list controls the
shelving (blocking) of alarms. Unauthorized access to this list shelving (blocking) of alarms. Unauthorized access to this list
could jeopardize the alarm management procedures since these could jeopardize the alarm-management procedures, since these
alarms will not be notified and not be part of the alarm list. alarms will not be notified or be part of the alarm list.
/alarms/control/alarm-profile/alarm-severity-assignment-profile: "/alarms/control/alarm-profile/alarm-severity-assignment-profile":
This list controls the severity levels of an alarm. Unauthorized This list controls the severity levels of an alarm. Unauthorized
access to this could for example downgrade the severity of an access to this could, for example, downgrade the severity of an
alarm and thereby have a negative impact on the alarm monitoring alarm and thereby have a negative impact on the alarm-monitoring
process. process.
Some of the operations in this YANG module may be considered Some of the RPC 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
alarm list. Unauthorized use of this action could jeopardize the the alarm list. Unauthorized use of this action could jeopardize
alarm management procedures since the deleted alarms may be vital the alarm-management procedures since the deleted alarms may be
for the alarm management application. vital 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
The authors wish to thank Viktor Leijon and Johan Nordlander for
their valuable input on forming the alarm model.
The authors also wish to thank Nick Hancock, Joey Boyd, Tom Petch and "/alarms/alarm-list/alarm/set-operator-state": This action can be
Balazs Lengyel for their extensive reviews and contributions to this used by the operator to indicate the level of human intervention
document. on an alarm. Unauthorized use of this action could result in
alarms being ignored by operators.
12. References 10. References
12.1. Normative References 10.1. Normative References
[M.3100] International Telecommunications Union, "Generic Network [M.3100] International Telecommunication Union, "Generic network
Information Model", ITU-T Recommendation M.3100, 2005. information model", ITU-T Recommendation M.3100, April
2005, <https://www.itu.int/rec/T-REC-M.3100-200504-I/en>.
[M.3160] International Telecommunications Union, "Generic, [M.3160] International Telecommunication Union, "Generic,
protocol-neutral management information model", protocol-neutral management information model",
ITU-T Recommendation M.3100, 2008. ITU-T Recommendation M.3100, November 2008,
<https://www.itu.int/rec/T-REC-M.3160-200811-I>.
[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, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://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,
<https://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
skipping to change at page 68, line 27 skipping to change at page 68, line 23
[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, YANG Data Model for Hardware Management", RFC 8348,
DOI 10.17487/RFC8348, March 2018, DOI 10.17487/RFC8348, March 2018,
<https://www.rfc-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 Telecommunication 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, February 1992,
<https://www.itu.int/rec/T-REC-X.721-199202-I/en>.
[X.733] International Telecommunications Union, "Information [X.733] International Telecommunication Union, "Information
Technology - Open Systems Interconnection - Systems technology - Open Systems Interconnection - Systems
Management: Alarm Reporting Function", Management: Alarm reporting function",
ITU-T Recommendation X.733, 1992. ITU-T Recommendation X.733, February 1992,
<https://www.itu.int/rec/T-REC-X.733-199202-I/en>.
[XSD-TYPES] [XSD-TYPES]
Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium Recommendation Second Edition", World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028, October 2004, REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
12.2. Informative References 10.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, March 2005,
2005. <http://www.3gpp.org/ftp/Specs/html-info/32111-2.htm>.
[ALARMSEM] [ALARMSEM] Wallin, S., Leijon, V., Nordlander, J., and N. Bystedt,
Wallin, S., Leijon, V., Nordlander, J., and N. Bystedt,
"The semantics of alarm definitions: enabling systematic "The semantics of alarm definitions: enabling systematic
reasoning about alarms. International Journal of Network reasoning about alarms", International Journal of Network
Management, Volume 22, Issue 3, John Wiley and Sons, Ltd, Management, Volume 22, Issue 3, May 2012,
http://dx.doi.org/10.1002/nem.800", March 2012. <http://dx.doi.org/10.1002/nem.800>.
[EEMUA] EEMUA Publication No. 191 Engineering Equipment and [EEMUA] "Alarm systems: a guide to design, management and
Materials Users Association, London, 2 edition., "Alarm procurement", EEMUA Publication No. 191, Engineering
Systems: A Guide to Design, Management and Procurement.", Equipment and Materials Users Association, Second Edition,
2007. 2007.
[G.7710] ITU-T, "SERIES G: TRANSMISSION SYSTEMS AND MEDIA, DIGITAL [G.7710] International Telecommunication Union, "SERIES G:
SYSTEMS AND NETWORKS Data over Transport - Generic aspects TRANSMISSION SYSTEMS AND MEDIA, DIGITAL SYSTEMS AND
- Transport network control aspects. Common equipment NETWORKS - Data over Transport - Generic aspects -
management function requirements", 2012. Transport network control aspects; Common equipment
management function requirements", ITU-T
[I-D.ietf-netmod-yang-instance-file-format] Recommendation G.7710/Y.1701, Amendment 1, November 2012.
Lengyel, B. and B. Claise, "YANG Instance Data File
Format", draft-ietf-netmod-yang-instance-file-format-02
(work in progress), February 2019.
[ISA182] International Society of Automation,ISA, "ANSI/ISA- [ISA182] International Society of Automation, "Management of Alarm
18.2-2009 Management of Alarm Systems for the Process Systems for the Process Industries", ANSI/ISA - 18.2-2016,
Industries", 2009. March 2016.
[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, <https://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 Telecommunication Union, "Information
Technology - Open Systems Interconnection - Systems technology - Open Systems Interconnection - Systems
Management: Security alarm reporting function", Management: Security alarm reporting function",
ITU-T Recommendation X.736, 1992. ITU-T Recommendation X.736, January 1992,
<https://www.itu.int/rec/T-REC-X.736-199201-I/en>.
Appendix A. Vendor-specific Alarm Types Example [YANG-INSTANCE]
Lengyel, B. and B. Claise, "YANG Instance Data File
Format", Work in Progress, draft-ietf-netmod-yang-
instance-file-format-02, August 2019.
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-
identities according to X.733 event types. level 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;
} }
identity xyz-alarms { identity xyz-alarms {
skipping to change at page 70, line 46 skipping to change at page 71, line 7
} }
// QoS alarms // QoS alarms
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: one alarm type is defined only with
with the identifier, and another dynamically configured. In the the identifier and another is dynamically configured. In the latter
latter case a digital input has been connected to a smoke-detector, 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-id" 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
</resource> </resource>
<will-clear>true</will-clear> <will-clear>true</will-clear>
<description> <description>
Link failure, operational state down but admin state up Link failure; operational state down but admin state up
</description> </description>
</alarm-type> </alarm-type>
<alarm-type> <alarm-type>
<alarm-type-id>xyz-al:environmental-alarm</alarm-type-id> <alarm-type-id>xyz-al:environmental-alarm</alarm-type-id>
<alarm-type-qualifier>smoke-alarm</alarm-type-qualifier> <alarm-type-qualifier>smoke-alarm</alarm-type-qualifier>
<will-clear>true</will-clear> <will-clear>true</will-clear>
<description> <description>
Connected smoke detector to digital input Connected smoke detector to digital input
</description> </description>
</alarm-type> </alarm-type>
</alarm-inventory> </alarm-inventory>
</alarms> </alarms>
Appendix C. Alarm List Example Appendix C. Alarm List Example
In this example we show an alarm that has toggled [major, clear, In this example, we show an alarm that has toggled [major, clear,
major]. An operator has acknowledged the alarm. major]. An operator has acknowledged the 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-list> <alarm-list>
<number-of-alarms>1</number-of-alarms> <number-of-alarms>1</number-of-alarms>
<last-changed>2018-04-08T08:39:50.00Z</last-changed> <last-changed>2018-04-08T08:39:50.00Z</last-changed>
<alarm> <alarm>
<resource> <resource>
skipping to change at page 72, line 42 skipping to change at page 73, line 7
<state>ack</state> <state>ack</state>
<operator>joe</operator> <operator>joe</operator>
<text>Will investigate, ticket TR764999</text> <text>Will investigate, ticket TR764999</text>
</operator-state-change> </operator-state-change>
</alarm> </alarm>
</alarm-list> </alarm-list>
</alarms> </alarms>
Appendix D. Alarm Shelving Example Appendix D. Alarm Shelving Example
This example shows how to shelf alarms. We shelf alarms related to This example shows how to shelve alarms. We shelve alarms related to
the smoke-detectors since they are being installed and tested. We the smoke detectors, since they are being installed and tested. We
also shelf all alarms from FastEthernet1/0. also shelve all alarms from FastEthernet1/0.
<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">
<control> <control>
<alarm-shelving> <alarm-shelving>
<shelf> <shelf>
<name>FE10</name> <name>FE10</name>
<resource> <resource>
/dev:interfaces/dev:interface[name='FastEthernet1/0'] /dev:interfaces/dev:interface[name='FastEthernet1/0']
skipping to change at page 74, line 5 skipping to change at page 74, line 26
<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>
<event-type>quality-of-service-alarm</event-type> <event-type>quality-of-service-alarm</event-type>
<probable-cause>777</probable-cause> <probable-cause>777</probable-cause>
</x733-mapping> </x733-mapping>
</control> </control>
</alarms> </alarms>
Appendix F. Relationship to other alarm standards Appendix F. Relationship to Other Alarm Standards
This section briefly describes how this alarm module relates to other This section briefly describes how this alarm data model relates to
relevant standards. other relevant standards.
F.1. Alarm definition F.1. Definition of "Alarm"
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. X.733 | | | physical or algorithmic | and not the state. |
| | cause of a malfunction. | defines an alarm as a | | | cause of a malfunction. | X.733 defines an alarm |
| | Faults manifest | deviation from normal | | | Faults manifest | as a deviation from a |
| | themselves as errors. | condition, but without | | | themselves as errors. | normal condition but |
| | alarm: A notification, of | the requirement that it | | | alarm: A notification, of | without the requirement |
| | the form defined by this | needs corrective | | | the form defined by this | that it needs corrective |
| | function, of a specific | actions. | | | 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 a device as | X.733 definition. | | | generated by a device as | X.733 definition. |
| | a result of the | | | | a result of the | |
| | declaration 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 as 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 data |
| | system from normal | adds the requirement | | | system from normal | model adds the |
| | operation. | that it should require a | | | operation. | requirement that it |
| | | should require a |
| | | corrective action and | | | | corrective action and |
| | | should be undesired, not | | | | should be undesired, not |
| | | only a deviation from | | | | only a deviation from |
| | | normal. The alarm MIB | | | | normal. The alarm MIB |
| | | 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 module; it focuses |
| | | "lasting condition", | | | | on the "lasting |
| | | not the individual | | | | condition", 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 | criterion 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. device, link) for | definition as this alarm | | | (e.g., device, link) for | definition as this alarm |
| | which an operator action | module. It is worth | | | which an operator action | data model. It is worth |
| | is required. It | noting that earlier | | | is required. It | noting that earlier |
| | emphasizes a key | versions used a | | | emphasizes a key | versions used a |
| | 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. | The earlier version also |
| | v12: alarm: abnormal | defined an alarm as a | | | 3GPP 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. | |
| | a deviation of a system | | | | fault: a deviation of a | |
| | from normal operation, | | | | system from normal | |
| | which may result in the | | | | operation, which may | |
| | loss of operational | | | | result in the loss of | |
| | capabilities [...] | | | | operational capabilities | |
| | [...] | |
+------------+---------------------------+--------------------------+ +------------+---------------------------+--------------------------+
Table 1: Definition of alarm in standards Table 1: Definition of the Term "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* that *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 data model relates to
standard data models. Note well that we cover other data models for other standard data models. Note well that we cover other data
alarm interfaces. Not other standards such as SDO specific alarms models for alarm interfaces but not other standards such as SDO-
for example. specific alarms.
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: years. The YANG alarm data model 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 data model defines the alarm list as the current alarm
for the resources, which is generated from the state change states 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
alarm module "clear" is not a severity level, it is a separate YANG alarm data model, "clear" is not a severity level; it is a
state of the alarm. An alarm can have the following states for separate state of the alarm. An alarm can have the following
example (major, cleared), (minor, not cleared) states, for example, (major, cleared) and (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 data model uses a hierarchical
identity, "alarm-type". This enables delegation of alarm types YANG identity: "alarm-type". This enables delegation of alarm
within organizations. It also lets management reason about types within organizations. It also enables management to reason
abstract alarm types corresponding to base identities, see about 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 data model has not included the majority of the
alarm attributes. Rather these are defined in an augmenting X.733 alarm attributes. Rather, these are defined in an
module if "strict" X.733 compliance is needed. augmenting module [X.733] if "strict" X.733 compliance is needed.
F.2.2. RFC 3877, the Alarm MIB F.2.2. The Alarm MIB (RFC 3877)
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
SNMP managed objects and notifications into alarm states and alarm SNMP-managed objects and notifications into alarm states and alarm
notifications. This was necessary since MIBs were already defined notifications. This was necessary since MIBs were already defined
with both managed objects and notifications indicating alarms, for with both managed objects and notifications indicating alarms, for
example linkUp and linkDown notifications in combination with example, "linkUp" and "linkDown" notifications in combination with
ifAdminState and ifOperState. So RFC 3877 can not really be compared "ifAdminState" and "ifOperState". So, RFC 3877 cannot really be
to the alarm YANG module in that sense. compared to the alarm YANG module in that sense.
The Alarm MIB maps existing MIB definitions into alarms, The Alarm MIB maps existing MIB definitions into alarms, such as
alarmModelTable. The upside of that is that a SNMP Manager can at "alarmModelTable". The upside of that is that an SNMP Manager can,
runtime read the possible alarm types. This corresponds to the at runtime, read the possible alarm types. This corresponds to the
alarmInventory in the alarm YANG module. "alarmInventory" in the alarm YANG module.
F.2.3. 3GPP Alarm IRP F.2.3. 3GPP Alarm IRP
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 as follows:
3GPP keeps the majority of the X.733 attributes, the alarm YANG 3GPP keeps the majority of the X.733 attributes, but the alarm
module does not. YANG 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 Example 3 in Annex C of [ALARMIRP]). In
YANG alarm module the key for identifying an alarm instance is the YANG alarm data model, the key for identifying an alarm
clearly defined by ("resource", "alarm-type-id", "alarm-type- instance is clearly defined by ("resource", "alarm-type-id",
qualifier"). See also Section 3.4 for more information. "alarm-type-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 lifecycle from the operator lifecycle. 3GPP allows
allows operators to set the alarm severity to clear, this is not operators to set the alarm severity to clear; this is not allowed
allowed by this module, rather an operator closes an alarm which by this module. Rather, an operator closes an alarm, which does
does not affect the severity. 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 previously referenced alarm standards.
does not define a data model for alarm reporting. It defines common It does not define a data model for alarm reporting. It defines
equipment management function requirements including alarm common 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 correspond 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, which is the NALM (No ALarM) 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
we have not gained the goal of alarm management. value, 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 their causes are summarized in Table 2.
Table 2. This summary is adopted to networking based on the ISA This summary is adopted to networking based on the ISA [ISA182] and
[ISA182] and EEMUA [EEMUA] standards. Engineering Equipment Materials Users Association (EEMUA) [EEMUA]
standards.
+------------------+--------------------------------+---------------+ +-----------------+--------------------------------+----------------+
| Problem | Cause | How this | | Problem | Cause | How this |
| | | module | | | | module |
| | | address the | | | | addresses the |
| | | cause | | | | cause |
+------------------+--------------------------------+---------------+ +-----------------+--------------------------------+----------------+
| Alarms are | "Nuisance" alarms (chattering | Strict | | Alarms are | "Nuisance" alarms (chattering | Strict |
| generated but | alarms and fleeting alarms), | definition of | | generated, but | alarms and fleeting alarms), | definition of |
| they are ignored | faulty hardware, redundant | alarms | | they are | faulty hardware, redundant | alarms |
| by the operator. | alarms, cascading alarms, | requiring | | ignored by the | alarms, cascading alarms, | requiring |
| | incorrect alarm settings, | corrective | | operator. | incorrect alarm settings, and | corrective |
| | alarms have not been | response. | | | alarms that have not been | response. See |
| | rationalized, the alarms | Alarm | | | rationalized; the alarms | alarm |
| | represent log information | requirements | | | represent log information | requirements |
| | rather than true alarms. | in Table 3. | | | rather than true alarms. | in Table 3. |
| | | | | | | |
| When alarms | Insufficient alarm response | The alarm | | When alarms | Insufficient alarm-response | The alarm |
| occur, operators | procedures and not well | inventory | | occur, | procedures and not well- | inventory |
| do not know how | defined alarm types. | lists all | | operators do | defined alarm types. | lists all |
| to respond. | | alarm types | | not know how to | | alarm types |
| | | and | | respond. | | and corrective |
| | | corrective | | | | actions. See |
| | | actions. | | | | alarm |
| | | Alarm | | | | requirements |
| | | requirements | | | | in Table 3. |
| | | in Table 3. | | | | |
| | | | | The alarm | Nuisance alarms, stale alarms, | The alarm |
| The alarm | Nuisance alarms, stale alarms, | The alarm | | display is full | and alarms from equipment not | definition and |
| display is full | alarms from equipment not in | definition | | of alarms, even | in service. | alarm |
| of alarms, even | service. | and alarm | | when there is | | shelving. |
| when there is | | shelving. | | nothing wrong. | | |
| nothing wrong. | | | | | | |
| | | | | During a | Incorrect prioritization of | State-based |
| During a | Incorrect prioritization of | State-based | | failure, | alarms. Not using advanced | alarm model |
| failure, | alarms. Not using advanced | alarm model, | | operators are | alarm techniques (e.g., state- | and alarm-rate |
| operators are | alarm techniques (e.g. state- | alarm rate | | flooded with so | based alarming). | requirements; |
| flooded with so | based alarming). | requirements | | many alarms | | see Tables 4 |
| many alarms that | | in Table 4 | | that they do | | and 5, |
| they do not know | | and Table 5 | | not know which | | respectively. |
| which ones are | | | | ones are the | | |
| the most | | | | most important. | | |
| important. | | | +-----------------+--------------------------------+----------------+
+------------------+--------------------------------+---------------+
Table 2: Alarm Problems and Causes Table 2: Alarm Problems and Causes
Based upon the above problems EEMUA gives the following definition of Based upon the above problems, EEMUA gives the following definition
a good alarm: of a good alarm:
+----------------+--------------------------------------------------+ +----------------+--------------------------------------------------+
| Characteristic | Explanation | | Characteristic | Explanation |
+----------------+--------------------------------------------------+ +----------------+--------------------------------------------------+
| Relevant | Not spurious or of low operational value. | | Relevant | Not spurious or of low operational value. |
| | | | | |
| Unique | Not duplicating another alarm. | | Unique | Not duplicating another alarm. |
| | | | | |
| Timely | Not long before any response is needed or too | | Timely | Not long before any response is needed or too |
| | late to do anything. | | | late to do anything. |
| | | | | |
| Prioritized | Indicating the importance that the operator | | Prioritized | Indicating the importance that the operator |
| | deals with the problem. | | | deals with the problem. |
| | | | | |
| Understandable | Having a message which is clear and easy to | | Understandable | Having a message that is clear and easy to |
| | understand. | | | understand. |
| | | | | |
| Diagnostic | Identifying the problem that has occurred. | | Diagnostic | Identifying the problem that has occurred. |
| | | | | |
| Advisory | Indicative of the action to be taken. | | Advisory | Indicative of the action to be taken. |
| | | | | |
| Focusing | Drawing attention to the most important issues. | | Focusing | Drawing attention to the most important issues. |
+----------------+--------------------------------------------------+ +----------------+--------------------------------------------------+
Table 3: Definition of a Good Alarm Table 3: Definition of a Good Alarm
Vendors SHOULD rationalize all alarms according to above. Another Vendors SHOULD rationalize all alarms according to the table above.
crucial requirement is acceptable alarm notification rates. Vendors Another crucial requirement is acceptable alarm notification rates.
SHOULD make sure that they do not exceed the recommendations from Vendors SHOULD make sure that they do not exceed the recommendations
EEMUA below: from EEMUA below:
+-----------------------------------+-------------------------------+ +-----------------------------------+-------------------------------+
| Long Term Alarm Rate in Steady | Acceptability | | Long-Term Alarm Rate in Steady | Acceptability |
| Operation | | | Operation | |
+-----------------------------------+-------------------------------+ +-----------------------------------+-------------------------------+
| More than one per minute | Very likely to be | | More than one per minute | Very likely to be |
| | unacceptable. | | | unacceptable. |
| | | | | |
| One per 2 minutes | Likely to be over-demanding. | | One per 2 minutes | Likely to be overdemanding. |
| | | | | |
| One per 5 minutes | Manageable. | | One per 5 minutes | Manageable. |
| | | | | |
| Less than one per 10 minutes | Very likely to be acceptable. | | Less than one per 10 minutes | Very likely to be acceptable. |
+-----------------------------------+-------------------------------+ +-----------------------------------+-------------------------------+
Table 4: Acceptable Alarm Rates, Steady State Table 4: Acceptable Alarm Rates -- Steady State
+----------------------------+--------------------------------------+ +----------------------------+--------------------------------------+
| Number of alarms displayed | Acceptability | | Number of alarms displayed | Acceptability |
| in 10 minutes following a | | | in 10 minutes following a | |
| major network problem | | | major network problem | |
+----------------------------+--------------------------------------+ +----------------------------+--------------------------------------+
| More than 100 | Definitely excessive and very likely | | More than 100 | Definitely excessive and very likely |
| | to lead to the operator to abandon | | | to lead to the operator abandoning |
| | the use of the alarm system. | | | the use of the alarm system. |
| | | | | |
| 20-100 | Hard to cope with. | | 20-100 | Hard to cope with. |
| | | | | |
| Under 10 | Should be manageable - but may be | | Under 10 | Should be manageable, but it may be |
| | difficult if several of the alarms | | | difficult if several of the alarms |
| | require a complex operator response. | | | require a complex operator response. |
+----------------------------+--------------------------------------+ +----------------------------+--------------------------------------+
Table 5: Acceptable Alarm Rates, Burst Table 5: Acceptable Alarm Rates -- Burst
The numbers in Table 4 and Table 5 are the sum of all alarms for a The numbers in Tables 4 and 5 are the sum of all alarms for a network
network being managed from one alarm console. So every individual being managed from one alarm console. So every individual system or
system or NMS contributes to these numbers. Network Management System (NMS) contributes to these numbers.
Vendors SHOULD make sure that the following rules are used in Vendors SHOULD make sure that the following rules are used in
designing the alarm interface: designing the alarm interface:
1. Rationalize the alarms in the system to ensure that every alarm 1. Rationalize the alarms in the system to ensure that every alarm
is necessary, has a purpose, and follows the cardinal rule - that is necessary, has a purpose, and follows the cardinal rule that
it requires an operator response. Adheres to the rules of it requires an operator response. Adheres to the rules of
Table 3 Table 3.
2. Audit the quality of the alarms. Talk with the operators about 2. Audit the quality of the alarms. Talk with the operators about
how well the alarm information support them. Do they know what how well the alarm information supports them. Do they know what
to do in the event of an alarm? Are they able to quickly to do in the event of an alarm? Are they able to quickly
diagnose the problem and determine the corrective action? Does diagnose the problem and determine the corrective action? Does
the alarm text adhere to the requirements in Table 3? the alarm text adhere to the requirements in Table 3?
3. Analyze and benchmark the performance of the system and compare 3. Analyze and benchmark the performance of the system and compare
it to the recommended metrics in Table 4 and Table 5. Start by it to the recommended metrics in Tables 4 and 5. Start by
identifying nuisance alarms, standing alarms at normal state and identifying nuisance alarms, as well as standing alarms at normal
startup. state and startup.
Acknowledgements
The authors wish to thank Viktor Leijon and Johan Nordlander for
their valuable input on forming the alarm model.
The authors also wish to thank Nick Hancock, Joey Boyd, Tom Petch,
and Balazs Lengyel for their extensive reviews and contributions to
this document.
Authors' Addresses Authors' Addresses
Stefan Vallin Stefan Vallin
Stefan Vallin AB Stefan Vallin AB
Email: stefan@wallan.se Email: stefan@wallan.se
Martin Bjorklund Martin Bjorklund
Cisco Cisco
Email: mbj@tail-f.com Email: mbj@tail-f.com
 End of changes. 396 change blocks. 
2039 lines changed or deleted 2049 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/