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