RFC 8632
A YANG Data Model for Alarm Management
7. The X.733 Mapping Module
Many alarm systems are based on the X.733 [X.733] and X.736 [X.736] alarm standards. This module "ietf-alarms-x733" augments the alarm inventory, the alarm lists, and the alarm notification with X.733 and X.736 parameters. The module also supports a feature whereby the alarm manager can configure the mapping from alarm types to X.733 "event-type" and "probable-cause" parameters. This might be needed when the default mapping provided by the system is in conflict with other management systems or not considered correct. Note that the term "resource" in this document is synonymous to the ITU term "managed object". This YANG module references [RFC6991], [X.721], [X.733], and [X.736]. <CODE BEGINS> file "ietf-alarms-x733@2019-09-11.yang" module ietf-alarms-x733 { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-alarms-x733"; prefix x733; import ietf-alarms { prefix al; } import ietf-yang-types { prefix yang; reference "RFC 6991: Common YANG Data Types"; } organization "IETF CCAMP Working Group";
contact
"WG Web: <https://trac.ietf.org/trac/ccamp>
WG List: <mailto:ccamp@ietf.org>
Editor: Stefan Vallin
<mailto:stefan@wallan.se>
Editor: Martin Bjorklund
<mailto:mbj@tail-f.com>";
description
"This module augments the ietf-alarms module with X.733 alarm
parameters.
The following structures are augmented with the X.733 event type
and probable cause:
1) alarms/alarm-inventory: all possible alarm types
2) alarms/alarm-list: every alarm in the system
3) alarm-notification: notifications indicating alarm-state
changes
4) alarms/shelved-alarms
The module also optionally allows the alarm-management system
to configure the mapping from the ietf-alarms' alarm keys
to the ITU tuple (event-type, probable-cause).
The mapping does not include a corresponding problem value
specific to X.733. 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.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.
Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject to
the license terms contained in, the Simplified BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8632; see
the RFC itself for full legal notices.";
reference
"ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function";
revision 2019-09-11 {
description
"Initial revision.";
reference
"RFC 8632: A YANG Data Model for Alarm Management";
}
/*
* Features
*/
feature configure-x733-mapping {
description
"The system supports configurable X733 mapping from
the ietf-alarms' alarm-type to X733 event-type
and probable-cause.";
}
/*
* Typedefs
*/
typedef event-type {
type enumeration {
enum other {
value 1;
description
"None of the below.";
}
enum communications-alarm {
value 2;
description
"An alarm of this type is principally associated with the
procedures and/or processes required to convey
information from one point to another.";
}
enum quality-of-service-alarm {
value 3;
description
"An alarm of this type is principally associated with a
degradation in the quality of a service.";
}
enum processing-error-alarm {
value 4;
description
"An alarm of this type is principally associated with a
software or processing fault.";
}
enum equipment-alarm {
value 5;
description
"An alarm of this type is principally associated with an
equipment fault.";
}
enum environmental-alarm {
value 6;
description
"An alarm of this type is principally associated with a
condition relating to an enclosure in which the equipment
resides.";
}
enum integrity-violation {
value 7;
description
"An indication that information may have been illegally
modified, inserted, or deleted.";
}
enum operational-violation {
value 8;
description
"An indication that the provision of the requested service
was not possible due to the unavailability, malfunction,
or incorrect invocation of the service.";
}
enum physical-violation {
value 9;
description
"An indication that a physical resource has been violated
in a way that suggests a security attack.";
}
enum security-service-or-mechanism-violation {
value 10;
description
"An indication that a security attack has been detected by
a security service or mechanism.";
}
enum time-domain-violation {
value 11;
description
"An indication that an event has occurred at an unexpected
or prohibited time.";
}
}
description
"The event types as defined by X.733 and X.736.";
reference
"ITU-T Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function
ITU-T 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
"ITU-T Recommendation X.721: Information Technology
- Open Systems Interconnection
- Structure of management information:
Definition of management information
Module Attribute-ASN1Module";
}
typedef value-type {
type union {
type int64;
type uint64;
type decimal64 {
fraction-digits 2;
}
}
description
"A generic union type to match the ITU choice of
integer and real.";
}
/*
* Groupings
*/
grouping x733-alarm-parameters {
description
"Common X.733 parameters for alarms.";
leaf event-type {
type event-type;
description
"The X.733/X.736 event type for this alarm.";
}
leaf probable-cause {
type uint32;
description
"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 that 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 is the value
of the crossed threshold, and the second is 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 raising the alarm.";
}
leaf up-low {
type value-type;
description
"The going-down threshold 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 raising the alarm.";
}
leaf down-high {
type value-type;
description
"The going-up threshold 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, it's the time at which the
threshold was last re-armed; namely, it's the time after
the previous threshold crossing at which the hysteresis
value of the threshold was exceeded, thus again permitting
the generation of notifications when the threshold is
crossed. For a counter threshold, it's the later of the
time at which the threshold offset was last applied or 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, and 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') that have not been cleared and that
pertain to the same resource as this alarm
('current alarm') does. 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; therefore, it
is possible to know whether or not services provided to the
user have been disrupted when this parameter is included.
The use of this field in conjunction with the
'perceived-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 'backedup-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 to 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 an additional
information set 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-T Recommendation X.733: Information Technology
- Open Systems Interconnection
- System Management: Alarm Reporting Function
ITU-T Recommendation X.736: Information Technology
- Open Systems Interconnection
- System Management: Security Alarm Reporting Function";
}
grouping x733-alarm-definition-parameters {
description
"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-alarms module.";
leaf event-type {
type event-type;
description
"The alarm type has this X.733/X.736 event type.";
}
leaf probable-cause {
type uint32;
description
"The alarm type has this X.733 probable cause value.
This module defines probable cause as an integer
and not as an enumeration. The reason being that the
primary use of probable cause is in the management
application if it is based on the X.733 standard.
However, most management applications have their own
defined enum definitions and merging enums from
different systems might create conflicts. By using
a configurable uint32, the system can be configured
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
"ITU-T Recommendation X.721: Information Technology
- Open Systems Interconnection
- Structure of management information:
Definition of management information
Module Attribute-ASN1Module";
}
/*
* Add X.733 parameters to the alarm definitions, alarms,
* and notification.
*/
augment "/al:alarms/al:alarm-inventory/al:alarm-type" {
description
"Augment X.733 mapping information to the alarm inventory.";
uses x733-alarm-definition-parameters;
}
/*
* Add X.733 configurable mapping.
*/
augment "/al:alarms/al:control" {
description
"Add X.733 mapping capabilities. ";
list x733-mapping {
if-feature "configure-x733-mapping";
key "alarm-type-id alarm-type-qualifier-match";
description
"This list allows a management application to control the
X.733 mapping for all alarm types in the system. Any entry
in this list will allow the alarm manager to override the
default X.733 mapping in the system, and the final mapping
will be shown in the alarm inventory.";
leaf alarm-type-id {
type al:alarm-type-id;
description
"Map the alarm type with this alarm type identifier.";
}
leaf alarm-type-qualifier-match {
type string;
description
"A W3C regular expression that is used when mapping an
alarm type and alarm-type-qualifier to X.733 parameters.";
}
uses x733-alarm-definition-parameters;
}
}
augment "/al:alarms/al:alarm-list/al:alarm" {
description
"Augment X.733 information to the alarm.";
uses x733-alarm-parameters;
}
augment "/al:alarms/al:shelved-alarms/al:shelved-alarm" {
description
"Augment X.733 information to the alarm.";
uses x733-alarm-parameters;
}
augment "/al:alarm-notification" {
description
"Augment X.733 information to the alarm notification.";
uses x733-alarm-parameters;
}
}
<CODE ENDS>
8. IANA Considerations
This document registers two URIs in the "IETF XML Registry"
[RFC3688]. Following the format in RFC 3688, the following
registrations have been made.
URI: urn:ietf:params:xml:ns:yang:ietf-alarms
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-alarms-x733
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
This document registers two YANG modules in the "YANG Module Names"
registry [RFC6020].
name: ietf-alarms
namespace: urn:ietf:params:xml:ns:yang:ietf-alarms
prefix: al
reference: RFC 8632
name: ietf-alarms-x733
namespace: urn:ietf:params:xml:ns:yang:ietf-alarms-x733
prefix: x733
reference: RFC 8632
9. Security Considerations
The YANG modules specified in this document define a schema for data
that is designed to be accessed via network management protocols such
as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
is the secure transport layer, and the mandatory-to-implement secure
transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
is HTTPS, and the mandatory-to-implement secure transport is TLS
[RFC8446].
The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. The list of alarms itself may be potentially sensitive from a security perspective, in that it potentially gives an attacker an authoritative picture of the (broken) state of the network. There are a number of data nodes defined in the YANG modules that are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes in the "ietf-alarms" module and their sensitivity/vulnerability: "/alarms/control/notify-status-changes": This leaf controls whether an alarm should notify based on various state changes. Unauthorized access to this leaf could have a negative impact on operational procedures relying on fine-grained alarm-state change reporting. "/alarms/control/alarm-shelving/shelf": This list controls the shelving (blocking) of alarms. Unauthorized access to this list could jeopardize the alarm-management procedures, since these alarms will not be notified or be part of the alarm list. "/alarms/control/alarm-profile/alarm-severity-assignment-profile": This list controls the severity levels of an alarm. Unauthorized access to this could, for example, downgrade the severity of an alarm and thereby have a negative impact on the alarm-monitoring process. Some of the RPC operations in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control access to these operations. These are the operations and their sensitivity/vulnerability: "/alarms/alarm-list/purge-alarms": This action deletes alarms from the alarm list. Unauthorized use of this action could jeopardize the alarm-management procedures since the deleted alarms may be vital for the alarm-management application. "/alarms/alarm-list/alarm/set-operator-state": This action can be used by the operator to indicate the level of human intervention on an alarm. Unauthorized use of this action could result in alarms being ignored by operators.
10. References
10.1. Normative References
[M.3100] International Telecommunication Union, "Generic network information model", ITU-T Recommendation M.3100, April 2005, <https://www.itu.int/rec/T-REC-M.3100-200504-I/en>. [M.3160] International Telecommunication Union, "Generic, protocol-neutral management information model", ITU-T Recommendation M.3100, November 2008, <https://www.itu.int/rec/T-REC-M.3160-200811-I>. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>. [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>. [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>. [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/rfc6991>. [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>. [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>. [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A YANG Data Model for Hardware Management", RFC 8348, DOI 10.17487/RFC8348, March 2018, <https://www.rfc-editor.org/info/rfc8348>. [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>. [X.721] International Telecommunication Union, "Information technology - Open Systems Interconnection - Structure of management information: Definition of management information", ITU-T Recommendation X.721, February 1992, <https://www.itu.int/rec/T-REC-X.721-199202-I/en>. [X.733] International Telecommunication Union, "Information technology - Open Systems Interconnection - Systems Management: Alarm reporting function", ITU-T Recommendation X.733, February 1992, <https://www.itu.int/rec/T-REC-X.733-199202-I/en>. [XSD-TYPES] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.10.2. Informative References
[ALARMIRP] 3GPP, "Telecommunication management; Fault Management; Part 2: Alarm Integration Reference Point (IRP): Information Service (IS)", 3GPP TS 32.111-2, March 2005, <http://www.3gpp.org/ftp/Specs/html-info/32111-2.htm>. [ALARMSEM] Wallin, S., Leijon, V., Nordlander, J., and N. Bystedt, "The semantics of alarm definitions: enabling systematic reasoning about alarms", International Journal of Network Management, Volume 22, Issue 3, May 2012, <http://dx.doi.org/10.1002/nem.800>.
[EEMUA] "Alarm systems: a guide to design, management and procurement", EEMUA Publication No. 191, Engineering Equipment and Materials Users Association, Second Edition, 2007. [G.7710] International Telecommunication Union, "SERIES G: TRANSMISSION SYSTEMS AND MEDIA, DIGITAL SYSTEMS AND NETWORKS - Data over Transport - Generic aspects - Transport network control aspects; Common equipment management function requirements", ITU-T Recommendation G.7710/Y.1701, Amendment 1, November 2012. [ISA182] International Society of Automation, "Management of Alarm Systems for the Process Industries", ANSI/ISA - 18.2-2016, March 2016. [RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877, September 2004, <https://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 Telecommunication Union, "Information technology - Open Systems Interconnection - Systems Management: Security alarm reporting function", ITU-T Recommendation X.736, January 1992, <https://www.itu.int/rec/T-REC-X.736-199201-I/en>. [YANG-INSTANCE] Lengyel, B. and B. Claise, "YANG Instance Data File Format", Work in Progress, draft-ietf-netmod-yang- instance-file-format-02, August 2019.
(next page on part 4)
