draft-ietf-ccamp-alarm-module-01.txt   draft-ietf-ccamp-alarm-module-02.txt 
Network Working Group S. Vallin Network Working Group S. Vallin
Internet-Draft Stefan Vallin AB Internet-Draft Stefan Vallin AB
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: August 12, 2018 Cisco Expires: February 9, 2019 Cisco
February 8, 2018 August 8, 2018
YANG Alarm Module YANG Alarm Module
draft-ietf-ccamp-alarm-module-01 draft-ietf-ccamp-alarm-module-02
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 RPCs to notifications to inform management systems. There are also RPCs to
manage the operator state of an alarm and administrative alarm manage the operator state of an alarm and administrative alarm
procedures. The module carefully maps to relevant alarm standards. procedures. The module carefully maps to relevant alarm standards.
Status of This Memo Status of This Memo
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 12, 2018. This Internet-Draft will expire on February 9, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://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 15 skipping to change at page 2, line 15
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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Alarm Module Concepts . . . . . . . . . . . . . . . . . . . . 5 3. Alarm Module Concepts . . . . . . . . . . . . . . . . . . . . 5
3.1. Alarm Definition . . . . . . . . . . . . . . . . . . . . 5 3.1. Alarm Definition . . . . . . . . . . . . . . . . . . . . 5
3.2. Alarm Type . . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Alarm Type . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Identifying Resource . . . . . . . . . . . . . . . . . . 7 3.3. Identifying the Alarming Resource . . . . . . . . . . . . 7
3.4. Identifying Alarm Instances . . . . . . . . . . . . . . . 7 3.4. Identifying Alarm Instances . . . . . . . . . . . . . . . 8
3.5. Alarm Life-Cycle . . . . . . . . . . . . . . . . . . . . 8 3.5. Alarm Life-Cycle . . . . . . . . . . . . . . . . . . . . 8
3.5.1. Resource Alarm Life-Cycle . . . . . . . . . . . . . . 8 3.5.1. Resource Alarm Life-Cycle . . . . . . . . . . . . . . 8
3.5.2. Operator Alarm Life-cycle . . . . . . . . . . . . . . 9 3.5.2. Operator Alarm Life-cycle . . . . . . . . . . . . . . 9
3.5.3. Administrative Alarm Life-Cycle . . . . . . . . . . . 9 3.5.3. Administrative Alarm Life-Cycle . . . . . . . . . . . 10
3.6. Root Cause and Impacted Resources . . . . . . . . . . . . 10 3.6. Root Cause, Impacted Resources and Related Alarms . . . . 10
3.7. Alarm Shelving . . . . . . . . . . . . . . . . . . . . . 10 3.7. Alarm Shelving . . . . . . . . . . . . . . . . . . . . . 11
4. Alarm Data Model . . . . . . . . . . . . . . . . . . . . . . 10 3.8. Alarm Profiles . . . . . . . . . . . . . . . . . . . . . 11
4.1. Alarm Control . . . . . . . . . . . . . . . . . . . . . . 11 4. Alarm Data Model . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. Alarm Shelving . . . . . . . . . . . . . . . . . . . 11 4.1. Alarm Control . . . . . . . . . . . . . . . . . . . . . . 12
4.1.1. Alarm Shelving . . . . . . . . . . . . . . . . . . . 12
4.2. Alarm Inventory . . . . . . . . . . . . . . . . . . . . . 12 4.2. Alarm Inventory . . . . . . . . . . . . . . . . . . . . . 12
4.3. Alarm Summary . . . . . . . . . . . . . . . . . . . . . . 13 4.3. Alarm Summary . . . . . . . . . . . . . . . . . . . . . . 13
4.4. The Alarm List . . . . . . . . . . . . . . . . . . . . . 13 4.4. The Alarm List . . . . . . . . . . . . . . . . . . . . . 13
4.5. The Shelved Alarms List . . . . . . . . . . . . . . . . . 15 4.5. The Shelved Alarms List . . . . . . . . . . . . . . . . . 13
4.6. RPCs and Actions . . . . . . . . . . . . . . . . . . . . 15 4.6. Alarm Profiles . . . . . . . . . . . . . . . . . . . . . 14
4.7. Notifications . . . . . . . . . . . . . . . . . . . . . . 15 4.7. RPCs and Actions . . . . . . . . . . . . . . . . . . . . 14
5. Alarm YANG Module . . . . . . . . . . . . . . . . . . . . . . 15 4.8. Notifications . . . . . . . . . . . . . . . . . . . . . . 14
6. X.733 Alarm Mapping Data Model . . . . . . . . . . . . . . . 43 5. Alarm YANG Module . . . . . . . . . . . . . . . . . . . . . . 14
7. X.733 Alarm Mapping YANG Module . . . . . . . . . . . . . . . 43 6. X.733 Extensions . . . . . . . . . . . . . . . . . . . . . . 44
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 7. The X.733 Mapping Module . . . . . . . . . . . . . . . . . . 44
9. Security Considerations . . . . . . . . . . . . . . . . . . . 50 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 51 9. Security Considerations . . . . . . . . . . . . . . . . . . . 56
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 57
11.1. Normative References . . . . . . . . . . . . . . . . . . 51 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 57
11.2. Informative References . . . . . . . . . . . . . . . . . 52 11.1. Normative References . . . . . . . . . . . . . . . . . . 57
Appendix A. Vendor-specific Alarm-Types Example . . . . . . . . 53 11.2. Informative References . . . . . . . . . . . . . . . . . 58
Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 54 Appendix A. Vendor-specific Alarm-Types Example . . . . . . . . 59
Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 54 Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 60
Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 56 Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 61
Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 56 Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 62
Appendix F. Background and Usability Requirements . . . . . . . 57 Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 63
F.1. Alarm Concepts . . . . . . . . . . . . . . . . . . . . . 57 Appendix F. Background and Usability Requirements . . . . . . . 64
F.1.1. Alarm type . . . . . . . . . . . . . . . . . . . . . 58 F.1. Alarm Concepts . . . . . . . . . . . . . . . . . . . . . 64
F.2. Usability Requirements . . . . . . . . . . . . . . . . . 58 F.1.1. Alarm type . . . . . . . . . . . . . . . . . . . . . 64
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 F.2. Usability Requirements . . . . . . . . . . . . . . . . . 65
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68
1. Introduction 1. Introduction
This document defines a YANG [RFC7950] module for alarm management. This document defines a YANG [RFC7950] module for alarm management.
The purpose is to define a standardised alarm interface for network The purpose is to define a standardised 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 standardised to feed alarms to the alarm management application in a standardised
format is a starting point for performing higher level network format is a starting point for performing higher level network
assurance tasks. assurance tasks.
This document defines a standardised YANG module for alarm The design of the module is based on experience from using and
management. The design of the module is based on experience from implementing available alarm standards from ITU [X.733], 3GPP
using and implementing available alarm standards from ITU [X.733], [ALARMIRP] and ANSI [ISA182].
3GPP [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 BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 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]:
skipping to change at page 3, line 50 skipping to change at page 4, line 5
o RPC o RPC
o server o server
The following terms are used within this document: The following terms are used within this document:
o Alarm (the general concept): An alarm signifies an undesirable o Alarm (the general concept): An alarm signifies an undesirable
state in a resource that requires corrective action. state in a resource that requires corrective action.
o Alarm Type: An alarm type identifies a possible unique alarm state
for a resource. Alarm types are names to identify the state like
"link-alarm", "jitter-violation", "high-disk-utilization".
o Resource: A fine-grained identification of the alarming resource,
for example: an interface, a process.
o Alarm Instance: The alarm state for a specific resource and alarm o Alarm Instance: The alarm state for a specific resource and alarm
type. For example (GigabitEthernet0/15, link-alarm). An entry in type. For example (GigabitEthernet0/15, link-alarm). An entry in
the alarm list. the alarm list.
o Alarm Inventory: A list of all possible alarm types on a system. o Alarm Inventory: A list of all possible alarm types on a system.
o Alarm Shelving: Blocking alarms according to specific criteria. o Alarm Shelving: Blocking alarms according to specific criteria.
o Alarm Type: An alarm type identifies a possible unique alarm state
for a resource. Alarm types are names to identify the state like
"link-alarm", "jitter-violation", "high-disk-utilization".
o Management System: The alarm management application that consumes o Management System: The alarm management application that consumes
the alarms, i.e., acts as a client. the alarms, i.e., acts as a client.
o Resource: A fine-grained identification of the alarming resource,
for example: an interface, a process.
o System: The system that implements this YANG alarm module, i.e., o System: The system that implements this YANG alarm module, i.e.,
acts as a server. This corresponds to a network device or a acts as a server. This corresponds to a network device or a
management application that provides a north-bound alarm management application that provides a north-bound alarm
interface. interface.
Tree diagrams used in this document follow the notation defined in Tree diagrams used in this document follow the notation defined in
[I-D.ietf-netmod-yang-tree-diagrams]. [RFC8340].
2. Objectives 2. Objectives
The objectives for the design of the Alarm Module are: The objectives for the design of the Alarm Module are:
o Simple to use. If a system supports this module, it shall be o Simple to use. If a system supports this module, it shall be
straight-forward to integrate this into a YANG based alarm straight-forward to integrate this into a YANG based alarm
manager. manager.
o View alarms as states on resources and not as discrete o View alarms as states on resources and not as discrete
skipping to change at page 6, line 9 skipping to change at page 6, line 14
The use of YANG identities means that all possible alarms are The use of YANG identities means that all possible alarms are
identified at design time. This explicit declaration of alarm types identified at design time. This explicit declaration of alarm types
makes it easier to allow for alarm qualification reviews and makes it easier to allow for alarm qualification reviews and
preparation of alarm actions and documentation. preparation of alarm actions and documentation.
There are occasions where the alarm types are not known at design There are occasions where the alarm types are not known at design
time. For example, a system with digital inputs that allows users to time. For example, a system with digital inputs that allows users to
connects detectors (e.g., smoke detector) to the inputs. In this connects detectors (e.g., smoke detector) to the inputs. In this
case it is a configuration action that says that certain connectors case it is a configuration action that says that certain connectors
are fire alarms for example. The drawback of this is that there is a are fire alarms for example. A potential drawback of this is that
big risk that alarm operators will receive alarm types as a surprise, there is a big risk that alarm operators will receive alarm types as
they do not know how to resolve the problem since a defined alarm a surprise, they do not know how to resolve the problem since a
procedure does not necessarily exist. defined alarm procedure does not necessarily exist. To avoid this
risk the system MUST publish all possible alarm types in the alarm
inventory, see Section 4.2.
In order to allow for dynamic addition of alarm types the alarm In order to allow for dynamic addition of alarm types the alarm
module also allows for further qualification of the identity based module also allows for further qualification of the identity based
alarm type using a string. alarm type using a string.
A vendor or standard can then define their own alarm-type hierarchy. A vendor or standard can then define their own alarm-type hierarchy.
The example below shows a hierarchy based on X.733 event types: The example below shows a hierarchy based on X.733 event types:
import ietf-alarms { import ietf-alarms {
prefix al; prefix al;
skipping to change at page 7, line 34 skipping to change at page 7, line 41
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 run-time 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.";
} }
3.3. Identifying Resource A server SHOULD strive to minimize the number of dynamically defined
alarm types.
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 then an instance-
identifier MUST be used with the full path to the object. identifier MUST be used with the full path to the object.
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
skipping to change at page 8, line 26 skipping to change at page 8, line 35
o resource alarm life-cycle: the alarm instrumentation that controls o resource alarm life-cycle: the alarm instrumentation that controls
alarm raise, clearance, and severity changes. alarm raise, clearance, and severity changes.
o operator alarm life-cycle: operators acting upon alarms with o operator alarm life-cycle: operators acting upon alarms with
actions like acknowledgment and closing. Closing an alarm implies actions like acknowledgment and closing. Closing an alarm implies
that the operator considers the corrective action performed. that the operator considers the corrective action performed.
Operators can also shelf (block/filter) alarms in order to avoid Operators can also shelf (block/filter) alarms in order to avoid
nuisance alarms. nuisance alarms.
o administrative alarm life-cycle: deleting (purging) alarms and o administrative alarm life-cycle: purging (deleting) unwanted
compressing the alarm status change list. This module exposes alarms and compressing the alarm status change list. This module
operations to manage the administrative life-cycle. The server exposes operations to manage the administrative life-cycle. The
may also perform these operations based on other policies, but how server may also perform these operations based on other policies,
that is done is out of scope for this document. but how that is done is out of scope for this document.
A server SHOULD describe how long it retains cleared/closed alarms: A server SHOULD describe how long it retains cleared/closed alarms:
until manually purged or if it has an automatic removal policy. until manually purged or if it has an automatic removal policy.
3.5.1. Resource Alarm Life-Cycle 3.5.1. Resource Alarm Life-Cycle
From a resource perspective, an alarm can have the following life- From a resource perspective, an alarm can for example have the
cycle: raise, change severity, change severity, clear, being raised following life-cycle: raise, change severity, change severity, clear,
again etc. All of these status changes can have different alarm being raised again etc. All of these status changes can have
texts generated by the instrumentation. Two important things to different alarm texts generated by the instrumentation. Two
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 rpc an administrative process. The alarm module defines an rpc
"purge" that deletes alarms. "purge" that deletes alarms.
2. Alarms are not cleared by operators, only the underlying 2. Alarms are not cleared by operators, only the underlying
instrumentation can clear an alarm. Operators can close alarms. instrumentation can clear an alarm. Operators can close alarms.
The YANG tree representation below illustrates the resource oriented The YANG tree representation below illustrates the resource oriented
life-cycle: life-cycle:
+--ro alarm* [resource alarm-type-id alarm-type-qualifier] +--ro alarm* [resource alarm-type-id alarm-type-qualifier]
... ...
+--ro is-cleared boolean +--ro is-cleared boolean
+--ro last-changed yang:date-and-time +--ro last-changed yang:date-and-time
+--ro perceived-severity severity +--ro perceived-severity severity
+--ro alarm-text alarm-text +--ro alarm-text alarm-text
+--ro status-change* [time] +--ro status-change* [time]
+--ro time yang:date-and-time +--ro time yang:date-and-time
+--ro perceived-severity severity +--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. The last status values are also to the "status-change" list. The last status values are also
represented at leafs for the alarm. Note well that the alarm represented as leafs for the alarm. Note well that the alarm
severity does not include "cleared", alarm clearance is a flag. severity does not include "cleared", alarm clearance is a boolean
flag.
An alarm can therefore look like this: ((GigabitEthernet0/25, link- An alarm can therefore look like this: ((GigabitEthernet0/25, link-
alarm,""), false, T, major, "Interface GigabitEthernet0/25 down") alarm,""), false, T, major, "Interface GigabitEthernet0/25 down")
3.5.2. Operator Alarm Life-cycle 3.5.2. Operator Alarm Life-cycle
Operators can also act upon alarms using the set-operator-state Operators can also act upon alarms using the set-operator-state
action: action:
+--ro alarm* [resource alarm-type-id alarm-type-qualifier] +--ro alarm* [resource alarm-type-id alarm-type-qualifier]
... ...
+--ro operator-state-change* [time] {operator-actions}? +--ro operator-state-change* [time] {operator-actions}?
| +--ro time yang:date-and-time | +--ro time yang:date-and-time
| +--ro operator string | +--ro operator string
| +--ro state operator-state | +--ro state operator-state
| +--ro text? string | +--ro text? string
+---x set-operator-state {operator-actions}? +---x set-operator-state {operator-actions}?
+---w input +---w input
+---w state 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 rpc "purge-alarms"), can use "closed". Alarm deletion (using the rpc "purge-alarms"), can use
this state as a criteria. A closed alarm is an alarm where the this state as a criteria. A closed alarm is an alarm where the
operator has performed any required corrective actions. Closed operator has performed any required corrective actions. Closed
alarms are good candidates for being deleted. alarms are good candidates for being purged.
3.5.3. Administrative Alarm Life-Cycle 3.5.3. Administrative Alarm Life-Cycle
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" rpc. The "purge- action. This is supported by the "purge-alarms" rpc. The "purge-
alarms" rpc takes a filter as input. The filter selects alarms based alarms" rpc takes a filter as input. The filter selects alarms based
on the operator and resource life-cycle such as "all closed cleared on the operator and resource life-cycle such as "all closed cleared
alarms older than a time specification". The server may also perform alarms older than a time specification". The server may also perform
these operations based on other policies, but how that is done is out these operations based on other policies, but how that is done is out
of scope for this document. of scope for this document.
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" rpc. change. A client can perform this using the "compress-alarms" rpc.
The server may also perform these operations based on other policies, The server may also perform these operations based on other policies,
but how that is done is out of scope for this document. but how that is done is out of scope for this document.
3.6. Root Cause and Impacted Resources 3.6. Root Cause, Impacted Resources and Related Alarms
The general principle of this alarm module is to limit the amount of The general principle of this alarm module is to limit the amount of
alarms. The alarm has two leaf-lists to identify possible impacted alarms. The alarm has two leaf-lists to identify possible impacted
resources and possible root-cause resources. The system should not resources and possible root-cause resources. The system should not
send individual alarms for the possible root-cause resources and represent individual alarms for the possible root-cause resources and
impacted resources. These serves as hints only. It is up to the impacted resources. These serves as hints only. It is up to the
client application to use this information to present the overall client application to use this information to present the overall
status. status.
A system should always strive to identify the resource that can be
acted upon as the "resource" leaf. The "impacted-resource" leaf-list
shall be used to identify any side-effects of the alarm. The
impacted resources can not be acted upon to fix the problem. An
example of this kind of alarm might be a disc full problem which
impacts a number of databases.
In some occasions the system might not be capable of detecting the
root cause, the resource that can be acted upon. The instrumentation
in this case only monitors the side-effect and needs to represent an
alarm that indicates a situation that needs acting upon. The
instrumentation still might identify possible candidates for the
root-cause resource. In this case the "root-cause-resource" leaf-
list can be used to indicate the candidate root-cause resources. An
example of this kind of alarm might be an active test tool that
detects an SLA violation on a VPN connection and identifies the
devices along the chain as candidate root causes.
The alarm module also supports a way to associate different alarms to
each other with the "related-alarm" list. This list enables the
server to inform the client that certain alarms are related to other
alarms.
Note well that this module does not prescribe any dependencies or
preference between the above alarm correlation mechanisms. Different
systems have different capabilities and the above described
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 this criteria are ignored alarm implies that any alarms fulfilling this criteria are ignored
(blocked/filtered). Shelved alarms appear in a dedicated shelved (blocked/filtered). Shelved alarms appear in a dedicated shelved
alarm list in order not to disturb the relevant alarms. Shelved alarm list in order not to disturb the relevant alarms. Shelved
alarms do not generate notifications. alarms do not generate notifications.
3.8. Alarm Profiles
Alarm profiles are used to configure further information to an alarm
type. This module supports configuring severity levels overriding
the system default levels. This corresponds to the Alarm Assignment
Profile, ASAP, functionality in M.3100 [M.3100] and M.3160 [M.3160].
Other standard or enterprise modules can augment this list with
further alarm type information.
4. Alarm Data Model 4. Alarm Data Model
Alarm shelving and operator actions are YANG features so that a The fundamental parts of the data model are the "alarm-list" with
server can select not to support these. associated notifications and the "alarm-inventory" list of all
possible alarm types. These MUST be implemented by a system. The
rest of the data model are made conditional with YANG the features
"operator-actions", "alarm-shelving", "alarm-history", "alarm-
summary", "alarm-profile", and "severity-assignment".
The data model has the following overall structure: The data model has the following overall structure:
+--rw alarms
+--rw control
| +--rw max-alarm-status-changes? union
| +--rw notify-status-changes? boolean
| +--rw alarm-shelving {alarm-shelving}?
| ...
+--ro alarm-inventory
| +--ro alarm-type* [alarm-type-id alarm-type-qualifier]
| ...
+--ro summary
| +--ro alarm-summary* [severity]
| | ...
| +--ro shelves-active? empty {alarm-shelving}?
+--ro alarm-list
| +--ro number-of-alarms? yang:gauge32
| +--ro last-changed? yang:date-and-time
| +--ro alarm* [resource alarm-type-id alarm-type-qualifier]
| ...
+--ro shelved-alarms {alarm-shelving}?
+--ro number-of-shelved-alarms? yang:gauge32
+--ro alarm-shelf-last-changed? yang:date-and-time
+--ro shelved-alarm*
[resource alarm-type-id alarm-type-qualifier]
...
4.1. Alarm Control 4.1. Alarm Control
The "/alarms/control/notify-status-changes" leaf controls if The "/alarms/control/notify-status-changes" choice controls if
notifications are sent for all state changes, severity change and notifications are sent for all state changes, only raise and clear,
alarm text change, or just for new and cleared alarms. or only notifications more severe than a configured level. This
feature in combination with alarm shelving corresponds to the ITU
Alarm Report Control functionality.
Every alarm has a list of status changes, this is a circular list. Every alarm has a list of status changes, this is a circular list.
The length of this list is controlled by "/alarms/control/max-alarm- The length of this list is controlled by "/alarms/control/max-alarm-
status-changes". status-changes".
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 alarms
+--rw control
+--rw alarm-shelving {alarm-shelving}?
+--rw shelf* [name]
+--rw name string
+--rw resource* resource-match
+--rw alarm-type-id? alarm-type-id
+--rw alarm-type-qualifier-match? string
+--rw description? string
Shelved alarms are shown in a dedicated shelved alarm list. The Shelved alarms are shown in a dedicated shelved alarm list. The
instrumentation MUST move shelved alarms from the alarm list instrumentation MUST move shelved alarms from the alarm list
(/alarms/alarm-list) to the shelved alarm list (/alarms/shelved- (/alarms/alarm-list) to the shelved alarm list (/alarms/shelved-
alarms/). Shelved alarms do not generate any notifications. When alarms/). Shelved alarms do not generate any notifications. When
the shelving criteria is removed or changed the alarm list MUST be the shelving criteria is removed or changed the alarm list MUST be
updated to the correct actual state of the alarms. updated to the correct actual state of the alarms.
Shelving and unshelving can only be performed by editing the shelf Shelving and unshelving can only be performed by editing the shelf
configuration. It cannot be performed on individual alarms. The configuration. It cannot be performed on individual alarms. The
server will add an operator state indicating that the alarm was server will add an operator state indicating that the alarm was
skipping to change at page 12, line 38 skipping to change at page 12, line 44
if there are shelved alarms. if there are shelved alarms.
A system can select to not support the shelving feature. A system can select to not support the shelving feature.
4.2. Alarm Inventory 4.2. Alarm Inventory
The alarm inventory represents all possible alarm types that may The alarm inventory represents all possible alarm types that may
occur in the system. A management system may use this to build alarm occur in the system. A management system may use this to build alarm
procedures. The alarm inventory is relevant for several reasons: procedures. The alarm inventory is relevant for several reasons:
The system might not instrument all alarm type identities. The system might not instrument all defined alarm type identities,
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.
The alarm inventory tree is shown below: A server MUST implement the alarm inventory in order to enable
controlled alarm procedures in the client.
+--rw alarms The alarm inventory tree is shown below:
+--ro alarm-inventory
+--ro alarm-type* [alarm-type-id alarm-type-qualifier]
+--ro alarm-type-id alarm-type-id
+--ro alarm-type-qualifier alarm-type-qualifier
+--ro resource* resource-match
+--ro has-clear boolean
+--ro severity-levels* severity
+--ro description string
4.3. Alarm Summary 4.3. Alarm Summary
The alarm summary list summarises alarms per severity; how many The alarm summary list summarises 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:
+--rw alarms
+--ro summary
+--ro alarm-summary* [severity]
| +--ro severity severity
| +--ro total? yang:gauge32
| +--ro cleared? yang:gauge32
| +--ro cleared-not-closed? yang:gauge32
| | {operator-actions}?
| +--ro cleared-closed? yang:gauge32
| | {operator-actions}?
| +--ro not-cleared-closed? yang:gauge32
| | {operator-actions}?
| +--ro not-cleared-not-closed? yang:gauge32
| {operator-actions}?
+--ro shelves-active? empty {alarm-shelving}?
4.4. The Alarm List 4.4. The Alarm List
The alarm list (/alarms/alarm-list) is a function from (resource, The alarm list (/alarms/alarm-list) is a function from (resource,
alarm type, alarm type qualifier) to the current alarm state. alarm type, alarm type qualifier) to the current alarm state.
+--ro alarm-list
+--ro number-of-alarms? yang:gauge32
+--ro last-changed? yang:date-and-time
+--ro alarm* [resource alarm-type-id alarm-type-qualifier]
+--ro resource resource
+--ro alarm-type-id alarm-type-id
+--ro alarm-type-qualifier alarm-type-qualifier
+--ro alt-resource* resource
+--ro related-alarm*
| [resource alarm-type-id alarm-type-qualifier]
| +--ro resource
| | -> /alarms/alarm-list/alarm/resource
| +--ro alarm-type-id leafref
| +--ro alarm-type-qualifier leafref
+--ro impacted-resource* resource
+--ro root-cause-resource* resource
+--ro time-created yang:date-and-time
+--ro is-cleared boolean
+--ro last-changed yang:date-and-time
+--ro perceived-severity severity
+--ro alarm-text alarm-text
+--ro status-change* [time] {alarm-history}?
| +--ro time yang:date-and-time
| +--ro perceived-severity severity-with-clear
| +--ro alarm-text alarm-text
+--ro operator-state-change* [time] {operator-actions}?
| +--ro time yang:date-and-time
| +--ro operator string
| +--ro state operator-state
| +--ro text? string
+---x set-operator-state {operator-actions}?
+---w input
+---w state writable-operator-state
+---w text? string
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 Alarms List
The shelved alarm list has the same structure as the alarm list The shelved alarm list has the same structure as the alarm list
above. It shows all the alarms that matches the shelving criteria above. It shows all the alarms that matches the shelving criteria
(/alarms/control/alarm-shelving). (/alarms/control/alarm-shelving).
4.6. RPCs and Actions 4.6. Alarm Profiles
Alarm profiles (/alarms/alarm-profile/) is a list of configurable
alarm types. The list supports configurable alarm severity levels in
the container "alarm-severity-assignment-profile". If an alarm
matches the configured alarm type it MUST use the configured severity
level(s) instead of the system default. This configuration MUST also
be represented in the alarm inventory.
4.7. RPCs and Actions
The alarm module supports rpcs and actions to manage the alarms: The alarm module supports rpcs and actions to manage the alarms:
"purge-alarms" (rpc): delete alarms according to specific "purge-alarms" (rpc): delete alarms according to specific
criteria, for example all cleared alarms older then a specific criteria, for example all cleared alarms older then a specific
date. date.
"compress-alarms" (rpc): compress the status-change list for the "compress-alarms" (rpc): compress the status-change list for the
alarms. alarms.
"set-operator-state" (action): change the operator state for an "set-operator-state" (action): change the operator state for an
alarm: for example acknowledge. alarm: for example acknowledge.
4.7. Notifications 4.8. Notifications
The alarm module supports a general notification to report alarm The alarm module 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 acknowledge.
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. Alarm YANG Module 5. Alarm YANG Module
This YANG module references [RFC6991]. This YANG module references [RFC6991].
<CODE BEGINS> file "ietf-alarms@2018-02-01.yang" <CODE BEGINS> file "ietf-alarms@2018-08-08.yang"
module ietf-alarms { module ietf-alarms {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-alarms"; namespace "urn:ietf:params:xml:ns:yang:ietf-alarms";
prefix al; prefix al;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
reference "RFC 6991: Common YANG Data Types."; reference "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: <http://tools.ietf.org/wg/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 defines an interface for managing alarms. Main "This module defines an interface for managing alarms. Main
inputs to the module design are the 3GPP Alarm IRP, ITU-T X.733 inputs to the module design are the 3GPP Alarm IRP, ITU-T X.733
and ANSI/ISA-18.2 alarm standards. and ANSI/ISA-18.2 alarm standards.
Main features of this module include: Main features of this module include:
* Alarm list: * Alarm list:
A list of all alarms. Cleared alarms stay in A list of all alarms. Cleared alarms stay in
the list until explicitly removed. the list until explicitly purged.
* Operator actions on alarms: * Operator actions on alarms:
Acknowledging and closing alarms. Acknowledging and closing alarms.
* Administrative actions on alarms: * Administrative actions on alarms:
Purging alarms from the list according to specific Purging alarms from the list according to specific
criteria. criteria.
* Alarm inventory: * Alarm inventory:
A management application can read all A management application can read all
alarm types implemented by the system. alarm types implemented by the system.
* Alarm shelving: * Alarm shelving:
Shelving (blocking) alarms according Shelving (blocking) alarms according
to specific criteria. to specific criteria.
* Alarm profiles:
A management system can attach further
information to alarm types, for example
overriding system default severity
levels.
This module uses a stateful view on alarms. An alarm is a state This module uses a stateful view on alarms. An alarm is a state
for a specific resource (note that an alarm is not a for a specific resource (note that an alarm is not a
notification). An alarm type is a possible alarm state for a notification). An alarm type is a possible alarm state for a
resource. For example, the tuple: resource. For example, the tuple:
('link-alarm', 'GigabitEthernet0/25') ('link-alarm', 'GigabitEthernet0/25')
is an alarm of type 'link-alarm' on the resource is an alarm of type 'link-alarm' on the resource
'GigabitEthernet0/25'. 'GigabitEthernet0/25'.
skipping to change at page 17, line 43 skipping to change at page 16, line 51
(('link-alarm', 'GigabitEthernet0/25'), (('link-alarm', 'GigabitEthernet0/25'),
warning, warning,
'interface down while interface admin state is up', 'interface down while interface admin state is up',
cleared, cleared,
closed) closed)
Administrative actions like removing closed alarms older than a Administrative actions like removing closed alarms older than a
given time is supported. given time is supported.
This alarm module does not define how the underlying
instrumentation detects and clears the specific alarms.
That belongs to the SDO or enterprise that owns that
specific technology.
Copyright (c) 2018 IETF Trust and the persons identified as Copyright (c) 2018 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).
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and
'OPTIONAL' in the module text are to be interpreted as described 'OPTIONAL' in the module text are to be interpreted as described
in RFC 2119 (https://tools.ietf.org/html/rfc2119). in RFC 2119 (https://tools.ietf.org/html/rfc2119).
This version of this YANG module is part of RFC XXXX This version of this YANG module is part of RFC XXXX
(https://tools.ietf.org/html/rfcXXXX); see the RFC itself for (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for
full legal notices."; full legal notices.";
revision 2018-02-01 { revision 2018-08-08 {
description description
"Initial revision."; "Initial revision.";
reference reference "RFC XXXX: YANG Alarm Module";
"RFC XXXX: YANG Alarm Module";
} }
/* /*
* 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.";
skipping to change at page 18, line 44 skipping to change at page 18, line 8
(blocking) alarms."; (blocking) alarms.";
} }
feature alarm-history { feature alarm-history {
description description
"This feature indicates that server maintains a history of "This feature indicates that server maintains a history of
state changes for each alarm. For example, if an alarm 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.";
} }
feature alarm-summary {
description
"This feature indicates that the server summarizes the number
of alarms per severity and operator state.";
}
feature alarm-profile {
description
"The system supports clients to configure further information
to each alarm type.";
}
feature severity-assignment {
description
"The system supports configurable alarm severity levels.";
reference
"M.3160/M.3100 Alarm Severity Assignment Profile, ASAP";
}
/* /*
* Identities * Identities
*/ */
identity alarm-type-id { identity alarm-type-id {
description description
"Base identity for alarm types. A unique identification of the "Base identity for alarm types. A unique identification of the
alarm, not including the resource. Different resources can alarm, not including the resource. Different resources can
share alarm types. If the resource reports the same alarm share alarm types. If the resource reports the same alarm
type, it is to be considered to be the same alarm. The alarm type, it is to be considered to be the same alarm. The alarm
skipping to change at page 19, line 30 skipping to change at page 19, line 14
/* /*
* Common types * Common types
*/ */
typedef resource { typedef resource {
type union { type union {
type instance-identifier { type instance-identifier {
require-instance false; require-instance false;
} }
type yang:object-identifier; type yang:object-identifier;
type yang:uuid;
type string; type string;
} }
description description
"This is an identification of the alarming resource, such as an "This is an identification of the alarming resource, such as an
interface. It should be as fine-grained as possible both to interface. It should be as fine-grained as possible both to
guide the operator and to guarantee uniqueness of the alarms. guide the operator and to guarantee uniqueness of the alarms.
If the alarming resource is modelled in YANG, this type will If the alarming resource is modelled in YANG, this type will
be an instance-identifier. be an instance-identifier.
If the resource is an SNMP object, the type will be an If the resource is an SNMP object, the type will be an
object-identifier. object-identifier.
If the resource is anything else, for example a distinguished If the resource is anything else, for example a distinguished
name or a CIM path, this type will be a string. name or a CIM path, this type will be a string.
If the alarming object is identified by a UUID use the uuid
type. Be cautious when using this type, since a UUID is hard
to use for an operator.
If the server supports several models, the presedence should If the server supports several models, the presedence should
be in the order as given in the union definition."; be in the order as given in the union definition.";
} }
typedef resource-match { typedef resource-match {
type union { type union {
type yang:xpath1.0; type yang:xpath1.0;
type yang:object-identifier; type yang:object-identifier;
type string; type string;
} }
description description
"This type is used to match resources of type 'resource'. "This type is used to match resources of type 'resource'.
Since the type 'resource' is a union of three different types, Since the type 'resource' is a union of different types,
the 'resource-match' type is also a union if corresponding the 'resource-match' type is also a union of corresponding
types. types.
If the type is given as an XPath 1.0 expression, a resource If the type is given as an XPath 1.0 expression, a resource
of type 'instance-identifier' matches if the instance is part of type 'instance-identifier' matches if the instance is part
of the node set that is the result of evaluating the XPath 1.0 of the node set that is the result of evaluating the XPath 1.0
expression. For example, the XPath 1.0 expression: expression. For example, the XPath 1.0 expression:
/if:interfaces/if:interface[if:type='ianaift:ethernetCsmacd'] /if:interfaces/if:interface[if:type='ianaift:ethernetCsmacd']
would match the resource instance-identifier: would match the resource instance-identifier:
skipping to change at page 20, line 39 skipping to change at page 20, line 28
type 'object-identifier' matches if the match object type 'object-identifier' matches if the match object
identifier is a prefix of the resource's object identifier. identifier is a prefix of the resource's object identifier.
For example, the value: For example, the value:
1.3.6.1.2.1.2.2 1.3.6.1.2.1.2.2
would match the resource object identifier: would match the resource object identifier:
1.3.6.1.2.1.2.2.1.1.5 1.3.6.1.2.1.2.2.1.1.5
If the type is given as a string, it is interpreted as a W3C If the type is given as an UUID or a string, it is interpreted
regular expression, which matches a resource of type 'string' as a W3C regular expression, which matches a resource of type
if the given regular expression matches the resource string. 'yang:uuid' or 'string' if the given regular expression
matches the resource string.
If the type is given as an XPath expressionm it is evaluated If the type is given as an XPath expression it is evaluated
in the following XPath context: in the following XPath context:
o The set of namespace declarations are those in scope on o The set of namespace declarations are those in scope on
the leaf element where this type is used. the leaf element where this type is used.
o The set of variable bindings is empty. o The set of variable bindings is empty.
o The function library is the core function library o The function library is the core function library
and the functions defined in Section 10 of RFC 7950. and the functions defined in Section 10 of RFC 7950.
skipping to change at page 21, line 22 skipping to change at page 21, line 12
type string; type string;
description description
"The string used to inform operators about the alarm. This "The string used to inform operators about the alarm. This
MUST contain enough information for an operator to be able MUST contain enough information for an operator to be able
to understand the problem and how to resolve it. If this to understand the problem and how to resolve it. If this
string contains structure, this format should be clearly string contains structure, this format should be clearly
documented for programs to be able to parse that documented for programs to be able to parse that
information."; information.";
} }
typedef severity { typedef severity {
type enumeration { type enumeration {
enum indeterminate { enum indeterminate {
value 2; value 2;
description description
"Indicates that the severity level could not be "Indicates that the severity level could not be
determined. This level SHOULD be avoided."; determined. This level SHOULD be avoided.";
} }
enum minor { enum minor {
value 3; value 3;
description description
skipping to change at page 21, line 44 skipping to change at page 21, line 34
non-service affecting fault condition and that corrective non-service affecting fault condition and that corrective
action should be taken in order to prevent a more serious action should be taken in order to prevent a more serious
(for example, service affecting) fault. Such a severity (for example, service affecting) fault. Such a severity
can be reported, for example, when the detected alarm can be reported, for example, when the detected alarm
condition is not currently degrading the capacity of the condition is not currently degrading the capacity of the
resource."; resource.";
} }
enum warning { enum warning {
value 4; value 4;
description description
"The 'warning' severity level indicates the detection of "The 'warning' severity level indicates the detection of a
a potential or impending service affecting fault, before potential or impending service affecting fault, before any
any significant effects have been felt. Action should be significant effects have been felt. Action should be
taken to further diagnose (if necessary) and correct the taken to further diagnose (if necessary) and correct the
problem in order to prevent it from becoming a more problem in order to prevent it from becoming a more
serious service affecting fault."; serious service affecting fault.";
} }
enum major { enum major {
value 5; value 5;
description description
"The 'major' severity level indicates that a service "The 'major' severity level indicates that a service
affecting condition has developed and an urgent affecting condition has developed and an urgent corrective
corrective action is required. Such a severity can be action is required. Such a severity can be reported, for
reported, for example, when there is a severe example, when there is a severe degradation in the
degradation in the capability of the resource capability of the resource and its full capability must be
and its full capability must be restored."; restored.";
} }
enum critical { enum critical {
value 6; value 6;
description description
"The 'critical' severity level indicates that a service "The 'critical' severity level indicates that a service
affecting condition has occurred and an immediate affecting condition has occurred and an immediate
corrective action is required. Such a severity can be corrective action is required. Such a severity can be
reported, for example, when a resource becomes totally reported, for example, when a resource becomes totally out
out of service and its capability must be restored."; of service and its capability must be restored.";
} }
} }
description description
"The severity level of the alarm. Note well that value 'clear' "The severity level of the alarm. Note well that value 'clear'
is not included. If an alarm is cleared or not is a separate is not included. If an alarm is cleared or not is a separate
boolean flag."; boolean flag.";
reference reference
"ITU Recommendation X.733: Information Technology "ITU Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function"; - System Management: Alarm Reporting Function";
} }
typedef severity-with-clear { typedef severity-with-clear {
type union { type union {
type enumeration { type enumeration {
enum cleared { enum cleared {
value 1; value 1;
description description
"The alarm is cleared by the instrumentation."; "The alarm is cleared by the instrumentation.";
} }
} }
type severity; type severity;
} }
description description
"The severity level of the alarm including clear. "The severity level of the alarm including clear.
This is used *only* in notifications reporting state changes This is used *only* in notifications reporting state changes
for an alarm."; for an alarm.";
} }
typedef writable-operator-state { typedef writable-operator-state {
type enumeration { type enumeration {
enum none { enum none {
value 1; value 1;
description description
"The alarm is not being taken care of."; "The alarm is not being taken care of.";
} }
enum ack { enum ack {
value 2; value 2;
description description
"The alarm is being taken care of. Corrective action not "The alarm is being taken care of. Corrective action not
skipping to change at page 23, line 27 skipping to change at page 23, line 18
description description
"Corrective action taken successfully."; "Corrective action taken successfully.";
} }
} }
description description
"Operator states on an alarm. The 'closed' state indicates "Operator states on an alarm. The 'closed' state indicates
that an operator considers the alarm being resolved. This that an operator considers the alarm being resolved. This
is separate from the alarm's 'is-cleared' leaf."; is separate from the alarm's 'is-cleared' leaf.";
} }
typedef operator-state { typedef operator-state {
type union { type union {
type writable-operator-state; type writable-operator-state;
type enumeration { type enumeration {
enum shelved { enum shelved {
value 4; value 4;
description description
"The alarm is shelved. Alarms in /alarms/shelved-alarms/ "The alarm is shelved. Alarms in /alarms/shelved-alarms/
MUST be assigned this operator state by the server as MUST be assigned this operator state by the server as
the last entry in the operator-state-change list. The the last entry in the operator-state-change list. The
text for that entry SHOULD include the shelf name."; text for that entry SHOULD include the shelf name.";
} }
enum un-shelved { enum un-shelved {
value 5; value 5;
description description
"The alarm is moved back to 'alarm-list' from a shelf. "The alarm is moved back to 'alarm-list' from a shelf.
Alarms that are moved from /alarms/shelved-alarms/ Alarms that are moved from /alarms/shelved-alarms/ to
to /alarms/alarm-list MUST be assigned this /alarms/alarm-list MUST be assigned this state by the
state by the server as the last entry in the server as the last entry in the 'operator-state-change'
'operator-state-change' list. The text for that list. The text for that entry SHOULD include the shelf
entry SHOULD include the shelf name."; name.";
} }
} }
} }
description description
"Operator states on an alarm. The 'closed' state indicates "Operator states on an alarm. The 'closed' state indicates
that an operator considers the alarm being resolved. This that an operator considers the alarm being resolved. This
is separate from the alarm's 'is-cleared' leaf."; is separate from the alarm's 'is-cleared' leaf.";
} }
/* Alarm type */ /* Alarm type */
skipping to change at page 24, line 45 skipping to change at page 24, line 36
/* /*
* Groupings * Groupings
*/ */
grouping common-alarm-parameters { grouping common-alarm-parameters {
description description
"Common parameters for an alarm. "Common parameters for an alarm.
This grouping is used both in the alarm list and in the This grouping is used both in the alarm list and in the
notification representing an alarm state change."; notification representing an alarm state change.";
leaf resource { leaf resource {
type resource; type resource;
mandatory true; mandatory true;
description description
"The alarming resource. See also 'alt-resource'. "The alarming resource. See also 'alt-resource'.
This could for example be a reference to the alarming This could for example be a reference to the alarming
interface"; interface";
} }
leaf alarm-type-id { leaf alarm-type-id {
type alarm-type-id; type alarm-type-id;
mandatory true; mandatory true;
description description
"This leaf and the leaf 'alarm-type-qualifier' together "This leaf and the leaf 'alarm-type-qualifier' together
provides a unique identification of the alarm type."; provides a unique identification of the alarm type.";
} }
leaf alarm-type-qualifier { leaf alarm-type-qualifier {
type alarm-type-qualifier; type alarm-type-qualifier;
description description
"This leaf is used when the 'alarm-type-id' leaf cannot "This leaf is used when the 'alarm-type-id' leaf cannot
uniquely identify the alarm type. Normally, this is not uniquely identify the alarm type. Normally, this is not
the case, and this leaf is the empty string."; the case, and this leaf is the empty string.";
} }
leaf-list alt-resource { leaf-list alt-resource {
type resource; type resource;
description description
"Used if the alarming resource is available over other "Used if the alarming resource is available over other
interfaces. This field can contain SNMP OID's, CIM paths or interfaces. This field can contain SNMP OID's, CIM paths or
3GPP Distinguished names for example."; 3GPP Distinguished names for example.";
} }
list related-alarm { list related-alarm {
key "resource alarm-type-id alarm-type-qualifier"; key "resource alarm-type-id alarm-type-qualifier";
description description
"References to related alarms. Note that the related alarm "References to related alarms. Note that the related alarm
might have been removed from the alarm list."; might have been purged from the alarm list.";
leaf resource { leaf resource {
type leafref { type leafref {
path "/alarms/alarm-list/alarm/resource"; path "/alarms/alarm-list/alarm/resource";
require-instance false; require-instance false;
} }
description description
"The alarming resource for the related alarm."; "The alarming resource for the related alarm.";
} }
leaf alarm-type-id { leaf alarm-type-id {
type leafref { type leafref {
skipping to change at page 27, line 45 skipping to change at page 27, line 26
"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 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 "This grouping defines parameters that can be changed by an
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 alarm.";
} }
leaf operator { leaf operator {
type string; type string;
mandatory true; mandatory true;
description description
skipping to change at page 28, line 36 skipping to change at page 28, line 19
description description
"Alarm parameters that originates from the resource view."; "Alarm parameters that originates 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-changed { leaf last-changed {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
description description
"A timestamp when the alarm status was last changed. Status "A timestamp when the alarm status was last changed. Status
changes are changes to 'is-cleared', 'perceived-severity', changes are changes to 'is-cleared', 'perceived-severity',
and 'alarm-text'."; and 'alarm-text'.";
} }
leaf perceived-severity { leaf perceived-severity {
type severity; type severity;
mandatory true; mandatory true;
description description
"The last severity of the alarm. "The last severity of the alarm.
If an alarm was raised with severity 'warning', but later If an alarm was raised with severity 'warning', but later
changed to 'major', this leaf will show 'major'."; changed to 'major', this leaf will show 'major'.";
} }
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 information for an operator to be able to understand
the problem and how to resolve it."; the 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 time-stamp in this list MUST
correspond to the leafs 'is-cleared', 'perceived-severity' correspond to the leafs 'is-cleared', 'perceived-severity'
and 'alarm-text' for the alarm. The time-stamp for that and 'alarm-text' for the alarm. The time-stamp for that
entry MUST be equal to the 'last-changed' leaf. entry MUST be equal to the 'last-changed' leaf.
skipping to change at page 29, line 51 skipping to change at page 29, line 27
uses alarm-state-change-parameters; uses alarm-state-change-parameters;
} }
} }
/* /*
* The /alarms data tree * The /alarms data tree
*/ */
container alarms { container alarms {
description description
"The top container for this module"; "The top container for this module.";
container control { container control {
description description
"Configuration to control the alarm behaviour."; "Configuration to control the alarm behaviour.";
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 "The status-change entries are kept in a circular list
per alarm. When this number is exceeded, the oldest per alarm. When this number is exceeded, the oldest
status change entry is automatically removed. If the status change entry is automatically removed. If the
value is 'infinite', the status change entries are value is 'infinite', the status change entries are
accumulated infinitely."; accumulated infinitely.";
} }
choice notify-status-changes {
leaf notify-status-changes {
type boolean;
default false;
description description
"This leaf controls whether notifications are sent on all "This leaf controls the notifications sent for alarm status
alarm status updates, e.g., updated perceived-severity or updates. There are three options:
alarm-text. By default the notifications are only sent 1. notifications are sent for all updates, severity level
when a new alarm is raised, re-raised after being cleared changes and alarm text changes
and when an alarm is cleared."; 2. notifications are only sent for alarm raise and clear
3. notifications are sent for status changes equal to or
above the specified severity level. Clear notifications
shall always be sent
Notifications shall also be sent for state changes that
makes an alarm less severe than the specified level.
In option 3, assuming the severity level is set to major,
and that the alarm has the following state changes
[(Time, severity, clear)]:
[(T1, major, -), (T2, minor, -), (T3, warning, -),
(T4, minor, -), (T5, major, -), (T6, critical, -),
(T7, major. -), (T8, major, clear)]
In that case, notifications will be sent at
T1, T2, T5, T6, T7 and T8.";
leaf notify-all-state-changes {
type empty;
description
"Send notifications for all status changes.";
}
leaf notify-raise-and-clear {
type empty;
description
"Send notifications only for raise, clear, and re-raise.
Notifications for severity level changes or alarm text
changes are not sent.";
}
leaf notify-severity-level {
type severity;
description
"Only send notifications for alarm state changes
crossing 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 server will move any alarms (block/filter) alarms. The server will move any alarms
corresponding to the shelving criteria from the corresponding to the shelving criteria from the
alarms/alarm-list/alarm list to the alarms/alarm-list/alarm list to the
alarms/shelved-alarms/shelved-alarm list. It will also alarms/shelved-alarms/shelved-alarm list. It will also
stop sending notifications for the shelved alarms. The stop sending notifications for the shelved alarms. The
conditions in the shelf criteria are logically ANDed. conditions in the shelf criteria are logically ANDed.
When the shelving criteria is deleted or changed, the When the shelving criteria is deleted or changed, the
non-matching alarms MUST appear in the non-matching alarms MUST appear in the
alarms/alarm-list/alarm list according to the real state. alarms/alarm-list/alarm list according to the real state.
This means that the instrumentation MUST maintain states This means that the instrumentation MUST maintain states
for the shelved alarms. Alarms that match the criteria for the shelved alarms. Alarms that match the criteria
shall have an operator-state 'shelved'. When the shelf shall have an operator-state 'shelved'. When the shelf
configuration will remove an alarm from the shelf the configuration will remove an alarm from the shelf the
server shall add an operator state 'unshelved'"; server shall add an operator state 'unshelved'.";
list shelf { list shelf {
key "name"; key "name";
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.
Criterias 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.";
} }
leaf alarm-type-id { leaf alarm-type-id {
type alarm-type-id; type alarm-type-id;
description description
"Shelve all alarms that have an alarm-type-id that is "Shelve all alarms that have an alarm-type-id that is
equal to or derived from the given alarm-type-id."; equal to or derived from the given alarm-type-id.";
skipping to change at page 33, line 31 skipping to change at page 33, line 33
leaf description { leaf description {
type string; type string;
mandatory true; mandatory true;
description description
"A description of the possible alarm. It SHOULD include "A description of the possible alarm. It SHOULD include
information on possible underlying root causes and information on possible underlying root causes and
corrective actions."; corrective actions.";
} }
} }
} }
container summary { container summary {
if-feature "alarm-summary";
config false; config false;
description description
"This container gives a summary of number of alarms"; "This container gives a summary of number of alarms.";
list alarm-summary { list alarm-summary {
key "severity"; key "severity";
description description
"A global summary of all alarms in the system. The summary "A global summary of all alarms in the system. The summary
does not include shelved alarms"; does not include shelved alarms.";
leaf severity { leaf severity {
type severity; type severity;
description description
"Alarm summary for this severity level."; "Alarm summary for this severity level.";
} }
leaf total { leaf total {
type yang:gauge32; type yang:gauge32;
description description
"Total number of alarms of this severity level."; "Total number of alarms of this severity level.";
} }
leaf cleared { leaf cleared {
type yang:gauge32; type yang:gauge32;
description description
"For this severity level, the number of alarms that are "For this severity level, the number of alarms that are
cleared."; cleared.";
} }
leaf cleared-not-closed { leaf cleared-not-closed {
if-feature operator-actions; if-feature "operator-actions";
type yang:gauge32; type yang:gauge32;
description description
"For this severity level, the number of alarms that are "For this severity level, the number of alarms that are
cleared but not closed."; cleared but not closed.";
} }
leaf cleared-closed { leaf cleared-closed {
if-feature operator-actions; if-feature "operator-actions";
type yang:gauge32; type yang:gauge32;
description description
"For this severity level, the number of alarms that are "For this severity level, the number of alarms that are
cleared and closed."; cleared and closed.";
} }
leaf not-cleared-closed { leaf not-cleared-closed {
if-feature operator-actions; if-feature "operator-actions";
type yang:gauge32; type yang:gauge32;
description description
"For this severity level, the number of alarms that are "For this severity level, the number of alarms that are
not cleared but closed."; not cleared but closed.";
} }
leaf not-cleared-not-closed { leaf not-cleared-not-closed {
if-feature operator-actions; if-feature "operator-actions";
type yang:gauge32; type yang:gauge32;
description description
"For this severity level, the number of alarms that are "For this severity level, the number of alarms that are
not cleared and not closed."; not cleared and not closed.";
} }
} }
leaf shelves-active { leaf shelves-active {
if-feature alarm-shelving; if-feature "alarm-shelving";
type empty; type empty;
description description
"This is a hint to the operator that there are active "This is a hint to the operator that there are active
alarm shelves. This leaf MUST exist if the alarm shelves. This leaf MUST exist if the
alarms/shelved-alarms/number-of-shelved-alarms is > 0."; alarms/shelved-alarms/number-of-shelved-alarms is > 0.";
} }
} }
container alarm-list { container alarm-list {
config false; config false;
description description
"The alarms in the system."; "The alarms in the system.";
leaf number-of-alarms { leaf number-of-alarms {
type yang:gauge32; type yang:gauge32;
description description
"This object shows the total number of "This object shows the total number of
alarms in the system, i.e., the total number alarms in the system, i.e., the total number
of entries in the alarm list."; of entries in the alarm list.";
skipping to change at page 35, line 39 skipping to change at page 35, line 36
resource: is-cleared, last-change, perceived-severity, resource: is-cleared, last-change, perceived-severity,
and alarm-text. An operator can change: operator-state and alarm-text. An operator can change: operator-state
and operator-text. and operator-text.
Entries appear in the alarm list the first time an Entries appear in the alarm list the first time an
alarm becomes active for a given alarm-type and resource. alarm becomes active for a given alarm-type and resource.
Entries do not get deleted when the alarm is cleared, this Entries do not get deleted when the alarm is cleared, this
is a boolean state in the alarm. is a boolean state in the alarm.
Alarm entries are removed, purged, from the list by an Alarm entries are removed, purged, from the list by an
explicit purge action. For example, delete all alarms explicit purge action. For example, purge all alarms
that are cleared and in closed operator-state that are that are cleared and in closed operator-state that are
older than 24 hours. Systems may also remove alarms based older than 24 hours. Systems may also remove alarms based
on locally configured policies which is out of scope for on locally configured policies which is out of scope for
this module."; this module.";
uses common-alarm-parameters; uses common-alarm-parameters;
leaf time-created { leaf time-created {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
description description
"The time-stamp when this alarm entry was created. This "The time-stamp when this alarm entry was created. This
represents the first time the alarm appeared, it can represents the first time the alarm appeared, it can
also represent that the alarm re-appeared after a purge. also represent that the alarm re-appeared after a purge.
Further state-changes of the same alarm does not change Further state-changes of the same alarm does not change
this leaf, these changes will update the 'last-changed' this leaf, these changes will update the 'last-changed'
leaf."; leaf.";
skipping to change at page 36, line 8 skipping to change at page 36, line 4
leaf time-created { leaf time-created {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
description description
"The time-stamp when this alarm entry was created. This "The time-stamp when this alarm entry was created. This
represents the first time the alarm appeared, it can represents the first time the alarm appeared, it can
also represent that the alarm re-appeared after a purge. also represent that the alarm re-appeared after a purge.
Further state-changes of the same alarm does not change Further state-changes of the same alarm does not change
this leaf, these changes will update the 'last-changed' this leaf, these changes will update the 'last-changed'
leaf."; leaf.";
}
}
uses resource-alarm-parameters; uses resource-alarm-parameters;
list operator-state-change { list operator-state-change {
if-feature operator-actions; if-feature "operator-actions";
key "time"; key "time";
description description
"This list is used by operators to indicate "This list is used by operators to indicate
the state of human intervention on an alarm. the state of human intervention on an alarm.
For example, if an operator has seen an alarm, For example, if an operator has seen an alarm,
the operator can add a new item to this list indicating the operator can add a new item to this list indicating
that the alarm is acknowledged."; that the alarm is acknowledged.";
uses operator-parameters; uses operator-parameters;
} }
action set-operator-state { action set-operator-state {
if-feature operator-actions; if-feature "operator-actions";
description description
"This is a means for the operator to indicate "This is a means for the operator to indicate
the level of human intervention on an alarm."; the level of human intervention on an alarm.";
input { input {
leaf state { leaf state {
type writable-operator-state; type writable-operator-state;
mandatory true; mandatory true;
description description
"Set this operator state."; "Set this operator state.";
} }
leaf text { leaf text {
type string; type string;
description description
"Additional optional textual information."; "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;
}
} }
} }
container shelved-alarms { container shelved-alarms {
if-feature alarm-shelving; if-feature "alarm-shelving";
config false; config false;
description description
"The shelved alarms. Alarms appear here if they match the "The shelved alarms. Alarms appear here if they match the
criterias in /alarms/control/alarm-shelving. This list does criteria in /alarms/control/alarm-shelving. This list does
not generate any notifications. The list represents alarms not generate any notifications. The list represents alarms
that are considered not relevant by the operator. Alarms in that are considered not relevant by the operator. Alarms in
this list have an operator-state of 'shelved'. This can not this list have an operator-state of 'shelved'. This can not
be changed."; be changed.";
leaf number-of-shelved-alarms { leaf number-of-shelved-alarms {
type yang:gauge32; type yang:gauge32;
description description
"This object shows the total number of currently "This object shows the total number of currently
alarms, i.e., the total number of entries alarms, i.e., the total number of entries
in the alarm list."; in the alarm list.";
} }
leaf alarm-shelf-last-changed { leaf alarm-shelf-last-changed {
type yang:date-and-time; type yang:date-and-time;
description description
"A timestamp when the shelved alarm list was last "A timestamp when the shelved alarm list was last
changed. The value can be used by a manager to changed. The value can be used by a manager to
initiate an alarm resynchronization procedure."; initiate an alarm resynchronization procedure.";
} }
list shelved-alarm { list shelved-alarm {
key "resource alarm-type-id alarm-type-qualifier"; key "resource alarm-type-id alarm-type-qualifier";
description description
"The list of shelved alarms. Each entry in the list holds "The list of shelved alarms. Shelved alarms
one alarm for a given alarm type and resource. An alarm can only be updated from the underlying resource,
can be updated from the underlying resource or by the no operator actions are supported.";
user. These changes are reflected in different lists
below the corresponding alarm.";
uses common-alarm-parameters; uses common-alarm-parameters;
leaf shelf-name { leaf shelf-name {
type leafref { type leafref {
path "/alarms/control/alarm-shelving/shelf/name"; path "/alarms/control/alarm-shelving/shelf/name";
require-instance false; require-instance false;
} }
description description
"The name of the shelf."; "The name of the shelf.";
} }
uses resource-alarm-parameters; uses resource-alarm-parameters;
list operator-state-change { list operator-state-change {
if-feature operator-actions; if-feature "operator-actions";
key "time"; key "time";
description description
"This list is used by operators to indicate "This list is used by operators to indicate
the state of human intervention on an alarm. the state of human intervention on an alarm.
For example, if an operator has seen an alarm, For shelved alarms, the system has set the list
the operator can add a new item to this list indicating item in the list to 'shelved'.";
that the alarm is acknowledged.";
uses operator-parameters; uses operator-parameters;
} }
} }
} }
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 al:alarm-type-id;
description
"The alarm type identifier to match.";
}
leaf alarm-type-qualifier-match {
type string;
description
"A W3C regular expression that is used to
match.";
}
leaf resource {
type al: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 M.3100, ITU M.3160
- Generic Network Information Model,
Alarm Severity Assignment Profile";
leaf-list severity-levels {
type al: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 the IETF alarm module supports
stateful alarms the mapping must allow for several
severity levels.
Assume a high-utilisation alarm type with two
thresholds with the system default severity levels of
threshold1 = warning and threshold2 = minor. Setting
this leaf-list to (minor, major) will assign the
severity levels threshold1 = minor and
threshold2 = major";
}
}
}
} }
/* /*
* Operations * Operations
*/ */
rpc compress-alarms { rpc compress-alarms {
if-feature alarm-history; if-feature "alarm-history";
description description
"This operation requests the server to compress entries in the "This operation requests the server to compress entries in the
alarm list by removing all but the latest state change for all alarm list by removing all but the latest state change for all
alarms. Conditions in the input are logically ANDed. If no alarms. Conditions in the input are logically ANDed. If no
input condition is given, all alarms are compressed."; input condition is given, all alarms are compressed.";
input { input {
leaf resource { leaf resource {
type leafref { type leafref {
path "/alarms/alarm-list/alarm/resource"; path "/alarms/alarm-list/alarm/resource";
require-instance false; require-instance false;
} }
description description
"Compress the alarms with this resource."; "Compress the alarms with this resource.";
} }
leaf alarm-type-id { leaf alarm-type-id {
type leafref { type leafref {
path "/alarms/alarm-list/alarm/alarm-type-id"; path "/alarms/alarm-list/alarm/alarm-type-id";
require-instance false;
} }
description description
"Compress alarms with this alarm-type-id."; "Compress alarms with this alarm-type-id.";
} }
leaf alarm-type-qualifier { leaf alarm-type-qualifier {
type leafref { type leafref {
path "/alarms/alarm-list/alarm/alarm-type-qualifier"; 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.";
}
}
}
rpc compress-shelved-alarms {
if-feature "alarm-history and alarm-shelving";
description
"This operation requests the server to compress entries in the
shelved alarm list by removing all but the latest state change
for all 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 description
"Compress the alarms with this alarm-type-qualifier."; "Compress the alarms with this alarm-type-qualifier.";
} }
} }
output { output {
leaf compressed-alarms { leaf compressed-alarms {
type uint32; type uint32;
description description
"Number of compressed alarm entries."; "Number of compressed alarm entries.";
skipping to change at page 41, line 5 skipping to change at page 43, line 4
"Severity level equal this leaf."; "Severity level equal 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 description
"Filter based on operator state."; "Filter based on operator state.";
} }
} }
rpc purge-alarms { rpc purge-alarms {
description description
"This operation requests the server to delete entries from the "This operation requests the server to delete entries from the
alarm list according to the supplied criteria. Typically it alarm list or the shelved alarms list according to the
can be used to delete alarms that are in closed operator state supplied criteria. To purge alarms in the shelved alarms,
and older than a specified time. The number of purged alarms set the operator-state filter input to 'shelved'.
is returned as an output parameter"; Typically it can be used to delete alarms that are
in closed operator state and older than a specified time.
In the shelved alarm list it makes sense to delete alarms that
are not relevant anymore.
The number of purged alarms is returned as an output
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.";
} }
} }
skipping to change at page 42, line 5 skipping to change at page 44, line 9
/* /*
* Notifications * Notifications
*/ */
notification alarm-notification { notification alarm-notification {
description description
"This notification is used to report a state change for an "This notification is used to report a state change for an
alarm. The same notification is used for reporting a newly alarm. The same notification is used for reporting a newly
raised alarm, a cleared alarm or changing the text and/or raised alarm, a cleared alarm or changing the text and/or
severity of an existing alarm."; severity of an existing alarm.";
uses common-alarm-parameters; uses common-alarm-parameters;
uses alarm-state-change-parameters; uses alarm-state-change-parameters;
} }
notification alarm-inventory-changed { notification alarm-inventory-changed {
description description
"This notification is used to report that the list of possible "This notification is used to report that the list of possible
alarms has changed. This can happen when for example if a new alarms has changed. This can happen when for example if a new
software module is installed, or a new physical card is software module is installed, or a new physical card is
inserted"; inserted.";
}
notification operator-action {
if-feature operator-actions;
description
"This notification is used to report that an operator
acted upon an alarm.";
leaf resource {
type leafref {
path "/alarms/alarm-list/alarm/resource";
require-instance false;
}
description
"The alarming resource.";
}
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 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 alarm.";
}
uses operator-parameters;
} }
} }
<CODE ENDS> <CODE ENDS>
6. X.733 Alarm Mapping Data Model 6. X.733 Extensions
Many alarm management systems are based on the X.733 alarm standard.
This YANG module allows a mapping from alarm types to X.733 event-
type and probable-cause.
The module augments the alarm inventory, the alarm list and the alarm Many alarm systems are based on the X.733, [X.733], and X.736 [X.736]
notification with X.733 parameters. alarm standards. This module 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. This might be needed when the default mapping configure the mapping from alarm types to X.733 event-type and
provided by the system is in conflict with other systems or not probable-cause parameters. This might be needed when the default
considered good. mapping provided by the system is in conflict with other management
systems or not considered correct.
7. X.733 Alarm Mapping YANG Module Note that the IETF Alarm Module term 'resource' is synonymous to the
ITU term 'managed object'.
This YANG module references [X.733]. 7. The X.733 Mapping Module
<CODE BEGINS> file "ietf-alarms-x733@2017-10-30.yang" This YANG module references [X.733] and [X.736].
<CODE BEGINS> file "ietf-alarms-x733@2018-08-08.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 {
prefix yang;
reference "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: <http://tools.ietf.org/wg/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 mapping "This module augments the ietf-alarms module with X.733 alarm
information. The following structures are augmented with parameters.
event type and probable cause:
1) alarm inventory: all possible alarms. The following structures are augmented with X.733 event type
2) alarm: every alarm in the system. and probable cause:
3) alarm notification: notifications indicating alarm state
changes.
The module also optionally allows the alarm management system 1) alarms/alarm-inventory: all possible alarm types
to configure the mapping. The mapping does not include a 2) alarms/alarm-list: every alarm in the system
a corresponding specific problem value. The recommendation is 3) alarm-notification: notifications indicating alarm state
to use alarm-type-qualifier which serves the same purpose."; changes
The module also optionally allows the alarm management system
to configure the mapping from the IETF Alarm module alarm keys
to the ITU tuple (event-type, probable-cause).
The mapping does not include a corresponding X.733 specific
problem value. The recommendation is to use the
'alarm-type-qualifier' leaf which serves the same purpose.
The module uses an integer and a corresponding string for
probable cause instead of a globally defined enumeration, in
order to be able to manage conflicting enumeration definitions.
A single globally defined enumeration is challenging to
maintain.";
reference reference
"ITU Recommendation X.733: Information Technology "ITU Recommendation X.733: Information Technology
- Open Systems Interconnection - Open Systems Interconnection
- System Management: Alarm Reporting Function"; - System Management: Alarm Reporting Function";
revision 2017-10-30 { revision 2018-08-08 {
description description
"Initial revision."; "Initial revision.";
reference
"RFC XXXX: YANG Alarm Module"; reference "RFC XXXX: YANG Alarm Module";
} }
/* /*
* 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
alarm type to event type and probable cause."; the IETF alarm module alarm-type to X733 event-type
and probable-cause.";
} }
/* /*
* Typedefs * Typedefs
*/ */
typedef event-type { typedef event-type {
type enumeration { type enumeration {
enum other { enum other {
value 1; value 1;
description description
"None of the below."; "None of the below.";
} }
enum communications-alarm { enum communications-alarm {
value 2; value 2;
description description
"An alarm of this type is principally associated with the "An alarm of this type is principally associated with the
procedures and/or processes required to convey procedures and/or processes required to convey
information from one point to another."; information from one point to another.";
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
} }
enum quality-of-service-alarm { enum quality-of-service-alarm {
value 3; value 3;
description description
"An alarm of this type is principally associated with a "An alarm of this type is principally associated with a
degradation in the quality of a service."; degradation in the quality of a service.";
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
} }
enum processing-error-alarm { enum processing-error-alarm {
value 4; value 4;
description description
"An alarm of this type is principally associated with a "An alarm of this type is principally associated with a
software or processing fault."; software or processing fault.";
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
} }
enum equipment-alarm { enum equipment-alarm {
value 5; value 5;
description description
"An alarm of this type is principally associated with an "An alarm of this type is principally associated with an
equipment fault."; equipment fault.";
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
} }
enum environmental-alarm { enum environmental-alarm {
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.";
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
} }
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.";
reference
"ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
} }
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 or
incorrect invocation of the service."; incorrect invocation of the service.";
reference
"ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
} }
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.";
reference
"ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
} }
enum security-service-or-mechanism-violation { enum security-service-or-mechanism-violation {
value 10; value 10;
description description
"An indication that a security attack has been detected by "An indication that a security attack has been detected by
a security service or mechanism."; a security service or mechanism.";
reference
"ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
} }
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.";
reference
"ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
} }
} }
description description
"The event types as defined by X.733 and X.736. The use of the "The event types as defined by X.733 and X.736.";
term 'event' is a bit confusing. In an alarm context these reference
are top level alarm types."; "ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function
ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
}
typedef trend {
type enumeration {
enum less-severe {
description
"There is at least one outstanding alarm of a
severity higher (more severe) than that in the
current alarm.";
}
enum no-change {
description
"The Perceived severity reported in the current
alarm is the same as the highest (most severe)
of any of the outstanding alarms";
}
enum more-severe {
description
"The Perceived severity in the current alarm is
higher (more severe) than that reported in any
of the outstanding alarms.";
}
}
description
"This type is used to describe the
severity trend of the alarming resource";
reference "Module Attribute-ASN1Module (X.721:02/1992)";
}
typedef value-type {
type union {
type int64;
type uint64;
type decimal64 {
fraction-digits 2;
}
}
description
"A generic union type to match ITU choice of 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 {
type event-type; type event-type;
description description
"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.";
} }
skipping to change at page 47, line 35 skipping to change at page 49, line 18
leaf event-type { leaf event-type {
type event-type; type event-type;
description description
"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 {
type string;
description
"The user friendly string matching
the probable cause integer value. The string
SHOULD match the X.733 enumeration. For example,
value 27 is 'localNodeTransmissionError'.";
}
container threshold-information {
description
"This parameter shall be present when the alarm
is a result of crossing a threshold. ";
leaf triggered-threshold {
type string;
description
"The identifier of the threshold attribute that
caused the notification.";
}
leaf observed-value {
type value-type;
description
"The value of the gauge or counter which crossed
the threshold. This may be different from the
threshold value if, for example, the gauge may
only take on discrete values.";
}
choice threshold-level {
description
"In the case of a gauge the threshold level specifies
a pair of threshold values, the first being the value
of the crossed threshold and the second, its corresponding
hysteresis; in the case of a counter the threshold level
specifies only the threshold value.";
case up {
leaf up-high {
type value-type;
description
"The going up threshold for rising the alarm.";
}
leaf up-low {
type value-type;
description
"The threshold level for clearing the alarm.
This is used for hysteresis functions for gauges.";
}
}
case down {
leaf down-low {
type value-type;
description
"The going down threshold for rising the alarm.";
}
leaf down-high {
type value-type;
description
"The threshold level for clearing the alarm.
This is used for hysteresis functions for gauges.";
}
}
}
leaf arm-time {
type yang:date-and-time;
description
"For a gauge threshold, the time at which the threshold
was last re-armed, namely the time after the previous
threshold crossing at which the hysteresis value of the
threshold was exceeded thus again permitting generation
of notifications when the threshold is crossed.
For a counter threshold, the later of the time at which
the threshold offset was last applied, or the time at
which the counter was last initialized (for resettable
counters).";
}
}
list monitored-attributes {
uses attribute;
key "id";
description
"The Monitored attributes parameter, when present, defines
one or more attributes of the resource and their
corresponding values at the time of the alarm.";
}
leaf-list proposed-repair-actions {
type string;
description
"This parameter, when present, is used if the cause is
known and the system being managed can suggest one or
more solutions (such as switch in standby equipment,
retry, replace media).";
}
leaf trend-indication {
type trend;
description
"This parameter specifies the current
severity trend of the resource. If present it
indicates that there are one or more alarms
('outstanding alarms') which have not been cleared,
and pertain to the same resource as that to which
this alarm ('current alarm') pertains.
The possible values are:
more-severe: The Perceived severity in the current
alarm is higher (more severe) than that reported in
any of the outstanding alarms.
no-change: The Perceived severity reported in the
current alarm is the same as the highest (most severe)
of any of the outstanding alarms.
less-severe: There is at least one outstanding alarm
of a severity higher (more severe) than that in the
current alarm.";
}
leaf backedup-status {
type boolean;
description
"This parameter, when present, specifies whether or not
the object emitting the alarm has been backed-up, and
services provided to the user have, therefore, not been
disrupted. The use of this field in conjunction with the
severity field provides information in an independent form
to qualify the seriousness of the alarm and the ability of
the system as a whole to continue to provide services.
If the value of this parameter is true, it indicates that
the object emitting the alarm has been backed-up; if false,
the object has not been backed-up.";
}
leaf backup-object {
type al:resource;
description
"This parameter shall be present when the Backed-up status
parameter is present and has the value true. This parameter
specifies the managed object instance that is providing
back-up services for the managed object about which the
notification pertains. This parameter is useful,
for example, when the back-up object is from a pool of
objects any of which may be dynamically allocated to
replace a faulty object.";
}
list additional-information {
key "identifier";
description
"This parameter allows the inclusion of a
set of additional information in the alarm. It is
a series of data structures each of which contains three
items of information: an identifier, a significance
indicator, and the problem information.";
leaf identifier {
type string;
description
"Identifies the data-type of the information parameter.";
}
leaf significant {
type boolean;
description
"Set to true if the receiving system must be able to
parse the contents of the information subparameter
for the event report to be fully understood.";
}
leaf information {
type string;
description
"Additional information about the alarm.";
}
}
leaf security-alarm-detector {
type al:resource;
description
"This parameter identifies the detector of the security
alarm.";
}
leaf service-user {
type al:resource;
description
"This parameter identifies the service-user whose request
for service led to the generation of the security alarm.";
}
leaf service-provider {
type al:resource;
description
"This parameter identifies the intended service-provider
of the service that led to the generation of the security
alarm.";
}
reference
"ITU Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function
ITU Recommendation X.736: Information Technology
- Open Systems Interconnection
- 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
attributes that can be mapped from the alarm-type
mechanism in the ietf-alarm 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 manager."; to match the enum values in the management application.";
}
leaf probable-cause-string {
type string;
description
"This string can be used to give a user friendly string
to the probable cause value.";
}
}
grouping attribute {
description
"A grouping to match the ITU generic reference to
an attribute.";
leaf id {
type al:resource;
description
"The resource representing the attribute.";
}
leaf value {
type string;
description
"The value represented as a string since it could
be of any type.";
} }
reference "Module Attribute-ASN1Module (X.721:02/1992)";
} }
/* /*
* Add X.733 parameters to the alarm definitions, alarms, * Add X.733 parameters to the alarm definitions, alarms,
* and notification. * and notification.
*/ */
augment "/al:alarms/al:alarm-inventory/al:alarm-type" { augment "/al:alarms/al:alarm-inventory/al:alarm-type" {
description description
"Augment X.733 mapping information to the alarm inventory."; "Augment X.733 mapping information to the alarm inventory.";
skipping to change at page 48, line 22 skipping to change at page 54, line 29
} }
/* /*
* Add X.733 parameters to the alarm definitions, alarms, * Add X.733 parameters to the alarm definitions, alarms,
* and notification. * and notification.
*/ */
augment "/al:alarms/al:alarm-inventory/al:alarm-type" { augment "/al:alarms/al:alarm-inventory/al:alarm-type" {
description description
"Augment X.733 mapping information to the alarm inventory."; "Augment X.733 mapping information to the alarm inventory.";
uses x733-alarm-definition-parameters; uses x733-alarm-definition-parameters;
} }
/*
* Add X.733 configurable mapping.
*/
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 over-ride 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
alarm type and alarm-type-qualifier to X.733 parameters."; alarm type and alarm-type-qualifier to X.733 parameters.";
} }
uses x733-alarm-definition-parameters; uses x733-alarm-definition-parameters;
} }
} }
augment "/al:alarms/al:alarm-list/al:alarm" { augment "/al:alarms/al:alarm-list/al: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: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>
8. IANA Considerations 8. IANA Considerations
This document registers a URI in the IETF XML registry [RFC3688]. This document registers a URI in the IETF XML registry [RFC3688].
Following the format in RFC 3688, the following registration is Following the format in RFC 3688, the following registration is
skipping to change at page 51, line 18 skipping to change at page 57, line 18
their valuable input on forming the alarm model. their valuable input on forming the alarm model.
The authors also wish to thank Nick Hancock, Joey Boyd, Tom Petch and The authors also wish to thank Nick Hancock, Joey Boyd, Tom Petch and
Balazs Lengyel for their extensive reviews and contributions to this Balazs Lengyel for their extensive reviews and contributions to this
document. document.
11. References 11. References
11.1. Normative References 11.1. Normative References
[M.3100] International Telecommunications Union, "Generic Network
Information Model", ITU-T Recommendation M.3100, 2005.
[M.3160] International Telecommunications Union, "Generic,
protocol-neutral management information model", ITU-T
Recommendation M.3100, 2008.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
DOI 10.17487/RFC2119, March 1997, <https://www.rfc- RFC2119, March 1997,
editor.org/info/rfc2119>. <http://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, <https://www.rfc- DOI 10.17487/RFC3688, January 2004,
editor.org/info/rfc3688>. <http://www.rfc-editor.org/info/rfc3688>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/
DOI 10.17487/RFC5246, August 2008, <https://www.rfc- RFC5246, August 2008, <https://www.rfc-editor.org/info/
editor.org/info/rfc5246>. rfc5246>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020, the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010, <https://www.rfc- DOI 10.17487/RFC6020, October 2010,
editor.org/info/rfc6020>. <http://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<https://www.rfc-editor.org/info/rfc6241>. <http://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>. <https://www.rfc-editor.org/info/rfc6242>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC
RFC 6991, DOI 10.17487/RFC6991, July 2013, 6991, DOI 10.17487/RFC6991, July 2013,
<https://www.rfc-editor.org/info/rfc6991>. <http://www.rfc-editor.org/info/rfc6991>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016, RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>. <http://www.rfc-editor.org/info/rfc7950>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>. <http://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[X.733] International Telecommunications Union, "Information [X.733] International Telecommunications Union, "Information
Technology - Open Systems Interconnection - Systems Technology - Open Systems Interconnection - Systems
Management: Alarm Reporting Function", Management: Alarm Reporting Function", ITU-T
ITU-T Recommendation X.733, 1992. Recommendation X.733, 1992.
11.2. Informative References 11.2. Informative References
[ALARMIRP] [ALARMIRP]
3GPP, "Telecommunication management; Fault Management; 3GPP, "Telecommunication management; Fault Management;
Part 2: Alarm Integration Reference Point (IRP): Part 2: Alarm Integration Reference Point (IRP):
Information Service (IS)", 3GPP TS 32.111-2 3.4.0, March Information Service (IS)", 3GPP TS 32.111-2 3.4.0, March
2005. 2005.
[ALARMSEM] [ALARMSEM]
skipping to change at page 52, line 38 skipping to change at page 58, line 46
"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, John Wiley and Sons, Ltd,
http://dx.doi.org/10.1002/nem.800", March 2012. http://dx.doi.org/10.1002/nem.800", March 2012.
[EEMUA] EEMUA Publication No. 191 Engineering Equipment and [EEMUA] EEMUA Publication No. 191 Engineering Equipment and
Materials Users Association, London, 2 edition., "Alarm Materials Users Association, London, 2 edition., "Alarm
Systems: A Guide to Design, Management and Procurement.", Systems: A Guide to Design, Management and Procurement.",
2007. 2007.
[I-D.ietf-netmod-yang-tree-diagrams]
Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft-
ietf-netmod-yang-tree-diagrams-05 (work in progress),
January 2018.
[ISA182] International Society of Automation,ISA, "ANSI/ISA- [ISA182] International Society of Automation,ISA, "ANSI/ISA-
18.2-2009 Management of Alarm Systems for the Process 18.2-2009 Management of Alarm Systems for the Process
Industries", 2009. Industries", 2009.
[RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management [RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management
Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877, Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877,
September 2004, <https://www.rfc-editor.org/info/rfc3877>. September 2004, <http://www.rfc-editor.org/info/rfc3877>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[X.736] International Telecommunications Union, "Information
Technology - Open Systems Interconnection - Systems
Management: Security alarm reporting function", ITU-T
Recommendation X.736, 1992.
Appendix A. Vendor-specific Alarm-Types Example Appendix A. Vendor-specific Alarm-Types Example
This example shows how to define alarm-types in a vendor-specific This example shows how to define alarm-types in a vendor-specific
module. In this case the vendor "xyz" has chosen to define top level module. In this case the vendor "xyz" has chosen to define top level
identities according to X.733 event types. identities according to X.733 event types.
module example-xyz-alarms { module example-xyz-alarms {
namespace "urn:example:xyz-alarms"; namespace "urn:example:xyz-alarms";
prefix xyz-al; prefix xyz-al;
skipping to change at page 57, line 25 skipping to change at page 64, line 10
<probable-cause>777</probable-cause> <probable-cause>777</probable-cause>
</x733-mapping> </x733-mapping>
</control> </control>
</alarms> </alarms>
Appendix F. Background and Usability Requirements Appendix F. Background and Usability Requirements
This section gives background information regarding design choices in This section gives background information regarding design choices in
the alarm module. It also defines usability requirements for alarms. the alarm module. It also defines usability requirements for alarms.
Alarm usability is important for an alarm interface. A data-model Alarm usability is important for an alarm interface. A data-model
will help in defining the format but if the actual alarms is of low will help in defining the format but if the actual alarms are of low
value we have not gained the goal of alarm management. value we have not gained the goal of alarm management.
The telecommunication domain has standardised an alarm interface in The telecommunication domain has standardised an alarm interface in
ITU-T X.733 [X.733]. This continued in mobile networks within the ITU-T X.733 [X.733]. This continued in mobile networks within the
3GPP organisation [ALARMIRP]. Although SNMP is the dominant 3GPP organisation [ALARMIRP]. Although SNMP is the dominant
mechanism for monitoring devices, IETF did not early on standardise mechanism for monitoring devices, IETF did not early on standardise
an alarm MIB. Instead, management systems interpreted the enterprise an alarm MIB. Instead, management systems interpreted the enterprise
specific traps per MIB and device to build an alarm list. When specific traps per MIB and device to build an alarm list. When
finally The Alarm MIB [RFC3877] was published, it had to address the finally The Alarm MIB [RFC3877] was published, it had to address the
existence of enterprise traps and map these into alarms. This existence of enterprise traps and map these into alarms. This
skipping to change at page 60, line 31 skipping to change at page 67, line 31
| 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 2: Definition of a Good Alarm Table 2: Definition of a Good Alarm
Vendors SHOULD rationalise all alarms according to above. Another Vendors SHOULD rationalise all alarms according to above. Another
crucial requirement is acceptable alarm rates. Vendors SHOULD make crucial requirement is acceptable alarm notification rates. Vendors
sure that they do not exceed the recommendations from EEMUA below: SHOULD make sure that they do not exceed the recommendations 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 over-demanding. |
| | | | | |
 End of changes. 181 change blocks. 
442 lines changed or deleted 767 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/