| module ietf-alarms { |
| yang-version 1.1; |
| namespace "urn:ietf:params:xml:ns:yang:ietf-alarms"; |
| prefix al; |
| |
| import ietf-yang-types { |
| prefix yang; |
| reference |
| "RFC 6991: Common YANG Data Types."; |
| } |
| |
| organization |
| "IETF CCAMP Working Group"; |
| contact |
| "WG Web: <https://trac.ietf.org/trac/ccamp> |
| WG List: <mailto:ccamp@ietf.org> |
| |
| Editor: Stefan Vallin |
| <mailto:stefan@wallan.se> |
| |
| Editor: Martin Bjorklund |
| <mailto:mbj@tail-f.com>"; |
| description |
| "This module defines an interface for managing alarms. Main |
| inputs to the module design are the 3GPP Alarm Integration |
| Reference Point (IRP), ITU-T X.733, and ANSI/ISA-18.2 alarm |
| standards. |
| |
| Main features of this module include: |
| |
| * Alarm list: |
| A list of all alarms. Cleared alarms stay in |
| the list until explicitly purged. |
| |
| * Operator actions on alarms: |
| Acknowledging and closing alarms. |
| |
| * Administrative actions on alarms: |
| Purging alarms from the list according to specific |
| criteria. |
| |
| * Alarm inventory: |
| A management application can read all |
| alarm types implemented by the system. |
| |
| * Alarm shelving: |
| Shelving (blocking) alarms according |
| to specific criteria. |
| |
| * Alarm profiles: |
| A management system can attach further |
| information to alarm types, for example, |
| overriding system-default severity |
| levels. |
| |
| This module uses a stateful view on alarms. An alarm is a state |
| for a specific resource (note that an alarm is not a |
| notification). An alarm type is a possible alarm state for a |
| resource. For example, the tuple: |
| |
| ('link-alarm', 'GigabitEthernet0/25') |
| |
| is an alarm of type 'link-alarm' on the resource |
| 'GigabitEthernet0/25'. |
| |
| Alarm types are identified using YANG identities and an optional |
| string-based qualifier. The string-based qualifier allows for |
| dynamic extension of the statically defined alarm types. Alarm |
| types identify a possible alarm state and not the individual |
| notifications. For example, the traditional 'link-down' and |
| 'link-up' notifications are two notifications referring to the |
| same alarm type 'link-alarm'. |
| |
| With this design, there is no ambiguity about how alarm and |
| alarm clear correlation should be performed; notifications that |
| report the same resource and alarm type are considered updates |
| of the same alarm, e.g., clearing an active alarm or changing |
| the severity of an alarm. The instrumentation can update the |
| severity and alarm text on an existing alarm. The above alarm |
| example can therefore look like the following: |
| |
| (('link-alarm', 'GigabitEthernet0/25'), |
| warning, |
| 'interface down while interface admin state is up') |
| |
| There is a clear separation between updates on the alarm from |
| the underlying resource, like clear, and updates from an |
| operator, like acknowledging or closing an alarm: |
| |
| (('link-alarm', 'GigabitEthernet0/25'), |
| warning, |
| 'interface down while interface admin state is up', |
| cleared, |
| closed) |
| |
| Administrative actions like removing closed alarms older than a |
| given time is supported. |
| |
| This YANG module does not define how the underlying |
| instrumentation detects and clears the specific alarms. That |
| belongs to the Standards Development Organization (SDO) or |
| enterprise that owns that specific technology. |
| |
| The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL |
| NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', |
| 'MAY', and 'OPTIONAL' in this document are to be interpreted as |
| described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, |
| they appear in all capitals, as shown here. |
| |
| Copyright (c) 2019 IETF Trust and the persons identified as |
| authors of the code. All rights reserved. |
| |
| Redistribution and use in source and binary forms, with or |
| without modification, is permitted pursuant to, and subject to |
| the license terms contained in, the Simplified BSD License set |
| forth in Section 4.c of the IETF Trust's Legal Provisions |
| Relating to IETF Documents |
| (https://trustee.ietf.org/license-info). |
| |
| This version of this YANG module is part of RFC 8632; see |
| the RFC itself for full legal notices."; |
| |
| revision 2019-09-11 { |
| description |
| "Initial revision."; |
| reference |
| "RFC 8632: A YANG Data Model for Alarm Management"; |
| } |
| |
| /* |
| * Features |
| */ |
| |
| feature operator-actions { |
| description |
| "This feature indicates that the system supports operator |
| states on alarms."; |
| } |
| |
| feature alarm-shelving { |
| description |
| "This feature indicates that the system supports shelving |
| (blocking) alarms. |
| |
| Alarm shelving may have an impact on server processing |
| resources in order to match alarms against shelf |
| criteria."; |
| } |
| |
| feature alarm-history { |
| description |
| "This feature indicates that the server maintains a history |
| of state changes for each alarm. For example, if an alarm |
| toggles between cleared and active 10 times, these state |
| changes are present in a separate list in the alarm. |
| |
| Keeping the alarm history may have an impact on server |
| memory resources."; |
| } |
| |
| feature alarm-summary { |
| description |
| "This feature indicates that the server summarizes the number |
| of alarms per severity and operator state."; |
| } |
| |
| feature alarm-profile { |
| description |
| "The system enables clients to configure further information |
| to each alarm type."; |
| } |
| |
| feature severity-assignment { |
| description |
| "The system supports configurable alarm severity levels."; |
| reference |
| "ITU-T Recommendation M.3100: |
| Generic network information model |
| ITU-T Recommendation M.3160: |
| Generic, protocol-neutral management information model"; |
| } |
| |
| feature root-cause-analysis { |
| description |
| "The system supports identifying candidate root-cause |
| resources for an alarm, for example, a disk partition |
| root cause for a logger failure alarm."; |
| } |
| |
| feature service-impact-analysis { |
| description |
| "The system supports identifying candidate-impacted |
| resources for an alarm, for example, an interface state change |
| resulting in a link alarm, which can refer to a link as being |
| impacted."; |
| } |
| |
| feature alarm-correlation { |
| description |
| "The system supports correlating/grouping alarms |
| that belong together."; |
| } |
| |
| /* |
| * Identities |
| */ |
| |
| identity alarm-type-id { |
| description |
| "Base identity for alarm types. A unique identification of |
| the alarm, not including the resource. Different resources |
| can share alarm types. If the resource reports the same |
| alarm type, it is considered to be the same alarm. The alarm |
| type is a simplification of the different X.733 and 3GPP Alarm |
| IRP correlation mechanisms, and it allows for |
| hierarchical extensions. |
| |
| A string-based qualifier can be used in addition to the |
| identity in order to have different alarm types based on |
| information not known at design time, such as values in |
| textual SNMP Notification varbinds. |
| |
| Standards and vendors can define sub-identities to clearly |
| identify specific alarm types. |
| |
| This identity is abstract and MUST NOT be used for alarms."; |
| } |
| |
| /* |
| * Common types |
| */ |
| |
| typedef resource { |
| type union { |
| type instance-identifier { |
| require-instance false; |
| } |
| type yang:object-identifier; |
| type string; |
| type yang:uuid; |
| } |
| description |
| "This is an identification of the alarming resource, such as an |
| interface. It should be as fine-grained as possible to both |
| guide the operator and guarantee uniqueness of the alarms. |
| |
| If the alarming resource is modeled in YANG, this type will |
| be an instance-identifier. |
| |
| If the resource is an SNMP object, the type will be an |
| 'object-identifier'. |
| |
| If the resource is anything else, for example, a distinguished |
| name or a Common Information Model (CIM) path, this type will |
| be a string. |
| |
| If the alarming object is identified by a Universally Unique |
| Identifier (UUID), use the uuid type. Be cautious when using |
| this type, since a UUID is hard to use for an operator. |
| |
| If the server supports several models, the precedence should |
| be in the order as given in the union definition."; |
| } |
| |
| typedef resource-match { |
| type union { |
| type yang:xpath1.0; |
| type yang:object-identifier; |
| type string; |
| } |
| description |
| "This type is used to match resources of type 'resource'. |
| Since the type 'resource' is a union of different types, the |
| 'resource-match' type is also a union of corresponding types. |
| |
| If the type is given as an XPath 1.0 expression, a resource |
| of type 'instance-identifier' matches if the instance is part |
| of the node set that is the result of evaluating the XPath 1.0 |
| expression. For example, the XPath 1.0 expression: |
| |
| /ietf-interfaces:interfaces/ietf-interfaces:interface |
| [ietf-interfaces:type='ianaift:ethernetCsmacd'] |
| |
| would match the resource instance-identifier: |
| |
| /if:interfaces/if:interface[if:name='eth1'], |
| |
| assuming that the interface 'eth1' is of type |
| 'ianaift:ethernetCsmacd'. |
| |
| If the type is given as an object identifier, a resource of |
| type 'object-identifier' matches if the match object |
| identifier is a prefix of the resource's object identifier. |
| For example, the value: |
| |
| 1.3.6.1.2.1.2.2 |
| |
| would match the resource object identifier: |
| |
| 1.3.6.1.2.1.2.2.1.1.5 |
| |
| If the type is given as an UUID or a string, it is interpreted |
| as an XML Schema regular expression, which matches a resource |
| of type 'yang:uuid' or 'string' if the given regular |
| expression matches the resource string. |
| |
| If the type is given as an XPath expression, it is evaluated |
| in the following XPath context: |
| |
| o The set of namespace declarations is the set of prefix |
| and namespace pairs for all YANG modules implemented by |
| the server, where the prefix is the YANG module name and |
| the namespace is as defined by the 'namespace' statement |
| in the YANG module. |
| |
| If a leaf of this type is encoded in XML, all namespace |
| declarations in scope on the leaf element are added to |
| the set of namespace declarations. If a prefix found in |
| the XML is already present in the set of namespace |
| declarations, the namespace in the XML is used. |
| |
| o The set of variable bindings is empty. |
| |
| o The function library is the core function library, and |
| the functions are defined in Section 10 of RFC 7950. |
| |
| o The context node is the root node in the data tree."; |
| reference |
| "XML Schema Part 2: Datatypes Second Edition, |
| World Wide Web Consortium Recommendation |
| REC-xmlschema-2-20041028"; |
| } |
| |
| typedef alarm-text { |
| type string; |
| description |
| "The string used to inform operators about the alarm. This |
| MUST contain enough information for an operator to be able to |
| understand the problem and how to resolve it. If this string |
| contains structure, this format should be clearly documented |
| for programs to be able to parse that information."; |
| } |
| |
| typedef severity { |
| type enumeration { |
| enum indeterminate { |
| value 2; |
| description |
| "Indicates that the severity level could not be |
| determined. This level SHOULD be avoided."; |
| } |
| enum warning { |
| value 3; |
| description |
| "The 'warning' severity level indicates the detection of a |
| potential or impending service-affecting fault, before any |
| significant effects have been felt. Action should be |
| taken to further diagnose (if necessary) and correct the |
| problem in order to prevent it from becoming a more |
| serious service-affecting fault."; |
| } |
| enum minor { |
| value 4; |
| description |
| "The 'minor' severity level indicates the existence of a |
| non-service-affecting fault condition and that corrective |
| action should be taken in order to prevent a more serious |
| (for example, service-affecting) fault. Such a severity |
| can be reported, for example, when the detected alarm |
| condition is not currently degrading the capacity of the |
| resource."; |
| } |
| enum major { |
| value 5; |
| description |
| "The 'major' severity level indicates that a service- |
| affecting condition has developed and an urgent corrective |
| action is required. Such a severity can be reported, for |
| example, when there is a severe degradation in the |
| capability of the resource and its full capability must be |
| restored."; |
| } |
| enum critical { |
| value 6; |
| description |
| "The 'critical' severity level indicates that a service- |
| affecting condition has occurred and an immediate |
| corrective action is required. Such a severity can be |
| reported, for example, when a resource becomes totally out |
| of service and its capability must be restored."; |
| } |
| } |
| description |
| "The severity level of the alarm. Note well that the value |
| 'clear' is not included. Whether or not an alarm is cleared |
| is a separate boolean flag."; |
| reference |
| "ITU-T Recommendation X.733: Information Technology |
| - Open Systems Interconnection |
| - System Management: Alarm Reporting Function"; |
| } |
| |
| typedef severity-with-clear { |
| type union { |
| type enumeration { |
| enum cleared { |
| value 1; |
| description |
| "The alarm is cleared by the instrumentation."; |
| } |
| } |
| type severity; |
| } |
| description |
| "The severity level of the alarm including clear. This is used |
| only in notifications reporting state changes for an alarm."; |
| } |
| |
| typedef writable-operator-state { |
| type enumeration { |
| enum none { |
| value 1; |
| description |
| "The alarm is not being taken care of."; |
| } |
| enum ack { |
| value 2; |
| description |
| "The alarm is being taken care of. Corrective action not |
| taken yet or has failed"; |
| } |
| enum closed { |
| value 3; |
| description |
| "Corrective action taken successfully."; |
| } |
| } |
| description |
| "Operator states on an alarm. The 'closed' state indicates |
| that an operator considers the alarm being resolved. This is |
| separate from the alarm's 'is-cleared' leaf."; |
| } |
| |
| typedef operator-state { |
| type union { |
| type writable-operator-state; |
| type enumeration { |
| enum shelved { |
| value 4; |
| description |
| "The alarm is shelved. Alarms in /alarms/shelved-alarms/ |
| MUST be assigned this operator state by the server as |
| the last entry in the 'operator-state-change' list. The |
| text for that entry SHOULD include the shelf name."; |
| } |
| enum un-shelved { |
| value 5; |
| description |
| "The alarm is moved back to 'alarm-list' from a shelf. |
| Alarms that are moved from /alarms/shelved-alarms/ to |
| /alarms/alarm-list MUST be assigned this state by the |
| server as the last entry in the 'operator-state-change' |
| list. The text for that entry SHOULD include the shelf |
| name."; |
| } |
| } |
| } |
| description |
| "Operator states on an alarm. The 'closed' state indicates |
| that an operator considers the alarm being resolved. This is |
| separate from the alarm's 'is-cleared' leaf."; |
| } |
| |
| /* Alarm type */ |
| |
| typedef alarm-type-id { |
| type identityref { |
| base alarm-type-id; |
| } |
| description |
| "Identifies an alarm type. The description of the alarm type |
| id MUST indicate whether or not the alarm type is abstract. |
| An abstract alarm type is used as a base for other alarm type |
| ids and will not be used as a value for an alarm or be present |
| in the alarm inventory."; |
| } |
| |
| typedef alarm-type-qualifier { |
| type string; |
| description |
| "If an alarm type cannot be fully specified at design time by |
| 'alarm-type-id', this string qualifier is used in addition to |
| fully define a unique alarm type. |
| |
| The definition of alarm qualifiers is considered to be part of |
| the instrumentation and is out of scope for this module. An |
| empty string is used when this is part of a key."; |
| } |
| |
| /* |
| * Groupings |
| */ |
| |
| grouping common-alarm-parameters { |
| description |
| "Common parameters for an alarm. |
| |
| This grouping is used both in the alarm list and in the |
| notification representing an alarm-state change."; |
| leaf resource { |
| type resource; |
| mandatory true; |
| description |
| "The alarming resource. See also 'alt-resource'. This could |
| be, for example, a reference to the alarming interface"; |
| } |
| leaf alarm-type-id { |
| type alarm-type-id; |
| mandatory true; |
| description |
| "This leaf and the leaf 'alarm-type-qualifier' together |
| provide a unique identification of the alarm type."; |
| } |
| leaf alarm-type-qualifier { |
| type alarm-type-qualifier; |
| description |
| "This leaf is used when the 'alarm-type-id' leaf cannot |
| uniquely identify the alarm type. Normally, this is not the |
| case, and this leaf is the empty string."; |
| } |
| leaf-list alt-resource { |
| type resource; |
| description |
| "Used if the alarming resource is available over other |
| interfaces. This field can contain SNMP OIDs, CIM paths, or |
| 3GPP distinguished names, for example."; |
| } |
| list related-alarm { |
| if-feature "alarm-correlation"; |
| key "resource alarm-type-id alarm-type-qualifier"; |
| description |
| "References to related alarms. Note that the related alarm |
| might have been purged from the alarm list."; |
| leaf resource { |
| type leafref { |
| path "/alarms/alarm-list/alarm/resource"; |
| require-instance false; |
| } |
| description |
| "The alarming resource for the related alarm."; |
| } |
| leaf alarm-type-id { |
| type leafref { |
| path "/alarms/alarm-list/alarm" |
| + "[resource=current()/../resource]" |
| + "/alarm-type-id"; |
| require-instance false; |
| } |
| description |
| "The alarm type identifier for the related alarm."; |
| } |
| leaf alarm-type-qualifier { |
| type leafref { |
| path "/alarms/alarm-list/alarm" |
| + "[resource=current()/../resource]" |
| + "[alarm-type-id=current()/../alarm-type-id]" |
| + "/alarm-type-qualifier"; |
| require-instance false; |
| } |
| description |
| "The alarm qualifier for the related alarm."; |
| } |
| } |
| leaf-list impacted-resource { |
| if-feature "service-impact-analysis"; |
| type resource; |
| description |
| "Resources that might be affected by this alarm. If the |
| system creates an alarm on a resource and also has a mapping |
| to other resources that might be impacted, these resources |
| can be listed in this leaf-list. In this way, the system |
| can create one alarm instead of several. For example, if an |
| interface has an alarm, the 'impacted-resource' can |
| reference the aggregated port channels."; |
| } |
| leaf-list root-cause-resource { |
| if-feature "root-cause-analysis"; |
| type resource; |
| description |
| "Resources that are candidates for causing the alarm. If the |
| system has a mechanism to understand the candidate root |
| causes of an alarm, this leaf-list can be used to list the |
| root-cause candidate resources. In this way, the system can |
| create one alarm instead of several. An example might be a |
| logging system (alarm resource) that fails; the alarm can |
| reference the file system in the 'root-cause-resource' |
| leaf-list. Note that the intended use is not to also send |
| an alarm with the 'root-cause-resource' as an alarming |
| resource. The 'root-cause-resource' leaf-list is a hint and |
| should not also generate an alarm for the same problem."; |
| } |
| } |
| |
| grouping alarm-state-change-parameters { |
| description |
| "Parameters for an alarm-state change. |
| |
| This grouping is used both in the alarm list's status-change |
| list and in the notification representing an alarm-state |
| change."; |
| leaf time { |
| type yang:date-and-time; |
| mandatory true; |
| description |
| "The time the status of the alarm changed. The value |
| represents the time the real alarm-state change appeared in |
| the resource and not when it was added to the alarm |
| list. The /alarm-list/alarm/last-changed MUST be set to the |
| same value."; |
| } |
| leaf perceived-severity { |
| type severity-with-clear; |
| mandatory true; |
| description |
| "The severity of the alarm as defined by X.733. Note that |
| this may not be the original severity since the alarm may |
| have changed severity."; |
| reference |
| "ITU-T Recommendation X.733: Information Technology |
| - Open Systems Interconnection |
| - System Management: Alarm Reporting Function"; |
| } |
| leaf alarm-text { |
| type alarm-text; |
| mandatory true; |
| description |
| "A user-friendly text describing the alarm-state change."; |
| reference |
| "ITU-T Recommendation X.733: Information Technology |
| - Open Systems Interconnection |
| - System Management: Alarm Reporting Function"; |
| } |
| } |
| |
| grouping operator-parameters { |
| description |
| "This grouping defines parameters that can be changed by an |
| operator."; |
| leaf time { |
| type yang:date-and-time; |
| mandatory true; |
| description |
| "Timestamp for operator action on the alarm."; |
| } |
| leaf operator { |
| type string; |
| mandatory true; |
| description |
| "The name of the operator that has acted on this alarm."; |
| } |
| leaf state { |
| type operator-state; |
| mandatory true; |
| description |
| "The operator's view of the alarm state."; |
| } |
| leaf text { |
| type string; |
| description |
| "Additional optional textual information provided by the |
| operator."; |
| } |
| } |
| |
| grouping resource-alarm-parameters { |
| description |
| "Alarm parameters that originate from the resource view."; |
| leaf is-cleared { |
| type boolean; |
| mandatory true; |
| description |
| "Indicates the current clearance state of the alarm. An |
| alarm might toggle from active alarm to cleared alarm and |
| back to active again."; |
| } |
| leaf last-raised { |
| type yang:date-and-time; |
| mandatory true; |
| description |
| "An alarm may change severity level and toggle between |
| active and cleared during its lifetime. This leaf indicates |
| the last time it was raised ('is-cleared' = 'false')."; |
| } |
| leaf last-changed { |
| type yang:date-and-time; |
| mandatory true; |
| description |
| "A timestamp when the 'status-change' or |
| 'operator-state-change' list was last changed."; |
| } |
| leaf perceived-severity { |
| type severity; |
| mandatory true; |
| description |
| "The last severity of the alarm. |
| |
| If an alarm was raised with severity 'warning' but later |
| changed to 'major', this leaf will show 'major'."; |
| } |
| leaf alarm-text { |
| type alarm-text; |
| mandatory true; |
| description |
| "The last reported alarm text. This text should contain |
| information for an operator to be able to understand the |
| problem and how to resolve it."; |
| } |
| list status-change { |
| if-feature "alarm-history"; |
| key "time"; |
| min-elements 1; |
| description |
| "A list of status-change events for this alarm. |
| |
| The entry with latest timestamp in this list MUST |
| correspond to the leafs 'is-cleared', 'perceived-severity', |
| and 'alarm-text' for the alarm. |
| |
| This list is ordered according to the timestamps of alarm |
| state changes. The first item corresponds to the latest |
| state change. |
| |
| The following state changes create an entry in this |
| list: |
| - changed severity (warning, minor, major, critical) |
| - clearance status; this also updates the 'is-cleared' |
| leaf |
| - alarm-text update"; |
| uses alarm-state-change-parameters; |
| } |
| } |
| |
| grouping filter-input { |
| description |
| "Grouping to specify a filter construct on alarm information."; |
| leaf alarm-clearance-status { |
| type enumeration { |
| enum any { |
| description |
| "Ignore alarm-clearance status."; |
| } |
| enum cleared { |
| description |
| "Filter cleared alarms."; |
| } |
| enum not-cleared { |
| description |
| "Filter not-cleared alarms."; |
| } |
| } |
| mandatory true; |
| description |
| "The clearance status of the alarm."; |
| } |
| container older-than { |
| presence "Age specification"; |
| description |
| "Matches the 'last-status-change' leaf in the alarm."; |
| choice age-spec { |
| description |
| "Filter using date and time age."; |
| case seconds { |
| leaf seconds { |
| type uint16; |
| description |
| "Age expressed in seconds."; |
| } |
| } |
| case minutes { |
| leaf minutes { |
| type uint16; |
| description |
| "Age expressed in minutes."; |
| } |
| } |
| case hours { |
| leaf hours { |
| type uint16; |
| description |
| "Age expressed in hours."; |
| } |
| } |
| case days { |
| leaf days { |
| type uint16; |
| description |
| "Age expressed in days."; |
| } |
| } |
| case weeks { |
| leaf weeks { |
| type uint16; |
| description |
| "Age expressed in weeks."; |
| } |
| } |
| } |
| } |
| container severity { |
| presence "Severity filter"; |
| choice sev-spec { |
| description |
| "Filter based on severity level."; |
| leaf below { |
| type severity; |
| description |
| "Severity less than this leaf."; |
| } |
| leaf is { |
| type severity; |
| description |
| "Severity level equal to this leaf."; |
| } |
| leaf above { |
| type severity; |
| description |
| "Severity level higher than this leaf."; |
| } |
| } |
| description |
| "Filter based on severity."; |
| } |
| container operator-state-filter { |
| if-feature "operator-actions"; |
| presence "Operator state filter"; |
| leaf state { |
| type operator-state; |
| description |
| "Filter on operator state."; |
| } |
| leaf user { |
| type string; |
| description |
| "Filter based on which operator."; |
| } |
| description |
| "Filter based on operator state."; |
| } |
| } |
| |
| /* |
| * The /alarms data tree |
| */ |
| |
| container alarms { |
| description |
| "The top container for this module."; |
| container control { |
| description |
| "Configuration to control the alarm behavior."; |
| leaf max-alarm-status-changes { |
| type union { |
| type uint16; |
| type enumeration { |
| enum infinite { |
| description |
| "The status-change entries are accumulated |
| infinitely."; |
| } |
| } |
| } |
| default "32"; |
| description |
| "The 'status-change' entries are kept in a circular list |
| per alarm. When this number is exceeded, the oldest |
| status change entry is automatically removed. If the |
| value is 'infinite', the status-change entries are |
| accumulated infinitely."; |
| } |
| leaf notify-status-changes { |
| type enumeration { |
| enum all-state-changes { |
| description |
| "Send notifications for all status changes."; |
| } |
| enum raise-and-clear { |
| description |
| "Send notifications only for raise, clear, and |
| re-raise. Notifications for severity-level changes or |
| alarm-text changes are not sent."; |
| } |
| enum severity-level { |
| description |
| "Only send notifications for alarm-state changes |
| crossing the level specified in |
| 'notify-severity-level'. Always send clear |
| notifications."; |
| } |
| } |
| must '. != "severity-level" or ../notify-severity-level' { |
| description |
| "When notify-status-changes is 'severity-level', a value |
| must be given for 'notify-severity-level'."; |
| } |
| default "all-state-changes"; |
| description |
| "This leaf controls the notifications sent for alarm status |
| updates. There are three options: |
| |
| 1. Notifications are sent for all updates, severity-level |
| changes, and alarm-text changes. |
| |
| 2. Notifications are only sent for alarm raise and clear. |
| |
| 3. Notifications are sent for status changes equal to or |
| above the specified severity level. Clear |
| notifications shall always be sent. Notifications |
| shall also be sent for state changes that make an |
| alarm less severe than the specified level. |
| |
| For example, in option 3, assume that the severity level |
| is set to major and that the alarm has the following state |
| changes: |
| |
| [(Time, severity, clear)]: |
| [(T1, major, -), (T2, minor, -), (T3, warning, -), |
| (T4, minor, -), (T5, major, -), (T6, critical, -), |
| (T7, major. -), (T8, major, clear)] |
| |
| In that case, notifications will be sent at times |
| T1, T2, T5, T6, T7, and T8."; |
| } |
| leaf notify-severity-level { |
| when '../notify-status-changes = "severity-level"'; |
| type severity; |
| description |
| "Only send notifications for alarm-state changes crossing |
| the specified level. Always send clear notifications."; |
| } |
| container alarm-shelving { |
| if-feature "alarm-shelving"; |
| description |
| "The 'alarm-shelving/shelf' list is used to shelve |
| (block/filter) alarms. The conditions in the shelf |
| criteria are logically ANDed. The first matching shelf is |
| used, and an alarm is shelved only for this first match. |
| Matching alarms MUST appear in the |
| /alarms/shelved-alarms/shelved-alarm list, and |
| non-matching /alarms MUST appear in the |
| /alarms/alarm-list/alarm list. The server does not send |
| any notifications for shelved alarms. |
| |
| The server MUST maintain states (e.g., severity |
| changes) for the shelved alarms. |
| |
| Alarms that match the criteria shall have an |
| operator state 'shelved'. When the shelf |
| configuration removes an alarm from the shelf, the server |
| shall add the operator state 'un-shelved'."; |
| list shelf { |
| key "name"; |
| ordered-by user; |
| leaf name { |
| type string; |
| description |
| "An arbitrary name for the alarm shelf."; |
| } |
| description |
| "Each entry defines the criteria for shelving alarms. |
| Criteria are ANDed. If no criteria are specified, |
| all alarms will be shelved."; |
| leaf-list resource { |
| type resource-match; |
| description |
| "Shelve alarms for matching resources."; |
| } |
| list alarm-type { |
| key "alarm-type-id alarm-type-qualifier-match"; |
| description |
| "Any alarm matching the combined criteria of |
| 'alarm-type-id' and 'alarm-type-qualifier-match' |
| MUST be matched."; |
| leaf alarm-type-id { |
| type alarm-type-id; |
| description |
| "Shelve all alarms that have an 'alarm-type-id' that |
| is equal to or derived from the given |
| 'alarm-type-id'."; |
| } |
| leaf alarm-type-qualifier-match { |
| type string; |
| description |
| "An XML Schema regular expression that is used to |
| match an alarm type qualifier. Shelve all alarms |
| that match this regular expression for the alarm |
| type qualifier."; |
| reference |
| "XML Schema Part 2: Datatypes Second Edition, |
| World Wide Web Consortium Recommendation |
| REC-xmlschema-2-20041028"; |
| } |
| } |
| leaf description { |
| type string; |
| description |
| "An optional textual description of the shelf. This |
| description should include the reason for shelving |
| these alarms."; |
| } |
| } |
| } |
| } |
| container alarm-inventory { |
| config false; |
| description |
| "The 'alarm-inventory/alarm-type' list contains all possible |
| alarm types for the system. |
| |
| If the system knows for which resources a specific alarm |
| type can appear, it is also identified in the inventory. |
| The list also tells if each alarm type has a corresponding |
| clear state. The inventory shall only contain concrete |
| alarm types. |
| |
| The alarm inventory MUST be updated by the system when new |
| alarms can appear. This can be the case when installing new |
| software modules or inserting new card types. A |
| notification 'alarm-inventory-changed' is sent when the |
| inventory is changed."; |
| list alarm-type { |
| key "alarm-type-id alarm-type-qualifier"; |
| description |
| "An entry in this list defines a possible alarm."; |
| leaf alarm-type-id { |
| type alarm-type-id; |
| description |
| "The statically defined alarm type identifier for this |
| possible alarm."; |
| } |
| leaf alarm-type-qualifier { |
| type alarm-type-qualifier; |
| description |
| "The optionally dynamically defined alarm type identifier |
| for this possible alarm."; |
| } |
| leaf-list resource { |
| type resource-match; |
| description |
| "Optionally, specifies for which resources the alarm type |
| is valid."; |
| } |
| leaf will-clear { |
| type boolean; |
| mandatory true; |
| description |
| "This leaf tells the operator if the alarm will be |
| cleared when the correct corrective action has been |
| taken. Implementations SHOULD strive for detecting the |
| cleared state for all alarm types. |
| |
| If this leaf is 'true', the operator can monitor the |
| alarm until it becomes cleared after the corrective |
| action has been taken. |
| |
| If this leaf is 'false', the operator needs to validate |
| that the alarm is no longer active using other |
| mechanisms. Alarms can lack a corresponding clear due |
| to missing instrumentation or no logical |
| corresponding clear state."; |
| } |
| leaf-list severity-level { |
| type severity; |
| description |
| "This leaf-list indicates the possible severity levels of |
| this alarm type. Note well that 'clear' is not part of |
| the severity type. In general, the severity level |
| should be defined by the instrumentation based on the |
| dynamic state, rather than being defined statically by |
| the alarm type, in order to provide a relevant severity |
| level based on dynamic state and context. However, most |
| alarm types have a defined set of possible severity |
| levels, and this should be provided here."; |
| } |
| leaf description { |
| type string; |
| mandatory true; |
| description |
| "A description of the possible alarm. It SHOULD include |
| information on possible underlying root causes and |
| corrective actions."; |
| } |
| } |
| } |
| container summary { |
| if-feature "alarm-summary"; |
| config false; |
| description |
| "This container gives a summary of the number of alarms."; |
| list alarm-summary { |
| key "severity"; |
| description |
| "A global summary of all alarms in the system. The summary |
| does not include shelved alarms."; |
| leaf severity { |
| type severity; |
| description |
| "Alarm summary for this severity level."; |
| } |
| leaf total { |
| type yang:gauge32; |
| description |
| "Total number of alarms of this severity level."; |
| } |
| leaf not-cleared { |
| type yang:gauge32; |
| description |
| "Total number of alarms of this severity level |
| that are not cleared."; |
| } |
| leaf cleared { |
| type yang:gauge32; |
| description |
| "For this severity level, the number of alarms that are |
| cleared."; |
| } |
| leaf cleared-not-closed { |
| if-feature "operator-actions"; |
| type yang:gauge32; |
| description |
| "For this severity level, the number of alarms that are |
| cleared but not closed."; |
| } |
| leaf cleared-closed { |
| if-feature "operator-actions"; |
| type yang:gauge32; |
| description |
| "For this severity level, the number of alarms that are |
| cleared and closed."; |
| } |
| leaf not-cleared-closed { |
| if-feature "operator-actions"; |
| type yang:gauge32; |
| description |
| "For this severity level, the number of alarms that are |
| not cleared but closed."; |
| } |
| leaf not-cleared-not-closed { |
| if-feature "operator-actions"; |
| type yang:gauge32; |
| description |
| "For this severity level, the number of alarms that are |
| not cleared and not closed."; |
| } |
| } |
| leaf shelves-active { |
| if-feature "alarm-shelving"; |
| type empty; |
| description |
| "This is a hint to the operator that there are active |
| alarm shelves. This leaf MUST exist if the |
| /alarms/shelved-alarms/number-of-shelved-alarms is > 0."; |
| } |
| } |
| container alarm-list { |
| config false; |
| description |
| "The alarms in the system."; |
| leaf number-of-alarms { |
| type yang:gauge32; |
| description |
| "This object shows the total number of |
| alarms in the system, i.e., the total number |
| of entries in the alarm list."; |
| } |
| leaf last-changed { |
| type yang:date-and-time; |
| description |
| "A timestamp when the alarm list was last |
| changed. The value can be used by a manager to |
| initiate an alarm resynchronization procedure."; |
| } |
| list alarm { |
| key "resource alarm-type-id alarm-type-qualifier"; |
| description |
| "The list of alarms. Each entry in the list holds one |
| alarm for a given alarm type and resource. An alarm can |
| be updated from the underlying resource or by the user. |
| The following leafs are maintained by the resource: |
| 'is-cleared', 'last-change', 'perceived-severity', and |
| 'alarm-text'. An operator can change 'operator-state' and |
| 'operator-text'. |
| |
| Entries appear in the alarm list the first time an alarm |
| becomes active for a given alarm type and resource. |
| Entries do not get deleted when the alarm is cleared. |
| Clear status is represented as a boolean flag. |
| |
| Alarm entries are removed, i.e., purged, from the list by |
| an explicit purge action. For example, purge all alarms |
| that are cleared and in closed operator state that are |
| older than 24 hours. Purged alarms are removed from the |
| alarm list. If the alarm resource state changes after a |
| purge, the alarm will reappear in the alarm list. |
| |
| Systems may also remove alarms based on locally configured |
| policies; this is out of scope for this module."; |
| uses common-alarm-parameters; |
| leaf time-created { |
| type yang:date-and-time; |
| mandatory true; |
| description |
| "The timestamp when this alarm entry was created. This |
| represents the first time the alarm appeared; it can |
| also represent that the alarm reappeared after a purge. |
| Further state changes of the same alarm do not change |
| this leaf; these changes will update the 'last-changed' |
| leaf."; |
| } |
| uses resource-alarm-parameters; |
| list operator-state-change { |
| if-feature "operator-actions"; |
| key "time"; |
| description |
| "This list is used by operators to indicate the state of |
| human intervention on an alarm. For example, if an |
| operator has seen an alarm, the operator can add a new |
| item to this list indicating that the alarm is |
| acknowledged."; |
| uses operator-parameters; |
| } |
| action set-operator-state { |
| if-feature "operator-actions"; |
| description |
| "This is a means for the operator to indicate the level |
| of human intervention on an alarm."; |
| input { |
| leaf state { |
| type writable-operator-state; |
| mandatory true; |
| description |
| "Set this operator state."; |
| } |
| leaf text { |
| type string; |
| description |
| "Additional optional textual information."; |
| } |
| } |
| } |
| notification operator-action { |
| if-feature "operator-actions"; |
| description |
| "This notification is used to report that an operator |
| acted upon an alarm."; |
| uses operator-parameters; |
| } |
| } |
| action purge-alarms { |
| description |
| "This operation requests that the server delete entries |
| from the alarm list according to the supplied criteria. |
| |
| Typically, this operation is used to delete alarms that |
| are in closed operator state and older than a specified |
| time. |
| |
| The number of purged alarms is returned as an output |
| parameter."; |
| input { |
| uses filter-input; |
| } |
| output { |
| leaf purged-alarms { |
| type uint32; |
| description |
| "Number of purged alarms."; |
| } |
| } |
| } |
| action compress-alarms { |
| if-feature "alarm-history"; |
| description |
| "This operation requests that the server compress |
| entries in the alarm list by removing all but the |
| latest 'status-change' entry for all matching alarms. |
| Conditions in the input are logically ANDed. If no |
| input condition is given, all alarms are compressed."; |
| input { |
| leaf resource { |
| type resource-match; |
| description |
| "Compress the alarms matching this resource."; |
| } |
| leaf alarm-type-id { |
| type leafref { |
| path "/alarms/alarm-list/alarm/alarm-type-id"; |
| require-instance false; |
| } |
| description |
| "Compress alarms with this 'alarm-type-id'."; |
| } |
| leaf alarm-type-qualifier { |
| type leafref { |
| path "/alarms/alarm-list/alarm/alarm-type-qualifier"; |
| require-instance false; |
| } |
| description |
| "Compress the alarms with this |
| 'alarm-type-qualifier'."; |
| } |
| } |
| output { |
| leaf compressed-alarms { |
| type uint32; |
| description |
| "Number of compressed alarm entries."; |
| } |
| } |
| } |
| } |
| container shelved-alarms { |
| if-feature "alarm-shelving"; |
| config false; |
| description |
| "The shelved alarms. Alarms appear here if they match the |
| criteria in /alarms/control/alarm-shelving. This list does |
| not generate any notifications. The list represents alarms |
| that are considered not relevant by the operator. Alarms in |
| this list have an 'operator-state' of 'shelved'. This |
| cannot be changed."; |
| leaf number-of-shelved-alarms { |
| type yang:gauge32; |
| description |
| "This object shows the total number of current |
| alarms, i.e., the total number of entries |
| in the alarm list."; |
| } |
| leaf shelved-alarms-last-changed { |
| type yang:date-and-time; |
| description |
| "A timestamp when the shelved-alarm list was last changed. |
| The value can be used by a manager to initiate an alarm |
| resynchronization procedure."; |
| } |
| list shelved-alarm { |
| key "resource alarm-type-id alarm-type-qualifier"; |
| description |
| "The list of shelved alarms. Shelved alarms can only be |
| updated from the underlying resource; no operator actions |
| are supported."; |
| uses common-alarm-parameters; |
| leaf shelf-name { |
| type leafref { |
| path "/alarms/control/alarm-shelving/shelf/name"; |
| require-instance false; |
| } |
| description |
| "The name of the shelf."; |
| } |
| uses resource-alarm-parameters; |
| list operator-state-change { |
| if-feature "operator-actions"; |
| key "time"; |
| description |
| "This list is used by operators to indicate the state of |
| human intervention on an alarm. For shelved alarms, the |
| system has set the list item in the list to 'shelved'."; |
| uses operator-parameters; |
| } |
| } |
| action purge-shelved-alarms { |
| description |
| "This operation requests that the server delete entries from |
| the shelved-alarm list according to the supplied criteria. |
| In the shelved-alarm list, it makes sense to delete alarms |
| that are not relevant anymore. |
| |
| The number of purged alarms is returned as an output |
| parameter."; |
| input { |
| uses filter-input; |
| } |
| output { |
| leaf purged-alarms { |
| type uint32; |
| description |
| "Number of purged alarms."; |
| } |
| } |
| } |
| action compress-shelved-alarms { |
| if-feature "alarm-history"; |
| description |
| "This operation requests that the server compress entries |
| in the shelved-alarm list by removing all but the latest |
| 'status-change' entry for all matching shelved alarms. |
| Conditions in the input are logically ANDed. If no input |
| condition is given, all alarms are compressed."; |
| input { |
| leaf resource { |
| type leafref { |
| path "/alarms/shelved-alarms/shelved-alarm/resource"; |
| require-instance false; |
| } |
| description |
| "Compress the alarms with this resource."; |
| } |
| leaf alarm-type-id { |
| type leafref { |
| path "/alarms/shelved-alarms/shelved-alarm" |
| + "/alarm-type-id"; |
| require-instance false; |
| } |
| description |
| "Compress alarms with this 'alarm-type-id'."; |
| } |
| leaf alarm-type-qualifier { |
| type leafref { |
| path "/alarms/shelved-alarms/shelved-alarm" |
| + "/alarm-type-qualifier"; |
| require-instance false; |
| } |
| description |
| "Compress the alarms with this |
| 'alarm-type-qualifier'."; |
| } |
| } |
| output { |
| leaf compressed-alarms { |
| type uint32; |
| description |
| "Number of compressed alarm entries."; |
| } |
| } |
| } |
| } |
| list alarm-profile { |
| if-feature "alarm-profile"; |
| key "alarm-type-id alarm-type-qualifier-match resource"; |
| ordered-by user; |
| description |
| "This list is used to assign further information or |
| configuration for each alarm type. This module supports a |
| mechanism where the client can override the system-default |
| alarm severity levels. The 'alarm-profile' is also a useful |
| augmentation point for specific additions to alarm types."; |
| leaf alarm-type-id { |
| type alarm-type-id; |
| description |
| "The alarm type identifier to match."; |
| } |
| leaf alarm-type-qualifier-match { |
| type string; |
| description |
| "An XML Schema regular expression that is used to match the |
| alarm type qualifier."; |
| reference |
| "XML Schema Part 2: Datatypes Second Edition, |
| World Wide Web Consortium Recommendation |
| REC-xmlschema-2-20041028"; |
| } |
| leaf resource { |
| type resource-match; |
| description |
| "Specifies which resources to match."; |
| } |
| leaf description { |
| type string; |
| mandatory true; |
| description |
| "A description of the alarm profile."; |
| } |
| container alarm-severity-assignment-profile { |
| if-feature "severity-assignment"; |
| description |
| "The client can override the system-default severity |
| level."; |
| reference |
| "ITU-T Recommendation M.3100: |
| Generic network information model |
| ITU-T Recommendation M.3160: |
| Generic, protocol-neutral management information model"; |
| leaf-list severity-level { |
| type severity; |
| ordered-by user; |
| description |
| "Specifies the configured severity level(s) for the |
| matching alarm. If the alarm has several severity |
| levels, the leaf-list shall be given in rising severity |
| order. The original M3100/M3160 ASAP function only |
| allows for a one-to-one mapping between alarm type and |
| severity, but since YANG module supports stateful |
| alarms, the mapping must allow for several severity |
| levels. |
| |
| Assume a high-utilization alarm type with two thresholds |
| with the system-default severity levels of threshold1 = |
| warning and threshold2 = minor. Setting this leaf-list |
| to (minor, major) will assign the severity levels as |
| threshold1 = minor and threshold2 = major"; |
| } |
| } |
| } |
| } |
| |
| /* |
| * Notifications |
| */ |
| |
| notification alarm-notification { |
| description |
| "This notification is used to report a state change for an |
| alarm. The same notification is used for reporting a newly |
| raised alarm, a cleared alarm, or changing the text and/or |
| severity of an existing alarm."; |
| uses common-alarm-parameters; |
| uses alarm-state-change-parameters; |
| } |
| |
| notification alarm-inventory-changed { |
| description |
| "This notification is used to report that the list of possible |
| alarms has changed. This can happen when, for example, a new |
| software module is installed or a new physical card is |
| inserted."; |
| } |
| } |