idnits 2.17.1 draft-vallin-netmod-alarm-module-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 565 has weird spacing: '...everity sev...' == Line 569 has weird spacing: '...everity sev...' == Line 587 has weird spacing: '...r-state ope...' == Line 593 has weird spacing: '...o state ope...' == Line 605 has weird spacing: '...perator str...' == (12 more instances...) -- The document date (October 5, 2016) is 2759 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Vallin 3 Internet-Draft Stefan Vallin AB 4 Intended status: Standards Track M. Bjorklund 5 Expires: April 8, 2017 Cisco 6 October 5, 2016 8 YANG Alarm Module 9 draft-vallin-netmod-alarm-module-00 11 Abstract 13 This document defines a YANG module for alarm management. It 14 includes functions for alarm list management, alarm shelving and 15 notifications to inform management systems. There are also RPCs to 16 manage the operator state of an alarm and administrative alarm 17 procedures. The module carefully maps to relevant alarm standards. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 8, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 3 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4. Background and Usability Requirements . . . . . . . . . . . . 5 58 5. Alarm Concepts . . . . . . . . . . . . . . . . . . . . . . . 8 59 5.1. What is an Alarm? . . . . . . . . . . . . . . . . . . . . 9 60 5.2. What is an Alarm Type? . . . . . . . . . . . . . . . . . 9 61 5.3. How are Resources Identified? . . . . . . . . . . . . . . 12 62 5.4. How are Alarm Instances Identified? . . . . . . . . . . . 12 63 5.5. What is the Life-Cycle of an Alarm? . . . . . . . . . . . 13 64 5.5.1. Resource Alarm Life-Cycle . . . . . . . . . . . . . . 13 65 5.5.2. Operator Alarm Life-cycle . . . . . . . . . . . . . . 14 66 5.5.3. Administrative Alarm Life-Cycle . . . . . . . . . . . 15 67 5.6. Alarm Shelving . . . . . . . . . . . . . . . . . . . . . 15 68 6. Alarm Data Model . . . . . . . . . . . . . . . . . . . . . . 15 69 6.1. Alarm Control . . . . . . . . . . . . . . . . . . . . . . 18 70 6.1.1. Alarm Shelving . . . . . . . . . . . . . . . . . . . 18 71 6.2. Alarm Inventory . . . . . . . . . . . . . . . . . . . . . 18 72 6.3. Alarm Summary . . . . . . . . . . . . . . . . . . . . . . 19 73 6.4. The Alarm List . . . . . . . . . . . . . . . . . . . . . 19 74 6.5. The Shelved Alarms List . . . . . . . . . . . . . . . . . 21 75 6.6. RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . 21 76 6.7. Notifications . . . . . . . . . . . . . . . . . . . . . . 21 77 7. Alarm YANG Module . . . . . . . . . . . . . . . . . . . . . . 21 78 8. X.733 Alarm Mapping Data Model . . . . . . . . . . . . . . . 45 79 9. X.733 Alarm Mapping YANG Module . . . . . . . . . . . . . . . 45 80 10. Security Considerations . . . . . . . . . . . . . . . . . . . 52 81 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 52 82 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 83 12.1. Normative References . . . . . . . . . . . . . . . . . . 52 84 12.2. Informative References . . . . . . . . . . . . . . . . . 52 85 Appendix A. Enterprise-specific Alarm-Types Example . . . . . . 53 86 Appendix B. Alarm Inventory Example . . . . . . . . . . . . . . 54 87 Appendix C. Alarm List Example . . . . . . . . . . . . . . . . . 55 88 Appendix D. Alarm Shelving Example . . . . . . . . . . . . . . . 56 89 Appendix E. X.733 Mapping Example . . . . . . . . . . . . . . . 57 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 92 1. Requirements notation 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 96 document are to be interpreted as described in [RFC2119]. 98 2. Introduction 100 This document defines a YANG [RFC7950] module for alarm management. 101 The purpose is to define a standardised alarm interface for network 102 devices that can be easily integrated into management applications. 103 The model is also applicable as a northbound alarm interface in the 104 management applications. 106 Alarm monitoring is a fundamental part of monitoring the network. 107 Raw alarms from devices do not always tell the status of the network 108 services or necessarily point to the root cause. However, being able 109 to feed alarms to the network management system in a standardised 110 format is a starting point for performing higher level network 111 assurance tasks. 113 The telecommunication domain has standardised an alarm interface in 114 ITU-T X.733 [X.733]. This continued in mobile networks within the 115 3GPP organisation [ALARMIRP]. Although SNMP is the dominant 116 mechanism for monitoring devices, IETF did not early on standardise 117 an alarm MIB. Instead, management systems interpreted the enterprise 118 specific traps per MIB and device to build an alarm list. When 119 finally The Alarm MIB [RFC3877] was published, it had to address the 120 existence of enterprise traps and map these into alarms. This 121 requirement led to a MIB that is not easy to use. 123 This document defines a standardised YANG module for alarm 124 management. The design of the module is based on experience from 125 using and implementing the above mentioned alarm standards. 127 2.1. Terminology 129 The following terms are defined in [RFC7950]: 131 o action 133 o client 135 o data tree 137 o RPC 139 o server 140 The following terms are used within this document: 142 o Alarm (the general concept): An alarm signifies an undesirable 143 state in a resource that requires corrective action. 145 o Alarm Instance: The alarm state for a specific resource and alarm 146 type. For example (GigabitEthernet0/15, link-alarm). An entry in 147 the alarm list. 149 o Alarm Inventory: A list of all possible alarm types on a system. 151 o Alarm Shelving: Blocking alarms according to specific criteria. 153 o Alarm Type: An alarm type identifies a possible unique alarm state 154 for a resource. Alarm types are names to identify the state like 155 'link-alarm', 'jitter-violation', 'high-disk-utilization'. 157 o Management System: The alarm management application that consumes 158 the alarms, i.e., acts as a client. 160 o Resource: A fine-grained identification of the alarming resource, 161 for example: an interface, a process. 163 o System: The system that implements this YANG alarm module, i.e., 164 acts as a server. This corresponds to a network device or a 165 management application that provides a north-bound alarm 166 interface. 168 3. Objectives 170 The objectives for the design of the Alarm Module are: 172 o Simple to use. If a system supports this module, it shall be 173 straight-forward to integrate this into a YANG based alarm 174 manager. 176 o View alarms as states on resources and not as discrete 177 notifications. 179 o Clear definition of "alarm" in order to exclude general events 180 that should not be forwarded as alarm notifications. 182 o Clear and precise identification of alarm types and alarm 183 instances. 185 o A management system should be able to pull all available alarm 186 types from a system, i.e., read the alarm inventory from a system. 188 This makes it possible to prepare alarm operators with 189 corresponding alarm instructions. 191 o Address alarm usability requirements. While IETF has not really 192 addressed alarm management, telecom standards has addressed it 193 purely from a protocol perspective. The process industry has 194 published several relevant standards addressing requirements for a 195 useful alarm interface; [EEMUA], [ISA182]. This alarm module 196 defines usability requirements as well as a YANG data model. 198 o Mapping to X.733, which is a requirement for many alarm systems. 199 Still, keep some of the X.733 concepts out of the core model in 200 order to make the model small and easy to understand. 202 4. Background and Usability Requirements 204 Common alarm problems and the cause of the problems are summarised in 205 Table 1. This summary is adopted to networking based on the ISA 206 [ISA182] and EEMUA [EEMUA] standards. 208 +------------------+--------------------------------+---------------+ 209 | Problem | Cause | How this | 210 | | | module | 211 | | | address the | 212 | | | cause | 213 +------------------+--------------------------------+---------------+ 214 | Alarms are | "Nuisance" alarms (chattering | Strict | 215 | generated but | alarms and fleeting alarms), | definition of | 216 | they are ignored | faulty hardware, redundant | alarms | 217 | by the operator. | alarms, cascading alarms, | requiring | 218 | | incorrect alarm settings, | corrective | 219 | | alarms have not been | response. | 220 | | rationalised, the alarms | Alarm | 221 | | represent log information | requirements | 222 | | rather than true alarms. | in Table 2. | 223 | | | | 224 | When alarms | Insufficient alarm response | The alarm | 225 | occur, operators | procedures and not well | inventory | 226 | do not know how | defined alarm types. | lists all | 227 | to respond. | | alarm types | 228 | | | and | 229 | | | corrective | 230 | | | actions. | 231 | | | Alarm | 232 | | | requirements | 233 | | | in Table 2. | 234 | | | | 235 | The alarm | Nuisance alarms, stale alarms, | The alarm | 236 | display is full | alarms from equipment not in | definition | 237 | of alarms, even | service. | and alarm | 238 | when there is | | shelving. | 239 | nothing wrong. | | | 240 | | | | 241 | During a | Incorrect prioritization of | State-based | 242 | failure, | alarms. Not using advanced | alarm model, | 243 | operators are | alarm techniques (e.g. state- | alarm rate | 244 | flooded with so | based alarming). | requirements | 245 | many alarms that | | in Table 3 | 246 | they do not know | | and Table 4 | 247 | which ones are | | | 248 | the most | | | 249 | important. | | | 250 +------------------+--------------------------------+---------------+ 252 Table 1: Alarm Problems and Causes 254 Based upon the above problems EEMUA gives the following definition of 255 a good alarm: 257 +----------------+--------------------------------------------------+ 258 | Characteristic | Explanation | 259 +----------------+--------------------------------------------------+ 260 | Relevant | Not spurious or of low operational value. | 261 | | | 262 | Unique | Not duplicating another alarm. | 263 | | | 264 | Timely | Not long before any response is needed or too | 265 | | late to do anything. | 266 | | | 267 | Prioritised | Indicating the importance that the operator | 268 | | deals with the problem. | 269 | | | 270 | Understandable | Having a message which is clear and easy to | 271 | | understand. | 272 | | | 273 | Diagnostic | Identifying the problem that has occurred. | 274 | | | 275 | Advisory | Indicative of the action to be taken. | 276 | | | 277 | Focusing | Drawing attention to the most important issues. | 278 +----------------+--------------------------------------------------+ 280 Table 2: Definition of a Good Alarm 282 Vendors SHOULD rationalise all alarms according to above. Another 283 crucial requirement is acceptable alarm rates. Vendors SHOULD make 284 sure that they do not exceed the recommendations from EEMUA below: 286 +-----------------------------------+-------------------------------+ 287 | Long Term Alarm Rate in Steady | Acceptability | 288 | Operation | | 289 +-----------------------------------+-------------------------------+ 290 | More than one per minute | Very likely to be | 291 | | unacceptable. | 292 | | | 293 | One per 2 minutes | Likely to be over-demanding. | 294 | | | 295 | One per 5 minutes | Manageable. | 296 | | | 297 | Less than one per 10 minutes | Very likely to be acceptable. | 298 +-----------------------------------+-------------------------------+ 300 Table 3: Acceptable Alarm Rates, Steady State 302 +----------------------------+--------------------------------------+ 303 | Number of alarms displayed | Acceptability | 304 | in 10 minutes following a | | 305 | major network problem | | 306 +----------------------------+--------------------------------------+ 307 | More than 100 | Definitely excessive and very likely | 308 | | to lead to the operator to abandon | 309 | | the use of the alarm system. | 310 | | | 311 | 20-100 | Hard to cope with. | 312 | | | 313 | Under 10 | Should be manageable - but may be | 314 | | difficult if several of the alarms | 315 | | require a complex operator response. | 316 +----------------------------+--------------------------------------+ 318 Table 4: Acceptable Alarm Rates, Burst 320 The numbers in Table 3 and Table 4 are the sum of all alarms for a 321 network being managed from one alarm console. So every individual 322 system or NMS contributes to these numbers. 324 Vendors SHOULD make sure that the following rules are used in 325 designing the alarm interface: 327 1. Rationalize the alarms in the system to ensure that every alarm 328 is necessary, has a purpose, and follows the cardinal rule - that 329 it requires an operator response. Adheres to the rules of 330 Table 2 332 2. Audit the quality of the alarms. Talk with the operators about 333 how well the alarm information support them. Do they know what 334 to do in the event of an alarm? Are they able to quickly 335 diagnose the problem and determine the corrective action? Does 336 the alarm text adhere to the requirements in Table 2? 338 3. Analyze and benchmark the performance of the system and compare 339 it to the recommended metrics in Table 3 and Table 4. Start by 340 identifying nuisance alarms, standing alarms at normal state and 341 startup. 343 5. Alarm Concepts 345 This section defines the fundamental concepts behind the data model. 346 This section is rooted in the works of Vallin et. al [ALARMSEM]. 348 5.1. What is an Alarm? 350 There are two misconceptions regarding alarms and alarm interfaces 351 that are important to sort out. The first problem is that alarms are 352 mixed with events in general. Alarms MUST correspond to an 353 undesirable state that needs corrective action. Many implementations 354 of alarm interfaces do not adhere to this principle and just send 355 events in general. In order to qualify as an alarm, there must exist 356 a corrective action. If that is not true, it is an event that can go 357 into logs. 359 The other misconception is that the term alarm refers to the 360 notification itself. Rather, an alarm is a state of a resource in 361 the system. The alarm notifications report state changes of the 362 alarm, such as alarm raise and alarm clear. 364 Based upon the above, we will use the following alarm definition: 366 An alarm signifies an undesirable state in a resource that 367 requires corrective action. 369 "One of the most important principles of alarm management is that an 370 alarm requires an action. This means that if the operator does not 371 need to respond to an alarm (because unacceptable consequences do not 372 occur), then it is not an alarm. Following this cardinal rule will 373 help eliminate many potential alarm management issues." [ISA182] 375 5.2. What is an Alarm Type? 377 One of the fundamental requirements stated in the previous section is 378 that every alarm must have a corresponding corrective action. This 379 means that every vendor should be able to prepare a list of available 380 alarms and their corrective actions. We use the term 'alarm type' to 381 refer to every possible alarm that could be active in the system. 383 Alarm types are also fundamental in order to provide a state-based 384 alarm list. The alarm list correlates alarm state changes for the 385 same alarm type and the same resource into one alarm. 387 Different alarm interfaces use different mechanisms to define alarm 388 types, ranging from simple error numbers to more advanced mechanisms 389 like the X.733 triplet of event type, probable cause and specific 390 problem. 392 This document defines an alarm type with an alarm type id and an 393 alarm type qualifier. 395 The alarm type id is modeled as a YANG identity. With YANG 396 identities, new alarm types can be defined in a distributed fashion. 397 YANG identities are hierarchical, which means that an hierarchy of 398 alarm types can be defined. 400 The primary goal for the alarm module has been to provide a simple 401 but extensible mechanism. YANG identities is a good mechanism for 402 enumerated values that are easy to extend. 404 This means that every possible alarm type that can appear in a system 405 exists as a well defined hierarchical identity along with a 406 description. Tools can provide a list of possible alarms by parsing 407 the YANG identities rather than reading user guides. 409 Standards and vendors should define their own alarm type identities 410 based on this definition. 412 The use of YANG identities means that all possible alarms are 413 identified at design time. This explicit declaration of alarm types 414 makes it easier to allow for alarm qualification reviews and 415 preparation of alarm actions and documentation. 417 There are occasions where the alarm types are not known at design 418 time. For example, a system with digital inputs that allows users to 419 connects detectors (e.g., smoke detector) to the inputs. In this 420 case it is a configuration action that says that certain connectors 421 are fire alarms for example. The drawback of this is that there is a 422 big risk that alarm operators will receive alarm types as a surprise, 423 they do not know how to resolve the problem since a defined alarm 424 procedure does not necessarily exist. 426 In order to allow for dynamic addition of alarm types the alarm 427 module also allows for further qualification of the identity based 428 alarm type using a string. 430 A common misunderstanding is that individual alarm notifications are 431 alarm types. This is not correct; e.g., "link-up" and "link-down" 432 are two notifications reporting different states for the same alarm 433 type, "link-alarm". 435 A vendor or standard can then define their own alarm-type hierarchy. 436 The example below shows a hierarchy based on X.733 event types: 438 import ietf-alarms { 439 prefix al; 440 } 441 identity vendor-alarms { 442 base al:alarm-type; 443 } 444 identity communications-alarm { 445 base vendor-alarms; 446 } 447 identity link-alarm { 448 base communications-alarm; 449 } 451 Alarm types can be abstract. An abstract alarm type is used as a 452 base for defining hierarchical alarm types. Concrete alarm types are 453 used for alarm states and appear in the alarm inventory. There are 454 two kinds of concrete alarm types: 456 1. The last subordinate identity in the 'alarm-type-id' hierarchy is 457 concrete, for example: "alarm-identity.environmental- 458 alarm.smoke". In this example "alarm-identity" and 459 "environmental-alarm" are abstract YANG identities, whereas 460 "smoke" is a concrete YANG identity. 462 2. The YANG identity hierarchy is abstract and the concrete alarm 463 type is defined by the dynamic alarm qualifier string, for 464 example: "alarm-identity.environmental-alarm.external-detector" 465 with alarm-type-qualifier "smoke". 467 For example: 469 // Alternative 1: concrete alarm type identity 470 import ietf-alarms { 471 prefix al; 472 } 473 identity environmental-alarm { 474 base al:alarm-type; 475 description "Abstract alarm type"; 476 } 477 identity smoke { 478 base environmental-alarm; 479 description "Concrete alarm type"; 480 } 482 // Alternative 2: concrete alarm type qualifier 483 import ietf-alarms { 484 prefix al; 485 } 486 identity environmental-alarm { 487 base al:alarm-type; 488 description "Abstract alarm type"; 489 } 490 identity external-detector { 491 base environmental-alarm; 492 description 493 "Abstract alarm type, a run-time configuration 494 procedure sets the type of alarm detected. This will 495 be reported in the alarm-qualifier."; 496 } 498 5.3. How are Resources Identified? 500 It is of vital importance to be able to refer to the alarming 501 resource. This reference must be as fine-grained as possible. If 502 the alarming resource exists in the data tree then an instance- 503 identifier MUST be used with the full path to the object. 505 This module also allows for alternate naming of the alarming resource 506 if it is not available in the data tree. 508 5.4. How are Alarm Instances Identified? 510 A primary goal of this alarm module is to remove any ambiguity in how 511 alarm notifications are mapped to an update of an alarm instance. 512 X.733 and especially 3GPP was not really clear on this point. This 513 YANG alarm module states that the tuple (resource, alarm type 514 identifier, alarm type qualifier) corresponds to the same alarm 515 instance. This means that alarm notifications for the same resource 516 and same alarm type are matched to update the same alarm instance. 517 These three leafs are therefore used as the key in the alarm list: 519 list alarm { 520 key "resource alarm-type-id alarm-type-qualifier"; 521 ... 522 } 524 5.5. What is the Life-Cycle of an Alarm? 526 The alarm model clearly separates the resource alarm life-cycle from 527 the operator and administrative life-cycles of an alarm. 529 o resource alarm life-cycle: the alarm instrumentation that controls 530 alarm raise, clearance, and severity changes. 532 o operator alarm life-cycle: operators acting upon alarms with 533 actions like acknowledgment and closing. Closing an alarm implies 534 that the operator considers the corrective action performed. 535 Operators can also shelf alarms in order to avoid nuisance alarms. 537 o administrative alarm life-cycle: deleting (purging) alarms and 538 compressing the alarm status change list. This module exposes 539 operations to manage the administrative life-cycle. The server 540 may also perform these operations based on other policies, but how 541 that is done is out of scope for this document. 543 5.5.1. Resource Alarm Life-Cycle 545 From a resource perspective, an alarm can have the following life- 546 cycle: raise, change severity, change severity, clear, being raised 547 again etc. All of these status changes can have different alarm 548 texts generated by the instrumentation. Two important things to 549 note: 551 1. Alarms are not deleted when they are cleared. Deleting alarms is 552 an administrative process. The alarm module defines an rpc 553 "purge" that deletes alarms. 555 2. Alarms are not cleared by operators, only the underlying 556 instrumentation can clear an alarm. Operators can close alarms. 558 The YANG tree representation below illustrates the resource oriented 559 life-cycle: 561 +--ro alarm* [resource alarm-type-id alarm-type-qualifier] 562 ... 563 +--ro is-cleared boolean 564 +--ro last-status-change yang:date-and-time 565 +--ro last-perceived-severity severity 566 +--ro last-alarm-text alarm-text 567 +--ro status-change* [time] 568 +--ro time yang:date-and-time 569 +--ro perceived-severity severity 570 +--ro alarm-text alarm-text 572 For every status change from the resource perspective a row is added 573 to the 'status-change' list. The last status values are also 574 represented at leafs for the alarm. Note well that the alarm 575 severity does not include 'cleared', alarm clearance is a flag. 577 An alarm can therefore look like this: ((GigabitEthernet0/25, link- 578 alarm,""), false, T, major, "Interface GigabitEthernet0/25 down") 580 5.5.2. Operator Alarm Life-cycle 582 Operators can also act upon alarms using the set-operator-state 583 action: 585 +--ro alarm* [resource alarm-type-id alarm-type-qualifier] 586 ... 587 +--ro last-operator-state operator-state {operator-actions}? 588 +--ro last-operator? string {operator-actions}? 589 +--ro last-operator-text? alarm-text {operator-actions}? 590 +--ro last-operator-action? yang:date-and-time {operator-actions}? 591 +--ro operator-action* [time] {operator-actions}? 592 +--ro time yang:date-and-time 593 +--ro state operator-state 594 +--ro name string 595 +--ro text? string 596 | +--ro last-operator-state-change? yang:date-and-time 597 | +--ro last-operator? string 598 {operator-actions}? 599 | +--ro last-operator-state operator-state 600 {operator-actions}? 601 | +--ro last-operator-text? alarm-text 602 {operator-actions}? 603 | +--ro operator-state-change* [time] {operator-actions}? 604 | | +--ro time yang:date-and-time 605 | | +--ro operator string 606 | | +--ro state operator-state 607 | | +--ro text? string 609 The operator state for an alarm can be: 'none', 'ack', 'shelved', and 610 'closed'. Alarm deletion, 'rpc purge', can use this state as a 611 criteria. A closed alarm is an alarm where the operator has 612 performed any required corrective actions. Closed alarms are good 613 candidates for being deleted. 615 5.5.3. Administrative Alarm Life-Cycle 617 Deleting alarms from the alarm list is considered an administrative 618 action. This is supported by the "purge-alarms" rpc. The "purge- 619 alarms" rpc takes a filter as input. The filter selects alarms based 620 on the operator and resource life-cycle such as "all closed cleared 621 alarms older than a time specification". The server may also perform 622 these operations based on other policies, but how that is done is out 623 of scope for this document. 625 Alarms can be compressed. Compressing an alarm deletes all entries 626 in the alarm's "status-change" list except for the last status 627 change. A client can perform this using the "compress-alarms" rpc. 628 The server may also perform these operations based on other policies, 629 but how that is done is out of scope for this document. 631 5.6. Alarm Shelving 633 Alarm shelving is an important function in order for alarm management 634 applications and operators to stop superfluous alarms. A shelved 635 alarm implies that any alarms fulfilling this criteria are ignored. 636 Shelved alarms appear in a dedicated shelved alarm list in order not 637 to disturb the relevant alarms. Shelved alarms do not generate 638 notifications. 640 6. Alarm Data Model 642 Alarm shelving and operator actions are YANG features so that a 643 server can select not to support these. 645 The data model has the following overall structure: 647 +--rw alarms 648 +--rw control 649 | +--rw max-alarm-status-changes? union 650 | +--rw notify-status-changes? boolean 651 | +--rw alarm-shelving {alarm-shelving}? 652 | +--rw shelf* [shelf-name] 653 | +--rw shelf-name string 654 | +--rw resource? resource 655 | +--rw alarm-type-id? alarm-type-id 656 | +--rw alarm-type-qualifier? alarm-type-qualifier 657 | +--rw description? string 658 +--ro alarm-inventory 659 | +--ro alarm-type* 660 | +--ro alarm-type-id alarm-type-id 661 | +--ro alarm-type-qualifier? alarm-type-qualifier 662 | +--ro has-clear union 663 | +--ro description string 664 +--ro summary 665 | +--ro alarm-summary* [severity] 666 | | +--ro severity severity 667 | | +--ro total? yang:gauge32 668 | | +--ro cleared? yang:gauge32 669 | | +--ro cleared-not-closed? yang:gauge32 670 | | | {operator-actions}? 671 | | +--ro cleared-closed? yang:gauge32 672 | | | {operator-actions}? 673 | | +--ro not-cleared-closed? yang:gauge32 674 | | | {operator-actions}? 675 | | +--ro not-cleared-not-closed? yang:gauge32 676 | | {operator-actions}? 677 | +--ro shelves-active? empty {alarm-shelving}? 678 +--ro alarm-list 679 | +--ro number-of-alarms? yang:gauge32 680 | +--ro last-changed? yang:date-and-time 681 | +--ro alarm* [resource alarm-type-id alarm-type-qualifier] 682 | +--ro resource resource 683 | +--ro alarm-type-id alarm-type-id 684 | +--ro alarm-type-qualifier alarm-type-qualifier 685 | +--ro alt-resource* resource 686 | +--ro related-alarm* 687 | | [resource alarm-type-id alarm-type-qualifier] 688 | | +--ro resource 689 | | | -> /alarms/alarm-list/alarm/resource 690 | | +--ro alarm-type-id leafref 691 | | +--ro alarm-type-qualifier leafref 692 | +--ro impacted-resources* resource 693 | +--ro root-cause-resources* resource 694 | +--ro is-cleared boolean 695 | +--ro last-status-change yang:date-and-time 696 | +--ro last-perceived-severity severity 697 | +--ro last-alarm-text alarm-text 698 | +--ro status-change* [time] 699 | | +--ro time yang:date-and-time 700 | | +--ro perceived-severity severity-with-clear 701 | | +--ro alarm-text alarm-text 702 | +--ro last-operator-state-change? yang:date-and-time 703 | | {operator-actions}? 704 | +--ro last-operator? string 705 | | {operator-actions}? 706 | +--ro last-operator-state operator-state 707 | | {operator-actions}? 708 | +--ro last-operator-text? alarm-text 709 | | {operator-actions}? 710 | +--ro operator-state-change* [time] {operator-actions}? 711 | | +--ro time yang:date-and-time 712 | | +--ro operator string 713 | | +--ro state operator-state 714 | | +--ro text? string 715 | +---x set-operator-state {operator-actions}? 716 | +---w input 717 | +---w state operator-state 718 | +---w text? string 719 +--ro shelved-alarms {alarm-shelving}? 720 +--ro number-of-shelved-alarms? yang:gauge32 721 +--ro alarm-shelf-last-changed? yang:date-and-time 722 +--ro shelved-alarm* 723 [resource alarm-type-id alarm-type-qualifier] 724 +--ro resource resource 725 +--ro alarm-type-id alarm-type-id 726 +--ro alarm-type-qualifier alarm-type-qualifier 727 +--ro alt-resource* resource 728 +--ro related-alarm* 729 | [resource alarm-type-id alarm-type-qualifier] 730 | +--ro resource 731 | | -> /alarms/alarm-list/alarm/resource 732 | +--ro alarm-type-id leafref 733 | +--ro alarm-type-qualifier leafref 734 +--ro impacted-resources* resource 735 +--ro root-cause-resources* resource 736 +--ro is-cleared boolean 737 +--ro last-status-change yang:date-and-time 738 +--ro last-perceived-severity severity 739 +--ro last-alarm-text alarm-text 740 +--ro status-change* [time] 741 | +--ro time yang:date-and-time 742 | +--ro perceived-severity severity-with-clear 743 | +--ro alarm-text alarm-text 744 +--ro last-operator-state-change? yang:date-and-time 745 | {operator-actions}? 746 +--ro last-operator? string 747 | {operator-actions}? 748 +--ro last-operator-state operator-state 749 | {operator-actions}? 750 +--ro last-operator-text? alarm-text 751 | {operator-actions}? 752 +--ro operator-state-change* [time] {operator-actions}? 753 +--ro time yang:date-and-time 754 +--ro operator string 755 +--ro state operator-state 756 +--ro text? string 758 6.1. Alarm Control 760 The "/alarms/control/notify-status-changes" leaf controls if 761 notifications are sent for all state changes, severity change and 762 alarm text change, or just for new and cleared alarms. 764 Every alarm has a list of status changes, this is a circular list. 765 The length of this list is controlled by "/alarms/control/max-alarm- 766 status-changes". 768 6.1.1. Alarm Shelving 770 The shelving control tree is shown below: 772 +--rw alarm-shelving {alarm-shelving}? 773 +--rw shelf* [shelf-name] 774 +--rw shelf-name string 775 +--rw resource? resource 776 +--rw alarm-type-id? alarm-type-id 777 +--rw alarm-type-qualifier? alarm-type-qualifier 779 Shelved alarms are shown in a dedicated shelved alarm list. The 780 instrumentation MUST move shelved alarms from the alarm list 781 (/alarms/alarm-list) to the shelved alarm list (/alarms/shelved- 782 alarms/). Shelved alarms do not generate any notifications. When 783 the shelving criteria is removed or changed the alarm list MUST be 784 updated to the correct actual state of the alarms. 786 A leaf (/alarms/summary/shelfs-active) in the alarm summary indicates 787 if there are shelved alarms. 789 A system can select to not support the shelving feature. 791 6.2. Alarm Inventory 793 The alarm inventory represents all possible alarm types that may 794 occur in the system. A management system may use this to build alarm 795 procedures. The alarm inventory is relevant for several reasons: 797 The system might not instrument all alarm type identities. 799 The system has configured dynamic alarm types using the alarm 800 qualifier. The inventory makes it possible for the management 801 system to discover these. 803 Note that the mechanism whereby dynamic alarm types are added using 804 the alarm type qualifier MUST populate this list. 806 The alarm inventory tree is shown below: 808 +--ro alarm-inventory 809 +--ro alarm-type* 810 +--ro alarm-type-id alarm-type-id 811 +--ro alarm-type-qualifier? alarm-type-qualifier 812 +--ro has-clear union 813 +--ro description string 815 6.3. Alarm Summary 817 The alarm summary list summarises alarms per severity; how many 818 cleared, cleared and closed, and closed. It also gives an indication 819 if there are shelved alarms. 821 6.4. The Alarm List 823 The alarm list (/alarms/alarm-list) is a function from (resource, 824 alarm type, alarm type qualifier) to the current alarm state. 826 +--ro alarm-list 827 +--ro number-of-alarms? yang:gauge32 828 +--ro last-changed? yang:date-and-time 829 +--ro alarm* [resource alarm-type-id alarm-type-qualifier] 830 +--ro resource resource 831 +--ro alarm-type-id alarm-type-id 832 +--ro alarm-type-qualifier alarm-type-qualifier 833 +--ro alt-resource* resource 834 +--ro related-alarm* 835 | [resource alarm-type-id alarm-type-qualifier] 836 | +--ro resource 837 | | -> /alarms/alarm-list/alarm/resource 838 | +--ro alarm-type-id leafref 839 | +--ro alarm-type-qualifier leafref 840 +--ro impacted-resources* resource 841 +--ro root-cause-resources* resource 842 +--ro is-cleared boolean 843 +--ro last-status-change yang:date-and-time 844 +--ro last-perceived-severity severity 845 +--ro last-alarm-text alarm-text 846 +--ro status-change* [time] 847 | +--ro time yang:date-and-time 848 | +--ro perceived-severity severity-with-clear 849 | +--ro alarm-text alarm-text 850 +--ro last-operator-state-change? yang:date-and-time 851 | {operator-actions}? 852 +--ro last-operator? string 853 | {operator-actions}? 854 +--ro last-operator-state operator-state 855 | {operator-actions}? 856 +--ro last-operator-text? alarm-text 857 | {operator-actions}? 858 +--ro operator-state-change* [time] {operator-actions}? 859 | +--ro time yang:date-and-time 860 | +--ro operator string 861 | +--ro state operator-state 862 | +--ro text? string 863 +---x set-operator-state {operator-actions}? 864 +---w input 865 +---w state operator-state 866 +---w text? string 868 Every alarm has three important states, the resource clearance state 869 "is-cleared", the operator state "last-operator-state" and the 870 severity "last-perceived-severity". 872 In order to see the alarm history the resource state changes are 873 available in the "status-change" list and the operator history is 874 available in the "operator-state-change" list. 876 6.5. The Shelved Alarms List 878 The shelved alarm list has the same structure as the alarm list 879 above. It shows all the alarms that matches the shelving criteria 880 (/alarms/control/alarm-shelving). 882 6.6. RPCs 884 The alarm module supports rpcs/actions to manage the alarms: 886 "purge-alarms" (RPC): delete alarms according to specific 887 criteria, for example all cleared alarms older then a specific 888 date. 890 "compress" and "compress-alarms" rpcs: compress the status-change 891 list for the alarms. 893 "set-operator-state" action: change the operator state for an 894 alarm: for example acknowledge. 896 6.7. Notifications 898 The alarm module supports a general notification to report alarm 899 state changes. It carries all relevant parameters for the alarm 900 management application. 902 There is also a notification to report that an operator changed the 903 operator state on an alarm, like acknowledge. 905 7. Alarm YANG Module 907 file "ietf-alarms.yang" 908 module ietf-alarms { 909 yang-version 1.1; 910 namespace "urn:ietf:params:xml:ns:yang:ietf-alarms"; 911 prefix al; 913 import ietf-yang-types { 914 prefix yang; 915 } 917 organization 918 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 920 contact 921 "WG Web: 922 WG List: 924 Editor: Stefan Vallin 925 927 Editor: Martin Bjorklund 928 "; 930 description 931 "This module is an interface for managing alarms. Main inputs to 932 the module design are the 3GPP Alarm IRP, ITU-T X.733 and 933 ANSI/ISA-18.2 alarm standards. 935 Main features of this module include: 937 * Alarm list: 938 A list of all alarms. Cleared alarms stay in 939 the list until explicitly removed. 941 * Operator actions on alarms: 942 Acknowledging and closing alarms. 944 * Administrative actions on alarms: 945 Purging alarms from the list according to specific 946 criteria. 948 * Alarm inventory: 949 A management application can read all 950 alarm types implemented by the system. 952 * Alarm shelving: 953 Shelving (blocking) alarms according 954 to specific criteria. 956 This module uses a stateful view on alarms. An alarm is a state 957 for a specific resource (note that an alarm is not a 958 notification). An alarm type is a possible alarm state for a 959 resource. For example, the tuple: 961 ('link-alarm', 'GigabitEthernet0/25') 963 is an alarm of type 'link-alarm' on the resource 964 'GigabitEthernet0/25'. 966 Alarm types are identified using YANG identities and an optional 967 string-based qualifier. The string-based qualifier allows for 968 dynamic extension of the statically defined alarm types. Alarm 969 types identify a possible alarm state and not the individual 970 notifications. For example, the traditional 'link-down' and 971 'link-up' notifications are two notifications referring to the 972 same alarm type 'link-alarm'. 974 With this design there is no ambiguity about how alarm and alarm 975 clear correlation should be performed: notifications that report 976 the same resource and alarm type are considered updates of the 977 same alarm, such as clearing an active alarm or changing the 978 severity of an alarm. 980 The instrumentation can update 'severity' and 'alarm-text' on an 981 existing alarm. The above alarm example can therefore look 982 like: 984 (('link-alarm', 'GigabitEthernet0/25'), 985 warning, 986 'interface down while interface admin state is up') 988 There is a clear separation between updates on the alarm from 989 the underlying resource, like clear, and updates from an 990 operator like acknowledge or closing an alarm: 992 (('link-alarm', 'GigabitEthernet0/25'), 993 warning, 994 'interface down while interface admin state is up', 995 cleared, 996 closed) 998 Administrative actions like removing closed alarms older than a 999 given time is supported."; 1001 revision 2016-10-05 { 1002 description 1003 "Initial revision."; 1004 reference 1005 "RFC XXXX: YANG Alarm Module"; 1006 } 1008 /* 1009 * Features 1010 */ 1012 feature operator-actions { 1013 description 1014 "This feature means that the systems supports operator states 1015 on alarms."; 1016 } 1018 feature alarm-shelving { 1019 description 1020 "This feature means that the system supports shelving 1021 (blocking) alarms."; 1022 } 1024 /* 1025 * Identities 1026 */ 1028 identity alarm-identity { 1029 description 1030 "Base identity for alarm types. A unique identification of the 1031 alarm, not including the resource. Different resources can 1032 share alarm types. If the resource reports the same alarm 1033 type, it is to be considered to be the same alarm. The alarm 1034 type is a simplification of the different X.733 and 3GPP alarm 1035 IRP alarm correlation mechanisms and it allows for 1036 hierarchical extensions. 1038 A string-based qualifier can be used in addition to the 1039 identity in order to have different alarm types based on 1040 information not known at design-time, such as values in 1041 textual SNMP Notification var-binds. 1043 Standards and vendors can define sub-identities to clearly 1044 identify specific alarm types. 1046 This identity is abstract and shall not be used for alarms."; 1047 } 1049 /* 1050 * Common types 1051 */ 1053 typedef resource { 1054 type union { 1055 type instance-identifier { 1056 require-instance false; 1057 } 1058 type yang:object-identifier; 1059 type string; 1060 } 1061 description 1062 "This is an identification of the alarming resource, such as an 1063 interface. It should be as fine-grained as possible both to 1064 guide the operator and to guarantee uniqueness of the 1065 alarms. If a resource has both a config and a state tree 1066 normally this should identify the state tree, 1067 (e.g., /interfaces-state/interface/name). 1068 But if the instrumentation can detect a broken config, this 1069 should be identified as the resource. 1070 If the alarming resource is modelled in YANG, this 1071 type will be an instance-identifier. If the resource is an 1072 SNMP object, the type will be an object-identifier. If the 1073 resource is anything else, for example a distinguished name or 1074 a CIM path, this type will be a string."; 1075 } 1077 typedef alarm-text { 1078 type string; 1079 description 1080 "The string used to inform operators about the alarm. This 1081 MUST contain enough information for an operator to be able 1082 to understand the problem and how to resolve it. If this 1083 string contains structure, this format should be clearly 1084 documented for programs to be able to parse that 1085 information."; 1086 } 1088 typedef severity { 1089 type enumeration { 1090 enum indeterminate { 1091 value 2; 1092 description 1093 "Indicates that the severity level could not be 1094 determined. This level SHOULD be avoided."; 1095 } 1096 enum minor { 1097 value 3; 1098 description 1099 "The 'minor' severity level indicates the existence of a 1100 non-service affecting fault condition and that corrective 1101 action should be taken in order to prevent a more serious 1102 (for example, service affecting) fault. Such a severity 1103 can be reported, for example, when the detected alarm 1104 condition is not currently degrading the capacity of the 1105 resource."; 1106 } 1107 enum warning { 1108 value 4; 1109 description 1110 "The 'warning' severity level indicates the detection of 1111 a potential or impending service affecting fault, before 1112 any significant effects have been felt. Action should be 1113 taken to further diagnose (if necessary) and correct the 1114 problem in order to prevent it from becoming a more 1115 serious service affecting fault."; 1116 } 1117 enum major { 1118 value 5; 1119 description 1120 "The 'major' severity level indicates that a service 1121 affecting condition has developed and an urgent 1122 corrective action is required. Such a severity can be 1123 reported, for example, when there is a severe 1124 degradation in the capability of the resource 1125 and its full capability must be restored."; 1126 } 1127 enum critical { 1128 value 6; 1129 description 1130 "The 'critical' severity level indicates that a service 1131 affecting condition has occurred and an immediate 1132 corrective action is required. Such a severity can be 1133 reported, for example, when a resource becomes totally 1134 out of service and its capability must be restored."; 1135 } 1136 } 1137 description 1138 "The severity level of the alarm. Note well that value 'clear' 1139 is not included. If an alarm is cleared or not is a separate 1140 boolean flag."; 1141 reference 1142 "ITU Recommendation X.733: Information Technology 1143 - Open Systems Interconnection 1144 - System Management: Alarm Reporting Function"; 1145 } 1147 typedef severity-with-clear { 1148 type union { 1149 type enumeration { 1150 enum cleared { 1151 value 1; 1152 description 1153 "The alarm is cleared by the instrumentation."; 1154 } 1155 } 1156 type severity; 1157 } 1158 description 1159 "The severity level of the alarm including clear. 1160 This is used *only* in notifications reporting state changes 1161 for an alarm."; 1162 } 1164 typedef operator-state { 1165 type enumeration { 1166 enum none { 1167 value 1; 1168 description 1169 "The alarm is not being taken care of."; 1170 } 1171 enum ack { 1172 value 2; 1173 description 1174 "The alarm is being taken care of. Corrective action not 1175 taken yet, or failed"; 1176 } 1177 enum closed { 1178 value 3; 1179 description 1180 "Corrective action taken successfully."; 1181 } 1182 enum shelved { 1183 value 4; 1184 description 1185 "Alarm shelved. Alarms in alarms/shelved-alarms/ 1186 MUST be assigned this state by the server."; 1187 } 1188 enum un-shelved { 1189 value 5; 1190 description 1191 "Alarm moved back to alarm-list from shelf. 1192 Alarms 'moved' from /alarms/shelved-alarms/ 1193 to /alarms/alarm-list MUST be assigned this 1194 state by the server."; 1195 } 1197 } 1198 description 1199 "Operator states on an alarm. The 'closed' state indicates 1200 that an operator considers the alarm being resolved. This 1201 is separate from the resource alarm clear flag."; 1202 } 1204 /* Alarm type */ 1205 typedef alarm-type-id { 1206 type identityref { 1207 base alarm-identity; 1208 } 1209 description 1210 "Identifies an alarm type. The description of the alarm type id 1211 MUST indicate if the alarm type is abstract or not. An 1212 abstract alarm type is used as a base for other alarm type ids 1213 and will not be used as a value for an alarm or be present in 1214 the alarm inventory."; 1215 } 1217 typedef alarm-type-qualifier { 1218 type string; 1219 description 1220 "If an alarm type can not be fully specified at design time by 1221 alarm-type-id, this string qualifier is used in addition to 1222 fully define a unique alarm type. 1224 The definition of alarm qualifiers is considered being part 1225 of the instrumentation and out of scope for this module. 1226 An empty string is used when this is part of a key."; 1227 } 1229 /* 1230 * Groupings 1231 */ 1233 grouping common-alarm-parameters { 1234 description 1235 "Common parameters for an alarm. 1237 This grouping is used both in the alarm list and in the 1238 notification representing an alarm state change."; 1240 leaf resource { 1241 type resource; 1242 mandatory true; 1243 description 1244 "The alarming resource. See also 'alt-resource'. 1245 This could for example be a reference to the alarming 1246 interface"; 1247 } 1249 leaf alarm-type-id { 1250 type alarm-type-id; 1251 mandatory true; 1252 description 1253 "This leaf and the leaf 'alarm-type-qualifier' together 1254 provides a unique identification of the alarm type."; 1255 } 1257 leaf alarm-type-qualifier { 1258 type alarm-type-qualifier; 1259 description 1260 "This leaf is used when the 'alarm-type-id' leaf cannot 1261 uniquely identify the alarm type. Normally, this is not 1262 the case, and this leaf is the empty string."; 1263 } 1265 leaf-list alt-resource { 1266 type resource; 1267 description 1268 "Used if the alarming resource is available over other 1269 interfaces. This field can contain SNMP OID's, CIM paths or 1270 3GPP Distinguished names for example."; 1271 } 1273 list related-alarm { 1274 key "resource alarm-type-id alarm-type-qualifier"; 1276 description 1277 "References to related alarms. Note that the related alarm 1278 might have been removed from the alarm list."; 1280 leaf resource { 1281 type leafref { 1282 path "/alarms/alarm-list/alarm/resource"; 1283 require-instance false; 1284 } 1285 description 1286 "The alarming resource for the related alarm."; 1287 } 1288 leaf alarm-type-id { 1289 type leafref { 1290 path "/alarms/alarm-list/alarm" 1291 + "[resource=current()/../resource]" 1292 + "/alarm-type-id"; 1293 require-instance false; 1294 } 1295 description 1296 "The alarm type identifier for the related alarm."; 1297 } 1298 leaf alarm-type-qualifier { 1299 type leafref { 1300 path "/alarms/alarm-list/alarm" 1301 + "[resource=current()/../resource]" 1302 + "[alarm-type-id=current()/../alarm-type-id]" 1303 + "/alarm-type-qualifier"; 1304 require-instance false; 1305 } 1306 description 1307 "The alarm qualifier for the related alarm."; 1308 } 1309 } 1310 leaf-list impacted-resources { 1311 type resource; 1312 description 1313 "Resources that might be affected by this alarm."; 1314 } 1315 leaf-list root-cause-resources { 1316 type resource; 1317 description 1318 "Resources that are candidates for causing the alarm."; 1319 } 1320 } 1322 grouping alarm-state-change-parameters { 1323 description 1324 "Parameters for an alarm state change. 1326 This grouping is used both in the alarm list's 1327 status-change list and in the notification representing an 1328 alarm state change."; 1330 leaf time { 1331 type yang:date-and-time; 1332 mandatory true; 1333 description 1334 "The time the status of the alarm changed. The value 1335 represents the time the real alarm state change appeared 1336 in the resource and not when it was added to the 1337 alarm list."; 1338 } 1339 leaf perceived-severity { 1340 type severity-with-clear; 1341 mandatory true; 1342 description 1343 "The severity of the alarm as defined by X.733. Note 1344 that this may not be the original severity since the alarm 1345 may have changed severity."; 1346 reference 1347 "ITU Recommendation X.733: Information Technology 1348 - Open Systems Interconnection 1349 - System Management: Alarm Reporting Function"; 1350 } 1351 leaf alarm-text { 1352 type alarm-text; 1353 mandatory true; 1354 description 1355 "A user friendly text describing the alarm state change."; 1356 reference 1357 "ITU Recommendation X.733: Information Technology 1358 - Open Systems Interconnection 1359 - System Management: Alarm Reporting Function"; 1360 } 1361 } 1363 grouping operator-parameters { 1364 description 1365 "This grouping defines parameters that can 1366 be changed by an operator"; 1367 leaf time { 1368 type yang:date-and-time; 1369 mandatory true; 1370 description 1371 "Timestamp for operator action on alarm."; 1372 } 1373 leaf operator { 1374 type string; 1375 mandatory true; 1376 description 1377 "The name of the operator that has acted on this 1378 alarm."; 1379 } 1380 leaf state { 1381 type operator-state; 1382 mandatory true; 1383 description 1384 "The operator's view of the alarm state."; 1385 } 1386 leaf text { 1387 type string; 1388 description 1389 "Additional optional textual information provided by 1390 the operator."; 1391 } 1392 } 1394 grouping resource-alarm-parameters { 1395 description 1396 "Alarm parameters that originates from the resource view."; 1398 leaf is-cleared { 1399 type boolean; 1400 mandatory true; 1401 description 1402 "Indicates the clearance state of the alarm. An alarm 1403 might toggle from active alarm to cleared alarm and back 1404 to active again. This leaf reflects the perceived 1405 severity in the latest entry in the status-change 1406 list."; 1407 } 1409 leaf last-status-change { 1410 type yang:date-and-time; 1411 mandatory true; 1412 description 1413 "A timestamp when the status-change list was last 1414 changed. This value equals the latest 'when' leaf in the 1415 status-change list. The value can be used by a manager 1416 to read the last status change without iterating the 1417 status-change list below. Alarms can be deleted by the 1418 operator using the 'purge' rpc, the status change list of 1419 an alarm can be compressed by the 'compress-alarms' rpc. 1420 The server may also purge and compress alarms based on 1421 locally configured policies, but how this is done is out 1422 of scope for this document."; 1423 } 1425 leaf last-perceived-severity { 1426 type severity; 1427 mandatory true; 1428 description 1429 "The severity of the last status-change that 1430 reported a severity that is not equal to cleared."; 1431 } 1433 leaf last-alarm-text { 1434 type alarm-text; 1435 mandatory true; 1436 description 1437 "The alarm-text of the last status-change that 1438 reported a severity that is not equal to cleared."; 1439 } 1441 list status-change { 1442 key time; 1443 min-elements 1; 1444 description 1445 "A list of status change events for this alarm. 1447 This list is ordered according to the timestamps of 1448 alarm state changes. The last item corresponds to the 1449 latest state change. 1451 The following state changes creates an entry in this 1452 list: 1453 - changed severity (warning, minor, major, critical) 1454 - clearance status, this also updates the is-cleared 1455 leaf 1456 - alarm text update"; 1458 uses alarm-state-change-parameters; 1459 } 1460 } 1462 grouping operator-alarm-parameters { 1463 description 1464 "Alarm parameters that originates from the operator view."; 1466 leaf last-operator-state-change { 1467 if-feature operator-actions; 1468 type yang:date-and-time; 1469 description 1470 "A timestamp when the operator-state-change list was last 1471 changed."; 1472 } 1473 leaf last-operator { 1474 if-feature operator-actions; 1475 type string; 1476 description 1477 "The last operator that acted upon the alarm."; 1478 } 1480 leaf last-operator-state { 1481 if-feature operator-actions; 1482 type operator-state; 1483 mandatory true; 1484 description 1485 "The state of the alarm as set by the operator. When the 1486 alarm is first raised by the instrumentation it has the 1487 'none' state. After initial alarm raise this leaf 1488 represents the state in the latest entry in the 1489 'operator-state-change' list. 1490 The 'closed' state indicates that the alarm is 1491 considered resolved by the operator."; 1492 } 1494 leaf last-operator-text { 1495 if-feature operator-actions; 1496 type alarm-text; 1497 description 1498 "The alarm-text of the last status change."; 1499 } 1501 list operator-state-change { 1502 if-feature operator-actions; 1503 key time; 1504 description 1505 "This list is used by operators to indicate 1506 the state of human intervention on an alarm. 1507 For example, if an operator has seen an alarm, 1508 the operator can add a new item to this list indicating 1509 that the alarm is acknowledged."; 1510 uses operator-parameters; 1511 } 1513 } 1515 /* 1516 * The /alarms data tree 1517 */ 1519 container alarms { 1520 description 1521 "The top container for this module"; 1522 container control { 1523 description 1524 "Configuration to control the alarm behaviour."; 1525 leaf max-alarm-status-changes { 1526 type union { 1527 type uint16; 1528 type enumeration { 1529 enum infinite { 1530 description 1531 "The status change entries are accumulated 1532 infinitely."; 1533 } 1534 } 1535 } 1536 default 32; 1537 description 1538 "The status-change entries are kept in a circular list 1539 per alarm. When this number is exceeded, the oldest 1540 status change entry is automatically removed. If the 1541 value is 'infinite', the status change entries are 1542 accumulated infinitely."; 1543 } 1545 leaf notify-status-changes { 1546 type boolean; 1547 default false; 1548 description 1549 "This leaf controls whether notifications are sent on all 1550 alarm status updates, e.g., updated perceived-severity or 1551 alarm-text. By default the notifications are only sent 1552 when a new alarm is raised, re-raised after being cleared 1553 and when an alarm is cleared."; 1554 } 1555 container alarm-shelving { 1556 if-feature alarm-shelving; 1557 description 1558 "This list is used to shelf alarms. The server will move 1559 any alarms corresponding to the shelving criteria from the 1560 alarms/alarm-list/alarm list to the 1561 alarms/shelved-alarms/shelved-alarm list. It will also 1562 stop sending notifications for the shelved alarms. The 1563 conditions in the shelf criteria are logically ANDed. When 1564 the shelving criteria is deleted or changed, the 1565 non-matching alarms MUST appear in the 1566 alarms/alarm-list/alarm list according to the real state. 1567 This means that the instrumentation MUST maintain states 1568 for the shelved alarms. Alarms that match the criteria 1569 shall have an operator-state 'shelved'."; 1570 list shelf { 1571 key shelf-name; 1572 leaf shelf-name { 1573 type string; 1574 description 1575 "An arbitrary name for the alarm shelf."; 1576 } 1577 description 1578 "Each entry defines the criteria for shelving alarms. 1579 Criterias are ANDed."; 1581 leaf resource { 1582 type resource; 1583 description 1584 "Shelv alarms for this resource."; 1585 } 1586 leaf alarm-type-id { 1587 type alarm-type-id; 1588 description 1589 "Shelv alarms for this alarm type identifier."; 1591 } 1592 leaf alarm-type-qualifier { 1593 type alarm-type-qualifier; 1594 description 1595 "Shelv alarms for this alarm type qualifier."; 1596 } 1597 leaf description { 1598 type string; 1599 description 1600 "An optional textual description of the shelf. This 1601 description should include the reason for shelving 1602 these alarms."; 1603 } 1604 } 1605 } 1606 } 1608 container alarm-inventory { 1609 config false; 1610 description 1611 "This list contains all possible alarm types for the system. 1612 The list also tells if each alarm type has a corresponding 1613 clear state. The inventory shall only contain concrete alarm 1614 types."; 1615 list alarm-type { 1616 description 1617 "An entry in this list defines a possible alarm."; 1618 leaf alarm-type-id { 1619 type alarm-type-id; 1620 mandatory true; 1621 description 1622 "The statically defined alarm type identifier for this 1623 possible alarm."; 1624 } 1625 leaf alarm-type-qualifier { 1626 type alarm-type-qualifier; 1627 description 1628 "The optionally dynamically defined alarm type identifier 1629 for this possible alarm."; 1630 } 1631 leaf has-clear { 1632 type union { 1633 type boolean; 1634 } 1635 mandatory true; 1636 description 1637 "This leaf tells the operator if the alarm will be 1638 cleared when the correct corrective action has been 1639 taken. Implementations SHOULD strive for detecting the 1640 cleared state for all alarm types. If this leaf is 1641 true, the operator can monitor the alarm until it 1642 becomes cleared after the corrective action has been 1643 taken. If this leaf is false the operator needs to 1644 validate that the alarm is not longer active using other 1645 mechanisms. Alarms can lack a corresponding clear due 1646 to missing instrumentation or that there is no logical 1647 corresponding clear state."; 1648 } 1649 leaf description { 1650 type string; 1651 mandatory true; 1652 description 1653 "A description of the possible alarm. It SHOULD include 1654 information on possible underlying root causes and 1655 corrective actions."; 1656 } 1657 } 1658 } 1660 container summary { 1661 config false; 1662 description 1663 "This container gives a summary of number of alarms 1664 and shelved alarms"; 1665 list alarm-summary { 1666 key severity; 1667 description 1668 "A global summary of all alarms in the system."; 1669 leaf severity { 1670 type severity; 1671 description 1672 "Alarm summary for this severity level."; 1673 } 1674 leaf total { 1675 type yang:gauge32; 1676 description 1677 "Total number of alarms of this severity level."; 1678 } 1679 leaf cleared { 1680 type yang:gauge32; 1681 description 1682 "For this severity level, the number of alarms that are 1683 cleared."; 1684 } 1685 leaf cleared-not-closed { 1686 if-feature operator-actions; 1687 type yang:gauge32; 1688 description 1689 "For this severity level, the number of alarms that are 1690 cleared but not closed."; 1691 } 1692 leaf cleared-closed { 1693 if-feature operator-actions; 1694 type yang:gauge32; 1695 description 1696 "For this severity level, the number of alarms that are 1697 cleared and closed."; 1698 } 1699 leaf not-cleared-closed { 1700 if-feature operator-actions; 1701 type yang:gauge32; 1702 description 1703 "For this severity level, the number of alarms that are 1704 not cleared but closed."; 1705 } 1706 leaf not-cleared-not-closed { 1707 if-feature operator-actions; 1708 type yang:gauge32; 1709 description 1710 "For this severity level, the number of alarms that are 1711 not cleared and not closed."; 1712 } 1713 } 1714 leaf shelves-active { 1715 if-feature alarm-shelving; 1716 type empty; 1717 description 1718 "This is a hint to the operator that there are active 1719 alarm shelves. This leaf MUST exist if the 1720 alarms/shelved-alarms/number-of-shelved-alarms is > 0."; 1721 } 1722 } 1724 container alarm-list { 1725 config false; 1726 description 1727 "The alarms in the system."; 1728 leaf number-of-alarms { 1729 type yang:gauge32; 1730 description 1731 "This object shows the total number of 1732 alarms in the system, i.e., the total number 1733 of entries in the alarm list."; 1734 } 1735 leaf last-changed { 1736 type yang:date-and-time; 1737 description 1738 "A timestamp when the alarm list was last 1739 changed. The value can be used by a manager to 1740 initiate an alarm resynchronization procedure."; 1741 } 1743 list alarm { 1744 key "resource alarm-type-id alarm-type-qualifier"; 1746 description 1747 "The list of alarms. Each entry in the list holds one 1748 alarm for a given alarm type and resource. 1749 An alarm can be updated from the underlying resource or 1750 by the user. These changes are reflected in different 1751 lists below the corresponding alarm."; 1753 uses common-alarm-parameters; 1754 uses resource-alarm-parameters; 1755 uses operator-alarm-parameters; 1757 action set-operator-state { 1758 if-feature operator-actions; 1759 description 1760 "This is a means for the operator to indicate 1761 the level of human intervention on an alarm."; 1762 input { 1763 leaf state { 1764 type operator-state; 1765 mandatory true; 1766 description 1767 "Set this operator state."; 1768 } 1769 leaf text { 1770 type string; 1771 description 1772 "Additional optional textual information."; 1773 } 1774 } 1775 } 1777 } 1778 } 1780 container shelved-alarms { 1781 if-feature alarm-shelving; 1782 config false; 1783 description 1784 "The shelved alarms. Alarms appear here if they match the 1785 criterias in /alarms/control/alarm-shelving. This list does 1786 not generate any notifications. The list represents alarms 1787 that are considered not relevant by the operator. Alarms in 1788 this list have an operator-state of 'shelved'. This can not 1789 be changed."; 1790 leaf number-of-shelved-alarms { 1791 type yang:gauge32; 1792 description 1793 "This object shows the total number of currently 1794 alarms, i.e., the total number of entries 1795 in the alarm list."; 1796 } 1798 leaf alarm-shelf-last-changed { 1799 type yang:date-and-time; 1800 description 1801 "A timestamp when the shelved alarm list was last 1802 changed. The value can be used by a manager to 1803 initiate an alarm resynchronization procedure."; 1804 } 1806 list shelved-alarm { 1807 key "resource alarm-type-id alarm-type-qualifier"; 1809 description 1810 "The list of shelved alarms. Each entry in the list holds 1811 one alarm for a given alarm type and resource. An alarm 1812 can be updated from the underlying resource or by the 1813 user. These changes are reflected in different lists below 1814 the corresponding alarm."; 1816 uses common-alarm-parameters; 1817 uses resource-alarm-parameters; 1818 uses operator-alarm-parameters; 1820 } 1821 } 1822 } 1824 /* 1825 * Operations 1826 */ 1828 rpc compress-alarms { 1829 description 1830 "This operation requests the server to compress entries in the 1831 alarm list by removing all but the latest state change for all 1832 alarms. Conditions in the input are logically ANDed. If no 1833 input condition is given, all alarms are compressed."; 1834 input { 1835 leaf resource { 1836 type leafref { 1837 path "/alarms/alarm-list/alarm/resource"; 1838 require-instance false; 1839 } 1840 description 1841 "Compress the alarms with this resource."; 1842 } 1843 leaf alarm-type-id { 1844 type leafref { 1845 path "/alarms/alarm-list/alarm/alarm-type-id"; 1846 } 1847 description 1848 "Compress alarms with this alarm-type-id."; 1849 } 1850 leaf alarm-type-qualifier { 1851 type leafref { 1852 path "/alarms/alarm-list/alarm/alarm-type-qualifier"; 1853 } 1854 description 1855 "Compress the alarms with this alarm-type-qualifier."; 1856 } 1857 } 1858 output { 1859 leaf compressed-alarms { 1860 type uint32; 1861 description 1862 "Number of compressed alarm entries."; 1863 } 1864 } 1865 } 1867 grouping filter-input { 1868 description 1869 "Grouping to specify a filter construct on alarm information."; 1870 leaf alarm-status { 1871 type enumeration { 1872 enum any { 1873 description 1874 "Ignore alarm clearance status."; 1875 } 1876 enum cleared { 1877 description 1878 "Filter cleared alarms."; 1880 } 1881 enum not-cleared { 1882 description 1883 "Filter not cleared alarms."; 1884 } 1885 } 1886 mandatory true; 1887 description 1888 "The clearance status of the alarm."; 1889 } 1891 container older-than { 1892 presence "Age specification"; 1893 description 1894 "Matches the 'last-status-change' leaf in the alarm."; 1895 choice age-spec { 1896 description 1897 "Filter using date and time age."; 1898 case seconds { 1899 leaf seconds { 1900 type uint16; 1901 description 1902 "Seconds part"; 1903 } 1904 } 1905 case minutes { 1906 leaf minutes { 1907 type uint16; 1908 description 1909 "Minute part"; 1910 } 1911 } 1912 case hours { 1913 leaf hours { 1914 type uint16; 1915 description 1916 "Hours part."; 1917 } 1918 } 1919 case days { 1920 leaf days { 1921 type uint16; 1922 description 1923 "Day part"; 1924 } 1925 } 1926 case weeks { 1927 leaf weeks { 1928 type uint16; 1929 description 1930 "Week part"; 1931 } 1932 } 1933 } 1934 } 1935 container severity { 1936 presence "Severity filter"; 1937 choice sev-spec { 1938 description 1939 "Filter based on severity level."; 1940 leaf below { 1941 type severity; 1942 description 1943 "Severity less than this leaf."; 1944 } 1945 leaf is { 1946 type severity; 1947 description 1948 "Severity level equal this leaf."; 1949 } 1950 leaf above { 1951 type severity; 1952 description 1953 "Severity level higher than this leaf."; 1954 } 1955 } 1956 description 1957 "Filter based on severity."; 1958 } 1959 container operator-state-filter { 1960 if-feature operator-actions; 1961 presence "Operator state filter"; 1962 leaf state { 1963 type operator-state; 1964 description 1965 "Filter on operator state."; 1966 } 1967 leaf user { 1968 type string; 1969 description 1970 "Filter based on which operator."; 1971 } 1972 description 1973 "Filter based on operator state."; 1974 } 1975 } 1976 rpc purge-alarms { 1977 description 1978 "This operation requests the server to delete entries from the 1979 alarm list according to the supplied criteria. Typically it 1980 can be used to delete alarms that are in closed operator state 1981 and older than a specified time. The number of purged alarms 1982 is returned as an output parameter"; 1983 input { 1984 uses filter-input; 1985 } 1986 output { 1987 leaf purged-alarms { 1988 type uint32; 1989 description 1990 "Number of purged alarms."; 1991 } 1992 } 1993 } 1995 /* 1996 * Notifications 1997 */ 1999 notification alarm-notification { 2000 description 2001 "This notification is used to report a state change for an 2002 alarm. The same notification is used for sending a newly 2003 raised alarm, a cleared alarm or changing the text and/or 2004 severity of an existing alarm."; 2006 uses common-alarm-parameters; 2007 uses alarm-state-change-parameters; 2008 } 2010 notification operator-action { 2011 if-feature operator-actions; 2012 description 2013 "This notification is used to report that an operator 2014 acted upon an alarm."; 2016 leaf resource { 2017 type leafref { 2018 path "/alarms/alarm-list/alarm/resource"; 2019 require-instance false; 2020 } 2021 description 2022 "The alarming resource."; 2023 } 2024 leaf alarm-type-id { 2025 type leafref { 2026 path "/alarms/alarm-list/alarm" 2027 + "[resource=current()/../resource]" 2028 + "/alarm-type-id"; 2029 require-instance false; 2030 } 2031 description 2032 "The alarm type identifier for the alarm."; 2033 } 2034 leaf alarm-type-qualifier { 2035 type leafref { 2036 path "/alarms/alarm-list/alarm" 2037 + "[resource=current()/../resource]" 2038 + "[alarm-type-id=current()/../alarm-type-id]" 2039 + "/alarm-type-qualifier"; 2040 require-instance false; 2041 } 2042 description 2043 "The alarm qualifier for the alarm."; 2044 } 2046 uses operator-parameters; 2047 } 2048 } 2050 2052 8. X.733 Alarm Mapping Data Model 2054 Many alarm management systems are based on the X.733 alarm standard. 2055 This YANG module allows a mapping from alarm types to X.733 event- 2056 type and probable-cause. 2058 The module augments the alarm inventory, the alarm list and the alarm 2059 notification with X.733 parameters. 2061 The module also supports a feature whereby the alarm manager can 2062 configure the mapping. This might be needed when the default mapping 2063 provided by the system is in conflict with other systems or not 2064 considered good. 2066 9. X.733 Alarm Mapping YANG Module 2068 This YANG module references [X.736]. 2070 file "ietf-alarms-x733.yang" 2071 module ietf-alarms-x733 { 2072 yang-version 1.1; 2073 namespace "urn:ietf:params:xml:ns:yang:ietf-alarms-x733"; 2074 prefix x733; 2076 import ietf-alarms { 2077 prefix al; 2078 } 2080 organization 2081 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2083 contact 2084 "WG Web: 2085 WG List: 2087 Editor: Stefan Vallin 2088 2090 Editor: Martin Bjorklund 2091 "; 2093 description 2094 "This module augments the ietf-alarms module with X.733 mapping 2095 information. The following structures are augemented with 2096 event type and probable cause: 2098 1) alarm inventory: all possible alarms. 2099 2) alarm: every alarm in the system. 2100 3) alarm notification: notifications indicating alarm state 2101 changes. 2103 The module also optionally allows the alarm management system 2104 to configure the mapping. The mapping does not include a 2105 a corresponding specific problem value. The recommendation is 2106 to use alarm-type-qualifier which serves the same purpose."; 2107 reference 2108 "ITU Recommendation X.733: Information Technology 2109 - Open Systems Interconnection 2110 - System Management: Alarm Reporting Function"; 2112 revision 2016-10-05 { 2113 description 2114 "Initial revision."; 2115 reference 2116 "RFC XXXX: YANG Alarm Module"; 2117 } 2119 /* 2120 * Features 2121 */ 2123 feature configure-x733-mapping { 2124 description 2125 "The system supports configurable X733 mapping from 2126 alarm type to event type and probable cause."; 2127 } 2129 /* 2130 * Typedefs 2131 */ 2133 typedef event-type { 2134 type enumeration { 2135 enum other { 2136 value 1; 2137 description 2138 "None of the below."; 2139 } 2140 enum communications-alarm { 2141 value 2; 2142 description 2143 "An alarm of this type is principally associated with the 2144 procedures and/or processes required to convey 2145 information from one point to another."; 2146 reference 2147 "ITU Recommendation X.733: Information Technology 2148 - Open Systems Interconnection 2149 - System Management: Alarm Reporting Function"; 2150 } 2151 enum quality-of-service-alarm { 2152 value 3; 2153 description 2154 "An alarm of this type is principally associated with a 2155 degradation in the quality of a service."; 2156 reference 2157 "ITU Recommendation X.733: Information Technology 2158 - Open Systems Interconnection 2159 - System Management: Alarm Reporting Function"; 2160 } 2161 enum processing-error-alarm { 2162 value 4; 2163 description 2164 "An alarm of this type is principally associated with a 2165 software or processing fault."; 2166 reference 2167 "ITU Recommendation X.733: Information Technology 2168 - Open Systems Interconnection 2169 - System Management: Alarm Reporting Function"; 2170 } 2171 enum equipment-alarm { 2172 value 5; 2173 description 2174 "An alarm of this type is principally associated with an 2175 equipment fault."; 2176 reference 2177 "ITU Recommendation X.733: Information Technology 2178 - Open Systems Interconnection 2179 - System Management: Alarm Reporting Function"; 2180 } 2181 enum environmental-alarm { 2182 value 6; 2183 description 2184 "An alarm of this type is principally associated with a 2185 condition relating to an enclosure in which the equipment 2186 resides."; 2187 reference 2188 "ITU Recommendation X.733: Information Technology 2189 - Open Systems Interconnection 2190 - System Management: Alarm Reporting Function"; 2191 } 2192 enum integrity-violation { 2193 value 7; 2194 description 2195 "An indication that information may have been illegally 2196 modified, inserted or deleted."; 2197 reference 2198 "ITU Recommendation X.736: Information Technology 2199 - Open Systems Interconnection 2200 - System Management: Security Alarm Reporting Function"; 2201 } 2202 enum operational-violation { 2203 value 8; 2204 description 2205 "An indication that the provision of the requested service 2206 was not possible due to the unavailability, malfunction or 2207 incorrect invocation of the service."; 2208 reference 2209 "ITU Recommendation X.736: Information Technology 2210 - Open Systems Interconnection 2211 - System Management: Security Alarm Reporting Function"; 2212 } 2213 enum physical-violation { 2214 value 9; 2215 description 2216 "An indication that a physical resource has been violated 2217 in a way that suggests a security attack."; 2218 reference 2219 "ITU Recommendation X.736: Information Technology 2220 - Open Systems Interconnection 2221 - System Management: Security Alarm Reporting Function"; 2222 } 2223 enum security-service-or-mechanism-violation { 2224 value 10; 2225 description 2226 "An indication that a security attack has been detected by 2227 a security service or mechanism."; 2228 reference 2229 "ITU Recommendation X.736: Information Technology 2230 - Open Systems Interconnection 2231 - System Management: Security Alarm Reporting Function"; 2232 } 2233 enum time-domain-violation { 2234 value 11; 2235 description 2236 "An indication that an event has occurred at an unexpected 2237 or prohibited time."; 2238 reference 2239 "ITU Recommendation X.736: Information Technology 2240 - Open Systems Interconnection 2241 - System Management: Security Alarm Reporting Function"; 2242 } 2243 } 2244 description 2245 "The event types as defined by X.733 and X.736. The use of the 2246 term 'event' is a bit confusing. In an alarm context these 2247 are top level alarm types."; 2248 } 2250 /* 2251 * Groupings 2252 */ 2254 grouping x733-alarm-parameters { 2255 description 2256 "Common X.733 parameters for alarms."; 2258 leaf event-type { 2259 type event-type; 2260 description 2261 "The X.733/X.736 event type for this alarm."; 2262 } 2263 leaf probable-cause { 2264 type uint32; 2265 description 2266 "The X.733 probable cause for this alarm."; 2267 } 2268 } 2270 grouping x733-alarm-definition-parameters { 2271 description 2272 "Common X.733 parameters for alarm definitions."; 2274 leaf event-type { 2275 type event-type; 2276 description 2277 "The alarm type has this X.733/X.736 event type."; 2278 } 2279 leaf probable-cause { 2280 type uint32; 2281 description 2282 "The alarm type has this X.733 probable cause value. 2283 This module defines probable cause as an integer 2284 and not as an enumeration. The reason being that the 2285 primary use of probable cause is in the management 2286 application if it is based on the X.733 standard. 2287 However, most management applications have their own 2288 defined enum definitions and merging enums from 2289 different systems might create conflicts. By using 2290 a configurable uint32 the system can be configured 2291 to match the enum values in the manager."; 2292 } 2293 } 2295 /* 2296 * Add X.733 parameters to the alarm defintions, alarms, 2297 * and notification. 2298 */ 2300 augment "/al:alarms/al:alarm-inventory/al:alarm-type" { 2301 description 2302 "Augment X.733 mapping information to the alarm inventory."; 2304 uses x733-alarm-definition-parameters; 2305 } 2307 augment "/al:alarms/al:control" { 2308 description 2309 "Add X.733 mapping capabilities. "; 2310 list x733-mapping { 2311 if-feature configure-x733-mapping; 2312 key "alarm-type-id alarm-type-qualifier-match"; 2313 description 2314 "This list allows a management application to control the 2315 X.733 mapping for all alarm types in the system. Any entry 2316 in this list will allow the alarm manager to over-ride the 2317 default X.733 mapping in the system and the final mapping 2318 will be shown in the alarm-inventory"; 2320 leaf alarm-type-id { 2321 type al:alarm-type-id; 2322 description 2323 "Map the alarm type with this alarm type identifier."; 2324 } 2325 leaf alarm-type-qualifier-match { 2326 type string; 2327 description 2328 "A W3C regular expression that is used when mapping an 2329 alarm type and alarm-type-qualifier to X.733 parameters."; 2330 } 2332 uses x733-alarm-definition-parameters; 2333 } 2334 } 2336 augment "/al:alarms/al:alarm-list/al:alarm" { 2337 description 2338 "Augment X.733 information to the alarm."; 2340 uses x733-alarm-parameters; 2341 } 2343 augment "/al:alarms/al:shelved-alarms/al:shelved-alarm" { 2344 description 2345 "Augment X.733 information to the alarm."; 2347 uses x733-alarm-parameters; 2348 } 2350 augment "/al:alarm-notification" { 2351 description 2352 "Augment X.733 information to the alarm notification."; 2354 uses x733-alarm-parameters; 2355 } 2356 } 2358 2360 10. Security Considerations 2362 None. 2364 11. Acknowledgements 2366 The author wishes to thank Viktor Leijon and Johan Nordlander for 2367 their valuable input on forming the alarm model. 2369 12. References 2371 12.1. Normative References 2373 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2374 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2375 RFC2119, March 1997, 2376 . 2378 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2379 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2380 . 2382 12.2. Informative References 2384 [ALARMIRP] 2385 3GPP, "Telecommunication management; Fault Management; 2386 Part 2: Alarm Integration Reference Point (IRP): 2387 Information Service (IS)", 3GPP TS 32.111-2 3.4.0, March 2388 2005. 2390 [ALARMSEM] 2391 Wallin, S., Leijon, V., Nordlander, J., and N. Bystedt, 2392 "The semantics of alarm definitions: enabling systematic 2393 reasoning about alarms. International Journal of Network 2394 Management, Volume 22, Issue 3, John Wiley and Sons, Ltd, 2395 http://dx.doi.org/10.1002/nem.800", March 2012. 2397 [EEMUA] EEMUA Publication No. 191 Engineering Equipment and 2398 Materials Users Association, London, 2 edition., "Alarm 2399 Systems: A Guide to Design, Management and Procurement.", 2400 2007. 2402 [ISA182] International Society of Automation,ISA, "ANSI/ISA- 2403 18.2-2009 Management of Alarm Systems for the Process 2404 Industries", 2009. 2406 [RFC3877] Chisholm, S. and D. Romascanu, "Alarm Management 2407 Information Base (MIB)", RFC 3877, DOI 10.17487/RFC3877, 2408 September 2004, . 2410 [X.733] International Telecommunications Union, "Information 2411 Technology - Open Systems Interconnection - Systems 2412 Management: Alarm Reporting Function", ITU-T 2413 Recommendation X.733, 1992. 2415 [X.736] International Telecommunications Union, "Information 2416 Technology - Open Systems Interconnection - Systems 2417 Management: Security alarm reporting function", ITU-T 2418 Recommendation X.736, 1992. 2420 Appendix A. Enterprise-specific Alarm-Types Example 2422 This example shows how to define alarm-types in an enterprise 2423 specific module. In this case "xyz" has chosen to define top level 2424 identities according to X.733 event types. 2426 module example-xyz-alarms { 2427 namespace "urn:example:xyz-alarms"; 2428 prefix xyz-al; 2430 import ietf-alarms { 2431 prefix al; 2432 } 2434 identity xyz-alarms { 2435 base al:alarm-identity; 2436 } 2438 identity communications-alarm { 2439 base xyz-alarms; 2440 } 2441 identity quality-of-service-alarm { 2442 base xyz-alarms; 2443 } 2444 identity processing-error-alarm { 2445 base xyz-alarms; 2446 } 2447 identity equipment-alarm { 2448 base xyz-alarms; 2449 } 2450 identity environmental-alarm { 2451 base xyz-alarms; 2452 } 2454 // communications alarms 2455 identity link-alarm { 2456 base communications-alarm; 2457 } 2459 // QoS alarms 2460 identity high-jitter-alarm { 2461 base quality-of-service-alarm; 2462 } 2463 } 2465 Appendix B. Alarm Inventory Example 2467 This shows an alarm inventory, it shows one alarm type defined only 2468 with the identifier, and another dynamically configured. In the 2469 latter case a digital input has been connected to a smoke-detector, 2470 therefore the 'alarm-type-qualifier' is set to "smoke-detector" and 2471 the 'alarm-type-identity' to "environmental-alarm". 2473 2475 2476 2477 2478 Link failure, operational state down but admin state up 2479 2480 xyz-al:link-alarm 2481 true 2482 2483 2484 2485 Connected smoke detector to digital input 2486 2487 xyz-al:environmental-alarm 2488 smoke-alarm 2489 true 2490 2491 2492 2494 Appendix C. Alarm List Example 2496 In this example we show an alarm that has toggled [major, clear, 2497 major]. An operator has acknowledged the alarm. 2499 2502 2503 1 2504 2015-04-08T08:39:50.00Z 2506 2507 2508 /dev:interfaces/dev:interface[name='FastEthernet1/0'] 2509 2510 xyz-al:link-alarm 2511 2513 false 2514 1.3.6.1.2.1.2.2.1.1.17 2515 2516 2015-04-08T08:39:40.00Z 2517 2518 major 2519 2520 Link operationally down but administratively up 2521 2522 2523 2524 major 2525 2526 Link operationally down but administratively up 2527 2528 2529 2530 2531 cleared 2532 2533 Link operationally up and administratively up 2534 2535 2536 2537 2538 major 2539 2540 Link operationally down but administratively up 2541 2542 2544 ack 2545 2546 Will investigate, ticket TR764999 2547 2548 2549 2015-04-08T08:39:50.00Z 2550 2551 2552 2553 ack 2554 joe 2555 Will investigate, ticket TR764999 2556 2557 2559 2560 2562 Appendix D. Alarm Shelving Example 2564 This example shows how to shelf alarms. We shelf alarms related to 2565 the smoke-detectors since they are being installed and tested. We 2566 also shelf all alarms from FastEthernet1/0. 2568 2571 2572 2573 2574 FE10 2575 2576 /dev:interfaces/dev:interface[name='FastEthernet1/0'] 2577 2578 2579 2580 detectortest 2581 xyz-al:environmental-alarm 2582 smoke-alarm 2583 2584 2585 2586 2588 Appendix E. X.733 Mapping Example 2590 This example shows how to map a dynamic alarm type (alarm-type- 2591 identity=environmental-alarm, alarm-type-qualifier=smoke-alarm) to 2592 the corresponding X.733 event-type and probable cause parameters. 2594 2596 2597 2599 xyz-al:environmental-alarm 2600 2601 smoke-alarm 2602 2603 quality-of-service-alarm 2604 777 2605 2606 2607 2609 Authors' Addresses 2610 Stefan Vallin 2611 Stefan Vallin AB 2613 Email: stefan@wallan.se 2615 Martin Bjorklund 2616 Cisco 2618 Email: mbj@tail-f.com