idnits 2.17.1 draft-ietf-netmod-eca-policy-00.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 59 instances of too long lines in the document, the longest one being 41 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 590 has weird spacing: '...-source leaf...' == Line 591 has weird spacing: '...-result leaf...' == Line 699 has weird spacing: '...nc-name str...' == Line 754 has weird spacing: '...-option iden...' == Line 779 has weird spacing: '...-source leaf...' == (2 more instances...) -- The document date (December 22, 2020) is 1219 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: 'RFC3198' is mentioned on line 96, but not defined == Missing Reference: 'RFC3178' is mentioned on line 148, but not defined == Missing Reference: 'XPATH' is mentioned on line 462, but not defined == Missing Reference: 'RFC8641' is mentioned on line 705, but not defined == Missing Reference: 'GNCA' is mentioned on line 1762, but not defined == Unused Reference: 'RFC3460' is defined on line 1799, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 2 errors (**), 0 flaws (~~), 13 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group Q. Wu 3 Internet-Draft Huawei 4 Intended status: Standards Track I. Bryskin 5 Expires: June 25, 2021 Individual 6 H. Birkholz 7 Fraunhofer SIT 8 X. Liu 9 Volta Networks 10 B. Claise 11 Cisco 12 December 22, 2020 14 A YANG Data model for ECA Policy Management 15 draft-ietf-netmod-eca-policy-00 17 Abstract 19 This document defines a YANG data model for Event Condition Action 20 (ECA) policy management. The ECA policy YANG module provides the 21 ability to delegate some network management functions to the server 22 which can take simple and instant action when a trigger condition on 23 the system state is met. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on June 25, 2021. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Conventions used in this document . . . . . . . . . . . . . . 3 61 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 2.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 5 63 3. Overview of ECA YANG Data Model . . . . . . . . . . . . . . . 5 64 3.1. ECA Policy Variable and Value . . . . . . . . . . . . . . 5 65 3.2. ECA Event . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.3. ECA Condition . . . . . . . . . . . . . . . . . . . . . . 9 67 3.3.1. Mapping Policy Variables to XPath Variables . . . . . 10 68 3.3.2. ECA XPath Context . . . . . . . . . . . . . . . . . . 11 69 3.3.3. ECA Evaluation Exceptions . . . . . . . . . . . . . . 11 70 3.4. ECA Action . . . . . . . . . . . . . . . . . . . . . . . 12 71 3.5. ECA . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 3.5.1. ECA XPath Function Library (ECALIB) . . . . . . . . . 15 73 4. ECA YANG Model (Tree Structure) . . . . . . . . . . . . . . . 16 74 5. ECA YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 75 6. Security Considerations . . . . . . . . . . . . . . . . . . . 37 76 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 77 8. Acknowledges . . . . . . . . . . . . . . . . . . . . . . . . 38 78 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 38 79 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 80 10.1. Normative References . . . . . . . . . . . . . . . . . . 39 81 10.2. Informative References . . . . . . . . . . . . . . . . . 40 82 Appendix A. ECA Condition Expression Examples . . . . . . . . . 40 83 Appendix B. Usage Example of Smart Filter using Server Event 84 Trigger . . . . . . . . . . . . . . . . . . . . . . 41 85 Appendix C. Usage Example of Router Log Dump using Timer Event 86 Trigger . . . . . . . . . . . . . . . . . . . . . . 47 87 Appendix D. Usage Example of High CPU Utilization 88 Troubleshooting . . . . . . . . . . . . . . . . . . 48 89 Appendix E. Changes between Revisions . . . . . . . . . . . . . 51 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 92 1. Introduction 94 Traditional approaches for network to automatically perform 95 corrective actions in response to network events have been largely 96 built on centralized policy based management [RFC3198]. With 97 centralized network management, the managed object state or 98 operational state spanning across the devices needs to be retrieved 99 by the client from various different servers. However there are 100 issues associated with centralized network management: 102 o Centralized network management incurs massive data collection and 103 processing, the resource consumption (e.g., network bandwidth 104 usage, the state to be maintained) is huge; 106 o Centralized network management leads to slow reaction to the 107 network changes when large amounts of managed object state from 108 devices needs to collected and correlated at the central point 109 where decisions about resource adjustment are made; 111 o Centralized network management cannot control or influence 112 management behavior within the server if the server is not 113 connected to any network or the existing configuration on the 114 server has major errors; 116 o Centralized network management doesn't scale well when thousands 117 of devices needs to send hundreds of event notifications, or 118 millions of managed data objects needs to be polled by the client; 120 A more effective alternative to centralized network management is to 121 delegate network management functions to servers in the network and 122 allow each server to monitor state changes of managed objects. 123 Accordingly there is a need for a service to provide continuous 124 performance monitoring, detect defects and failures, and take 125 corrective action. 127 This document defines an ECA Policy management YANG data model. The 128 ECA Policy YANG allows the client to move the network management task 129 to the server, which provides the ability to control the 130 configurations and monitor state parameters, and take simple and 131 instant action on the server when a trigger condition on the system 132 state is met. 134 The data model in this document is designed to be compliant with the 135 Network Management Datastore Architecture (NMDA) [RFC8342]. 137 2. Conventions used in this document 139 2.1. Terminology 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in [RFC2119]. In this 144 document, these words will appear with that interpretation only when 145 in ALL CAPS. Lower case uses of these words are not to be 146 interpreted as carrying [RFC2119] significance. 148 The following terms are defined in [RFC7950] [RFC3178] and are not 149 redefined here: 151 o Policy Decision Point (PDP) 153 o Policy Enforcement Point (PEP) 155 o Provisioned Policy 157 o Server 159 o Client 161 o Event 163 This document uses the following terms: 165 Condition: Condition can be seen as a logical test that, if 166 satisfied or evaluated to be true, causes the action to be carried 167 out. 169 Action: Update or invocation on local managed object attributes. 171 ECA Event: The input to the ECA logic that initiates the processing 172 derived from an extensible list of platform event types. 174 Server Event: An event that happens in the server for which a 175 Notification could be generated in an Event Stream subscription. 177 Datastore Event: An event that happens within a datastore within the 178 server for which a Notification could be generated in a datastore 179 subscription. 181 Timer Event: A pseudo-event in the server that allows ECA logic to 182 be invoked periodically. 184 Diagnostic Event: A pseudo-event initiated by the client to test ECA 185 logic. 187 Self Monitoring: Automatic monitoring of resources to ensure the 188 optimal functioning with respect to the defined requirements. 190 Self Healing: Automatic discovery and correction of faults; 191 automatically applying all necessary Actions to bring the system 192 back to normal operation. 194 Policy Variable (PV): Represents datastore states that change (or 195 "vary"), and that is set or evaluated by software. 197 PV-Source: Represents an XPath result, which contains one of four 198 data types: Boolean, Number, String, and Node Set. 200 PV-Result: Represents the value of the result of an Policy Variable 201 evaluation. 203 2.2. Tree Diagrams 205 Tree diagrams used in this document follow the notation defined in 206 [RFC8340]. 208 3. Overview of ECA YANG Data Model 210 A ECA policy rule is read as: when event occurs in a situation where 211 condition is true, then action is executed. Therefore ECA comprises 212 three key elements: event, associated conditions, and actions. These 213 three elements should be pushed down and configured on the server by 214 the client. If the action is rejected by the server duing ECA policy 215 execution, the action should be rolled back and cleaned up. 217 3.1. ECA Policy Variable and Value 219 ECA policy variable (PV) generically represents datastore states that 220 change (or "vary"), and that is set or evaluated by software. The 221 value of ECA policy variable is used for modeling values and 222 constants used in policy conditions and actions. In policy, 223 conditions and actions can abstract information as "policy variables" 224 to be evaluated in logical expressions, or set by actions, e.g., the 225 policy condition has the semantics "variable matches value" while 226 policy action has the semantics "set variable to value". 228 In ECA, two type of policy variables are defined, pv-source variable 229 and pv-result variable. pv-source variable represents an XPath 230 expression input, which contains one of four data types: Boolean, 231 Number, String, and Node Set while pv-result variable represents the 232 value of the result of an Policy Variable evaluation. 234 o A pv-source is always config = true. 236 o A pv-result is always config = false. 238 o A single anydata cannot be used for all values since it is only 239 allowed to contain child nodes. Separate scalar and nodeset 240 values are needed. 242 Each ECA policy variable has the following two attributes: 244 o Name with Globally unique or ECA unique scope ; 246 o Type either pv-source or pv-result; 248 The following operations are allowed with/on a PV: 250 o initialize (with a constant/enum/identity); 252 o set (with contents of another same type PV); 254 o read (retrieve datastore contents pointed by the specified same 255 type XPath/sub-tree); 257 o write (modify configuration data in the datastore with the PV's 258 content/value); 260 o function calls or RPC in a form of F(arg1,arg2,...), where F is an 261 identity of a function from extendable function library, 262 arg1,arg2,etc are PVs respectively, the function's input 263 parameters, with the result returned in result policy variable. 265 PVs could also be a source of information sent to the client in 266 notification messages. 268 PVs could be also used in condition expressions. 270 The model structure for the Policy Variable is shown below: 272 +--rw policy-variables 273 | +--rw policy-variable* [name] 274 | +--rw name string 275 | +--rw type identityref 276 | +--rw (xpath-value-choice)? 277 | +--:(policy-source) 278 | | +--rw (pv-source) 279 | | +--:(xpath-expr) 280 | | | +--rw xpath-expr? yang:xpath1.0 281 | | +--:(scalar-constant) 282 | | | +--rw scalar-constant? string 283 | | +--:(nodeset-constant) 284 | | +--rw nodeset-constant? 285 | +--:(policy-result) 286 | +--rw (pv-result) 287 | +--:(scalar-value) 288 | | +--rw scalar-value? string 289 | +--:(nodeset-value) 290 | +--rw nodeset-value? 292 3.2. ECA Event 294 The ECA Event is any subscribable event notification either 295 explicitly defined in a YANG module (e.g., interface management 296 model) supported by the server or a event stream conveyed to the 297 server via YANG Push subscription. The ECA event are used to keep 298 track of state of changes associated with one of multiple operational 299 state data objects in the network device. 301 Each ECA Event can be classified into server event, datastore event, 302 timer event, diagnostics event and has the following common 303 attributes: 305 o event-name, the name of ECA event; 307 o event-type, typical examples of ECA event type include server 308 event, datastore event, timer event and diagnostic event. 310 For server event, the following additional attributes are defined: 312 o event-stream,typical example of event stream is NETCONF stream. 314 o event-module, the name of YANG module associated with the ECA 315 event. 317 o event, it is event stream conveyed to the server. 319 For datastore event, the following additional attributes are defined: 321 datastore, the name of the datastore, typical example of datastore 322 is running, operational state datastores. 324 data-path, in the form of XPATH expression. 326 data, it is event notification defined in a YANG module. 328 A client may define an event of interest by making use of YANG PUSH 329 subscription. Specifically, the client may configure an ECA event 330 according to the ECA model specifying the event's name, as well as 331 the name of corresponding PUSH subscription. In this case, the 332 server is expected to: 334 o Register the event recording its name and using the referred PUSH 335 subsription trigger as definition of the event firing trigger; 337 o Auto-configure the event's ECA input in the form of local PVs 338 using the PUSH subscription's filters; 340 o At the moment of event firing intercept the notifications that 341 would be normally sent to the PUSH subscription's client(s); copy 342 the data store states pointed by the PUSH subscription's filters 343 into the auto-configured ECA's local PVs and execute the ECA's 344 condition-action chain. 346 All events (specified in at least one ECA pushed to the server) are 347 required to be constantly monitored by the server. One way to think 348 of this is that the server subscribes to its own publications with 349 respect to all events that are associated with at least one ECA. 351 The model structure for the ECA Event is shown below: 353 +--rw events 354 | +--rw event* [event-name] 355 | +--rw event-name string 356 | +--rw event-type? identityref 357 | +--rw policy-variable* -> /gncd/policy-variables/policy-variable/name 358 | +--rw local-policy-variable* -> /gncd/ecas/eca/policy-variable/name 359 | +--rw (type-choice)? 360 | +--:(server-event) 361 | | +--rw event-stream? string 362 | | +--rw event-module? string 363 | | +--rw event? 364 | +--:(datastore-event) 365 | | +--rw datatore? string 366 | | +--rw data-path? string 367 | | +--rw data? 368 | +--:(timer-event) 369 | +--:(diagnostics-event) 371 3.3. ECA Condition 373 The ECA Condition is the logical expression that is specified in a 374 form of Xpath expression and evaluated to TRUE or FALSE. The XPath 375 expression specifies an arbitrary logical/mathematical expression; 376 The elements of the ECA Condition expression are referred by the 377 XPaths pointing to referred datastore states. 379 The ECA Condition expression in the form of XPath expression allows 380 for specifying a condition of arbitrary complexity as a single string 381 with an XPath expression, in which pertinent PVs and datastore states 382 are referred to by their respective positions in the YANG tree. 384 ECA Conditions are associated with ECA Events and evaluated only 385 within event threads triggered by the event detection. 387 When an ECA Condition is evaluated to TRUE, the associated ECA Action 388 is executed. 390 The model structure for the condition is shown below: 392 +--rw conditions 393 | +--rw condition* [name] 394 | +--rw name string 395 | +--rw (expression-choice)? 396 | +--:(xpath) 397 | +--rw condition-xpath? string 399 3.3.1. Mapping Policy Variables to XPath Variables 401 Policy variables are mapped to XPath variable bindings so they can be 402 referenced in the XPath expression for a Condition. 404 o The 'name' leaf value for the policy variable is mapped to the 405 local-name of the XPath variable. No namespace is used for ECA 406 varaibles. Eg., the policy variable named 'foo' would be 407 accessible with a variable refernece '$foo'. 409 o The local-name 'USER' is reserved and defined in NACM. The server 410 SHOULD provide the USER variable as NACM is implemented. 412 o XPath variables can be used in 2 main ways in an expression: 414 1) anchor of a path-expr 416 $node-set-variable/child1/nested2 418 2) right-hand side of a primary-expr 420 /foo[name = $scalar-variable] 422 o It cannot be used in the middle of a path-expr 424 /interfaces/$node-set-variable/child1/nested2 // NOT OK 426 o Since a variable is a primary expression it can be used in XPath 427 expression constructions anywhere a primary-expr is allowed 429 $nodeset-variable1 | $ nodeset-variable2 431 ($min-length + $avg-length) < $last-length 433 o The values of all available policy variables are updated by the 434 server (if required) before the XPath expression is evaluated. 435 The variable binding value MUST NOT change while the XPath 436 expression is being evaluated. If multiple references to the same 437 variable exist in an XPath expression, they MUST resolve to the 438 same value in each instance. 440 Example: "/test1[name=$badfan] and /test2[name=$badfan]" 441 The same value of 'badfan' is expected in each instance. 443 o If a variable reference cannot be resolved because no policy 444 variable with that name is accessible to the ECA under evaluation, 445 then an eca-exception notification SHOULD be generated, and the 446 XPath evaluation MUST be terminated with an error. 448 3.3.2. ECA XPath Context 450 All XPath expressions used in ECA share the following XPath context 451 definition. 453 o The set of namespace declarations is the set of all modules loaded 454 into the server at the moment. Prefix bindings can reference the 455 set of namespace URIs for this set of modules. 457 o All names SHOULD be namespace-qualified. There is no default 458 namespace to use if no namespace is specified. If no namespace is 459 used then the XPath step matches the local-name in all namespaces. 461 o The function library is the core function library defined in 462 [XPATH], the functions defined in Section 10 of [RFC7950], and the 463 ECALIB functions defined in this document Section 3.5.1. 465 o The set of variable bindings is set to all policy variables that 466 are visible to the ECA under evaluation. This includes the local- 467 policy-variable and policy-variable entries configured for the 468 'eca' entry. Since pv-source values can reference other policy 469 variables, the order that these fields are set is significant. 471 o The accessible tree is all state data in the server, and the 472 running configuration datastore. The root node has all top-level 473 data nodes in all modules as children. 475 o The context node for all ECA XPath evaluation is the root node. 477 3.3.3. ECA Evaluation Exceptions 479 Not all errors can be detected at configuration time. Error that 480 occur while ECA logis is being evaluated will cause the server to 481 generate an eca-exception notification. 483 If the ECA is scheduled one time, an exception to eca entry execution 484 will be generated if the error occurs. If the ECA is scheduled 485 periodically and duplicated exception notification is generated in 486 the second period interval, ECA entry execution will be disabled 487 automamtically and in addition eca entry disable exeception will be 488 generated and sent to the local client. 490 identity eca-exception-reason { 491 description 492 "Base of all values for the 'reason' leaf in the 493 eca-exception notification."; 494 } 496 identity varbind-unknown { 497 base eca-exception-reason; 498 description 499 "The requested policy variable binding is not defined. 500 The variable binding cannot be resolved in the XPath 501 evaluation."; 502 } 503 identity func-invoke-error { 504 base eca-exception-reason; 505 description 506 "The function call is invoked and return false output."; 507 } 508 identity rpc-call-error { 509 base eca-exception-reason; 510 description 511 "The rpc call is invoked and return false output."; 512 } 513 identity eca-entry-disable { 514 base eca-exception-reason; 515 description 516 "The ECA entry is disabled if the same exception occurs more than once 517 in the periodical ECA."; 518 } 519 // Additional exceptions can be added as needed 520 notification eca-exception { 521 description 522 "This notification is sent when some error occurs 523 while the server is processing ECA logic."; 524 leaf reason { 525 type eca-exception-reason; 526 } 527 } 529 3.4. ECA Action 531 The ECA Action list consists of updates or invocations on local 532 managed object attributes and a set of actions are defined as 533 follows, which will be performed when the corresponding event is 534 triggered: 536 o sending one time notification 537 o (re-)configuration scheduling - scheduling one time or periodic 538 (re-)configuration in the future 540 o stopping current ECA; 542 o invoking the same ECA recursively; 544 Three points are worth noting: 546 o When a "Send notification" action is configured as an ECA Action, 547 the notification message to be sent to the client may contain not 548 only elements of the data store (as, for example, YANG PUSH or 549 smart filter notifications do), but also the contents of global 550 and local PVs, which store results of arbitrary operations 551 performed on the data store contents (possibly over arbitrary 552 period of time) to determine, for example, history/evolution of 553 data store changes, median values, ranges and rates of the 554 changes, results of configured function calls and expressions, 555 etc. - in short, any data the client may find interesting about 556 the associated event with all the logic to compute said data 557 delegated to the server. Importantly, ECA notifications are the 558 only ECA actions that directly interact with and hence need to be 559 unambiguously understood by the client. Furthermore, the same ECA 560 may originate numerous single or repetitive semantically different 561 notifications within the same or separate event firings. In order 562 to facilitate for the client the correlation of events and ECA 563 notifications received from the server, the ECA model requires 564 each notification to carry mandatory information, such as event 565 and (event scope unique) notification names. 567 o Multiple ECA Actions could be triggered by a single ECA event. 569 o Any given ECA Condition or Action may appear in more than one 570 ECAs. 572 The model structure for the actions is shown below: 574 +--rw actions 575 | +--rw time-schedule! 576 | | +--rw period? centiseconds 577 | +--rw action* [name] 578 | +--rw name string 579 | +--rw action-element* [name] 580 | | +--rw name string 581 | | +--rw action-type? identityref 582 | | +--rw (action-operation)? 583 | | +--:(action) 584 | | | +--rw next-period boolean 585 | | | +--rw action-name? 586 | | | -> /gnca/actions/action/name 587 | | +--:(function-call) 588 | | | +--rw function-call 589 | | | +--rw func-name leafref 590 | | | +--rw policy-source leafref 591 | | | +--rw policy-result leafref 592 | | | +--:(rpc-operation) 593 | | | | +--rw rpc-operation 594 | | | | +--rw rpc-name? string 595 | | | | +--rw nc-action-xpath? string 597 3.5. ECA 599 An ECA container includes: 601 o ECA name. 603 o List of local PVs and global PVs. As mentioned, These PVs could 604 be configured as dynamic (their instances appear/disappear with 605 start/stop of the ECA execution) or as static (their instances 606 exist as long as the ECA is configured). Global PV will be shared 607 by multiple ECA instances while local PVs are within the scope of 608 a specific ECA instance. 610 o Normal CONDITION-ACTION list: configured conditions each with 611 associated actions to be executed if the condition is evaluated to 612 TRUE 614 Note that this document currently focuses on one event with multiple 615 conditions and actions case. How different ECAs do not impact each 616 other if they share PVs and other components is not in the scope of 617 this document at this moment. 619 3.5.1. ECA XPath Function Library (ECALIB) 621 A set of common event PVs need to be set for every invocation of 622 condition or action logic: 624 $event-type (string) 625 $event-name (string) 627 For event-type = "server-event" 629 $event-stream (string) 630 $event-module (string) 631 $event-name (string) 632 $event (node-set) 634 The condition can use these PVs directly in an expression 635 An expression can access client-configured PVs of course 637 $event/child[name=$some-global-var] > 10 639 For event-type = "datastore" 641 $datastore (string) 642 $data-path (string) 643 $data (node-set) 645 The data is defined to be a container with the requested data as child nodes 647 $data/interface[type=$gigabit-eth] // (node-set is an array of data nodes, usually 648 siblings) 650 A standard func call should be defined to specify operation on policy variables 651 and xpath expression and store func result. 652 //Increment count by one each time increment-func is invoked 653 boolean function increment-func(number count) 655 //Decrement count by one each time decrement-func is invoked 656 boolean function decrement-func(number count) 658 //Exit the loop to monitor specific event 659 boolean function exit-func() 661 //Continue the loop to monitor the specific event 662 boolean function continue-func() 664 //set iteration variable as true if count variable is equal to or greater than 1 665 //set iteration variable as false if count variable is zero 666 boolean function match-func (string expr,number count,boolean iteration) 667 // check every 5 seconds until the same event occurs 2 times 668 sustained-event("$event/child[type=$some-global-var]/descendant[$leaf1 > 10]", 5, 2) 670 boolean function sustained-event (string expr, number interval, number count) 671 test expression 'expr' once per 'interval'. Keep testing once per 672 interval until true result reached, i.e., both xpath expression is 673 evaluated to true and 'count' number of interval on specific data 674 object has been tested true 675 (e.g., the same event occurs 'count' times )Return true if condition 676 tested true for count intervals; Returns false otherwise; 678 // check the event record every 5 seconds and filter the event record with 679 constraint of a specific descendant node to the event record root node 680 filtered-event("$event/child/descendant[$leaf1 > 10]", "$event",5) 682 boolean function filtered-event (string input-expr,string output-expr,number 683 interval)test expression 'expr'once per 'interval' and generate event 684 record output represented by 'output-expr' based on 'input-expr'. 685 Note than 'output-expr'and 'input-expr'share the same root node; 687 A standard rpc should be defined to specify the operation on the event stream 688 // suppress the event stream corresponding to XPATH expression 689 boolean rpc event-duplication-suppress(string expr) 691 The ECA XPath function library is expected to grow over time and 692 additional standard or vendor function libraries should be possible. 693 The server should provide a read-only list of ECA function libraries 694 supported. How it is exposed to the client is beyond scope of this 695 document. 697 +--rw eca-func-libs 698 +--rw eca-function* [func-name] 699 | +--rw func-name string 700 +--rw eca-rpc* [rpc-name] 701 | +--rw rpc-name string 702 +--rw eca-name -> /gncd/ecas/eca/name 704 Note that ECA accesses specific datastores in the same way as YANG 705 Push [RFC8641]. The difference is condition expression is introduced 706 to further filter nodes in the node set and the policy variable is 707 introduced to keep the intermediate states during the interaction 708 between the local client and the server. 710 4. ECA YANG Model (Tree Structure) 712 The following tree diagrams [RFC8340] provide an overview of the data 713 model for the "ietf-eca" module. 715 module: ietf-eca 716 +--rw gncd 717 +--rw policy-variables 718 | +--rw policy-variable* [name] 719 | +--rw name string 720 | +--rw type identityref 721 | +--rw (xpath-value-choice)? 722 | +--:(policy-source) 723 | | +--rw (pv-source) 724 | | +--:(xpath-expr) 725 | | | +--rw xpath-expr? yang:xpath1.0 726 | | +--:(scalar-constant) 727 | | | +--rw scalar-constant? string 728 | | +--:(nodeset-constant) 729 | | +--rw nodeset-constant? 730 | +--:(policy-result) 731 | +--rw (pv-result) 732 | +--:(scalar-value) 733 | | +--rw scalar-value? string 734 | +--:(nodeset-value) 735 | +--rw nodeset-value? 736 +--rw events 737 | +--rw event* [event-name] 738 | +--rw event-name string 739 | +--rw event-type? identityref 740 | +--rw policy-variable* -> /gncd/policy-variables/policy-variable/name 741 | +--rw local-policy-variable* -> /gncd/ecas/eca/policy-variable/name 742 | +--rw (type-choice)? 743 | +--:(server-event) 744 | | +--rw event-stream? string 745 | | +--rw event-module? string 746 | | +--rw event? 747 | +--:(datastore-event) 748 | | +--rw datatore? string 749 | | +--rw data-path? string 750 | | +--rw data? 751 | +--:(timer-event) 752 | | +--rw start-time yang:date-and-time 753 | | +--rw duration centiseconds 754 | | +--rw repeat-option identityref 755 | | +--rw repeat-time-len centiseconds 756 | +--:(diagnostics-event) 757 +--rw conditions 758 | +--rw condition* [name] 759 | +--rw name string 760 | +--rw (expression-choice)? 761 | +--:(xpath) 762 | +--rw condition-xpath? string 763 +--rw actions 764 | +--rw time-schedule! 765 | | +--rw period? centiseconds 766 | +--rw action* [name] 767 | +--rw name string 768 | +--rw action-element* [name] 769 | | +--rw name string 770 | | +--rw action-type? identityref 771 | | +--rw (action-operation)? 772 | | | +--:(action) 773 | | | | +--rw next-period boolean 774 | | | | +--rw action-name? 775 | | | | -> /gnca/actions/action/name 776 | | | +--:(function-call) 777 | | | | +--rw function-call 778 | | | | +--rw func-name leafref 779 | | | | +--rw policy-source leafref 780 | | | | +--rw policy-result leafref 781 | | | +--:(rpc-operation) 782 | | | | +--rw rpc-operation 783 | | | | +--rw rpc-name? string 784 | | | | +--rw nc-action-xpath? string 785 +--rw ecas 786 | +--rw eca* [name] 787 | +--rw name string 788 | +--rw username string 789 | +--rw event-name string 790 | +--rw policy-variable* [name] 791 | | +--rw name leafref 792 | | +--rw is-static? boolean 793 | +--rw condition-action* [name] 794 | | +--rw name string 795 | | +--rw condition* -> /gncd/conditions/condition/name 796 | | +--rw action? -> /gncd/actions/action/name 797 | +---x start 798 | +---x stop 799 | +---x next-action 800 +--rw eca-func-libs 801 +--rw eca-function* [func-name] 802 | +--rw func-name string 803 +--rw eca-rpc* [rpc-name] 804 | +--rw rpc-name string 805 +--rw eca-name -> /gncd/ecas/eca/name 807 notifications: 808 +---n eca-exception 809 | +--ro reason? identityref 810 +---n custom-notification 811 +--ro eventTime yang:date-and-time 812 +--ro event-type? identityref 813 +--ro (type-choice)? 814 | +--:(server-event) 815 | | +--ro event-stream? string 816 | | +--ro event-module? string 817 | | +--ro policy-result leafref 818 | +--:(datastore-event) 819 | | +--ro datatore? string 820 | | +--ro data-path? string 821 | | +--ro policy-result leafref 823 5. ECA YANG Module 825 file "ietf-eca@2019-10-28.yang" 827 module ietf-eca { 828 yang-version 1.1; 829 namespace "urn:ietf:params:xml:ns:yang:ietf-eca"; 830 prefix gnca; 832 import ietf-yang-types { 833 prefix yang; 834 } 835 import ietf-netconf-acm { 836 prefix nacm; 837 reference 838 "RFC8341: Network Configuration Access Control Model"; 839 } 840 organization 841 "IETF Network Configuration (NETCONF) Working Group"; 842 contact 843 "WG Web: 844 WG List: 845 Editor: Qin Wu 846 847 Editor: Igor Bryskin 848 849 Editor: Henk Birkholz 850 851 Editor: Xufeng Liu 852 853 Editor: Benoit Claise 854 855 Editor: Andy Bierman 856 857 Editor: Alexander Clemm 858 "; 860 description 861 "Event Condition Action (ECA) model."; 863 revision 2018-06-22 { 864 description 865 "Initial revision"; 866 reference 867 "RFC XXXX"; 868 } 870 identity argument-type { 871 description 872 "Possible values are: 873 constant, variable, or datastore state."; 874 } 876 identity comparison-type { 877 description 878 "Possible values are: 879 equal, not-equal, greater, greater-equal, less, less-equal."; 880 } 882 identity logical-operation-type { 883 description 884 "Possible values are: 885 not, or, and."; 886 } 888 identity function-type { 889 description 890 "Possible values are: 891 plus, minus, mult, divide, sustained-event."; 892 } 894 identity sustained-event { 895 description 896 "Identity for standard sustained-event function call, 897 the input variables for sustained-event include string 898 expr, number interval, number count. Keep testing 899 expression 'expr'once per interval until false result 900 reached.Return true if condition tested true 901 for count intervals; Returns false otherwise."; 902 } 904 identity plus { 905 description 906 "Identity for standard plus function call, the input 907 variables for plus function call include src policy argument 908 and dst policy arugment."; 909 } 911 identity minus { 912 description 913 "Identity for standard minus function call, the input 914 variables for plus function call include src policy argument 915 and dst policy arugment."; 916 } 918 identity multiply { 919 description 920 "Identity for standard multiply function call, the input 921 variables for multiply function call include src policy argument 922 and dst policy arugment."; 923 } 925 identity divide { 926 description 927 "Identity for standard divide function call, the input 928 variables for multiply function call include src policy argument 929 and dst policy arugment."; 930 } 932 identity action-type { 933 description 934 "Possible values are: 935 action, function-call, rpc."; 936 } 938 identity event-type { 939 description 940 "Base identity for Event Type."; 941 } 943 identity server-event { 944 base event-type; 945 description 946 "Identity for server event."; 947 } 949 identity datastore-event { 950 base event-type; 951 description 952 "Identity for datastore event."; 953 } 955 identity timer-event { 956 base event-type; 957 description 958 "Identity for timer event."; 959 } 961 identity diagnostics-event { 962 base event-type; 963 description 964 "Identity for diagnostics event."; 965 } 967 identity eca-exception-reason { 968 description 969 "Base of all values for the 'reason' leaf in the 970 eca-exception notification."; 971 } 973 identity varbind-unknown { 974 base eca-exception-reason; 975 description 976 "The requested policy variable binding is not defined. 977 The variable binding cannot be resolved in the XPath 978 evaluation."; 979 } 981 typedef centiseconds { 982 type uint32; 983 description 984 "A period of time, measured in units of 0.01 seconds."; 985 } 987 typedef oper-status { 988 type enumeration { 989 enum completed { 990 description 991 "Completed with no error."; 992 } 993 enum running { 994 description 995 "Currently with no error."; 996 } 997 enum sleeping { 998 description 999 "Sleeping because of time schedule."; 1000 } 1001 enum stoped { 1002 description 1003 "Stopped by the operator."; 1005 } 1006 enum failed { 1007 description 1008 "Failed with errors."; 1009 } 1010 enum error-handling { 1011 description 1012 "Asking the operator to handle an error."; 1013 } 1014 } 1015 description 1016 "The operational status of an ECA execution."; 1017 } 1019 grouping scalar-value { 1020 leaf scalar-value { 1021 type string; 1022 description 1023 "Represents an XPath simple value that has an 1024 XPath type of Boolean, String, or Number. 1025 This value will be converted to an XPath type, 1026 as needed. 1028 A YANG value is encoded as a string using the same 1029 rules as the 'default' value for the data type. 1031 An eca-exception notification is generated if a scalar 1032 XPath value is used in a path expression, where a 1033 node-set is expected. Normally XPath will treat this result 1034 as an empty node-set, but this is an ECA programming error."; 1035 } 1036 } 1038 grouping nodeset-value { 1039 anydata nodeset-value { 1040 description 1041 "Represents an XPath node set. A 'node-set' anydata node 1042 with no child data nodes represents an empty node-set. 1043 Each child node in within this anydata structure 1044 represents a subtree that is present in the XPath 1045 node-set. 1047 An XPath node-set is not required to contain a top-level 1048 YANG data node. It is not required to contain an entire 1049 complete subtree. 1051 It is am implementation-specific manner how a 1052 representation of YANG 'anydata' nodes are mapped 1053 to specific YANG module schema definitions."; 1054 } 1055 } 1056 grouping scalar-constant { 1057 leaf scalar-constant { 1058 type string; 1059 description 1060 "Represents an XPath simple value that has an 1061 XPath type of Boolean, String, or Number. 1062 This value will be converted to an XPath type, 1063 as needed. 1065 A YANG value is encoded as a string using the same 1066 rules as the 'default' value for the data type. 1068 An eca-exception notification is generated if a scalar 1069 XPath value is used in a path expression, where a 1070 node-set is expected. Normally XPath will treat this result 1071 as an empty node-set, but this is an ECA programming error."; 1072 } 1073 } 1075 grouping nodeset-constant { 1076 anydata nodeset-constant { 1077 description 1078 "Represents an XPath node set. A 'node-set' anydata node 1079 with no child data nodes represents an empty node-set. 1080 Each child node in within this anydata structure 1081 represents a subtree that is present in the XPath 1082 node-set. 1084 An XPath node-set is not required to contain a top-level 1085 YANG data node. It is not required to contain an entire 1086 complete subtree. 1088 It is am implementation-specific manner how a 1089 representation of YANG 'anydata' nodes are mapped 1090 to specific YANG module schema definitions."; 1091 } 1092 } 1093 grouping pv-source { 1094 choice pv-source { 1095 mandatory true; 1096 description 1097 "A PV source represents an XPath result, which contains 1098 one of four data types: Boolean, Number, String, 1099 and Node Set. XPath defines mechanisms to covert 1100 values between these four types. 1102 The 'xpath-expr' leaf is used to assign the PV source 1103 to the result of an arbitrary XPath expression. 1104 The result of this expression evaluation is used 1105 internally as needed. The result may be any one of 1106 the XPath data types. 1108 The 'scalar-constant' leaf is used to represent a Boolean, 1109 String, or Number XPath constant value. 1111 The 'nodeset-constant' anydata structure is used to 1112 represent a constant XPath node-set."; 1114 leaf xpath-expr { 1115 type yang:xpath1.0; 1116 description 1117 "Contains an XPath expression that must be evaluated 1118 to produce an XPath value. [section X.X] describes 1119 the XPath execution environment used to process this 1120 object."; 1121 } 1123 case scalar-constant { 1124 uses scalar-constant; 1125 } 1126 case nodeset-constant { 1127 uses nodeset-constant; 1128 } 1129 } 1130 } 1132 grouping pv-result { 1133 choice pv-result { 1134 mandatory true; 1135 description 1136 "Represents the value of the result of an 1137 Policy Variable evaluation. 1139 The 'scalar-value' leaf is used to represent a Boolean, 1140 String, or Number XPath result value. 1142 The 'nodeset-value' anydata structure is used to represent 1143 an XPath node-set result."; 1145 case scalar-value { 1146 uses scalar-value; 1147 } 1148 case nodeset-value { 1149 uses nodeset-value; 1151 } 1152 } 1153 } 1155 grouping policy-variable-attributes { 1156 description 1157 "Defining the policy variable attributes, including name, type 1158 and value. These attributes are used as part of the Policy 1159 Variable (PV) definition."; 1160 leaf name { 1161 type string; 1162 description 1163 "A string to uniquely identify a Policy Variable (PV), either 1164 globally for a global PV, or within the soope of ECA for a 1165 local PV."; 1166 } 1167 choice xpath-value-choice { 1168 description 1169 "The type of a policy variable may be either a common 1170 primative type like boolean or a type from existing 1171 schema node referenced by an XPath string."; 1172 /*case scalar { 1173 uses scalar-value; 1174 } 1175 case nodeset { 1176 uses nodeset-value; 1177 }*/ 1178 case policy-source { 1179 uses pv-source; 1180 } 1181 case policy-result { 1182 uses pv-result; 1183 } 1184 } 1185 } 1187 grouping action-element-attributes { 1188 description 1189 "Grouping of action element attributes."; 1190 leaf action-type { 1191 type identityref { 1192 base action-type; 1193 } 1194 description 1195 "Identifies the action type."; 1196 } 1197 choice action-operation { 1198 description 1199 "The operation choices that an ECA Action can take."; 1200 case action { 1201 leaf next-period { 1202 type boolean; 1203 description 1204 "invoke the same eca recursively if the next period 1205 is set to true."; 1206 } 1207 leaf action-name { 1208 type leafref { 1209 path "/gncd/actions/action/name"; 1210 } 1211 description 1212 "The operation is to execute a configured ECA Action."; 1213 } 1214 } // action 1215 case function-call { 1216 container function-call { 1217 description 1218 "The operation is to call a function, which is of one of 1219 a few basic predefined types, such as plus, minus, 1220 multiply, devide, or remainder."; 1221 leaf function-name { 1222 type string; 1223 description 1224 "The name of function call to be called"; 1225 } 1226 leaf policy-source { 1227 type leafref { 1228 path "/gncd/policy-variables/policy-variable/name"; 1229 } 1230 description 1231 "The policy source."; 1232 } 1233 leaf policy-result { 1234 type leafref { 1235 path "/gncd/policy-variables/policy-variable/name"; 1236 } 1237 description 1238 "The policy result."; 1239 } 1240 } 1241 } // function-call 1242 case rpc-operation { 1243 container rpc-operation { 1244 description 1245 "The operation is to call an RPC, which is defined by 1246 a YANG module supported by the server."; 1248 leaf rpc-name { 1249 type string; 1250 description 1251 "The name of the YANG RPC or YANG action to be 1252 called."; 1253 } 1254 leaf nc-action-xpath { 1255 type string; 1256 description 1257 "The location where the YANG action is defined. 1258 This is used if and only if a YANG action is called. 1259 This leaf is not set when a YANG RPC is called."; 1260 } 1261 } 1262 } // rpc-operation 1264 /*case notify-operation { 1265 container notify-operation { 1266 description 1267 "The operation is to send a YANG notification."; 1268 leaf name { 1269 type string; 1270 description 1271 "Name of the subscribed YANG notification."; 1272 } 1273 list policy-variable { 1274 key "name"; 1275 description 1276 "A list of policy arguments carried in the notification 1277 message."; 1278 leaf name { 1279 type string; 1280 description 1281 "A string name used as the list key to form a list 1282 of policy arguments."; 1283 } 1284 } 1285 } 1286 }*/ 1287 } 1288 } 1290 grouping time-schedule-container { 1291 description 1292 "Grouping to define a container of a time schedule."; 1293 container time-schedule { 1294 presence "Presence indicates that the timer is enabled."; 1295 description 1296 "Specifying the time schedule to execute an ECA Action, or 1297 trigger an event."; 1298 leaf period { 1299 type centiseconds; 1300 description 1301 "Duration of time that should occur between periodic 1302 push updates, in units of 0.01 seconds."; 1303 } 1304 } 1305 } 1307 container gncd { 1308 nacm:default-deny-all; 1309 description 1310 "Top level container for Generalized Network Control Automation 1311 (gncd)."; 1312 container policy-variables { 1313 description 1314 "Container of global Policy Variables (PVs)."; 1315 list policy-variable { 1316 key "name"; 1317 description 1318 "A list of global Policy Variables (PVs), with a string 1319 name as the entry key."; 1320 uses policy-variable-attributes; 1321 } 1322 } 1323 container events { 1324 description 1325 "Container of ECA events."; 1326 list event { 1327 key "event-name"; 1328 description 1329 "A list of events used as the triggers of ECAs."; 1330 leaf event-name { 1331 type string; 1332 description 1333 "The name of the event."; 1334 } 1335 leaf event-type { 1336 type identityref { 1337 base event-type; 1338 } 1339 description 1340 "The type of the event."; 1341 } 1342 leaf-list policy-variable { 1343 type leafref { 1344 path "/gncd/policy-variables/" 1345 + "policy-variable/name"; 1346 } 1347 description 1348 "global policy variables, which 1349 are shared by all ECA scripts."; 1350 } 1351 leaf-list local-policy-variable { 1352 type leafref { 1353 path "/gncd/ecas/eca/policy-variable/name"; 1354 } 1355 description 1356 "local policy variables, which 1357 are kept within an ECA instance, and appears/ 1358 disappears with start/stop of the ECA execution."; 1359 } 1361 choice type-choice { 1362 description 1363 "The type of an event, including server event and datastore event."; 1364 case server-event { 1365 leaf event-stream { 1366 type string; 1367 description 1368 "The name of a subscribed stream ."; 1369 } 1370 leaf event-module { 1371 type string; 1372 description 1373 "The name of YANG data module associated with the subscribed 1374 stream."; 1375 } 1376 anydata event { 1377 description 1378 "This anydata value MUST Contain the absolute XPath 1379 expression identifying the element path to the node that is 1380 associated with subscribed stream."; 1381 } 1382 } 1383 case datastore-event { 1384 leaf datatore { 1385 type string; 1386 description 1387 "The name of a datatore from which applications 1388 subscribe to updates."; 1389 } 1390 leaf data-path { 1391 type string; 1392 description 1393 "The absolute XPath expression identifying the 1394 element path to the node that is associated with 1395 subscribed stream.."; 1396 } 1397 anydata data { 1398 description 1399 "This anydata value MUST Contain the node that is 1400 associated with the data path."; 1401 } 1402 } 1403 case timer-event { 1404 leaf start-time { 1405 type yang:date-and-time; 1406 description 1407 "This object specifies the scheduled start date/time to trigger 1408 timer event."; 1409 } 1410 leaf duration { 1411 type centiseconds; 1412 description 1413 "This object specifies duration of the timer event execution."; 1414 } 1415 leaf repeat-option { 1416 type centiseconds; 1417 description 1418 "This object indicate repeat option, e.g., repeat everyday, everyweek, 1419 everymoth,everyyear or every specfiied time length."; 1420 } 1421 leaf repeat-len { 1422 type centiseconds; 1423 description 1424 "This object specifies the time length in 0.01 seconds after which 1425 the timer event is executed for the duration."; 1426 } 1427 } 1428 case diagnostics-event; 1429 } 1430 } 1431 } 1432 container conditions { 1433 description 1434 "Container of ECA Conditions."; 1435 list condition { 1436 key "name"; 1437 description 1438 "A list of ECA Conditions."; 1439 leaf name { 1440 type string; 1441 description 1442 "A string name to uniquely identify an ECA Condition 1443 globally."; 1444 } 1445 choice expression-choice { 1446 description 1447 "The choices of expression format to specify a condition, 1448 which can be either a XPath string."; 1449 case xpath { 1450 leaf condition-xpath { 1451 type string; 1452 description 1453 "A XPath string, representing a logical expression, 1454 which can contain comparisons of datastore values 1455 and logical operations in the XPath format."; 1456 } 1457 } 1458 } 1459 } 1460 } 1461 container actions { 1462 description 1463 "Container of ECA Actions."; 1464 uses time-schedule-container { 1465 description 1466 "Specifying the time schedule to execute this ECA 1467 Action. 1468 If not specified, the ECA Action is executed one time immediately 1469 when it is called."; 1470 } 1471 list action { 1472 key "name"; 1473 description 1474 "A list of ECA Actions."; 1475 leaf name { 1476 type string; 1477 description 1478 "A string name to uniquely identify an ECA Action 1479 globally."; 1480 } 1481 list action-element { 1482 key "name"; 1483 description 1484 "A list of elements contained in an ECA Action. "; 1485 leaf name { 1486 type string; 1487 description 1488 "A string name to uniquely identify the action element 1489 within the scope of an ECA action."; 1490 } 1491 uses action-element-attributes; 1492 } 1493 } 1494 } 1495 container ecas { 1496 description 1497 "Container of ECAs."; 1498 list eca { 1499 key "name"; 1500 description 1501 "A list of ECAs"; 1502 leaf name { 1503 type string; 1504 description 1505 "A string name to uniquely identify an ECA globally."; 1506 } 1507 leaf username { 1508 type string; 1509 mandatory true; 1510 description 1511 "Name of the user for the session."; 1512 } 1513 leaf event-name { 1514 type string; 1515 mandatory true; 1516 description 1517 "The name of an event that triggers the execution of 1518 this ECA."; 1519 } 1520 list policy-variable { 1521 key "name"; 1522 description 1523 "A list of ECA local Policy Variables (PVs), with a 1524 string name as the entry key."; 1525 leaf name { 1526 type leafref { 1527 path "/gncd/policy-variables/policy-variable/name"; 1528 } 1529 } 1530 leaf is-static { 1531 type boolean; 1532 description 1533 "'true' if the PV is static; 'false' if the PV is 1534 dynamic. 1535 A dynamic PV appears/disappears with the start/stop 1536 of the ECA execution; a static PV exists as long as 1537 the ECA is configured."; 1538 } 1539 } 1540 list condition-action { 1541 key "name"; 1542 ordered-by user; 1543 description 1544 "A list of Condition-Actions, which are configured 1545 conditions each with associated actions to be executed 1546 if the condition is evaluated to TRUE. The server can do 1547 multiple action when the condition is true. If the next-period 1548 is set to true, condition-action will be executed recursively. 1549 It is also possbile to require multiple conditions to be true 1550 in order to do one action."; 1551 leaf name { 1552 type string; 1553 description 1554 "A string name uniquely identify a Condition-Action 1555 within this ECA."; 1556 } 1557 leaf-list condition { 1558 type leafref { 1559 path "/gncd/conditions/condition/name"; 1560 } 1561 description 1562 "The reference to a configured condition."; 1563 } 1564 leaf action { 1565 type leafref { 1566 path "/gncd/actions/action/name"; 1567 } 1568 description 1569 "The reference to a configured action."; 1570 } 1571 } 1572 action start { 1573 description 1574 "Start to execute this ECA. The start action is invoked 1575 by the local client when the event type is set to diagnostic 1576 event."; 1577 } 1578 action stop { 1579 description 1580 "Stop the execution of this ECA. The stop action is invoked 1581 by the local client when the event type is set to diagnostic 1582 event."; 1583 } 1584 action next-action { 1585 description 1586 "Resume the execution of this ECA to complete the next 1587 action. The next action is invoked by the local client 1588 when the event type is set to diagnostic event."; 1589 } 1590 } 1591 } 1592 container eca-func-libs { 1593 description 1594 "Container of ECA Function Libraries."; 1595 list eca-function { 1596 key func-name; 1597 description 1598 "A list of ECA standard function."; 1599 leaf func-name { 1600 type string; 1601 description 1602 "A string name to uniquely identify an ECA standard function."; 1603 } 1604 } 1605 list rpc-function { 1606 key rpc-name; 1607 description 1608 "A list of ECA standard function."; 1609 leaf rpc-name { 1610 type string; 1611 description 1612 "A string name to uniquely identify an ECA standard RPC."; 1613 } 1614 } 1615 leaf eca-name { 1616 type leafref { 1617 path "/gncd/ecas/eca/name"; 1618 } 1619 description 1620 "The reference to a configured ECA."; 1621 } 1622 } // eca-scripts 1623 } 1625 notification eca-exception { 1626 description 1627 "This notification is sent when some error occurs 1628 while the server is processing ECA logic."; 1629 leaf reason { 1630 type identityref { 1631 base eca-exception-reason; 1632 } 1633 } 1634 } 1635 notification custom-notification { 1636 description 1637 "This notification is sent when some error occurs 1638 while the server is processing ECA logic."; 1639 leaf eventTime { 1640 type yang:date-and-time; 1641 description 1642 "The event occurrence time"; 1643 } 1644 leaf event-type { 1645 type identityref { 1646 base event-type; 1647 } 1648 description 1649 "The type of the event."; 1650 } 1651 choice type-choice { 1652 description 1653 "The type of an event, including server event and datastore event."; 1654 case server-event { 1655 leaf event-stream { 1656 type string; 1657 description 1658 "The name of a subscribed stream ."; 1659 } 1660 leaf event-module { 1661 type string; 1662 description 1663 "The name of YANG data module associated with the subscribed 1664 stream."; 1665 } 1666 anydata event { 1667 description 1668 "This anydata value MUST Contain the absolute XPath 1669 expression identifying the element path to the node that is 1670 associated with subscribed stream."; 1671 } 1672 } 1673 case datastore-event { 1674 leaf datatore { 1675 type string; 1676 description 1677 "The name of a datatore from which applications 1678 subscribe to updates."; 1679 } 1680 leaf data-path { 1681 type string; 1682 description 1683 "The absolute XPath expression identifying the 1684 element path to the node that is associated with 1685 subscribed stream.."; 1686 } 1687 anydata data { 1688 description 1689 "This anydata value MUST Contain the node that is 1690 associated with the data path."; 1691 } 1692 } 1693 } 1694 } 1695 } 1697 1699 6. Security Considerations 1701 The YANG modules defined in this document MAY be accessed via the 1702 RESTCONF protocol [RFC8040] or NETCONF protocol ([RFC6241]). The 1703 lowest RESTCONF or NETCONF layer requires that the transport-layer 1704 protocol provides both data integrity and confidentiality, see 1705 Section 2 in [RFC8040] and [RFC6241]. The lowest NETCONF layer is 1706 the secure transport layer, and the mandatory-to-implement secure 1707 transport is Secure Shell (SSH)[RFC6242] . The lowest RESTCONF layer 1708 is HTTPS, and the mandatory-to-implement secure transport is TLS 1709 [RFC5246]. 1711 The NETCONF access control model [RFC6536] provides the means to 1712 restrict access for particular NETCONF or RESTCONF users to a 1713 preconfigured subset of all available NETCONF or RESTCONF protocol 1714 operations and content. 1716 There are a number of data nodes defined in this YANG module that are 1717 writable/creatable/deletable (i.e., config true, which is the 1718 default). These data nodes may be considered sensitive or vulnerable 1719 in some network environments. Write operations (e.g., edit-config) 1720 to these data nodes without proper protection can have a negative 1721 effect on network operations. These are the subtrees and data nodes 1722 and their sensitivity/vulnerability: 1724 o /gnca:gncd/gnca:policy-variables/gnca:policy-variable/gnca:name 1726 o /gnca:gncd/gnca:events/gnca:event/gnca:name 1727 o /gnca:gncd/gnca:conditions/gnca:condition/gnca:name 1729 o /gnca:gncd/gnca:actions/gnca:action/gnca:name 1731 o /gnca:gncd/gnca:ecas/gnca:eca/gnca:name 1733 o /gnca:gncd/gnca:ecas/gnca:eca/gnca:username 1735 o /gnca:gncd/gnca:eca-func-libs/gnca:eca-function/gnca:func-name 1737 7. IANA Considerations 1739 This document registers two URIs in the IETF XML registry [RFC3688]. 1740 Following the format in [RFC3688], the following registrations are 1741 requested to be made: 1743 --------------------------------------------------------------------- 1744 URI: urn:ietf:params:xml:ns:yang:ietf-eca 1745 Registrant Contact: The IESG. 1746 XML: N/A, the requested URI is an XML namespace. 1747 --------------------------------------------------------------------- 1749 This document registers one YANG module in the YANG Module Names 1750 registry [RFC6020]. 1752 --------------------------------------------------------------------- 1753 Name: ietf-eca 1754 Namespace: urn:ietf:params:xml:ns:yang:ietf-eca 1755 Prefix: gnca 1756 Reference: RFC xxxx 1757 --------------------------------------------------------------------- 1759 8. Acknowledges 1761 Igor Bryskin, Xufeng Liu, Alexander Clemm, Henk Birkholz, Tianran 1762 Zhou contributed to an earlier version of [GNCA]. We would like to 1763 thank the authors of that document on event response behaviors 1764 delegation for material that assisted in thinking that helped improve 1765 this document. We also would like to thanks Jonathan 1766 Hansford,Michale Wang, Xiaopeng Qin Yu Yang, Haoyu Song, Tianran 1767 Zhou,Aihua Guo,Nicola Sambo,Giuseppe Fioccola for valuable review on 1768 this document. 1770 9. Contributors 1771 Andy Bierman 1772 YumaWorks 1774 Email: andy@yumaworks.com 1776 Alex Clemm 1777 Futurewei 1778 Email: ludwig@clemm.org 1780 Qiufang Ma 1781 Huawei 1782 Email: maqiufang1@huawei.com 1784 Chongfeng Xie 1785 China Telecom 1786 Email: xiechf@ctbri.com.cn 1788 Diego R. Lopez 1789 Telefonica 1790 Email:diego.r.lopez@telefonica.com 1792 10. References 1794 10.1. Normative References 1796 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1797 Requirement Levels", March 1997. 1799 [RFC3460] Moore, B., Ed., "Policy Core Information Model (PCIM) 1800 Extensions", RFC 3460, DOI 10.17487/RFC3460, January 2003, 1801 . 1803 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1804 DOI 10.17487/RFC3688, January 2004, 1805 . 1807 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1808 the Network Configuration Protocol (NETCONF)", RFC 6020, 1809 DOI 10.17487/RFC6020, October 2010, 1810 . 1812 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1813 and A. Bierman, Ed., "Network Configuration Protocol 1814 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1815 . 1817 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1818 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1819 . 1821 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1822 Protocol (NETCONF) Access Control Model", RFC 6536, 1823 DOI 10.17487/RFC6536, March 2012, 1824 . 1826 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1827 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1828 . 1830 10.2. Informative References 1832 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1833 (TLS) Protocol Version 1.2", RFC 5246, 1834 DOI 10.17487/RFC5246, August 2008, 1835 . 1837 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1838 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1839 . 1841 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1842 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1843 . 1845 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1846 and R. Wilton, "Network Management Datastore Architecture 1847 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1848 . 1850 Appendix A. ECA Condition Expression Examples 1852 Here are two examples of Condition Expression: 1854 (a) a condition that only includes data store states and constants, 1855 for example: 1857 TE metric of Link L in Topology T greater than 100, 1858 it can be expressed as follows: 1860 "/nw:networks/nw:network[network-id='T']/nt:link[link-id='L']/tet:te\ 1861 /tet:te-link-attributes/tet:te-delay-metric > 100" 1863 (b) a condition that also includes a Policy Variable, for example: 1865 Allocated bandwidth of Link L in Topology T greater than 75% of 1866 what is stored in Policy Variable B, it can be expressed as follows: 1868 "/nw:networks/nw:network[network-id='T']/nt:link[link-id='L']/tet:te\ 1869 /tet:te-link-attributes/tet:max-resv-link-bandwidth\ 1870 > (ietf-eca:policy-variables/policy-variable[name='B']/value) * 0.75" 1872 Appendix B. Usage Example of Smart Filter using Server Event Trigger 1874 +---------------------------+ 1875 | Management System | 1876 +---------------------------+ 1877 | 1878 ECA | 1879 Model | 1880 | 1881 V 1882 +----------------------^-----+ 1883 | Managed Device | | 1884 | | | 1885 | //--\\ Condition--+ | 1886 | | Event| / \ | 1887 | | |----->|Actions | 1888 | \\--// \ / | 1889 | ---- | 1890 +----------------------------+ 1892 The management system designs a new ECA policy based on monitored 1893 objects in ietf-interfaces module that support threshold checking and 1894 pushes down the ECA policy to control interface behavior in the 1895 managed device that supports NETCONF/RESTCONF protocol operation, 1896 i.e.,scan all interfaces for a certain type every 5 seconds and check 1897 the counters or status, return an array of interface entries (XPath 1898 node-set) that match the search and suppress reporting of duplicated 1899 events if all conditions are evaluated into true. The XML example 1900 snippet is shown as below: 1902 1903 1904 1905 event-repeat-count 1906 0 1907 1908 1909 interface-statistics-event 1910 if:interfaces/if:interface[if:type=if:gigabitEthernet, 1911 if:oper-status=down] 1912 1914 1915 1916 1917 interface-self-monitoring 1918 server-event 1919 NETCONF 1920 ietf-interfaces 1921 if:interfaces/if:interface[if:type=if:gigabitEthernet] 1922 1923 1924 1925 1926 if-monitoring-condition1 1927 event[if:oper-status=down] 1928 1929 1930 if-monitoring-condition2 1931 event[if:oper-status!=down] 1932 1933 1934 if-monitoring-condition3 1935 event-repeat-count >1 1936 1937 1938 if-monitoring-condition4 1939 event-repeat-count <=1 1940 1941 1942 1943 1944 5 1945 1946 1947 if-matched-statistics1 1948 1949 event-filter-action 1950 filtered-event 1951 interface-statistics-event 1952 event 1953 1954 1955 increment-action 1956 increment-function 1957 event-repeat-count 1958 event-repeat-count 1959 1960 1961 suppress-action 1962 1963 suppress-notification 1964 1965 1966 1967 continue-check-action 1968 match-function 1969 interface-statistics-event 1970 event-repeat-count 1971 next-period 1972 1973 1974 1975 if-matched-statistics2 1976 1977 event-filter-action 1978 filtered-event 1979 interface-statistics-event 1980 event 1981 1982 1983 increment-action 1984 increment-function 1985 event-repeat-count 1986 event-repeat-count 1987 1988 1989 continue-check-action 1990 match-function 1991 interface-statistics-event 1992 event-repeat-count 1993 next-period 1994 1995 1996 1997 if-matched-statistics3 1998 1999 decrement-action 2000 decrement-function 2001 event-repeat-count 2002 event-repeat-count 2003 2004 2005 exit-action 2006 exit-func 2007 2008 2009 2010 2011 2012 interface-eca-handling 2013 Bob 2014 interface-self-monitoring 2015 2016 smart-filter1 2017 if-monitoring-condition1 2018 if-monitoring-condition3 2019 2020 if-matched-statistics1 2021 2022 event-filter-action 2023 2024 2025 increment-action 2026 2027 2028 suppress-action 2029 2030 2031 continue-check-action 2032 2033 2034 2035 2036 smart-filter2 2037 if-monitoring-condition1 2038 if-monitoring-condition4 2039 2040 if-matched-statistics2 2041 2042 event-filter-action 2043 2044 2045 increment-action 2046 2047 2048 continue-check-action 2049 2050 2051 2052 2053 smart-filter3 2054 if-monitoring-condition2 2055 2056 if-matched-statistics3 2057 2058 decrement-action 2059 2060 2061 exit-action 2062 2063 2064 2065 2066 2067 2068 2069 filtered-event 2070 2071 2072 increment-function 2073 2074 2075 decrement-function 2076 2077 2078 exit-function 2079 2080 2081 match-function 2082 2083 2084 event-duplication-suppress 2085 2086 interface-eca-handling 2087 2088 2090 // This custom-notification is only sent when there is no duplicated event to occur. 2091 2092 2016-11-21T13:51:00Z 2093 server-event 2094 NETCONF 2095 ietf-interfaces 2096 if:interfaces/if:interface[if:type=if:gigabitEthernet] 2097 2100 2101 GE0 2102 ianaift:gigabitEthernet 2103 false 2104 2105 ..... 2107 2108 GE1 2109 ianaift:gigabitEthernet 2110 true 2111 ... 2112 2113 ..... 2114 2115 GE2 2116 ianaift:gigabitEthernet 2117 ... 2118 true 2119 2120 2121 2123 In this example, the event name is set to 'interface-self- 2124 monitoring', the event type is set to 'server-event', the function 2125 name of ECA function libraries is set to 'sustained-event', 2126 'increment-function','decrement-function','match-function','exit- 2127 function' the rpc name of ECA function libraries is set to 'event- 2128 duplication-suppress',the name of 'condition-action' is corresponding 2129 to standard function calls described above. The pseudo code of ECA 2130 logic can be described as follows: 2132 count = 0; 2133 while { next-period = true} 2134 if(interface is down ) { 2135 event= filtered event;//eca exception will be notified to the local client if invoking filtered event fails 2136 count++; 2137 if(count > 1){ 2138 suppress event;//eca exception will be notified to the local client if invoking filtered event fails 2139 next-period = true; 2140 exit; 2141 }else if( count <= 1) { 2142 next-period = true; 2143 call custom-notification; 2144 continue; 2145 } 2146 }else if ( interface is not down){ 2147 next-period = false; 2148 count=0; 2149 exit; 2150 } 2151 } 2152 Appendix C. Usage Example of Router Log Dump using Timer Event Trigger 2154 Use a watchdog to dump the router log every 180 seconds to a flash. 2155 The XML example snippet is shown as below: 2157 2158 2159 2160 syslog-remote-info 2161 syslog:syslog/syslog:actions/syslog:remote 2162 2163 2164 2165 2166 log-dump-monitoring 2167 2020-10-21T13:51:00Z 2168 12000 2169 everyminutes 2170 3 2171 2172 2173 2174 2175 log-dump-statistics 2176 2177 log-dump-action 2178 syslog-remote-output 2179 syslog-remote-info 2180 2181 2182 2183 2184 2185 log-dump-handling 2186 Bob 2187 log-dump-monitoring 2188 2189 cron-log-monitoring 2190 2191 log-dump-statistics 2192 2193 syslog-remote-output 2194 2195 2196 2197 2198 2199 2200 2201 syslog-remote-output 2202 2203 log-dump-handling 2204 2205 2207 Appendix D. Usage Example of High CPU Utilization Troubleshooting 2209 It is usually found that at times the CPU utilization spikes up for a 2210 very short period of time and at indeterminate times. ECA to be 2211 executed in the network device can be used to detect CPU 2212 utilization,e.g.,It is triggered when the CPU utilization goes above 2213 60% and also output stack, cpu, fan statistics information to a 2214 flash. The XML example snippet is shown as below: 2216 2217 2218 2219 stack-info 2220 hw:hardware/hw:components/hw:component[hw:class=stack] 2221 2222 2223 fan-info 2224 hw:hardware/hw:components/hw:component[hw:class=fan] 2225 2226 2227 sensor-info 2228 hw:hardware/hw:components/hw:component[hw:class=sensor] 2229 2230 2231 2232 2233 cpu-util-monitoring 2234 server-event 2235 NETCONF 2236 ietf-hardware 2237 hw:hardware/hw:components/hw:component[hw:class=cpu] 2238 2239 2240 2241 2242 cpu-utilization-condition 2243 event/sensor-data[value>60,value-type=percentile] 2244 2245 2246 2247 2248 cpu-info-filter 2249 2250 cpu-info-dump-action1 2251 filtered-event 2252 event/sensor-data[value>60,value-type=percentile] 2253 stack-info 2254 2255 2256 cpu-info-dump-action2 2257 filtered-event 2258 event/sensor-data[value>60,value-type=percentile] 2259 fan-info 2260 2261 2262 cpu-info-dump-action3 2263 filtered-event 2264 event/sensor-data[value>60,value-type=percentile] 2265 sensor-info 2266 2267 2268 2269 cpu-info-output 2270 2271 cpu-info-dump-action1 2272 cpu-log-dump 2273 stack-info 2274 2275 2276 cpu-info-dump-action2 2277 cpu-log-dump 2278 fan-info 2279 2280 2281 cpu-info-dump-action3 2282 cpu-log-dump 2283 sensor-info 2284 2285 2286 cpu-info-dump-action4 2287 cpu-log-dump 2288 event/sensor-data[value>60,value-type=percentile] 2289 2290 2291 2292 2293 2294 cpu-util-handling 2295 Bob 2296 cpu-util-monitoring 2297 2298 cpu-log-monitoring 2299 cpu-utilization-condition 2300 2301 cpu-info-filter 2302 2303 cpu-info-dump-action1 2304 2305 2306 cpu-info-dump-action2 2307 2308 2309 cpu-info-dump-action3 2310 2311 2312 2313 2314 cpu-log-printing 2315 2316 cpu-info-output 2317 2318 cpu-info-dump-action1 2319 2320 2321 cpu-info-dump-action2 2322 2323 2324 cpu-info-dump-action3 2325 2326 2327 cpu-info-dump-action4 2328 2329 2330 2331 2332 2333 2334 2335 filtered-event 2336 2337 2338 cpu-log-dump 2339 2340 cpu-util-handling 2341 2342 2343 Appendix E. Changes between Revisions 2345 v09 - v10 2347 o Rewrite ECA Model Self Monitoring Usage Example; 2349 o Add usage Example of High CPU Utilization Troubleshooting; 2351 o Add usage Example of Router Log Dump using Timer Event Trigger; 2353 o Reintroduce iterate action, function call and rpc call action 2354 type. These action types are exchanged between local client and 2355 the server. 2357 o Move notification operation as separate notification since the 2358 notification is exchange between the management system and the 2359 server. 2361 v08 - v09 2363 o Add ECA function libraries list in the ECA model. 2365 o Subtree and data node path fixing in the security section. 2367 v07 - v08 2369 Replace ECA model usage example with self monitoring usage example 2370 in the appendix. 2372 Clean up references. 2374 Add a new section to discuss Mapping Policy Variables to XPath 2375 Variables. 2377 Add a new section to discuss ECA XPath Context. 2379 Add a new section to discuss ECA Evaluation Exceptions. 2381 Rewrite Introduction to highlight elevator pitch. 2383 Replace implicit variable and explicit variable with pv-source 2384 variable and pv-result variable. 2386 Take out function-call, cleanup-condition-action list, execution 2387 list, policy argument container, eca-script list at this moment. 2389 v06 - v07 2390 o Reuse alarm notification event received on an event stream (RFC 2391 8639) in ECA logic; 2393 o Represent ECA condition expression only in the form of Xpath 2394 expression; 2396 o Add ECA condition expression example in the appendix; 2398 o Add ECA model usage example in the appendix; 2400 o Remove the section to discuss the relation with YANG push; 2402 o Remove the dependency to SUPA framework draft; 2404 o Remove smart filter extension example in the Appendix. 2406 o Bind ECA script with condition expression in the model. 2408 v05 - v06 2410 o Decouple ECA model from NETCONF protocol and make it applicable to 2411 other network mangement protocols. 2413 o Move objective section to the last section with additional generic 2414 objectives. 2416 v04 - v05 2418 o Harmonize with draft-bryskin and add additional attributes in the 2419 models (e.g., policy variable, func call enhancement, rpc 2420 execution); 2422 o ECA conditions part harmonization; 2424 o ECA Event, Condition, Action, Policy Variable and Value 2425 definition; 2427 o Change ietf-event.yang into ietf-eca.yang and remove ietf-event- 2428 trigger.yang 2430 v02 - v03 2432 o Usage Example Update: add an usage example to introduce how to 2433 reuse the ietf-event-trigger module to define the subscription- 2434 notification smarter filter. 2436 v01 - v02 2437 o Introduce the group-id which allow group a set of events that can 2438 be executed together 2440 o Change threshold trigger condition into variation trigger 2441 condition to further clarify the difference between boolean 2442 trigger condition and variation trigger condition. 2444 o Module structure optimization. 2446 o Usage Example Update. 2448 v00 - v01 2450 o Separate ietf-event-trigger.yang from Event management modeland 2451 ietf-event.yang and make it reusable in other YANG models. 2453 o Clarify the difference between boolean trigger condition and 2454 threshold trigger condition. 2456 o Change evt-smp-min and evt-smp-max into min-data-object and max- 2457 data-object in the data model. 2459 Authors' Addresses 2461 Qin Wu 2462 Huawei 2463 101 Software Avenue, Yuhua District 2464 Nanjing, Jiangsu 210012 2465 China 2467 Email: bill.wu@huawei.com 2469 Igor Bryskin 2470 Individual 2472 Email: i_bryskin@yahoo.com 2474 Henk Birkholz 2475 Fraunhofer SIT 2477 Email: henk.birkholz@sit.fraunhofer.de 2478 Xufeng Liu 2479 Volta Networks 2481 Email: xufeng.liu.ietf@gmail.com 2483 Benoit Claise 2484 Cisco 2486 Email: bclaise@cisco.com