draft-ietf-ccamp-alarm-module-03.txt		draft-ietf-ccamp-alarm-module-04.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: March 24, 2019 Cisco		Expires: April 12, 2019 Cisco
	September 20, 2018		October 9, 2018
	YANG Alarm Module		YANG Alarm Module
	draft-ietf-ccamp-alarm-module-03		draft-ietf-ccamp-alarm-module-04
	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 March 24, 2019.		This Internet-Draft will expire on April 12, 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 48 ¶		skipping to change at page 2, line 48 ¶
	9. Security Considerations . . . . . . . . . . . . . . . . . . . 59		9. Security Considerations . . . . . . . . . . . . . . . . . . . 59
	10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 60		10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 60
	11. References . . . . . . . . . . . . . . . . . . . . . . . . . 60		11. References . . . . . . . . . . . . . . . . . . . . . . . . . 60
	11.1. Normative References . . . . . . . . . . . . . . . . . . 60		11.1. Normative References . . . . . . . . . . . . . . . . . . 60
	11.2. Informative References . . . . . . . . . . . . . . . . . 61		11.2. Informative References . . . . . . . . . . . . . . . . . 61
	Appendix A. Vendor-specific Alarm-Types Example . . . . . . . . 62		Appendix A. Vendor-specific Alarm-Types Example . . . . . . . . 62
	Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 63		Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 63
	Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 64		Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 64
	Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 65		Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 65
	Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 66		Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 66
	Appendix F. Background and Usability Requirements . . . . . . . 67		Appendix F. Relationships to other standards . . . . . . . . . . 67
	F.1. Alarm Concepts . . . . . . . . . . . . . . . . . . . . . 67		F.1. Relationship to RFC 8348 . . . . . . . . . . . . . . . . 67
	F.1.1. Alarm type . . . . . . . . . . . . . . . . . . . . . 67		F.2. Relationship to other alarm standards . . . . . . . . . . 67
	F.2. Relationships to other alarm standards . . . . . . . . . 68		F.2.1. Alarm definition . . . . . . . . . . . . . . . . . . 67
	F.2.1. Alarm definition . . . . . . . . . . . . . . . . . . 68		F.2.2. Data model . . . . . . . . . . . . . . . . . . . . . 69
	F.2.2. Data model . . . . . . . . . . . . . . . . . . . . . 70		Appendix G. Alarm Usability Requirements . . . . . . . . . . . . 71
	F.3. Usability Requirements . . . . . . . . . . . . . . . . . 72		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 74
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75
	1. Introduction		1. Introduction
	This document defines a YANG [RFC7950] module for alarm management.		This document defines a YANG [RFC7950] module for alarm management.
	The purpose is to define a standardized alarm interface for network		The purpose is to define a standardized alarm interface for network
	devices that can be easily integrated into management applications.		devices that can be easily integrated into management applications.
	The model is also applicable as a 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.
	skipping to change at page 5, line 10 ¶		skipping to change at page 5, line 10 ¶
	that should not be forwarded as alarm notifications.		that should not be forwarded as alarm notifications.
	o Clear and precise identification of alarm types and alarm		o Clear and precise identification of alarm types and alarm
	instances.		instances.
	o A management system should be able to pull all available alarm		o A management system should be able to pull all available alarm
	types from a system, i.e., read the alarm inventory from a system.		types from a system, i.e., read the alarm inventory from a system.
	This makes it possible to prepare alarm operators with		This makes it possible to prepare alarm operators with
	corresponding alarm instructions.		corresponding alarm instructions.
	o Address alarm usability requirements, see Appendix F. While IETF		o Address alarm usability requirements, see Appendix G. While IETF
	has not really addressed alarm management, telecom standards has		has not really addressed alarm management, telecom standards has
	addressed it purely from a protocol perspective. The process		addressed it purely from a protocol perspective. The process
	industry has published several relevant standards addressing		industry has published several relevant standards addressing
	requirements for a useful alarm interface; [EEMUA], [ISA182].		requirements for a useful alarm interface; [EEMUA], [ISA182].
	This alarm module defines usability requirements as well as a YANG		This alarm module defines usability requirements as well as a YANG
	data model.		data model.
	o Mapping to X.733, which is a requirement for some alarm systems.		o Mapping to X.733, which is a requirement for some alarm systems.
	Still, keep some of the X.733 concepts out of the core model in		Still, keep some of the X.733 concepts out of the core model in
	order to make the model small and easy to understand.		order to make the model small and easy to understand.
	skipping to change at page 5, line 41 ¶		skipping to change at page 5, line 41 ¶
	There are two main things to remember from this definition:		There are two main things to remember from this definition:
	1. the definition focuses on leaving out events and logging		1. the definition focuses on leaving out events and logging
	information in general. Alarms should only be used for undesired		information in general. Alarms should only be used for undesired
	states that require action.		states that require action.
	2. the definition also focus on alarms as a state on a resource, not		2. the definition also focus on alarms as a state on a resource, not
	the notifications that report the state changes.		the notifications that report the state changes.
	See Appendix F for more motivation and consequences around this		See Appendix F for information how this definition relates to other
	definition as well as how it relates to other alarm standards.		alarm standards.
	3.2. Alarm Type		3.2. Alarm Type
	This document defines an alarm type with an alarm type id and an		This document defines an alarm type with an alarm type id and an
	alarm type qualifier.		alarm type qualifier.
	The alarm type id is modeled as a YANG identity. With YANG		The alarm type id is modeled as a YANG identity. With YANG
	identities, new alarm types can be defined in a distributed fashion.		identities, new alarm types can be defined in a distributed fashion.
	YANG identities are hierarchical, which means that an hierarchy of		YANG identities are hierarchical, which means that an hierarchy of
	alarm types can be defined.		alarm types can be defined.
	skipping to change at page 9, line 32 ¶		skipping to change at page 9, line 32 ¶
	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-with-clear		+--ro perceived-severity severity-with-clear
	+--ro alarm-text alarm-text		+--ro alarm-text alarm-text
	For every status change from the resource perspective a row is added		For every status change from the resource perspective a row is added
	to the "status-change" list. The last status values are also		to the "status-change" list. The last status values are also
	represented as 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 boolean		severity does not include "cleared", alarm clearance is a boolean
	flag.		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 writable-operator-state		+---w state writable-operator-state
	+---w text? string		+---w text? string
	The operator state for an alarm can be: "none", "ack", "shelved", and		The operator state for an alarm can be: "none", "ack", "shelved", and
	"closed". Alarm deletion (using the 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 purged.		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
	skipping to change at page 18, line 16 ¶		skipping to change at page 18, line 16 ¶
	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-09-20.yang"		<CODE BEGINS> file "ietf-alarms@2018-10-09.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.";
	}		}
	skipping to change at page 20, line 43 ¶		skipping to change at page 20, line 43 ¶
	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-09-20 {		revision 2018-10-09 {
	description		description
	"Initial revision.";		"Initial revision.";
	reference "RFC XXXX: YANG Alarm Module";		reference "RFC XXXX: YANG Alarm Module";
	}		}
	/*		/*
	* Features		* Features
	*/		*/
	feature operator-actions {		feature operator-actions {
	skipping to change at page 26, line 19 ¶		skipping to change at page 26, line 19 ¶
	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
	taken yet, or failed";		taken yet, or failed";
	}		}
	enum closed {		enum closed {
	value 3;		value 3;
	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
	skipping to change at page 48, line 12 ¶		skipping to change at page 48, line 12 ¶
	mapping provided by the system is in conflict with other management		mapping provided by the system is in conflict with other management
	systems or not considered correct.		systems or not considered correct.
	Note that the IETF Alarm Module term 'resource' is synonymous to the		Note that the IETF Alarm Module term 'resource' is synonymous to the
	ITU term 'managed object'.		ITU term 'managed object'.
	7. The X.733 Mapping Module		7. The X.733 Mapping Module
	This YANG module references [X.733] and [X.736].		This YANG module references [X.733] and [X.736].
	<CODE BEGINS> file "ietf-alarms-x733@2018-09-20.yang"		<CODE BEGINS> file "ietf-alarms-x733@2018-10-09.yang"
	module ietf-alarms-x733 {		module ietf-alarms-x733 {
	yang-version 1.1;		yang-version 1.1;
	namespace "urn:ietf:params:xml:ns:yang:ietf-alarms-x733";		namespace "urn:ietf:params:xml:ns:yang:ietf-alarms-x733";
	prefix x733;		prefix x733;
	import ietf-alarms {		import ietf-alarms {
	prefix al;		prefix al;
	}		}
	import ietf-yang-types {		import ietf-yang-types {
	prefix yang;		prefix yang;
	skipping to change at page 49, line 19 ¶		skipping to change at page 49, line 19 ¶
	The module uses an integer and a corresponding string for		The module uses an integer and a corresponding string for
	probable cause instead of a globally defined enumeration, in		probable cause instead of a globally defined enumeration, in
	order to be able to manage conflicting enumeration definitions.		order to be able to manage conflicting enumeration definitions.
	A single globally defined enumeration is challenging to		A single globally defined enumeration is challenging to
	maintain.";		maintain.";
	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 2018-09-20 {		revision 2018-10-09 {
	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 {
	skipping to change at page 59, line 11 ¶		skipping to change at page 59, line 11 ¶
	}		}
	<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
	requested to be made.		requested to be made.
	URI: urn:ietf:params:xml:ns:yang:ietf-alarms		URI: urn:ietf:params:xml:ns:yang:ietf-alarms
	Registrant Contact: The IESG.		Registrant Contact: The IESG.
	XML: N/A, the requested URI is an XML namespace.		XML: N/A, the requested URI is an XML namespace.
	This document registers a YANG module in the YANG Module Names		This document registers a YANG module in the YANG Module Names
	registry [RFC6020].		registry [RFC6020].
	name: ietf-alarms		name: ietf-alarms
	namespace: urn:ietf:params:xml:ns:yang:ietf-alarms		namespace: urn:ietf:params:xml:ns:yang:ietf-alarms
	prefix: al		prefix: al
	reference: RFC XXXX		reference: RFC XXXX
	9. Security Considerations		9. Security Considerations
	The YANG module specified in this document defines a schema for data		The YANG module specified in this document defines a schema for data
	that is designed to be accessed via network management protocols such		that is designed to be accessed via network management protocols such
	as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer		as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
	is the secure transport layer, and the mandatory-to-implement secure		is the secure transport layer, and the mandatory-to-implement secure
	transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer		transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
	is HTTPS, and the mandatory-to-implement secure transport is TLS		is HTTPS, and the mandatory-to-implement secure transport is TLS
	[RFC5246].		[RFC5246].
	skipping to change at page 60, line 37 ¶		skipping to change at page 60, line 37 ¶
	document.		document.
	11. References		11. References
	11.1. Normative References		11.1. Normative References
	[M.3100] International Telecommunications Union, "Generic Network		[M.3100] International Telecommunications Union, "Generic Network
	Information Model", ITU-T Recommendation M.3100, 2005.		Information Model", ITU-T Recommendation M.3100, 2005.
	[M.3160] International Telecommunications Union, "Generic,		[M.3160] International Telecommunications Union, "Generic,
	protocol-neutral management information model", ITU-T		protocol-neutral management information model",
	Recommendation M.3100, 2008.		ITU-T Recommendation M.3100, 2008.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/		Requirement Levels", BCP 14, RFC 2119,
	RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
	<http://www.rfc-editor.org/info/rfc2119>.		editor.org/info/rfc2119>.
	[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,		[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
	DOI 10.17487/RFC3688, January 2004,		DOI 10.17487/RFC3688, January 2004, <https://www.rfc-
	<http://www.rfc-editor.org/info/rfc3688>.		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, DOI 10.17487/		(TLS) Protocol Version 1.2", RFC 5246,
	RFC5246, August 2008, <https://www.rfc-editor.org/info/		DOI 10.17487/RFC5246, August 2008, <https://www.rfc-
	rfc5246>.		editor.org/info/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,		DOI 10.17487/RFC6020, October 2010, <https://www.rfc-
	<http://www.rfc-editor.org/info/rfc6020>.		editor.org/info/rfc6020>.
	[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,		[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
	and A. Bierman, Ed., "Network Configuration Protocol		and A. Bierman, Ed., "Network Configuration Protocol
	(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,		(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
	<http://www.rfc-editor.org/info/rfc6241>.		<https://www.rfc-editor.org/info/rfc6241>.
	[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure		[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
	Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,		Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
	<https://www.rfc-editor.org/info/rfc6242>.		<https://www.rfc-editor.org/info/rfc6242>.
	[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC		[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
	6991, DOI 10.17487/RFC6991, July 2013,		Protocol (NETCONF) Access Control Model", RFC 6536,
	<http://www.rfc-editor.org/info/rfc6991>.		DOI 10.17487/RFC6536, March 2012, <https://www.rfc-
			editor.org/info/rfc6536>.
			[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",		[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
	RFC 7950, DOI 10.17487/RFC7950, August 2016,		RFC 7950, DOI 10.17487/RFC7950, August 2016,
	<http://www.rfc-editor.org/info/rfc7950>.		<https://www.rfc-editor.org/info/rfc7950>.
	[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF		[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
	Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,		Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
	<http://www.rfc-editor.org/info/rfc8040>.		<https://www.rfc-editor.org/info/rfc8040>.
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/rfc8174>.		May 2017, <https://www.rfc-editor.org/info/rfc8174>.
	[X.733] International Telecommunications Union, "Information		[X.733] International Telecommunications Union, "Information
	Technology - Open Systems Interconnection - Systems		Technology - Open Systems Interconnection - Systems
	Management: Alarm Reporting Function", ITU-T		Management: Alarm Reporting Function",
	Recommendation X.733, 1992.		ITU-T Recommendation X.733, 1992.
	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 62, line 28 ¶		skipping to change at page 62, line 28 ¶
	SYSTEMS AND NETWORKS Data over Transport - Generic aspects		SYSTEMS AND NETWORKS Data over Transport - Generic aspects
	- Transport network control aspects. Common equipment		- Transport network control aspects. Common equipment
	management function requirements", 2012.		management function requirements", 2012.
	[ISA182] International Society of Automation,ISA, "ANSI/ISA-		[ISA182] International Society of Automation,ISA, "ANSI/ISA-
	18.2-2009 Management of Alarm Systems for the Process		18.2-2009 Management of Alarm Systems for the Process
	Industries", 2009.		Industries", 2009.
	[RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management		[RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management
	Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877,		Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877,
	September 2004, <http://www.rfc-editor.org/info/rfc3877>.		September 2004, <https://www.rfc-editor.org/info/rfc3877>.
			[RFC4268] Chisholm, S. and D. Perkins, "Entity State MIB", RFC 4268,
			DOI 10.17487/RFC4268, November 2005, <https://www.rfc-
			editor.org/info/rfc4268>.
	[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",		[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
	BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,		BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
	<https://www.rfc-editor.org/info/rfc8340>.		<https://www.rfc-editor.org/info/rfc8340>.
			[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>.
	[X.736] International Telecommunications Union, "Information		[X.736] International Telecommunications Union, "Information
	Technology - Open Systems Interconnection - Systems		Technology - Open Systems Interconnection - Systems
	Management: Security alarm reporting function", ITU-T		Management: Security alarm reporting function",
	Recommendation X.736, 1992.		ITU-T Recommendation X.736, 1992.
	Appendix A. Vendor-specific Alarm-Types Example		Appendix A. Vendor-specific Alarm-Types Example
	This example shows how to define alarm-types in a vendor-specific		This example shows how to define alarm-types in a vendor-specific
	module. In this case the vendor "xyz" has chosen to define top level		module. In this case the vendor "xyz" has chosen to define top level
	identities according to X.733 event types.		identities according to X.733 event types.
	module example-xyz-alarms {		module example-xyz-alarms {
	namespace "urn:example:xyz-alarms";		namespace "urn:example:xyz-alarms";
	prefix xyz-al;		prefix xyz-al;
	skipping to change at page 67, line 5 ¶		skipping to change at page 67, line 5 ¶
	<alarm-type-id>xyz-al:environmental-alarm</alarm-type-id>		<alarm-type-id>xyz-al:environmental-alarm</alarm-type-id>
	<alarm-type-qualifier-match>		<alarm-type-qualifier-match>
	smoke-alarm		smoke-alarm
	</alarm-type-qualifier-match>		</alarm-type-qualifier-match>
	<event-type>quality-of-service-alarm</event-type>		<event-type>quality-of-service-alarm</event-type>
	<probable-cause>777</probable-cause>		<probable-cause>777</probable-cause>
	</x733-mapping>		</x733-mapping>
	</control>		</control>
	</alarms>		</alarms>
	Appendix F. Background and Usability Requirements		Appendix F. Relationships to other standards
	This section gives background information regarding design choices in
	the alarm module. It also defines usability requirements for alarms.
	Alarm usability is important for an alarm interface. A data-model
	will help in defining the format but if the actual alarms are of low
	value we have not gained the goal of alarm management.
	The telecommunication domain has standardized an alarm interface in
	ITU-T X.733 [X.733]. This continued in mobile networks within the
	3GPP organization [ALARMIRP]. Although SNMP is the dominant
	mechanism for monitoring devices, IETF did not early on standardize
	an alarm MIB. Instead, management systems interpreted the enterprise
	specific traps per MIB and device to build an alarm list. When
	finally The Alarm MIB [RFC3877] was published, it had to address the
	existence of enterprise traps and map these into alarms. This
	requirement led to a MIB that is not always easy to use.
	F.1. Alarm Concepts
	There are two misconceptions regarding alarms and alarm interfaces
	that are important to sort out. The first problem is that alarms are
	mixed with events in general. Alarms MUST correspond to an
	undesirable state that needs corrective action. Many implementations
	of alarm interfaces do not adhere to this principle and just send
	events in general. In order to qualify as an alarm, there must exist
	a corrective action. If that is not true, it is an event that can go
	into logs.
	"One of the most important principles of alarm management is that an		This section briefly describes how this alarm module relates to other
	alarm requires an action. This means that if the operator does not		relevant standards.
	need to respond to an alarm (because unacceptable consequences do not
	occur), then it is not an alarm. Following this cardinal rule will
	help eliminate many potential alarm management issues." [ISA182]
	The other misconception is that the term "alarm" refers to the		F.1. Relationship to RFC 8348
	notification itself. Rather, an alarm is a state of a resource in
	the system. The alarm notifications report state changes of the
	alarm, such as alarm raise and alarm clear.
	F.1.1. Alarm type		RFC 8348 [RFC8348] defines a YANG data model for the management of
			hardware. The "alarm-state" in RFC 8348 (and EntityAlarmStatus in
			RFC 4268 [RFC4268]) is a summary of the alarm severity levels that
			may be active on the specific hardware component. It does not say
			anything about how alarms are reported, and it doesn't provide any
			details of the alarms.
	Since every alarm has a corresponding corrective action, a vendor can		The mapping between the alarm YANG data-model and the alarm-state in
	to prepare a list of available alarms and their corrective actions.		RFC 8348 are outlined below
	We use the term "alarm type" to refer to every possible alarm that
	could be active in the system.
	Alarm types are also fundamental in order to provide a state-based		resource: corresponds to /hardware/component/
	alarm list. The alarm list correlates alarm state changes for the
	same alarm type and the same resource into one alarm.
	Different alarm interfaces use different mechanisms to define alarm		is-cleared: no bit set in /hardware/component/state/alarm-state
	types, ranging from simple error numbers to more advanced mechanisms
	like the X.733 triplet of event type, probable cause and specific
	problem.
	A common misunderstanding is that individual alarm notifications are		perceived-severity: corresponding bit set in
	alarm types. This is not correct; e.g., "link-up" and "link-down"		/hardware/component/state/alarm-state
	are two notifications reporting different states for the same alarm
	type, "link-alarm".
	F.2. Relationships to other alarm standards		operator-state-change/state: if the alarm is acknowledged by the
			operator it may correspond to under-repair
	This section briefly describes how this alarm module relates to other		F.2. Relationship to other alarm standards
	relevant alarm standards. It covers the definition of the concept of
	an alarm and the data models of the referenced alarm standards.
	F.2.1. Alarm definition		F.2.1. Alarm definition
	The table below summarizes relevant definitions of the term "alarm".		The table below summarizes relevant definitions of the term "alarm"
			in other alarm standards.
	+------------+---------------------------+--------------------------+		+------------+---------------------------+--------------------------+
	| Standard | Definition | Comment |		| Standard | Definition | Comment |
	+------------+---------------------------+--------------------------+		+------------+---------------------------+--------------------------+
	| X.733 | error: A deviation of a | The X.733 alarm |		| X.733 | error: A deviation of a | The X.733 alarm |
	| [X.733] | system from normal | definition is focused on |		| [X.733] | system from normal | definition is focused on |
	| | operation. fault: The | the notification as such |		| | operation. fault: The | the notification as such |
	| | physical or algorithmic | and not the state. It |		| | physical or algorithmic | and not the state. It |
	| | cause of a malfunction. | also uses the basic |		| | cause of a malfunction. | also uses the basic |
	| | Faults manifest | criteria of deviation |		| | Faults manifest | criteria of deviation |
	skipping to change at page 71, line 5 ¶		skipping to change at page 70, line 12 ¶
	identify alarm types. This alarm module uses a hierarchical YANG		identify alarm types. This alarm module uses a hierarchical YANG
	identity, alarm-type. This enables delegation of alarm types		identity, alarm-type. This enables delegation of alarm types
	within organizations. It also lets management reason about		within organizations. It also lets management reason about
	"abstract" alarm-types corresponding to base identities, see		"abstract" alarm-types corresponding to base identities, see
	Section 3.2.		Section 3.2.
	The YANG alarm module has not included the majority of the X.733		The YANG alarm module has not included the majority of the X.733
	alarm attributes. Rather these are defined in an augmenting		alarm attributes. Rather these are defined in an augmenting
	module if "strict" X.733 compliance is needed.		module if "strict" X.733 compliance is needed.
	F.2.2.2. RFC3877, the Alarm MIB		F.2.2.2. RFC 3877, the Alarm MIB
	The MIB in RFC3877 takes a different approach, rather than defining a		The MIB in RFC 3877 takes a different approach, rather than defining
	concrete data-model for alarms, it defines a model to map existing		a concrete data model for alarms, it defines a model to map existing
	SNMP managed-objects and notifications into alarm states and alarm		SNMP managed objects and notifications into alarm states and alarm
	notifications. This was necessary since MIBs where already defined		notifications. This was necessary since MIBs were already defined
	with both managed objects and notifications indicating alarms, for		with both managed objects and notifications indicating alarms, for
	example linkUp and linkDown notifications in combination with		example linkUp and linkDown notifications in combination with
	ifAdminState and ifOperState. So RFC3877 can not really be compared		ifAdminState and ifOperState. So RFC 3877 can not really be compared
	to the alarm YANG module in that sense.		to the alarm YANG module in that sense.
	The Alarm MIB maps existing MIB definitions into alarms,		The Alarm MIB maps existing MIB definitions into alarms,
	alarmModelTable. The upside of that is that a SNMP Manager can at		alarmModelTable. The upside of that is that a SNMP Manager can at
	runtime read the possible alarm types. This corresponds to the		runtime read the possible alarm types. This corresponds to the
	alarmInventory in the alarm YANG module.		alarmInventory in the alarm YANG module.
	F.2.2.3. 3GPP Alarm IRP		F.2.2.3. 3GPP Alarm IRP
	The 3GPP Alarm IRP is an evolution of X.733. Main differences		The 3GPP Alarm IRP is an evolution of X.733. Main differences
	skipping to change at page 72, line 12 ¶		skipping to change at page 71, line 22 ¶
	The requirements in G.7710 corresponds to features in the alarm YANG		The requirements in G.7710 corresponds to features in the alarm YANG
	module in the following way:		module in the following way:
	Alarm Severity Assignment Profile (ASAP): the alarm profile		Alarm Severity Assignment Profile (ASAP): the alarm profile
	"/alarms/alarm-profile/".		"/alarms/alarm-profile/".
	Alarm Reporting Control (ARC): alarm shelving "/alarms/control/		Alarm Reporting Control (ARC): alarm shelving "/alarms/control/
	alarm-shelving/" and the ability to control alarm notifications		alarm-shelving/" and the ability to control alarm notifications
	"/alarms/control/notify-status-changes".		"/alarms/control/notify-status-changes".
	F.3. Usability Requirements		Appendix G. Alarm Usability Requirements
			This section defines usability requirements for alarms. Alarm
			usability is important for an alarm interface. A data-model will
			help in defining the format but if the actual alarms are of low value
			we have not gained the goal of alarm management.
	Common alarm problems and the cause of the problems are summarized in		Common alarm problems and the cause of the problems are summarized in
	Table 2. This summary is adopted to networking based on the ISA		Table 2. This summary is adopted to networking based on the ISA
	[ISA182] and EEMUA [EEMUA] standards.		[ISA182] and EEMUA [EEMUA] standards.
	+------------------+--------------------------------+---------------+		+------------------+--------------------------------+---------------+
	| Problem | Cause | How this |		| Problem | Cause | How this |
	| | | module |		| | | module |
	| | | address the |		| | | address the |
	| | | cause |		| | | cause |
End of changes. 45 change blocks.
	136 lines changed or deleted		117 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/