idnits 2.17.1 draft-wwx-netmod-event-yang-03.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC8328], [RFC7950]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 373 has weird spacing: '...nterval uin...' == Line 670 has weird spacing: '...ld here may c...' -- The document date (October 13, 2019) is 1655 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 89, but not defined == Missing Reference: 'RFC3877' is mentioned on line 111, but not defined == Missing Reference: 'RFC8340' is mentioned on line 313, but not defined == Missing Reference: 'RFC8040' is mentioned on line 977, but not defined == Missing Reference: 'RFC5246' is mentioned on line 981, but not defined ** Obsolete undefined reference: RFC 5246 (Obsoleted by RFC 8446) == Unused Reference: 'RFC6370' is defined on line 1062, but no explicit reference was found in the text == Unused Reference: 'RFC7952' is defined on line 1076, 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 (~~), 10 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: April 15, 2020 C. Xie 6 China Telecom 7 October 13, 2019 9 A YANG Data model for Policy based Event Management 10 draft-wwx-netmod-event-yang-03 12 Abstract 14 [RFC8328] defines a policy-based management framework that allow 15 definition of a data model to be used to represent high-level, 16 possibly network-wide policies. This document defines an YANG data 17 model for the policy based event management [RFC7950]. The policy 18 based Event YANG provides the ability for the network management 19 function (within a controller, an orchestrator, or a network element) 20 to control the configuration and monitor state change on the network 21 element and take simple and instant action when a trigger condition 22 on the system state is met. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 15, 2020. 41 Copyright Notice 43 Copyright (c) 2019 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Conventions used in this document . . . . . . . . . . . . . . 2 60 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 4. Relationship to YANG Push . . . . . . . . . . . . . . . . . . 4 64 5. Relationship to EVENT MIB . . . . . . . . . . . . . . . . . . 5 65 6. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 6 66 7. EVENT TRIGGER YANG Module . . . . . . . . . . . . . . . . . . 12 67 8. EVENT YANG Module . . . . . . . . . . . . . . . . . . . . . . 17 68 9. Security Considerations . . . . . . . . . . . . . . . . . . . 22 69 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 70 11. Normative References . . . . . . . . . . . . . . . . . . . . 24 71 Appendix A. Usage Example of ECA model working with YANG PUSH . 25 72 Appendix B. Usage Example of reusing trigger-grouping . . . . . 27 73 Appendix C. Changes between revisions . . . . . . . . . . . . . 29 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 76 1. Introduction 78 [RFC8328] defines a policy-based management framework that allow 79 definition of a data model to be used to represent high-level, 80 possibly network-wide policies. This document defines an policy 81 based Event Management YANG data model [RFC7950]. The policy based 82 Event management YANG provides the ability for the network management 83 function (within a controller, an orchestrator, or a network element) 84 to control the configurations and monitor state parameters on the 85 network element and take simple and instant action when a trigger 86 condition on the system state is met. 88 The data model in this document is designed to be compliant with the 89 Network Management Datastore Architecture (NMDA) [RFC8342]. 91 2. Conventions used in this document 92 2.1. Terminology 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 96 document are to be interpreted as described in [RFC2119]. In this 97 document, these words will appear with that interpretation only when 98 in ALL CAPS. Lower case uses of these words are not to be 99 interpreted as carrying [RFC2119] significance. 101 This document uses the following terms: 103 Error A deviation of a system from normal operation [RFC3877]. 105 Fault Lasting error or warning condition [RFC3877]. 107 Event Something that happens which may be of interest or trigger the 108 invocation of the rule. A fault, an alarm, a change in network 109 state, network security threat, hardware malfunction, buffer 110 untilization crossing a threshold, network connection setup, an 111 external input to the system, for example [RFC3877]. 113 2.2. Tree Diagrams 115 Tree diagrams used in this document follow the notation defined in 116 [RFC8340]. 118 3. Objectives 120 This section describes some of the design objectives for the policy 121 based Event management Data Model: 123 o The policy based Event management YANG should provide the ability 124 for the network management function to control configuration and 125 monitor state changes on a network element using the NETCONF/ 126 RESTCONF, and initiate simple actions whenever a trigger condition 127 is met. For example, a NETCONF subscribed notification can be 128 generated when a system state value exceeds the threshold. 130 o Clear and precise identification of policy based Event types and 131 managed objects. 133 o Allow the server to inform the client that a certain Event is 134 related to other Events. 136 o Allow one event to be able to call another nested event. 138 o The event data model defined in this document can be implemented 139 on the management system that also implements EVENT-MIB; thus, the 140 mapping between the event data model and ENTITY-MIB should be 141 clear. 143 4. Relationship to YANG Push 145 YANG-push mechanism provides a subscription service for updates from 146 a datastore. And it supports two types of subscriptions which are 147 distinguished by how updates are triggered: periodic and on-change. 149 The On-change Push allow receivers to receive updates whenever 150 changes to target managed objects occur. This document specifies a 151 mechanism that provides three trigger conditions: 153 o Existence: When a specific managed object appears, the trigger 154 fires, e.g. reserved ports are configured. 156 o Boolean: The user can set the type of boolean operator (e.g. 157 unequal, equal, less, less-or-equal, greater, greater-or-equal, 158 etc) and preconfigured threshold value (e.g. Pre-configured 159 threshold). If the value of a managed object meet Boolean 160 conditions, the trigger fires, e.g., when the boolean operator 161 type is 'less', the trigger will be fired if the value of managed 162 object is less than the pre-configured Boolean value. 164 o Variation: The event that may be triggered when a managed object 165 in multiple instances of the data tree is found and the current 166 sampled value is either rising or falling and exceeds the pre- 167 configured threshold, but the value at the last sampling interval 168 does not exceed the pre-configured threshold. It also can be 169 triggered when the current sample value change exceeds the pre- 170 configured delta threshold. For example, when the 'startup' value 171 is set to 'rising', the current sampled value of that managed 172 object is greater than or equal to this threshold, and the value 173 at the last sampling interval was less than this threshold, then 174 one variation rising event is triggered for that managed object. 175 In another example, if the 'startup' value is set to 'falling' and 176 the system state value of the managed object is less than or equal 177 to this threshold, and the value at the last sampling interval was 178 greater than this threshold, then one variation falling event is 179 triggered for that managed object. 181 And the YANG Push mechanism more focuses on the remote mirroring and 182 monitoring of configuration and operational state. For example, for 183 on change method, the subscriber will receive a notification if the 184 change occurs. The model defined in this document provides a method 185 which allow automatic adjusting the value of the corresponding 186 managed object when some event is triggered. It establishes 187 association between network service monitoring and network service 188 provision and can use output generated by network service monitoring 189 as input of network service provision and thereby provide automated 190 network management. The details of the usage example is described in 191 Appendix A. 193 5. Relationship to EVENT MIB 195 If the device implements the EVENT-MIB [RFC2981], each entry in the 196 "/events/event/trigger" list is mapped to MteTriggerEntry,MteTriggerE 197 xistenceEntry,MteTriggerBooleanEntry,MteTriggerThresholdEntry,MteObje 198 ctsEntry,MteEventEntry,MteEventSetEntry. respectively. 200 The following table lists the YANG data nodes with corresponding 201 objects in the EVENT-MIB [RFC2981]. 203 +------------------------------|---------------------------------+ 204 | YANG data node in | EVENT-MIB Objects | 205 | ietf-event.yang | (RFC2981) | 206 +----------------------------------------------------------------+ 207 | target | mteObjectsName | 208 | | | 209 | event-name | mteEventName | 210 | | | 211 | event-description | mteEventComment | 212 | | | 213 | value | mteEventSetValue | 214 | | | 215 | events/event/trigger/name | mteTriggerName | 216 | | | 217 | trigger-description | mteTriggerComment | 218 | | | 219 | frequency | mteTriggerFrequency | 220 | | | 221 | operator | mteTriggerBooleanComparison | 222 | | | 223 | value | mteTriggerBooleanValue | 224 | | | 225 | rising-event | mteTriggerThresholdRising | 226 | | | 227 | falling-event | mteTriggerThresholdFalling | 228 | | | 229 | delta-rising-event | mteTriggerThresholdDeltaRising | 230 | | | 231 | variation/startup | mteTriggerThresholdStartup | 232 | | | 233 | existence/enable | mteTriggerExistenceStartup | 234 | | | 235 | boolean/enable | mteTriggerBooleanStartup | 236 -------------------------------|---------------------------------| 238 6. Model Overview 240 The YANG data model for the Event management has been split into two 241 modules: 243 o The ietf-event-trigger.yang module defines a set of groupings for 244 a generic trigger. It is intended that these groupings will be 245 used by the policy based event management model or other models 246 that require the trigger conditions. In this model, three trigger 247 conditions are defined under the "test" choice node: 249 * Existence: When a specific managed object appears, the trigger 250 fires. 252 * Boolean: The Boolean trigger condition is used to monitor the 253 value of managed object. It compares the value of the managed 254 object with the pre-configured threshold value and takes action 255 according to the comparison result. The operator types include 256 unequal, equal, less, less-or-equal, greater, and greater-or- 257 equal. For example, if the operator is set to equal, an event 258 is triggered when the value of the managed object equals the 259 pre-configured value. The event will not be triggered again 260 until the value becomes unequal and comes back to equal. 262 * Variation: A Variation trigger condition regularly compares the 263 change value of the managed object with the delta threshold 264 value. The Variation trigger condition can be used to monitor 265 the value change of a managed object (when "statup" be set to 266 'delta-rising' or 'delta-falling'), if the change during the 267 sample interval exceeds the delta threshold, the event is 268 triggered. It can also be used to monitor the value variation 269 of the managed object. In addition, if the value of the 270 monitored object crosses a delta threshold multiple times in 271 succession, the event is triggered only for the first crossing. 272 For example, if the value of a sampled object crosses the 273 rising threshold multiple times, only the first crossing 274 triggers a rising alarm event. 276 o The ietf-event.yang module defines four lists: trigger, target, 277 event, and action. Triggers define the targets meeting some 278 conditions that lead to events. Events trigger corresponding 279 actions: 281 * Each trigger can be seen as a logical test that, if satisfied 282 or evaluated to be true, cause the action to be carried out. 283 The ietf-event.yang module uses groupings defined in ietf- 284 event-trigger.yang to present the trigger attributes. 286 * The target list defines managed objects that can be added to 287 logging or be set to a new value on the trigger, the trigger 288 test type, or the event that resulted in the actions. 290 * The event list defines what happens when an event is triggered, 291 i.e., trigger the corresponding action, e.g., addding a logging 292 ( i.e. Recording the triggered event), setting a value to the 293 managed object or both. The group-id can be used to group a 294 set of event that can be executed together,e.g., deliver a 295 service or provide service assurance. 297 * Nested-event are supported by allowing one event's trigger to 298 reference other event's definitions using the call-event 299 configuration. Called events apply their triggers and actions 300 before returning to the calling event's trigger and resuming 301 evaluation. If the called event is triggered, then it returns 302 an effective boolean true value to the calling event. For the 303 calling event, this is equivalent to a condition statement 304 evaluating to a true value and evaluation of the event 305 continues. 307 * The action list consists of updates or invocations on local 308 managed object attributes and defines a set of actions which 309 will be performed (e.g. logging, set value, etc) when the 310 corresponding event is triggered. The value to be set can use 311 many variations on rule structure. 313 The following tree diagrams [RFC8340] provide an overview of the data 314 model for "ietf-event-trigger" module and the "ietf-event" module. 316 module: ietf-event-trigger 317 grouping existences-trigger 318 +-- existences 319 +-- target* target 320 grouping boolean-trigger 321 +-- boolean 322 +-- operator? operator 323 +-- value? match-value 324 +-- target* target 325 grouping variation-trigger 326 +-- variation 327 +-- rising-value? match-value 328 +-- rising-target* target 329 +-- falling-value? match-value 330 +-- falling-target* target 331 +-- delta-rising-value? match-value 332 +-- delta-rising-target* target 333 +-- delta-falling-value? match-value 334 +-- delta-falling-target* target 335 +-- startup? enumeration 336 grouping trigger-grouping 337 +-- (test)? 338 +--:(existences) 339 | +-- existences 340 | +-- target* target 341 +--:(boolean) 342 | +-- boolean 343 | +-- operator? operator 344 | +-- value? match-value 345 | +-- target* target 346 +--:(variation) 347 +-- variation 348 +-- rising-value? match-value 349 +-- rising-target* target 350 +-- falling-value? match-value 351 +-- falling-target* target 352 +-- delta-rising-value? match-value 353 +-- delta-rising-target* target 354 +-- delta-falling-value? match-value 355 +-- delta-falling-target* target 356 +-- startup? enumeration 358 module: ietf-event 359 +--rw events 360 +--rw event* [event-name type] 361 +--rw event-name string 362 +--rw type identityref 363 +--rw event-description? string 364 +--rw group-id? group-type 365 +--rw target* trig:target 366 +--rw clear? boolean 367 +--rw trigger* [name] 368 | +--rw name string 369 | +--rw call-event? -> ../../event-name 370 | +--rw frequency 371 | | +--rw type? identityref 372 | | +--rw periodic 373 | | | +--rw interval uint32 374 | | | +--rw start? yang:date-and-time 375 | | | +--rw end? yang:date-and-time 376 | | +--rw scheduling 377 | | +--rw month* string 378 | | +--rw day-of-month* uint8 379 | | +--rw day-of-week* uint8 380 | | +--rw hour* uint8 381 | | +--rw minute* uint8 382 | | +--rw second* uint8 383 | | +--rw start? yang:date-and-time 384 | | +--rw end? yang:date-and-time 385 | +--rw (test)? 386 | +--:(existences) 387 | | +--rw existences 388 | | +--rw target* target 389 | +--:(boolean) 390 | | +--rw boolean 391 | | +--rw operator? operator 392 | | +--rw value? match-value 393 | | +--rw target* target 394 | +--:(variation) 395 | +--rw variation 396 | +--rw rising-value? match-value 397 | +--rw rising-target* target 398 | +--rw falling-value? match-value 399 | +--rw falling-target* target 400 | +--rw delta-rising-value? match-value 401 | +--rw delta-rising-target* target 402 | +--rw delta-falling-value? match-value 403 | +--rw delta-falling-target* target 404 | +--rw startup? enumeration 405 +--rw actions 406 +--rw target? trig:target 407 +--rw value? 408 +--rw logging? logging-type 410 The relation between Event, Trigger, Target and Action is described 411 as follows: 413 Project 414 +-------------------------------+ 415 | Event | 416 | +-------+ | 417 | |Target | | 418 | +---|---+ | +-------------------------------+ 419 | | | | Event | 420 | +----V---+ +--------+ | | +-------+ | 421 | |Trigger |------->| Action |-------->|Target | | 422 | +--------+ +--------+ | | +---|---+ | 423 +-------------------------------+ | | | 424 | +----|---+ +--------+ | 425 | |Trigger |------- | Action | | 426 | +--------+ +----+---+ | 427 +------------------------+------+ 428 | 429 +-----------------+ 430 +------+------------------------+ 431 | Event| | 432 | +---V---+ | 433 | |Target | | 434 | +---|---+ | 435 | | | 436 | +----|---+ +--------+ | 437 | |Trigger |------- | Action | | 438 | +--------+ +---+----+ | 439 +-----------------------+-------+ 440 +----------------+ 441 +------+------------------------+ 442 | Event| | 443 | +---V---+ | 444 | |Target | | 445 | +---|---+ | 446 | | | 447 | +----|---+ +--------+ | 448 | |Trigger |------- | Action | | 449 | +--------+ +--------+ | 450 +-------------------------------+ 452 One event may trigger another event,i.e., the action output in the 453 first event can be input to target in the second event and a set of 454 events can be grouped together and executed in a coordinated manner, 455 but if it does not trigger another event, the relation between two 456 events should be ignored. 458 7. EVENT TRIGGER YANG Module 460 file "ietf-event-trigger@2019-06-24.yang" 461 module ietf-event-trigger { 462 yang-version 1.1; 463 namespace "urn:ietf:params:xml:ns:yang:ietf-event-trigger"; 464 prefix trig; 466 import ietf-yang-types { 467 prefix yang; 468 } 470 organization 471 "IETF xxx Working Group"; 472 contact 473 "Zitao Wang: wangzitao@huawei.com 474 Qin Wu: bill.wu@huawei.com"; 475 description 476 "This module defines a reusable grouping for event trigger."; 478 revision 2019-06-24 { 479 description 480 "Initial revision."; 481 reference 482 "foo"; 483 } 485 typedef match-value { 486 type union { 487 type yang:xpath1.0; 488 type yang:object-identifier; 489 type string; 490 } 491 description 492 "This type is used to match resources of type 'target'. 493 Since the type 'target' is a union of different types, 494 the 'match-value' type is also a union of corresponding 495 types."; 496 } 498 typedef target { 499 type union { 500 type instance-identifier; 501 type yang:object-identifier; 502 type yang:uuid; 503 type string; 504 } 505 description 506 "If the target is modelled in YANG, this type will 507 be an instance-identifier. 508 If the target is an SNMP object, the type will be an 509 object-identifier. 510 If the target is anything else, for example a distinguished 511 name or a CIM path, this type will be a string. 512 If the target is identified by a UUID use the uuid 513 type. 514 If the server supports several models, the presedence should 515 be in the order as given in the union definition."; 516 } 518 typedef operator { 519 type enumeration { 520 enum unequal { 521 description 522 "Indicates that the comparision type is unequal to."; 523 } 524 enum equal { 525 description 526 "Indicates that the comparision type is equal to."; 527 } 528 enum less { 529 description 530 "Indicates that the comparision type is less than."; 531 } 532 enum less-or-equal { 533 description 534 "Indicates that the comparision type is less than 535 or equal to."; 536 } 537 enum greater { 538 description 539 "Indicates that the comparision type is greater than."; 540 } 541 enum greater-or-equal { 542 description 543 "Indicates that the comparision type is greater than 544 or equal to."; 545 } 546 } 547 description 548 "definition of the operator"; 549 } 551 grouping existences-trigger { 552 description 553 "A grouping that provides existence trigger"; 555 container existences { 556 leaf-list target { 557 type target; 558 description 559 "List for target objects"; 560 } 561 description 562 "Container for existence"; 563 } 564 } 566 grouping boolean-trigger { 567 description 568 "A grouping that provides boolean trigger"; 569 container boolean { 570 leaf operator { 571 type operator; 572 description 573 "Comparison type."; 574 } 575 leaf value { 576 type match-value; 577 description 578 "Compartion value which is static threshold value."; 579 } 580 leaf-list target { 581 type target; 582 description 583 "List for target management objects."; 584 } 585 description 586 "Container for boolean test."; 587 } 588 } 590 grouping variation-trigger { 591 description 592 "A grouping that provides variation trigger"; 593 container variation { 594 leaf rising-value { 595 type match-value; 596 description 597 "Sets the rising variation to the specified value, 598 when the current sampled value is greater than or equal to 599 this threshold, and the value at the last sampling interval 600 was less than this threshold, the event is triggered. "; 601 } 602 leaf-list rising-target { 603 type target; 604 description 605 "List for target objects."; 606 } 607 leaf falling-value { 608 type match-value; 609 description 610 "Sets the falling threshold to the specified value."; 611 } 612 leaf-list falling-target { 613 type target; 614 description 615 "List for target objects."; 616 } 617 leaf delta-rising-value { 618 type match-value; 619 description 620 "Sets the delta rising threshold to the specified value."; 621 } 622 leaf-list delta-rising-target { 623 type target; 624 description 625 "List for target objects."; 626 } 627 leaf delta-falling-value { 628 type match-value; 629 description 630 "Sets the delta falling threshold to the specified value."; 631 } 632 leaf-list delta-falling-target { 633 type target; 634 description 635 "List for target objects."; 636 } 637 leaf startup { 638 type enumeration { 639 enum rising { 640 description 641 "If the first sample after this 642 managed object becomes active is greater than or equal 643 to 'rising-value' and the 'startup' is equal to 644 'rising' then one threshold rising event is 646 triggered for that managed object."; 647 } 648 enum falling { 649 description 650 "If the first sample after this managed object becomes 651 active is less than or equal to 'falling-value' and 652 the 'startup' is equal to 'falling' then one 653 threshold falling event is triggered for that managed 654 object."; 655 } 656 enum rising-or-falling { 657 description 658 "That event may be triggered when the 659 'startup' is equal to 'rising-or-falling'. 660 'rising-or-falling' indicate the state value of the 661 managed object may less than or greater than the 662 specified thrshold value."; 663 } 664 } 665 description 666 "Startup setting."; 667 } 668 description 669 "Container for the threshold trigger condition. 670 Note that the threshold here may change over time 671 or the state value changes in either ascend order 672 or descend order."; 673 } 674 } 676 grouping trigger-grouping { 677 description 678 "A grouping that provides event trigger."; 679 choice test { 680 description 681 "Choice test"; 682 case existences { 683 uses existences-trigger; 684 } 685 case boolean { 686 uses boolean-trigger; 687 } 688 case variation { 689 uses variation-trigger; 690 } 691 } 692 } 693 } 694 696 8. EVENT YANG Module 698 file "ietf-event@2019-06-24.yang" 700 module ietf-event { 701 yang-version 1.1; 702 namespace "urn:ietf:params:xml:ns:yang:ietf-event"; 703 prefix evt; 705 import ietf-yang-types { 706 prefix yang; 707 } 708 import ietf-event-trigger { 709 prefix trig; 710 } 712 organization 713 "IETF xxx Working Group"; 714 contact 715 "Zitao Wang: wangzitao@huawei.com 716 Qin Wu: bill.wu@huawei.com"; 717 description 718 "This module defines a model for the service topology."; 720 revision 2019-06-24 { 721 description 722 "Initial revision."; 723 reference 724 "foo"; 725 } 727 identity event-type { 728 description 729 "Base identity for event type"; 730 } 732 identity frequency { 733 description 734 "Base identity for frequency"; 735 } 737 identity periodic { 738 base frequency; 739 description 740 "Identity for periodic trigger"; 741 } 743 identity scheduling { 744 base frequency; 745 description 746 "Identity for scheduling trigger"; 747 } 749 identity logging { 750 description 751 "Base identity for logging action"; 752 } 754 identity logging-notification { 755 base logging; 756 description 757 "Logging for event notification"; 758 } 760 identity logging-set { 761 base logging; 762 description 763 "Logging for reset values"; 764 } 766 typedef logging-type { 767 type identityref { 768 base logging; 769 } 770 description 771 "Logging types"; 772 } 774 typedef group-type { 775 type string; 776 description 777 "Group type"; 778 } 780 grouping start-end-grouping { 781 description 782 "A grouping that provides start and end times for 783 Event objects."; 784 leaf start { 785 type yang:date-and-time; 786 description 787 "The date and time when the Event object 788 starts to create triggers."; 789 } 790 leaf end { 791 type yang:date-and-time; 792 description 793 "The date and time when the Event object 794 stops to create triggers. 795 It is generally a good idea to always configure 796 an end time and to refresh the end time as needed 797 to ensure that agents that lose connectivity to 798 their Controller do not continue executing Schedules 799 forever."; 800 } 801 } 803 container events { 804 list event { 805 key "event-name type"; 806 leaf event-name { 807 type string; 808 description 809 "Event name"; 810 } 811 leaf type { 812 type identityref { 813 base event-type; 814 } 815 description 816 "Type of event"; 817 } 818 leaf event-description { 819 type string; 820 description 821 "Event description"; 822 } 823 leaf group-id { 824 type group-type; 825 description 826 "Group Identifier"; 827 } 828 leaf-list target { 829 type trig:target; 830 description 831 "targeted objects"; 832 } 833 leaf clear { 834 type boolean; 835 default "false"; 836 description 837 "A flag indicate whether the event be closed"; 838 } 839 list trigger { 840 key "name"; 841 leaf name { 842 type string; 843 description 844 "Trigger name"; 845 } 846 leaf trigger-description { 847 type string; 848 description 849 "Trigger description"; 850 } 851 leaf call-event { 852 type leafref { 853 path "../../event-name"; 854 } 855 description 856 "This leaf call sub-event."; 857 } 858 container frequency { 859 leaf type { 860 type identityref { 861 base frequency; 862 } 863 description 864 "Type of trigger frequency"; 865 } 866 container periodic { 867 when "derived-from-or-self(../type, 'periodic')"; 868 description 869 "A periodic timing object triggers periodically 870 according to a regular interval."; 871 leaf interval { 872 type uint32 { 873 range "1..max"; 874 } 875 units "seconds"; 876 mandatory true; 877 description 878 "The number of seconds between two triggers 879 generated by this periodic timing object."; 880 } 881 uses start-end-grouping; 882 } 883 container scheduling { 884 when "derived-from-or-self(../type, 'scheduling')"; 885 description 886 "A scheduling timing object triggers."; 887 leaf-list month { 888 type string; 889 description 890 "A set of months at which this scheduling timing 891 will trigger."; 892 } 893 leaf-list day-of-month { 894 type uint8 { 895 range "0..59"; 896 } 897 description 898 "A set of days of the month at which this 899 scheduling timing will trigger."; 900 } 901 leaf-list day-of-week { 902 type uint8 { 903 range "0..59"; 904 } 905 description 906 "A set of weekdays at which this scheduling timing 907 will trigger."; 908 } 909 leaf-list hour { 910 type uint8 { 911 range "0..59"; 912 } 913 description 914 "A set of hours at which the scheduling timing will 915 trigger."; 916 } 917 leaf-list minute { 918 type uint8 { 919 range "0..59"; 920 } 921 description 922 "A set of minutes at which this scheduling timing 923 will trigger."; 924 } 925 leaf-list second { 926 type uint8 { 927 range "0..59"; 928 } 929 description 930 "A set of seconds at which this calendar timing 931 will trigger."; 932 } 933 uses start-end-grouping; 934 } 935 description 936 "Container for frequency"; 937 } 938 uses trig:trigger-grouping; 939 description 940 "List for trigger"; 941 } 942 container actions { 943 leaf target { 944 type trig:target; 945 description 946 "Report the target objects"; 947 } 948 anydata value { 949 description 950 "Inline set content."; 951 } 952 leaf logging { 953 type logging-type; 954 description 955 "Specifies the log action"; 956 } 957 description 958 "Container for Actions"; 959 } 960 description 961 "List for Events"; 962 } 963 description 964 "YANG data module for defining event triggers and actions for 965 network management purposes"; 966 } 967 } 969 971 9. Security Considerations 973 The YANG modules defined in this document MAY be accessed via the 974 RESTCONF protocol [RFC8040] or NETCONF protocol ([RFC6241]). The 975 lowest RESTCONF or NETCONF layer requires that the transport-layer 976 protocol provides both data integrity and confidentiality, see 977 Section 2 in [RFC8040] and [RFC6241]. The lowest NETCONF layer is 978 the secure transport layer, and the mandatory-to-implement secure 979 transport is Secure Shell (SSH)[RFC6242] . The lowest RESTCONF layer 980 is HTTPS, and the mandatory-to-implement secure transport is TLS 981 [RFC5246]. 983 The NETCONF access control model [RFC6536] provides the means to 984 restrict access for particular NETCONF or RESTCONF users to a 985 preconfigured subset of all available NETCONF or RESTCONF protocol 986 operations and content. 988 There are a number of data nodes defined in this YANG module that are 989 writable/creatable/deletable (i.e., config true, which is the 990 default). These data nodes may be considered sensitive or vulnerable 991 in some network environments. Write operations (e.g., edit-config) 992 to these data nodes without proper protection can have a negative 993 effect on network operations. These are the subtrees and data nodes 994 and their sensitivity/vulnerability: 996 o /events/event/event-name 998 o /events/event/target 1000 o /events/actions/target 1002 o /events/event/trigger/name 1004 10. IANA Considerations 1006 This document registers two URIs in the IETF XML registry [RFC3688]. 1007 Following the format in [RFC3688], the following registrations are 1008 requested to be made: 1010 --------------------------------------------------------------------- 1011 URI: urn:ietf:params:xml:ns:yang:ietf-event-trigger 1012 Registrant Contact: The IESG. 1013 XML: N/A, the requested URI is an XML namespace. 1015 URI: urn:ietf:params:xml:ns:yang:ietf-event 1016 Registrant Contact: The IESG. 1017 XML: N/A, the requested URI is an XML namespace. 1018 --------------------------------------------------------------------- 1020 This document registers two YANG modules in the YANG Module Names 1021 registry [RFC6020]. 1023 --------------------------------------------------------------------- 1024 Name: ietf-event-trigger 1025 Namespace: urn:ietf:params:xml:ns:yang:ietf-event-trigger 1026 Prefix: trig 1027 Reference: RFC xxxx 1029 Name: ietf-event 1030 Namespace: urn:ietf:params:xml:ns:yang:ietf-event 1031 Prefix: evt 1032 Reference: RFC xxxx 1033 --------------------------------------------------------------------- 1035 11. Normative References 1037 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1038 Requirement Levels", March 1997. 1040 [RFC2981] Kavasseri, R., Ed., "Event MIB", RFC 2981, 1041 DOI 10.17487/RFC2981, October 2000, 1042 . 1044 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1045 DOI 10.17487/RFC3688, January 2004, 1046 . 1048 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1049 the Network Configuration Protocol (NETCONF)", RFC 6020, 1050 DOI 10.17487/RFC6020, October 2010, 1051 . 1053 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1054 and A. Bierman, Ed., "Network Configuration Protocol 1055 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1056 . 1058 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1059 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1060 . 1062 [RFC6370] Bocci, M., Swallow, G., and E. Gray, "MPLS Transport 1063 Profile (MPLS-TP) Identifiers", RFC 6370, 1064 DOI 10.17487/RFC6370, September 2011, 1065 . 1067 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1068 Protocol (NETCONF) Access Control Model", RFC 6536, 1069 DOI 10.17487/RFC6536, March 2012, 1070 . 1072 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1073 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1074 . 1076 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 1077 RFC 7952, DOI 10.17487/RFC7952, August 2016, 1078 . 1080 [RFC8328] Liu, W., Xie, C., Strassner, J., Karagiannis, G., Klyus, 1081 M., Bi, J., Cheng, Y., and D. Zhang, "Policy-Based 1082 Management Framework for the Simplified Use of Policy 1083 Abstractions (SUPA)", RFC 8328, DOI 10.17487/RFC8328, 1084 March 2018, . 1086 Appendix A. Usage Example of ECA model working with YANG PUSH 1088 The relation between Event and YANG PUSH is described as follow: YANG 1089 Push Notification may trigger one event, i.e. one trigger conditions 1090 of the Event A can be set to "receiver received a yang push 1091 notification", and it can associates with other conditions of the 1092 Event A. When these conditions are met, the event A is triggered. 1094 +-----------------------+ 1095 | yang-push | 1096 | | 1097 | +--------------+ | 1098 | | receiver | | +------------------------------+ 1099 | | | | | Event A | 1100 | +--------^-----+ | | | 1101 | | | | +-----------+ | 1102 | | +-------+| | | | | 1103 | | |notification | | target | | 1104 | | | +| | --> | | 1105 | | +-------+\\ ---- +----+------+ | 1106 | +--------+-----+ | \---| | | 1107 | | target | ---- \\ | | | 1108 | | +-- | \\ | | 1109 | +--------------+ | |\ +------V---+ +----------+| 1110 +-----------------------+ | \\| | | || 1111 | > trigger +---> action || 1112 | | | | || 1113 | +----------+ +-----+----+| 1114 | | 1115 +------------------------ -----+ 1117 For Example: 1119 The receiver received a push-change-update notification and learned 1120 that the "oper-status" of interface[name='eth0'] changed. 1122 The target of Event "interface-state-monitoring" is set to 1123 "/if:interfaces/if:interface[if:name='eth0']", the trigger list 1124 contains two conditions: 1)receiver received a push-change-update 1125 notification; 2) the value of "in-errors" of interface[name='eth0'] 1126 exceeded the pre-configured threshold. When these conditions are 1127 met, corresponding action will be performed, i.e. disable 1128 interface[name='eth0']. The XML examples are shown as below: 1130 1131 2017-10-25T08:22:33.44Z 1132 1134 89 1135 1136 1137 0 1138 1139 edit1 1140 replace 1141 /ietf-interfaces:interfaces 1142 1143 1145 1146 eth0 1147 up 1148 1149 1150 1151 1152 1153 1154 1155 1157 1158 interface-state-monitoring 1159 interface-exception 1160 /if:interfaces/if:interface[if:name='eth0'] 1161 1162 state-push-change 1163 received yang push 1164 \changed notification 1165 1166 /yp:notification/yp:push-change-update/yp:id[id=89]\ 1167 /yp:datastore-changes/.../yp:target="/ietf-interfaces:interfaces='eth0'\ 1168 " 1169 1170 1171 1172 evaluate-in-errors 1173 interface-state-chang 1174 evaluate the number of 1175 the packets that contained errors 1176 1177 10m 1178 1179 1180 greater-or-equal 1181 100 1182 /if:interfaces/if:interface[if:name='eth0']\ 1183 /if:statistic/if:in-errors 1184 1185 1186 1187 1188 /if:interfaces/if:interface[if:name='eth0'] 1189 1190 1191 1192 eth0 1193 false 1194 1195 1196 1197 1198 1200 1202 Appendix B. Usage Example of reusing trigger-grouping 1204 The "ietf-event-trigger.yang" module defines a set of groupings for a 1205 generic trigger. It is intended that these groupings can be reused 1206 by other models that require the trigger conditions, for example, in 1207 some subscription and notification cases, many applications do not 1208 require every update, only updates that are of certain interest. The 1209 following example describe how to reuse the "ietf-event-trigger" 1210 module to define the subscription and notification smarter filter. 1212 import ietf-subscribed-notifications { 1213 prefix sn; 1214 } 1215 import ietf-event-trigger { 1216 prefix trig; 1217 } 1219 augment "/sn:subscriptions/sn:subscription" { 1220 description "add the smart filter container"; 1221 container smart-filter { 1222 description "It concludes filter configurations"; 1223 uses trig:trigger-grouping; 1224 } 1225 } 1227 The tree diagrams: 1229 module: ietf-smart-filter 1230 augment /sn:subscriptions/sn:subscription: 1231 +--rw smart-filter 1232 +--rw (test)? 1233 +--:(existences) 1234 | +--rw existences 1235 | +--rw target* target 1236 +--:(boolean) 1237 | +--rw boolean 1238 | +--rw operator? operator 1239 | +--rw value? match-value 1240 | +--rw target* target 1241 +--:(variation) 1242 +--rw variation 1243 +--rw rising-value? match-value 1244 +--rw rising-target* target 1245 +--rw falling-value? match-value 1246 +--rw falling-target* target 1247 +--rw delta-rising-value? match-value 1248 +--rw delta-rising-target* target 1249 +--rw delta-falling-value? match-value 1250 +--rw delta-falling-target* target 1251 +--rw startup? enumeration 1253 Appendix C. Changes between revisions 1255 v02 - v03 1257 o Usage Example Update: add an usage example to introduce how to 1258 reuse the ietf-event-trigger module to define the subscription- 1259 notification smarter filter. 1261 v01 - v02 1263 o Introduce the group-id which allow group a set of events that can 1264 be executed together 1266 o Change threshold trigger condition into variation trigger 1267 condition to further clarify the difference between boolean 1268 trigger condition and variation trigger condition. 1270 o Module structure optimization. 1272 o Usage Example Update. 1274 v00 - v01 1276 o Separate ietf-event-trigger.yang from Event management modeland 1277 ietf-event.yang and make it reusable in other YANG models. 1279 o Clarify the difference between boolean trigger condition and 1280 threshold trigger condition. 1282 o Change evt-smp-min and evt-smp-max into min-data-object and max- 1283 data-object in the data model. 1285 Authors' Addresses 1287 Michael Wang 1288 Huawei Technologies,Co.,Ltd 1289 101 Software Avenue, Yuhua District 1290 Nanjing 210012 1291 China 1293 Email: wangzitao@huawei.com 1295 Qin Wu 1296 Huawei 1297 101 Software Avenue, Yuhua District 1298 Nanjing, Jiangsu 210012 1299 China 1301 Email: bill.wu@huawei.com 1303 Chongfeng Xie 1304 China Telecom 1306 Email: xiechf@ctbri.com.cn