ntsimulator/deploy/o-ran-ru-fh/yang/ietf-alarms@2019-09-11.yang

   1 module ietf-alarms {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-alarms";
   4   prefix al;
   5
   6   import ietf-yang-types {
   7     prefix yang;
   8     reference
   9       "RFC 6991: Common YANG Data Types.";
  10   }
  11
  12   organization
  13     "IETF CCAMP Working Group";
  14   contact
  15     "WG Web:   <https://trac.ietf.org/trac/ccamp>
  16      WG List:  <mailto:ccamp@ietf.org>
  17
  18      Editor:   Stefan Vallin
  19                <mailto:stefan@wallan.se>
  20
  21      Editor:   Martin Bjorklund
  22                <mailto:mbj@tail-f.com>";
  23   description
  24     "This module defines an interface for managing alarms.  Main
  25      inputs to the module design are the 3GPP Alarm Integration
  26      Reference Point (IRP), ITU-T X.733, and ANSI/ISA-18.2 alarm
  27      standards.
  28      Main features of this module include:
  29
  30        * Alarm list:
  31                  A list of all alarms.  Cleared alarms stay in
  32                  the list until explicitly purged.
  33
  34        * Operator actions on alarms:
  35                  Acknowledging and closing alarms.
  36
  37        * Administrative actions on alarms:
  38                  Purging alarms from the list according to specific
  39                  criteria.
  40
  41        * Alarm inventory:
  42                  A management application can read all
  43                  alarm types implemented by the system.
  44
  45        * Alarm shelving:
  46                  Shelving (blocking) alarms according
  47                  to specific criteria.
  48
  49        * Alarm profiles:
  50                  A management system can attach further
  51                  information to alarm types, for example,
  52                  overriding system-default severity
  53                  levels.
  54
  55      This module uses a stateful view on alarms.  An alarm is a state
  56      for a specific resource (note that an alarm is not a
  57      notification).  An alarm type is a possible alarm state for a
  58      resource.  For example, the tuple:
  59
  60        ('link-alarm', 'GigabitEthernet0/25')
  61
  62      is an alarm of type 'link-alarm' on the resource
  63      'GigabitEthernet0/25'.
  64
  65      Alarm types are identified using YANG identities and an optional
  66      string-based qualifier.  The string-based qualifier allows for
  67      dynamic extension of the statically defined alarm types.  Alarm
  68      types identify a possible alarm state and not the individual
  69      notifications.  For example, the traditional 'link-down' and
  70      'link-up' notifications are two notifications referring to the
  71      same alarm type 'link-alarm'.
  72
  73      With this design, there is no ambiguity about how alarm and
  74      alarm clear correlation should be performed; notifications that
  75      report the same resource and alarm type are considered updates
  76      of the same alarm, e.g., clearing an active alarm or changing
  77      the severity of an alarm.  The instrumentation can update the
  78      severity and alarm text on an existing alarm.  The above alarm
  79      example can therefore look like the following:
  80
  81        (('link-alarm', 'GigabitEthernet0/25'),
  82         warning,
  83         'interface down while interface admin state is up')
  84
  85      There is a clear separation between updates on the alarm from
  86      the underlying resource, like clear, and updates from an
  87      operator, like acknowledging or closing an alarm:
  88
  89        (('link-alarm', 'GigabitEthernet0/25'),
  90         warning,
  91         'interface down while interface admin state is up',
  92         cleared,
  93         closed)
  94
  95      Administrative actions like removing closed alarms older than a
  96      given time is supported.
  97
  98      This YANG module does not define how the underlying
  99      instrumentation detects and clears the specific alarms.  That
 100      belongs to the Standards Development Organization (SDO) or
 101      enterprise that owns that specific technology.
 102
 103      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
 104      NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
 105      'MAY', and 'OPTIONAL' in this document are to be interpreted as
 106      described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
 107      they appear in all capitals, as shown here.
 108
 109      Copyright (c) 2019 IETF Trust and the persons identified as
 110      authors of the code.  All rights reserved.
 111
 112      Redistribution and use in source and binary forms, with or
 113      without modification, is permitted pursuant to, and subject to
 114      the license terms contained in, the Simplified BSD License set
 115      forth in Section 4.c of the IETF Trust's Legal Provisions
 116      Relating to IETF Documents
 117      (https://trustee.ietf.org/license-info).
 118
 119      This version of this YANG module is part of RFC 8632; see
 120      the RFC itself for full legal notices.";
 121
 122   revision 2019-09-11 {
 123     description
 124       "Initial revision.";
 125     reference
 126       "RFC 8632: A YANG Data Model for Alarm Management";
 127   }
 128
 129   /*
 130    * Features
 131    */
 132
 133   feature operator-actions {
 134     description
 135       "This feature indicates that the system supports operator
 136        states on alarms.";
 137   }
 138
 139   feature alarm-shelving {
 140     description
 141       "This feature indicates that the system supports shelving
 142        (blocking) alarms.
 143
 144        Alarm shelving may have an impact on server processing
 145        resources in order to match alarms against shelf
 146        criteria.";
 147   }
 148
 149   feature alarm-history {
 150     description
 151       "This feature indicates that the server maintains a history
 152        of state changes for each alarm.  For example, if an alarm
 153        toggles between cleared and active 10 times, these state
 154        changes are present in a separate list in the alarm.
 155
 156        Keeping the alarm history may have an impact on server
 157        memory resources.";
 158   }
 159
 160   feature alarm-summary {
 161     description
 162       "This feature indicates that the server summarizes the number
 163        of alarms per severity and operator state.";
 164   }
 165
 166   feature alarm-profile {
 167     description
 168       "The system enables clients to configure further information
 169        to each alarm type.";
 170   }
 171
 172   feature severity-assignment {
 173     description
 174       "The system supports configurable alarm severity levels.";
 175     reference
 176       "ITU-T Recommendation M.3100:
 177          Generic network information model
 178        ITU-T Recommendation M.3160:
 179          Generic, protocol-neutral management information model";
 180   }
 181
 182   feature root-cause-analysis {
 183     description
 184       "The system supports identifying candidate root-cause
 185        resources for an alarm, for example, a disk partition
 186        root cause for a logger failure alarm.";
 187   }
 188
 189   feature service-impact-analysis {
 190     description
 191       "The system supports identifying candidate-impacted
 192        resources for an alarm, for example, an interface state change
 193        resulting in a link alarm, which can refer to a link as being
 194        impacted.";
 195   }
 196
 197   feature alarm-correlation {
 198     description
 199       "The system supports correlating/grouping alarms
 200        that belong together.";
 201   }
 202
 203   /*
 204    * Identities
 205    */
 206
 207   identity alarm-type-id {
 208     description
 209       "Base identity for alarm types.  A unique identification of
 210        the alarm, not including the resource.  Different resources
 211        can share alarm types.  If the resource reports the same
 212        alarm type, it is considered to be the same alarm.  The alarm
 213        type is a simplification of the different X.733 and 3GPP Alarm
 214        IRP correlation mechanisms, and it allows for
 215        hierarchical extensions.
 216
 217        A string-based qualifier can be used in addition to the
 218        identity in order to have different alarm types based on
 219        information not known at design time, such as values in
 220        textual SNMP Notification varbinds.
 221
 222        Standards and vendors can define sub-identities to clearly
 223        identify specific alarm types.
 224
 225        This identity is abstract and MUST NOT be used for alarms.";
 226   }
 227
 228   /*
 229    * Common types
 230    */
 231
 232   typedef resource {
 233     type union {
 234       type instance-identifier {
 235         require-instance false;
 236       }
 237       type yang:object-identifier;
 238       type string;
 239       type yang:uuid;
 240     }
 241     description
 242       "This is an identification of the alarming resource, such as an
 243        interface.  It should be as fine-grained as possible to both
 244        guide the operator and guarantee uniqueness of the alarms.
 245
 246        If the alarming resource is modeled in YANG, this type will
 247        be an instance-identifier.
 248
 249        If the resource is an SNMP object, the type will be an
 250        'object-identifier'.
 251
 252        If the resource is anything else, for example, a distinguished
 253        name or a Common Information Model (CIM) path, this type will
 254        be a string.
 255
 256        If the alarming object is identified by a Universally Unique
 257        Identifier (UUID), use the uuid type.  Be cautious when using
 258        this type, since a UUID is hard to use for an operator.
 259
 260        If the server supports several models, the precedence should
 261        be in the order as given in the union definition.";
 262   }
 263
 264   typedef resource-match {
 265     type union {
 266       type yang:xpath1.0;
 267       type yang:object-identifier;
 268       type string;
 269     }
 270     description
 271       "This type is used to match resources of type 'resource'.
 272        Since the type 'resource' is a union of different types, the
 273        'resource-match' type is also a union of corresponding types.
 274
 275        If the type is given as an XPath 1.0 expression, a resource
 276        of type 'instance-identifier' matches if the instance is part
 277        of the node set that is the result of evaluating the XPath 1.0
 278        expression.  For example, the XPath 1.0 expression:
 279
 280         /ietf-interfaces:interfaces/ietf-interfaces:interface
 281             [ietf-interfaces:type='ianaift:ethernetCsmacd']
 282
 283        would match the resource instance-identifier:
 284
 285         /if:interfaces/if:interface[if:name='eth1'],
 286
 287        assuming that the interface 'eth1' is of type
 288        'ianaift:ethernetCsmacd'.
 289
 290        If the type is given as an object identifier, a resource of
 291        type 'object-identifier' matches if the match object
 292        identifier is a prefix of the resource's object identifier.
 293        For example, the value:
 294
 295         1.3.6.1.2.1.2.2
 296
 297        would match the resource object identifier:
 298
 299         1.3.6.1.2.1.2.2.1.1.5
 300
 301        If the type is given as an UUID or a string, it is interpreted
 302        as an XML Schema regular expression, which matches a resource
 303        of type 'yang:uuid' or 'string' if the given regular
 304        expression matches the resource string.
 305
 306        If the type is given as an XPath expression, it is evaluated
 307        in the following XPath context:
 308
 309          o  The set of namespace declarations is the set of prefix
 310             and namespace pairs for all YANG modules implemented by
 311             the server, where the prefix is the YANG module name and
 312             the namespace is as defined by the 'namespace' statement
 313             in the YANG module.
 314
 315             If a leaf of this type is encoded in XML, all namespace
 316             declarations in scope on the leaf element are added to
 317             the set of namespace declarations.  If a prefix found in
 318             the XML is already present in the set of namespace
 319             declarations, the namespace in the XML is used.
 320
 321          o  The set of variable bindings is empty.
 322
 323          o  The function library is the core function library, and
 324             the functions are defined in Section 10 of RFC 7950.
 325
 326          o  The context node is the root node in the data tree.";
 327     reference
 328       "XML Schema Part 2: Datatypes Second Edition,
 329          World Wide Web Consortium Recommendation
 330          REC-xmlschema-2-20041028";
 331   }
 332
 333   typedef alarm-text {
 334     type string;
 335     description
 336       "The string used to inform operators about the alarm.  This
 337        MUST contain enough information for an operator to be able to
 338        understand the problem and how to resolve it.  If this string
 339        contains structure, this format should be clearly documented
 340        for programs to be able to parse that information.";
 341   }
 342
 343   typedef severity {
 344     type enumeration {
 345       enum indeterminate {
 346         value 2;
 347         description
 348           "Indicates that the severity level could not be
 349            determined.  This level SHOULD be avoided.";
 350       }
 351       enum warning {
 352         value 3;
 353         description
 354           "The 'warning' severity level indicates the detection of a
 355            potential or impending service-affecting fault, before any
 356            significant effects have been felt.  Action should be
 357            taken to further diagnose (if necessary) and correct the
 358            problem in order to prevent it from becoming a more
 359            serious service-affecting fault.";
 360       }
 361       enum minor {
 362         value 4;
 363         description
 364           "The 'minor' severity level indicates the existence of a
 365            non-service-affecting fault condition and that corrective
 366            action should be taken in order to prevent a more serious
 367            (for example, service-affecting) fault.  Such a severity
 368            can be reported, for example, when the detected alarm
 369            condition is not currently degrading the capacity of the
 370            resource.";
 371       }
 372       enum major {
 373         value 5;
 374         description
 375           "The 'major' severity level indicates that a service-
 376            affecting condition has developed and an urgent corrective
 377            action is required.  Such a severity can be reported, for
 378            example, when there is a severe degradation in the
 379            capability of the resource and its full capability must be
 380            restored.";
 381       }
 382       enum critical {
 383         value 6;
 384         description
 385           "The 'critical' severity level indicates that a service-
 386            affecting condition has occurred and an immediate
 387            corrective action is required.  Such a severity can be
 388            reported, for example, when a resource becomes totally out
 389            of service and its capability must be restored.";
 390       }
 391     }
 392     description
 393       "The severity level of the alarm.  Note well that the value
 394        'clear' is not included.  Whether or not an alarm is cleared
 395        is a separate boolean flag.";
 396     reference
 397       "ITU-T Recommendation X.733: Information Technology
 398          - Open Systems Interconnection
 399          - System Management: Alarm Reporting Function";
 400   }
 401
 402   typedef severity-with-clear {
 403     type union {
 404       type enumeration {
 405         enum cleared {
 406           value 1;
 407           description
 408             "The alarm is cleared by the instrumentation.";
 409         }
 410       }
 411       type severity;
 412     }
 413     description
 414       "The severity level of the alarm including clear.  This is used
 415        only in notifications reporting state changes for an alarm.";
 416   }
 417
 418   typedef writable-operator-state {
 419     type enumeration {
 420       enum none {
 421         value 1;
 422         description
 423           "The alarm is not being taken care of.";
 424       }
 425       enum ack {
 426         value 2;
 427         description
 428           "The alarm is being taken care of.  Corrective action not
 429            taken yet or has failed";
 430       }
 431       enum closed {
 432         value 3;
 433         description
 434           "Corrective action taken successfully.";
 435       }
 436     }
 437     description
 438       "Operator states on an alarm.  The 'closed' state indicates
 439        that an operator considers the alarm being resolved.  This is
 440        separate from the alarm's 'is-cleared' leaf.";
 441   }
 442
 443   typedef operator-state {
 444     type union {
 445       type writable-operator-state;
 446       type enumeration {
 447         enum shelved {
 448           value 4;
 449           description
 450             "The alarm is shelved.  Alarms in /alarms/shelved-alarms/
 451              MUST be assigned this operator state by the server as
 452              the last entry in the 'operator-state-change' list.  The
 453              text for that entry SHOULD include the shelf name.";
 454         }
 455         enum un-shelved {
 456           value 5;
 457           description
 458             "The alarm is moved back to 'alarm-list' from a shelf.
 459              Alarms that are moved from /alarms/shelved-alarms/ to
 460              /alarms/alarm-list MUST be assigned this state by the
 461              server as the last entry in the 'operator-state-change'
 462              list.  The text for that entry SHOULD include the shelf
 463              name.";
 464         }
 465       }
 466     }
 467     description
 468       "Operator states on an alarm.  The 'closed' state indicates
 469        that an operator considers the alarm being resolved.  This is
 470        separate from the alarm's 'is-cleared' leaf.";
 471   }
 472
 473   /* Alarm type */
 474
 475   typedef alarm-type-id {
 476     type identityref {
 477       base alarm-type-id;
 478     }
 479     description
 480       "Identifies an alarm type.  The description of the alarm type
 481        id MUST indicate whether or not the alarm type is abstract.
 482        An abstract alarm type is used as a base for other alarm type
 483        ids and will not be used as a value for an alarm or be present
 484        in the alarm inventory.";
 485   }
 486
 487   typedef alarm-type-qualifier {
 488     type string;
 489     description
 490       "If an alarm type cannot be fully specified at design time by
 491        'alarm-type-id', this string qualifier is used in addition to
 492        fully define a unique alarm type.
 493
 494        The definition of alarm qualifiers is considered to be part of
 495        the instrumentation and is out of scope for this module.  An
 496        empty string is used when this is part of a key.";
 497   }
 498
 499   /*
 500    * Groupings
 501    */
 502
 503   grouping common-alarm-parameters {
 504     description
 505       "Common parameters for an alarm.
 506
 507        This grouping is used both in the alarm list and in the
 508        notification representing an alarm-state change.";
 509     leaf resource {
 510       type resource;
 511       mandatory true;
 512       description
 513         "The alarming resource.  See also 'alt-resource'.  This could
 514          be, for example, a reference to the alarming interface";
 515     }
 516     leaf alarm-type-id {
 517       type alarm-type-id;
 518       mandatory true;
 519       description
 520         "This leaf and the leaf 'alarm-type-qualifier' together
 521          provide a unique identification of the alarm type.";
 522     }
 523     leaf alarm-type-qualifier {
 524       type alarm-type-qualifier;
 525       description
 526         "This leaf is used when the 'alarm-type-id' leaf cannot
 527          uniquely identify the alarm type.  Normally, this is not the
 528          case, and this leaf is the empty string.";
 529     }
 530     leaf-list alt-resource {
 531       type resource;
 532       description
 533         "Used if the alarming resource is available over other
 534          interfaces.  This field can contain SNMP OIDs, CIM paths, or
 535          3GPP distinguished names, for example.";
 536     }
 537     list related-alarm {
 538       if-feature "alarm-correlation";
 539       key "resource alarm-type-id alarm-type-qualifier";
 540       description
 541         "References to related alarms.  Note that the related alarm
 542          might have been purged from the alarm list.";
 543       leaf resource {
 544         type leafref {
 545           path "/alarms/alarm-list/alarm/resource";
 546           require-instance false;
 547         }
 548         description
 549           "The alarming resource for the related alarm.";
 550       }
 551       leaf alarm-type-id {
 552         type leafref {
 553           path "/alarms/alarm-list/alarm"
 554              + "[resource=current()/../resource]"
 555              + "/alarm-type-id";
 556           require-instance false;
 557         }
 558         description
 559           "The alarm type identifier for the related alarm.";
 560       }
 561       leaf alarm-type-qualifier {
 562         type leafref {
 563           path "/alarms/alarm-list/alarm"
 564              + "[resource=current()/../resource]"
 565              + "[alarm-type-id=current()/../alarm-type-id]"
 566              + "/alarm-type-qualifier";
 567           require-instance false;
 568         }
 569         description
 570           "The alarm qualifier for the related alarm.";
 571       }
 572     }
 573     leaf-list impacted-resource {
 574       if-feature "service-impact-analysis";
 575       type resource;
 576       description
 577         "Resources that might be affected by this alarm.  If the
 578          system creates an alarm on a resource and also has a mapping
 579          to other resources that might be impacted, these resources
 580          can be listed in this leaf-list.  In this way, the system
 581          can create one alarm instead of several.  For example, if an
 582          interface has an alarm, the 'impacted-resource' can
 583          reference the aggregated port channels.";
 584     }
 585     leaf-list root-cause-resource {
 586       if-feature "root-cause-analysis";
 587       type resource;
 588       description
 589         "Resources that are candidates for causing the alarm.  If the
 590          system has a mechanism to understand the candidate root
 591          causes of an alarm, this leaf-list can be used to list the
 592          root-cause candidate resources.  In this way, the system can
 593          create one alarm instead of several.  An example might be a
 594          logging system (alarm resource) that fails; the alarm can
 595          reference the file system in the 'root-cause-resource'
 596          leaf-list.  Note that the intended use is not to also send
 597          an alarm with the 'root-cause-resource' as an alarming
 598          resource.  The 'root-cause-resource' leaf-list is a hint and
 599          should not also generate an alarm for the same problem.";
 600     }
 601   }
 602
 603   grouping alarm-state-change-parameters {
 604     description
 605       "Parameters for an alarm-state change.
 606
 607        This grouping is used both in the alarm list's status-change
 608        list and in the notification representing an alarm-state
 609        change.";
 610     leaf time {
 611       type yang:date-and-time;
 612       mandatory true;
 613       description
 614         "The time the status of the alarm changed.  The value
 615          represents the time the real alarm-state change appeared in
 616          the resource and not when it was added to the alarm
 617          list.  The /alarm-list/alarm/last-changed MUST be set to the
 618          same value.";
 619     }
 620     leaf perceived-severity {
 621       type severity-with-clear;
 622       mandatory true;
 623       description
 624         "The severity of the alarm as defined by X.733.  Note that
 625          this may not be the original severity since the alarm may
 626          have changed severity.";
 627       reference
 628         "ITU-T Recommendation X.733: Information Technology
 629            - Open Systems Interconnection
 630            - System Management: Alarm Reporting Function";
 631     }
 632     leaf alarm-text {
 633       type alarm-text;
 634       mandatory true;
 635       description
 636         "A user-friendly text describing the alarm-state change.";
 637       reference
 638         "ITU-T Recommendation X.733: Information Technology
 639            - Open Systems Interconnection
 640            - System Management: Alarm Reporting Function";
 641     }
 642   }
 643
 644   grouping operator-parameters {
 645     description
 646       "This grouping defines parameters that can be changed by an
 647        operator.";
 648     leaf time {
 649       type yang:date-and-time;
 650       mandatory true;
 651       description
 652         "Timestamp for operator action on the alarm.";
 653     }
 654     leaf operator {
 655       type string;
 656       mandatory true;
 657       description
 658         "The name of the operator that has acted on this alarm.";
 659     }
 660     leaf state {
 661       type operator-state;
 662       mandatory true;
 663       description
 664         "The operator's view of the alarm state.";
 665     }
 666     leaf text {
 667       type string;
 668       description
 669         "Additional optional textual information provided by the
 670          operator.";
 671     }
 672   }
 673
 674   grouping resource-alarm-parameters {
 675     description
 676       "Alarm parameters that originate from the resource view.";
 677     leaf is-cleared {
 678       type boolean;
 679       mandatory true;
 680       description
 681         "Indicates the current clearance state of the alarm.  An
 682          alarm might toggle from active alarm to cleared alarm and
 683          back to active again.";
 684     }
 685     leaf last-raised {
 686       type yang:date-and-time;
 687       mandatory true;
 688       description
 689         "An alarm may change severity level and toggle between
 690          active and cleared during its lifetime.  This leaf indicates
 691          the last time it was raised ('is-cleared' = 'false').";
 692     }
 693     leaf last-changed {
 694       type yang:date-and-time;
 695       mandatory true;
 696       description
 697         "A timestamp when the 'status-change' or
 698          'operator-state-change' list was last changed.";
 699     }
 700     leaf perceived-severity {
 701       type severity;
 702       mandatory true;
 703       description
 704         "The last severity of the alarm.
 705
 706          If an alarm was raised with severity 'warning' but later
 707          changed to 'major', this leaf will show 'major'.";
 708     }
 709     leaf alarm-text {
 710       type alarm-text;
 711       mandatory true;
 712       description
 713         "The last reported alarm text.  This text should contain
 714          information for an operator to be able to understand the
 715          problem and how to resolve it.";
 716     }
 717     list status-change {
 718       if-feature "alarm-history";
 719       key "time";
 720       min-elements 1;
 721       description
 722         "A list of status-change events for this alarm.
 723
 724          The entry with latest timestamp in this list MUST
 725          correspond to the leafs 'is-cleared', 'perceived-severity',
 726          and 'alarm-text' for the alarm.
 727
 728          This list is ordered according to the timestamps of alarm
 729          state changes.  The first item corresponds to the latest
 730          state change.
 731
 732          The following state changes create an entry in this
 733          list:
 734          - changed severity (warning, minor, major, critical)
 735          - clearance status; this also updates the 'is-cleared'
 736            leaf
 737          - alarm-text update";
 738       uses alarm-state-change-parameters;
 739     }
 740   }
 741
 742   grouping filter-input {
 743     description
 744       "Grouping to specify a filter construct on alarm information.";
 745     leaf alarm-clearance-status {
 746       type enumeration {
 747         enum any {
 748           description
 749             "Ignore alarm-clearance status.";
 750         }
 751         enum cleared {
 752           description
 753             "Filter cleared alarms.";
 754         }
 755         enum not-cleared {
 756           description
 757             "Filter not-cleared alarms.";
 758         }
 759       }
 760       mandatory true;
 761       description
 762         "The clearance status of the alarm.";
 763     }
 764     container older-than {
 765       presence "Age specification";
 766       description
 767         "Matches the 'last-status-change' leaf in the alarm.";
 768       choice age-spec {
 769         description
 770           "Filter using date and time age.";
 771         case seconds {
 772           leaf seconds {
 773             type uint16;
 774             description
 775               "Age expressed in seconds.";
 776           }
 777         }
 778         case minutes {
 779           leaf minutes {
 780             type uint16;
 781             description
 782               "Age expressed in minutes.";
 783           }
 784         }
 785         case hours {
 786           leaf hours {
 787             type uint16;
 788             description
 789               "Age expressed in hours.";
 790           }
 791         }
 792         case days {
 793           leaf days {
 794             type uint16;
 795             description
 796               "Age expressed in days.";
 797           }
 798         }
 799         case weeks {
 800           leaf weeks {
 801             type uint16;
 802             description
 803               "Age expressed in weeks.";
 804           }
 805         }
 806       }
 807     }
 808     container severity {
 809       presence "Severity filter";
 810       choice sev-spec {
 811         description
 812           "Filter based on severity level.";
 813         leaf below {
 814           type severity;
 815           description
 816             "Severity less than this leaf.";
 817         }
 818         leaf is {
 819           type severity;
 820           description
 821             "Severity level equal to this leaf.";
 822         }
 823         leaf above {
 824           type severity;
 825           description
 826             "Severity level higher than this leaf.";
 827         }
 828       }
 829       description
 830         "Filter based on severity.";
 831     }
 832     container operator-state-filter {
 833       if-feature "operator-actions";
 834       presence "Operator state filter";
 835       leaf state {
 836         type operator-state;
 837         description
 838           "Filter on operator state.";
 839       }
 840       leaf user {
 841         type string;
 842         description
 843           "Filter based on which operator.";
 844       }
 845       description
 846         "Filter based on operator state.";
 847     }
 848   }
 849
 850   /*
 851    * The /alarms data tree
 852    */
 853
 854   container alarms {
 855     description
 856       "The top container for this module.";
 857     container control {
 858       description
 859         "Configuration to control the alarm behavior.";
 860       leaf max-alarm-status-changes {
 861         type union {
 862           type uint16;
 863           type enumeration {
 864             enum infinite {
 865               description
 866                 "The status-change entries are accumulated
 867                  infinitely.";
 868             }
 869           }
 870         }
 871         default "32";
 872         description
 873           "The 'status-change' entries are kept in a circular list
 874            per alarm.  When this number is exceeded, the oldest
 875            status change entry is automatically removed.  If the
 876            value is 'infinite', the status-change entries are
 877            accumulated infinitely.";
 878       }
 879       leaf notify-status-changes {
 880         type enumeration {
 881           enum all-state-changes {
 882             description
 883               "Send notifications for all status changes.";
 884           }
 885           enum raise-and-clear {
 886             description
 887               "Send notifications only for raise, clear, and
 888                re-raise.  Notifications for severity-level changes or
 889                alarm-text changes are not sent.";
 890           }
 891           enum severity-level {
 892             description
 893               "Only send notifications for alarm-state changes
 894                crossing the level specified in
 895                'notify-severity-level'.  Always send clear
 896                notifications.";
 897           }
 898         }
 899         must '. != "severity-level" or ../notify-severity-level' {
 900           description
 901             "When notify-status-changes is 'severity-level', a value
 902              must be given for 'notify-severity-level'.";
 903         }
 904         default "all-state-changes";
 905         description
 906           "This leaf controls the notifications sent for alarm status
 907            updates.  There are three options:
 908
 909            1.  Notifications are sent for all updates, severity-level
 910                changes, and alarm-text changes.
 911
 912            2.  Notifications are only sent for alarm raise and clear.
 913
 914            3.  Notifications are sent for status changes equal to or
 915                above the specified severity level.  Clear
 916                notifications shall always be sent.  Notifications
 917                shall also be sent for state changes that make an
 918                alarm less severe than the specified level.
 919
 920            For example, in option 3, assume that the severity level
 921            is set to major and that the alarm has the following state
 922            changes:
 923
 924            [(Time, severity, clear)]:
 925            [(T1, major, -), (T2, minor, -), (T3, warning, -),
 926             (T4, minor, -), (T5, major, -), (T6, critical, -),
 927             (T7, major.  -), (T8, major, clear)]
 928
 929            In that case, notifications will be sent at times
 930            T1, T2, T5, T6, T7, and T8.";
 931       }
 932       leaf notify-severity-level {
 933         when '../notify-status-changes = "severity-level"';
 934         type severity;
 935         description
 936           "Only send notifications for alarm-state changes crossing
 937            the specified level.  Always send clear notifications.";
 938       }
 939       container alarm-shelving {
 940         if-feature "alarm-shelving";
 941         description
 942           "The 'alarm-shelving/shelf' list is used to shelve
 943            (block/filter) alarms.  The conditions in the shelf
 944            criteria are logically ANDed.  The first matching shelf is
 945            used, and an alarm is shelved only for this first match.
 946            Matching alarms MUST appear in the
 947            /alarms/shelved-alarms/shelved-alarm list, and
 948            non-matching /alarms MUST appear in the
 949            /alarms/alarm-list/alarm list.  The server does not send
 950            any notifications for shelved alarms.
 951
 952            The server MUST maintain states (e.g., severity
 953            changes) for the shelved alarms.
 954
 955            Alarms that match the criteria shall have an
 956            operator state 'shelved'.  When the shelf
 957            configuration removes an alarm from the shelf, the server
 958            shall add the operator state 'un-shelved'.";
 959         list shelf {
 960           key "name";
 961           ordered-by user;
 962           leaf name {
 963             type string;
 964             description
 965               "An arbitrary name for the alarm shelf.";
 966           }
 967           description
 968             "Each entry defines the criteria for shelving alarms.
 969              Criteria are ANDed.  If no criteria are specified,
 970              all alarms will be shelved.";
 971           leaf-list resource {
 972             type resource-match;
 973             description
 974               "Shelve alarms for matching resources.";
 975           }
 976           list alarm-type {
 977             key "alarm-type-id alarm-type-qualifier-match";
 978             description
 979               "Any alarm matching the combined criteria of
 980                'alarm-type-id' and 'alarm-type-qualifier-match'
 981                MUST be matched.";
 982             leaf alarm-type-id {
 983               type alarm-type-id;
 984               description
 985                 "Shelve all alarms that have an 'alarm-type-id' that
 986                  is equal to or derived from the given
 987                  'alarm-type-id'.";
 988             }
 989             leaf alarm-type-qualifier-match {
 990               type string;
 991               description
 992                 "An XML Schema regular expression that is used to
 993                  match an alarm type qualifier.  Shelve all alarms
 994                  that match this regular expression for the alarm
 995                  type qualifier.";
 996               reference
 997                 "XML Schema Part 2: Datatypes Second Edition,
 998                    World Wide Web Consortium Recommendation
 999                    REC-xmlschema-2-20041028";
1000             }
1001           }
1002           leaf description {
1003             type string;
1004             description
1005               "An optional textual description of the shelf.  This
1006                description should include the reason for shelving
1007                these alarms.";
1008           }
1009         }
1010       }
1011     }
1012     container alarm-inventory {
1013       config false;
1014       description
1015         "The 'alarm-inventory/alarm-type' list contains all possible
1016          alarm types for the system.
1017
1018          If the system knows for which resources a specific alarm
1019          type can appear, it is also identified in the inventory.
1020          The list also tells if each alarm type has a corresponding
1021          clear state.  The inventory shall only contain concrete
1022          alarm types.
1023
1024          The alarm inventory MUST be updated by the system when new
1025          alarms can appear.  This can be the case when installing new
1026          software modules or inserting new card types.  A
1027          notification 'alarm-inventory-changed' is sent when the
1028          inventory is changed.";
1029       list alarm-type {
1030         key "alarm-type-id alarm-type-qualifier";
1031         description
1032           "An entry in this list defines a possible alarm.";
1033         leaf alarm-type-id {
1034           type alarm-type-id;
1035           description
1036             "The statically defined alarm type identifier for this
1037              possible alarm.";
1038         }
1039         leaf alarm-type-qualifier {
1040           type alarm-type-qualifier;
1041           description
1042             "The optionally dynamically defined alarm type identifier
1043              for this possible alarm.";
1044         }
1045         leaf-list resource {
1046           type resource-match;
1047           description
1048             "Optionally, specifies for which resources the alarm type
1049              is valid.";
1050         }
1051         leaf will-clear {
1052           type boolean;
1053           mandatory true;
1054           description
1055             "This leaf tells the operator if the alarm will be
1056              cleared when the correct corrective action has been
1057              taken.  Implementations SHOULD strive for detecting the
1058              cleared state for all alarm types.
1059
1060              If this leaf is 'true', the operator can monitor the
1061              alarm until it becomes cleared after the corrective
1062              action has been taken.
1063
1064              If this leaf is 'false', the operator needs to validate
1065              that the alarm is no longer active using other
1066              mechanisms.  Alarms can lack a corresponding clear due
1067              to missing instrumentation or no logical
1068              corresponding clear state.";
1069         }
1070         leaf-list severity-level {
1071           type severity;
1072           description
1073             "This leaf-list indicates the possible severity levels of
1074              this alarm type.  Note well that 'clear' is not part of
1075              the severity type.  In general, the severity level
1076              should be defined by the instrumentation based on the
1077              dynamic state, rather than being defined statically by
1078              the alarm type, in order to provide a relevant severity
1079              level based on dynamic state and context.  However, most
1080              alarm types have a defined set of possible severity
1081              levels, and this should be provided here.";
1082         }
1083         leaf description {
1084           type string;
1085           mandatory true;
1086           description
1087             "A description of the possible alarm.  It SHOULD include
1088              information on possible underlying root causes and
1089              corrective actions.";
1090         }
1091       }
1092     }
1093     container summary {
1094       if-feature "alarm-summary";
1095       config false;
1096       description
1097         "This container gives a summary of the number of alarms.";
1098       list alarm-summary {
1099         key "severity";
1100         description
1101           "A global summary of all alarms in the system.  The summary
1102            does not include shelved alarms.";
1103         leaf severity {
1104           type severity;
1105           description
1106             "Alarm summary for this severity level.";
1107         }
1108         leaf total {
1109           type yang:gauge32;
1110           description
1111             "Total number of alarms of this severity level.";
1112         }
1113         leaf not-cleared {
1114           type yang:gauge32;
1115           description
1116             "Total number of alarms of this severity level
1117              that are not cleared.";
1118         }
1119         leaf cleared {
1120           type yang:gauge32;
1121           description
1122             "For this severity level, the number of alarms that are
1123              cleared.";
1124         }
1125         leaf cleared-not-closed {
1126           if-feature "operator-actions";
1127           type yang:gauge32;
1128           description
1129             "For this severity level, the number of alarms that are
1130              cleared but not closed.";
1131         }
1132         leaf cleared-closed {
1133           if-feature "operator-actions";
1134           type yang:gauge32;
1135           description
1136             "For this severity level, the number of alarms that are
1137              cleared and closed.";
1138         }
1139         leaf not-cleared-closed {
1140           if-feature "operator-actions";
1141           type yang:gauge32;
1142           description
1143             "For this severity level, the number of alarms that are
1144              not cleared but closed.";
1145         }
1146         leaf not-cleared-not-closed {
1147           if-feature "operator-actions";
1148           type yang:gauge32;
1149           description
1150             "For this severity level, the number of alarms that are
1151              not cleared and not closed.";
1152         }
1153       }
1154       leaf shelves-active {
1155         if-feature "alarm-shelving";
1156         type empty;
1157         description
1158           "This is a hint to the operator that there are active
1159            alarm shelves.  This leaf MUST exist if the
1160            /alarms/shelved-alarms/number-of-shelved-alarms is > 0.";
1161       }
1162     }
1163     container alarm-list {
1164       config false;
1165       description
1166         "The alarms in the system.";
1167       leaf number-of-alarms {
1168         type yang:gauge32;
1169         description
1170           "This object shows the total number of
1171            alarms in the system, i.e., the total number
1172            of entries in the alarm list.";
1173       }
1174       leaf last-changed {
1175         type yang:date-and-time;
1176         description
1177           "A timestamp when the alarm list was last
1178            changed.  The value can be used by a manager to
1179            initiate an alarm resynchronization procedure.";
1180       }
1181       list alarm {
1182         key "resource alarm-type-id alarm-type-qualifier";
1183         description
1184           "The list of alarms.  Each entry in the list holds one
1185            alarm for a given alarm type and resource.  An alarm can
1186            be updated from the underlying resource or by the user.
1187            The following leafs are maintained by the resource:
1188            'is-cleared', 'last-change', 'perceived-severity', and
1189            'alarm-text'.  An operator can change 'operator-state' and
1190            'operator-text'.
1191
1192            Entries appear in the alarm list the first time an alarm
1193            becomes active for a given alarm type and resource.
1194            Entries do not get deleted when the alarm is cleared.
1195            Clear status is represented as a boolean flag.
1196
1197            Alarm entries are removed, i.e., purged, from the list by
1198            an explicit purge action.  For example, purge all alarms
1199            that are cleared and in closed operator state that are
1200            older than 24 hours.  Purged alarms are removed from the
1201            alarm list.  If the alarm resource state changes after a
1202            purge, the alarm will reappear in the alarm list.
1203
1204            Systems may also remove alarms based on locally configured
1205            policies; this is out of scope for this module.";
1206         uses common-alarm-parameters;
1207         leaf time-created {
1208           type yang:date-and-time;
1209           mandatory true;
1210           description
1211             "The timestamp when this alarm entry was created.  This
1212              represents the first time the alarm appeared; it can
1213              also represent that the alarm reappeared after a purge.
1214              Further state changes of the same alarm do not change
1215              this leaf; these changes will update the 'last-changed'
1216              leaf.";
1217         }
1218         uses resource-alarm-parameters;
1219         list operator-state-change {
1220           if-feature "operator-actions";
1221           key "time";
1222           description
1223             "This list is used by operators to indicate the state of
1224              human intervention on an alarm.  For example, if an
1225              operator has seen an alarm, the operator can add a new
1226              item to this list indicating that the alarm is
1227              acknowledged.";
1228           uses operator-parameters;
1229         }
1230         action set-operator-state {
1231           if-feature "operator-actions";
1232           description
1233             "This is a means for the operator to indicate the level
1234              of human intervention on an alarm.";
1235           input {
1236             leaf state {
1237               type writable-operator-state;
1238               mandatory true;
1239               description
1240                 "Set this operator state.";
1241             }
1242             leaf text {
1243               type string;
1244               description
1245                 "Additional optional textual information.";
1246             }
1247           }
1248         }
1249         notification operator-action {
1250           if-feature "operator-actions";
1251           description
1252             "This notification is used to report that an operator
1253              acted upon an alarm.";
1254           uses operator-parameters;
1255         }
1256       }
1257       action purge-alarms {
1258         description
1259           "This operation requests that the server delete entries
1260            from the alarm list according to the supplied criteria.
1261
1262            Typically, this operation is used to delete alarms that
1263            are in closed operator state and older than a specified
1264            time.
1265
1266            The number of purged alarms is returned as an output
1267            parameter.";
1268         input {
1269           uses filter-input;
1270         }
1271         output {
1272           leaf purged-alarms {
1273             type uint32;
1274             description
1275               "Number of purged alarms.";
1276           }
1277         }
1278       }
1279       action compress-alarms {
1280         if-feature "alarm-history";
1281         description
1282           "This operation requests that the server compress
1283            entries in the alarm list by removing all but the
1284            latest 'status-change' entry for all matching alarms.
1285            Conditions in the input are logically ANDed.  If no
1286            input condition is given, all alarms are compressed.";
1287         input {
1288           leaf resource {
1289             type resource-match;
1290             description
1291               "Compress the alarms matching this resource.";
1292           }
1293           leaf alarm-type-id {
1294             type leafref {
1295               path "/alarms/alarm-list/alarm/alarm-type-id";
1296               require-instance false;
1297             }
1298             description
1299               "Compress alarms with this 'alarm-type-id'.";
1300           }
1301           leaf alarm-type-qualifier {
1302             type leafref {
1303               path "/alarms/alarm-list/alarm/alarm-type-qualifier";
1304               require-instance false;
1305             }
1306             description
1307               "Compress the alarms with this
1308                'alarm-type-qualifier'.";
1309           }
1310         }
1311         output {
1312           leaf compressed-alarms {
1313             type uint32;
1314             description
1315               "Number of compressed alarm entries.";
1316           }
1317         }
1318       }
1319     }
1320     container shelved-alarms {
1321       if-feature "alarm-shelving";
1322       config false;
1323       description
1324         "The shelved alarms.  Alarms appear here if they match the
1325          criteria in /alarms/control/alarm-shelving.  This list does
1326          not generate any notifications.  The list represents alarms
1327          that are considered not relevant by the operator.  Alarms in
1328          this list have an 'operator-state' of 'shelved'.  This
1329          cannot be changed.";
1330       leaf number-of-shelved-alarms {
1331         type yang:gauge32;
1332         description
1333           "This object shows the total number of current
1334            alarms, i.e., the total number of entries
1335            in the alarm list.";
1336       }
1337       leaf shelved-alarms-last-changed {
1338         type yang:date-and-time;
1339         description
1340           "A timestamp when the shelved-alarm list was last changed.
1341            The value can be used by a manager to initiate an alarm
1342            resynchronization procedure.";
1343       }
1344       list shelved-alarm {
1345         key "resource alarm-type-id alarm-type-qualifier";
1346         description
1347           "The list of shelved alarms.  Shelved alarms can only be
1348            updated from the underlying resource; no operator actions
1349            are supported.";
1350         uses common-alarm-parameters;
1351         leaf shelf-name {
1352           type leafref {
1353             path "/alarms/control/alarm-shelving/shelf/name";
1354             require-instance false;
1355           }
1356           description
1357             "The name of the shelf.";
1358         }
1359         uses resource-alarm-parameters;
1360         list operator-state-change {
1361           if-feature "operator-actions";
1362           key "time";
1363           description
1364             "This list is used by operators to indicate the state of
1365              human intervention on an alarm.  For shelved alarms, the
1366              system has set the list item in the list to 'shelved'.";
1367           uses operator-parameters;
1368         }
1369       }
1370       action purge-shelved-alarms {
1371         description
1372           "This operation requests that the server delete entries from
1373            the shelved-alarm list according to the supplied criteria.
1374            In the shelved-alarm list, it makes sense to delete alarms
1375            that are not relevant anymore.
1376
1377            The number of purged alarms is returned as an output
1378            parameter.";
1379         input {
1380           uses filter-input;
1381         }
1382         output {
1383           leaf purged-alarms {
1384             type uint32;
1385             description
1386               "Number of purged alarms.";
1387           }
1388         }
1389       }
1390       action compress-shelved-alarms {
1391         if-feature "alarm-history";
1392         description
1393           "This operation requests that the server compress entries
1394            in the shelved-alarm list by removing all but the latest
1395            'status-change' entry for all matching shelved alarms.
1396            Conditions in the input are logically ANDed.  If no input
1397            condition is given, all alarms are compressed.";
1398         input {
1399           leaf resource {
1400             type leafref {
1401               path "/alarms/shelved-alarms/shelved-alarm/resource";
1402               require-instance false;
1403             }
1404             description
1405               "Compress the alarms with this resource.";
1406           }
1407           leaf alarm-type-id {
1408             type leafref {
1409               path "/alarms/shelved-alarms/shelved-alarm"
1410                  + "/alarm-type-id";
1411               require-instance false;
1412             }
1413             description
1414               "Compress alarms with this 'alarm-type-id'.";
1415           }
1416           leaf alarm-type-qualifier {
1417             type leafref {
1418               path "/alarms/shelved-alarms/shelved-alarm"
1419                  + "/alarm-type-qualifier";
1420               require-instance false;
1421             }
1422             description
1423               "Compress the alarms with this
1424                'alarm-type-qualifier'.";
1425           }
1426         }
1427         output {
1428           leaf compressed-alarms {
1429             type uint32;
1430             description
1431               "Number of compressed alarm entries.";
1432           }
1433         }
1434       }
1435     }
1436     list alarm-profile {
1437       if-feature "alarm-profile";
1438       key "alarm-type-id alarm-type-qualifier-match resource";
1439       ordered-by user;
1440       description
1441         "This list is used to assign further information or
1442          configuration for each alarm type.  This module supports a
1443          mechanism where the client can override the system-default
1444          alarm severity levels.  The 'alarm-profile' is also a useful
1445          augmentation point for specific additions to alarm types.";
1446       leaf alarm-type-id {
1447         type alarm-type-id;
1448         description
1449           "The alarm type identifier to match.";
1450       }
1451       leaf alarm-type-qualifier-match {
1452         type string;
1453         description
1454           "An XML Schema regular expression that is used to match the
1455            alarm type qualifier.";
1456         reference
1457           "XML Schema Part 2: Datatypes Second Edition,
1458              World Wide Web Consortium Recommendation
1459              REC-xmlschema-2-20041028";
1460       }
1461       leaf resource {
1462         type resource-match;
1463         description
1464           "Specifies which resources to match.";
1465       }
1466       leaf description {
1467         type string;
1468         mandatory true;
1469         description
1470           "A description of the alarm profile.";
1471       }
1472       container alarm-severity-assignment-profile {
1473         if-feature "severity-assignment";
1474         description
1475           "The client can override the system-default severity
1476            level.";
1477         reference
1478           "ITU-T Recommendation M.3100:
1479              Generic network information model
1480            ITU-T Recommendation M.3160:
1481              Generic, protocol-neutral management information model";
1482         leaf-list severity-level {
1483           type severity;
1484           ordered-by user;
1485           description
1486             "Specifies the configured severity level(s) for the
1487              matching alarm.  If the alarm has several severity
1488              levels, the leaf-list shall be given in rising severity
1489              order.  The original M3100/M3160 ASAP function only
1490              allows for a one-to-one mapping between alarm type and
1491              severity, but since YANG module supports stateful
1492              alarms, the mapping must allow for several severity
1493              levels.
1494
1495              Assume a high-utilization alarm type with two thresholds
1496              with the system-default severity levels of threshold1 =
1497              warning and threshold2 = minor.  Setting this leaf-list
1498              to (minor, major) will assign the severity levels as
1499              threshold1 = minor and threshold2 = major";
1500         }
1501       }
1502     }
1503   }
1504
1505   /*
1506    * Notifications
1507    */
1508
1509   notification alarm-notification {
1510     description
1511       "This notification is used to report a state change for an
1512        alarm.  The same notification is used for reporting a newly
1513        raised alarm, a cleared alarm, or changing the text and/or
1514        severity of an existing alarm.";
1515     uses common-alarm-parameters;
1516     uses alarm-state-change-parameters;
1517   }
1518
1519   notification alarm-inventory-changed {
1520     description
1521       "This notification is used to report that the list of possible
1522        alarms has changed.  This can happen when, for example, a new
1523        software module is installed or a new physical card is
1524        inserted.";
1525   }
1526 }