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