idnits 2.17.1 draft-wwx-netmod-event-yang-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 16 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 423 has weird spacing: '...nterval uin...' == Line 742 has weird spacing: '...ld here may c...' -- The document date (October 31, 2019) is 1638 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC8342' is mentioned on line 148, but not defined == Missing Reference: 'RFC3877' is mentioned on line 171, but not defined == Missing Reference: 'RFC8340' is mentioned on line 360, but not defined == Missing Reference: 'RFC8040' is mentioned on line 1067, but not defined == Missing Reference: 'RFC5246' is mentioned on line 1071, but not defined ** Obsolete undefined reference: RFC 5246 (Obsoleted by RFC 8446) == Missing Reference: 'GNCA' is mentioned on line 1134, but not defined == Unused Reference: 'RFC2981' is defined on line 1162, but no explicit reference was found in the text == Unused Reference: 'RFC6370' is defined on line 1188, but no explicit reference was found in the text == Unused Reference: 'RFC7950' is defined on line 1198, but no explicit reference was found in the text == Unused Reference: 'RFC7952' is defined on line 1202, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Downref: Normative reference to an Informational RFC: RFC 8328 Summary: 4 errors (**), 0 flaws (~~), 13 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group M. Wang 3 Internet-Draft Q. Wu 4 Intended status: Standards Track Huawei 5 Expires: May 3, 2020 C. Xie 6 China Telecom 7 I. Bryskin 8 Individual 9 X. Liu 10 Volta Networks 11 A. Clemm 12 Futurewei 13 H. Birkholz 14 Fraunhofer SIT 15 T. Zhou 16 Huawei 17 October 31, 2019 19 A YANG Data model for ECA Policy Management 20 draft-wwx-netmod-event-yang-04 22 Abstract 24 RFC8328 defines a policy-based management framework that allow 25 definition of a data model to be used to represent high-level, 26 possibly network-wide policies. Policy discussed in RFC8328 are 27 classified into imperative policy and declarative policy, ECA policy 28 is an typical example of imperative policy. This document defines an 29 YANG data model for the ECA policy management. The ECA policy YANG 30 provides the ability for the network management function (within a 31 controller, an orchestrator, or a network element) to control the 32 configuration and monitor state change on the network element and 33 take simple and instant action when a trigger condition on the system 34 state is met. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on May 3, 2020. 53 Copyright Notice 55 Copyright (c) 2019 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 71 2. Conventions used in this document . . . . . . . . . . . . . . 4 72 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 73 2.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 4 74 3. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 75 4. Relationship to YANG Push . . . . . . . . . . . . . . . . . . 5 76 5. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 6 77 6. EVENT TRIGGER YANG Module . . . . . . . . . . . . . . . . . . 12 78 7. EVENT YANG Module . . . . . . . . . . . . . . . . . . . . . . 17 79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 80 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 81 10. Acknowledges . . . . . . . . . . . . . . . . . . . . . . . . 24 82 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 25 83 12. Normative References . . . . . . . . . . . . . . . . . . . . 25 84 Appendix A. Usage Example of ECA model Working with YANG PUSH . 26 85 Appendix B. Usage Example of Reusing Trigger-Grouping . . . . . 29 86 Appendix C. Changes between Revisions . . . . . . . . . . . . . 30 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 89 1. Introduction 91 Network management consists of using one or multiple device-, 92 technology-, service specific policies to influence management 93 behavior within the system and make sure policies are enforced or 94 executed correctly. 96 [RFC8328] defines a policy-based management framework that allow 97 definition of a data model to be used to represent high-level, 98 possibly network-wide policies. Policies discussed in [RFC8328] are 99 classified into imperative policy and declarative policy. 100 Declarative policy specifies the goals to be achieved but not how to 101 achieve those goals while imperative policy specifies when Events are 102 triggered and what actions must be performed on the occurrence of an 103 event. ECA policy is a typical example of imperative policy. 105 Event-driven management of states of managed objects across a wide 106 range of devices can be used to monitor state changes of managed 107 objects or resource and automatic trigger of rules in response to 108 events so as to better service assurance for customers and to provide 109 rapid autonomic response that can exhibit self-management properties 110 including self-configuration, self-healing, self-optimization, and 111 self-protection. Following are some of the use-cases where such ECA 112 Policy can be used: 114 o To filter out of objects underneath a requested a subtree, the 115 subscriber may use YANG Push smart filter to request the network 116 server to monitor specific network management data objects and 117 send updates only when the value falls within a certain range. 119 o To filter out of objects underneath a requested a subtree, the 120 subscriber may use YANG Push smart filter to request the network 121 server to monitor specific network management data objects and 122 send updates only when the value exceeds a certain threshold for 123 the first time but not again until the threshold is cleared. 125 o To provide rapid autonomic response that can exhibit self- 126 management properties, the management system delegate event 127 response behaviors (e.g., auto-recover from network failure) to 128 the network device so that the network can react to network change 129 as quickly as the event is detected. The event response behaviors 130 delegation can be done using ECA policy,e.g., to preconfigure 131 protection/ restoration capability on the network device. 133 o To perform troubleshoot failures (i.e., fault verification and 134 localization) and provide root cause analysis, the management 135 system monitoring specific network management data objects may 136 request the network device to export state information of a set of 137 managed data objects when the value of monitored data object 138 exceeds a certain threshold. 140 This document defines a ECA Policy management YANG data model. The 141 ECA Policy YANG provides the ability for the network management 142 function (within a controller, an orchestrator, or a network element) 143 to control the configurations and monitor state parameters on the 144 network element and take simple and instant action when a trigger 145 condition on the system state is met. 147 The data model in this document is designed to be compliant with the 148 Network Management Datastore Architecture (NMDA) [RFC8342]. 150 2. Conventions used in this document 152 2.1. Terminology 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in [RFC2119]. In this 157 document, these words will appear with that interpretation only when 158 in ALL CAPS. Lower case uses of these words are not to be 159 interpreted as carrying [RFC2119] significance. 161 This document uses the following terms: 163 Error A deviation of a system from normal operation [RFC3877]. 165 Fault Lasting error or warning condition [RFC3877]. 167 Event Something that happens which may be of interest or trigger the 168 invocation of the rule. A fault, an alarm, a change in network 169 state, network security threat, hardware malfunction, buffer 170 untilization crossing a threshold, network connection setup, an 171 external input to the system, for example [RFC3877]. 173 2.2. Tree Diagrams 175 Tree diagrams used in this document follow the notation defined in 176 [RFC8340]. 178 3. Objectives 180 This section describes some of the design objectives for the ECA 181 Policy management Data Model: 183 o Clear and precise identification of Event types in the ECA Policy. 185 o Clear and precise identification of managed object in the ECA 186 Policy. 188 o Allow nested ECA policy,e.g, one event to be able to call another 189 nested event. 191 o Allow the NETCONF server send updates only when the value falls 192 within a certain range. 194 o Allow the NETCONF server send updates only when the value exceeds 195 a certain threshold for the first time but not again until the 196 threshold is cleared. 198 o Provide rapid autonomic response in the network device that can 199 exhibit self-management properties including self-configuration, 200 self-healing, self-optimization, and self-protection. 202 4. Relationship to YANG Push 204 YANG-push mechanism provides a subscription service for updates from 205 a datastore. And it supports two types of subscriptions which are 206 distinguished by how updates are triggered: periodic and on-change. 208 The On-change Push allow receivers to receive updates whenever 209 changes to target managed objects occur. This document specifies a 210 mechanism that provides three trigger conditions: 212 o Existence: When a specific managed object appears,disappear or 213 object change, the trigger fires, e.g. reserved ports are 214 configured. 216 o Boolean: The user can set the type of boolean operator (e.g. 217 unequal, equal, less, less-or-equal, greater, greater-or-equal, 218 etc) and preconfigured threshold value (e.g. Pre-configured 219 threshold). If the value of a managed object meet Boolean 220 conditions, the trigger fires, e.g., when the boolean operator 221 type is 'less', the trigger will be fired if the value of managed 222 object is less than the pre-configured Boolean value. 224 o Threshold: The user can set the rising threshold,the falling 225 threshold, the delta rising threshold, the delta falling 226 threshold. A threshold test regularly compares the value of the 227 monitored object with the threshold values, e.g., an event is 228 triggered if the value of the monitored object is greater than or 229 equal to the rising threshold or an event is triggered if the 230 difference between the current measurement value and the previous 231 measurement value is smaller than or equal to the delta falling 232 threshold. 234 In these three trigger conditions, existence with type set to object 235 change is similar to on Push change. 237 In addtion, the model defined in this document provides a method for 238 closed loop network management automation which allows automatic 239 trigger of rules in response to events so as to better service 240 assurance for customers and to provide rapid autonomic response that 241 can exhibit self-management properties including self-configuration, 242 self-healing, self-optimization, and self-protection. The details of 243 the usage example is described in Appendix A. 245 5. Model Overview 247 The YANG data model for the ECA Policy management has been split into 248 two modules: 250 o The ietf-event-trigger.yang module defines a set of groupings for 251 a generic trigger. It is intended that these groupings will be 252 used by the policy based event management model or other models 253 that require the trigger conditions. In this model, three trigger 254 conditions are defined under the "test" choice node: 256 * Existence: An existence test monitors and manages the absence, 257 presence, and change of a data object, for example, interface 258 status. When a monitored object is specified, the system reads 259 the value of the monitored object regularly. 261 + If the test type is Absent, the system triggers a network 262 event and takes the specified action when the monitored 263 object disappears. 265 + If the test type is Present, the system triggers a network 266 event and takes the specified action when the monitored 267 object appears. 269 + If the test type is Changed, the system triggers a network 270 event and takes the specified action when the value of the 271 monitored object changes. 273 * Boolean: A Boolean test compares the value of the monitored 274 object with the reference value and takes action according to 275 the comparison result. The comparison types include unequal, 276 equal, less, lessorequal, greater, and greaterorequal. For 277 example, if the comparison type is equal, an event is triggered 278 when the value of the monitored object equals the reference 279 value. The event will not be triggered again until the value 280 becomes unequal and comes back to equal. 282 * Threshold: A Threshold trigger condition regularly compares 283 compares the value of the monitored object with the threshold 284 values. 286 + A rising network event is triggered if the value of the 287 monitored object is greater than or equal to the rising 288 threshold. 290 + A falling network event is triggered if the value of the 291 monitored object is smaller than or equal to the falling 292 threshold. 294 + A rising network event is triggered if the difference 295 between the current measurement value and the previous 296 measurement value is greater than or equal to the delta 297 rising threshold. 299 + A falling network event is triggered if the difference 300 between the current measurement value and the previous 301 measurement value is smaller than or equal to the delta 302 falling threshold. 304 + A falling network event is triggered if the values of the 305 monitored object, the rising threshold, and the falling 306 threshold are the same. 308 + A falling network event is triggered if the delta rising 309 threshold, the delta falling threshold, and the difference 310 between the current sampled value and the previous sampled 311 value is the same. 313 If the value of the monitored object crosses a threshold 314 multiple times in succession, the managed device triggers a 315 network event only for the first crossing. 317 Editor-note: Three trigger conditions defined this document align 318 with Complex condition and Simple condition defined in RFC3460? 319 Are they sufficient to model ECA condition? 321 o The ietf-event.yang module defines four lists: trigger, target, 322 event, and action. Triggers define the targets meeting some 323 conditions that lead to events. Events trigger corresponding 324 actions: 326 * Each trigger can be seen as a logical test that, if satisfied 327 or evaluated to be true, cause the action to be carried out. 328 The ietf-event.yang module uses groupings defined in ietf- 329 event-trigger.yang to present the trigger attributes. 331 * The target list defines managed objects that can be added to 332 logging or be set to a new value on the trigger, the trigger 333 test type, or the event that resulted in the actions. The 334 target is also refered to as policy variable defined in 335 [RFC3460]. 337 * The event list defines what happens when an event is triggered, 338 i.e., trigger the corresponding action, e.g., addding a logging 339 ( i.e. Recording the triggered event), setting a value to the 340 managed object or both. The group-id can be used to group a 341 set of event that can be executed together,e.g., deliver a 342 service or provide service assurance. 344 * Nested-event are supported by allowing one event's trigger to 345 reference other event's definitions using the call-event 346 configuration. Called events apply their triggers and actions 347 before returning to the calling event's trigger and resuming 348 evaluation. If the called event is triggered, then it returns 349 an effective boolean true value to the calling event. For the 350 calling event, this is equivalent to a condition statement 351 evaluating to a true value and evaluation of the event 352 continues. 354 * The action list consists of updates or invocations on local 355 managed object attributes and defines a set of actions which 356 will be performed (e.g. logging, set value, etc) when the 357 corresponding event is triggered. The value to be set can use 358 many variations on rule structure. 360 The following tree diagrams [RFC8340] provide an overview of the data 361 model for "ietf-event-trigger" module and the "ietf-event" module. 363 module: ietf-event-trigger 364 grouping existences-trigger 365 +-- existences 366 +-- test-type? enumeration 367 +-- target* target 368 grouping boolean-trigger 369 +-- boolean 370 +-- operator? operator 371 +-- value? match-value 372 +-- target* target 373 grouping threshold-trigger 374 +-- threshold 375 +-- rising-value? match-value 376 +-- rising-target* target 377 +-- falling-value? match-value 378 +-- falling-target* target 379 +-- delta-rising-value? match-value 380 +-- delta-rising-target* target 381 +-- delta-falling-value? match-value 382 +-- delta-falling-target* target 383 +-- startup? enumeration 384 grouping trigger-grouping 385 +-- (test)? 386 +--:(existences) 387 | +-- existences 388 | +-- test-type? enumeration 389 | +-- target* target 390 +--:(boolean) 391 | +-- boolean 392 | +-- operator? operator 393 | +-- value? match-value 394 | +-- target* target 395 +--:(threshold) 396 +-- threshold 397 +-- rising-value? match-value 398 +-- rising-target* target 399 +-- falling-value? match-value 400 +-- falling-target* target 401 +-- delta-rising-value? match-value 402 +-- delta-rising-target* target 403 +-- delta-falling-value? match-value 404 +-- delta-falling-target* target 405 +-- startup? enumeration 407 module: ietf-event 408 +--rw events 409 +--rw event* [event-name type] 410 +--rw event-name string 411 +--rw type identityref 412 +--rw event-description? string 413 +--rw group-id? group-type 414 +--rw target* trig:target 415 +--rw clear? boolean 416 +--rw trigger* [name] 417 | +--rw name string 418 | +--rw trigger-description? string 419 | +--rw call-event? -> ../../event-name 420 | +--rw frequency 421 | | +--rw type? identityref 422 | | +--rw periodic 423 | | | +--rw interval uint32 424 | | | +--rw start? yang:date-and-time 425 | | | +--rw end? yang:date-and-time 426 | | +--rw scheduling 427 | | +--rw month* string 428 | | +--rw day-of-month* uint8 429 | | +--rw day-of-week* uint8 430 | | +--rw hour* uint8 431 | | +--rw minute* uint8 432 | | +--rw second* uint8 433 | | +--rw start? yang:date-and-time 434 | | +--rw end? yang:date-and-time 435 | +--rw (test)? 436 | +--:(existences) 437 | | +--rw existences 438 | | +--rw target* target 439 | +--:(boolean) 440 | | +--rw boolean 441 | | +--rw operator? operator 442 | | +--rw value? match-value 443 | | +--rw target* target 444 | +--:(threshold) 445 | +--rw threshold 446 | +--rw rising-value? match-value 447 | +--rw rising-target* target 448 | +--rw falling-value? match-value 449 | +--rw falling-target* target 450 | +--rw delta-rising-value? match-value 451 | +--rw delta-rising-target* target 452 | +--rw delta-falling-value? match-value 453 | +--rw delta-falling-target* target 454 | +--rw startup? enumeration 455 +--rw actions 456 +--rw action* [name] 457 +--rw name string 458 +--rw set 459 | +--rw target? trig:target 460 | +--rw value? 461 +--rw logging 462 +--rw type? logging-type 464 The relation between Event, Trigger, Target and Action is described 465 as follows: 467 Project 468 +-------------------------------+ 469 | Event | 470 | +-------+ | 471 | |Target | | 472 | +---|---+ | +-------------------------------+ 473 | | | | Event | 474 | +----V---+ +--------+ | | +-------+ | 475 | |Trigger |------->| Action |-------->|Target | | 476 | +--------+ +--------+ | | +---|---+ | 477 +-------------------------------+ | | | 478 | +----|---+ +--------+ | 479 | |Trigger |------- | Action | | 480 | +--------+ +----+---+ | 481 +------------------------+------+ 482 | 483 +-----------------+ 484 +------+------------------------+ 485 | Event| | 486 | +---V---+ | 487 | |Target | | 488 | +---|---+ | 489 | | | 490 | +----|---+ +--------+ | 491 | |Trigger |------- | Action | | 492 | +--------+ +---+----+ | 493 +-----------------------+-------+ 494 +----------------+ 495 +------+------------------------+ 496 | Event| | 497 | +---V---+ | 498 | |Target | | 499 | +---|---+ | 500 | | | 501 | +----|---+ +--------+ | 502 | |Trigger |------- | Action | | 503 | +--------+ +--------+ | 504 +-------------------------------+ 506 One event may trigger another event,i.e., the action output in the 507 first event can be input to target in the second event and a set of 508 events can be grouped together and executed in a coordinated manner, 509 but if it does not trigger another event, the relation between two 510 events should be ignored. 512 6. EVENT TRIGGER YANG Module 514 file "ietf-event-trigger@2019-10-28.yang" 515 module ietf-event-trigger { 516 yang-version 1.1; 517 namespace "urn:ietf:params:xml:ns:yang:ietf-event-trigger"; 518 prefix trig; 520 import ietf-yang-types { 521 prefix yang; 522 } 523 organization 524 "IETF xxx Working Group"; 525 contact 526 "Zitao Wang: wangzitao@huawei.com 527 Qin Wu: bill.wu@huawei.com"; 528 description 529 "This module defines a reusable grouping for event trigger."; 531 revision 2019-10-28 { 532 description 533 "Initial revision."; 534 reference 535 "foo"; 536 } 538 typedef match-value { 539 type union { 540 type yang:xpath1.0; 541 type yang:object-identifier; 542 type string; 543 } 544 description 545 "This type is used to match resources of type 'target'. 546 Since the type 'target' is a union of different types, 547 the 'match-value' type is also a union of corresponding 548 types."; 549 } 551 typedef target { 552 type union { 553 type instance-identifier; 554 type yang:object-identifier; 555 type yang:uuid; 556 type string; 557 } 558 description 559 "If the target is modelled in YANG, this type will 560 be an instance-identifier. 561 If the target is an SNMP object, the type will be an 562 object-identifier. 563 If the target is anything else, for example a distinguished 564 name or a CIM path, this type will be a string. 565 If the target is identified by a UUID use the uuid 566 type. 567 If the server supports several models, the presedence should 568 be in the order as given in the union definition."; 569 } 571 typedef operator { 572 type enumeration { 573 enum unequal { 574 description 575 "Indicates that the comparision type is unequal to."; 576 } 577 enum equal { 578 description 579 "Indicates that the comparision type is equal to."; 580 } 581 enum less { 582 description 583 "Indicates that the comparision type is less than."; 584 } 585 enum less-or-equal { 586 description 587 "Indicates that the comparision type is less than 588 or equal to."; 589 } 590 enum greater { 591 description 592 "Indicates that the comparision type is greater than."; 593 } 594 enum greater-or-equal { 595 description 596 "Indicates that the comparision type is greater than 597 or equal to."; 598 } 599 } 600 description 601 "definition of the operator"; 602 } 604 grouping existences-trigger { 605 description 606 "A grouping that provides existence trigger"; 607 container existences { 608 leaf test-type { 609 type enumeration { 610 enum absent { 611 description 612 "If the test type is Absent, the system triggers an event 613 and takes the specified action when the monitored object disappears."; 614 } 615 enum present { 616 description 617 "If the test type is Present, the system triggers an event 618 and takes the specified action when the monitored object appears."; 619 } 620 enum changed { 621 description 622 "If the test type is Changed, the system triggers an alarm event and takes 623 the specified action when the value of the monitored object changes."; 624 } 625 } 626 description "test type."; 627 } 628 leaf-list target { 629 type target; 630 description 631 "List for target objects"; 632 } 633 description 634 "Container for existence"; 635 } 636 } 638 grouping boolean-trigger { 639 description 640 "A grouping that provides boolean trigger"; 641 container boolean { 642 leaf operator { 643 type operator; 644 description 645 "Comparison type."; 646 } 647 leaf value { 648 type match-value; 649 description 650 "Compartion value which is static threshold value."; 651 } 652 leaf-list target { 653 type target; 654 description 655 "List for target management objects."; 657 } 658 description 659 "Container for boolean test."; 660 } 661 } 663 grouping threshold-trigger { 664 description 665 "A grouping that provides threshold trigger"; 666 container threshold { 667 leaf rising-value { 668 type match-value; 669 description 670 "Sets the rising threshold to the specified value, 671 when the current sampled value is greater than or equal to 672 this threshold, and the value at the last sampling interval 673 was less than this threshold, the event is triggered. "; 674 } 675 leaf-list rising-target { 676 type target; 677 description 678 "List for target objects."; 679 } 680 leaf falling-value { 681 type match-value; 682 description 683 "Sets the falling threshold to the specified value."; 684 } 685 leaf-list falling-target { 686 type target; 687 description 688 "List for target objects."; 689 } 690 leaf delta-rising-value { 691 type match-value; 692 description 693 "Sets the delta rising threshold to the specified value."; 694 } 695 leaf-list delta-rising-target { 696 type target; 697 description 698 "List for target objects."; 699 } 700 leaf delta-falling-value { 701 type match-value; 702 description 703 "Sets the delta falling threshold to the specified value."; 704 } 705 leaf-list delta-falling-target { 706 type target; 707 description 708 "List for target objects."; 709 } 710 leaf startup { 711 type enumeration { 712 enum rising { 713 description 714 "If the first sample after this 715 managed object becomes active is greater than or equal 716 to 'rising-value' and the 'startup' is equal to 717 'rising' then one threshold rising event is 718 triggered for that managed object."; 719 } 720 enum falling { 721 description 722 "If the first sample after this managed object becomes 723 active is less than or equal to 'falling-value' and 724 the 'startup' is equal to 'falling' then one 725 threshold falling event is triggered for that managed 726 object."; 727 } 728 enum rising-or-falling { 729 description 730 "That event may be triggered when the 731 'startup' is equal to 'rising-or-falling'. 732 'rising-or-falling' indicate the state value of the 733 managed object may less than or greater than the 734 specified thrshold value."; 735 } 736 } 737 description 738 "Startup setting."; 739 } 740 description 741 "Container for the threshold trigger condition. 742 Note that the threshold here may change over time 743 or the state value changes in either ascend order 744 or descend order."; 745 } 746 } 748 grouping trigger-grouping { 749 description 750 "A grouping that provides event trigger."; 751 choice test { 752 description 753 "Choice test"; 754 case existences { 755 uses existences-trigger; 756 } 757 case boolean { 758 uses boolean-trigger; 759 } 760 case threshold { 761 uses threshold-trigger; 762 } 763 } 764 } 765 } 766 768 7. EVENT YANG Module 770 file "ietf-event@2019-10-28.yang" 772 module ietf-event { 773 yang-version 1.1; 774 namespace "urn:ietf:params:xml:ns:yang:ietf-event"; 775 prefix evt; 777 import ietf-yang-types { 778 prefix yang; 779 } 780 import ietf-event-trigger { 781 prefix trig; 782 } 784 organization 785 "IETF xxx Working Group"; 786 contact 787 "Zitao Wang: wangzitao@huawei.com 788 Qin Wu: bill.wu@huawei.com"; 789 description 790 "This module defines a model for the service topology."; 792 revision 2019-10-28 { 793 description 794 "Initial revision."; 795 reference 796 "foo"; 797 } 799 identity event-type { 800 description 801 "Base identity for event type"; 802 } 804 identity frequency { 805 description 806 "Base identity for frequency"; 807 } 809 identity periodic { 810 base frequency; 811 description 812 "Identity for periodic trigger"; 813 } 815 identity scheduling { 816 base frequency; 817 description 818 "Identity for scheduling trigger"; 819 } 821 identity logging { 822 description 823 "Base identity for logging action"; 824 } 826 identity logging-notification { 827 base logging; 828 description 829 "Logging for event notification"; 830 } 832 identity logging-set { 833 base logging; 834 description 835 "Logging for reset values"; 836 } 838 typedef logging-type { 839 type identityref { 840 base logging; 841 } 842 description 843 "Logging types"; 844 } 846 typedef group-type { 847 type string; 848 description 849 "Group type"; 850 } 852 grouping start-end-grouping { 853 description 854 "A grouping that provides start and end times for 855 Event objects."; 856 leaf start { 857 type yang:date-and-time; 858 description 859 "The date and time when the Event object 860 starts to create triggers."; 861 } 862 leaf end { 863 type yang:date-and-time; 864 description 865 "The date and time when the Event object 866 stops to create triggers. 867 It is generally a good idea to always configure 868 an end time and to refresh the end time as needed 869 to ensure that agents that lose connectivity to 870 their Controller do not continue executing Schedules 871 forever."; 872 } 873 } 875 container events { 876 list event { 877 key "event-name type"; 878 leaf event-name { 879 type string; 880 description 881 "Event name"; 882 } 883 leaf type { 884 type identityref { 885 base event-type; 886 } 887 description 888 "Type of event"; 889 } 890 leaf event-description { 891 type string; 892 description 893 "Event description"; 894 } 895 leaf group-id { 896 type group-type; 897 description 898 "Group Identifier"; 899 } 900 leaf-list target { 901 type trig:target; 902 description 903 "targeted objects"; 904 } 905 leaf clear { 906 type boolean; 907 default "false"; 908 description 909 "A flag indicate whether the event be closed"; 910 } 911 list trigger { 912 key "name"; 913 leaf name { 914 type string; 915 description 916 "Trigger name"; 917 } 918 leaf trigger-description { 919 type string; 920 description 921 "Trigger description"; 922 } 923 leaf call-event { 924 type leafref { 925 path "../../event-name"; 926 } 927 description 928 "This leaf call sub-event."; 929 } 930 container frequency { 931 leaf type { 932 type identityref { 933 base frequency; 934 } 935 description 936 "Type of trigger frequency"; 937 } 938 container periodic { 939 when "derived-from-or-self(../type, 'periodic')"; 940 description 941 "A periodic timing object triggers periodically 942 according to a regular interval."; 943 leaf interval { 944 type uint32 { 945 range "1..max"; 946 } 947 units "seconds"; 948 mandatory true; 949 description 950 "The number of seconds between two triggers 951 generated by this periodic timing object."; 952 } 953 uses start-end-grouping; 954 } 955 container scheduling { 956 when "derived-from-or-self(../type, 'scheduling')"; 957 description 958 "A scheduling timing object triggers."; 959 leaf-list month { 960 type string; 961 description 962 "A set of months at which this scheduling timing 963 will trigger."; 964 } 965 leaf-list day-of-month { 966 type uint8 { 967 range "0..59"; 968 } 969 description 970 "A set of days of the month at which this 971 scheduling timing will trigger."; 972 } 973 leaf-list day-of-week { 974 type uint8 { 975 range "0..59"; 976 } 977 description 978 "A set of weekdays at which this scheduling timing 979 will trigger."; 980 } 981 leaf-list hour { 982 type uint8 { 983 range "0..59"; 984 } 985 description 986 "A set of hours at which the scheduling timing will 987 trigger."; 988 } 989 leaf-list minute { 990 type uint8 { 991 range "0..59"; 992 } 993 description 994 "A set of minutes at which this scheduling timing 995 will trigger."; 996 } 997 leaf-list second { 998 type uint8 { 999 range "0..59"; 1000 } 1001 description 1002 "A set of seconds at which this calendar timing 1003 will trigger."; 1004 } 1005 uses start-end-grouping; 1006 } 1007 description 1008 "Container for frequency"; 1009 } 1010 uses trig:trigger-grouping; 1011 description 1012 "List for trigger"; 1013 } 1014 container actions { 1015 list action { 1016 key "name"; 1017 leaf name { 1018 type string; 1019 description 1020 "Action Name"; 1021 } 1022 container set { 1023 leaf target { 1024 type trig:target; 1025 description 1026 "The target objects"; 1027 } 1028 anydata value { 1029 description 1030 "Inline set content."; 1031 } 1032 description 1033 "Set a value to the target"; 1034 } 1035 container logging { 1036 leaf type { 1037 type logging-type; 1038 description 1039 "Specifies the log action"; 1040 } 1041 description 1042 "Specifies the log action"; 1043 } 1044 description 1045 "List for actions"; 1046 } 1047 description 1048 "Container for Actions"; 1049 } 1050 description 1051 "List for Events"; 1052 } 1053 description 1054 "YANG data module for defining event triggers and actions for 1055 network management purposes"; 1056 } 1057 } 1059 1061 8. Security Considerations 1063 The YANG modules defined in this document MAY be accessed via the 1064 RESTCONF protocol [RFC8040] or NETCONF protocol ([RFC6241]). The 1065 lowest RESTCONF or NETCONF layer requires that the transport-layer 1066 protocol provides both data integrity and confidentiality, see 1067 Section 2 in [RFC8040] and [RFC6241]. The lowest NETCONF layer is 1068 the secure transport layer, and the mandatory-to-implement secure 1069 transport is Secure Shell (SSH)[RFC6242] . The lowest RESTCONF layer 1070 is HTTPS, and the mandatory-to-implement secure transport is TLS 1071 [RFC5246]. 1073 The NETCONF access control model [RFC6536] provides the means to 1074 restrict access for particular NETCONF or RESTCONF users to a 1075 preconfigured subset of all available NETCONF or RESTCONF protocol 1076 operations and content. 1078 There are a number of data nodes defined in this YANG module that are 1079 writable/creatable/deletable (i.e., config true, which is the 1080 default). These data nodes may be considered sensitive or vulnerable 1081 in some network environments. Write operations (e.g., edit-config) 1082 to these data nodes without proper protection can have a negative 1083 effect on network operations. These are the subtrees and data nodes 1084 and their sensitivity/vulnerability: 1086 o /events/event/event-name 1088 o /events/event/target 1089 o /events/actions/target 1091 o /events/event/trigger/name 1093 9. IANA Considerations 1095 This document registers two URIs in the IETF XML registry [RFC3688]. 1096 Following the format in [RFC3688], the following registrations are 1097 requested to be made: 1099 --------------------------------------------------------------------- 1100 URI: urn:ietf:params:xml:ns:yang:ietf-event-trigger 1101 Registrant Contact: The IESG. 1102 XML: N/A, the requested URI is an XML namespace. 1104 URI: urn:ietf:params:xml:ns:yang:ietf-event 1105 Registrant Contact: The IESG. 1106 XML: N/A, the requested URI is an XML namespace. 1107 --------------------------------------------------------------------- 1109 This document registers two YANG modules in the YANG Module Names 1110 registry [RFC6020]. 1112 --------------------------------------------------------------------- 1113 Name: ietf-event-trigger 1114 Namespace: urn:ietf:params:xml:ns:yang:ietf-event-trigger 1115 Prefix: trig 1116 Reference: RFC xxxx 1118 Name: ietf-event 1119 Namespace: urn:ietf:params:xml:ns:yang:ietf-event 1120 Prefix: evt 1121 Reference: RFC xxxx 1122 --------------------------------------------------------------------- 1124 10. Acknowledges 1126 This work has benefited from the discussions of ECA Policy over the 1127 years. In particular, the SUPA project [ 1128 https://datatracker.ietf.org/wg/supa/about/ ] provided approaches to 1129 express high-level, possibly network-wide policies to a network 1130 management function (within a controller, an orchestrator, or a 1131 network element). 1133 Igor Bryskin, Xufeng Liu, Alexander Clemm, Henk Birkholz, Tianran 1134 Zhou contributed to an earlier version of [GNCA]. We would like to 1135 thank the authors of that document on event response behaviors 1136 delegation for material that assisted in thinking that helped improve 1137 this document. 1139 11. Contributors 1141 Nicola Sambo 1142 Scuola Superiore Sant'Anna 1143 Via Moruzzi 1 1144 Pisa 56124 1145 Italy 1147 Email: nicola.sambo@sssup.it 1149 Giuseppe Fioccola 1150 Huawei Technologies 1151 Riesstrasse, 25 1152 Munich 80992 1153 Germany 1155 Email: giuseppe.fioccola@huawei.com 1157 12. Normative References 1159 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1160 Requirement Levels", March 1997. 1162 [RFC2981] Kavasseri, R., Ed., "Event MIB", RFC 2981, 1163 DOI 10.17487/RFC2981, October 2000, 1164 . 1166 [RFC3460] Moore, B., Ed., "Policy Core Information Model (PCIM) 1167 Extensions", RFC 3460, DOI 10.17487/RFC3460, January 2003, 1168 . 1170 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1171 DOI 10.17487/RFC3688, January 2004, 1172 . 1174 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1175 the Network Configuration Protocol (NETCONF)", RFC 6020, 1176 DOI 10.17487/RFC6020, October 2010, 1177 . 1179 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1180 and A. Bierman, Ed., "Network Configuration Protocol 1181 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1182 . 1184 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1185 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1186 . 1188 [RFC6370] Bocci, M., Swallow, G., and E. Gray, "MPLS Transport 1189 Profile (MPLS-TP) Identifiers", RFC 6370, 1190 DOI 10.17487/RFC6370, September 2011, 1191 . 1193 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1194 Protocol (NETCONF) Access Control Model", RFC 6536, 1195 DOI 10.17487/RFC6536, March 2012, 1196 . 1198 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1199 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1200 . 1202 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1203 RFC 7952, DOI 10.17487/RFC7952, August 2016, 1204 . 1206 [RFC8328] Liu, W., Xie, C., Strassner, J., Karagiannis, G., Klyus, 1207 M., Bi, J., Cheng, Y., and D. Zhang, "Policy-Based 1208 Management Framework for the Simplified Use of Policy 1209 Abstractions (SUPA)", RFC 8328, DOI 10.17487/RFC8328, 1210 March 2018, . 1212 Appendix A. Usage Example of ECA model Working with YANG PUSH 1214 The relation between Event and YANG PUSH is described as follow: YANG 1215 Push Notification may trigger one event, i.e. one trigger conditions 1216 of the Event A can be set to "receiver received a yang push 1217 notification", and it can associates with other conditions of the 1218 Event A. When these conditions are met, the event A is triggered. 1220 +-----------------------+ 1221 | yang-push | 1222 | | 1223 | +--------------+ | 1224 | | receiver | | +------------------------------+ 1225 | | | | | Event A | 1226 | +--------^-----+ | | | 1227 | | | | +-----------+ | 1228 | | +-------+| | | | | 1229 | | |notification | | target | | 1230 | | | +| | --> | | 1231 | | +-------+\\ ---- +----+------+ | 1232 | +--------+-----+ | \---| | | 1233 | | target | ---- \\ | | | 1234 | | +-- | \\ | | 1235 | +--------------+ | |\ +------V---+ +----------+| 1236 +-----------------------+ | \\| | | || 1237 | > trigger +---> action || 1238 | | | | || 1239 | +----------+ +-----+----+| 1240 | | 1241 +------------------------ -----+ 1243 For Example: 1245 The receiver received a push-change-update notification and learned 1246 that the "oper-status" of interface[name='eth0'] changed. 1248 The target of Event "interface-state-monitoring" is set to 1249 "/if:interfaces/if:interface[if:name='eth0']", the trigger list 1250 contains two conditions: 1)receiver received a push-change-update 1251 notification; 2) the value of "in-errors" of interface[name='eth0'] 1252 exceeded the pre-configured threshold. When these conditions are 1253 met, corresponding action will be performed, i.e. disable 1254 interface[name='eth0']. The XML examples are shown as below: 1256 1257 2017-10-25T08:22:33.44Z 1258 1260 89 1261 1262 1263 0 1264 1265 edit1 1266 replace 1267 /ietf-interfaces:interfaces 1268 1269 1271 1272 eth0 1273 up 1274 1275 1276 1277 1278 1279 1280 1281 1283 1284 interface-state-monitoring 1285 interface-exception 1286 /if:interfaces/if:interface[if:name='eth0'] 1287 1288 state-push-change 1289 received yang push 1290 \changed notification 1291 1292 /yp:notification/yp:push-change-update/yp:id[id=89]\ 1293 /yp:datastore-changes/.../yp:target="/ietf-interfaces:interfaces='eth0'\ 1294 " 1295 1296 1297 1298 evaluate-in-errors 1299 interface-state-chang 1300 evaluate the number of 1301 the packets that contained errors 1302 1303 10m 1304 1305 1306 greater-or-equal 1307 100 1308 /if:interfaces/if:interface[if:name='eth0']\ 1309 /if:statistic/if:in-errors 1310 1311 1312 1313 1314 /if:interfaces/if:interface[if:name='eth0'] 1315 1316 1317 1318 eth0 1319 false 1320 1321 1322 1323 1324 1325 1327 Appendix B. Usage Example of Reusing Trigger-Grouping 1329 The "ietf-event-trigger.yang" module defines a set of groupings for a 1330 generic trigger. It is intended that these groupings can be reused 1331 by other models that require the trigger conditions, for example, in 1332 some subscription and notification cases, many applications do not 1333 require every update, only updates that are of certain interest. The 1334 following example describe how to reuse the "ietf-event-trigger" 1335 module to define the subscription and notification smarter filter. 1337 import ietf-subscribed-notifications { 1338 prefix sn; 1339 } 1340 import ietf-event-trigger { 1341 prefix trig; 1342 } 1344 augment "/sn:subscriptions/sn:subscription" { 1345 description "add the smart filter container"; 1346 container smart-filter { 1347 description "It concludes filter configurations"; 1348 uses trig:trigger-grouping; 1349 } 1350 } 1352 The tree diagrams: 1354 module: ietf-smart-filter 1355 augment /sn:subscriptions/sn:subscription: 1356 +--rw smart-filter 1357 +--rw (test)? 1358 +--:(existences) 1359 | +--rw existences 1360 | +--rw target* target 1361 +--:(boolean) 1362 | +--rw boolean 1363 | +--rw operator? operator 1364 | +--rw value? match-value 1365 | +--rw target* target 1366 +--:(variation) 1367 +--rw variation 1368 +--rw rising-value? match-value 1369 +--rw rising-target* target 1370 +--rw falling-value? match-value 1371 +--rw falling-target* target 1372 +--rw delta-rising-value? match-value 1373 +--rw delta-rising-target* target 1374 +--rw delta-falling-value? match-value 1375 +--rw delta-falling-target* target 1376 +--rw startup? enumeration 1378 Appendix C. Changes between Revisions 1380 v03 - v04 1382 o Add text in introduction section to clarify the usage examples of 1383 ECA policy 1385 o Update objective section to align with use cases. 1387 o Clarify the relationship between target and policy variable. 1389 o Change variation trigger condition back into threshold trigger 1390 condition and clarify the usage of three trigger conditions. 1392 o Remove Event MIB related section. 1394 o Add new coauthors. 1396 v02 - v03 1398 o Usage Example Update: add an usage example to introduce how to 1399 reuse the ietf-event-trigger module to define the subscription- 1400 notification smarter filter. 1402 v01 - v02 1404 o Introduce the group-id which allow group a set of events that can 1405 be executed together 1407 o Change threshold trigger condition into variation trigger 1408 condition to further clarify the difference between boolean 1409 trigger condition and variation trigger condition. 1411 o Module structure optimization. 1413 o Usage Example Update. 1415 v00 - v01 1417 o Separate ietf-event-trigger.yang from Event management modeland 1418 ietf-event.yang and make it reusable in other YANG models. 1420 o Clarify the difference between boolean trigger condition and 1421 threshold trigger condition. 1423 o Change evt-smp-min and evt-smp-max into min-data-object and max- 1424 data-object in the data model. 1426 Authors' Addresses 1428 Michael Wang 1429 Huawei Technologies,Co.,Ltd 1430 101 Software Avenue, Yuhua District 1431 Nanjing 210012 1432 China 1434 Email: wangzitao@huawei.com 1436 Qin Wu 1437 Huawei 1438 101 Software Avenue, Yuhua District 1439 Nanjing, Jiangsu 210012 1440 China 1442 Email: bill.wu@huawei.com 1444 Chongfeng Xie 1445 China Telecom 1447 Email: xiechf@ctbri.com.cn 1448 Igor Bryskin 1449 Individual 1451 Email: i_bryskin@yahoo.com 1453 Xufeng Liu 1454 Volta Networks 1456 Email: xufeng.liu.ietf@gmail.com 1458 Alexander Clemm 1459 Futurewei 1461 Email: ludwig@clemm.org 1463 Henk Birkholz 1464 Fraunhofer SIT 1466 Email: henk.birkholz@sit.fraunhofer.de 1468 Tianran Zhou 1469 Huawei 1471 Email: zhoutianran@huawei.com