--- /dev/null
+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.";
+ }
+}
Code Review / sim / o1-interface.git / blobdiff